@ignex/ninox 0.1.5 → 0.1.6

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

@@ -1467,6 +1467,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 +1556,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;
 }
 
 /**
@@ -2420,9 +2427,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>;

package/dist/index.js

@@ -3142,13 +3142,28 @@ var probeDebugQuery = async () => {
     debugQueryCache = null;
   }
 };
+var sanitizeDebugParams = (value) => {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    try {
+      return String(value);
+    } catch {
+      return "[unserializable]";
+    }
+  }
+};
 var traceDbOp = async (logger, meta, fn, options = {}) => {
   const start = performance.now();
   logger.debug({ ...meta, operation: "start" }, "start");
   try {
-    if (debugQueryCache === void 0) await probeDebugQuery();
-    const debugQuery = debugQueryCache;
-    const result = debugQuery ? await debugQuery(`${meta.collection}.${meta.op}`, void 0, () => fn()) : await fn();
+    let debugQuery = options.debugQuery;
+    if (debugQuery === void 0) {
+      if (debugQueryCache === void 0) await probeDebugQuery();
+      debugQuery = debugQueryCache;
+    }
+    const params = meta.params === void 0 ? void 0 : sanitizeDebugParams(meta.params);
+    const result = debugQuery ? await debugQuery(`${meta.collection}.${meta.op}`, params, () => fn()) : await fn();
     const durationMs = performance.now() - start;
     logger.info({ ...meta, durationMs }, "ok");
     return result;
@@ -3164,11 +3179,12 @@ var traceDbOp = async (logger, meta, fn, options = {}) => {
 // src/service/op-deps.ts
 var makeOpDeps = (logger, dbLabel, resolve, wrapMongoErrors) => {
   const trace = (meta2, fn) => traceDbOp(logger, meta2, fn, { wrapMongoErrors });
-  const meta = (collection, op) => ({
+  const meta = (collection, op, params) => ({
     collection: String(collection),
     physicalCollection: resolve(String(collection)),
     db: dbLabel,
-    op
+    op,
+    ...params !== void 0 ? { params } : {}
   });
   return { trace, meta };
 };
@@ -3214,11 +3230,11 @@ var resolveDriftMode = (perOp, serviceDefault) => {
 };
 
 // src/service/crud-op.ts
-var defineCrudOp = async (deps2, collection, opName, execute, options, write = false) => {
+var defineCrudOp = async (deps2, collection, opName, execute, options, write = false, params) => {
   const resolved = resolveQueryOptions(options);
   const maxAttempts = write && resolved.retryWrites !== true ? 1 : resolved.maxAttempts;
   return deps2.trace(
-    deps2.meta(collection, opName),
+    deps2.meta(collection, opName, params),
     async () => withRetry(async () => execute(resolved), {
       maxAttempts,
       delayMs: resolved.retryDelayMs
@@ -3323,7 +3339,9 @@ var PipelineBuilder = class _PipelineBuilder {
       this.deps.logical,
       "mongo.pipeline",
       run,
-      this.deps.options
+      this.deps.options,
+      false,
+      { pipeline: this.stages }
     );
   }
   /** Run the pipeline and return the first output document (or null). */
@@ -3350,7 +3368,9 @@ var PipelineBuilder = class _PipelineBuilder {
       this.deps.logical,
       "mongo.pipeline.first",
       run,
-      this.deps.options
+      this.deps.options,
+      false,
+      { pipeline: this.stages }
     );
   }
   /** Streaming cursor (raw driver cursor; no retry / trace). */
@@ -3470,7 +3490,9 @@ var makeAggregateOps = (ctx) => {
       collection,
       "mongo.aggregate",
       (r) => coll(collection).aggregate(pipeline2, mergeAggOptions2(r.driverOpts, r.sdk)),
-      options
+      options,
+      false,
+      { pipeline: pipeline2 }
     );
   };
   const pipeline = (collection, options) => new PipelineBuilder({
@@ -3556,7 +3578,7 @@ var createCachedAggregate = (ctx) => {
     const noSession = !resolved.sdk.session;
     const useCache = cache !== void 0 && noSession && resolved.cache !== false && isCacheablePipeline(pipeline);
     const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
-    const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options);
+    const runDriver = () => defineCrudOp(deps2, collection, opName, execute, options, false, { pipeline });
     const key = useCache ? cache.key(
       cacheCollectionKey(client.databaseName, physical),
       stableHash([opName, pipeline, options])
@@ -3905,8 +3927,8 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
   );
   const coll = (name) => client.collection(resolve(String(name)));
   const toDriverFilter = (filter) => filter;
-  const run = (collection, opName, execute, options) => defineCrudOp(deps2, collection, opName, execute, options);
-  const writeRun = (collection, opName, execute, options) => defineCrudOp(deps2, collection, opName, execute, options, true);
+  const run = (collection, opName, execute, options, params) => defineCrudOp(deps2, collection, opName, execute, options, false, params);
+  const writeRun = (collection, opName, execute, options, params) => defineCrudOp(deps2, collection, opName, execute, options, true, params);
   const invalidate = (collection) => {
     opts.cache?.invalidateByCollection(
       cacheCollectionKey(client.databaseName, resolve(String(collection)))
@@ -3942,6 +3964,9 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
   const read = async (collection, opName, filter, options, execute, shape = "none", keyExtra) => {
     const physical = resolve(String(collection));
     const resolved = resolveQueryOptions(options);
+    const sentParams = { filter };
+    if (Object.keys(resolved.driverOpts).length > 0) sentParams.options = resolved.driverOpts;
+    if (keyExtra !== void 0) sentParams.field = keyExtra;
     const noSession = !resolved.sdk.session;
     const useCache = opts.cache !== void 0 && noSession && resolved.cache !== false;
     const shouldDedupe = resolved.dedupe !== false && (resolved.dedupe === true || opts.dedupeReads === true && noSession) && opts.inFlight !== void 0;
@@ -3963,7 +3988,7 @@ var createCrudContext = (client, dbLabel, logger, opts) => {
       );
     };
     const executeWrapped = () => deps2.trace(
-      deps2.meta(collection, opName),
+      deps2.meta(collection, opName, sentParams),
       () => withRetry(() => execute(resolved), {
         maxAttempts: resolved.maxAttempts,
         delayMs: resolved.retryDelayMs
@@ -4292,7 +4317,8 @@ var makeWriteOps = (ctx, readOps) => {
           insertOpts
         );
       },
-      options
+      options,
+      { doc }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterCreate", {
@@ -4325,7 +4351,8 @@ var makeWriteOps = (ctx, readOps) => {
           bulkOpts
         );
       },
-      options
+      options,
+      { docs }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterCreate", {
@@ -4354,7 +4381,8 @@ var makeWriteOps = (ctx, readOps) => {
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4383,7 +4411,8 @@ var makeWriteOps = (ctx, readOps) => {
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4416,7 +4445,8 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4449,7 +4479,8 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter, replacement: effective }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4477,7 +4508,8 @@ var makeWriteOps = (ctx, readOps) => {
           repOpts
         );
       },
-      options
+      options,
+      { filter, replacement }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4501,7 +4533,8 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return await coll(collection).deleteOne(toDriverFilter(filter), delOpts);
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterDelete", {
@@ -4525,7 +4558,8 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return await coll(collection).deleteMany(toDriverFilter(filter), delOpts);
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterDelete", {
@@ -4554,7 +4588,8 @@ var makeWriteOps = (ctx, readOps) => {
           fOpts
         );
       },
-      options
+      options,
+      { filter }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterDelete", {
@@ -4586,7 +4621,8 @@ var makeWriteOps = (ctx, readOps) => {
           updateOpts
         );
       },
-      options
+      options,
+      { filter, update: effective }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterDelete", {
@@ -4612,7 +4648,8 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return await coll(collection).updateOne(toDriverFilter(filter), formatted, updateOpts);
       },
-      options
+      options,
+      { filter, update: formatted }
     );
     invalidate(collection);
     await safeAfterHooks(String(collection), "afterUpdate", {
@@ -4644,7 +4681,8 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return await coll(collection).bulkWrite(writes, bulkOpts);
       },
-      options
+      options,
+      { operations }
     );
     invalidate(collection);
     return result;
@@ -4665,7 +4703,8 @@ var makeWriteOps = (ctx, readOps) => {
         };
         return await coll(collection).bulkWrite(operations, bulkOpts);
       },
-      options
+      options,
+      { operations }
     );
     invalidate(collection);
     return result;
@@ -4848,7 +4887,9 @@ var makePaginateCursor = (ctx) => {
         };
         return client.collection(resolve(String(collection))).find(filter, findOpts).sort(effectiveSort).limit(limit + 1).toArray();
       },
-      config.queryOptions
+      config.queryOptions,
+      false,
+      { filter, sort: effectiveSort, limit }
     );
     const hasMore = rows.length > limit;
     const page = backwards ? rows.slice(0, limit).reverse() : rows.slice(0, limit);
@@ -4974,40 +5015,63 @@ var optionSignature = (o) => JSON.stringify([
 ]);
 var indexKeyOf = (key, options) => `${JSON.stringify(Object.keys(key).map((k) => [k, key[k]]))}|${optionSignature(options)}`;
 var makeSchemaOps = (client, _logger, opts) => {
+  const readCollectionValidator = async (physical) => {
+    const info = await client.listCollections({ name: physical }).next();
+    return info?.options?.validator;
+  };
+  const ensureDeclaredIndexes = async (collection, physical, def) => {
+    const declared = def?.indexes ?? [];
+    if (declared.length === 0) return;
+    const handle = client.collection(physical);
+    const existing = new Set(
+      (await handle.listIndexes().toArray()).filter((i) => i.name !== "_id_").map((i) => indexKeyOf(i.key, i))
+    );
+    for (const index of declared) {
+      if (existing.has(indexKeyOf(index.key, index.options))) continue;
+      try {
+        await handle.createIndex(index.key, index.options);
+      } catch (err) {
+        if (err?.code === 85) {
+          throw new Error(
+            `Cannot apply declared index on "${collection}": an index with the same name/key already exists with different options. Run db.syncIndexes("${collection}") to reconcile index drift.`,
+            { cause: err }
+          );
+        }
+        throw err;
+      }
+    }
+  };
   const createSchema = async (collection, createCollectionOptions) => {
     const physical = opts.resolveCollectionName(collection);
     const def = opts.getDefinition(collection);
-    const validator = def?.schema ? toMongoValidator(def.schema) : void 0;
+    const createOptions = {
+      ...createCollectionOptions ?? {},
+      ...def?.schema ? { validator: toMongoValidator(def.schema) } : {}
+    };
+    let created = true;
     try {
-      await client.createCollection(physical, {
-        // Caller options FIRST, derived validator LAST — a stale `validator`
-        // key in the options must not clobber the schema-derived one.
-        ...createCollectionOptions ?? {},
-        ...validator ? { validator } : {}
-      });
+      await client.createCollection(physical, createOptions);
     } catch (err) {
-      if (err?.code === 48) {
-        throw new DomainError("COLLECTION_EXISTS", `Collection "${collection}" already exists`, {
-          physicalCollection: physical
-        });
-      }
-      throw err;
+      if (err?.code !== 48) throw err;
+      created = false;
     }
-    const indexes = def?.indexes ?? [];
-    if (indexes.length > 0) {
+    if (created) {
       try {
-        await client.collection(physical).createIndexes(
-          indexes.map((index) => ({
-            key: index.key,
-            ...index.options ?? {}
-          }))
-        );
+        await ensureDeclaredIndexes(collection, physical, def);
       } catch (err) {
         await client.dropCollection(physical).catch(() => {
         });
         throw err;
       }
+      return;
+    }
+    if (createOptions.validator) {
+      const current = await readCollectionValidator(physical);
+      if (JSON.stringify(current) !== JSON.stringify(createOptions.validator)) {
+        await client.command({ collMod: physical, validator: createOptions.validator });
+      }
     }
+    await ensureDeclaredIndexes(collection, physical, def);
   };
   const updateSchema = async (collection, schema) => {
     const physical = opts.resolveCollectionName(collection);