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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/mongo-resource",
-  "version": "0.1.18-rc.8",
+  "version": "0.1.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -26,16 +26,17 @@
     "mongodb": "*"
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.6",
-    "@owlmeans/resource": "^0.1.18-rc.7",
-    "@owlmeans/server-context": "^0.1.18-rc.8"
+    "@owlmeans/context": "^0.1.18",
+    "@owlmeans/log": "^0.1.18",
+    "@owlmeans/resource": "^0.1.18",
+    "@owlmeans/server-context": "^0.1.18"
   },
   "devDependencies": {
-    "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test-integration": "^0.1.18-rc.6",
-    "@types/bun": "^1.4.0",
-    "@types/node": "^26.1.0",
-    "mongodb": "^7.5.0",
+    "@owlmeans/dep-config": "^0.1.18",
+    "@owlmeans/test-integration": "^0.1.18",
+    "@types/bun": "^1.4.2",
+    "@types/node": "^26.6.4",
+    "mongodb": "^7.7.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

package/src/consts.ts

@@ -1,14 +1,18 @@
 
 export const DEFAULT_DB_ALIAS = 'mongo'
 
-export const DEFAULT_PAGE_SIZE = 10
+/**
+ * Page size a `list` call gets when it asks for none. Mongo cannot afford an unbounded read
+ * of a collection by omission, so paging is the default here — `list(where, { size: 0 })`
+ * asks for the whole result set, explicitly and greppably.
+ */
+export const DEFAULT_PAGE_SIZE = 100
 
 /**
  * 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.
+ * One ledger per database, which is the right boundary: it sits beside the data its
+ * migrations changed, so dropping the database drops the ledger with it.
  */
 export const DEF_MIGRATIONS_COLLECTION = '_owlmeans_migrations'
 

package/src/declarations/types.ts

@@ -0,0 +1,12 @@
+import type { MongoDeclaration } from '../types.js'
+
+/**
+ * The per-alias declaration store every mongo resource maker reads and extends — migrations and
+ * declared references, keyed by resource alias.
+ */
+export interface MongoDeclarationHelper {
+  /** The declaration of an alias, created empty on first use. */
+  getDeclaration: (alias: string) => MongoDeclaration
+  /** Testing seam — drops every declaration so a spec can redeclare a resource from scratch. */
+  resetDeclarations: (alias?: string) => void
+}

package/src/declarations.ts

@@ -1,42 +1,46 @@
 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>
-}
+import type { MongoDeclarationHelper } from './declarations/types.js'
+import type { MongoTx, MongoDeclaration } from './types.js'
 
 /**
  * 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.
+ * A maker may run more than once for the same alias — a custom maker wrapping the built-in
+ * one, a maker called again by an app or a spec. Keying the declarations by alias makes
+ * that a no-op: every run reads and extends the same registry, so nothing a caller declared
+ * by chaining onto an earlier resource object is lost. Losing a migration is silent — the
+ * data transformation simply never runs — which is why the store cannot live on the object.
+ *
+ * Process-wide for the same reason: it stays outside the factory, so every helper built from it
+ * reads the one store.
  */
 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)
-  }
+export const createMongoDeclarationHelper = (): MongoDeclarationHelper => {
+  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
-}
+    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()
+  const resetDeclarations = (alias?: string): void => {
+    if (alias == null) {
+      declarations.clear()
 
-    return
+      return
+    }
+    declarations.delete(alias)
   }
-  declarations.delete(alias)
+
+  return { getDeclaration, resetDeclarations }
 }
+
+export const mongoDeclarationHelper = createMongoDeclarationHelper()
+
+/** @deprecated compat:factory-refactor — use `mongoDeclarationHelper.resetDeclarations(…)` */
+export const resetDeclarations = (alias?: string): void => mongoDeclarationHelper.resetDeclarations(alias)

package/src/index.ts

@@ -2,7 +2,11 @@
 export type * from './types.js'
 export * from './consts.js'
 export * from './declarations.js'
+export type * from './declarations/types.js'
 export * from './utils/migrations.js'
 export * from './utils/refs.js'
+export type * from './utils/refs/types.js'
+export * from './utils/criteria.js'
+export type * from './utils/criteria/types.js'
 export * from './resource.js'
 export * from './helper.js'

package/src/resource.ts

@@ -1,120 +1,144 @@
 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 { MigrationStage, type Criteria, type FirstOptions, type ListOptions, type ListResult, type ResourceRecord, type WriteOptions, MisshapedRecord, RecordExists, UnknownRecordError, UnsupportedArgumentError, RecordUpdateFailed } from '@owlmeans/resource'
 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 { makeMongoLifeCycleUtils } from './utils/life-cycle.js'
+import { mongoDeclarationHelper } from './declarations.js'
+import { ObjectId, type CreateIndexesOptions, type Document, type IndexSpecification } from 'mongodb'
 import type { JSONSchemaType } from 'ajv'
 import { getSchemaSecureFeilds } from './helper.js'
-import {
-  demarshalRefs, identityCriteria, makeRefMigration, marshalCriteria, marshalReference,
-  refMigrationName
-} from './utils/refs.js'
+import { mongoCriteriaHelper } from './utils/criteria.js'
+import { makeRefMigration, mongoRefHelper } from './utils/refs.js'
+import type { Config, Context } from './types.local.js'
 
-type Config = ServerConfig
-type Context<C extends Config = Config> = ServerContext<C>
 
 export const makeMongoResource = <
   R extends ResourceRecord, T extends MongoResource<R> = MongoResource<R>
 >(
   alias: string, dbAlias: string = DEFAULT_DB_ALIAS, serviceAlias: string = DEFAULT_DB_ALIAS,
-  makeCustomResource?: ResourceMaker<R, T>, collectionName?: string
+  collectionName?: string
 ): 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`.
+   * declarations live at module scope keyed by alias, so a second maker run for the
+   * same alias sees everything already declared for it.
    */
-  const refs = (): Map<string, MongoReference> => getDeclaration(alias).references
+  const refs = (): Map<string, MongoReference> => mongoDeclarationHelper.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())
+    return mongoRefHelper.demarshalRefs(record, refs())
+  }
+
+  /**
+   * A read addressed either way. An id is matched tolerantly: a string that is not a mongo id
+   * finds nothing, where handing it to `ObjectId` would raise a driver error at a call site
+   * that only asked whether the record exists.
+   */
+  const filterOf = (idOrWhere: string | Criteria<R>): Document =>
+    typeof idOrWhere === 'string'
+      ? mongoRefHelper.identityCriteria('id', idOrWhere, refs())
+      : mongoCriteriaHelper.criteriaToFilter(idOrWhere, refs())
+
+  /**
+   * The single implementation both overloads of `load` and `get` stand on — an id and a
+   * criteria object differ only in how the filter is built.
+   */
+  const loadOne = async (
+    idOrWhere: string | Criteria<R>, opts?: FirstOptions<R>
+  ): Promise<R | null> => {
+    const sort = mongoCriteriaHelper.sortToMongo(opts?.sort)
+    const record = await resource.collection.findOne(
+      filterOf(idOrWhere), sort != null ? { sort } : {}
+    )
+
+    return record != null ? demarshal(record as unknown as R) : null
   }
 
   const resource: T = appendContextual<T>(alias, {
-    get: async (id, field, opts) => {
-      const record = await resource.load(id, field, opts)
+    get: (async (idOrWhere: string | Criteria<R>, opts?: FirstOptions<R>): Promise<R> => {
+      const record = await loadOne(idOrWhere, opts)
       if (record == null) {
-        throw new UnknownRecordError(id)
+        throw new UnknownRecordError(
+          typeof idOrWhere === 'string' ? idOrWhere : JSON.stringify(idOrWhere)
+        )
       }
 
       return record
-    },
+    }) as T['get'],
+
+    load: loadOne as T['load'],
 
-    load: async (id, field, opts) => {
-      if (typeof field === 'object') {
-        opts = field
-        field = field.field
+    list: async (where?: Criteria<R>, opts?: ListOptions<R>): Promise<ListResult<R>> => {
+      const filter = mongoCriteriaHelper.criteriaToFilter(where, refs())
+      const total = await resource.collection.countDocuments(filter)
+
+      /** `size: 0` is the explicit ask for everything; an omitted size pages by default. */
+      const size = opts?.size ?? DEFAULT_PAGE_SIZE
+      const page = opts?.page ?? 0
+      if (size < 1 && page !== 0) {
+        /** Nothing to page through — answering page 0 instead would be a silent wrong answer. */
+        throw new UnsupportedArgumentError('page-without-size')
       }
-      field = field ?? '_id'
-      if (opts?.ttl != null) {
-        throw new UnsupportedArgumentError('ttl')
+
+      if (total === 0) {
+        return size > 0 ? { items: [], total, page, size } : { items: [], total }
       }
 
-      const record = await resource.collection.findOne(identityCriteria(field, id, refs()))
-      if (record != null) {
-        demarshal(record)
+      let cursor = resource.collection.find(filter)
+      const sort = mongoCriteriaHelper.sortToMongo(opts?.sort)
+      if (sort != null) {
+        cursor = cursor.sort(sort)
+      }
+      if (size > 0) {
+        cursor = cursor.skip(page * size).limit(size)
       }
 
-      return record
+      const items = (await cursor.toArray()).map(item => demarshal({ ...item } as unknown as R))
+
+      return size > 0 ? { items, total, page, size } : { items, total }
     },
 
-    update: async (record, opts) => {
-      let field = '_id'
-      if (typeof opts === 'string') {
-        field = opts
-      } else if (typeof opts === 'object') {
-        field = opts.field ?? field
-      }
+    count: async (where?: Criteria<R>): Promise<number> =>
+      await resource.collection.countDocuments(mongoCriteriaHelper.criteriaToFilter(where, refs())),
 
-      if (field !== '_id' && record[field as keyof typeof record] == null) {
-        throw new MisshapedRecord('no-field-value')
+    update: async (record: Partial<R>, opts?: WriteOptions): Promise<R> => {
+      if (opts?.ttl != null) {
+        throw new UnsupportedArgumentError('ttl')
       }
-
-      const id = field == '_id' ? record.id : record[field as keyof typeof record] as string
+      const id = record.id
       if (id == null) {
         throw new MisshapedRecord('id')
       }
 
-      const original = await resource.get(id, field)
+      /** Absence is an error, not a silent no-op — `replaceOne` would just match nothing. */
+      const original = await resource.get(id)
 
-      const replace = { ...record, _id: new ObjectId(original.id) }
-      if (replace.id != null) {
-        delete replace.id
-      }
+      const replace: Document = { ...record }
+      /**
+       * Documents never store `id`, and a replacement that omits `_id` keeps the one the
+       * document already carries — so the whole record is replaced without touching its key.
+       */
+      delete replace.id
 
       const result = await resource.collection.replaceOne(
-        identityCriteria(field, id, refs()),
+        mongoRefHelper.identityCriteria('id', original.id as string, refs()),
         _prepareValues(replace, resource.schema as JSONSchemaType<any>, refs())
       )
       if (!result.acknowledged) {
-        throw new RecordUpdateFailed(`${field}:${id}`)
+        throw new RecordUpdateFailed(`id:${id}`)
       }
 
-      return resource.get(id, opts)
+      return await resource.get(original.id as string)
     },
 
-    save: async (record, opts) => {
-      const id = record.id
-      if (id != null || (
-        typeof opts === 'string' && record[opts as keyof typeof record] != null
-      ) || (
-          typeof opts === 'object' && ("field" in opts)
-          && record[opts.field as keyof typeof record] != null
-        )) {
-        return resource.update(record, opts)
-      }
-
-      return resource.create(record, typeof opts !== 'string' ? opts : undefined)
-    },
+    save: async (record: Partial<R>, opts?: WriteOptions): Promise<R> =>
+      record.id != null
+        ? await resource.update(record, opts)
+        : await resource.create(record, opts),
 
     getDefaults: () => {
       const schema: JSONSchemaType<unknown> | undefined = resource.schema as JSONSchemaType<unknown>
@@ -130,14 +154,14 @@ export const makeMongoResource = <
       }, {})
     },
 
-    create: async (record, opts) => {
+    create: async (record: Partial<R>, opts?: WriteOptions): Promise<R> => {
       if ("id" in record && record.id == null) {
         delete record.id
       }
       if (record.id != null) {
         throw new RecordExists('id-present')
       }
-      if (opts != null && opts.ttl != null) {
+      if (opts?.ttl != null) {
         throw new UnsupportedArgumentError('ttl')
       }
       const result = await resource.collection.insertOne({
@@ -149,89 +173,33 @@ export const makeMongoResource = <
         throw new RecordUpdateFailed(`creation`)
       }
 
-      const id = result.insertedId
-
-      return resource.get(id.toString())
+      return await resource.get(result.insertedId.toString())
     },
 
-    delete: async (id, opts) => {
-      let record: R | null = null
-      if (typeof id === 'object') {
-        if (id.id == null) {
-          throw new MisshapedRecord('id')
-        }
-        record = await resource.load(id.id)
-      } else {
-        record = await resource.load(id, opts)
-      }
-
-      if (record == null) {
-        return null
-      }
+    /** Atomic: the record is handed back by the very operation that removed it. */
+    delete: async (id: string): Promise<R | null> => {
+      const record = await resource.collection.findOneAndDelete(mongoRefHelper.identityCriteria('id', id, refs()))
 
-      let field = '_id'
-      if (typeof opts === 'string') {
-        field = opts
-        opts = undefined
-      } else if (typeof opts === 'object') {
-        field = opts.field ?? field
-      }
-
-      const _id = field == '_id' ? record.id : record[field as keyof typeof record] as string
-      if (id == null) {
-        throw new MisshapedRecord('id')
-      }
-
-      const result = await resource.collection.deleteOne(identityCriteria(field, _id as string, refs()))
-      if (!result.acknowledged || result.deletedCount === 0) {
-        return null
-      }
-
-      return record
+      return record != null ? demarshal(record as unknown as R) : null
     },
 
-    pick: async (id, opts) => {
-      const record = await resource.delete(id, opts)
+    take: async (id: string): Promise<R> => {
+      const record = await resource.delete(id)
       if (record == null) {
-        throw new UnknownRecordError(typeof id == 'string' ? id : (id.id ?? 'unknown'))
+        throw new UnknownRecordError(id)
       }
 
       return record
     },
 
-    list: async (criteria, opts) => {
-      const options = prepareListOptions(DEFAULT_PAGE_SIZE, criteria, opts)
-
-      criteria = marshalCriteria(options.criteria, refs()) ?? {}
-      const pager = options.pager ?? {}
-
-      const size = pager?.size ?? DEFAULT_PAGE_SIZE
-      const total = await resource.collection.countDocuments(criteria as ListCriteria)
-      pager.total = total
-
-      const skip = (pager.page ?? 0) * size
-      if (total === 0 && skip >= total) {
-        return { items: [], pager }
-      }
-
-      let cursor = resource.collection.find(criteria as ListCriteria)
-        .skip(skip).limit(size)
-
-      if (pager.sort != null) {
-        cursor = cursor.sort(
-          typeof pager.sort === 'string'
-            ? pager.sort
-            : pager.sort.reduce((sort, [field, order]) =>
-              ({ ...sort, [field as keyof typeof sort]: order ? -1 : 1 }), {}
-            )
-        )
+    purge: async (where: Criteria<R>): Promise<number> => {
+      const filter = mongoCriteriaHelper.criteriaToFilter(where, refs())
+      if (Object.keys(filter).length < 1) {
+        /** An empty filter here would empty the collection. */
+        throw new UnsupportedArgumentError('purge:no-criteria')
       }
 
-      const items = await cursor.toArray()
-
-      return {
-        pager, items: items.map(item => demarshal({ ...item } as unknown as R))
-      }
+      return (await resource.collection.deleteMany(filter)).deletedCount
     },
 
     lock: async (record, fields) => {
@@ -272,26 +240,26 @@ export const makeMongoResource = <
       return await mongo.client(dbAlias)
     },
 
-    index: (name, index, options) => {
+    /**
+     * `index`, `migration` and `reference` hand the resource itself back so declarations
+     * chain — a return an object literal can't express, hence the member level casts: each
+     * implementation returns the closed over `resource`, which is that very object.
+     */
+    index: ((name: string, index: IndexSpecification, options?: CreateIndexesOptions) => {
       resource.indexes = resource.indexes ?? []
       resource.indexes.push({ name, index, options })
       return resource
-    },
+    }) as T['index'],
 
-    /**
-     * `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)
+      mongoDeclarationHelper.getDeclaration(alias).migrations.register(name, apply, stage)
       return resource
     }) as T['migration'],
 
-    migrations: () => getDeclaration(alias).migrations,
+    migrations: () => mongoDeclarationHelper.getDeclaration(alias).migrations,
 
     reference: ((field: string, opts?: string | MongoRefOptions) => {
-      const declaration = getDeclaration(alias)
+      const declaration = mongoDeclarationHelper.getDeclaration(alias)
       const options = typeof opts === 'string' ? { resource: opts } : opts ?? {}
       declaration.references.set(field, { field, resource: options.resource, noIndex: options.noIndex })
       /**
@@ -299,17 +267,16 @@ export const makeMongoResource = <
        * 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)
+      declaration.migrations.register(mongoRefHelper.refMigrationName(field), makeRefMigration(field), MigrationStage.Pre)
 
       return resource
     }) as T['reference'],
 
-    references: () => [...getDeclaration(alias).references.values()]
+    references: () => [...mongoDeclarationHelper.getDeclaration(alias).references.values()]
   } as Partial<T>)
 
   // Explicit collection name override (decoupled from the registration alias, which may
-  // contain characters that aren't valid in a collection name). Survives reinitializeContext
-  // because it's threaded back into the recursive makeMongoResource call below.
+  // contain characters that aren't valid in a collection name).
   if (collectionName != null) {
     resource.name = collectionName
   }
@@ -322,20 +289,11 @@ 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>, context
+    resource.collection = await makeMongoLifeCycleUtils(db).initializeCollection(
+      config, resource as unknown as MongoResource<ResourceRecord>, context
     )
   }
 
-  resource.reinitializeContext = <Type extends Contextual>(context: BasicContext<Config>) => {
-    const resource = (makeCustomResource?.(dbAlias, serviceAlias)
-      ?? makeMongoResource<R, T>(alias, dbAlias, serviceAlias, makeCustomResource, collectionName)) as unknown as Type
-
-    resource.ctx = context
-
-    return resource as Type
-  }
-
   return resource
 }
 
@@ -349,7 +307,7 @@ const _prepareValues = <T extends ResourceRecord>(
    */
   if (refs != null && refs.size > 0) {
     obj = Object.fromEntries(Object.entries(obj).map(([key, value]) =>
-      refs.has(key) ? [key, marshalReference(key, value)] : [key, value]
+      refs.has(key) ? [key, mongoRefHelper.marshalReference(key, value)] : [key, value]
     )) as T
   }
   // @TODO Validate keys from additional properties in the root

package/src/types.local.ts

@@ -0,0 +1,5 @@
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+
+export type Config = ServerConfig
+
+export type Context<C extends Config = Config> = ServerContext<C>

package/src/types.ts

@@ -1,6 +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'
 
@@ -44,7 +42,8 @@ export interface MongoRefOptions {
   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.
@@ -61,13 +60,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
@@ -81,3 +81,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>
+}