@owlmeans/mongo-resource 0.1.18-rc.9 → 0.1.18

package/build/types.d.ts

@@ -1,4 +1,4 @@
-import type { Resource, ResourceRecord, ResourceDbService, DbLocker, ResourceLocker, MigratableResource } from '@owlmeans/resource';
+import type { Resource, ResourceRecord, ResourceDbService, DbLocker, LockableResource, MigratableResource, MigrationRegistry } from '@owlmeans/resource';
 import type { Collection, CreateIndexesOptions, Db, IndexSpecification, MongoClient } from 'mongodb';
 import type { AnySchema } from 'ajv';
 /**
@@ -38,7 +38,7 @@ export interface MongoRefOptions {
     resource?: string;
     noIndex?: boolean;
 }
-export interface MongoResource<T extends ResourceRecord> extends Resource<T>, ResourceLocker<T>, MigratableResource<MongoTx> {
+export interface MongoResource<T extends ResourceRecord> extends Resource<T>, LockableResource<T>, MigratableResource<MongoTx, MongoResource<T>> {
     name?: string;
     /**
      * The db-config alias this resource was registered against.
@@ -59,13 +59,14 @@ export interface MongoResource<T extends ResourceRecord> extends Resource<T>, Re
     collection: Collection;
     db: () => Promise<Db>;
     client: () => Promise<MongoClient>;
-    index: <Type extends MongoResource<T>>(name: string, index: IndexSpecification, options?: CreateIndexesOptions) => Type;
+    index: (name: string, index: IndexSpecification, options?: CreateIndexesOptions) => this;
     /**
      * Declare that a field stores another record's id.
      *
      * Chainable and idempotent like {@link MigratableResource.migration}, and stored the same
-     * way — per alias at module scope — because losing the declaration to a context rebuild
-     * would silently stop the string/ObjectId conversion for the field.
+     * way — per alias at module scope — so a maker that runs more than once for the same alias
+     * re-declares the same entry rather than losing it. A lost declaration would silently stop
+     * the string/ObjectId conversion for the field.
      *
      * Declare only fields whose values really are mongo ids (assigned from another record's
      * `id`). Composite keys, external provider ids, DIDs and business slugs must stay
@@ -78,4 +79,9 @@ export interface MongoResource<T extends ResourceRecord> extends Resource<T>, Re
 }
 export interface MongoDbService extends ResourceDbService<Db, MongoClient>, DbLocker<ResourceRecord> {
 }
+export interface MongoDeclaration {
+    migrations: MigrationRegistry<MongoTx>;
+    /** Declared ObjectId references, keyed by field. Registered via `resource.reference()`. */
+    references: Map<string, MongoReference>;
+}
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,QAAQ,EAAE,cAAc,EAAE,kBAAkB,EAC1F,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAEpC;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,EAAE,CAAA;IACN,wCAAwC;IACxC,UAAU,EAAE,UAAU,CAAA;IACtB,yFAAyF;IACzF,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,UAAU,CAAA;IACnC,mGAAmG;IACnG,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC;IAC1H,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,kBAAkB,CAAC;QAAC,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAA;IAC5F,UAAU,EAAE,UAAU,CAAA;IACtB,EAAE,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAA;IACrB,MAAM,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IAClC,KAAK,EAAE,CAAC,IAAI,SAAS,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAA;IACvH;;;;;;;;;;OAUG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,KAAK,IAAI,CAAA;IACnE,6CAA6C;IAC7C,UAAU,EAAE,MAAM,cAAc,EAAE,CAAA;IAClC,WAAW,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC;CACnG"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACxJ,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,EAAE,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAA;AAEpC;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,EAAE,CAAA;IACN,wCAAwC;IACxC,UAAU,EAAE,UAAU,CAAA;IACtB,yFAAyF;IACzF,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,UAAU,CAAA;IACnC,mGAAmG;IACnG,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/F,kBAAkB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,kBAAkB,CAAC;QAAC,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAA;IAC5F,UAAU,EAAE,UAAU,CAAA;IACtB,EAAE,EAAE,MAAM,OAAO,CAAC,EAAE,CAAC,CAAA;IACrB,MAAM,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IAClC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAA;IACxF;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,KAAK,IAAI,CAAA;IACnE,6CAA6C;IAC7C,UAAU,EAAE,MAAM,cAAc,EAAE,CAAA;IAClC,WAAW,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,cAAe,SAAQ,iBAAiB,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC;CACnG;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAA;IACtC,2FAA2F;IAC3F,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CACxC"}

package/build/types.local.d.ts

@@ -0,0 +1,4 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+export type Config = ServerConfig;
+export type Context<C extends Config = Config> = ServerContext<C>;
+//# sourceMappingURL=types.local.d.ts.map

package/build/types.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE3E,MAAM,MAAM,MAAM,GAAG,YAAY,CAAA;AAEjC,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,aAAa,CAAC,CAAC,CAAC,CAAA"}

package/build/types.local.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.local.js.map

package/build/types.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":""}

package/build/utils/consts.local.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Operators mongo speaks natively and that mean the same thing here as they do in SQL and in
+ * the in-memory engine. Everything else in the shared vocabulary is rewritten below into a
+ * mongo expression with the same meaning — a criteria object has to answer identically
+ * whichever store it reaches.
+ */
+export declare const NATIVE: Set<string>;
+/** What the SERVER reports about an index rather than what a declaration asks for — never a
+ *  reason to recreate one. `collation` is here because a collection's default collation is
+ *  reported on every index in it, including the ones declared without any. */
+export declare const REPORTED_FIELDS: Set<string>;
+export declare const VALID_COLLECTION_NAME: RegExp;
+/**
+ * The only shape a stored reference is converted from. Deliberately stricter than
+ * `ObjectId.isValid`, which also accepts any 12 character string and would silently
+ * swallow short business keys.
+ */
+export declare const HEX24: RegExp;
+/**
+ * Operators whose operand is never an id — a 24 hex string under `$regex` is a pattern,
+ * not a reference.
+ */
+export declare const OPAQUE_OPERATORS: string[];
+export declare const LOGICAL_OPERATORS: string[];
+//# sourceMappingURL=consts.local.d.ts.map

package/build/utils/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../../src/utils/consts.local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,MAAM,aAAiF,CAAA;AAEpG;;8EAE8E;AAC9E,eAAO,MAAM,eAAe,aAE1B,CAAA;AAMF,eAAO,MAAM,qBAAqB,QAAqB,CAAA;AAEvD;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAsB,CAAA;AAExC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,UAAwE,CAAA;AAErG,eAAO,MAAM,iBAAiB,UAA0B,CAAA"}

package/build/utils/consts.local.js

@@ -0,0 +1,31 @@
+/**
+ * Operators mongo speaks natively and that mean the same thing here as they do in SQL and in
+ * the in-memory engine. Everything else in the shared vocabulary is rewritten below into a
+ * mongo expression with the same meaning — a criteria object has to answer identically
+ * whichever store it reaches.
+ */
+export const NATIVE = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin', '$regex']);
+/** What the SERVER reports about an index rather than what a declaration asks for — never a
+ *  reason to recreate one. `collation` is here because a collection's default collation is
+ *  reported on every index in it, including the ones declared without any. */
+export const REPORTED_FIELDS = new Set([
+    'v', 'ns', 'name', 'collation', 'textIndexVersion', '2dsphereIndexVersion', 'background'
+]);
+// Collection names must use only alphanumeric characters, underscore, and hyphen — no
+// colons or other delimiters. This guard enforces the rule for every collection created
+// through makeMongoResource across all projects (common/internal/app), failing fast at
+// initialization rather than silently creating a badly-named collection.
+export const VALID_COLLECTION_NAME = /^[a-zA-Z0-9_-]+$/;
+/**
+ * The only shape a stored reference is converted from. Deliberately stricter than
+ * `ObjectId.isValid`, which also accepts any 12 character string and would silently
+ * swallow short business keys.
+ */
+export const HEX24 = /^[0-9a-fA-F]{24}$/;
+/**
+ * Operators whose operand is never an id — a 24 hex string under `$regex` is a pattern,
+ * not a reference.
+ */
+export const OPAQUE_OPERATORS = ['$regex', '$options', '$type', '$size', '$mod', '$exists', '$where'];
+export const LOGICAL_OPERATORS = ['$and', '$or', '$nor'];
+//# sourceMappingURL=consts.local.js.map

package/build/utils/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../../src/utils/consts.local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;AAEpG;;8EAE8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IACrC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,YAAY;CACzF,CAAC,CAAA;AAEF,sFAAsF;AACtF,wFAAwF;AACxF,uFAAuF;AACvF,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAA;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,mBAAmB,CAAA;AAExC;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAA;AAErG,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA"}

package/build/utils/criteria/types.d.ts

@@ -0,0 +1,27 @@
+import type { Criteria, Sort } from '@owlmeans/resource';
+import type { Document } from 'mongodb';
+import type { MongoReference } from '../../types.js';
+/** The portable criteria and sort vocabulary, as the documents a collection takes. */
+export interface MongoCriteriaHelper {
+    /**
+     * Translate `Criteria<T>` into the filter a collection takes.
+     *
+     * Two passes: the shared operator vocabulary becomes mongo expressions, then
+     * `mongoRefHelper.marshalCriteria` converts the values addressed at `_id` or at a declared
+     * reference into `ObjectId`s and maps the `id` alias onto `_id`. Both halves are needed — a
+     * criteria object carries string ids and portable operators, a collection stores neither.
+     *
+     * An empty result is an empty filter, which matches everything. Callers that must not act on
+     * "everything" — `purge` — check for it themselves.
+     *
+     * @throws {UnsupportedArgumentError}
+     */
+    criteriaToFilter: (criteria: Criteria<any> | undefined, refs: Map<string, MongoReference>) => Document;
+    /**
+     * Translate `Sort<T>[]` into a mongo sort document. A bare field name is ascending, and `id`
+     * addresses `_id` — documents never store an `id` field, so sorting by the name records carry
+     * would silently order by nothing.
+     */
+    sortToMongo: (sort?: Sort<any>[]) => Document | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/utils/criteria/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/criteria/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;;;;;OAYG;IACH,gBAAgB,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,QAAQ,CAAA;IACtG;;;;OAIG;IACH,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,QAAQ,GAAG,SAAS,CAAA;CAC1D"}

package/build/utils/criteria/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/utils/criteria/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/criteria/types.ts"],"names":[],"mappings":""}

package/build/utils/criteria.d.ts

@@ -0,0 +1,9 @@
+import { type Criteria } from '@owlmeans/resource';
+import type { Document } from 'mongodb';
+import type { MongoReference } from '../types.js';
+import type { MongoCriteriaHelper } from './criteria/types.js';
+export declare const createMongoCriteriaHelper: () => MongoCriteriaHelper;
+export declare const mongoCriteriaHelper: MongoCriteriaHelper;
+/** @deprecated compat:factory-refactor — use `mongoCriteriaHelper.criteriaToFilter(…)` */
+export declare const criteriaToFilter: (criteria: Criteria<any> | undefined, refs: Map<string, MongoReference>) => Document;
+//# sourceMappingURL=criteria.d.ts.map

package/build/utils/criteria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria.d.ts","sourceRoot":"","sources":["../../src/utils/criteria.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,QAAQ,EAAa,MAAM,oBAAoB,CAAA;AACvF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAsF9D,eAAO,MAAM,yBAAyB,QAAO,mBAwI5C,CAAA;AAED,eAAO,MAAM,mBAAmB,qBAA8B,CAAA;AAE9D,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB,aAAc,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,QAAQ,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,KAAG,QACpD,CAAA"}

package/build/utils/criteria.js

@@ -0,0 +1,204 @@
+import { UnsupportedArgumentError } from '@owlmeans/resource';
+import { mongoRefHelper } from './refs.js';
+import { NATIVE } from './consts.local.js';
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * A SQL `LIKE` pattern as an anchored regular expression: `%` is any run, `_` is one
+ * character, and `\` escapes either. The mapping is the one the in-memory engine applies, so
+ * the same pattern selects the same records against a collection.
+ */
+const likeToRegExp = (pattern) => {
+    let source = '';
+    for (let index = 0; index < pattern.length; index++) {
+        const char = pattern[index];
+        if (char === '\\' && index + 1 < pattern.length) {
+            source += escapeRegExp(pattern[++index]);
+            continue;
+        }
+        if (char === '%') {
+            source += '.*';
+            continue;
+        }
+        if (char === '_') {
+            source += '.';
+            continue;
+        }
+        source += escapeRegExp(char);
+    }
+    return `^${source}$`;
+};
+const asArray = (operand) => Array.isArray(operand) ? operand : [operand];
+/**
+ * One operator as the mongo field expression that answers it.
+ *
+ * `$exists` and `$null` both become a comparison against `null`, not mongo's own `$exists`:
+ * the shared vocabulary asks whether a field *has a value*, which the relational and
+ * in-memory stores answer as `IS NULL` / `value == null`. Mongo's `$exists` answers a
+ * different question — whether the key is present — and a key present but null would part
+ * the three stores over one criteria object.
+ *
+ * @throws {UnsupportedArgumentError} on an operator this store cannot answer.
+ */
+const operatorToFilter = (field, operator, operand) => {
+    if (NATIVE.has(operator)) {
+        return { [operator]: operand };
+    }
+    switch (operator) {
+        case '$exists':
+            return operand === false ? { $eq: null } : { $ne: null };
+        case '$null':
+            return operand === false ? { $ne: null } : { $eq: null };
+        case '$like':
+            return { $regex: likeToRegExp(`${operand}`) };
+        case '$ilike':
+            return { $regex: likeToRegExp(`${operand}`), $options: 'i' };
+        case '$startsWith':
+            return { $regex: `^${escapeRegExp(`${operand}`)}` };
+        case '$endsWith':
+            return { $regex: `${escapeRegExp(`${operand}`)}$` };
+        case '$between':
+            if (!Array.isArray(operand) || operand.length !== 2) {
+                throw new UnsupportedArgumentError(`criteria:$between:${field}`);
+            }
+            return { $gte: operand[0], $lte: operand[1] };
+        /** Array membership, mirroring the postgres array operators `@>`, `<@` and `&&`. */
+        case '$contains':
+            return { $all: asArray(operand) };
+        case '$contained':
+            /**
+             * Nothing outside the operand list may appear in the field. The `$ne: null` keeps an
+             * absent field out of the result — `$not` alone is satisfied by a document that has no
+             * such field at all, where the relational store answers NULL and matches nothing.
+             */
+            return { $not: { $elemMatch: { $nin: asArray(operand) } }, $ne: null };
+        case '$overlaps':
+            return { $in: asArray(operand) };
+        default:
+            throw new UnsupportedArgumentError(`criteria-operator:${operator}`);
+    }
+};
+/**
+ * An object naming at least one `$` key is a spec, not a value to compare against. A Date and
+ * an array are values even though both are objects.
+ */
+const isOperatorSpec = (value) => value != null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+    && Object.keys(value).some(key => key.startsWith('$'));
+export const createMongoCriteriaHelper = () => {
+    const { marshalCriteria } = mongoRefHelper;
+    /**
+     * One field's criteria as mongo conditions. Operators that translate into the same mongo key —
+     * `$like` and `$startsWith` both produce `$regex` — are emitted as separate conditions rather
+     * than merged, so neither silently overwrites the other.
+     */
+    const fieldConditions = (field, spec) => {
+        const merged = {};
+        const conditions = [];
+        for (const [operator, operand] of Object.entries(spec)) {
+            if (operand === undefined) {
+                continue;
+            }
+            const fragment = operatorToFilter(field, operator, operand);
+            if (Object.keys(fragment).some(key => key in merged)) {
+                conditions.push({ [field]: fragment });
+                continue;
+            }
+            Object.assign(merged, fragment);
+        }
+        if (Object.keys(merged).length > 0) {
+            conditions.unshift({ [field]: merged });
+        }
+        return conditions;
+    };
+    /**
+     * Flatten the conditions into one filter document. Mongo reads sibling keys as a conjunction,
+     * so only the ones that would overwrite an earlier key — two `$regex` expressions over the
+     * same field, say — need an explicit `$and`.
+     */
+    const flatten = (conditions) => {
+        const filter = {};
+        const conflicting = [];
+        for (const condition of conditions) {
+            if (Object.keys(condition).some(key => key in filter)) {
+                conflicting.push(condition);
+                continue;
+            }
+            Object.assign(filter, condition);
+        }
+        if (conflicting.length > 0) {
+            filter.$and = [...(Array.isArray(filter.$and) ? filter.$and : []), ...conflicting];
+        }
+        return filter;
+    };
+    const build = (criteria) => {
+        const conditions = [];
+        for (const [key, raw] of Object.entries(criteria ?? {})) {
+            /**
+             * An untouched filter must never empty a list, so `undefined` is skipped rather than
+             * compared. `null` asks for the absence of a value.
+             */
+            if (raw === undefined) {
+                continue;
+            }
+            if (key === '$and' || key === '$or') {
+                const parts = (Array.isArray(raw) ? raw : [raw])
+                    .map(part => build(part))
+                    .filter(part => part.length > 0)
+                    .map(part => flatten(part));
+                if (parts.length > 0) {
+                    conditions.push(key === '$and' ? { $and: parts } : { $or: parts });
+                }
+                continue;
+            }
+            if (key === '$not') {
+                const inner = build(raw);
+                if (inner.length > 0) {
+                    /** Mongo has no top level `$not`; `$nor` over a single branch is its negation. */
+                    conditions.push({ $nor: [flatten(inner)] });
+                }
+                continue;
+            }
+            if (raw === null) {
+                conditions.push({ [key]: { $eq: null } });
+                continue;
+            }
+            if (isOperatorSpec(raw)) {
+                conditions.push(...fieldConditions(key, raw));
+                continue;
+            }
+            if (Array.isArray(raw)) {
+                /**
+                 * A bare array means "any of these", exactly as it does against a relational store.
+                 * Exact array equality stays reachable as `{ $eq: [...] }`.
+                 */
+                conditions.push({ [key]: { $in: raw } });
+                continue;
+            }
+            conditions.push({ [key]: raw });
+        }
+        return conditions;
+    };
+    const criteriaToFilter = (criteria, refs) => {
+        const conditions = build(criteria);
+        if (conditions.length < 1) {
+            return {};
+        }
+        return marshalCriteria(flatten(conditions), refs) ?? {};
+    };
+    const sortToMongo = (sort) => {
+        if (sort == null || sort.length < 1) {
+            return undefined;
+        }
+        return sort.reduce((order, entry) => {
+            const [field, direction] = typeof entry === 'string'
+                ? [entry, 1]
+                : [entry.field, entry.order === 'desc' ? -1 : 1];
+            order[field === 'id' ? '_id' : field] = direction;
+            return order;
+        }, {});
+    };
+    return { criteriaToFilter, sortToMongo };
+};
+export const mongoCriteriaHelper = createMongoCriteriaHelper();
+/** @deprecated compat:factory-refactor — use `mongoCriteriaHelper.criteriaToFilter(…)` */
+export const criteriaToFilter = (criteria, refs) => mongoCriteriaHelper.criteriaToFilter(criteria, refs);
+//# sourceMappingURL=criteria.js.map

package/build/utils/criteria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria.js","sourceRoot":"","sources":["../../src/utils/criteria.ts"],"names":[],"mappings":"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"}

package/build/utils/index.d.ts

@@ -4,4 +4,5 @@ export * from './name.js';
 export * from './life-cycle.js';
 export * from './migrations.js';
 export * from './refs.js';
+export * from './criteria.js';
 //# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/build/utils/index.js

@@ -4,4 +4,5 @@ export * from './name.js';
 export * from './life-cycle.js';
 export * from './migrations.js';
 export * from './refs.js';
+export * from './criteria.js';
 //# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/build/utils/indexes/types.d.ts

@@ -0,0 +1,19 @@
+import type { ResourceRecord } from '@owlmeans/resource';
+import type { Collection, Document } from 'mongodb';
+import type { MongoResource } from '../../types.js';
+/** A collection's indexes against the ones its resource declares. */
+export interface MongoIndexUtils {
+    /**
+     * Whether an index the database already holds differs from the one declared.
+     *
+     * Mongo returns an index's options in ITS order, not the declaration's, so comparing the two
+     * documents as JSON reported every index as changed — and every boot then dropped and recreated
+     * every index. That is invisible until two processes boot at once, when the second one's drop
+     * fails with `IndexNotFound` and takes the service down with it. Only the KEY is order-sensitive
+     * (a compound index is its key order); options are a set.
+     */
+    indexChanged: (existing: Document, proposed: Document) => boolean;
+    /** Create the declared indexes the collection lacks and recreate the ones that changed. */
+    updateIndexes: (collection: Collection, resource: MongoResource<ResourceRecord>) => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/utils/indexes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/indexes/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,YAAY,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAA;IACjE,2FAA2F;IAC3F,aAAa,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClG"}

package/build/utils/indexes/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/utils/indexes/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/indexes/types.ts"],"names":[],"mappings":""}

package/build/utils/indexes.d.ts

@@ -1,5 +1,4 @@
-import type { ResourceRecord } from '@owlmeans/resource';
-import type { MongoResource } from '../types.js';
-import type { Collection } from 'mongodb';
-export declare const updateIndexes: (collection: Collection, resource: MongoResource<ResourceRecord>) => Promise<void>;
+import type { MongoIndexUtils } from './indexes/types.js';
+export declare const createMongoIndexUtils: () => MongoIndexUtils;
+export declare const mongoIndexUtils: MongoIndexUtils;
 //# sourceMappingURL=indexes.d.ts.map

package/build/utils/indexes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../../src/utils/indexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,eAAO,MAAM,aAAa,eAAsB,UAAU,YAAY,aAAa,CAAC,cAAc,CAAC,kBAiClG,CAAA"}
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../../src/utils/indexes.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAQzD,eAAO,MAAM,qBAAqB,QAAO,eA0CxC,CAAA;AAED,eAAO,MAAM,eAAe,iBAA0B,CAAA"}

package/build/utils/indexes.js

@@ -1,34 +1,50 @@
-export const updateIndexes = async (collection, resource) => {
-    if (resource.indexes != null) {
+import { logger } from '@owlmeans/log';
+import { REPORTED_FIELDS } from './consts.local.js';
+const log = logger('mongo-resource');
+const options = (spec) => Object.entries(spec)
+    .filter(([field]) => field !== 'key' && !REPORTED_FIELDS.has(field))
+    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+export const createMongoIndexUtils = () => {
+    const indexChanged = (existing, proposed) => {
+        // We do not recreate text indexes.
+        if ('weights' in existing)
+            return false;
+        if (JSON.stringify(existing.key) !== JSON.stringify(proposed.key))
+            return true;
+        return JSON.stringify(options(existing)) !== JSON.stringify(options(proposed));
+    };
+    const updateIndexes = async (collection, resource) => {
+        if (resource.indexes == null) {
+            return;
+        }
+        const present = await collection.indexes();
         await Promise.all(resource.indexes.map(async (index) => {
-            const _index = (await collection.indexes()).find(_index => _index.name === index.name);
-            if (_index != null) {
-                const existing = { ..._index };
-                if ('name' in existing) {
-                    delete existing.name;
-                }
-                if ('v' in existing) {
-                    delete existing.v;
-                }
-                const propsed = { key: index.index, ...index.options };
-                // We do not recreate text indexes
-                if (JSON.stringify(existing) !== JSON.stringify(propsed) && !('weights' in existing)) {
-                    console.info(JSON.stringify(existing));
-                    console.info(JSON.stringify(propsed));
-                    console.debug(`Recreate index ${resource.alias} : ${index.name}`);
-                    await collection.dropIndex(index.name);
-                    await collection.createIndex(index.index, {
-                        name: index.name, ...((index.options != null) ? index.options : {})
-                    });
-                }
+            const create = async () => await collection.createIndex(index.index, {
+                name: index.name, ...((index.options != null) ? index.options : {})
+            });
+            const existing = present.find(_index => _index.name === index.name);
+            if (existing == null) {
+                log.debug('Create index', { resource: resource.alias, index: index.name });
+                await create();
+                return;
             }
-            else {
-                console.debug(`Create index ${resource.alias} : ${index.name}`);
-                await collection.createIndex(index.index, {
-                    name: index.name, ...((index.options != null) ? index.options : {})
-                });
+            if (!indexChanged(existing, { key: index.index, ...index.options })) {
+                return;
             }
+            log.debug('Recreate index', { resource: resource.alias, index: index.name });
+            try {
+                await collection.dropIndex(index.name);
+            }
+            catch (e) {
+                // IndexNotFound: another process booting alongside this one dropped it first — it is
+                // recreating the same declaration, so there is nothing here to fail over.
+                if (e.code !== 27)
+                    throw e;
+            }
+            await create();
         }));
-    }
+    };
+    return { indexChanged, updateIndexes };
 };
+export const mongoIndexUtils = createMongoIndexUtils();
 //# sourceMappingURL=indexes.js.map

package/build/utils/indexes.js.map

@@ -1 +1 @@
-{"version":3,"file":"indexes.js","sourceRoot":"","sources":["../../src/utils/indexes.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,UAAsB,EAAE,QAAuC,EAAE,EAAE;IACrG,IAAI,QAAQ,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CACpC,KAAK,EAAC,KAAK,EAAC,EAAE;YACZ,MAAM,MAAM,GAAG,CAAC,MAAM,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAA;YACtF,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;gBACnB,MAAM,QAAQ,GAAG,EAAE,GAAG,MAAM,EAAE,CAAA;gBAC9B,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;oBACvB,OAAO,QAAQ,CAAC,IAAI,CAAA;gBACtB,CAAC;gBACD,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;oBACpB,OAAO,QAAQ,CAAC,CAAC,CAAA;gBACnB,CAAC;gBACD,MAAM,OAAO,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAA;gBACtD,kCAAkC;gBAClC,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,QAAQ,CAAC,EAAE,CAAC;oBACrF,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAA;oBACtC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAA;oBACrC,OAAO,CAAC,KAAK,CAAC,kBAAkB,QAAQ,CAAC,KAAK,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;oBACjE,MAAM,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;oBACtC,MAAM,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE;wBACxC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;qBACpE,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,gBAAgB,QAAQ,CAAC,KAAK,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAA;gBAC/D,MAAM,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE;oBACxC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpE,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CACF,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"indexes.js","sourceRoot":"","sources":["../../src/utils/indexes.ts"],"names":[],"mappings":"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"}

package/build/utils/life-cycle/types.d.ts

@@ -0,0 +1,36 @@
+import type { BasicContext } from '@owlmeans/context';
+import type { DbConfig, ResourceRecord } from '@owlmeans/resource';
+import type { Collection } from 'mongodb';
+import type { MongoResource } from '../../types.js';
+/** A resource collection's initialization over one database. */
+export interface MongoLifeCycleUtils {
+    /**
+     * Bring a resource's collection to the shape its schema declares.
+     *
+     * Order is deliberate, and matches the Postgres counterpart:
+     *
+     *  1. probe for the collection
+     *  2. absent → *baseline* every registered migration; present → run the `pre` ones
+     *     (including the system `$ref:` migrations that convert declared references)
+     *  3. create the collection, or update its validator and indexes
+     *  4. present → run the `post` migrations
+     *  5. reconcile declared references — the second half of their double check: the ledger
+     *     said whether the `$ref:` migration ran, this probes the collection itself and
+     *     converts whatever strings still slipped through
+     *
+     * Step 2 is what stops the two mechanisms colliding. A `pre` migration runs before the
+     * validator is tightened, so it can reshape documents the new validator would reject. On a
+     * collection this call just created there is nothing to reshape — replaying a historical
+     * migration against a collection born in its final shape would at best scan for nothing —
+     * so the migrations are recorded as satisfied instead of run.
+     *
+     * `context` is optional so the existing three-argument call keeps working; without it a
+     * migration's `use`/`ref` can only address the owning resource.
+     */
+    initializeCollection: (config: DbConfig, resource: MongoResource<ResourceRecord>, context?: BasicContext<any>) => Promise<Collection>;
+    /** Create the collection with its validator and its declared indexes. */
+    createCollection: (name: string, resource: MongoResource<ResourceRecord>) => Promise<Collection>;
+    /** Replace the validator of an existing collection and bring its indexes up to date. */
+    updateCollection: (name: string, resource: MongoResource<ResourceRecord>) => Promise<Collection>;
+}
+//# sourceMappingURL=types.d.ts.map