@ignex/ninox 0.1.6 → 0.1.7

package/dist/index.d.ts

@@ -2,7 +2,6 @@ import * as mongodb from 'mongodb';
 import { Db, MongoClient, ClientSession, Document, Filter, Hint, CollationOptions, ReadPreferenceLike, ReadConcern, WriteConcern, WithId, Condition, RootFilterOperators, Collection, FindOptions, Sort, FindCursor, ObjectId, Decimal128, ReadConcernLike, AggregateOptions, AggregationCursor, CreateCollectionOptions, TransactionOptions, InsertOneOptions, InsertOneResult, InsertManyResult, UpdateOptions, UpdateResult, FindOneAndUpdateOptions, DeleteResult, ChangeStreamOptions, ChangeStream } from 'mongodb';
 import { L as LoggerLike } from './timeout-B10CTiGm.js';
 export { C as CacheOptions, a as LRU, b as LRUOptions, c as LogFn, d as LogLevel, e as createCachedAsyncFactory, f as createCachedFactory, g as createConsoleLogger, h as createNoopLogger, i as hashString, s as sleep, j as sleepJittered, k as stableHash, l as stableStringify, w as withTimeout } from './timeout-B10CTiGm.js';
-import * as bson from 'bson';
 
 /**
  * Types + constants for the HotCache layer. All type-only (plus the stream-key
@@ -411,14 +410,6 @@ declare const createMongoCapabilitiesStore: () => MongoCapabilitiesStore;
 /** Probe a connected client/db via `hello`. */
 declare const probeMongoCapabilities: (client: MongoClient | Db | null | undefined) => Promise<MongoCapabilities>;
 
-/**
- * The ORM's error classes (`AppError` → `DomainError` / `InfraError` /
- * `BadRequest`), their type guards, and the `ERROR_HTTP_STATUS` table that sets
- * each error's `statusCode` at construction.
- *
- * A leaf module: nothing else in `src/errors/` imports this (so `driver-map.ts`
- * and `http-status.ts` can depend on it without cycles).
- */
 interface ErrorContext {
     db?: string;
     collection?: string;
@@ -437,23 +428,47 @@ declare class AppError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly extra?: Record<string, unknown>;
-    constructor(code: string, message: string, statusCode?: number, extra?: Record<string, unknown>);
     /**
-     * Stable, client-safe serialization for framework error middleware: a
-     * framework can forward `JSON.stringify(error)` (or `error.toJSON()`) straight
-     * to the client — no parsing of server internals. `stack` is dropped; the
-     * shape is always `{ name, code, message, statusCode, ...(extra) }`.
+     * Whether `message`/`extra` may be sent to a CLIENT.
+     *
+     * Fail-closed: a 4xx message is the caller's contract, a 5xx message is an
+     * operator detail that may quote a driver, a host or a query. Pass `expose`
+     * explicitly to override — only for a 5xx whose text was written for callers
+     * (e.g. `new InfraError("DRAINING", "queue is draining", extra, true)`).
+     */
+    readonly expose: boolean;
+    constructor(code: string, message: string, statusCode?: number, extra?: Record<string, unknown>, expose?: boolean);
+    /**
+     * Full, stack-free shape for LOGS and typed consumers:
+     * `{ name, code, message, statusCode, ...(extra) }`.
+     *
+     * It carries the real message, so it is NOT the client path — use
+     * {@link toClientPayload} (or `serializeError`) for anything a caller sees, and
+     * prefer `logger.error({ err })` so pino's own serializer keeps the stack in the
+     * log rather than in a payload.
      */
     toJSON(): Record<string, unknown>;
+    /**
+     * The client-safe payload — the same shape as {@link toJSON}, except that a
+     * non-exposed error's `message` is replaced by the canonical reason phrase and
+     * its `extra` is dropped. A framework can forward this (or `serializeError`'s
+     * result) without auditing what the message might contain.
+     *
+     * @param options - `expose: true` forces the real (masked) message + extra.
+     * @returns The client payload.
+     */
+    toClientPayload(options?: {
+        expose?: boolean;
+    }): Record<string, unknown>;
 }
 declare class DomainError extends AppError {
-    constructor(code: string, message: string, extra?: Record<string, unknown>);
+    constructor(code: string, message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare class InfraError extends AppError {
-    constructor(code: string, message: string, extra?: Record<string, unknown>);
+    constructor(code: string, message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare class BadRequest extends DomainError {
-    constructor(message: string, extra?: Record<string, unknown>);
+    constructor(message: string, extra?: Record<string, unknown>, expose?: boolean);
 }
 declare const isAppError: (err: unknown) => err is AppError;
 declare const isDomainError: (err: unknown) => err is DomainError;
@@ -483,8 +498,16 @@ declare const isMappedMongoError: (error: unknown) => error is AppError;
 
 /** Effective HTTP status for any thrown value: AppError-aware, raw → 500 (503 transient). */
 declare const httpStatusForError: (err: unknown) => number;
+/** Options for {@link serializeError}. */
+interface SerializeErrorOptions {
+    /**
+     * Include the real message (and `extra`) even for a non-exposed error — the
+     * development / trusted-caller path. It is still credential-masked.
+     */
+    expose?: boolean;
+}
 /**
- * Reduce any thrown value to a stable, client-safe error payload:
+ * Reduce any thrown value to a stable, CLIENT-SAFE error payload:
  * `{ name, code, message, statusCode, ...(extra) }`.
  *
  * Raw driver errors are mapped through `mapMongoDriverError` first, so a
@@ -495,8 +518,15 @@ declare const httpStatusForError: (err: unknown) => number;
  *     const payload = serializeError(err, { db, collection, op });
  *     res.status(payload.statusCode).json(payload);
  *   });
+ *
+ * Fail-closed by default: a 4xx message/extra is the caller's contract, while a
+ * 5xx message is replaced by the canonical reason phrase (`Internal Server
+ * Error`, `Service Unavailable`, …) and `extra` is dropped — a driver message
+ * that quotes a host, a query or a stored value never reaches a client. The
+ * detail stays on the error itself for logs; pass `{ expose: true }` (or a
+ * per-error `expose`) to opt out for a trusted caller.
  */
-declare const serializeError: (err: unknown, ctx?: ErrorContext) => Record<string, unknown>;
+declare const serializeError: (err: unknown, ctx?: ErrorContext, options?: SerializeErrorOptions) => Record<string, unknown>;
 
 /**
  * Transient-error detection: which MongoDB errors are safe to retry. This is a
@@ -2038,7 +2068,7 @@ interface CrudOpsOptions {
  * and fire lifecycle hooks.
  */
 declare const makeCrudOps: <TClients extends DbClientsDefinition, TDb extends ExtractDbNames<TClients>>(client: Db, dbLabel: string, logger: LoggerLike, opts: CrudOpsOptions) => {
-    watchCollection: <X extends ColNames<TClients, TDb>>(collection: X, pipeline?: bson.Document[], options?: mongodb.ChangeStreamOptions) => mongodb.ChangeStream<CollectionDoc<TClients[TDb]["collections"][X]>, mongodb.ChangeStreamDocument<CollectionDoc<TClients[TDb]["collections"][X]>>>;
+    watchCollection: <X extends ColNames<TClients, TDb>>(collection: X, pipeline?: mongodb.Document[], options?: mongodb.ChangeStreamOptions) => mongodb.ChangeStream<CollectionDoc<TClients[TDb]["collections"][X]>, mongodb.ChangeStreamDocument<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     query: <X extends ColNames<TClients, TDb>>(collection: X) => QueryBuilder<CollectionDoc<TClients[TDb]["collections"][X]>, CollectionDoc<TClients[TDb]["collections"][X]>>;
     insertOne: <X extends ColNames<TClients, TDb>>(collection: X, doc: InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.InsertOneOptions & QueryOptions) => Promise<mongodb.InsertOneResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     insertMany: <X extends ColNames<TClients, TDb>>(collection: X, docs: readonly InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.InsertManyResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
@@ -2054,8 +2084,8 @@ declare const makeCrudOps: <TClients extends DbClientsDefinition, TDb extends Ex
         filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
         update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>;
         upsert?: boolean;
-    }[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<bson.Document>;
-    bulkWrite: <X extends ColNames<TClients, TDb>>(collection: X, operations: mongodb.AnyBulkWriteOperation<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<bson.Document>;
+    }[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.Document>;
+    bulkWrite: <X extends ColNames<TClients, TDb>>(collection: X, operations: mongodb.AnyBulkWriteOperation<CollectionDoc<TClients[TDb]["collections"][X]>>[], options?: mongodb.BulkWriteOptions & QueryOptions) => Promise<mongodb.Document>;
     updateWithVersion: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, update: UpdateInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.FindOneAndUpdateOptions & QueryOptions) => Promise<VersionedUpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;
     findOneAndDelete: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.FindOneAndDeleteOptions & QueryOptions) => Promise<CollectionDoc<TClients[TDb]["collections"][X]> | null>;
     replaceOne: <X extends ColNames<TClients, TDb>>(collection: X, filter: FilterInput<CollectionDoc<TClients[TDb]["collections"][X]>>, replacement: InsertInput<CollectionDoc<TClients[TDb]["collections"][X]>>, options?: mongodb.ReplaceOptions & QueryOptions) => Promise<mongodb.UpdateResult<CollectionDoc<TClients[TDb]["collections"][X]>>>;

package/dist/index.js

@@ -57,6 +57,17 @@ var probeMongoCapabilities = async (client) => {
   }
 };
 
+// src/utils/redact.ts
+var CONNECTION_CREDENTIALS = /([a-z][a-z0-9+.-]*:\/\/[^/\s:@]*):[^/\s@]*@/gi;
+var SECRET_PAIR = /\b(password|passwd|pwd|secret|token|api[-_]?key|access[-_]?key)=([^&\s;,"')]+)/gi;
+var maskCredentials = (value) => value.replace(CONNECTION_CREDENTIALS, "$1:***@");
+var maskSecretPairs = (value) => value.replace(SECRET_PAIR, "$1=***");
+var redactText = (value, max = 300) => {
+  const single = maskSecretPairs(maskCredentials(value)).split("\n").find((line) => line.trim().length > 0);
+  const text = (single ?? "").trim();
+  return text.length <= max ? text : `${text.slice(0, max - 1)}\u2026`;
+};
+
 // src/errors/classes.ts
 var ERROR_HTTP_STATUS = {
   BAD_REQUEST: 400,
@@ -68,22 +79,49 @@ var ERROR_HTTP_STATUS = {
   VALIDATION_FAILED: 422,
   MONGO_TIMEOUT: 504
 };
+var STATUS_MESSAGES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  409: "Conflict",
+  422: "Unprocessable Entity",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+var genericStatusMessage = (statusCode) => STATUS_MESSAGES[statusCode] ?? (statusCode >= 500 ? "Internal Server Error" : "Request failed");
 var AppError = class extends Error {
   code;
   statusCode;
   extra;
-  constructor(code, message, statusCode = 500, extra) {
+  /**
+   * Whether `message`/`extra` may be sent to a CLIENT.
+   *
+   * Fail-closed: a 4xx message is the caller's contract, a 5xx message is an
+   * operator detail that may quote a driver, a host or a query. Pass `expose`
+   * explicitly to override — only for a 5xx whose text was written for callers
+   * (e.g. `new InfraError("DRAINING", "queue is draining", extra, true)`).
+   */
+  expose;
+  constructor(code, message, statusCode = 500, extra, expose) {
     super(message);
     this.name = "AppError";
     this.code = code;
     this.statusCode = statusCode;
+    this.expose = expose ?? statusCode < 500;
     if (extra !== void 0) this.extra = extra;
   }
   /**
-   * Stable, client-safe serialization for framework error middleware: a
-   * framework can forward `JSON.stringify(error)` (or `error.toJSON()`) straight
-   * to the client — no parsing of server internals. `stack` is dropped; the
-   * shape is always `{ name, code, message, statusCode, ...(extra) }`.
+   * Full, stack-free shape for LOGS and typed consumers:
+   * `{ name, code, message, statusCode, ...(extra) }`.
+   *
+   * It carries the real message, so it is NOT the client path — use
+   * {@link toClientPayload} (or `serializeError`) for anything a caller sees, and
+   * prefer `logger.error({ err })` so pino's own serializer keeps the stack in the
+   * log rather than in a payload.
    */
   toJSON() {
     return {
@@ -94,22 +132,42 @@ var AppError = class extends Error {
       ...this.extra !== void 0 ? { extra: this.extra } : {}
     };
   }
+  /**
+   * The client-safe payload — the same shape as {@link toJSON}, except that a
+   * non-exposed error's `message` is replaced by the canonical reason phrase and
+   * its `extra` is dropped. A framework can forward this (or `serializeError`'s
+   * result) without auditing what the message might contain.
+   *
+   * @param options - `expose: true` forces the real (masked) message + extra.
+   * @returns The client payload.
+   */
+  toClientPayload(options = {}) {
+    const expose = options.expose === true || this.expose;
+    const payload = {
+      name: this.name,
+      code: this.code,
+      message: expose ? maskCredentials(this.message) : genericStatusMessage(this.statusCode),
+      statusCode: this.statusCode
+    };
+    if (expose && this.extra !== void 0) payload.extra = this.extra;
+    return payload;
+  }
 };
 var DomainError = class extends AppError {
-  constructor(code, message, extra) {
-    super(code, message, ERROR_HTTP_STATUS[code] ?? 400, extra);
+  constructor(code, message, extra, expose) {
+    super(code, message, ERROR_HTTP_STATUS[code] ?? 400, extra, expose);
     this.name = "DomainError";
   }
 };
 var InfraError = class extends AppError {
-  constructor(code, message, extra) {
-    super(code, message, ERROR_HTTP_STATUS[code] ?? 500, extra);
+  constructor(code, message, extra, expose) {
+    super(code, message, ERROR_HTTP_STATUS[code] ?? 500, extra, expose);
     this.name = "InfraError";
   }
 };
 var BadRequest = class extends DomainError {
-  constructor(message, extra) {
-    super("BAD_REQUEST", message, extra);
+  constructor(message, extra, expose) {
+    super("BAD_REQUEST", message, extra, expose);
     this.name = "BadRequest";
   }
 };
@@ -279,13 +337,20 @@ var httpStatusForError = (err) => {
   if (isMongoTransientError(err)) return 503;
   return 500;
 };
-var serializeError = (err, ctx = {}) => {
+var serializeError = (err, ctx = {}, options = {}) => {
   const mapped = mapMongoDriverError(err, ctx);
-  if (mapped instanceof AppError) return mapped.toJSON();
-  if (mapped instanceof Error) {
-    return { name: mapped.name, code: "UNKNOWN", message: mapped.message, statusCode: 500 };
+  if (mapped instanceof AppError) return mapped.toClientPayload(options);
+  const statusCode = httpStatusForError(mapped);
+  const name = mapped instanceof Error ? mapped.name : "UnknownError";
+  if (options.expose !== true) {
+    return { name, code: "UNKNOWN", message: genericStatusMessage(statusCode), statusCode };
   }
-  return { name: "UnknownError", code: "UNKNOWN", message: String(mapped), statusCode: 500 };
+  return {
+    name,
+    code: "UNKNOWN",
+    message: redactText(mapped instanceof Error ? mapped.message : String(mapped)),
+    statusCode
+  };
 };
 var cloneDeep = (value) => {
   if (value instanceof Date) return new Date(value.getTime());
@@ -525,6 +590,7 @@ var RefreshTicker = class {
     this.host = host;
     this.intervalMs = tickIntervalMs;
   }
+  host;
   timer;
   intervalMs;
   /** Whether the timer is currently running. */
@@ -618,16 +684,26 @@ var normalizeWatchId = (id) => {
 };
 
 // src/utils/watch-errors.ts
-var isPermanentWatchError = (message) => (
-  // Standalone server: `$changeStream` is not supported at all.
-  /only supported on replica sets/i.test(message) || // Credentials/authorization problems: the user cannot run `aggregate` on
-  // this collection/server. Wrong creds, missing roles, or a user created
-  // without the `read`/`changeStream` privilege will never start working by
-  // retrying — fail once and stop instead of retrying forever.
-  /requires authentication|not authorized|unauthorized|authentication failed|Command .* requires authentication/i.test(
-    message
-  )
-);
+var STANDALONE = /only supported on replica sets|not supported on (?:a )?standalone/i;
+var CREDENTIALS = /requires authentication|not authorized|unauthorized|authentication failed|Command .* requires authentication/i;
+var explainPermanentWatchError = (message) => {
+  if (STANDALONE.test(message)) {
+    return {
+      reason: "standalone",
+      headline: "change streams need a replica set",
+      hint: "Point the connection at a replica set (a single-node replica set is fine for local dev), or set cacheWatch: false / cache: { ttlMs } to run write-through only."
+    };
+  }
+  if (CREDENTIALS.test(message)) {
+    return {
+      reason: "credentials",
+      headline: "the connection is not authorized for change streams",
+      hint: "Change streams need an authenticated user with the read + changeStream privilege (usually granted on the authSource database) \u2014 fix the credentials in .env, then restart."
+    };
+  }
+  return void 0;
+};
+var isPermanentWatchError = (message) => explainPermanentWatchError(message) !== void 0;
 
 // src/cache/hot-cache/watcher.ts
 var resolveDbSafe = (ref, logger) => {
@@ -649,6 +725,7 @@ var WatchCoordinator = class {
   constructor(host) {
     this.host = host;
   }
+  host;
   streams = /* @__PURE__ */ new Map();
   failedStreams = /* @__PURE__ */ new Set();
   stopped = true;
@@ -762,7 +839,7 @@ var WatchCoordinator = class {
           }
         }
         if (isPermanentWatchError(message)) {
-          this.markStreamFailed(key);
+          this.markStreamFailed(key, explainPermanentWatchError(message));
           return;
         }
       }
@@ -771,12 +848,15 @@ var WatchCoordinator = class {
       await sleepJittered(backoff, 1e3, true);
     }
   }
-  markStreamFailed(key) {
+  markStreamFailed(key, verdict) {
     this.failedStreams.add(key);
     if (!this.host.isReplica()) return;
     const planned = this.plannedStreamKeys();
     if (planned.size > 0 && [...planned].every((k) => this.failedStreams.has(k))) {
-      this.host.logger.warn?.({}, "hot cache: change streams unsupported, falling back to ticker");
+      this.host.logger.warn?.(
+        verdict === void 0 ? {} : { reason: verdict.reason, hint: verdict.hint },
+        `hot cache: change streams unsupported${verdict === void 0 ? "" : ` \u2014 ${verdict.headline}`}, falling back to ticker`
+      );
       this.host.fallbackToStandalone();
     }
   }
@@ -1787,6 +1867,7 @@ var QueryBuilder = class _QueryBuilder {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  ctx;
   _filter = {};
   _sort;
   _skip;
@@ -2814,13 +2895,19 @@ var CacheInvalidator = class {
           } catch {
           }
         }
-        if (isPermanentWatchError(message)) {
+        const verdict = explainPermanentWatchError(message);
+        if (verdict) {
           this.disabled = true;
           if (!this.warnedUnsupported) {
             this.warnedUnsupported = true;
             this.logger.warn?.(
-              { collection: ref.collection, error: message },
-              "cacheWatch: change streams unavailable permanently \u2014 the query cache stays write-through only; set cache: { ttlMs } or disable cacheWatch"
+              {
+                collection: ref.collection,
+                reason: verdict.reason,
+                error: message,
+                hint: verdict.hint
+              },
+              `cacheWatch: disabled \u2014 ${verdict.headline}; the query cache stays write-through only`
             );
           }
           return;
@@ -3248,6 +3335,8 @@ var PipelineBuilder = class _PipelineBuilder {
     this.deps = deps2;
     this.stages = stages;
   }
+  deps;
+  stages;
   /** Raw accumulated stages — embeddable into `$lookup` / `$facet` branches. */
   raw() {
     return this.stages;