diff --git a/src/blob-store/index.js b/src/blob-store/index.js
index 919387d98..544b2378e 100644
--- a/src/blob-store/index.js
+++ b/src/blob-store/index.js
@@ -4,7 +4,15 @@ import util from 'node:util'
 import { discoveryKey } from 'hypercore-crypto'
 import { TypedEmitter } from 'tiny-typed-emitter'
 import { LiveDownload } from './live-download.js'
+/** @import { Readable as NodeReadable } from 'node:stream' */
+/** @import { Readable as StreamxReadable, Writable } from 'streamx' */
 /** @import { BlobId } from '../types.js' */
+/** @import { BlobDownloadEvents } from './live-download.js' */
+
+/**
+ * @internal
+ * @typedef {NodeReadable | StreamxReadable} Readable
+ */
 
 /** @typedef {TypedEmitter<{ 'add-drive': (drive: import('hyperdrive')) => void }>} InternalDriveEmitter */
 
@@ -74,12 +82,16 @@ export class BlobStore {
     })
   }
 
+  /**
+   * @returns {string}
+   */
   get writerDriveId() {
     return getDiscoveryId(this.#writer.key)
   }
 
   /**
    * @param {string} driveId hex-encoded discovery key
+   * @returns {Hyperdrive}
    */
   #getDrive(driveId) {
     const drive = this.#hyperdrives.get(driveId)
@@ -92,6 +104,7 @@ export class BlobStore {
    * @param {object} opts
    * @param {false} [opts.wait=false] Set to `true` to wait for a blob to download, otherwise will throw if blob is not available locally
    * @param {never} [opts.timeout] Optional timeout to wait for a blob to download
+   * @returns {Promise<Uint8Array>}
    */
   async get({ type, variant, name, driveId }, { wait = false, timeout } = {}) {
     const drive = this.#getDrive(driveId)
@@ -112,7 +125,7 @@ export class BlobStore {
    * @param {import('../types.js').BlobFilter} [filter] Filter blob types and/or variants to download. Filter is { [BlobType]: BlobVariants[] }. At least one blob variant must be specified for each blob type.
    * @param {object} options
    * @param {AbortSignal} [options.signal] Optional AbortSignal to cancel in-progress download
-   * @returns EventEmitter with `.state` propery, emits `state` with new state when it updates
+   * @returns {TypedEmitter<BlobDownloadEvents>}
    */
   download(filter, { signal } = {}) {
     return new LiveDownload(this.#hyperdrives.values(), this.#driveEmitter, {
@@ -126,6 +139,7 @@ export class BlobStore {
    * @param {object} [options]
    * @param {boolean} [options.wait=false] Set to `true` to wait for a blob to download, otherwise will throw if blob is not available locally
    * @param {number} [options.timeout] Optional timeout to wait for a blob to download
+   * @returns {Readable}
    */
   createReadStream(
     { type, variant, name, driveId },
@@ -146,6 +160,7 @@ export class BlobStore {
    * @param {import('hyperdrive').HyperdriveEntry} entry Hyperdrive entry
    * @param {object} [options]
    * @param {boolean} [options.wait=false] Set to `true` to wait for a blob to download, otherwise will throw if blob is not available locally
+   * @returns {Promise<Readable>}
    */
   async createEntryReadStream(driveId, entry, options = { wait: false }) {
     const drive = this.#getDrive(driveId)
@@ -165,7 +180,6 @@ export class BlobStore {
    * @param {import('hyperdrive').HyperdriveEntry} entry Hyperdrive entry
    * @param {object} [opts]
    * @param {number} [opts.length]
-   *
    * @returns {Promise<Buffer | null>}
    */
   async getEntryBlob(driveId, entry, { length } = {}) {
@@ -199,6 +213,7 @@ export class BlobStore {
    * @param {Omit<BlobId, 'driveId'>} blobId
    * @param {object} [options]
    * @param {{mimeType: string}} [options.metadata] Metadata to store with the blob
+   * @returns {Writable & { driveId: string }}
    */
   createWriteStream({ type, variant, name }, options) {
     const path = makePath({ type, variant, name })