@brightchain/db 0.20.0

package/src/lib/errors.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Typed error classes for brightchain-db.
+ *
+ * Provides MongoDB-compatible error names and structured properties
+ * so consumers can catch and classify errors programmatically.
+ */
+/**
+ * Base class for all brightchain-db errors.
+ */
+export declare class BrightChainDbError extends Error {
+    /** Numeric error code (MongoDB-style) */
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+/**
+ * Thrown when a document is not found by _id.
+ */
+export declare class DocumentNotFoundError extends BrightChainDbError {
+    readonly documentId: string;
+    readonly collection: string;
+    constructor(collection: string, documentId: string);
+}
+/**
+ * Thrown when a unique index constraint is violated.
+ * (Re-exported from indexing.ts — use `DuplicateKeyError` from there for the canonical class.)
+ */
+/**
+ * Thrown when a document fails schema validation.
+ */
+export declare class ValidationError extends BrightChainDbError {
+    /** Field-level validation failures */
+    readonly validationErrors: ValidationFieldError[];
+    readonly collection: string;
+    constructor(collection: string, errors: ValidationFieldError[]);
+}
+export interface ValidationFieldError {
+    field: string;
+    message: string;
+    value?: unknown;
+}
+/**
+ * Thrown when a transaction operation is invalid (e.g. commit without active txn).
+ */
+export declare class TransactionError extends BrightChainDbError {
+    readonly sessionId?: string;
+    constructor(message: string, sessionId?: string);
+}
+/**
+ * Thrown when an index operation fails.
+ */
+export declare class IndexError extends BrightChainDbError {
+    readonly indexName?: string;
+    constructor(message: string, indexName?: string);
+}
+/**
+ * Thrown when a write concern cannot be satisfied.
+ */
+export declare class WriteConcernError extends BrightChainDbError {
+    readonly writeConcern: WriteConcernSpec;
+    constructor(message: string, writeConcern: WriteConcernSpec);
+}
+/** Write concern specification */
+export interface WriteConcernSpec {
+    /** Number of acknowledgments required (1 = primary only, 'majority' = majority) */
+    w?: number | 'majority';
+    /** Timeout in ms for write concern acknowledgment */
+    wtimeoutMS?: number;
+    /** Whether to wait for journal sync */
+    journal?: boolean;
+}
+/**
+ * Thrown when one or more operations in a bulk write fail.
+ */
+export declare class BulkWriteError extends BrightChainDbError {
+    /** The individual write errors indexed by operation position */
+    readonly writeErrors: BulkWriteOperationError[];
+    /** Count of operations that succeeded */
+    readonly successCount: number;
+    constructor(writeErrors: BulkWriteOperationError[], successCount: number);
+}
+export interface BulkWriteOperationError {
+    index: number;
+    code: number;
+    message: string;
+}

package/src/lib/errors.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Typed error classes for brightchain-db.
+ *
+ * Provides MongoDB-compatible error names and structured properties
+ * so consumers can catch and classify errors programmatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkWriteError = exports.WriteConcernError = exports.IndexError = exports.TransactionError = exports.ValidationError = exports.DocumentNotFoundError = exports.BrightChainDbError = void 0;
+// ── Base ──
+/**
+ * Base class for all brightchain-db errors.
+ */
+class BrightChainDbError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'BrightChainDbError';
+        this.code = code;
+    }
+}
+exports.BrightChainDbError = BrightChainDbError;
+// ── Document errors ──
+/**
+ * Thrown when a document is not found by _id.
+ */
+class DocumentNotFoundError extends BrightChainDbError {
+    constructor(collection, documentId) {
+        super(`Document not found: collection "${collection}", _id "${documentId}"`, 404);
+        this.name = 'DocumentNotFoundError';
+        this.collection = collection;
+        this.documentId = documentId;
+    }
+}
+exports.DocumentNotFoundError = DocumentNotFoundError;
+// ── Duplicate key (re-export from indexing for convenience, but also provide the typed base) ──
+/**
+ * Thrown when a unique index constraint is violated.
+ * (Re-exported from indexing.ts — use `DuplicateKeyError` from there for the canonical class.)
+ */
+// ── Validation errors ──
+/**
+ * Thrown when a document fails schema validation.
+ */
+class ValidationError extends BrightChainDbError {
+    constructor(collection, errors) {
+        const summary = errors.map((e) => `${e.field}: ${e.message}`).join('; ');
+        super(`Document failed validation for collection "${collection}": ${summary}`, 121);
+        this.name = 'ValidationError';
+        this.collection = collection;
+        this.validationErrors = errors;
+    }
+}
+exports.ValidationError = ValidationError;
+// ── Transaction errors ──
+/**
+ * Thrown when a transaction operation is invalid (e.g. commit without active txn).
+ */
+class TransactionError extends BrightChainDbError {
+    constructor(message, sessionId) {
+        super(message, 251); // MongoDB error code for NoSuchTransaction
+        this.name = 'TransactionError';
+        this.sessionId = sessionId;
+    }
+}
+exports.TransactionError = TransactionError;
+// ── Index errors ──
+/**
+ * Thrown when an index operation fails.
+ */
+class IndexError extends BrightChainDbError {
+    constructor(message, indexName) {
+        super(message, 86); // MongoDB error code for IndexKeySpecsConflict
+        this.name = 'IndexError';
+        this.indexName = indexName;
+    }
+}
+exports.IndexError = IndexError;
+// ── Write concern errors ──
+/**
+ * Thrown when a write concern cannot be satisfied.
+ */
+class WriteConcernError extends BrightChainDbError {
+    constructor(message, writeConcern) {
+        super(message, 64); // MongoDB error code for WriteConcernFailed
+        this.name = 'WriteConcernError';
+        this.writeConcern = writeConcern;
+    }
+}
+exports.WriteConcernError = WriteConcernError;
+// ── Bulk write errors ──
+/**
+ * Thrown when one or more operations in a bulk write fail.
+ */
+class BulkWriteError extends BrightChainDbError {
+    constructor(writeErrors, successCount) {
+        super(`Bulk write operation failed: ${writeErrors.length} error(s), ${successCount} succeeded`, 65);
+        this.name = 'BulkWriteError';
+        this.writeErrors = writeErrors;
+        this.successCount = successCount;
+    }
+}
+exports.BulkWriteError = BulkWriteError;
+//# sourceMappingURL=errors.js.map

package/src/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../brightchain-db/src/lib/errors.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,aAAa;AAEb;;GAEG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAI3C,YAAY,OAAe,EAAE,IAAY;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AATD,gDASC;AAED,wBAAwB;AAExB;;GAEG;AACH,MAAa,qBAAsB,SAAQ,kBAAkB;IAI3D,YAAY,UAAkB,EAAE,UAAkB;QAChD,KAAK,CACH,mCAAmC,UAAU,WAAW,UAAU,GAAG,EACrE,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAbD,sDAaC;AAED,iGAAiG;AAEjG;;;GAGG;AAEH,0BAA0B;AAE1B;;GAEG;AACH,MAAa,eAAgB,SAAQ,kBAAkB;IAKrD,YAAY,UAAkB,EAAE,MAA8B;QAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,KAAK,CACH,8CAA8C,UAAU,MAAM,OAAO,EAAE,EACvE,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,gBAAgB,GAAG,MAAM,CAAC;IACjC,CAAC;CACF;AAfD,0CAeC;AAQD,2BAA2B;AAE3B;;GAEG;AACH,MAAa,gBAAiB,SAAQ,kBAAkB;IAGtD,YAAY,OAAe,EAAE,SAAkB;QAC7C,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,2CAA2C;QAChE,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AARD,4CAQC;AAED,qBAAqB;AAErB;;GAEG;AACH,MAAa,UAAW,SAAQ,kBAAkB;IAGhD,YAAY,OAAe,EAAE,SAAkB;QAC7C,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,+CAA+C;QACnE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AARD,gCAQC;AAED,6BAA6B;AAE7B;;GAEG;AACH,MAAa,iBAAkB,SAAQ,kBAAkB;IAGvD,YAAY,OAAe,EAAE,YAA8B;QACzD,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,4CAA4C;QAChE,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AARD,8CAQC;AAYD,0BAA0B;AAE1B;;GAEG;AACH,MAAa,cAAe,SAAQ,kBAAkB;IAMpD,YAAY,WAAsC,EAAE,YAAoB;QACtE,KAAK,CACH,gCAAgC,WAAW,CAAC,MAAM,cAAc,YAAY,YAAY,EACxF,EAAE,CACH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF;AAfD,wCAeC"}

package/src/lib/expressMiddleware.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Express middleware/router for BrightChainDb.
+ *
+ * Provides a REST API for interacting with the document database:
+ *
+ *   GET    /:collection                      - Find documents (query params as filter)
+ *   GET    /:collection/:id                  - Find document by ID
+ *   POST   /:collection                      - Insert one document (body = document)
+ *   POST   /:collection/find                 - Find with rich filter (body = { filter, sort, limit, skip, projection })
+ *   POST   /:collection/aggregate            - Aggregation pipeline (body = { pipeline })
+ *   PUT    /:collection/:id                  - Replace document
+ *   PATCH  /:collection/:id                  - Update document (body = update operators)
+ *   DELETE /:collection/:id                  - Delete document by ID
+ *   POST   /:collection/insertMany           - Bulk insert (body = { documents })
+ *   POST   /:collection/updateMany           - Bulk update (body = { filter, update })
+ *   POST   /:collection/deleteMany           - Bulk delete (body = { filter })
+ *   POST   /:collection/count                - Count documents (body = { filter })
+ *   POST   /:collection/distinct             - Distinct values (body = { field, filter })
+ *   POST   /:collection/indexes              - Create index (body = { spec, options })
+ *   DELETE /:collection/indexes/:name         - Drop index
+ *   GET    /:collection/indexes              - List indexes
+ *   POST   /:collection/bulkWrite            - Bulk write operations
+ *   POST   /:collection/cursor               - Create a server-side cursor
+ *   GET    /cursors/:cursorId                 - Fetch next batch from cursor
+ *   DELETE /cursors/:cursorId                 - Close a cursor
+ */
+import type { Router } from 'express';
+import { BrightChainDb } from './database';
+/**
+ * Options for the DB router.
+ */
+export interface DbRouterOptions {
+    /** Restrict access to specific collection names (default: allow all) */
+    allowedCollections?: string[];
+    /** Maximum response size for find queries (default: 1000) */
+    maxResults?: number;
+}
+/**
+ * Create an Express router that provides REST access to a BrightChainDb instance.
+ *
+ * @param db - The database instance
+ * @param options - Router options
+ * @returns Express router
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { BrightChainDb, createDbRouter } from '@brightchain/db';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * const db = new BrightChainDb(blockStore);
+ * app.use('/api/db', createDbRouter(db));
+ * ```
+ */
+export declare function createDbRouter(db: BrightChainDb, options?: DbRouterOptions): Router;