@owlmeans/mongo-resource 0.1.15 → 0.1.16

package/build/utils/refs.js

@@ -0,0 +1,197 @@
+import { MisshapedRecord } from '@owlmeans/resource';
+import { ObjectId } from 'mongodb';
+/**
+ * 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.
+ */
+const HEX24 = /^[0-9a-fA-F]{24}$/;
+export const isObjectIdHex = (value) => typeof value === 'string' && HEX24.test(value);
+/**
+ * Write side of a declared reference: the string id a record carries becomes the
+ * `ObjectId` the collection stores. Arrays convert elementwise.
+ *
+ * Strict on purpose — a declared reference holding something that is not a mongo id is
+ * either a mis-declared field (should never have been a reference) or a bug at the call
+ * site, and storing it as a string would silently reintroduce the mixed type state this
+ * mechanism exists to remove.
+ *
+ * @throws {MisshapedRecord}
+ */
+export const marshalReference = (field, value) => {
+    if (value == null) {
+        return value;
+    }
+    if (value instanceof ObjectId) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => marshalReference(field, item));
+    }
+    if (isObjectIdHex(value)) {
+        return new ObjectId(value);
+    }
+    throw new MisshapedRecord(`ref:${field}`);
+};
+/** Read side: `ObjectId` back to the string records carry. Tolerates not yet migrated strings. */
+export const demarshalReference = (value) => {
+    if (value instanceof ObjectId) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(demarshalReference);
+    }
+    return value;
+};
+/** Convert every declared reference of a fetched document back to string ids, in place. */
+export const demarshalRefs = (record, refs) => {
+    if (refs.size < 1) {
+        return record;
+    }
+    for (const field of refs.keys()) {
+        const value = record[field];
+        if (value != null) {
+            record[field] = demarshalReference(value);
+        }
+    }
+    return record;
+};
+/**
+ * Operators whose operand is never an id — a 24 hex string under `$regex` is a pattern,
+ * not a reference.
+ */
+const OPAQUE_OPERATORS = ['$regex', '$options', '$type', '$size', '$mod', '$exists', '$where'];
+const LOGICAL_OPERATORS = ['$and', '$or', '$nor'];
+const marshalCriteriaValue = (value) => {
+    if (typeof value === 'string') {
+        return isObjectIdHex(value) ? new ObjectId(value) : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(marshalCriteriaValue);
+    }
+    if (value != null && typeof value === 'object' && !(value instanceof ObjectId) && !(value instanceof Date)) {
+        return Object.fromEntries(Object.entries(value).map(([operator, operand]) => OPAQUE_OPERATORS.includes(operator)
+            ? [operator, operand]
+            : [operator, marshalCriteriaValue(operand)]));
+    }
+    return value;
+};
+/**
+ * Convert list criteria the way records are converted: values addressed at `_id` or at a
+ * declared reference become `ObjectId`s, and the `id` alias records actually carry is
+ * mapped onto `_id` — documents never store `id`, so before this mapping such criteria
+ * silently matched nothing.
+ *
+ * Tolerant by design: a value that is not 24 hex passes through unconverted. Criteria are
+ * matched against the collection, and against an `ObjectId` typed field a stray string
+ * matches nothing — which is exactly what it matched before the field was converted.
+ */
+export const marshalCriteria = (criteria, refs) => {
+    if (criteria == null) {
+        return criteria;
+    }
+    return Object.fromEntries(Object.entries(criteria).map(([key, value]) => {
+        if (LOGICAL_OPERATORS.includes(key) && Array.isArray(value)) {
+            return [key, value.map(sub => marshalCriteria(sub, refs))];
+        }
+        if (key === 'id' || key === '_id') {
+            return ['_id', marshalCriteriaValue(value)];
+        }
+        if (refs.has(key)) {
+            return [key, marshalCriteriaValue(value)];
+        }
+        return [key, value];
+    }));
+};
+/**
+ * Criteria for addressing a single record by a field — `get`/`load`/`update`/`delete`.
+ *
+ * `_id` keeps its historical strictness (an invalid id throws through the driver). The
+ * `id` alias and declared references convert tolerantly, so a caller probing a reference
+ * with a value that is not a mongo id gets "not found" rather than a throw.
+ */
+export const identityCriteria = (field, id, refs) => {
+    if (field === '_id') {
+        return { _id: new ObjectId(id) };
+    }
+    if (field === 'id') {
+        return { _id: isObjectIdHex(id) ? new ObjectId(id) : id };
+    }
+    if (refs.has(field)) {
+        return { [field]: isObjectIdHex(id) ? new ObjectId(id) : id };
+    }
+    return { [field]: id };
+};
+/**
+ * Name of the system migration that converts a reference field's stored strings.
+ *
+ * The `@1` is the body's version: the shared body below fingerprints identically for
+ * every field, so an edit to it would raise `MigrationConflict` against every ledger on
+ * the next boot. Any semantic change to {@link convertReferenceField} must bump this
+ * suffix instead — the old name stays applied, the new one runs (idempotently) once.
+ */
+export const refMigrationName = (field) => `$ref:${field}@1`;
+/** Ledger registered body of the system reference migration. */
+export const makeRefMigration = (field) => async (tx) => {
+    await convertReferenceField(tx.collection, field);
+};
+const convertScalar = (path) => ({
+    $cond: [
+        {
+            $and: [
+                { $eq: [{ $type: path }, 'string'] },
+                { $regexMatch: { input: path, regex: HEX24 } }
+            ]
+        },
+        { $toObjectId: path },
+        path
+    ]
+});
+/**
+ * Convert one reference field's stored string ids to `ObjectId`s — the body of the
+ * system migration and of the boot time reconciliation probe alike.
+ *
+ * Idempotent and interrupt safe: it matches only documents where the field (or one of
+ * its elements) is still a string, converts only values that are actually 24 hex, and
+ * leaves everything else exactly as it was. Safe to run concurrently from several
+ * replicas — a document converts once, the loser's filter no longer matches it.
+ *
+ * Validation is bypassed deliberately: at `Pre` stage the collection still carries the
+ * validator that declares the field a *string*, and after the switch a legacy document
+ * may violate the schema in unrelated ways — either would wedge the boot on a write
+ * that only makes the data more correct. (Bypassing requires the connection's user to
+ * hold the `bypassDocumentValidation` privilege — `dbOwner`/`root` do.)
+ */
+export const convertReferenceField = async (collection, field) => {
+    const result = await collection.updateMany(
+    /** An array valued field matches `$type: 'string'` when any element is a string. */
+    { [field]: { $type: 'string' } }, [{
+            $set: {
+                [field]: {
+                    $cond: [
+                        { $eq: [{ $type: `$${field}` }, 'array'] },
+                        { $map: { input: `$${field}`, as: 'ref', in: convertScalar('$$ref') } },
+                        convertScalar(`$${field}`)
+                    ]
+                }
+            }
+        }], { bypassDocumentValidation: true });
+    return result.modifiedCount;
+};
+/**
+ * The second half of the double check the reference migration promises: the ledger says
+ * whether the migration ran; this probes whether the collection actually holds no
+ * convertible strings — and repairs it when the two disagree (a restored backup, a
+ * write from a legacy process, a ledger created by hand).
+ */
+export const reconcileReferences = async (collection, refs, alias) => {
+    for (const ref of refs) {
+        const remnant = await collection.findOne({ [ref.field]: { $type: 'string', $regex: HEX24 } }, { projection: { _id: 1 } });
+        if (remnant != null) {
+            const converted = await convertReferenceField(collection, ref.field);
+            console.warn(`@owlmeans/mongo-resource: ${alias}.${ref.field} held string ids outside the migration`
+                + ` ledger — converted ${converted} document(s)`);
+        }
+    }
+};
+//# sourceMappingURL=refs.js.map

package/build/utils/refs.js.map

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

package/build/utils/schema.d.ts

@@ -1,4 +1,12 @@
 import type { AnySchema } from 'ajv';
 import type { Document } from 'mongodb';
+import type { MongoReference } from '../types.js';
+/**
+ * Declared references are stored as `ObjectId`s while the AJV schema — which describes
+ * the records the app exchanges — keeps calling them strings. The collection validator
+ * describes what's stored, so the reference fields are overridden here after the plain
+ * conversion. Nullability and array shape carry over from the declared property.
+ */
+export declare const applyReferenceTypes: (mongoSchema: Document, schema: AnySchema, refs: MongoReference[]) => Document;
 export declare const schemaToMongoSchema: (schema: AnySchema) => Document;
 //# sourceMappingURL=schema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,KAAK,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,eAAO,MAAM,mBAAmB,GAAI,QAAQ,SAAS,KAAG,QAmCvD,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,KAAK,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,QAAQ,EAAE,QAAQ,SAAS,EAAE,MAAM,cAAc,EAAE,KAC/D,QAoBF,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,QAAQ,SAAS,KAAG,QAmCvD,CAAA"}

package/build/utils/schema.js

@@ -1,3 +1,28 @@
+/**
+ * Declared references are stored as `ObjectId`s while the AJV schema — which describes
+ * the records the app exchanges — keeps calling them strings. The collection validator
+ * describes what's stored, so the reference fields are overridden here after the plain
+ * conversion. Nullability and array shape carry over from the declared property.
+ */
+export const applyReferenceTypes = (mongoSchema, schema, refs) => {
+    if (mongoSchema.properties == null || refs.length < 1) {
+        return mongoSchema;
+    }
+    const properties = schema.properties ?? {};
+    for (const ref of refs) {
+        const declared = properties[ref.field];
+        if (declared == null || mongoSchema.properties[ref.field] == null) {
+            continue;
+        }
+        mongoSchema.properties[ref.field] = declared.type === 'array'
+            ? {
+                bsonType: declared.nullable ? ['array', 'null'] : 'array',
+                items: { bsonType: 'objectId' }
+            }
+            : { bsonType: declared.nullable ? ['objectId', 'null'] : 'objectId' };
+    }
+    return mongoSchema;
+};
 export const schemaToMongoSchema = (schema) => {
     const _schema = schema;
     if (_schema.type !== 'object') {

package/build/utils/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/utils/schema.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,WAAqB,EAAE,MAAiB,EAAE,IAAsB,EACtD,EAAE;IACZ,IAAI,WAAW,CAAC,UAAU,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,WAAW,CAAA;IACpB,CAAC;IACD,MAAM,UAAU,GACb,MAAkC,CAAC,UAAU,IAAI,EAAE,CAAA;IACtD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACtC,IAAI,QAAQ,IAAI,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;YAClE,SAAQ;QACV,CAAC;QACD,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC,IAAI,KAAK,OAAO;YAC3D,CAAC,CAAC;gBACA,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO;gBACzD,KAAK,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE;aAChC;YACD,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAA;IACzE,CAAC;IAED,OAAO,WAAW,CAAA;AACpB,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAiB,EAAY,EAAE;IACjE,MAAM,OAAO,GAAG,MAAiC,CAAA;IAEjD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,WAAW,CAAC,sDAAsD,CAAC,CAAA;IAC/E,CAAC;IAED,MAAM,WAAW,GAAa;QAC5B,QAAQ,EAAE,QAAQ;QAClB,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;YACpC,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU;gBAC7B,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;gBACnD,iBAAiB,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;YAC7C,CAAC,CAAC,SAAS;QACb,oBAAoB,EAClB,OAAO,CAAC,oBAAoB,IAAI,IAAI;YAClC,CAAC,CAAC,2BAA2B,CAAC,OAAO,CAAC,oBAAoB,CAAC;YAC3D,CAAC,CAAC,KAAK;QACX,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpE,CAAA;IAED,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,WAAW,CAAC,QAAQ,GAAG,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACvD,CAAC;IAED,IAAI,YAAY,IAAI,WAAW,IAAI,WAAW,CAAC,UAAU,IAAI,IAAI,EAAE,CAAC;QAClE,OAAO,WAAW,CAAC,UAAU,CAAA;IAC/B,CAAC;IAED,IAAI,UAAU,IAAI,WAAW,IAAI,WAAW,CAAC,QAAQ,IAAI,IAAI;WACxD,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9E,OAAO,WAAW,CAAC,QAAQ,CAAA;IAC7B,CAAC;IAED,OAAO,WAAW,CAAA;AACpB,CAAC,CAAA;AAED,MAAM,2BAA2B,GAAG,CAAC,oBAAyC,EAAsB,EAAE;IACpG,IAAI,OAAO,oBAAoB,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,oBAAoB,CAAA;IAC7B,CAAC;IAED,OAAO,iBAAiB,CAAC,oBAA+C,CAAC,CAAA;AAC3E,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CAAC,UAAqC,EAAY,EAAE,CAC5E,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;IACjE,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,WAAW,CAAC,0DAA0D,CAAC,CAAA;IACnF,CAAC;IAED,OAAO,CAAC,GAAG,EAAE,iBAAiB,CAAC,KAAgC,CAAC,CAAC,CAAA;AACnE,CAAC,CAAC,CAAC,CAAA;AAEL,MAAM,qBAAqB,GAAG,CAAC,KAAgD,EAAY,EAAE,CAC3F,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;KAC5D,MAAM,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AAEvE,MAAM,iBAAiB,GAAG,CAAC,KAA8B,EAAqB,EAAE;IAC9E,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;SACjE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IAClD,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACnB,CAAC;IAED,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC3C,CAAC,CAAA;AAED,MAAM,iBAAiB,GAAG,CAAC,KAA8B,EAAY,EAAE;IACrE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,IAAI,YAAY,IAAI,KAAK,IAAI,sBAAsB,IAAI,KAAK,EAAE,CAAC;YAC7D,OAAO;gBACL,GAAG,mBAAmB,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;gBACpD,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC;aACnC,CAAA;QACH,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAA;IAC/C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAC5B,sFAAsF;QACtF,wFAAwF;QACxF,yFAAyF;QACzF,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,KAAK,CAAC;QACtH,CAAC,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAA;AAC5C,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/mongo-resource",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -26,13 +26,13 @@
     "mongodb": "*"
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.15",
-    "@owlmeans/resource": "^0.1.15",
-    "@owlmeans/server-context": "^0.1.15"
+    "@owlmeans/context": "^0.1.16",
+    "@owlmeans/resource": "^0.1.16",
+    "@owlmeans/server-context": "^0.1.16"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-integration": "^0.1.15",
+    "@owlmeans/test-integration": "^0.1.16",
     "@types/bun": "^1.3.14",
     "@types/node": "^26.1.0",
     "mongodb": "^6.9.0",

package/src/consts.ts

@@ -2,3 +2,23 @@
 export const DEFAULT_DB_ALIAS = 'mongo'
 
 export const DEFAULT_PAGE_SIZE = 10
+
+/**
+ * Collection that records which code-registered migrations have already been applied.
+ *
+ * One ledger per database, which is the right boundary: `dbName()` already varies the
+ * database per Entity/User layer, so a tenant's migrations are tracked with the tenant's
+ * data and dropping the database drops the ledger with it.
+ */
+export const DEF_MIGRATIONS_COLLECTION = '_owlmeans_migrations'
+
+/**
+ * How long a replica waits for another replica's in-flight migration before giving up.
+ * Bounded because the alternative is a pod that hangs on boot with no diagnostic.
+ */
+export const DEF_MIGRATION_WAIT = 60000
+
+export const DEF_MIGRATION_POLL = 250
+
+/** `E11000` — the unique index on `(alias, name)` rejecting a second replica's claim. */
+export const MONGO_DUPLICATE_KEY = 11000

package/src/declarations.ts

@@ -0,0 +1,42 @@
+import { createMigrationRegistry } from '@owlmeans/resource'
+import type { MigrationRegistry } from '@owlmeans/resource'
+
+import type { MongoReference, MongoTx } from './types.js'
+
+export interface MongoDeclaration {
+  migrations: MigrationRegistry<MongoTx>
+  /** Declared ObjectId references, keyed by field. Registered via `resource.reference()`. */
+  references: Map<string, MongoReference>
+}
+
+/**
+ * Per-alias migration store, held at module scope rather than on the resource object.
+ *
+ * `reinitializeContext` rebuilds every resource from the maker, which drops anything a
+ * caller attached by chaining afterwards. For indexes that is survivable — they already
+ * exist in the database and `updateIndexes` only ever adds. Migrations are not: a layer
+ * switch points the resource at a *different* database, and a registry emptied by the
+ * rebuild would mean the entity database silently never gets the transformation. Keying
+ * by alias makes the declarations outlive any number of context switches.
+ */
+const declarations: Map<string, MongoDeclaration> = new Map()
+
+export const getDeclaration = (alias: string): MongoDeclaration => {
+  let declaration = declarations.get(alias)
+  if (declaration == null) {
+    declaration = { migrations: createMigrationRegistry<MongoTx>(), references: new Map() }
+    declarations.set(alias, declaration)
+  }
+
+  return declaration
+}
+
+/** Testing seam — drops every declaration so a spec can redeclare a resource from scratch. */
+export const resetDeclarations = (alias?: string): void => {
+  if (alias == null) {
+    declarations.clear()
+
+    return
+  }
+  declarations.delete(alias)
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 
 export type * from './types.js'
 export * from './consts.js'
+export * from './declarations.js'
+export * from './utils/migrations.js'
+export * from './utils/refs.js'
 export * from './resource.js'
-export * from './helper.js'
+export * from './helper.js'

package/src/resource.ts

@@ -1,14 +1,20 @@
 import { appendContextual, assertContext } from '@owlmeans/context'
 import type { BasicContext, Contextual } from '@owlmeans/context'
 import { DEFAULT_DB_ALIAS, DEFAULT_PAGE_SIZE } from './consts.js'
+import { MigrationStage } from '@owlmeans/resource'
 import type { ListCriteria, ResourceMaker, ResourceRecord } from '@owlmeans/resource'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
-import type { MongoDbService, MongoResource } from './types.js'
+import type { MongoDbService, MongoReference, MongoRefOptions, MongoResource, MongoTx } from './types.js'
 import { initializeCollection } from './utils/life-cycle.js'
+import { getDeclaration } from './declarations.js'
 import { ObjectId } from 'mongodb'
 import { MisshapedRecord, RecordExists, UnknownRecordError, UnsupportedArgumentError, RecordUpdateFailed, prepareListOptions } from '@owlmeans/resource'
 import type { JSONSchemaType } from 'ajv'
 import { getSchemaSecureFeilds } from './helper.js'
+import {
+  demarshalRefs, identityCriteria, makeRefMigration, marshalCriteria, marshalReference,
+  refMigrationName
+} from './utils/refs.js'
 
 type Config = ServerConfig
 type Context<C extends Config = Config> = ServerContext<C>
@@ -21,6 +27,18 @@ export const makeMongoResource = <
 ): T => {
   const location = `mongo-resource:${alias}`
 
+  /**
+   * Live view — references may be declared after the resource is built, and the
+   * declarations are module scoped so they survive `reinitializeContext`.
+   */
+  const refs = (): Map<string, MongoReference> => getDeclaration(alias).references
+
+  const demarshal = <Type extends ResourceRecord>(record: Type & { _id?: unknown }): Type => {
+    record.id = record._id instanceof ObjectId ? record._id.toString() : record._id as string
+    delete record._id
+    return demarshalRefs(record, refs())
+  }
+
   const resource: T = appendContextual<T>(alias, {
     get: async (id, field, opts) => {
       const record = await resource.load(id, field, opts)
@@ -37,15 +55,13 @@ export const makeMongoResource = <
         field = field.field
       }
       field = field ?? '_id'
-      const criteria = '_id' === field ? new ObjectId(id) : id
       if (opts?.ttl != null) {
         throw new UnsupportedArgumentError('ttl')
       }
 
-      const record = await resource.collection.findOne({ [field]: criteria })
+      const record = await resource.collection.findOne(identityCriteria(field, id, refs()))
       if (record != null) {
-        record.id = record._id instanceof ObjectId ? record._id.toString() : record._id
-        delete (record as any)._id
+        demarshal(record)
       }
 
       return record
@@ -70,16 +86,14 @@ export const makeMongoResource = <
 
       const original = await resource.get(id, field)
 
-      const criteria = '_id' === field ? new ObjectId(id) : id
-
       const replace = { ...record, _id: new ObjectId(original.id) }
       if (replace.id != null) {
         delete replace.id
       }
 
       const result = await resource.collection.replaceOne(
-        { [field]: criteria },
-        _prepareValues(replace, resource.schema as JSONSchemaType<any>)
+        identityCriteria(field, id, refs()),
+        _prepareValues(replace, resource.schema as JSONSchemaType<any>, refs())
       )
       if (!result.acknowledged) {
         throw new RecordUpdateFailed(`${field}:${id}`)
@@ -128,7 +142,7 @@ export const makeMongoResource = <
       }
       const result = await resource.collection.insertOne({
         ...resource.getDefaults(),
-        ..._prepareValues(record, resource.schema as JSONSchemaType<any>)
+        ..._prepareValues(record, resource.schema as JSONSchemaType<any>, refs())
       })
 
       if (!result.acknowledged) {
@@ -168,9 +182,7 @@ export const makeMongoResource = <
         throw new MisshapedRecord('id')
       }
 
-      const criteria = '_id' === field ? new ObjectId(_id) : _id
-
-      const result = await resource.collection.deleteOne({ [field]: criteria })
+      const result = await resource.collection.deleteOne(identityCriteria(field, _id as string, refs()))
       if (!result.acknowledged || result.deletedCount === 0) {
         return null
       }
@@ -190,7 +202,7 @@ export const makeMongoResource = <
     list: async (criteria, opts) => {
       const options = prepareListOptions(DEFAULT_PAGE_SIZE, criteria, opts)
 
-      criteria = options.criteria
+      criteria = marshalCriteria(options.criteria, refs()) ?? {}
       const pager = options.pager ?? {}
 
       const size = pager?.size ?? DEFAULT_PAGE_SIZE
@@ -218,13 +230,7 @@ export const makeMongoResource = <
       const items = await cursor.toArray()
 
       return {
-        pager, items: items.map(item => {
-          const _item: R = { ...item } as any
-          _item.id = item._id.toString()
-          delete (_item as any)._id
-
-          return _item
-        })
+        pager, items: items.map(item => demarshal({ ...item } as unknown as R))
       }
     },
 
@@ -270,7 +276,35 @@ export const makeMongoResource = <
       resource.indexes = resource.indexes ?? []
       resource.indexes.push({ name, index, options })
       return resource
-    }
+    },
+
+    /**
+     * `migration` and `reference` are `this`-returning in the interface, which an object
+     * literal can't express — hence the member level casts: the implementations return
+     * the closed over `resource`, which is that very object.
+     */
+    migration: ((name: string, apply: (tx: MongoTx) => Promise<void>, stage?: MigrationStage) => {
+      getDeclaration(alias).migrations.register(name, apply, stage)
+      return resource
+    }) as T['migration'],
+
+    migrations: () => getDeclaration(alias).migrations,
+
+    reference: ((field: string, opts?: string | MongoRefOptions) => {
+      const declaration = getDeclaration(alias)
+      const options = typeof opts === 'string' ? { resource: opts } : opts ?? {}
+      declaration.references.set(field, { field, resource: options.resource, noIndex: options.noIndex })
+      /**
+       * The system migration that converts the field's pre-existing string ids. Registered
+       * here rather than at init so it precedes migrations the app declares after its
+       * `reference()` calls — the field's type contract is the foundation those build on.
+       */
+      declaration.migrations.register(refMigrationName(field), makeRefMigration(field), MigrationStage.Pre)
+
+      return resource
+    }) as T['reference'],
+
+    references: () => [...getDeclaration(alias).references.values()]
   } as Partial<T>)
 
   // Explicit collection name override (decoupled from the registration alias, which may
@@ -286,7 +320,9 @@ export const makeMongoResource = <
     await mongo.ready()
     const db = await mongo.db(dbAlias)
     const config = mongo.config(dbAlias)
-    resource.collection = await initializeCollection(db, config, resource as unknown as MongoResource<ResourceRecord>)
+    resource.collection = await initializeCollection(
+      db, config, resource as unknown as MongoResource<ResourceRecord>, context
+    )
   }
 
   resource.reinitializeContext = <Type extends Contextual>(context: BasicContext<Config>) => {
@@ -301,15 +337,27 @@ export const makeMongoResource = <
   return resource
 }
 
-const _prepareValues = <T extends ResourceRecord>(obj: T, schema?: JSONSchemaType<T>): T => {
+const _prepareValues = <T extends ResourceRecord>(
+  obj: T, schema?: JSONSchemaType<T>, refs?: Map<string, MongoReference>
+): T => {
+  /**
+   * Declared references convert independently of the schema — the schema is optional,
+   * and where it exists it declares these fields as strings, whose coercion below would
+   * undo the conversion.
+   */
+  if (refs != null && refs.size > 0) {
+    obj = Object.fromEntries(Object.entries(obj).map(([key, value]) =>
+      refs.has(key) ? [key, marshalReference(key, value)] : [key, value]
+    )) as T
+  }
   // @TODO Validate keys from additional properties in the root
   return schema != null ? Object.fromEntries(Object.entries(obj).map(([key, value]) => {
-    // @TODO What if we reference another table by object id in another field?
-    // How to properly transform them?
-    // What if _id isn't an Object Id?
-    if (key === '_id') {
+    if (key === '_id' && !(value instanceof ObjectId)) {
       return [key, new ObjectId(value as string)]
     }
+    if (key === '_id' || refs?.has(key)) {
+      return [key, value]
+    }
     // A null/undefined value has nothing to coerce — pass it through for any declared
     // type. Without this guard the object-map and array branches below call
     // `Object.entries`/`.map` on `undefined` and throw (and `new Date(null)` would

package/src/types.ts

@@ -1,8 +1,50 @@
-import type { Resource, ResourceRecord, ResourceDbService, DbLocker, ResourceLocker } from '@owlmeans/resource'
+import type {
+  Resource, ResourceRecord, ResourceDbService, DbLocker, ResourceLocker, MigratableResource
+} from '@owlmeans/resource'
 import type { Collection, CreateIndexesOptions, Db, IndexSpecification, MongoClient } from 'mongodb'
 import type { AnySchema } from 'ajv'
 
-export interface MongoResource<T extends ResourceRecord> extends Resource<T>, ResourceLocker<T> {
+/**
+ * What a mongo migration is handed.
+ *
+ * Deliberately not a session or transaction: multi-document transactions require a replica
+ * set, and a standalone `mongod` — the usual development and CI target — rejects them
+ * outright. A migration therefore has to be written to tolerate being interrupted partway,
+ * which in practice means idempotent updates rather than read-then-write.
+ */
+export interface MongoTx {
+  db: Db
+  /** The owning resource's collection. */
+  collection: Collection
+  /** Another registered mongo resource's collection; omit the alias for the owning one. */
+  use: (alias?: string) => Collection
+  /** A collection *name*, for `$lookup.from` and other stages that take one rather than a handle. */
+  ref: (alias?: string) => string
+}
+
+/**
+ * A declared ObjectId reference — a record field that stores another record's id.
+ *
+ * The resource converts the field between the string ids records carry and the `ObjectId`
+ * the collection stores, exactly the way it already does for `_id`: strings in records and
+ * criteria, `ObjectId` on the wire. Declaring a reference also gives the field a mongo
+ * level index and registers the system migration that converts pre-existing string values.
+ */
+export interface MongoReference {
+  /** Top level record property holding the reference (a single id or an array of ids). */
+  field: string
+  /** Alias of the referenced resource. Informational — conversion never resolves it. */
+  resource?: string
+  /** Skip the automatic `{ [field]: 1 }` index. */
+  noIndex?: boolean
+}
+
+export interface MongoRefOptions {
+  resource?: string
+  noIndex?: boolean
+}
+
+export interface MongoResource<T extends ResourceRecord> extends Resource<T>, ResourceLocker<T>, MigratableResource<MongoTx> {
   name?: string
   schema?: AnySchema
   indexes?: Array<{ name: string, index: IndexSpecification, options?: CreateIndexesOptions }>
@@ -10,6 +52,20 @@ export interface MongoResource<T extends ResourceRecord> extends Resource<T>, Re
   db: () => Promise<Db>
   client: () => Promise<MongoClient>
   index: <Type extends MongoResource<T>>(name: string, index: IndexSpecification, options?: CreateIndexesOptions) => Type
+  /**
+   * 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.
+   *
+   * 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
+   * strings — converting them corrupts the collection.
+   */
+  reference: (field: string, opts?: string | MongoRefOptions) => this
+  /** The declared references of this alias. */
+  references: () => MongoReference[]
   getDefaults: () => Partial<T>
 }
 

package/src/utils/index.ts

@@ -3,3 +3,5 @@ export * from './indexes.js'
 export * from './schema.js'
 export * from './name.js'
 export * from './life-cycle.js'
+export * from './migrations.js'
+export * from './refs.js'