From 0aa0944d42798d1f6fd589e8a58de7d791760644 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 27 Nov 2023 10:29:27 +0000 Subject: [PATCH] deps(dev): bump aegir from 40.0.13 to 41.1.9 (#268) Bumps [aegir](https://github.com/ipfs/aegir) from 40.0.13 to 41.1.9. - [Release notes](https://github.com/ipfs/aegir/releases) - [Changelog](https://github.com/ipfs/aegir/blob/master/CHANGELOG.md) - [Commits](https://github.com/ipfs/aegir/compare/v40.0.13...v41.1.9) --- updated-dependencies: - dependency-name: aegir dependency-type: direct:development update-type: version-update:semver-major ... --------- Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: achingbrain --- .github/workflows/semantic-pull-request.yml | 12 ++ README.md | 22 +-- package.json | 2 +- packages/blockstore-core/README.md | 91 +----------- packages/blockstore-core/package.json | 3 +- packages/blockstore-core/src/index.ts | 69 +++++++++ packages/blockstore-core/test/memory.spec.ts | 2 +- packages/blockstore-fs/README.md | 26 +--- packages/blockstore-fs/package.json | 6 +- packages/blockstore-fs/src/index.ts | 14 ++ packages/blockstore-fs/src/sharding.ts | 4 +- packages/blockstore-fs/test/index.spec.ts | 10 +- packages/blockstore-idb/README.md | 28 ++-- packages/blockstore-idb/package.json | 3 +- packages/blockstore-idb/src/index.ts | 14 ++ packages/blockstore-level/README.md | 30 ++-- packages/blockstore-level/package.json | 3 +- packages/blockstore-level/src/index.ts | 16 ++ packages/blockstore-s3/README.md | 63 ++++---- packages/blockstore-s3/package.json | 3 +- packages/blockstore-s3/src/index.ts | 27 ++++ packages/blockstore-s3/src/sharding.ts | 4 +- packages/blockstore-s3/test/index.spec.ts | 2 +- packages/datastore-core/README.md | 94 +----------- packages/datastore-core/package.json | 3 +- packages/datastore-core/src/index.ts | 71 ++++++++- packages/datastore-fs/README.md | 30 ++-- packages/datastore-fs/package.json | 3 +- packages/datastore-fs/src/index.ts | 14 ++ packages/datastore-idb/README.md | 28 ++-- packages/datastore-idb/package.json | 6 +- packages/datastore-idb/src/index.ts | 14 ++ packages/datastore-level/README.md | 53 +++---- packages/datastore-level/package.json | 3 +- packages/datastore-level/src/index.ts | 52 ++++++- packages/datastore-s3/README.md | 57 +++---- packages/datastore-s3/package.json | 3 +- packages/datastore-s3/src/index.ts | 25 ++++ packages/interface-blockstore-tests/README.md | 30 ++-- .../interface-blockstore-tests/package.json | 3 +- .../interface-blockstore-tests/src/index.ts | 28 +++- packages/interface-blockstore/README.md | 28 ++-- packages/interface-blockstore/package.json | 3 +- packages/interface-blockstore/src/index.ts | 18 ++- packages/interface-datastore-tests/README.md | 30 ++-- .../interface-datastore-tests/package.json | 3 +- .../interface-datastore-tests/src/index.ts | 28 +++- packages/interface-datastore/README.md | 139 +----------------- packages/interface-datastore/package.json | 3 +- packages/interface-datastore/src/index.ts | 110 +++++++++++++- packages/interface-store/README.md | 17 +-- packages/interface-store/package.json | 7 +- packages/interface-store/src/index.ts | 26 ++-- packages/interface-store/typedoc.json | 5 + 54 files changed, 760 insertions(+), 628 deletions(-) create mode 100644 .github/workflows/semantic-pull-request.yml create mode 100644 packages/interface-store/typedoc.json diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.yml new file mode 100644 index 00000000..bd00f090 --- /dev/null +++ b/.github/workflows/semantic-pull-request.yml @@ -0,0 +1,12 @@ +name: Semantic PR + +on: + pull_request_target: + types: + - opened + - edited + - synchronize + +jobs: + main: + uses: pl-strflt/.github/.github/workflows/reusable-semantic-pull-request.yml@v0.3 diff --git a/README.md b/README.md index c55056f4..9e796f7b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -# stores - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,15 +5,7 @@ > Blockstores and datastores used by IP-JS internals -## Table of contents - -- [Structure](#structure) -- [Packages](#packages) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) - -## Structure +# Packages - [`/packages/blockstore-core`](./packages/blockstore-core) Contains various implementations of the API contract described in interface-blockstore - [`/packages/blockstore-fs`](./packages/blockstore-fs) Blockstore implementation with file system backend @@ -33,22 +23,18 @@ - [`/packages/interface-datastore-tests`](./packages/interface-datastore-tests) Compliance tests for the datastore interface - [`/packages/interface-store`](./packages/interface-store) A generic interface for storing and retrieving data -## Packages - -See the [./packages](./packages) directory for the various interfaces. - -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/package.json b/package.json index 25e5f8b1..1283763c 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "release": "npm run docs:no-publish && aegir run release && npm run docs" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" }, "workspaces": [ "packages/*" diff --git a/packages/blockstore-core/README.md b/packages/blockstore-core/README.md index f55d6b17..8ab2013a 100644 --- a/packages/blockstore-core/README.md +++ b/packages/blockstore-core/README.md @@ -1,5 +1,3 @@ -# blockstore-core - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,27 +5,13 @@ > Contains various implementations of the API contract described in interface-blockstore -## Table of contents - -- [Install](#install) - - [Browser ` ``` -## Implementations - -- Base: [`src/base`](src/base.ts) -- Memory: [`src/memory`](src/memory.ts) -- BlackHole: ['src/black-hole](src/black-hole.ts) -- Tiered: ['src/tiered](src/tiered.ts) - -## Usage - -### BaseBlockstore - -Provides a complete implementation of the Blockstore interface. You must implement `.get`, `.put`, etc. - -```js -import { BaseBlockstore } from 'blockstore-core/base' - -class MyCustomBlockstore extends BaseBlockstore { - put (key, val, options) { - // store a block - } - - get (key, options) { - // retrieve a block - } - - // ...etc -} -``` - -### MemoryBlockstore - -A simple Blockstore that stores blocks in memory. - -```js -import { MemoryBlockstore } from 'blockstore-core/memory' - -const store = new MemoryBlockstore() -``` - -### BlackHoleBlockstore - -A Blockstore that does not store any blocks. - -```js -import { BlackHoleBlockstore } from 'blockstore-core/black-hole' - -const store = new BlackHoleBlockstore() -``` - -### TieredBlockstore - -A tiered blockstore wraps one or more blockstores and will query each in parallel to retrieve a block - the operation will succeed if any wrapped store has the block. - -Writes are invoked on all wrapped blockstores. - -```js -import { TieredBlockstore } from 'blockstore-core/tiered' - -const store = new TieredBlockstore([ - store1, - store2, - // ...etc -]) -``` - -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/blockstore-core/package.json b/packages/blockstore-core/package.json index 597f67e2..eea19605 100644 --- a/packages/blockstore-core/package.json +++ b/packages/blockstore-core/package.json @@ -71,6 +71,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -186,7 +187,7 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-blockstore-tests": "^6.0.0" } } diff --git a/packages/blockstore-core/src/index.ts b/packages/blockstore-core/src/index.ts index 69fa16c8..3e4df1a4 100644 --- a/packages/blockstore-core/src/index.ts +++ b/packages/blockstore-core/src/index.ts @@ -1,3 +1,72 @@ +/** + * @packageDocumentation + * + * Various Blockstore implementations are available. + * + * ## Implementations + * + * - Base: [`src/base`](src/base.ts) + * - Memory: [`src/memory`](src/memory.ts) + * - BlackHole: ['src/black-hole](src/black-hole.ts) + * - Tiered: ['src/tiered](src/tiered.ts) + * + * @example BaseBlockstore + * + * Provides a complete implementation of the Blockstore interface. You must implement `.get`, `.put`, etc. + * + * ```js + * import { BaseBlockstore } from 'blockstore-core/base' + * + * class MyCustomBlockstore extends BaseBlockstore { + * put (key, val, options) { + * // store a block + * } + * + * get (key, options) { + * // retrieve a block + * } + * + * // ...etc + * } + * ``` + * + * @example MemoryBlockstore + * + * A simple Blockstore that stores blocks in memory. + * + * ```js + * import { MemoryBlockstore } from 'blockstore-core/memory' + * + * const store = new MemoryBlockstore() + * ``` + * + * @example BlackHoleBlockstore + * + * A Blockstore that does not store any blocks. + * + * ```js + * import { BlackHoleBlockstore } from 'blockstore-core/black-hole' + * + * const store = new BlackHoleBlockstore() + * ``` + * + * @example TieredBlockstore + * + * A tiered blockstore wraps one or more blockstores and will query each in parallel to retrieve a block - the operation will succeed if any wrapped store has the block. + * + * Writes are invoked on all wrapped blockstores. + * + * ```js + * import { TieredBlockstore } from 'blockstore-core/tiered' + * + * const store = new TieredBlockstore([ + * store1, + * store2, + * // ...etc + * ]) + * ``` + */ + import * as ErrorsImport from './errors.js' export { BaseBlockstore } from './base.js' diff --git a/packages/blockstore-core/test/memory.spec.ts b/packages/blockstore-core/test/memory.spec.ts index d42c548b..0bf49373 100644 --- a/packages/blockstore-core/test/memory.spec.ts +++ b/packages/blockstore-core/test/memory.spec.ts @@ -4,7 +4,7 @@ import { interfaceBlockstoreTests } from 'interface-blockstore-tests' import { MemoryBlockstore } from '../src/memory.js' describe('memory', () => { - describe('interface-datastore', () => { + describe('interface-blockstore', () => { interfaceBlockstoreTests({ setup () { return new MemoryBlockstore() diff --git a/packages/blockstore-fs/README.md b/packages/blockstore-fs/README.md index e46e8afa..f2e27373 100644 --- a/packages/blockstore-fs/README.md +++ b/packages/blockstore-fs/README.md @@ -1,5 +1,3 @@ -# blockstore-fs - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,40 +5,24 @@ > Blockstore implementation with file system backend -## Table of contents - -- [Install](#install) -- [Usage](#usage) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) - -## Install +# Install ```console $ npm i blockstore-fs ``` -## Usage - -```js -import { FsBlockstore } from 'blockstore-fs' - -const store = new FsBlockstore('path/to/store') -``` - -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/blockstore-fs/package.json b/packages/blockstore-fs/package.json index fc0e3192..a77cc58a 100644 --- a/packages/blockstore-fs/package.json +++ b/packages/blockstore-fs/package.json @@ -55,11 +55,11 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { - "sourceType": "module", "project": [ "tsconfig.json", "benchmarks/encoding/tsconfig.json" - ] + ], + "sourceType": "module" } }, "release": { @@ -168,7 +168,7 @@ "multiformats": "^12.0.1" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-blockstore-tests": "^6.0.0" } } diff --git a/packages/blockstore-fs/src/index.ts b/packages/blockstore-fs/src/index.ts index 06471475..c029b0e4 100644 --- a/packages/blockstore-fs/src/index.ts +++ b/packages/blockstore-fs/src/index.ts @@ -1,3 +1,17 @@ +/** + * @packageDocumentation + * + * A Blockstore implementation that stores blocks in the local filesystem. + * + * @example + * + * ```js + * import { FsBlockstore } from 'blockstore-fs' + * + * const store = new FsBlockstore('path/to/store') + * ``` + */ + import fs from 'node:fs/promises' import path from 'node:path' import { promisify } from 'node:util' diff --git a/packages/blockstore-fs/src/sharding.ts b/packages/blockstore-fs/src/sharding.ts index 10d65169..aa6365be 100644 --- a/packages/blockstore-fs/src/sharding.ts +++ b/packages/blockstore-fs/src/sharding.ts @@ -5,8 +5,8 @@ import type { MultibaseCodec } from 'multiformats/bases/interface' export interface ShardingStrategy { extension: string - encode: (cid: CID) => { dir: string, file: string } - decode: (path: string) => CID + encode(cid: CID): { dir: string, file: string } + decode(path: string): CID } export interface NextToLastInit { diff --git a/packages/blockstore-fs/test/index.spec.ts b/packages/blockstore-fs/test/index.spec.ts index 25e0ebc3..696bacbc 100644 --- a/packages/blockstore-fs/test/index.spec.ts +++ b/packages/blockstore-fs/test/index.spec.ts @@ -4,7 +4,7 @@ import os from 'node:os' import path from 'node:path' import { expect } from 'aegir/chai' import { interfaceBlockstoreTests } from 'interface-blockstore-tests' -import { base256emoji } from 'multiformats/bases/base256emoji' +import { base32 } from 'multiformats/bases/base32' import { CID } from 'multiformats/cid' import { FsBlockstore } from '../src/index.js' import { FlatDirectory, NextToLast } from '../src/sharding.js' @@ -84,7 +84,7 @@ describe('FsBlockstore', () => { .with.property('code', 'ERR_NOT_FOUND') }) - describe('interface-datastore (flat directory)', () => { + describe('interface-blockstore (flat directory)', () => { interfaceBlockstoreTests({ setup: async () => { const store = new FsBlockstore(path.join(os.tmpdir(), `test-${Math.random()}`), { @@ -103,7 +103,7 @@ describe('FsBlockstore', () => { }) }) - describe('interface-datastore (default sharding)', () => { + describe('interface-blockstore (default sharding)', () => { interfaceBlockstoreTests({ setup: async () => { const store = new FsBlockstore(path.join(os.tmpdir(), `test-${Math.random()}`)) @@ -120,12 +120,12 @@ describe('FsBlockstore', () => { }) }) - describe('interface-datastore (custom encoding)', () => { + describe('interface-blockstore (custom encoding)', () => { interfaceBlockstoreTests({ setup: async () => { const store = new FsBlockstore(path.join(os.tmpdir(), `test-${Math.random()}`), { shardingStrategy: new NextToLast({ - base: base256emoji + base: base32 }) }) diff --git a/packages/blockstore-idb/README.md b/packages/blockstore-idb/README.md index ecb33d07..5e007576 100644 --- a/packages/blockstore-idb/README.md +++ b/packages/blockstore-idb/README.md @@ -1,5 +1,3 @@ -# blockstore-idb - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,25 @@ > Blockstore implementation with IndexedDB backend -## Table of contents +# About + +A Blockstore implementation for browsers that stores blocks in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). + +## Example -- [Install](#install) - - [Browser ` ``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/blockstore-idb/package.json b/packages/blockstore-idb/package.json index 2a0222ea..ebc5a805 100644 --- a/packages/blockstore-idb/package.json +++ b/packages/blockstore-idb/package.json @@ -36,6 +36,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -144,7 +145,7 @@ "multiformats": "^12.0.1" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-blockstore-tests": "^6.0.0" } } diff --git a/packages/blockstore-idb/src/index.ts b/packages/blockstore-idb/src/index.ts index 8adbe0eb..27b6882b 100644 --- a/packages/blockstore-idb/src/index.ts +++ b/packages/blockstore-idb/src/index.ts @@ -1,3 +1,17 @@ +/** + * @packageDocumentation + * + * A Blockstore implementation for browsers that stores blocks in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). + * + * @example + * + * ```js + * import { IDBBlockstore } from 'blockstore-idb' + * + * const store = new IDBBlockstore('path/to/store') + * ``` + */ + import { BaseBlockstore, Errors diff --git a/packages/blockstore-level/README.md b/packages/blockstore-level/README.md index 3372bd47..6434601f 100644 --- a/packages/blockstore-level/README.md +++ b/packages/blockstore-level/README.md @@ -1,5 +1,3 @@ -# blockstore-level - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,27 @@ > Blockstore implementation with level(up|down) backend -## Table of contents +# About + +A Blockstore implementation that uses a flavour of [Level](https://leveljs.org/) as a backend. + +N.b. this is here largely for the sake of completeness, in node you should probably use FSDatastore, in browsers you should probably use IDBDatastore. -- [Install](#install) - - [Browser ` ``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/blockstore-level/package.json b/packages/blockstore-level/package.json index 92ce2ecd..bfd11484 100644 --- a/packages/blockstore-level/package.json +++ b/packages/blockstore-level/package.json @@ -37,6 +37,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -147,7 +148,7 @@ "multiformats": "^12.0.1" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-blockstore-tests": "^6.0.0", "ipfs-utils": "^9.0.4", "memory-level": "^1.0.0" diff --git a/packages/blockstore-level/src/index.ts b/packages/blockstore-level/src/index.ts index 4748dda1..22ac0ab5 100644 --- a/packages/blockstore-level/src/index.ts +++ b/packages/blockstore-level/src/index.ts @@ -1,3 +1,19 @@ +/** + * @packageDocumentation + * + * A Blockstore implementation that uses a flavour of [Level](https://leveljs.org/) as a backend. + * + * N.b. this is here largely for the sake of completeness, in node you should probably use FSDatastore, in browsers you should probably use IDBDatastore. + * + * @example + * + * ```js + * import { LevelBlockstore } from 'blockstore-level' + * + * const store = new LevelBlockstore('path/to/store') + * ``` + */ + import { BaseBlockstore, Errors } from 'blockstore-core' import { Level } from 'level' import { base32upper } from 'multiformats/bases/base32' diff --git a/packages/blockstore-s3/README.md b/packages/blockstore-s3/README.md index 50e16998..c57f45e6 100644 --- a/packages/blockstore-s3/README.md +++ b/packages/blockstore-s3/README.md @@ -1,5 +1,3 @@ -# blockstore-s3 - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,66 +5,59 @@ > IPFS blockstore implementation backed by s3 -## Table of contents - -- [Install](#install) - - [Browser ` -``` +A Blockstore implementation that stores blocks on Amazon S3. -## Usage +## Example - Quickstart -If the flag `createIfMissing` is not set or is false, then the bucket must be created prior to using datastore-s3. Please see the AWS docs for information on how to configure the S3 instance. A bucket name is required to be set at the s3 instance level, see the below example. +If the flag `createIfMissing` is not set or is false, then the bucket must be created prior to using blockstore-s3. Please see the AWS docs for information on how to configure the S3 instance. A bucket name is required to be set at the s3 instance level, see the below example. ```js import S3 from 'aws-sdk/clients/s3.js' -import { S3Datastore } from 'datastore-s3' +import { S3Blockstore } from 'blockstore-s3' const s3Instance = new S3({ params: { Bucket: 'my-ipfs-bucket' } }) -const store = new S3Datastore('.ipfs/datastore', { +const store = new S3Blockstore('.ipfs/datastore', { s3: s3Instance createIfMissing: false }) ``` -### Create a Repo +## Example -See [examples/full-s3-repo](./examples/full-s3-repo) for how to quickly create an S3 backed repo using the `createRepo` convenience function. +```ts +Using with Helia -### Examples +See [examples/helia](./examples/helia) for a full example of how to use Helia with an S3 backed blockstore. +``` + +# Install + +```console +$ npm i blockstore-s3 +``` -You can see examples of S3 backed ipfs in the [examples folder](examples/) +## Browser ` +``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/blockstore-s3/package.json b/packages/blockstore-s3/package.json index a22d3b7a..ea5bad84 100644 --- a/packages/blockstore-s3/package.json +++ b/packages/blockstore-s3/package.json @@ -35,6 +35,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -148,7 +149,7 @@ }, "devDependencies": { "@types/sinon": "^10.0.15", - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-blockstore-tests": "^6.0.0", "p-defer": "^4.0.0", "sinon": "^15.0.2" diff --git a/packages/blockstore-s3/src/index.ts b/packages/blockstore-s3/src/index.ts index 0444d4d3..4757866f 100644 --- a/packages/blockstore-s3/src/index.ts +++ b/packages/blockstore-s3/src/index.ts @@ -1,3 +1,28 @@ +/** + * @packageDocumentation + * + * A Blockstore implementation that stores blocks on Amazon S3. + * + * @example Quickstart + * + * If the flag `createIfMissing` is not set or is false, then the bucket must be created prior to using blockstore-s3. Please see the AWS docs for information on how to configure the S3 instance. A bucket name is required to be set at the s3 instance level, see the below example. + * + * ```js + * import S3 from 'aws-sdk/clients/s3.js' + * import { S3Blockstore } from 'blockstore-s3' + * + * const s3Instance = new S3({ params: { Bucket: 'my-ipfs-bucket' } }) + * const store = new S3Blockstore('.ipfs/datastore', { + * s3: s3Instance + * createIfMissing: false + * }) + * ``` + * + * @example Using with Helia + * + * See [examples/helia](./examples/helia) for a full example of how to use Helia with an S3 backed blockstore. + */ + import { PutObjectCommand, CreateBucketCommand, @@ -16,6 +41,8 @@ import type { Pair } from 'interface-blockstore' import type { AbortOptions } from 'interface-store' import type { CID } from 'multiformats/cid' +export type { ShardingStrategy } + export interface S3BlockstoreInit { /** * Whether to try to create the bucket if it is missing when `.open` is called diff --git a/packages/blockstore-s3/src/sharding.ts b/packages/blockstore-s3/src/sharding.ts index ef086143..b3cd23ac 100644 --- a/packages/blockstore-s3/src/sharding.ts +++ b/packages/blockstore-s3/src/sharding.ts @@ -4,8 +4,8 @@ import type { MultibaseCodec } from 'multiformats/bases/interface' export interface ShardingStrategy { extension: string - encode: (cid: CID) => string - decode: (path: string) => CID + encode(cid: CID): string + decode(path: string): CID } export interface NextToLastInit { diff --git a/packages/blockstore-s3/test/index.spec.ts b/packages/blockstore-s3/test/index.spec.ts index 7c537d9e..7e849e17 100644 --- a/packages/blockstore-s3/test/index.spec.ts +++ b/packages/blockstore-s3/test/index.spec.ts @@ -169,7 +169,7 @@ describe('S3Blockstore', () => { }) }) - describe('interface-datastore', () => { + describe('interface-blockstore', () => { interfaceBlockstoreTests({ setup () { const s3 = s3Mock(new S3({ region: 'REGION' })) diff --git a/packages/datastore-core/README.md b/packages/datastore-core/README.md index b794d97b..03229227 100644 --- a/packages/datastore-core/README.md +++ b/packages/datastore-core/README.md @@ -1,5 +1,3 @@ -# datastore-core - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,27 +5,13 @@ > Wrapper implementation for interface-datastore -## Table of contents - -- [Install](#install) - - [Browser ` ``` -## Implementations - -- Wrapper Implementations - - Mount: [`src/mount`](src/mount.ts) - - Keytransform: [`src/keytransform`](src/keytransform.ts) - - Sharding: [`src/sharding`](src/sharding.ts) - - Tiered: [`src/tiered`](src/tirered.ts) - - Namespace: [`src/namespace`](src/namespace.ts) - - BlackHole: [`src/black-hole`](src/black-hole.ts) - -## Usage - -### BaseDatastore - -An base store is made available to make implementing your own datastore easier: - -```javascript -import { BaseDatastore } from 'datastore-core' - -class MyDatastore extends BaseDatastore { - constructor () { - super() - } - - async put (key, val) { - // your implementation here - } - - async get (key) { - // your implementation here - } - - // etc... -} -``` - -See the [MemoryDatastore](./src/memory.js) for an example of how it is used. - -### Wrapping Stores - -```js -import { Key } from 'interface-datastore' -import { - MemoryStore, - MountStore -} from 'datastore-core' - -const store = new MountStore({prefix: new Key('/a'), datastore: new MemoryStore()}) -``` - -### BlackHoleDatastore - -A datastore that does not store any data. - -```js -import { BlackHoleDatastore } from 'datastore-core/black-hole' - -const store = new BlackHoleDatastore() -``` - -## Contribute - -Feel free to join in. All welcome. Open an [issue](https://github.com/ipfs/js-ipfs-unixfs-importer/issues)! - -This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md). - -[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) - -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/datastore-core/package.json b/packages/datastore-core/package.json index 9d079da4..946c8ab2 100644 --- a/packages/datastore-core/package.json +++ b/packages/datastore-core/package.json @@ -91,6 +91,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -209,7 +210,7 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-datastore": "^8.0.0", "interface-datastore-tests": "^5.0.0" } diff --git a/packages/datastore-core/src/index.ts b/packages/datastore-core/src/index.ts index 73e80c48..5ec96a75 100644 --- a/packages/datastore-core/src/index.ts +++ b/packages/datastore-core/src/index.ts @@ -1,3 +1,66 @@ +/** + * @packageDocumentation + * + * Various Datastore implementations are available. + * + * ## Implementations + * + * - Mount: [`src/mount`](src/mount.ts) + * - Keytransform: [`src/keytransform`](src/keytransform.ts) + * - Sharding: [`src/sharding`](src/sharding.ts) + * - Tiered: [`src/tiered`](src/tirered.ts) + * - Namespace: [`src/namespace`](src/namespace.ts) + * - BlackHole: [`src/black-hole`](src/black-hole.ts) + * + * @example BaseDatastore + * + * An base store is made available to make implementing your own datastore easier: + * + * ```javascript + * import { BaseDatastore } from 'datastore-core' + * + * class MyDatastore extends BaseDatastore { + * constructor () { + * super() + * } + * + * async put (key, val) { + * // your implementation here + * } + * + * async get (key) { + * // your implementation here + * } + * + * // etc... + * } + * ``` + * + * See the [MemoryDatastore](./src/memory.js) for an example of how it is used. + * + * @example Wrapping Stores + * + * ```js + * import { Key } from 'interface-datastore' + * import { + * MemoryStore, + * MountStore + * } from 'datastore-core' + * + * const store = new MountStore({prefix: new Key('/a'), datastore: new MemoryStore()}) + * ``` + * + * @example BlackHoleDatastore + * + * A datastore that does not store any data. + * + * ```js + * import { BlackHoleDatastore } from 'datastore-core/black-hole' + * + * const store = new BlackHoleDatastore() + * ``` + */ + import * as Errors from './errors.js' import * as shard from './shard.js' import type { Key } from 'interface-datastore' @@ -17,11 +80,11 @@ export interface Shard { name: string param: number readonly _padding: string - fun: (s: string) => string - toString: () => string + fun(s: string): string + toString(): string } export interface KeyTransform { - convert: (key: Key) => Key - invert: (key: Key) => Key + convert(key: Key): Key + invert(key: Key): Key } diff --git a/packages/datastore-fs/README.md b/packages/datastore-fs/README.md index 3e40717b..6ea50496 100644 --- a/packages/datastore-fs/README.md +++ b/packages/datastore-fs/README.md @@ -1,5 +1,3 @@ -# datastore-fs - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,11 @@ > Datastore implementation with file system backend -## Table of contents - -- [Install](#install) -- [Usage](#usage) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) - -## Install +# About -```console -$ npm i datastore-fs -``` +A Datastore implementation with a file system backend. -## Usage +## Example ```js import { FsDatastore } from 'datastore-fs' @@ -29,18 +17,24 @@ import { FsDatastore } from 'datastore-fs' const store = new FsDatastore('path/to/store') ``` -## API Docs +# Install + +```console +$ npm i datastore-fs +``` + +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/datastore-fs/package.json b/packages/datastore-fs/package.json index 76c5122b..24687053 100644 --- a/packages/datastore-fs/package.json +++ b/packages/datastore-fs/package.json @@ -36,6 +36,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -145,7 +146,7 @@ }, "devDependencies": { "@types/mkdirp": "^2.0.0", - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-datastore-tests": "^5.0.0", "ipfs-utils": "^9.0.4" } diff --git a/packages/datastore-fs/src/index.ts b/packages/datastore-fs/src/index.ts index ed76a805..bd19b657 100644 --- a/packages/datastore-fs/src/index.ts +++ b/packages/datastore-fs/src/index.ts @@ -1,3 +1,17 @@ +/** + * @packageDocumentation + * + * A Datastore implementation with a file system backend. + * + * @example + * + * ```js + * import { FsDatastore } from 'datastore-fs' + * + * const store = new FsDatastore('path/to/store') + * ``` + */ + import fs from 'node:fs/promises' import path from 'node:path' import { promisify } from 'util' diff --git a/packages/datastore-idb/README.md b/packages/datastore-idb/README.md index ee98b412..52bdec2b 100644 --- a/packages/datastore-idb/README.md +++ b/packages/datastore-idb/README.md @@ -1,5 +1,3 @@ -# datastore-idb - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,25 @@ > Datastore implementation with IndexedDB backend. -## Table of contents +# About + +A Datastore implementation for browsers that stores data in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). + +## Example -- [Install](#install) - - [Browser ` ``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/datastore-idb/package.json b/packages/datastore-idb/package.json index 8efbf570..d9eb1db0 100644 --- a/packages/datastore-idb/package.json +++ b/packages/datastore-idb/package.json @@ -37,11 +37,11 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { - "sourceType": "module", "project": [ "tsconfig.json", "benchmarks/datastore-level/tsconfig.json" - ] + ], + "sourceType": "module" } }, "release": { @@ -145,7 +145,7 @@ "it-sort": "^3.0.1" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "datastore-core": "^9.0.0", "interface-datastore-tests": "^5.0.0" } diff --git a/packages/datastore-idb/src/index.ts b/packages/datastore-idb/src/index.ts index 8a582f79..8d50ee12 100644 --- a/packages/datastore-idb/src/index.ts +++ b/packages/datastore-idb/src/index.ts @@ -1,3 +1,17 @@ +/** + * @packageDocumentation + * + * A Datastore implementation for browsers that stores data in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). + * + * @example + * + * ```js + * import { IDBDatastore } from 'datastore-idb' + * + * const store = new IDBDatastore('path/to/store') + * ``` + */ + import { Errors, BaseDatastore } from 'datastore-core' import { openDB, deleteDB, type IDBPDatabase } from 'idb' import { type Batch, Key, type KeyQuery, type Pair, type Query } from 'interface-datastore' diff --git a/packages/datastore-level/README.md b/packages/datastore-level/README.md index 66b53723..c2a8674b 100644 --- a/packages/datastore-level/README.md +++ b/packages/datastore-level/README.md @@ -1,5 +1,3 @@ -# datastore-level - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,32 +5,13 @@ > Datastore implementation with level(up|down) backend -## Table of contents - -- [Install](#install) - - [Browser ` -``` +This module is targetted at Node.js. It is possible to use it in a browser but you should probably use IDBDatastore instead. -## Usage +## Example ```js import { LevelDatastore } from 'datastore-level' @@ -49,13 +28,13 @@ const memStore = new LevelDatastore( ) ``` -### Browser Shimming Leveldown +## Browser Shimming Leveldown `LevelStore` uses the `level` module to automatically use `level` if a modern bundler is used which can detect bundle targets based on the `pkg.browser` property in your `package.json`. If you are using a bundler that does not support `pkg.browser`, you will need to handle the shimming yourself, as was the case with versions of `LevelStore` 0.7.0 and earlier. -### Database names +## Database names `level-js@3` changed the database prefix from `IDBWrapper-` to `level-js-`, so please specify the old prefix if you wish to continue using databases created using `datastore-level` prior to `v0.12.0`. E.g. @@ -70,18 +49,32 @@ import browserStore = new LevelDatastore( More information: [https://github.com/Level/level-js/blob/master/UPGRADING.md#new-database-prefix](https://github.com/Level/level-js/blob/99831913e905d19e5f6dee56d512b7264fbed7bd/UPGRADING.md#new-database-prefix) -## API Docs +# Install + +```console +$ npm i datastore-level +``` + +## Browser ` +``` + +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/datastore-level/package.json b/packages/datastore-level/package.json index 17ed0a6a..c5671a5b 100644 --- a/packages/datastore-level/package.json +++ b/packages/datastore-level/package.json @@ -38,6 +38,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -150,7 +151,7 @@ "level": "^8.0.0" }, "devDependencies": { - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-datastore-tests": "^5.0.0", "ipfs-utils": "^9.0.4", "memory-level": "^1.0.0" diff --git a/packages/datastore-level/src/index.ts b/packages/datastore-level/src/index.ts index 25e9418e..66d8411a 100644 --- a/packages/datastore-level/src/index.ts +++ b/packages/datastore-level/src/index.ts @@ -1,3 +1,49 @@ +/** + * @packageDocumentation + * + * A Datastore implementation that uses a flavour of [Level](https://leveljs.org/) as a backend. + * + * This module is targetted at Node.js. It is possible to use it in a browser but you should probably use IDBDatastore instead. + * + * @example + * + * ```js + * import { LevelDatastore } from 'datastore-level' + * + * // Default using level as backend for node or the browser + * const store = new LevelDatastore('path/to/store') + * + * // another leveldown compliant backend like memory-level + * const memStore = new LevelDatastore( + * new MemoryLevel({ + * keyEncoding: 'utf8', + * valueEncoding: 'view' + * }) + * ) + * ``` + * + * ## Browser Shimming Leveldown + * + * `LevelStore` uses the `level` module to automatically use `level` if a modern bundler is used which can detect bundle targets based on the `pkg.browser` property in your `package.json`. + * + * If you are using a bundler that does not support `pkg.browser`, you will need to handle the shimming yourself, as was the case with versions of `LevelStore` 0.7.0 and earlier. + * + * ## Database names + * + * `level-js@3` changed the database prefix from `IDBWrapper-` to `level-js-`, so please specify the old prefix if you wish to continue using databases created using `datastore-level` prior to `v0.12.0`. E.g. + * + * ```javascript + * import leveljs from 'level-js' + * import browserStore = new LevelDatastore( + * new Level('my/db/name', { + * prefix: 'IDBWrapper-' + * }) + * }) + * ``` + * + * More information: [https://github.com/Level/level-js/blob/master/UPGRADING.md#new-database-prefix](https://github.com/Level/level-js/blob/99831913e905d19e5f6dee56d512b7264fbed7bd/UPGRADING.md#new-database-prefix) + */ + import { BaseDatastore, Errors } from 'datastore-core' import { type Batch, Key, type KeyQuery, type Pair, type Query } from 'interface-datastore' import filter from 'it-filter' @@ -215,7 +261,7 @@ export class LevelDatastore extends BaseDatastore { } } -async function * levelIteratorToIterator (li: AsyncIterable<[string, Uint8Array]> & { close: () => Promise }): AsyncIterable { +async function * levelIteratorToIterator (li: AsyncIterable<[string, Uint8Array]> & { close(): Promise }): AsyncIterable { for await (const [key, value] of li) { yield { key: new Key(key, false), value } } @@ -224,8 +270,8 @@ async function * levelIteratorToIterator (li: AsyncIterable<[string, Uint8Array] } interface OldLevelIterator { - next: (cb: (err: Error, key: string | Uint8Array | null, value: any) => void) => void - end: (cb: (err: Error) => void) => void + next(cb: (err: Error, key: string | Uint8Array | null, value: any) => void): void + end(cb: (err: Error) => void): void } function oldLevelIteratorToIterator (li: OldLevelIterator): AsyncIterable { diff --git a/packages/datastore-s3/README.md b/packages/datastore-s3/README.md index 7fa06ced..9a6a7ba3 100644 --- a/packages/datastore-s3/README.md +++ b/packages/datastore-s3/README.md @@ -1,5 +1,3 @@ -# datastore-s3 - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,32 +5,11 @@ > IPFS datastore implementation backed by s3 -## Table of contents - -- [Install](#install) - - [Browser ` -``` +A Datastore implementation that stores data on Amazon S3. -## Usage +## Example - Quickstart If the flag `createIfMissing` is not set or is false, then the bucket must be created prior to using datastore-s3. Please see the AWS docs for information on how to configure the S3 instance. A bucket name is required to be set at the s3 instance level, see the below example. @@ -47,26 +24,40 @@ const store = new S3Datastore('.ipfs/datastore', { }) ``` -### Create a Repo +## Example -See [examples/full-s3-repo](./examples/full-s3-repo) for how to quickly create an S3 backed repo using the `createRepo` convenience function. +```ts +Using with Helia -### Examples +See [examples/helia](./examples/helia) for a full example of how to use Helia with an S3 backed datastore. +``` + +# Install + +```console +$ npm i datastore-s3 +``` -You can see examples of S3 backed ipfs in the [examples folder](examples/) +## Browser ` +``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/datastore-s3/package.json b/packages/datastore-s3/package.json index da580d6c..f9fc2b99 100644 --- a/packages/datastore-s3/package.json +++ b/packages/datastore-s3/package.json @@ -35,6 +35,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -148,7 +149,7 @@ }, "devDependencies": { "@types/sinon": "^10.0.15", - "aegir": "^40.0.8", + "aegir": "^41.1.9", "interface-datastore-tests": "^5.0.0", "p-defer": "^4.0.0", "sinon": "^15.0.2" diff --git a/packages/datastore-s3/src/index.ts b/packages/datastore-s3/src/index.ts index b3829546..d072898a 100644 --- a/packages/datastore-s3/src/index.ts +++ b/packages/datastore-s3/src/index.ts @@ -1,3 +1,28 @@ +/** + * @packageDocumentation + * + * A Datastore implementation that stores data on Amazon S3. + * + * @example Quickstart + * + * If the flag `createIfMissing` is not set or is false, then the bucket must be created prior to using datastore-s3. Please see the AWS docs for information on how to configure the S3 instance. A bucket name is required to be set at the s3 instance level, see the below example. + * + * ```js + * import S3 from 'aws-sdk/clients/s3.js' + * import { S3Datastore } from 'datastore-s3' + * + * const s3Instance = new S3({ params: { Bucket: 'my-ipfs-bucket' } }) + * const store = new S3Datastore('.ipfs/datastore', { + * s3: s3Instance + * createIfMissing: false + * }) + * ``` + * + * @example Using with Helia + * + * See [examples/helia](./examples/helia) for a full example of how to use Helia with an S3 backed datastore. + */ + import { PutObjectCommand, CreateBucketCommand, diff --git a/packages/interface-blockstore-tests/README.md b/packages/interface-blockstore-tests/README.md index b70ea886..bd7f6239 100644 --- a/packages/interface-blockstore-tests/README.md +++ b/packages/interface-blockstore-tests/README.md @@ -1,5 +1,3 @@ -# interface-blockstore-tests - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,11 @@ > Compliance tests for the blockstore interface -## Table of contents - -- [Install](#install) -- [Usage](#usage) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) - -## Install +# About -```console -$ npm i interface-blockstore-tests -``` +A test suite that ensures a given implementation implements the Blockstore interface properly. -## Usage +## Example ```js const MyBlockstore from './path/to/my-blockstore') @@ -39,18 +27,24 @@ describe('MyBlockstore', () => { }) ``` -## API Docs +# Install + +```console +$ npm i interface-blockstore-tests +``` + +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/interface-blockstore-tests/package.json b/packages/interface-blockstore-tests/package.json index a3572734..97872e2e 100644 --- a/packages/interface-blockstore-tests/package.json +++ b/packages/interface-blockstore-tests/package.json @@ -34,6 +34,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -137,6 +138,6 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" } } diff --git a/packages/interface-blockstore-tests/src/index.ts b/packages/interface-blockstore-tests/src/index.ts index 697998e1..69a77146 100644 --- a/packages/interface-blockstore-tests/src/index.ts +++ b/packages/interface-blockstore-tests/src/index.ts @@ -1,5 +1,29 @@ /* eslint-env mocha */ +/** + * @packageDocumentation + * + * A test suite that ensures a given implementation implements the Blockstore interface properly. + * + * @example + * + * ```js + * const MyBlockstore from './path/to/my-blockstore') + * const suite from 'interface-blockstore-tests') + * + * describe('MyBlockstore', () => { + * describe('interface-blockstore compliance tests', () => { + * suite({ + * setup () { + * return new MyBlockstore() + * }, + * teardown () {} + * }) + * }) + * }) + * ``` + */ + import { expect } from 'aegir/chai' import all from 'it-all' import drain from 'it-drain' @@ -25,8 +49,8 @@ async function getKeyValuePairs (count: number): Promise { } export interface InterfaceBlockstoreTest { - setup: () => B | Promise - teardown: (store: B) => void | Promise + setup(): B | Promise + teardown(store: B): void | Promise } export function interfaceBlockstoreTests (test: InterfaceBlockstoreTest): void { diff --git a/packages/interface-blockstore/README.md b/packages/interface-blockstore/README.md index 0d3fcf8f..0986e458 100644 --- a/packages/interface-blockstore/README.md +++ b/packages/interface-blockstore/README.md @@ -1,5 +1,3 @@ -# interface-blockstore - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,19 +5,11 @@ > An interface for storing and retrieving blocks -## Table of contents - -- [Install](#install) -- [Implementations](#implementations) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) +# About -## Install +A Blockstore is a key/value database that lets use CIDs to store/retrieve binary blobs. -```console -$ npm i interface-blockstore -``` +It is used by IPFS to store/retrieve the block that a given CID resolves to. ## Implementations @@ -29,18 +19,24 @@ $ npm i interface-blockstore - Memory: [`blockstore-core/memory`](https://github.com/ipfs/js-stores/blob/main/packages/blockstore-core/src/memory.ts) - S3: [`blockstore-s3`](https://github.com/ipfs/js-stores/tree/main/packages/blockstore-s3) -## API Docs +# Install + +```console +$ npm i interface-blockstore +``` + +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/interface-blockstore/package.json b/packages/interface-blockstore/package.json index 203d48b4..39e1dd7d 100644 --- a/packages/interface-blockstore/package.json +++ b/packages/interface-blockstore/package.json @@ -28,6 +28,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -127,6 +128,6 @@ "multiformats": "^12.0.1" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" } } diff --git a/packages/interface-blockstore/src/index.ts b/packages/interface-blockstore/src/index.ts index 68662013..17fbdc96 100644 --- a/packages/interface-blockstore/src/index.ts +++ b/packages/interface-blockstore/src/index.ts @@ -4,6 +4,22 @@ // we are using it as an intersection type - see the aside at the bottom: // https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-675156492 +/** + * @packageDocumentation + * + * A Blockstore is a key/value database that lets use CIDs to store/retrieve binary blobs. + * + * It is used by IPFS to store/retrieve the block that a given CID resolves to. + * + * ## Implementations + * + * - File System: [`blockstore-fs`](https://github.com/ipfs/js-stores/tree/main/packages/blockstore-fs) + * - IndexedDB: [`blockstore-idb`](https://github.com/ipfs/js-stores/blob/main/packages/blockstore-idb) + * - level: [`blockstore-level`](https://github.com/ipfs/js-stores/tree/main/packages/blockstore-level) (supports any levelup compatible backend) + * - Memory: [`blockstore-core/memory`](https://github.com/ipfs/js-stores/blob/main/packages/blockstore-core/src/memory.ts) + * - S3: [`blockstore-s3`](https://github.com/ipfs/js-stores/tree/main/packages/blockstore-s3) + */ + import type { AbortOptions, AwaitIterable, @@ -34,5 +50,5 @@ DeleteOptionsExtension = {}, DeleteManyOptionsExtension = {}> extends Store AwaitIterable + getAll(options?: AbortOptions & GetAllOptionsExtension): AwaitIterable } diff --git a/packages/interface-datastore-tests/README.md b/packages/interface-datastore-tests/README.md index 4b488f6c..7befb1ef 100644 --- a/packages/interface-datastore-tests/README.md +++ b/packages/interface-datastore-tests/README.md @@ -1,5 +1,3 @@ -# interface-datastore-tests - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,21 +5,11 @@ > Compliance tests for the datastore interface -## Table of contents - -- [Install](#install) -- [Usage](#usage) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) - -## Install +# About -```console -$ npm i interface-datastore-tests -``` +A test suite that ensures a given implementation implements the Datastore interface properly. -## Usage +## Example ```js const MyDatastore from './path/to/my-datastore') @@ -39,18 +27,24 @@ describe('MyDatastore', () => { }) ``` -## API Docs +# Install + +```console +$ npm i interface-datastore-tests +``` + +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/interface-datastore-tests/package.json b/packages/interface-datastore-tests/package.json index 0174fd83..b1505abf 100644 --- a/packages/interface-datastore-tests/package.json +++ b/packages/interface-datastore-tests/package.json @@ -34,6 +34,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -138,6 +139,6 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" } } diff --git a/packages/interface-datastore-tests/src/index.ts b/packages/interface-datastore-tests/src/index.ts index 3f47501c..8076c214 100644 --- a/packages/interface-datastore-tests/src/index.ts +++ b/packages/interface-datastore-tests/src/index.ts @@ -1,5 +1,29 @@ /* eslint-env mocha */ +/** + * @packageDocumentation + * + * A test suite that ensures a given implementation implements the Datastore interface properly. + * + * @example + * + * ```js + * const MyDatastore from './path/to/my-datastore') + * const suite from 'interface-datastore-tests') + * + * describe('MyDatastore', () => { + * describe('interface-datastore compliance tests', () => { + * suite({ + * setup () { + * return new MyDatastore() + * }, + * teardown () {} + * }) + * }) + * }) + * ``` + */ + import { expect } from 'aegir/chai' import { type Datastore, Key, type KeyQueryFilter, type KeyQueryOrder, type Pair, type QueryFilter, type QueryOrder } from 'interface-datastore' import { randomBytes } from 'iso-random-stream' @@ -9,8 +33,8 @@ import length from 'it-length' import { fromString as uint8ArrayFromString } from 'uint8arrays/from-string' export interface InterfacDatastoreTest { - setup: () => D | Promise - teardown: (store: D) => void | Promise + setup(): D | Promise + teardown(store: D): void | Promise } export function interfaceDatastoreTests (test: InterfacDatastoreTest): void { diff --git a/packages/interface-datastore/README.md b/packages/interface-datastore/README.md index 6e869940..69454128 100644 --- a/packages/interface-datastore/README.md +++ b/packages/interface-datastore/README.md @@ -1,5 +1,3 @@ -# interface-datastore - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,27 +5,13 @@ > datastore interface -## Table of contents - -- [Install](#install) - - [Browser ` ``` -## Implementations - -- Backed Implementations - - File System: [`datastore-fs`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-fs) - - IndexedDB: [`datastore-idb`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-idb) - - level: [`datastore-level`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-level) (supports any levelup compatible backend) - - Memory: [`datastore-core/memory`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/memory.ts) - - S3: [`datastore-s3`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-s3) -- Wrapper Implementations - - Keytransform: [`datstore-core/src/keytransform`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/keytransform.ts) - - Mount: [`datastore-core/src/mount`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/mount.ts) - - Namespace: [`datastore-core/src/namespace`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/namespace.ts) - - Sharding: [`datastore-core/src/sharding`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/sharding.ts) - - Tiered: [`datstore-core/src/tiered`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/tiered.ts) - -If you want the same functionality as [go-ds-flatfs](https://github.com/ipfs/go-ds-flatfs), use sharding with fs. - -```js -import FsStore from 'datastore-fs' -import { ShardingDataStore, shard } from 'datastore-core' - -const fs = new FsStore('path/to/store') - -// flatfs now works like go-flatfs -const flatfs = await ShardingStore.createOrOpen(fs, new shard.NextToLast(2)) -``` - -### Test suite - -Available via the [`interface-datastore-tests`](https://npmjs.com/package/interface-datastore-tests) module - -```js -import { interfaceDatastoreTests } from 'interface-datastore-tests' - -describe('mystore', () => { - interfaceDatastoreTests({ - async setup () { - return instanceOfMyStore - }, - async teardown () { - // cleanup resources - } - }) -}) -``` - -### Aborting requests - -Most API methods accept an \[AbortSignal]\[] as part of an options object. Implementations may listen for an `abort` event emitted by this object, or test the `signal.aborted` property. When received implementations should tear down any long-lived requests or resources created. - -### Concurrency - -The streaming `(put|get|delete)Many` methods are intended to be used with modules such as [it-parallel-batch](https://www.npmjs.com/package/it-parallel-batch) to allow calling code to control levels of parallelisation. The batching method ensures results are returned in the correct order, but interface implementations should be thread safe. - -```js -import batch from 'it-parallel-batch' -const source = [{ - key: .., - value: .. -}] - -// put values into the datastore concurrently, max 10 at a time -for await (const { key, data } of batch(store.putMany(source), 10)) { - console.info(`Put ${key}`) -} -``` - -### Keys - -To allow a better abstraction on how to address values, there is a `Key` class which is used as identifier. It's easy to create a key from a `Uint8Array` or a `string`. - -```js -const a = new Key('a') -const b = new Key(new Uint8Array([0, 1, 2, 3])) -``` - -The key scheme is inspired by file systems and Google App Engine key model. Keys are meant to be unique across a system. They are typically hierarchical, incorporating more and more specific namespaces. Thus keys can be deemed 'children' or 'ancestors' of other keys: - -- `new Key('/Comedy')` -- `new Key('/Comedy/MontyPython')` - -Also, every namespace can be parameterized to embed relevant object information. For example, the Key `name` (most specific namespace) could include the object type: - -- `new Key('/Comedy/MontyPython/Actor:JohnCleese')` -- `new Key('/Comedy/MontyPython/Sketch:CheeseShop')` -- `new Key('/Comedy/MontyPython/Sketch:CheeseShop/Character:Mousebender')` - -## API - - - -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). @@ -148,25 +41,3 @@ Please be aware that all interactions related to this repo are subject to the IP Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. [![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) - -[Key]: #Keys - -[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object - -[Uint8Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array - -[AbortSignal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal - -[AsyncIterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator - -[AsyncIterable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols - -[String]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String - -[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array - -[Function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function - -[Number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number - -[Boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/packages/interface-datastore/package.json b/packages/interface-datastore/package.json index ba6b8816..4c9e2a30 100644 --- a/packages/interface-datastore/package.json +++ b/packages/interface-datastore/package.json @@ -54,6 +54,7 @@ "eslintConfig": { "extends": "ipfs", "parserOptions": { + "project": true, "sourceType": "module" } }, @@ -161,6 +162,6 @@ "uint8arrays": "^4.0.2" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" } } diff --git a/packages/interface-datastore/src/index.ts b/packages/interface-datastore/src/index.ts index 251495c3..1ee4a57d 100644 --- a/packages/interface-datastore/src/index.ts +++ b/packages/interface-datastore/src/index.ts @@ -4,6 +4,104 @@ // we are using it as an intersection type - see the aside at the bottom: // https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-675156492 +/** + * @packageDocumentation + * + * A Datastore is a key/value database that lets store/retrieve binary blobs using namespaced Keys. + * + * It is used by IPFS to store/retrieve arbitrary metadata needed to run the node - DHT provider records, signed peer records, etc. + * + * ## Backed Implementations + * + * - File System: [`datastore-fs`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-fs) + * - IndexedDB: [`datastore-idb`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-idb) + * - level: [`datastore-level`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-level) (supports any levelup compatible backend) + * - Memory: [`datastore-core/memory`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/memory.ts) + * - S3: [`datastore-s3`](https://github.com/ipfs/js-stores/tree/main/packages/datastore-s3) + * + * ## Wrapper Implementations + * + * - Keytransform: [`datstore-core/src/keytransform`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/keytransform.ts) + * - Mount: [`datastore-core/src/mount`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/mount.ts) + * - Namespace: [`datastore-core/src/namespace`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/namespace.ts) + * - Sharding: [`datastore-core/src/sharding`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/sharding.ts) + * - Tiered: [`datstore-core/src/tiered`](https://github.com/ipfs/js-stores/blob/main/packages/datastore-core/src/tiered.ts) + * + * If you want the same functionality as [go-ds-flatfs](https://github.com/ipfs/go-ds-flatfs), use sharding with fs. + * + * @example + * + * ```js + * import FsStore from 'datastore-fs' + * import { ShardingDataStore, shard } from 'datastore-core' + * + * const fs = new FsStore('path/to/store') + * + * // flatfs now works like go-flatfs + * const flatfs = await ShardingStore.createOrOpen(fs, new shard.NextToLast(2)) + * ``` + * + * ### Test suite + * + * Available via the [`interface-datastore-tests`](https://npmjs.com/package/interface-datastore-tests) module + * + * ```js + * import { interfaceDatastoreTests } from 'interface-datastore-tests' + * + * describe('mystore', () => { + * interfaceDatastoreTests({ + * async setup () { + * return instanceOfMyStore + * }, + * async teardown () { + * // cleanup resources + * } + * }) + * }) + * ``` + * + * ### Aborting requests + * + * Most API methods accept an \[AbortSignal]\[] as part of an options object. Implementations may listen for an `abort` event emitted by this object, or test the `signal.aborted` property. When received implementations should tear down any long-lived requests or resources created. + * + * ### Concurrency + * + * The streaming `(put|get|delete)Many` methods are intended to be used with modules such as [it-parallel-batch](https://www.npmjs.com/package/it-parallel-batch) to allow calling code to control levels of parallelisation. The batching method ensures results are returned in the correct order, but interface implementations should be thread safe. + * + * ```js + * import batch from 'it-parallel-batch' + * const source = [{ + * key: .., + * value: .. + * }] + * + * // put values into the datastore concurrently, max 10 at a time + * for await (const { key, data } of batch(store.putMany(source), 10)) { + * console.info(`Put ${key}`) + * } + * ``` + * + * ### Keys + * + * To allow a better abstraction on how to address values, there is a `Key` class which is used as identifier. It's easy to create a key from a `Uint8Array` or a `string`. + * + * ```js + * const a = new Key('a') + * const b = new Key(new Uint8Array([0, 1, 2, 3])) + * ``` + * + * The key scheme is inspired by file systems and Google App Engine key model. Keys are meant to be unique across a system. They are typically hierarchical, incorporating more and more specific namespaces. Thus keys can be deemed 'children' or 'ancestors' of other keys: + * + * - `new Key('/Comedy')` + * - `new Key('/Comedy/MontyPython')` + * + * Also, every namespace can be parameterized to embed relevant object information. For example, the Key `name` (most specific namespace) could include the object type: + * + * - `new Key('/Comedy/MontyPython/Actor:JohnCleese')` + * - `new Key('/Comedy/MontyPython/Sketch:CheeseShop')` + * - `new Key('/Comedy/MontyPython/Sketch:CheeseShop/Character:Mousebender')` + */ + import { Key } from './key.js' import type { Await, @@ -18,9 +116,9 @@ export interface Pair { } export interface Batch { - put: (key: Key, value: Uint8Array) => void - delete: (key: Key) => void - commit: (options?: AbortOptions & BatchOptionsExtension) => Await + put(key: Key, value: Uint8Array): void + delete(key: Key): void + commit(options?: AbortOptions & BatchOptionsExtension): Await } export interface Datastore Batch + batch(): Batch /** * Query the datastore. @@ -63,7 +161,7 @@ BatchOptionsExtension = {} * console.log('ALL THE VALUES', list) * ``` */ - query: (query: Query, options?: AbortOptions & QueryOptionsExtension) => AwaitIterable + query(query: Query, options?: AbortOptions & QueryOptionsExtension): AwaitIterable /** * Query the datastore. @@ -78,7 +176,7 @@ BatchOptionsExtension = {} * console.log('ALL THE KEYS', key) * ``` */ - queryKeys: (query: KeyQuery, options?: AbortOptions & QueryKeysOptionsExtension) => AwaitIterable + queryKeys(query: KeyQuery, options?: AbortOptions & QueryKeysOptionsExtension): AwaitIterable } export interface QueryFilter { (item: Pair): boolean } diff --git a/packages/interface-store/README.md b/packages/interface-store/README.md index 06915f4d..0a7edca7 100644 --- a/packages/interface-store/README.md +++ b/packages/interface-store/README.md @@ -1,5 +1,3 @@ -# interface-store - [![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech) [![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech) [![codecov](https://img.shields.io/codecov/c/github/ipfs/js-stores.svg?style=flat-square)](https://codecov.io/gh/ipfs/js-stores) @@ -7,31 +5,28 @@ > A generic interface for storing and retrieving data -## Table of contents +# About -- [Install](#install) -- [API Docs](#api-docs) -- [License](#license) -- [Contribute](#contribute) +An abstraction of the Datastore/Blockstore codebases. -## Install +# Install ```console $ npm i interface-store ``` -## API Docs +# API Docs - -## License +# License Licensed under either of - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / ) - MIT ([LICENSE-MIT](LICENSE-MIT) / ) -## Contribute +# Contribute Contributions welcome! Please check out [the issues](https://github.com/ipfs/js-stores/issues). diff --git a/packages/interface-store/package.json b/packages/interface-store/package.json index 28e062d9..8aa1fcfe 100644 --- a/packages/interface-store/package.json +++ b/packages/interface-store/package.json @@ -32,7 +32,10 @@ "dist" ], "eslintConfig": { - "extends": "ipfs" + "extends": "ipfs", + "parserOptions": { + "project": true + } }, "release": { "branches": [ @@ -127,6 +130,6 @@ "dep-check": "aegir dep-check" }, "devDependencies": { - "aegir": "^40.0.8" + "aegir": "^41.1.9" } } diff --git a/packages/interface-store/src/index.ts b/packages/interface-store/src/index.ts index ff67c003..5d84d4ca 100644 --- a/packages/interface-store/src/index.ts +++ b/packages/interface-store/src/index.ts @@ -4,6 +4,12 @@ // we are using it as an intersection type - see the aside at the bottom: // https://github.com/typescript-eslint/typescript-eslint/issues/2063#issuecomment-675156492 +/** + * @packageDocumentation + * + * An abstraction of the Datastore/Blockstore codebases. + */ + /** * An iterable or async iterable of values */ @@ -39,7 +45,7 @@ export interface Store Await + has(key: Key, options?: AbortOptions & HasOptionsExtension): Await /** * Store the passed value under the passed key @@ -50,7 +56,7 @@ export interface Store Await + put(key: Key, val: Value, options?: AbortOptions & PutOptionsExtension): Await /** * Store the given key/value pairs @@ -64,10 +70,10 @@ export interface Store, options?: AbortOptions & PutManyOptionsExtension - ) => AwaitIterable + ): AwaitIterable /** * Retrieve the value stored under the given key @@ -79,7 +85,7 @@ export interface Store got content: datastore * ``` */ - get: (key: Key, options?: AbortOptions & GetOptionsExtension) => Await + get(key: Key, options?: AbortOptions & GetOptionsExtension): Await /** * Retrieve values for the passed keys @@ -92,10 +98,10 @@ export interface Store, options?: AbortOptions & GetManyOptionsExtension - ) => AwaitIterable + ): AwaitIterable /** * Remove the record for the passed key @@ -107,7 +113,7 @@ export interface Store Await + delete(key: Key, options?: AbortOptions & DeleteOptionsExtension): Await /** * Remove values for the passed keys @@ -122,8 +128,8 @@ export interface Store, options?: AbortOptions & DeleteManyOptionsExtension - ) => AwaitIterable + ): AwaitIterable } diff --git a/packages/interface-store/typedoc.json b/packages/interface-store/typedoc.json new file mode 100644 index 00000000..f599dc72 --- /dev/null +++ b/packages/interface-store/typedoc.json @@ -0,0 +1,5 @@ +{ + "entryPoints": [ + "./src/index.ts" + ] +}