deps(dev): bump aegir from 40.0.13 to 41.1.9 (ipfs#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](ipfs/aegir@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] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: achingbrain <alex@achingbrain.net>
tabcat · Jul 26, 2024 · 5e0d88a · 5e0d88a
1 parent 12d5d8e
commit 5e0d88a
Show file tree

Hide file tree

Showing 54 changed files with 760 additions and 628 deletions.
diff --git a/.github/workflows/semantic-pull-request.yml 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
@@ -1,21 +1,11 @@
-# stores <!-- omit in toc -->
-
 [![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)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/js-stores/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/js-stores/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > Blockstores and datastores used by IP-JS internals
 
-## Table of contents <!-- omit in toc -->
-
-- [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
 
 - <https://ipfs.github.io/js-stores>
 
-## License
+# License
 
 Licensed under either of
 
 - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/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
@@ -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
@@ -1,117 +1,36 @@
-# blockstore-core <!-- omit in toc -->
-
 [![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)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/js-stores/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/js-stores/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > Contains various implementations of the API contract described in interface-blockstore
 
-## Table of contents <!-- omit in toc -->
-
-- [Install](#install)
-  - [Browser `<script>` tag](#browser-script-tag)
-- [Implementations](#implementations)
-- [Usage](#usage)
-  - [BaseBlockstore](#baseblockstore)
-  - [MemoryBlockstore](#memoryblockstore)
-  - [BlackHoleBlockstore](#blackholeblockstore)
-  - [TieredBlockstore](#tieredblockstore)
-- [API Docs](#api-docs)
-- [License](#license)
-- [Contribute](#contribute)
-
-## Install
+# Install
 
 ```console
 $ npm i blockstore-core
 ```
 
-### Browser `<script>` tag
+## Browser `<script>` tag
 
 Loading this module through a script tag will make it's exports available as `BlockstoreCore` in the global namespace.
 
 ```html
 <script src="https://unpkg.com/blockstore-core/dist/index.min.js"></script>
 ```
 
-## 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
 
 - <https://ipfs.github.io/js-stores/modules/blockstore_core.html>
 
-## License
+# License
 
 Licensed under either of
 
 - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/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
@@ -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
@@ -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
@@ -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
@@ -1,46 +1,28 @@
-# blockstore-fs <!-- omit in toc -->
-
 [![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)
 [![CI](https://img.shields.io/github/actions/workflow/status/ipfs/js-stores/js-test-and-release.yml?branch=main\&style=flat-square)](https://github.com/ipfs/js-stores/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
 
 > Blockstore implementation with file system backend
 
-## Table of contents <!-- omit in toc -->
-
-- [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
 
 - <https://ipfs.github.io/js-stores/modules/blockstore_fs.html>
 
-## License
+# License
 
 Licensed under either of
 
 - Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
 - MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/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
@@ -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
@@ -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
@@ -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 {