@comapeo/core 5.4.1 → 6.0.0

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@comapeo/core",
-  "version": "5.4.1",
+  "version": "6.0.0",
   "description": "Offline p2p mapping library",
   "main": "src/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./errors.js": {
+      "types": "./dist/errors.d.ts",
+      "import": "./src/errors.js"
+    },
+    "./schema.js": {
+      "types": "./dist/schema.d.ts",
+      "import": "./src/schema.js"
+    }
+  },
   "type": "module",
   "scripts": {
     "lint": "eslint --cache .",
@@ -13,6 +27,7 @@
     "test:unit": "node --test",
     "test:e2e": "node --test test-e2e/*.js test-e2e/**/*.js",
     "test:types": "tsc -p test-types/tsconfig.json",
+    "build": "npm-run-all build:types",
     "build:types": "tsc -p tsconfig.npm.json && cpy 'src/**/*.d.ts' dist",
     "bench": "nanobench benchmarks/*.js",
     "type": "tsc",
@@ -21,7 +36,7 @@
     "protobuf": "node ./scripts/build-messages.js",
     "db:generate:project": "drizzle-kit generate --dialect sqlite --schema src/schema/project.js --out drizzle/project",
     "db:generate:client": "drizzle-kit generate --dialect sqlite --schema src/schema/client.js --out drizzle/client",
-    "prepack": "npm run build:types",
+    "prepack": "npm run build",
     "prepare": "husky install"
   },
   "files": [
@@ -182,6 +197,7 @@
     "comapeocat": "^1.0.0",
     "compact-encoding": "^2.12.0",
     "corestore": "6.8.4",
+    "custom-error-creator": "^1.1.1",
     "debug": "^4.3.4",
     "dot-prop": "^9.0.0",
     "dot-prop-extra": "^10.2.0",

package/src/blob-api.js

@@ -2,6 +2,7 @@ import fs from 'node:fs'
 // @ts-expect-error - pipelinePromise missing from streamx types
 import { Transform, pipelinePromise as pipeline } from 'streamx'
 import { createHash, randomBytes } from 'node:crypto'
+import { BlobReadError, UnsupportedMimeTypeError } from './errors.js'
 /** @import { BlobId, BlobType } from './types.js' */
 
 /**
@@ -57,8 +58,13 @@ export class BlobApi {
       { type, variant: 'original', name },
       { metadata }
     )
+
     const writePromises = [
-      pipeline(fs.createReadStream(original), hashTransform(hash), ws),
+      pipeline(fs.createReadStream(original), hashTransform(hash), ws).catch(
+        (/** @type {Error} */ e) => {
+          throw new BlobReadError(original, { cause: e })
+        }
+      ),
     ]
 
     if (preview) {
@@ -66,7 +72,14 @@ export class BlobApi {
         { type, variant: 'preview', name },
         { metadata }
       )
-      writePromises.push(pipeline(fs.createReadStream(preview), ws))
+
+      writePromises.push(
+        pipeline(fs.createReadStream(preview), ws).catch(
+          (/** @type {Error} */ e) => {
+            throw new BlobReadError(preview, { cause: e })
+          }
+        )
+      )
     }
 
     if (thumbnail) {
@@ -74,7 +87,14 @@ export class BlobApi {
         { type, variant: 'thumbnail', name },
         { metadata }
       )
-      writePromises.push(pipeline(fs.createReadStream(thumbnail), ws))
+
+      writePromises.push(
+        pipeline(fs.createReadStream(thumbnail), ws).catch(
+          (/** @type {Error} */ e) => {
+            throw new BlobReadError(thumbnail, { cause: e })
+          }
+        )
+      )
     }
 
     await Promise.all(writePromises)
@@ -109,5 +129,5 @@ function getType(mimeType) {
   if (mimeType.startsWith('video')) return 'video'
   if (mimeType.startsWith('audio')) return 'audio'
 
-  throw new Error(`Unsupported mimeType: ${mimeType}`)
+  throw new UnsupportedMimeTypeError({ mimeType })
 }

package/src/blob-store/downloader.js

@@ -1,6 +1,7 @@
 import { TypedEmitter } from 'tiny-typed-emitter'
 import { createEntriesStream } from './entries-stream.js'
 import { filePathMatchesFilter } from './utils.js'
+import { DriveNotFoundError, UnexpectedEndOfStreamError } from '../errors.js'
 
 /** @import { BlobFilter } from '../types.js' */
 /** @import { THyperdriveIndex } from './hyperdrive-index.js' */
@@ -74,13 +75,13 @@ export class Downloader extends TypedEmitter {
       if (!this.#shouldDownloadFile(filePath)) continue
       const drive = this.#driveIndex.get(driveId)
       // ERROR HANDLING: this is unexpected and should not happen
-      if (!drive) throw new Error('Drive not found: ' + driveId)
+      if (!drive) throw new DriveNotFoundError({ driveId })
       const blobs = await drive.getBlobs()
       this.#ac.signal.throwIfAborted()
       await this.#processEntry(blobs.core, blob)
       this.#ac.signal.throwIfAborted()
     }
-    throw new Error('Entries stream ended unexpectedly')
+    throw new UnexpectedEndOfStreamError()
   }
 
   /**
@@ -112,11 +113,11 @@ export class Downloader extends TypedEmitter {
     this.#ac.abort()
   }
 
-  /** @param {Error} error */
-  #handleError = (error) => {
+  /** @param {Error} err */
+  #handleError = (err) => {
     if (this.#ac.signal.aborted) return
-    this.emit('error', error)
-    this.#ac.abort(error)
+    this.emit('error', err)
+    this.#ac.abort(err)
   }
 
   #handleAbort = () => {

package/src/blob-store/entries-stream.js

@@ -101,6 +101,6 @@ class AddDriveIds extends Transform {
         }
         callback(null, { ...entry, driveId: this.#driveId, blobCoreId })
       })
-      .catch((reason) => callback(ensureError(reason)))
+      .catch((e) => callback(ensureError(e)))
   }
 }

package/src/blob-store/hyperdrive-index.js

@@ -1,8 +1,8 @@
 import b4a from 'b4a'
 import { discoveryKey } from 'hypercore-crypto'
 import Hyperdrive from 'hyperdrive'
-import util from 'node:util'
 import { TypedEmitter } from 'tiny-typed-emitter'
+import { MissingWriterError, UnsupportedCorestoreOptsError } from '../errors.js'
 
 /** @typedef {HyperdriveIndexImpl} THyperdriveIndex */
 
@@ -33,7 +33,7 @@ export class HyperdriveIndexImpl extends TypedEmitter {
       }
     }
     if (!writer) {
-      throw new Error('Could not find a writer for the blobIndex namespace')
+      throw new MissingWriterError({ namespace: 'blobIndex' })
     }
     this.#writer = writer
 
@@ -103,9 +103,7 @@ class PretendCorestore {
     } else if (opts.name.includes('blobs')) {
       return this.#coreManager.getWriterCore('blob').core
     } else {
-      throw new Error(
-        'Unsupported corestore.get() with opts ' + util.inspect(opts)
-      )
+      throw new UnsupportedCorestoreOptsError({ opts })
     }
   }
 

package/src/blob-store/index.js

@@ -7,7 +7,13 @@ import { noop } from '../utils.js'
 import { TypedEmitter } from 'tiny-typed-emitter'
 import { HyperdriveIndexImpl as HyperdriveIndex } from './hyperdrive-index.js'
 import { Logger } from '../logger.js'
-import { getErrorCode, getErrorMessage } from '../lib/error.js'
+import {
+  BlobNotFoundError,
+  getErrorCode,
+  BlobsNotFoundError,
+  DriveNotFoundError,
+} from '../errors.js'
+import ensureError from 'ensure-error'
 
 /** @import Hyperdrive from 'hyperdrive' */
 /** @import { JsonObject } from 'type-fest' */
@@ -52,13 +58,6 @@ const NON_ARCHIVE_DEVICE_DOWNLOAD_FILTER = {
   // thumbnails aren't supported yet.
 }
 
-class ErrNotFound extends Error {
-  constructor(message = 'NotFound') {
-    super(message)
-    this.code = 'ENOENT'
-  }
-}
-
 /** @extends {TypedEmitter<BlobStoreEvents>} */
 export class BlobStore extends TypedEmitter {
   #driveIndex
@@ -110,12 +109,12 @@ export class BlobStore extends TypedEmitter {
           blobCoreId,
         })
       }
-    } catch (err) {
-      if (getErrorCode(err) === 'ERR_STREAM_PREMATURE_CLOSE') return
+    } catch (e) {
+      if (getErrorCode(e) === 'ERR_STREAM_PREMATURE_CLOSE') return
       this.#l.log(
         'Error getting blob entries stream for peer %h: %s',
         peerId,
-        getErrorMessage(err)
+        ensureError(e).message
       )
     }
   }
@@ -217,7 +216,7 @@ export class BlobStore extends TypedEmitter {
    */
   #getDrive(driveId) {
     const drive = this.#driveIndex.get(driveId)
-    if (!drive) throw new Error('Drive not found ' + driveId.slice(0, 7))
+    if (!drive) throw new DriveNotFoundError({ driveId: driveId.slice(0, 7) })
     return drive
   }
 
@@ -232,7 +231,7 @@ export class BlobStore extends TypedEmitter {
     const drive = this.#getDrive(driveId)
     const path = makePath({ type, variant, name })
     const blob = await drive.get(path, { wait, timeout })
-    if (!blob) throw new ErrNotFound()
+    if (!blob) throw new BlobNotFoundError()
     return blob
   }
 
@@ -285,9 +284,7 @@ export class BlobStore extends TypedEmitter {
     const blobs = await drive.getBlobs()
 
     if (!blobs) {
-      throw new Error(
-        'Hyperblobs instance not found for drive ' + driveId.slice(0, 7)
-      )
+      throw new BlobsNotFoundError({ driveId: driveId.slice(0, 7) })
     }
 
     return blobs.createReadStream(entry.value.blob, options)
@@ -305,9 +302,7 @@ export class BlobStore extends TypedEmitter {
     const blobs = await drive.getBlobs()
 
     if (!blobs) {
-      throw new Error(
-        'Hyperblobs instance not found for drive ' + driveId.slice(0, 7)
-      )
+      throw new BlobsNotFoundError({ driveId: driveId.slice(0, 7) })
     }
 
     return blobs.get(entry.value.blob, { wait: false, start: 0, length })
@@ -380,7 +375,7 @@ export class BlobStore extends TypedEmitter {
     options = { follow: false, wait: false }
   ) {
     const drive = this.#driveIndex.get(driveId)
-    if (!drive) throw new Error('Drive not found ' + driveId.slice(0, 7))
+    if (!drive) throw new DriveNotFoundError({ driveId: driveId.slice(0, 7) })
     const path = makePath({ type, variant, name })
     const entry = await drive.entry(path, options)
     return entry

package/src/core-manager/bitfield-rle.js

@@ -3,6 +3,7 @@
 // Modified to encode and decode Uint32Arrays
 
 import varint from 'varint'
+import { InvalidBitfieldError } from '../errors.js'
 
 const isLittleEndian =
   new Uint8Array(new Uint16Array([0xff]).buffer)[0] === 0xff
@@ -123,7 +124,7 @@ export function decodingLength(buffer, offset) {
     if (!repeat) offset += slice
   }
 
-  if (offset > buffer.length) throw new Error('Invalid RLE bitfield')
+  if (offset > buffer.length) throw new InvalidBitfieldError()
 
   if (len & (n - 1)) return len + (n - (len & (n - 1)))
 

package/src/core-manager/core-index.js

@@ -1,4 +1,5 @@
 import crypto from 'hypercore-crypto'
+import { MissingWriterError } from '../errors.js'
 /** @import { Namespace } from '../types.js' */
 /** @import { CoreRecord } from './index.js' */
 
@@ -59,7 +60,7 @@ export class CoreIndex {
     const writerRecord = this.#writersByNamespace.get(namespace)
     // Shouldn't happen, since we add all the writers in the contructor
     if (!writerRecord) {
-      throw new Error(`Writer for namespace '${namespace}' is not defined`)
+      throw new MissingWriterError({ namespace })
     }
     return writerRecord
   }

package/src/core-manager/index.js

@@ -1,7 +1,6 @@
 import { TypedEmitter } from 'tiny-typed-emitter'
 import Corestore from 'corestore'
 import { debounce } from 'throttle-debounce'
-import assert from 'node:assert/strict'
 import { sql, eq } from 'drizzle-orm'
 
 import {
@@ -17,7 +16,11 @@ import { coresTable } from '../schema/project.js'
 import * as rle from './bitfield-rle.js'
 import { CoreIndex } from './core-index.js'
 import mapObject from 'map-obj'
-import { PeerNotFoundError } from '../errors.js'
+import {
+  InvalidProjectKeyError,
+  InvalidProjectSecretKeyError,
+  PeerNotFoundError,
+} from '../errors.js'
 
 /** @import Hypercore from 'hypercore' */
 /** @import { BlobFilter, GenericBlobFilter, HypercorePeer, Namespace } from '../types.js' */
@@ -83,14 +86,10 @@ export class CoreManager extends TypedEmitter {
     logger,
   }) {
     super()
-    assert(
-      projectKey.length === 32,
-      'project owner core public key must be 32-byte buffer'
-    )
-    assert(
-      !projectSecretKey || projectSecretKey.length === 64,
-      'project owner core secret key must be 64-byte buffer'
-    )
+    if (projectKey.length !== 32) throw new InvalidProjectKeyError()
+    if (projectSecretKey && projectSecretKey.length !== 64) {
+      throw new InvalidProjectSecretKeyError()
+    }
     // Each peer will attach a listener, so max listeners is max attached peers
     this.setMaxListeners(0)
     this.#l = Logger.create('coreManager', logger)
@@ -492,11 +491,11 @@ export class CoreManager extends TypedEmitter {
   /**
    * Send a map share to a peer
    * @param {MapShareExtension} mapShare
-   * @param {HypercorePeer['remotePublicKey']} peerId
    */
-  async sendMapShare(mapShare, peerId) {
+  async sendMapShare(mapShare) {
+    const { receiverDeviceKey } = mapShare
     for (const peer of this.creatorCore.peers) {
-      if (peer.remotePublicKey.equals(peerId)) {
+      if (peer.remotePublicKey.equals(receiverDeviceKey)) {
         this.#mapShareExtension.send(mapShare, peer)
         return
       }

package/src/core-ownership.js

@@ -16,7 +16,7 @@ import pDefer from 'p-defer'
 import { NAMESPACES } from './constants.js'
 import { TypedEmitter } from 'tiny-typed-emitter'
 import { omit } from './lib/omit.js'
-import { NotFoundError } from './errors.js'
+import { InvalidCoreOwnershipError, NotFoundError } from './errors.js'
 /**
  * @import {
  *   CoreOwnershipWithSignatures,
@@ -161,10 +161,14 @@ export function mapAndValidateCoreOwnership(doc, { coreDiscoveryKey }) {
   if (
     !coreDiscoveryKey.equals(discoveryKey(Buffer.from(doc.authCoreId, 'hex')))
   ) {
-    throw new Error('Invalid coreOwnership record: mismatched authCoreId')
+    throw new InvalidCoreOwnershipError(
+      'Invalid coreOwnership record: mismatched authCoreId'
+    )
   }
   if (!verifyCoreOwnership(doc)) {
-    throw new Error('Invalid coreOwnership record: signatures are invalid')
+    throw new InvalidCoreOwnershipError(
+      'Invalid coreOwnership record: signatures are invalid'
+    )
   }
   const docWithoutSignatures = omit(doc, [
     'identitySignature',

package/src/datastore/index.js

@@ -5,7 +5,12 @@ import pDefer from 'p-defer'
 import { discoveryKey } from 'hypercore-crypto'
 import { NAMESPACE_SCHEMAS } from '../constants.js'
 import { createMap } from '../utils.js'
-import { NotFoundError } from '../errors.js'
+import {
+  InvalidDocSchemaError,
+  InvalidVersionIdError,
+  NotFoundError,
+  WriterCoreNotReadyError,
+} from '../errors.js'
 /** @import { MapeoDoc } from '@comapeo/schema' */
 
 /**
@@ -139,11 +144,10 @@ export class DataStore extends TypedEmitter {
   async write(doc) {
     // @ts-ignore
     if (!NAMESPACE_SCHEMAS[this.#namespace].includes(doc.schemaName)) {
-      throw new Error(
-        `Schema '${doc.schemaName}' is not allowed in namespace '${
-          this.#namespace
-        }'`
-      )
+      throw new InvalidDocSchemaError({
+        schemaName: doc.schemaName,
+        namespace: this.#namespace,
+      })
     }
     const block = encode(doc)
     // The indexer batch can sometimes complete before the append below
@@ -159,7 +163,7 @@ export class DataStore extends TypedEmitter {
     const index = length - 1
     const coreDiscoveryKey = this.#writerCore.discoveryKey
     if (!coreDiscoveryKey) {
-      throw new Error('Writer core is not ready')
+      throw new WriterCoreNotReadyError()
     }
     const versionId = getVersionId({ coreDiscoveryKey, index })
     /** @type {import('p-defer').DeferredPromise<void>} */
@@ -181,7 +185,7 @@ export class DataStore extends TypedEmitter {
   async read(versionId) {
     const { coreDiscoveryKey, index } = parseVersionId(versionId)
     const coreRecord = this.#coreManager.getCoreByDiscoveryKey(coreDiscoveryKey)
-    if (!coreRecord) throw new Error('Invalid versionId')
+    if (!coreRecord) throw new InvalidVersionIdError()
     const block = await coreRecord.core.get(index, { wait: false })
     if (!block) throw new NotFoundError('Not Found')
     return decode(block, { coreDiscoveryKey, index })
@@ -193,7 +197,7 @@ export class DataStore extends TypedEmitter {
     const index = length - 1
     const coreDiscoveryKey = this.#writerCore.discoveryKey
     if (!coreDiscoveryKey) {
-      throw new Error('Writer core is not ready')
+      throw new WriterCoreNotReadyError()
     }
     const versionId = getVersionId({ coreDiscoveryKey, index })
     return versionId

package/src/datatype/index.js

@@ -3,10 +3,18 @@ import { getTableConfig } from 'drizzle-orm/sqlite-core'
 import { eq, inArray, sql } from 'drizzle-orm'
 import { randomBytes } from 'node:crypto'
 import { noop, mutatingDeNullify } from '../utils.js'
-import { NotFoundError } from '../errors.js'
+import {
+  DocAlreadyDeletedError,
+  DocAlreadyExistsError,
+  InvalidDocError,
+  InvalidDocFormatError,
+  NotFoundError,
+  nullIfNotFound,
+} from '../errors.js'
 import { TypedEmitter } from 'tiny-typed-emitter'
 import { setProperty, getProperty } from 'dot-prop-extra'
 import { parseBcp47 } from '../intl/parse-bcp-47.js'
+
 /** @import { MapeoDoc, MapeoValue } from '@comapeo/schema' */
 /** @import { RunResult } from 'better-sqlite3' */
 /** @import { SQLiteSelectBase } from 'drizzle-orm/sqlite-core' */
@@ -78,6 +86,7 @@ function generateDate() {
   return new Date().toISOString()
 }
 export const kCreateWithDocId = Symbol('kCreateWithDocId')
+export const kCreateOrUpdateWithDocId = Symbol('kCreateWithDocId')
 export const kSelect = Symbol('select')
 export const kTable = Symbol('table')
 export const kDataStore = Symbol('dataStore')
@@ -181,6 +190,20 @@ export class DataType extends TypedEmitter {
     return this[kCreateWithDocId](docId, value, { checkExisting: false })
   }
 
+  /**
+   * @param {string} docId
+   * @param {ExcludeSchema<TValue, 'coreOwnership'>} value
+   * @returns {Promise<TDoc & DerivedDocFields>}
+   */
+  async [kCreateOrUpdateWithDocId](docId, value) {
+    const existing = await this.getByDocId(docId).catch(nullIfNotFound)
+    if (existing) {
+      return this.update(existing.versionId, value)
+    } else {
+      return this[kCreateWithDocId](docId, value, { checkExisting: false })
+    }
+  }
+
   /**
    * @param {string} docId
    * @param {ExcludeSchema<TValue, 'coreOwnership'> | CoreOwnershipWithSignaturesValue} value
@@ -190,12 +213,12 @@ export class DataType extends TypedEmitter {
   async [kCreateWithDocId](docId, value, { checkExisting = true } = {}) {
     if (!validate(this.#schemaName, value)) {
       // TODO: pass through errors from validate functions
-      throw new Error('Invalid value ' + value)
+      throw new InvalidDocFormatError({ value })
     }
     if (checkExisting) {
       const existing = await this.getByDocId(docId).catch(noop)
       if (existing) {
-        throw new Error('Doc with docId ' + docId + ' already exists')
+        throw new DocAlreadyExistsError({ docId })
       }
     }
     const nowDateString = generateDate()
@@ -376,7 +399,7 @@ export class DataType extends TypedEmitter {
     const existingDoc = await this.getByDocId(docId)
 
     if ('deleted' in existingDoc && existingDoc.deleted) {
-      throw new Error('Doc already deleted')
+      throw new DocAlreadyDeletedError()
     }
 
     /** @type {any} */
@@ -423,7 +446,7 @@ export class DataType extends TypedEmitter {
       (doc) => doc.docId === docId && doc.schemaName === this.#schemaName
     )
     if (!areLinksValid) {
-      throw new Error('Updated docs must have the same docId and schemaName')
+      throw new InvalidDocError()
     }
     return { docId, createdAt, originalVersionId }
   }

package/src/discovery/local-discovery.js

@@ -3,13 +3,14 @@ import net from 'node:net'
 import { randomBytes } from 'node:crypto'
 import NoiseSecretStream from '@hyperswarm/secret-stream'
 import { once } from 'node:events'
-import { noop } from '../utils.js'
+import { noop, timeoutPromise } from '../utils.js'
 import { isPrivate } from 'bogon'
 import StartStopStateMachine from 'start-stop-state-machine'
-import pTimeout from 'p-timeout'
 import { keyToPublicId } from '@mapeo/crypto'
 import { Logger } from '../logger.js'
-import { getErrorCode } from '../lib/error.js'
+import { ensureKnownError, getErrorCode } from '../errors.js'
+import { ServerNotListeningError } from '../errors.js'
+
 /** @import { OpenedNoiseStream } from '../lib/noise-secret-stream-helpers.js' */
 
 /** @typedef {{ publicKey: Buffer, secretKey: Buffer }} Keypair */
@@ -88,7 +89,7 @@ export class LocalDiscovery extends TypedEmitter {
       this.#server.listen(this.#port, '0.0.0.0')
       await onListening
     } catch (e) {
-      if (this.#port === 0) throw e
+      if (this.#port === 0) throw ensureKnownError(e)
       // Account for errors from re-binding the port failing
       this.#port = 0
       return this.#start()
@@ -297,7 +298,7 @@ export class LocalDiscovery extends TypedEmitter {
       for (const socket of this.#noiseConnections.values()) {
         socket.destroy()
       }
-      return pTimeout(closePromise, { milliseconds: 500 })
+      return timeoutPromise(closePromise, { milliseconds: 500 })
     }
 
     if (!force) {
@@ -306,7 +307,7 @@ export class LocalDiscovery extends TypedEmitter {
       // If timeout is 0, we force-close immediately
       await forceClose()
     } else {
-      await pTimeout(closePromise, {
+      await timeoutPromise(closePromise, {
         milliseconds: timeout,
         fallback: forceClose,
       })
@@ -324,7 +325,7 @@ export class LocalDiscovery extends TypedEmitter {
 function getAddress(server) {
   const addr = server.address()
   if (addr === null || typeof addr === 'string') {
-    throw new Error('Server is not listening on a port')
+    throw new ServerNotListeningError()
   }
   return addr
 }