From e004550b6c6abb8e639ba8247fc7fd56f3785c98 Mon Sep 17 00:00:00 2001
From: Sean Zellmer <sean@lejeunerenard.com>
Date: Fri, 5 Jun 2026 10:26:42 -0500
Subject: [PATCH 1/7] 7.10.1

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 429d645..202fe25 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "corestore",
-  "version": "7.10.0",
+  "version": "7.10.1",
   "description": "A Hypercore factory that simplifies managing collections of cores.",
   "main": "index.js",
   "files": [

From 6b4926ca8b4d8cde3fb36c1fe2611ff3aebb6990 Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 30 Jun 2026 16:01:34 -0300
Subject: [PATCH 2/7] chore: add JSDoc to public API

Generated JSDoc (descriptions, typed @param/@returns, @throws, and @typedef
option shapes) for the public API surface.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 index.js      | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/notify.js |   3 +
 2 files changed, 186 insertions(+)

diff --git a/index.js b/index.js
index 2910281..21fbd1a 100644
--- a/index.js
+++ b/index.js
@@ -13,6 +13,17 @@ const GroupNotifyHandle = require('./lib/notify.js')
 const [NS] = crypto.namespace('corestore', 1)
 const DEFAULT_NAMESPACE = b4a.alloc(32) // This is meant to be 32 0-bytes
 
+/**
+ * Options for the {@link Corestore} constructor. Any other options are
+ * forwarded to the underlying `hypercore-storage` instance.
+ * @typedef {Object} CorestoreOptions
+ * @property {Buffer} [primaryKey] - The 32-byte master key from which all writable named cores are derived. Generated and persisted automatically when omitted.
+ * @property {boolean} [writable=true] - Set to `false` to open the store read-only; loaded cores default to read-only too.
+ * @property {boolean} [readOnly=false] - Open the backing storage in read-only mode.
+ * @property {boolean} [active=true] - Whether loaded cores are automatically attached to active replication streams.
+ * @property {boolean} [unsafe=false] - Acknowledge that passing `primaryKey` directly is unsafe; required when `primaryKey` is set on a root store.
+ */
+
 class StreamTracker {
   constructor() {
     this.records = []
@@ -233,10 +244,26 @@ class FindingPeers {
 }
 
 class Corestore extends ReadyResource {
+  /**
+   * Create a new Corestore instance.
+   * @param {string|object} storage - can be either a `hypercore-storage` instance or a string.
+   * @param {CorestoreOptions} [opts] - Store options.
+   * @throws {ASSERTION} if `primaryKey` is set on a root store without `unsafe: true`.
+   * @example
+   * {
+   *   primaryKey: null, // The primary key to use as the master key for key derivation.
+   *   writable: true,
+   * }
+   */
   constructor(storage, opts = {}) {
     super()
 
     this.root = opts.root || null
+    /**
+     * The backing storage adapter used for aliases, seeds, and Hypercore data
+     * files.
+     * @type {object}
+     */
     this.storage = this.root
       ? this.root.storage
       : Hypercore.defaultStorage(storage, {
@@ -249,12 +276,31 @@ class Corestore extends ReadyResource {
     this.cores = this.root ? this.root.cores : new CoreTracker()
     this.sessions = new SessionTracker()
     this.corestores = this.root ? this.root.corestores : new Set()
+    /**
+     * `true` when the store was opened without write access.
+     * @type {boolean}
+     */
     this.readOnly = opts.writable === false || !!opts.readOnly
     this.globalCache = this.root ? this.root.globalCache : opts.globalCache || null
+    /**
+     * The 32-byte primary key used to deterministically derive writable named
+     * cores and namespaced key pairs.
+     * @type {Buffer}
+     */
     this.primaryKey = this.root ? this.root.primaryKey : opts.primaryKey || null
     this.ns = opts.namespace || DEFAULT_NAMESPACE
+    /**
+     * The Hypercore manifest version used when Corestore creates new writable
+     * cores.
+     * @type {number}
+     */
     this.manifestVersion = opts.manifestVersion || 1
     this.shouldSuspend = isAndroid ? !!opts.suspend : opts.suspend !== false
+    /**
+     * `true` when the store should automatically attach loaded cores to active
+     * replication streams.
+     * @type {boolean}
+     */
     this.active = opts.active !== false
 
     this.watchers = null
@@ -274,6 +320,17 @@ class Corestore extends ReadyResource {
     this.ready().catch(noop)
   }
 
+  /**
+   * Register a callback called when new Hypercores are opened. `core` is the
+   * internal core for the opened Hypercore. It can be used to create weak
+   * references to a Hypercore like so:
+   * @param {Function} fn - Callback invoked with the internal `core` each time a Hypercore is opened.
+   * @returns {void}
+   * @example
+   * store.watch(function (core) {
+   *   const weakCore = new Hypercore({ core, weak: true })
+   * })
+   */
   watch(fn) {
     if (this.watchers === null) {
       this.watchers = new Set()
@@ -283,6 +340,14 @@ class Corestore extends ReadyResource {
     this.watchers.add(fn)
   }
 
+  /**
+   * Unregister a callback used with `store.watch(callback)` so it no longer
+   * fires.
+   * @param {Function} fn - The callback previously passed to `store.watch()`.
+   * @returns {void}
+   * @example
+   * store.unwatch(onCore)
+   */
   unwatch(fn) {
     if (this.watchers === null) return
 
@@ -303,6 +368,14 @@ class Corestore extends ReadyResource {
     for (const handle of handles) handle.emit('update')
   }
 
+  /**
+   * Get a `handle` for updates from all `hypercore`s with the group `topic` set.
+   * @param {Buffer} topic - The 32-byte group topic to watch.
+   * @returns {GroupNotifyHandle} A handle that emits `update` when a core in the group changes.
+   * @example
+   * const handle = store.notifyGroup(topic)
+   * handle.on('update', () => console.log('group changed'))
+   */
   notifyGroup(topic) {
     const topicHex = b4a.toString(topic, 'hex')
     let handles = this._groupNotifiers.get(topicHex)
@@ -332,6 +405,14 @@ class Corestore extends ReadyResource {
     handle.index = -1
   }
 
+  /**
+   * A completion callback. Call it after the current peer-discovery pass
+   * finishes so pending update waits on loaded cores can unblock.
+   * @returns {Function} A `done` function to call once peer discovery has finished.
+   * @example
+   * const done = store.findingPeers()
+   * swarm.flush().then(done, done)
+   */
   findingPeers() {
     if (this._findingPeers === null) this._findingPeers = new FindingPeers()
     this._findingPeers.inc(this.sessions)
@@ -343,10 +424,25 @@ class Corestore extends ReadyResource {
     }
   }
 
+  /**
+   * An audit report describing the state of the backing store and any detected
+   * inconsistencies.
+   * @param {object} [opts] - Audit options (e.g. `dryRun`).
+   * @returns {AsyncGenerator<object>} Yields a result per core as it is audited.
+   * @example
+   * for await (const report of store.audit()) console.log(report)
+   */
   audit(opts = {}) {
     return auditStore(this, opts)
   }
 
+  /**
+   * Suspend the underlying storage for the Corestore.
+   * @param {object} [options] - Suspend options.
+   * @returns {Promise<void>} Resolves once the storage is flushed and suspended.
+   * @example
+   * await store.suspend()
+   */
   async suspend({ log = noop } = {}) {
     await log('Flushing db...')
     // If readOnly we don't need to flush
@@ -360,10 +456,24 @@ class Corestore extends ReadyResource {
     await log('Suspending db completed')
   }
 
+  /**
+   * Resume a suspended Corestore.
+   * @returns {Promise<void>} Resolves once the storage is resumed.
+   * @example
+   * await store.resume()
+   */
   resume() {
     return this.storage.resume()
   }
 
+  /**
+   * Create a new Corestore session. Closing a session will close all cores made
+   * from this session.
+   * @param {object} opts - Session options (forwarded to the new Corestore).
+   * @returns {Corestore} A new Corestore session sharing the same storage.
+   * @example
+   * const session = store.session()
+   */
   session(opts) {
     this._maybeClosed()
     const root = this.root || this
@@ -374,6 +484,19 @@ class Corestore extends ReadyResource {
     })
   }
 
+  /**
+   * Create a new namespaced Corestore session. Namespacing is useful if you're
+   * going to be sharing a single Corestore instance between many applications or
+   * components, as it prevents name collisions.
+   * @param {string|Buffer} name - Namespace name; combined with the current namespace to derive a new one.
+   * @param {object} opts - Session options (forwarded to the new Corestore).
+   * @returns {Corestore} A new namespaced Corestore session.
+   * @example
+   * const ns1 = store.namespace('a')
+   * const ns2 = ns1.namespace('b')
+   * const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores
+   * const core2 = ns2.get({ name: 'main' })
+   */
   namespace(name, opts) {
     return this.session({
       ...opts,
@@ -381,10 +504,26 @@ class Corestore extends ReadyResource {
     })
   }
 
+  /**
+   * Creates a discovery key stream of all cores within a namespace or all cores
+   * in general if no namespace is provided.
+   * @param {Buffer} [namespace] - to scope to; omit to list all cores.
+   * @returns {Readable} A stream of discovery keys.
+   * @example
+   * for await (const discoveryKey of store.list()) console.log(discoveryKey)
+   */
   list(namespace) {
     return this.storage.createDiscoveryKeyStream(namespace)
   }
 
+  /**
+   * The storage-layer auth metadata for that core, including manifest details
+   * when available.
+   * @param {Buffer} discoveryKey - Discovery key of the core to look up.
+   * @returns {Promise<object|null>} The auth record, or `null` if not stored.
+   * @example
+   * const auth = await store.getAuth(discoveryKey)
+   */
   getAuth(discoveryKey) {
     return this.storage.getAuth(discoveryKey)
   }
@@ -478,6 +617,22 @@ class Corestore extends ReadyResource {
     )
   }
 
+  /**
+   * Creates a replication stream that's capable of replicating all Hypercores
+   * that are managed by the Corestore, assuming the remote peer has the correct
+   * capabilities.
+   * @param {boolean|Stream} isInitiator - `true`/`false` to initiate, or an existing stream/connection to replicate over.
+   * @param {object} opts - Replication options, forwarded to the protocol stream.
+   * @returns {Stream} The replication stream.
+   * @example
+   * const swarm = new Hyperswarm()
+   *
+   * // join the relevant topic
+   * swarm.join(...)
+   *
+   * // simply pass the connection stream to corestore
+   * swarm.on('connection', (connection) => store.replicate(connection))
+   */
   replicate(isInitiator, opts) {
     this._maybeClosed()
 
@@ -517,6 +672,16 @@ class Corestore extends ReadyResource {
     }
   }
 
+  /**
+   * A reopened Hypercore whose manifest is converted into a static
+   * prologue-based manifest for the current data snapshot.
+   * @param {Hypercore} core - The source core to snapshot. Must have data.
+   * @param {object} opts - Options forwarded to `store.get()` for the new core.
+   * @returns {Promise<Hypercore>} The new static Hypercore.
+   * @throws if the core has no data to staticify.
+   * @example
+   * const staticCore = await store.staticify(core)
+   */
   async staticify(core, opts) {
     if (!this.opened) await this.ready()
     if (!core.opened) await core.ready()
@@ -561,6 +726,15 @@ class Corestore extends ReadyResource {
     return staticCore
   }
 
+  /**
+   * Loads a Hypercore, either by name (if the `name` option is provided), or
+   * from the provided key (if the first argument is a Buffer or String with
+   * hex/z32 key, or if the `key` options is set).
+   * @param {Buffer|string|object} opts - A key (Buffer/hex/z32 string), or an options object with `name`, `key`, or `discoveryKey` plus Hypercore options.
+   * @returns {Hypercore} A Hypercore session for the requested core.
+   * @example
+   * const core = store.get({ name: 'my-core' })
+   */
   get(opts) {
     this._maybeClosed()
 
@@ -618,6 +792,15 @@ class Corestore extends ReadyResource {
     return session
   }
 
+  /**
+   * Generate a key pair seeded with the Corestore's primary key using a `name`
+   * and a `ns` aka namespace. `ns` defaults to the current namespace.
+   * @param {string} name - to derive the key pair from.
+   * @param {Buffer} [ns]
+   * @returns {Promise<{publicKey: Buffer, secretKey: Buffer}>} The derived key pair.
+   * @example
+   * const keyPair = await store.createKeyPair('signer')
+   */
   async createKeyPair(name, ns = this.ns) {
     if (this.opened === false) await this.ready()
     return createKeyPair(this.primaryKey, ns, name)
diff --git a/lib/notify.js b/lib/notify.js
index 748a1c5..e31a9a5 100644
--- a/lib/notify.js
+++ b/lib/notify.js
@@ -17,6 +17,9 @@ class GroupNotifyHandle extends EventEmitter {
     })
   }
 
+  /**
+   * Destroys and unregisters the `handle` from its `store`.
+   */
   destroy() {
     this._store._removeGroupNotify(this)
   }

From 85ca47c72e9743263a5bfdc1f4a4167caa928fb9 Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 21 Jul 2026 16:55:29 -0300
Subject: [PATCH 3/7] Revert "chore: add JSDoc to public API"

This reverts commit 6b4926ca8b4d8cde3fb36c1fe2611ff3aebb6990.
---
 index.js      | 183 --------------------------------------------------
 lib/notify.js |   3 -
 2 files changed, 186 deletions(-)

diff --git a/index.js b/index.js
index 0f2b0b3..18a284c 100644
--- a/index.js
+++ b/index.js
@@ -13,17 +13,6 @@ const GroupNotifyHandle = require('./lib/notify.js')
 const [NS] = crypto.namespace('corestore', 1)
 const DEFAULT_NAMESPACE = b4a.alloc(32) // This is meant to be 32 0-bytes
 
-/**
- * Options for the {@link Corestore} constructor. Any other options are
- * forwarded to the underlying `hypercore-storage` instance.
- * @typedef {Object} CorestoreOptions
- * @property {Buffer} [primaryKey] - The 32-byte master key from which all writable named cores are derived. Generated and persisted automatically when omitted.
- * @property {boolean} [writable=true] - Set to `false` to open the store read-only; loaded cores default to read-only too.
- * @property {boolean} [readOnly=false] - Open the backing storage in read-only mode.
- * @property {boolean} [active=true] - Whether loaded cores are automatically attached to active replication streams.
- * @property {boolean} [unsafe=false] - Acknowledge that passing `primaryKey` directly is unsafe; required when `primaryKey` is set on a root store.
- */
-
 class StreamTracker {
   constructor() {
     this.records = []
@@ -244,26 +233,10 @@ class FindingPeers {
 }
 
 class Corestore extends ReadyResource {
-  /**
-   * Create a new Corestore instance.
-   * @param {string|object} storage - can be either a `hypercore-storage` instance or a string.
-   * @param {CorestoreOptions} [opts] - Store options.
-   * @throws {ASSERTION} if `primaryKey` is set on a root store without `unsafe: true`.
-   * @example
-   * {
-   *   primaryKey: null, // The primary key to use as the master key for key derivation.
-   *   writable: true,
-   * }
-   */
   constructor(storage, opts = {}) {
     super()
 
     this.root = opts.root || null
-    /**
-     * The backing storage adapter used for aliases, seeds, and Hypercore data
-     * files.
-     * @type {object}
-     */
     this.storage = this.root
       ? this.root.storage
       : Hypercore.defaultStorage(storage, {
@@ -276,31 +249,12 @@ class Corestore extends ReadyResource {
     this.cores = this.root ? this.root.cores : new CoreTracker()
     this.sessions = new SessionTracker()
     this.corestores = this.root ? this.root.corestores : new Set()
-    /**
-     * `true` when the store was opened without write access.
-     * @type {boolean}
-     */
     this.readOnly = opts.writable === false || !!opts.readOnly
     this.globalCache = this.root ? this.root.globalCache : opts.globalCache || null
-    /**
-     * The 32-byte primary key used to deterministically derive writable named
-     * cores and namespaced key pairs.
-     * @type {Buffer}
-     */
     this.primaryKey = this.root ? this.root.primaryKey : opts.primaryKey || null
     this.ns = opts.namespace || DEFAULT_NAMESPACE
-    /**
-     * The Hypercore manifest version used when Corestore creates new writable
-     * cores.
-     * @type {number}
-     */
     this.manifestVersion = opts.manifestVersion || 1
     this.shouldSuspend = isAndroid ? !!opts.suspend : opts.suspend !== false
-    /**
-     * `true` when the store should automatically attach loaded cores to active
-     * replication streams.
-     * @type {boolean}
-     */
     this.active = opts.active !== false
 
     this.watchers = null
@@ -320,17 +274,6 @@ class Corestore extends ReadyResource {
     this.ready().catch(noop)
   }
 
-  /**
-   * Register a callback called when new Hypercores are opened. `core` is the
-   * internal core for the opened Hypercore. It can be used to create weak
-   * references to a Hypercore like so:
-   * @param {Function} fn - Callback invoked with the internal `core` each time a Hypercore is opened.
-   * @returns {void}
-   * @example
-   * store.watch(function (core) {
-   *   const weakCore = new Hypercore({ core, weak: true })
-   * })
-   */
   watch(fn) {
     if (this.watchers === null) {
       this.watchers = new Set()
@@ -340,14 +283,6 @@ class Corestore extends ReadyResource {
     this.watchers.add(fn)
   }
 
-  /**
-   * Unregister a callback used with `store.watch(callback)` so it no longer
-   * fires.
-   * @param {Function} fn - The callback previously passed to `store.watch()`.
-   * @returns {void}
-   * @example
-   * store.unwatch(onCore)
-   */
   unwatch(fn) {
     if (this.watchers === null) return
 
@@ -368,14 +303,6 @@ class Corestore extends ReadyResource {
     for (const handle of handles) handle.emit('update', update)
   }
 
-  /**
-   * Get a `handle` for updates from all `hypercore`s with the group `topic` set.
-   * @param {Buffer} topic - The 32-byte group topic to watch.
-   * @returns {GroupNotifyHandle} A handle that emits `update` when a core in the group changes.
-   * @example
-   * const handle = store.notifyGroup(topic)
-   * handle.on('update', () => console.log('group changed'))
-   */
   notifyGroup(topic) {
     const topicHex = b4a.toString(topic, 'hex')
     let handles = this._groupNotifiers.get(topicHex)
@@ -405,14 +332,6 @@ class Corestore extends ReadyResource {
     handle.index = -1
   }
 
-  /**
-   * A completion callback. Call it after the current peer-discovery pass
-   * finishes so pending update waits on loaded cores can unblock.
-   * @returns {Function} A `done` function to call once peer discovery has finished.
-   * @example
-   * const done = store.findingPeers()
-   * swarm.flush().then(done, done)
-   */
   findingPeers() {
     if (this._findingPeers === null) this._findingPeers = new FindingPeers()
     this._findingPeers.inc(this.sessions)
@@ -424,25 +343,10 @@ class Corestore extends ReadyResource {
     }
   }
 
-  /**
-   * An audit report describing the state of the backing store and any detected
-   * inconsistencies.
-   * @param {object} [opts] - Audit options (e.g. `dryRun`).
-   * @returns {AsyncGenerator<object>} Yields a result per core as it is audited.
-   * @example
-   * for await (const report of store.audit()) console.log(report)
-   */
   audit(opts = {}) {
     return auditStore(this, opts)
   }
 
-  /**
-   * Suspend the underlying storage for the Corestore.
-   * @param {object} [options] - Suspend options.
-   * @returns {Promise<void>} Resolves once the storage is flushed and suspended.
-   * @example
-   * await store.suspend()
-   */
   async suspend({ log = noop } = {}) {
     await log('Flushing db...')
     // If readOnly we don't need to flush
@@ -456,24 +360,10 @@ class Corestore extends ReadyResource {
     await log('Suspending db completed')
   }
 
-  /**
-   * Resume a suspended Corestore.
-   * @returns {Promise<void>} Resolves once the storage is resumed.
-   * @example
-   * await store.resume()
-   */
   resume() {
     return this.storage.resume()
   }
 
-  /**
-   * Create a new Corestore session. Closing a session will close all cores made
-   * from this session.
-   * @param {object} opts - Session options (forwarded to the new Corestore).
-   * @returns {Corestore} A new Corestore session sharing the same storage.
-   * @example
-   * const session = store.session()
-   */
   session(opts) {
     this._maybeClosed()
     const root = this.root || this
@@ -484,19 +374,6 @@ class Corestore extends ReadyResource {
     })
   }
 
-  /**
-   * Create a new namespaced Corestore session. Namespacing is useful if you're
-   * going to be sharing a single Corestore instance between many applications or
-   * components, as it prevents name collisions.
-   * @param {string|Buffer} name - Namespace name; combined with the current namespace to derive a new one.
-   * @param {object} opts - Session options (forwarded to the new Corestore).
-   * @returns {Corestore} A new namespaced Corestore session.
-   * @example
-   * const ns1 = store.namespace('a')
-   * const ns2 = ns1.namespace('b')
-   * const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores
-   * const core2 = ns2.get({ name: 'main' })
-   */
   namespace(name, opts) {
     return this.session({
       ...opts,
@@ -504,26 +381,10 @@ class Corestore extends ReadyResource {
     })
   }
 
-  /**
-   * Creates a discovery key stream of all cores within a namespace or all cores
-   * in general if no namespace is provided.
-   * @param {Buffer} [namespace] - to scope to; omit to list all cores.
-   * @returns {Readable} A stream of discovery keys.
-   * @example
-   * for await (const discoveryKey of store.list()) console.log(discoveryKey)
-   */
   list(namespace) {
     return this.storage.createDiscoveryKeyStream(namespace)
   }
 
-  /**
-   * The storage-layer auth metadata for that core, including manifest details
-   * when available.
-   * @param {Buffer} discoveryKey - Discovery key of the core to look up.
-   * @returns {Promise<object|null>} The auth record, or `null` if not stored.
-   * @example
-   * const auth = await store.getAuth(discoveryKey)
-   */
   getAuth(discoveryKey) {
     return this.storage.getAuth(discoveryKey)
   }
@@ -617,22 +478,6 @@ class Corestore extends ReadyResource {
     )
   }
 
-  /**
-   * Creates a replication stream that's capable of replicating all Hypercores
-   * that are managed by the Corestore, assuming the remote peer has the correct
-   * capabilities.
-   * @param {boolean|Stream} isInitiator - `true`/`false` to initiate, or an existing stream/connection to replicate over.
-   * @param {object} opts - Replication options, forwarded to the protocol stream.
-   * @returns {Stream} The replication stream.
-   * @example
-   * const swarm = new Hyperswarm()
-   *
-   * // join the relevant topic
-   * swarm.join(...)
-   *
-   * // simply pass the connection stream to corestore
-   * swarm.on('connection', (connection) => store.replicate(connection))
-   */
   replicate(isInitiator, opts) {
     this._maybeClosed()
 
@@ -672,16 +517,6 @@ class Corestore extends ReadyResource {
     }
   }
 
-  /**
-   * A reopened Hypercore whose manifest is converted into a static
-   * prologue-based manifest for the current data snapshot.
-   * @param {Hypercore} core - The source core to snapshot. Must have data.
-   * @param {object} opts - Options forwarded to `store.get()` for the new core.
-   * @returns {Promise<Hypercore>} The new static Hypercore.
-   * @throws if the core has no data to staticify.
-   * @example
-   * const staticCore = await store.staticify(core)
-   */
   async staticify(core, opts) {
     if (!this.opened) await this.ready()
     if (!core.opened) await core.ready()
@@ -726,15 +561,6 @@ class Corestore extends ReadyResource {
     return staticCore
   }
 
-  /**
-   * Loads a Hypercore, either by name (if the `name` option is provided), or
-   * from the provided key (if the first argument is a Buffer or String with
-   * hex/z32 key, or if the `key` options is set).
-   * @param {Buffer|string|object} opts - A key (Buffer/hex/z32 string), or an options object with `name`, `key`, or `discoveryKey` plus Hypercore options.
-   * @returns {Hypercore} A Hypercore session for the requested core.
-   * @example
-   * const core = store.get({ name: 'my-core' })
-   */
   get(opts) {
     this._maybeClosed()
 
@@ -792,15 +618,6 @@ class Corestore extends ReadyResource {
     return session
   }
 
-  /**
-   * Generate a key pair seeded with the Corestore's primary key using a `name`
-   * and a `ns` aka namespace. `ns` defaults to the current namespace.
-   * @param {string} name - to derive the key pair from.
-   * @param {Buffer} [ns]
-   * @returns {Promise<{publicKey: Buffer, secretKey: Buffer}>} The derived key pair.
-   * @example
-   * const keyPair = await store.createKeyPair('signer')
-   */
   async createKeyPair(name, ns = this.ns) {
     if (this.opened === false) await this.ready()
     return createKeyPair(this.primaryKey, ns, name)
diff --git a/lib/notify.js b/lib/notify.js
index e31a9a5..748a1c5 100644
--- a/lib/notify.js
+++ b/lib/notify.js
@@ -17,9 +17,6 @@ class GroupNotifyHandle extends EventEmitter {
     })
   }
 
-  /**
-   * Destroys and unregisters the `handle` from its `store`.
-   */
   destroy() {
     this._store._removeGroupNotify(this)
   }

From f4a5134f16f8f195c3357da87f403c22119af8b5 Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 21 Jul 2026 16:57:28 -0300
Subject: [PATCH 4/7] chore: provide public API types via index.d.ts

Generated TypeScript declarations for the public API surface.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 index.d.ts   | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json |   3 +-
 2 files changed, 185 insertions(+), 1 deletion(-)
 create mode 100644 index.d.ts

diff --git a/index.d.ts b/index.d.ts
new file mode 100644
index 0000000..ddbe826
--- /dev/null
+++ b/index.d.ts
@@ -0,0 +1,183 @@
+// Type declarations for the holepunchto/corestore public API.
+
+export interface CorestoreOptions {
+  /** The primary key to use as the master key for key derivation. */
+  primaryKey?: any;
+  writable?: any;
+}
+
+/**
+ * `opts`
+ */
+export interface GroupNotifyHandleUpdateOptions {
+  /** What timestamp to start returning updates from. Default `0` returns all updates */
+  since?: any;
+  /** Flag to return updates in reverse order. Defaults to `true` so latest returned first */
+  reverse?: any;
+}
+
+export class Corestore {
+  /**
+   * Create a new Corestore instance.
+   * @param storage - `storage` can be either a `hypercore-storage` instance or a string.
+   */
+  constructor(storage: any, opts?: CorestoreOptions);
+
+  /**
+   * Register a callback called when new Hypercores are opened. `core` is the internal core for the opened Hypercore. It can be used to create weak references to a Hypercore like so:
+   */
+  watch(fn?: any): any;
+
+  /**
+   * Unregister a callback used with `store.watch(callback)` so it no longer fires.
+   */
+  unwatch(fn: any): any;
+
+  /**
+   * Get a `handle` for updates from all `hypercore`s with the group `topic` set.
+   */
+  notifyGroup(topic: any): any;
+
+  findingPeers(): any;
+
+  audit(opts?: any): any;
+
+  /**
+   * Suspend the underlying storage for the Corestore.
+   */
+  suspend(options?: any): Promise<void>;
+
+  /**
+   * Resume a suspended Corestore.
+   */
+  resume(): any;
+
+  /**
+   * Create a new Corestore session. Closing a session will close all cores made from this session.
+   */
+  session(opts: any): any;
+
+  /**
+   * Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.
+   */
+  namespace(name: any, opts: any): any;
+
+  /**
+   * Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.
+   */
+  list(namespace: any): any;
+
+  getAuth(discoveryKey: any): any;
+
+  /**
+   * Creates a replication stream that's capable of replicating all Hypercores that are managed by the Corestore, assuming the remote peer has the correct capabilities.
+   */
+  replicate(isInitiator: any, opts: any): any;
+
+  staticify(core: any, opts: any): Promise<void>;
+
+  /**
+   * Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).
+   */
+  get(opts: any): any;
+
+  /**
+   * Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.
+   * @param ns - `ns` defaults to the current namespace.
+   */
+  createKeyPair(name: any, ns?: any): Promise<void>;
+
+  ready(): Promise<void>;
+
+  /**
+   * Fully close this Corestore instance.
+   */
+  close(): Promise<void>;
+
+  readonly opened: any;
+
+  readonly closed: any;
+
+  emit(event: any, arg1?: any): any;
+
+  root: any;
+
+  storage: any;
+
+  streamTracker: any;
+
+  cores: any;
+
+  sessions: any;
+
+  corestores: any;
+
+  readOnly: any;
+
+  globalCache: any;
+
+  primaryKey: any;
+
+  ns: any;
+
+  manifestVersion: any;
+
+  shouldSuspend: any;
+
+  active: any;
+
+  watchers: any;
+
+  watchIndex: any;
+
+  /**
+   * The `group-active` event emits whenever an opened Hypercore in the store updates. The `topic` is the group topic the core belongs to.
+   */
+  on(event: 'group-active', listener: (topic: any, update: any) => void): this;
+}
+
+export class GroupNotifyHandle {
+  constructor(store: any, topic: any);
+
+  updates(opts: any): any;
+
+  /**
+   * Destroys and unregisters the `handle` from its `store`.
+   */
+  destroy(): any;
+
+  emit(event: any, arg1?: any): any;
+
+  index: any;
+
+  /**
+   * Gets updates for the `topic` the handle is for.
+   * @param opts - `opts`
+   */
+  update(opts?: GroupNotifyHandleUpdateOptions): any;
+
+  /**
+   * Calls the callback whenever a core with the `topic` for the `handle` updates.
+   */
+  on(event: 'update', listener: (...args: any[]) => void): this;
+}
+
+export class FindingPeers {
+  constructor();
+
+  add(core: any): any;
+
+  inc(sessions: any): any;
+
+  dec(sessions: any): any;
+
+  destroy(): any;
+
+  count: any;
+
+  pending: any;
+
+  destroyed: any;
+}
+
+export default Corestore;
diff --git a/package.json b/package.json
index fc0fd4e..994042e 100644
--- a/package.json
+++ b/package.json
@@ -48,5 +48,6 @@
   "bugs": {
     "url": "https://github.com/holepunchto/corestore/issues"
   },
-  "homepage": "https://github.com/holepunchto/corestore"
+  "homepage": "https://github.com/holepunchto/corestore",
+  "types": "index.d.ts"
 }

From de27e1a7c1a5bbd048c5cef848fbf01653455dc2 Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 21 Jul 2026 17:04:41 -0300
Subject: [PATCH 5/7] style: run index.d.ts through prettier

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 index.d.ts | 114 ++++++++++++++++++++++++++---------------------------
 1 file changed, 57 insertions(+), 57 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index ddbe826..5f7b4a0 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -2,8 +2,8 @@
 
 export interface CorestoreOptions {
   /** The primary key to use as the master key for key derivation. */
-  primaryKey?: any;
-  writable?: any;
+  primaryKey?: any
+  writable?: any
 }
 
 /**
@@ -11,9 +11,9 @@ export interface CorestoreOptions {
  */
 export interface GroupNotifyHandleUpdateOptions {
   /** What timestamp to start returning updates from. Default `0` returns all updates */
-  since?: any;
+  since?: any
   /** Flag to return updates in reverse order. Defaults to `true` so latest returned first */
-  reverse?: any;
+  reverse?: any
 }
 
 export class Corestore {
@@ -21,163 +21,163 @@ export class Corestore {
    * Create a new Corestore instance.
    * @param storage - `storage` can be either a `hypercore-storage` instance or a string.
    */
-  constructor(storage: any, opts?: CorestoreOptions);
+  constructor(storage: any, opts?: CorestoreOptions)
 
   /**
    * Register a callback called when new Hypercores are opened. `core` is the internal core for the opened Hypercore. It can be used to create weak references to a Hypercore like so:
    */
-  watch(fn?: any): any;
+  watch(fn?: any): any
 
   /**
    * Unregister a callback used with `store.watch(callback)` so it no longer fires.
    */
-  unwatch(fn: any): any;
+  unwatch(fn: any): any
 
   /**
    * Get a `handle` for updates from all `hypercore`s with the group `topic` set.
    */
-  notifyGroup(topic: any): any;
+  notifyGroup(topic: any): any
 
-  findingPeers(): any;
+  findingPeers(): any
 
-  audit(opts?: any): any;
+  audit(opts?: any): any
 
   /**
    * Suspend the underlying storage for the Corestore.
    */
-  suspend(options?: any): Promise<void>;
+  suspend(options?: any): Promise<void>
 
   /**
    * Resume a suspended Corestore.
    */
-  resume(): any;
+  resume(): any
 
   /**
    * Create a new Corestore session. Closing a session will close all cores made from this session.
    */
-  session(opts: any): any;
+  session(opts: any): any
 
   /**
    * Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.
    */
-  namespace(name: any, opts: any): any;
+  namespace(name: any, opts: any): any
 
   /**
    * Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.
    */
-  list(namespace: any): any;
+  list(namespace: any): any
 
-  getAuth(discoveryKey: any): any;
+  getAuth(discoveryKey: any): any
 
   /**
    * Creates a replication stream that's capable of replicating all Hypercores that are managed by the Corestore, assuming the remote peer has the correct capabilities.
    */
-  replicate(isInitiator: any, opts: any): any;
+  replicate(isInitiator: any, opts: any): any
 
-  staticify(core: any, opts: any): Promise<void>;
+  staticify(core: any, opts: any): Promise<void>
 
   /**
    * Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).
    */
-  get(opts: any): any;
+  get(opts: any): any
 
   /**
    * Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.
    * @param ns - `ns` defaults to the current namespace.
    */
-  createKeyPair(name: any, ns?: any): Promise<void>;
+  createKeyPair(name: any, ns?: any): Promise<void>
 
-  ready(): Promise<void>;
+  ready(): Promise<void>
 
   /**
    * Fully close this Corestore instance.
    */
-  close(): Promise<void>;
+  close(): Promise<void>
 
-  readonly opened: any;
+  readonly opened: any
 
-  readonly closed: any;
+  readonly closed: any
 
-  emit(event: any, arg1?: any): any;
+  emit(event: any, arg1?: any): any
 
-  root: any;
+  root: any
 
-  storage: any;
+  storage: any
 
-  streamTracker: any;
+  streamTracker: any
 
-  cores: any;
+  cores: any
 
-  sessions: any;
+  sessions: any
 
-  corestores: any;
+  corestores: any
 
-  readOnly: any;
+  readOnly: any
 
-  globalCache: any;
+  globalCache: any
 
-  primaryKey: any;
+  primaryKey: any
 
-  ns: any;
+  ns: any
 
-  manifestVersion: any;
+  manifestVersion: any
 
-  shouldSuspend: any;
+  shouldSuspend: any
 
-  active: any;
+  active: any
 
-  watchers: any;
+  watchers: any
 
-  watchIndex: any;
+  watchIndex: any
 
   /**
    * The `group-active` event emits whenever an opened Hypercore in the store updates. The `topic` is the group topic the core belongs to.
    */
-  on(event: 'group-active', listener: (topic: any, update: any) => void): this;
+  on(event: 'group-active', listener: (topic: any, update: any) => void): this
 }
 
 export class GroupNotifyHandle {
-  constructor(store: any, topic: any);
+  constructor(store: any, topic: any)
 
-  updates(opts: any): any;
+  updates(opts: any): any
 
   /**
    * Destroys and unregisters the `handle` from its `store`.
    */
-  destroy(): any;
+  destroy(): any
 
-  emit(event: any, arg1?: any): any;
+  emit(event: any, arg1?: any): any
 
-  index: any;
+  index: any
 
   /**
    * Gets updates for the `topic` the handle is for.
    * @param opts - `opts`
    */
-  update(opts?: GroupNotifyHandleUpdateOptions): any;
+  update(opts?: GroupNotifyHandleUpdateOptions): any
 
   /**
    * Calls the callback whenever a core with the `topic` for the `handle` updates.
    */
-  on(event: 'update', listener: (...args: any[]) => void): this;
+  on(event: 'update', listener: (...args: any[]) => void): this
 }
 
 export class FindingPeers {
-  constructor();
+  constructor()
 
-  add(core: any): any;
+  add(core: any): any
 
-  inc(sessions: any): any;
+  inc(sessions: any): any
 
-  dec(sessions: any): any;
+  dec(sessions: any): any
 
-  destroy(): any;
+  destroy(): any
 
-  count: any;
+  count: any
 
-  pending: any;
+  pending: any
 
-  destroyed: any;
+  destroyed: any
 }
 
-export default Corestore;
+export default Corestore

From b862da6cf3d45b0e919c88b6a3803bd46779ca22 Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 21 Jul 2026 19:16:01 -0300
Subject: [PATCH 6/7] fix(types): improve index.d.ts accuracy

Regenerated from the corrected emitter:
- Undocumented async returns are now Promise<any> instead of a fabricated
  Promise<void>, which wrongly asserted the method returns no value.
- Internal helper classes are emitted as non-exported `declare class`, since
  the package only exports its main class.
- README-documented members that belong to a returned sub-object (the apply
  host, a server/socket, a message, an extension, a codec) are no longer
  misattributed as methods of the main class.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 index.d.ts | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index 5f7b4a0..cb1fbf0 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -45,7 +45,7 @@ export class Corestore {
   /**
    * Suspend the underlying storage for the Corestore.
    */
-  suspend(options?: any): Promise<void>
+  suspend(options?: any): Promise<any>
 
   /**
    * Resume a suspended Corestore.
@@ -74,7 +74,7 @@ export class Corestore {
    */
   replicate(isInitiator: any, opts: any): any
 
-  staticify(core: any, opts: any): Promise<void>
+  staticify(core: any, opts: any): Promise<any>
 
   /**
    * Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).
@@ -85,14 +85,14 @@ export class Corestore {
    * Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.
    * @param ns - `ns` defaults to the current namespace.
    */
-  createKeyPair(name: any, ns?: any): Promise<void>
+  createKeyPair(name: any, ns?: any): Promise<any>
 
-  ready(): Promise<void>
+  ready(): Promise<any>
 
   /**
    * Fully close this Corestore instance.
    */
-  close(): Promise<void>
+  close(): Promise<any>
 
   readonly opened: any
 
@@ -136,7 +136,7 @@ export class Corestore {
   on(event: 'group-active', listener: (topic: any, update: any) => void): this
 }
 
-export class GroupNotifyHandle {
+declare class GroupNotifyHandle {
   constructor(store: any, topic: any)
 
   updates(opts: any): any
@@ -162,7 +162,7 @@ export class GroupNotifyHandle {
   on(event: 'update', listener: (...args: any[]) => void): this
 }
 
-export class FindingPeers {
+declare class FindingPeers {
   constructor()
 
   add(core: any): any

From 7c232226adafe86a3911e97900acd1d449c7c3bb Mon Sep 17 00:00:00 2001
From: Lucas Tortora <lucas.tortora@tether.io>
Date: Tue, 21 Jul 2026 22:09:09 -0300
Subject: [PATCH 7/7] fix(types): restore return types and model returned
 sub-objects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Regenerated from the improved emitter:
- Methods that return a known object are typed as that object instead of
  `any` (verified against source) — sessions/checkouts/batches return their
  own class, stream factories return their stream class, etc.
- Objects the README documents under their own receiver (a server, socket,
  message, extension, or the autobase apply `host`) are now modeled as helper
  classes and wired to the method/callback that produces them, instead of
  being dropped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 index.d.ts | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index cb1fbf0..b439cbc 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -1,5 +1,7 @@
 // Type declarations for the holepunchto/corestore public API.
 
+import type Hypercore from 'hypercore'
+
 export interface CorestoreOptions {
   /** The primary key to use as the master key for key derivation. */
   primaryKey?: any
@@ -36,7 +38,7 @@ export class Corestore {
   /**
    * Get a `handle` for updates from all `hypercore`s with the group `topic` set.
    */
-  notifyGroup(topic: any): any
+  notifyGroup(topic: any): GroupNotifyHandle
 
   findingPeers(): any
 
@@ -55,12 +57,12 @@ export class Corestore {
   /**
    * Create a new Corestore session. Closing a session will close all cores made from this session.
    */
-  session(opts: any): any
+  session(opts: any): Corestore
 
   /**
    * Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.
    */
-  namespace(name: any, opts: any): any
+  namespace(name: any, opts: any): Corestore
 
   /**
    * Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.
@@ -79,7 +81,7 @@ export class Corestore {
   /**
    * Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).
    */
-  get(opts: any): any
+  get(opts: any): Hypercore
 
   /**
    * Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.