@ignex/ninox 0.1.5 → 0.1.7

package/README.md

@@ -787,10 +787,15 @@ you need the code → status mapping yourself.
 > transient errors.
 
 Schema validation is enforced **by MongoDB** — the DB `$jsonSchema` validator
-derived from your schema is installed with `createSchema` (and hot-swapped with
-`updateSchema`), and the DB rejects violating writes with `VALIDATION_FAILED`.
-ninox deliberately does **not** validate *incoming user input* at runtime (no
-client-side/zod layer).
+derived from your schema is installed with `createSchema`, and the DB rejects
+violating writes with `VALIDATION_FAILED`. `createSchema` is **idempotent and
+self-reconciling**: it provisions a NEW collection, and when the collection
+already exists it upgrades the DB schema to match the current ORM schema
+(hot-swapping the validator via `collMod` only when it has drifted, and
+creating any newly-declared indexes) — so calling it on every boot keeps
+Mongo's schema in lockstep with your models as they change. `updateSchema`
+hot-swaps a validator explicitly (via `collMod`). ninox deliberately does
+**not** validate *incoming user input* at runtime (no client-side/zod layer).
 
 - **Strict by default** — `additionalProperties: false` is emitted unless a
   field opts out (`s.object({ ... }, { additionalProperties: true })`), so
@@ -814,7 +819,8 @@ client-side/zod layer).
   `DomainError` carries the offending field paths (`extra.fields`), the failing
   document id (`extra.documentId`), and the raw `extra.details`, so a rejected
   write names exactly what (and which document) violated the schema.
-- **Index lifecycle** — `createSchema` installs the declared indexes;
+- **Index lifecycle** — `createSchema` installs the declared indexes (and, on
+  an existing collection, adds any newly-declared ones without dropping);
   `syncIndexes(collection)` reconciles drift (`await db.syncIndexes('products')`
   creates missing declared keys and drops undeclared ones, `_id_` kept).
 
@@ -1015,9 +1021,10 @@ unknown keys in object literals AND non-literal patches. The only way an unknown
 key passes is a variable explicitly typed with an index signature
 (`Record<string, any>`) — prefer inline literals for full checking.
 
-**Index drift.** `createSchema` installs declared indexes; if they drift out of
-band (manual drops, other tooling), `syncIndexes('collection')` reconciles —
-creates missing declared indexes and drops undeclared ones (`_id_` kept).
+**Index drift.** `createSchema` installs declared indexes on creation and adds
+newly-declared ones on re-provision; if indexes drift out of band (manual
+drops, other tooling), `syncIndexes('collection')` reconciles — creates
+missing declared indexes and drops undeclared ones (`_id_` kept).
 
 **Observability.** `QueryCache.stats()` (hits/misses/evictions/…) and
 `hot.stats()` (per-query hits/misses/refreshes/loadErrors/evictions/…) give you

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
@@ -1467,6 +1497,13 @@ interface DbOpMeta {
     physicalCollection?: string;
     db: string;
     op: string;
+    /**
+     * What was sent to the database (filter / document / update / pipeline /
+     * options). Surfaced in the ignex debugbar as the span's `params`, so the
+     * dashboard shows exactly what the query carried — not just its name.
+     * Optional: ops without a payload worth showing omit it.
+     */
+    params?: unknown;
 }
 
 /**
@@ -1549,7 +1586,7 @@ interface TextSearchPagination {
 
 interface CrudOpDeps<TCollection> {
     trace: <T>(meta: DbOpMeta, fn: () => T | Promise<T>) => Promise<T>;
-    meta: (collection: TCollection, op: string) => DbOpMeta;
+    meta: (collection: TCollection, op: string, params?: unknown) => DbOpMeta;
 }
 
 /**
@@ -2031,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]>>>;
@@ -2047,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]>>>;
@@ -2420,9 +2457,19 @@ interface SchemaOpsOptions {
     getDefinition: (logical: string) => CollectionRegistryEntry | undefined;
 }
 /**
- * Schema-first collection management. `createSchema` provisions a collection
- * with a `$jsonSchema` validator derived from the ORM schema (and creates any
- * declared indexes); `updateSchema` hot-swaps the validator via `collMod`.
+ * Schema-first collection management.
+ *
+ * `createSchema` is IDEMPOTENT and SELF-RECONCILING: on a NEW collection it
+ * provisions the `$jsonSchema` validator derived from the ORM schema plus the
+ * declared indexes; when the collection ALREADY exists it upgrades the DB
+ * schema to match the current ORM schema — hot-swapping the validator via
+ * `collMod` only when it has actually drifted, and creating any newly-declared
+ * indexes. It never drops indexes or data (destructive reconciliation stays
+ * explicit via `syncIndexes`), so it is safe to call on every boot: the Mongo
+ * schema follows the app schema automatically as models change.
+ *
+ * `updateSchema` hot-swaps a validator explicitly (via `collMod`);
+ * `syncIndexes` reconciles index drift (create missing, drop undeclared).
  */
 declare const makeSchemaOps: (client: Db, _logger: LoggerLike, opts: SchemaOpsOptions) => {
     createSchema: (collection: string, createCollectionOptions?: CreateCollectionOptions) => Promise<void>;