@owlmeans/mongo-resource 0.1.18-rc.2 → 0.1.18-rc.21

package/src/resource.ts

@@ -1,19 +1,23 @@
 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 {
+  Criteria, FirstOptions, ListOptions, ListResult, ResourceRecord, WriteOptions
+} from '@owlmeans/resource'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 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 { CreateIndexesOptions, Document, IndexSpecification } from 'mongodb'
+import {
+  MisshapedRecord, RecordExists, UnknownRecordError, UnsupportedArgumentError, RecordUpdateFailed
+} from '@owlmeans/resource'
 import type { JSONSchemaType } from 'ajv'
 import { getSchemaSecureFeilds } from './helper.js'
+import { criteriaToFilter, sortToMongo } from './utils/criteria.js'
 import {
-  demarshalRefs, identityCriteria, makeRefMigration, marshalCriteria, marshalReference,
-  refMigrationName
+  demarshalRefs, identityCriteria, makeRefMigration, marshalReference, refMigrationName
 } from './utils/refs.js'
 
 type Config = ServerConfig
@@ -23,13 +27,14 @@ 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
 
@@ -39,82 +44,112 @@ export const makeMongoResource = <
     return 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'
+      ? identityCriteria('id', idOrWhere, refs())
+      : 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 = 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: async (id, field, opts) => {
-      if (typeof field === 'object') {
-        opts = field
-        field = field.field
+    load: loadOne as T['load'],
+
+    list: async (where?: Criteria<R>, opts?: ListOptions<R>): Promise<ListResult<R>> => {
+      const filter = 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 = 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(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()),
+        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 +165,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 +184,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)
-      }
+    /** 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(identityCriteria('id', id, refs()))
 
-      if (record == null) {
-        return null
-      }
-
-      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 }
+    purge: async (where: Criteria<R>): Promise<number> => {
+      const filter = criteriaToFilter(where, refs())
+      if (Object.keys(filter).length < 1) {
+        /** An empty filter here would empty the collection. */
+        throw new UnsupportedArgumentError('purge:no-criteria')
       }
 
-      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 }), {}
-            )
-        )
-      }
-
-      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,17 +251,17 @@ 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)
       return resource
@@ -308,11 +287,12 @@ export const makeMongoResource = <
   } 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
   }
+  resource.dbAlias = dbAlias
+  resource.serviceAlias = serviceAlias
 
   resource.init = async () => {
     const context = assertContext<Config, Context>(resource.ctx as Context, location)
@@ -325,15 +305,6 @@ export const makeMongoResource = <
     )
   }
 
-  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
 }
 

package/src/types.ts

@@ -1,5 +1,5 @@
 import type {
-  Resource, ResourceRecord, ResourceDbService, DbLocker, ResourceLocker, MigratableResource
+  Resource, ResourceRecord, ResourceDbService, DbLocker, LockableResource, MigratableResource
 } from '@owlmeans/resource'
 import type { Collection, CreateIndexesOptions, Db, IndexSpecification, MongoClient } from 'mongodb'
 import type { AnySchema } from 'ajv'
@@ -44,20 +44,32 @@ 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.
+   *
+   * Exposed because a collection's NAME depends on it: two resources in one database can carry
+   * different `resourcePrefix`es, so anything naming a collection on another resource's behalf —
+   * a migration reaching across aliases, for one — has to read that resource's own config rather
+   * than assume its caller's.
+   */
+  dbAlias?: string
+  serviceAlias?: string
   schema?: AnySchema
   indexes?: Array<{ name: string, index: IndexSpecification, options?: CreateIndexesOptions }>
   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

package/src/utils/criteria.ts

@@ -0,0 +1,248 @@
+import { UnsupportedArgumentError } from '@owlmeans/resource'
+import type { Criteria, Sort } from '@owlmeans/resource'
+import type { Document } from 'mongodb'
+
+import type { MongoReference } from '../types.js'
+import { marshalCriteria } from './refs.js'
+
+/**
+ * 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.
+ */
+const NATIVE = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin', '$regex'])
+
+const escapeRegExp = (value: string): string => 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: string): string => {
+  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: unknown): unknown[] => 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: string, operator: string, operand: unknown): Document => {
+  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: unknown): value is Record<string, unknown> =>
+  value != null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+  && Object.keys(value).some(key => key.startsWith('$'))
+
+/**
+ * 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: string, spec: Record<string, unknown>): Document[] => {
+  const merged: Document = {}
+  const conditions: Document[] = []
+
+  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: Document[]): Document => {
+  const filter: Document = {}
+  const conflicting: Document[] = []
+
+  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: Criteria<any> | undefined): Document[] => {
+  const conditions: Document[] = []
+
+  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 as Criteria<any>))
+        .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 as Criteria<any>)
+      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 as Record<string, unknown>))
+      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
+}
+
+/**
+ * Translate `Criteria<T>` into the filter a collection takes.
+ *
+ * Two passes: the shared operator vocabulary becomes mongo expressions, then
+ * {@link 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}
+ */
+export const criteriaToFilter = (
+  criteria: Criteria<any> | undefined, refs: Map<string, MongoReference>
+): Document => {
+  const conditions = build(criteria)
+  if (conditions.length < 1) {
+    return {}
+  }
+
+  return marshalCriteria(flatten(conditions), refs) ?? {}
+}
+
+/**
+ * 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.
+ */
+export const sortToMongo = (sort?: Sort<any>[]): Document | undefined => {
+  if (sort == null || sort.length < 1) {
+    return undefined
+  }
+
+  return sort.reduce<Document>((order, entry) => {
+    const [field, direction]: [string, number] = typeof entry === 'string'
+      ? [entry, 1]
+      : [entry.field, entry.order === 'desc' ? -1 : 1]
+    order[field === 'id' ? '_id' : field] = direction
+
+    return order
+  }, {})
+}

package/src/utils/index.ts

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