{"id":20671101,"url":"https://github.com/allnulled/basic-filesystem-store","last_synced_at":"2025-09-02T17:23:31.756Z","repository":{"id":57386593,"uuid":"249300552","full_name":"allnulled/basic-filesystem-store","owner":"allnulled","description":"Basic filesystem store interface and implementation.","archived":false,"fork":false,"pushed_at":"2020-03-23T23:29:45.000Z","size":905,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-09T03:01:46.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/basic-filesystem-store","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allnulled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-23T00:36:35.000Z","updated_at":"2020-03-25T13:39:24.000Z","dependencies_parsed_at":"2022-09-05T14:01:20.263Z","dependency_job_id":null,"html_url":"https://github.com/allnulled/basic-filesystem-store","commit_stats":null,"previous_names":["allnulled/universal-filesystem-store"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fbasic-filesystem-store","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fbasic-filesystem-store/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fbasic-filesystem-store/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fbasic-filesystem-store/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allnulled","download_url":"https://codeload.github.com/allnulled/basic-filesystem-store/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242889589,"owners_count":20201989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T20:25:01.678Z","updated_at":"2025-03-10T17:22:13.735Z","avatar_url":"https://github.com/allnulled.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# basic-filesystem-store\n\nBasic filesystem store interface and implementation.\n\n## Install\n\n`$ npm i -s basic-filesystem-store`\n\n## Why?\n\nTo have a universal (promise-based) interface to interact with the filesystem.\n\nTo have a universal safe interface to interact with the filesystem.\n\n## Overview\n\n### Goal\n\nThe API is aimed to support the following features, and serve as a universal interface\nbased in promises to interact with a filesystem-like data exchanger:\n\n  - operate under safe nodes (specially when `\"/\"` and `\"..\"` come into play)\n  - initialize stores\n  - create paths\n  - create streams\n  - create folders and files\n  - ensure folders and files\n  - read folders and files\n  - write folders and files\n  - update folders and files\n  - delete folders and files\n  - rename folders and files\n  - check the existence folders and files\n  - find folders and files by patterns\n\n### Current state\n\nThe current API supports this set of methods:\n\n- **Sync:**\n\n    - `store.getPath(node:String)`\n    - `store.createReadStream(node:String)`\n    - `store.createWriteStream(node:String)`\n\n- **Async:**\n\n    - `store.initialize()`\n    - `store.createFolder(node:String)`\n    - `store.createFolders(nodes:Array\u003cString\u003e)`\n    - `store.deleteFile(node:String)`\n    - `store.deleteFiles(nodes:Array\u003cString\u003e)`\n    - `store.deleteFolder(node:String)`\n    - `store.deleteRecursively(nodes:Array\u003cString\u003e)`\n    - `store.describe(node:String)`\n    - `store.ensureFile(node:String)`\n    - `store.ensureFiles(nodes:Array\u003cString\u003e)`\n    - `store.ensureFolder(node:String)`\n    - `store.ensureFolders(nodes:Array\u003cString\u003e)`\n    - `store.has(node:String)`\n    - `store.hasFile(node:String)`\n    - `store.hasFolder(node:String)`\n    - `store.readFile(node:String, contents:String)`\n    - `store.readFolder(node:String)`\n    - `store.rename(nodeSrc:String, nodeDst:String)`\n    - `store.writeFile(node:String, contents:String, options:String|Object)`\n    - `store.writeFiles(nodes:Object\u003cString, String|Object\u003e)`\n    - `store.findPatterns(patterns:Array\u003cString\u003e)`\n\n## API reference\n\n\n\n----\n\n### `Store.create(...args):Store`\n\n\n\n**Static Method**.\n\n\n**Synchronous**.\n\n\n**Description**:  creates a new store instance. Read about the constructor of the class for more info.\n\n\n\n\n----\n\n### `Store.DEFAULT_OPTIONS:Object`\n\n\n\n**Static Property**.\n\n\n**Description**:  default values of options. Any property here can be overwritten from the constructor's options.\n\n\n**Property**:  `basedir:String` - directory used as store.\n   - defaults to `process.cwd() + \"/_files_\"`\n\n\n\n\n----\n\n### `Store.constructor(options={}:Object):Store`\n\n\n\n**Constructor**.\n\n\n**Description**:  method that generates a new store.\n\n\n**Parameter**: \n\n\n  - `options={}:Object` - options that can overwrite properties and methods of the created store.\n\n\n**Returns**:  `Store` - a new store.\n\n\n\n\n----\n\n### `Store.ORIGINAL_INTERFACE`\n\n\n\n**Static Property**.\n\n\n**Description**:  best class to inherit from if you want to develop your own store.\n\n\n\n\n----\n\n### `Store#initialize():Promise`\n\n\n\n**Method**.\n\n\n**Asynchronous**: \n\n\n\n\n\n**Description**:  ensures the existence of `basedir` folder.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when folder cannot be ensured.\n\n\n\n\n----\n\n### `Store#getPath(node:String):String`\n\n\n\n**Method**.\n\n\n**Synchronous**.\n\n\n**Description**:  returns the full path from an identifier of the node in the store.\n\n\n**Parameter**: \n\n\n  - `node:String` - node identifier, or subpath. Must be inside the folder.\n\n\n**Returns**:  `filepath:String | Error` - full path of the file, or an object error. Must be checked once returned.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n\n\n----\n\n### `Store#describe(node:String):Promise\u003cObject\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  returns a [stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) object.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to describe.\n\n\n**Returns**:  `Promise\u003cstats:Object\u003e` a [stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) object of the node.\n\n\n**Throws**: \n\n\n  - when no node is found.\n\n\n  - when node is out of bounds.\n\n\n\n\n----\n\n### `Store#has(node:String):Promise\u003cBoolean\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  checks if a node exists in the store\n\n\n**Parameter**: \n\n\n  - `node:String` - node suposed to exist.\n\n\n**Returns**:  `Promise\u003chasNode:Boolean\u003e` - result of the check.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n\n\n----\n\n### `Store#hasFile(node:String):Promise\u003cBoolean\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  checks if a node exists in the store as a file\n\n\n**Parameter**: \n\n\n  - `node:String` - node suposed to be a file or not.\n\n\n**Returns**:  `Promise\u003chasFile:Boolean\u003e` - result of the check.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n\n\n----\n\n### `Store#hasFolder(node:String):Promise\u003cBoolean\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  check if a node exists in the store as a folder\n\n\n**Parameter**: \n\n\n  - `node:String` - node suposed to be a folder or not.\n\n\n**Returns**:  `Promise\u003chasFolder:Boolean\u003e` - result of the check.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n\n\n----\n\n### `Store#readFile(node:String, options=\"utf8\":String|Object):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  reads a file and returns its contents.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to be read as file.\n\n\n  - `options:Object` - options of the file reading.\n\n\n**Returns**:  `Promise\u003ccontents:String\u003e` - the contents of the file.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when file cannot be read.\n\n\n\n\n----\n\n### `Store#readFolder(node:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  reads a folder and returns its contents (files and folders).\n\n\n**Parameter**: \n\n\n  - `node:String` - node to be read as folder.\n\n\n**Returns**:  `Promise\u003cnodes:Array\u003cString\u003e\u003e` - nodes inside the folder.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when folder cannot be read.\n\n\n\n\n----\n\n### `Store#writeFile(node:String, contents:String|Buffer, options=\"utf8\":String|Object):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  writes contents to a file based in some options.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to be written as file.\n\n\n  - `contents:String|Buffer` - contents to be written.\n\n\n  - `options:String|Object` - options of the writing.\n\n\n**Returns**:  `Promise\u003cfilepath:String\u003e` - node overwritten.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when file cannot be written.\n\n\n\n\n----\n\n### `Store#createFolder(node:String, options={}:String|Object):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  creates a folder.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to create as folder.\n\n\n  - `options:Object` - options of the creation.\n\n\n**Returns**:  `filepath:String` - node created.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when folder cannot be created.\n\n\n\n\n----\n\n### `Store#updateFile(node:String, contents:String, options=\"utf8\":String|Object):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  if a file exists (1), it updates its content. Otherwise, it fails.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to be updated.\n\n\n  - `contents:String|Buffer` - contents to write.\n\n\n  - `options:String|Object` - options of the writing.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when node is not a file.\n\n\n  - when node is out of bounds.\n\n\n  - when file cannot be written.\n\n\n\n\n----\n\n### `Store#deleteFile(node:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  deletes a node as file.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to be deleted as file.\n\n\n**Returns**:  `filepath:String` - node deleted.\n\n\n**Throws**: \n\n\n  - when the node is out of bounds.\n\n\n  - when the file cannot be deleted.\n\n\n\n\n----\n\n### `Store#deleteFolder(node:String, options={}:String|Object):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  deletes a node as folder\n\n\n**Parameter**: \n\n\n  - `node:String` - node to delete as folder\n\n\n  - `options:Object` - options of the deletion\n\n\n**Returns**:  `Promise\u003cfolder:String\u003e` - folder to delete.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when folder cannot be deleted.\n\n\n\n\n----\n\n### `Store#ensureFile(node:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  ensures that a file exists or creates it.\n\n\n**Parameter**: \n\n\n  - `node:String` - file to be ensured.\n\n\n**Returns**:  `Promise\u003cString\u003e` - the file ensured.\n\n\n**Throws**: \n\n\n  - when the node is out of bounds.\n\n\n  - when the file cannot be ensured.\n\n\n\n\n----\n\n### `Store#ensureFolder(node:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  ensures that a folder exists or creates it.\n\n\n**Parameter**: \n\n\n  - `node:String` - folder to be ensured.\n\n\n**Returns**:  `Promise\u003cString\u003e` - the folder ensured.\n\n\n**Throws**: \n\n\n  - when the node is out of bounds.\n\n\n  - when the folder cannot be ensured.\n\n\n\n\n----\n\n### `Store#rename(oldNode:String, newNode:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  renames or moves a node.\n\n\n**Parameter**: \n\n\n  - `oldNode:String` - node source.\n\n\n  - `newNode:String` - node destination.\n\n\n**Returns**:  `Promise\u003cnodeDestination:String\u003e` - node destination.\n\n\n**Throws**: \n\n\n  - when node cannot be renamed.\n\n\n  - when a node is out of bounds.\n\n\n\n\n----\n\n### `Store#createReadStream(node:String):ReadStream`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  creates a node readable stream\n\n\n**Parameter**: \n\n\n  - `node:String` - node to create the stream from.\n\n\n**Returns**:  `readable:Stream` - readable stream of the node.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when stream cannot be created.\n\n\n\n\n----\n\n### `Store#createWriteStream(node:String):WriteStream`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  creates a node writable stream\n\n\n**Parameter**: \n\n\n  - `node:String` - node to create the stream from.\n\n\n**Returns**:  `writable:Stream` - writable stream of the node.\n\n\n**Throws**: \n\n\n  - when node is out of bounds.\n\n\n  - when stream cannot be created.\n\n\n\n\n----\n\n### `Store#writeFiles(nodes:Object\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  creates multiple files with one operation.\n\n\n**Parameter**: \n\n\n  - `nodes:Object\u003cString\u003e` - map `{ \u003cfilename\u003e:\u003cfilecontents\u003e }` of files to create.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when some file cannot be created.\n\n\n\n\n----\n\n### `Store#deleteFiles(nodes:Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  deletes multiple files with one operation.\n\n\n**Parameter**: \n\n\n  - `nodes:Array\u003cString\u003e` - list of files to delete.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when some file cannot be deleted.\n\n\n\n\n----\n\n### `Store#createFolders(nodes:Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  creates multiple folders with one operation.\n\n\n**Parameter**: \n\n\n  - `nodes:Array\u003cString\u003e` - list of folders to create.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when some folder cannot be created.\n\n\n\n\n----\n\n### `Store#deleteFolders(nodes:Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  deletes multiple folders with one operation.\n\n\n**Parameter**: \n\n\n  - `nodes:Array\u003cString\u003e` - list of folders to delete.\n\n\n**Returns**:  `Promise`\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when some folder cannot be deleted.\n\n\n\n\n----\n\n### `Store#ensureFiles(nodes:Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  ensures that some files exist or creates them.\n\n\n**Parameter**: \n\n\n  - `node:Array\u003cString\u003e` - files to be ensured.\n\n\n**Returns**:  `Promise\u003cArray\u003cString\u003e\u003e` - the files ensured.\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when the files cannot be ensured.\n\n\n\n\n----\n\n### `Store#ensureFolders(nodes:Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  ensures that some folders exist or creates them.\n\n\n**Parameter**: \n\n\n  - `node:String` - folders to be ensured.\n\n\n**Returns**:  `Promise\u003cString\u003e` - the folders ensured.\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when the folders cannot be ensured.\n\n\n\n\n----\n\n### `Store#deleteRecursively(node:String):Promise\u003cString\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  deletes a node (file or folder) and all its subnodes.\n\n\n**Parameter**: \n\n\n  - `node:String` - node to delete recursively.\n\n\n**Returns**:  `Promise\u003cString\u003e` - the node to delete recursively.\n\n\n**Throws**: \n\n\n  - when the node is out of bounds.\n\n\n  - when the node cannot be deleted recursively.\n\n\n\n\n----\n\n### `Store#findPatterns(patterns:String|Array\u003cString\u003e):Promise\u003cArray\u003cString\u003e\u003e`\n\n\n\n**Method**.\n\n\n**Asynchronous**.\n\n\n**Description**:  finds nodes by [glob patterns](https://www.npmjs.com/package/glob#glob-primer).\n\n\n**Parameter**: \n\n\n  - `patterns:String|Array\u003cString\u003e` - [glob patterns](https://www.npmjs.com/package/glob#glob-primer) to match.\n\n\n**Returns**:  `Promise\u003cArray\u003cString\u003e\u003e` - the nodes matched.\n\n\n**Throws**: \n\n\n  - when a node is out of bounds.\n\n\n  - when the search produces some error.\n\n\n\n\n\n## License\n\nThis project is licensed under [WTFPL](http://www.wtfpl.net/), which means 'do what you want with it'.\n\n## Issues and suggestions\n\nFor issues and suggestions, please, [here](https://github.com/allnulled/filesystem-store/issues).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fbasic-filesystem-store","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallnulled%2Fbasic-filesystem-store","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fbasic-filesystem-store/lists"}