# basic-filesystem-store > Basic store for filesystem, based in promises. Latest version **0.0.7** (published 2020-03-23) · WTFPL license · 0 weekly downloads ## Install ```sh npm install basic-filesystem-store pnpm add basic-filesystem-store yarn add basic-filesystem-store bun add basic-filesystem-store ``` ## Health **Score 15/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.0.7 | | Published | 2020-03-23 | | First published | 2020-03-23 | | Weekly downloads | 0 | | License | WTFPL | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 3 | | Unpacked size | 474.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | allnulled | | Maintainers | allnulled | | Keywords | store, file, filesystem, promise | ## Links - npm: https://www.npmjs.com/package/basic-filesystem-store - Repository: https://github.com/allnulled/basic-filesystem-store - Homepage: https://github.com/allnulled/basic-filesystem-store#readme - Issues: https://github.com/allnulled/basic-filesystem-store/issues - npm.io page: https://npm.io/package/basic-filesystem-store ## Dependencies (3) - [debug](https://npm.io/package/debug.md) ^4.1.1 - [globby](https://npm.io/package/globby.md) ^11.0.0 - [fs-extra](https://npm.io/package/fs-extra.md) ^9.0.0 ## Alternatives - [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads - [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads - [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads - [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads - [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads ## Recent versions - 0.0.7 (latest) — 2020-03-23 - 0.0.6 — 2020-03-23 - 0.0.5 — 2020-03-23 ## README # basic-filesystem-store Basic filesystem store interface and implementation. ## Install `$ npm i -s basic-filesystem-store` ## Why? To have a universal (promise-based) interface to interact with the filesystem. To have a universal safe interface to interact with the filesystem. ## Overview ### Goal The API is aimed to support the following features, and serve as a universal interface based in promises to interact with a filesystem-like data exchanger: - operate under safe nodes (specially when `"/"` and `".."` come into play) - initialize stores - create paths - create streams - create folders and files - ensure folders and files - read folders and files - write folders and files - update folders and files - delete folders and files - rename folders and files - check the existence folders and files - find folders and files by patterns ### Current state The current API supports this set of methods: - **Sync:** - `store.getPath(node:String)` - `store.createReadStream(node:String)` - `store.createWriteStream(node:String)` - **Async:** - `store.initialize()` - `store.createFolder(node:String)` - `store.createFolders(nodes:Array)` - `store.deleteFile(node:String)` - `store.deleteFiles(nodes:Array)` - `store.deleteFolder(node:String)` - `store.deleteRecursively(nodes:Array)` - `store.describe(node:String)` - `store.ensureFile(node:String)` - `store.ensureFiles(nodes:Array)` - `store.ensureFolder(node:String)` - `store.ensureFolders(nodes:Array)` - `store.has(node:String)` - `store.hasFile(node:String)` - `store.hasFolder(node:String)` - `store.readFile(node:String, contents:String)` - `store.readFolder(node:String)` - `store.rename(nodeSrc:String, nodeDst:String)` - `store.writeFile(node:String, contents:String, options:String|Object)` - `store.writeFiles(nodes:Object)` - `store.findPatterns(patterns:Array)` ## API reference ---- ### `Store.create(...args):Store` **Static Method**. **Synchronous**. **Description**: creates a new store instance. Read about the constructor of the class for more info. ---- ### `Store.DEFAULT_OPTIONS:Object` **Static Property**. **Description**: default values of options. Any property here can be overwritten from the constructor's options. **Property**: `basedir:String` - directory used as store. - defaults to `process.cwd() + "/_files_"` ---- ### `Store.constructor(options={}:Object):Store` **Constructor**. **Description**: method that generates a new store. **Parameter**: - `options={}:Object` - options that can overwrite properties and methods of the created store. **Returns**: `Store` - a new store. ---- ### `Store.ORIGINAL_INTERFACE` **Static Property**. **Description**: best class to inherit from if you want to develop your own store. ---- ### `Store#initialize():Promise` **Method**. **Asynchronous**: **Description**: ensures the existence of `basedir` folder. **Returns**: `Promise` **Throws**: - when folder cannot be ensured. ---- ### `Store#getPath(node:String):String` **Method**. **Synchronous**. **Description**: returns the full path from an identifier of the node in the store. **Parameter**: - `node:String` - node identifier, or subpath. Must be inside the folder. **Returns**: `filepath:String | Error` - full path of the file, or an object error. Must be checked once returned. **Throws**: - when node is out of bounds. ---- ### `Store#describe(node:String):Promise` **Method**. **Asynchronous**. **Description**: returns a [stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) object. **Parameter**: - `node:String` - node to describe. **Returns**: `Promise` a [stats](https://nodejs.org/api/fs.html#fs_class_fs_stats) object of the node. **Throws**: - when no node is found. - when node is out of bounds. ---- ### `Store#has(node:String):Promise` **Method**. **Asynchronous**. **Description**: checks if a node exists in the store **Parameter**: - `node:String` - node suposed to exist. **Returns**: `Promise` - result of the check. **Throws**: - when node is out of bounds. ---- ### `Store#hasFile(node:String):Promise` **Method**. **Asynchronous**. **Description**: checks if a node exists in the store as a file **Parameter**: - `node:String` - node suposed to be a file or not. **Returns**: `Promise` - result of the check. **Throws**: - when node is out of bounds. ---- ### `Store#hasFolder(node:String):Promise` **Method**. **Asynchronous**. **Description**: check if a node exists in the store as a folder **Parameter**: - `node:String` - node suposed to be a folder or not. **Returns**: `Promise` - result of the check. **Throws**: - when node is out of bounds. ---- ### `Store#readFile(node:String, options="utf8":String|Object):Promise` **Method**. **Asynchronous**. **Description**: reads a file and returns its contents. **Parameter**: - `node:String` - node to be read as file. - `options:Object` - options of the file reading. **Returns**: `Promise` - the contents of the file. **Throws**: - when node is out of bounds. - when file cannot be read. ---- ### `Store#readFolder(node:String):Promise` **Method**. **Asynchronous**. **Description**: reads a folder and returns its contents (files and folders). **Parameter**: - `node:String` - node to be read as folder. **Returns**: `Promise>` - nodes inside the folder. **Throws**: - when node is out of bounds. - when folder cannot be read. ---- ### `Store#writeFile(node:String, contents:String|Buffer, options="utf8":String|Object):Promise` **Method**. **Asynchronous**. **Description**: writes contents to a file based in some options. **Parameter**: - `node:String` - node to be written as file. - `contents:String|Buffer` - contents to be written. - `options:String|Object` - options of the writing. **Returns**: `Promise` - node overwritten. **Throws**: - when node is out of bounds. - when file cannot be written. ---- ### `Store#createFolder(node:String, options={}:String|Object):Promise` **Method**. **Asynchronous**. **Description**: creates a folder. **Parameter**: - `node:String` - node to create as folder. - `options:Object` - options of the creation. **Returns**: `filepath:String` - node created. **Throws**: - when node is out of bounds. - when folder cannot be created. ---- ### `Store#updateFile(node:String, contents:String, options="utf8":String|Object):Promise` **Method**. **Asynchronous**. **Description**: if a file exists (1), it updates its content. Otherwise, it fails. **Parameter**: - `node:String` - node to be updated. - `contents:String|Buffer` - contents to write. - `options:String|Object` - options of the writing. **Returns**: `Promise` **Throws**: - when node is not a file. - when node is out of bounds. - when file cannot be written. ---- ### `Store#deleteFile(node:String):Promise` **Method**. **Asynchronous**. **Description**: deletes a node as file. **Parameter**: - `node:String` - node to be deleted as file. **Returns**: `filepath:String` - node deleted. **Throws**: - when the node is out of bounds. - when the file cannot be deleted. ---- ### `Store#deleteFolder(node:String, options={}:String|Object):Promise` **Method**. **Asynchronous**. **Description**: deletes a node as folder **Parameter**: - `node:String` - node to delete as folder - `options:Object` - options of the deletion **Returns**: `Promise` - folder to delete. **Throws**: - when node is out of bounds. - when folder cannot be deleted. ---- ### `Store#ensureFile(node:String):Promise` **Method**. **Asynchronous**. **Description**: ensures that a file exists or creates it. **Parameter**: - `node:String` - file to be ensured. **Returns**: `Promise` - the file ensured. **Throws**: - when the node is out of bounds. - when the file cannot be ensured. ---- ### `Store#ensureFolder(node:String):Promise` **Method**. **Asynchronous**. **Description**: ensures that a folder exists or creates it. **Parameter**: - `node:String` - folder to be ensured. **Returns**: `Promise` - the folder ensured. **Throws**: - when the node is out of bounds. - when the folder cannot be ensured. ---- ### `Store#rename(oldNode:String, newNode:String):Promise` **Method**. **Asynchronous**. **Description**: renames or moves a node. **Parameter**: - `oldNode:String` - node source. - `newNode:String` - node destination. **Returns**: `Promise` - node destination. **Throws**: - when node cannot be renamed. - when a node is out of bounds. ---- ### `Store#createReadStream(node:String):ReadStream` **Method**. **Asynchronous**. **Description**: creates a node readable stream **Parameter**: - `node:String` - node to create the stream from. **Returns**: `readable:Stream` - readable stream of the node. **Throws**: - when node is out of bounds. - when stream cannot be created. ---- ### `Store#createWriteStream(node:String):WriteStream` **Method**. **Asynchronous**. **Description**: creates a node writable stream **Parameter**: - `node:String` - node to create the stream from. **Returns**: `writable:Stream` - writable stream of the node. **Throws**: - when node is out of bounds. - when stream cannot be created. ---- ### `Store#writeFiles(nodes:Object):Promise>` **Method**. **Asynchronous**. **Description**: creates multiple files with one operation. **Parameter**: - `nodes:Object` - map `{ : }` of files to create. **Returns**: `Promise` **Throws**: - when a node is out of bounds. - when some file cannot be created. ---- ### `Store#deleteFiles(nodes:Array):Promise>` **Method**. **Asynchronous**. **Description**: deletes multiple files with one operation. **Parameter**: - `nodes:Array` - list of files to delete. **Returns**: `Promise` **Throws**: - when a node is out of bounds. - when some file cannot be deleted. ---- ### `Store#createFolders(nodes:Array):Promise>` **Method**. **Asynchronous**. **Description**: creates multiple folders with one operation. **Parameter**: - `nodes:Array` - list of folders to create. **Returns**: `Promise` **Throws**: - when a node is out of bounds. - when some folder cannot be created. ---- ### `Store#deleteFolders(nodes:Array):Promise>` **Method**. **Asynchronous**. **Description**: deletes multiple folders with one operation. **Parameter**: - `nodes:Array` - list of folders to delete. **Returns**: `Promise` **Throws**: - when a node is out of bounds. - when some folder cannot be deleted. ---- ### `Store#ensureFiles(nodes:Array):Promise>` **Method**. **Asynchronous**. **Description**: ensures that some files exist or creates them. **Parameter**: - `node:Array` - files to be ensured. **Returns**: `Promise>` - the files ensured. **Throws**: - when a node is out of bounds. - when the files cannot be ensured. ---- ### `Store#ensureFolders(nodes:Array):Promise>` **Method**. **Asynchronous**. **Description**: ensures that some folders exist or creates them. **Parameter**: - `node:String` - folders to be ensured. **Returns**: `Promise` - the folders ensured. **Throws**: - when a node is out of bounds. - when the folders cannot be ensured. ---- ### `Store#deleteRecursively(node:String):Promise` **Method**. **Asynchronous**. **Description**: deletes a node (file or folder) and all its subnodes. **Parameter**: - `node:String` - node to delete recursively. **Returns**: `Promise` - the node to delete recursively. **Throws**: - when the node is out of bounds. - when the node cannot be deleted recursively. ---- ### `Store#findPatterns(patterns:String|Array):Promise>` **Method**. **Asynchronous**. **Description**: finds nodes by [glob patterns](https://www.npmjs.com/package/glob#glob-primer). **Parameter**: - `patterns:String|Array` - [glob patterns](https://www.npmjs.com/package/glob#glob-primer) to match. **Returns**: `Promise>` - the nodes matched. **Throws**: - when a node is out of bounds. - when the search produces some error. ## License This project is licensed under [WTFPL](http://www.wtfpl.net/), which means 'do what you want with it'. ## Issues and suggestions For issues and suggestions, please, [here](https://github.com/allnulled/filesystem-store/issues). --- _Source: https://npm.io/package/basic-filesystem-store · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._