diff --git a/README.md b/README.md index 26bf0d82e..1c8a6bafc 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ npm i memfs - `experimental` [`fs` to File System Access API adapter](./docs/fsa/fs-to-fsa.md) - `experimental` [File System Access API to `fs` adapter](./docs/fsa/fsa-to-fs.md) - `experimental` [`crudfs` a CRUD-like file system abstraction](./docs/crudfs/index.md) +- `experimental` [`casfs` Content Addressable Storage file system abstraction](./docs/casfs/index.md) ## Demos diff --git a/docs/casfs/index.md b/docs/casfs/index.md new file mode 100644 index 000000000..57096d16b --- /dev/null +++ b/docs/casfs/index.md @@ -0,0 +1,63 @@ +# `casfs` + +`casfs` is a Content Addressable Storage (CAS) abstraction over a file system. +It has no folders nor files. Instead, it has *blobs* which are identified by their content. + +Essentially, it provides two main operations: `put` and `get`. The `put` operation +takes a blob and stores it in the underlying file system and returns the blob's hash digest. +The `get` operation takes a hash and returns the blob, which matches the hash digest, if it exists. + + +## Usage + + +### `casfs` on top of Node.js `fs` module + +`casfs` builds on top of [`crudfs`](../crudfs//index.md), and `crudfs`—in turn—builds on top of +[File System Access API](../fsa/fs-to-fsa.md). + +```js +import * as fs from 'fs'; +import { nodeToFsa } from 'memfs/lib/node-to-fsa'; +import { FsaCrud } from 'memfs/lib/fsa-to-crud'; + +const fsa = nodeToFsa(fs, '/path/to/folder', {mode: 'readwrite'}); +const crud = new FsaCrud(fsa); +const cas = new CrudCas(crud, {hash}); +``` + +The `hash` is a function which computes a hash digest `string` from a `Uint8Array` blob. +Here is how one could look like: + +```ts +import { createHash } from 'crypto'; + +const hash = async (blob: Uint8Array): Promise => { + const shasum = createHash('sha1'); + shasum.update(blob); + return shasum.digest('hex'); +}; +``` + +Now that you have a `cas` instance, you can use it to `put` and `get` blobs. + +```js +const blob = new Uint8Array([1, 2, 3]); + +const hash = await cas.put(blob); +console.log(hash); // 9dc58b6d4e8eefb5a3c3e0c9f4a1a0b1b2b3b4b5 + +const blob2 = await cas.get(hash); +``` + +You can also delete blobs: + +```js +await cas.delete(hash); +``` + +And retrieve information about blobs: + +```js +const info = await cas.info(hash); +```