@owlmeans/resource 0.1.14 → 0.1.16-rc.0

package/README.md

@@ -65,7 +65,7 @@ const result: ListResult<ProjectRecord> = await ctx.project().list({
 - `save(record, opts?)` — upsert by ID
 - `update(record, opts?)` — update; throws `UnknownRecordError` if missing
 - `delete(id, opts?)` — remove; returns the deleted record or `null`
-- `pick(id, opts?)` — like `get` but optimized for existence checks
+- `pick(id, opts?)` — **delete and return** the record; throws `UnknownRecordError` if missing. Never use it for read-only checks
 
 ### `ResourceMaker<R, T>`
 
@@ -75,10 +75,31 @@ interface ResourceMaker<R extends ResourceRecord, T extends Resource<R> = Resour
 }
 ```
 
+### Migration framework
+
+Storage-agnostic and optional — a backend that supports code migrations (mongo, postgres)
+extends `MigratableResource<Tx>`; backends with nothing to migrate simply don't (the same way
+pub/sub is an optional capability of redis resources). Migrations run **automatically during
+resource initialization** (app setup) — registering one is all an app ever does.
+
+- `MigratableResource<Tx>` — `migration(name, apply, stage?): this` + `migrations()`
+- `createMigrationRegistry<Tx>()` — per-alias ledger of registered migrations; declaration
+  order is application order; identical re-registration is a no-op, a changed body under a
+  used name throws `MigrationConflict`
+- `MigrationStore<Tx>` — the *migration register* a database implements to track applied
+  migrations (`ensure` / `applied` / `baseline` / `run`); both mongo and postgres persist it
+  as `_owlmeans_migrations`
+- `runMigrations(alias, registry, store, opts?)` — the storage-agnostic runner; with
+  `baseline: true` migrations are recorded instead of run (used on just-created structures);
+  `strictChecksum` (default) rejects edited applied bodies
+- `MigrationStage.Pre` / `MigrationStage.Post` — run before / after the backend's structure
+  reconciliation
+
 ### Helpers
 
 - `prepareListOptions(defPageSize, criteria?, opts?)` — normalize list criteria + pager
 - `filterObject(obj, keep?)` — strip null/undefined fields from a record before saving
+- `createDbService(alias, override, init?)` — base plumbing for `ResourceDbService` implementations
 
 ### Error Classes
 
@@ -86,6 +107,8 @@ interface ResourceMaker<R extends ResourceRecord, T extends Resource<R> = Resour
 - `UnknownRecordError` — record not found (has `.id` getter)
 - `RecordExists` — duplicate record on `create`
 - `MisshapedRecord` — invalid record structure
+- `MigrationError` — a migration body threw; initialization aborts
+- `MigrationConflict` — an already applied migration's body changed, or a name was redeclared with a different body
 
 ## Related Packages
 

package/agent-meta/instructions/resource.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "How to use @owlmeans/resource — generic resource abstraction (CRUD over a collection of records) used by mongo-resource, redis-resource, state, storage-resource. Use when implementing a custom resource."
+description: "How to use @owlmeans/resource — generic resource abstraction (CRUD over records) plus the storage-agnostic migration framework (MigratableResource, registry/store/runner). Use when implementing a custom resource or adding migration support to a database backend."
 applyTo: "**/*.ts, **/*.tsx"
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -7,27 +7,37 @@ applyTo: "**/*.ts, **/*.tsx"
 # @owlmeans/resource
 
 **Layer:** Core
-**Install:** `"@owlmeans/resource": "^0.1.14"` in `dependencies`
+**Install:** `"@owlmeans/resource": "^0.1.16-rc.0"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Resource<T>` types | Generic resource interface (get/list/create/update/delete) |
-| Errors | Typed resource errors (NotFound, AlreadyExists, etc.) |
-| Constants | Default resource aliases |
-| Service helpers | Wrap a resource as a context service |
+| `Resource<T>` | Generic contract: get/load/list/save/create/update/delete/pick |
+| `MigratableResource<Tx>` | Optional migration capability — `migration(name, apply, stage?)` + `migrations()`. Optional like pub/sub on redis: mongo/postgres extend it, others don't |
+| `MigrationRegistry`, `MigrationStore`, `createMigrationRegistry`, `runMigrations`, `MigrationStage` | The framework: per-alias registry (declaration order = application order), the applied-tracking register a db implements, the storage-agnostic runner (`baseline` for fresh structures, strict checksums) |
+| Errors | `UnknownRecordError`, `MisshapedRecord`, `RecordExists`, `RecordUpdateFailed`, `UnsupportedArgumentError`, `MigrationError`, `MigrationConflict` |
+| `createDbService`, `prepareListOptions`, `DbConfig` | Service base, list helpers, `cfg.dbs` config type |
 
 ## Usage
 
 ```typescript
 import type { Resource } from '@owlmeans/resource'
-
-interface Project { id: string; name: string; entityId: string }
-const projects = ctx.getResource<Resource<Project>>('projects')
+const projects = ctx.resource<Resource<Project>>('projects')
 const { items } = await projects.list({ entityId: 'abc' })
 ```
 
+## Migration framework rules
+
+- Migrations run **automatically on app setup** inside resource `init()` — apps only register.
+- Each migration self-checks: registry skips ledger-recorded names; `baseline: true` records
+  instead of running on just-created structures; bodies are written idempotent.
+- New backend support: extend the concrete interface with `MigratableResource<YourTx>`; keep
+  registrations in a module-scope declaration keyed by alias (context rebuilds must not lose
+  them); implement `MigrationStore` over a durable ledger; in `init()` probe → baseline|Pre →
+  reconcile structure → Post; make `run` atomic with the ledger where the db allows
+  (postgres tx), claim-then-complete where it doesn't (mongo).
+
 ## Depends On
 
-- `@owlmeans/error`, `@owlmeans/i18n`
+- `@owlmeans/context`, `@noble/hashes` (body checksums)

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "package": "@owlmeans/resource",
-  "version": "0.1.14",
-  "generatedAt": "2026-08-05T16:56:53.373Z",
+  "version": "0.1.16-rc.0",
+  "generatedAt": "2026-08-11T14:02:34.972Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/resource/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: resource
-description: How to use @owlmeans/resource — generic resource abstraction (CRUD over a collection of records) used by mongo-resource, redis-resource, state, storage-resource, etc. Auto-invoked when importing from this package or implementing a custom resource type.
+description: How to use @owlmeans/resource — generic resource abstraction (CRUD over records) plus the storage-agnostic migration framework (MigratableResource, migration registry/store/runner) used by mongo-resource, postgres-resource, redis-resource, state, storage-resource, etc. Auto-invoked when importing from this package, implementing a custom resource type, or adding migration support to a database backend.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,30 +8,67 @@ user-invocable: false
 # @owlmeans/resource
 
 **Layer:** Core
-**Install:** `"@owlmeans/resource": "^0.1.14"` in `dependencies`
+**Install:** `"@owlmeans/resource": "^0.1.16-rc.0"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `Resource<T>` types | Generic resource interface (get/list/create/update/delete) |
-| Errors | Typed resource errors (NotFound, AlreadyExists, etc.) |
-| Constants | Default resource aliases, operation names |
-| Service helpers | Wrap a resource as a context service |
+| `Resource<T>` | Generic resource contract: `get`/`load`/`list`/`save`/`create`/`update`/`delete`/`pick`. |
+| `MigratableResource<Tx>` | **Optional migration capability** — `migration(name, apply, stage?)` (chainable) + `migrations()`. Optional the way pub/sub is on redis resources: mongo and postgres extend it, backends with nothing to migrate don't. |
+| `Migration`, `MigrationRegistry`, `MigrationStore`, `MigrationReport`, `MigrationRunOptions` | The framework's contracts. `MigrationStore` is the *migration register* a database implements to track applied migrations (`ensure`/`applied`/`baseline`/`run`). |
+| `createMigrationRegistry<Tx>()` | Storage-agnostic ledger of code-registered migrations per alias. Declaration order = application order; re-registering an identical body is a no-op, a changed body under a used name throws `MigrationConflict`. |
+| `runMigrations(alias, registry, store, opts?)` | Apply one stage's pending migrations through a store. `baseline: true` records instead of running (fresh structures); `strictChecksum` (default on) rejects edited applied bodies. |
+| `MigrationStage` | `Pre` (before structure reconciliation — renames, casts, rescues) / `Post` (after — backfills into new structure). |
+| `createDbService` | Base for `ResourceDbService` implementations (config/alias/name/client plumbing). |
+| `prepareListOptions`, `filterObject`, `createListSchema` | List/criteria helpers. |
+| Errors | `ResourceError`, `UnknownRecordError`, `MisshapedRecord`, `RecordExists`, `RecordUpdateFailed`, `UnsupportedArgumentError`, `UnsupportedMethodError`, `MigrationError`, `MigrationConflict`. |
+| `DbConfig`, `Config`, `Context` | Database config (`cfg.dbs`) types. |
 
 ## Usage
 
-A resource is a typed CRUD-over-records abstraction. Concrete implementations come from `@owlmeans/mongo-resource`, `@owlmeans/redis-resource`, `@owlmeans/state`, etc. Consumers register a resource with the context and access it via `ctx.getResource<T>(alias)`.
+A resource is a typed CRUD-over-records abstraction. Concrete implementations come from
+`@owlmeans/mongo-resource`, `@owlmeans/postgres-resource`, `@owlmeans/redis-resource`,
+`@owlmeans/state`, etc. Consumers register with the context and access via
+`ctx.resource<T>(alias)`.
 
 ```typescript
 import type { Resource } from '@owlmeans/resource'
 
 interface Project { id: string; name: string; entityId: string }
-const projects = ctx.getResource<Resource<Project>>('projects')
+const projects = ctx.resource<Resource<Project>>('projects')
 const { items } = await projects.list({ entityId: 'abc' })
 ```
 
+## The migration framework
+
+Migrations are **automatic on app setup**: a backend runs them inside the resource's
+`init()` — registering one is all an app ever does. Every migration self-describes when it
+applies: the registry skips names the store has recorded, `baseline` covers structures
+created already at head, and bodies are written idempotent so an interrupted run can repeat.
+
+Adding migration support to a new database backend:
+
+1. Extend the concrete resource interface with `MigratableResource<YourTx>` and design the
+   `Tx` façade a migration receives.
+2. Keep registrations in a **module-scope declaration keyed by alias** (see either
+   implementation's `declarations.ts`) — `reinitializeContext` rebuilds resource objects, and
+   a registry lost to a rebuild silently loses data transformations.
+3. Implement `MigrationStore` over a durable ledger when the database can store one
+   (`_owlmeans_migrations` in both mongo and postgres); a store-less backend may run
+   migrations unconditionally if its bodies are self-checking.
+4. In the resource's `init()`: probe structure → absent: `runMigrations(..., { baseline: true })`;
+   present: run `Pre` → reconcile structure → run `Post`.
+5. Make `run` atomic with the ledger write where the database allows it (postgres: same
+   transaction). Where it doesn't (mongo: no multi-doc transactions on standalone), use
+   claim-then-complete on a unique `(alias, name)` key and require idempotent bodies.
+
 ## Depends On
 
-- `@owlmeans/error` — for typed errors
-- `@owlmeans/i18n` — error messages
+- `@owlmeans/context` — service/resource lifecycle
+- `@noble/hashes` — migration body checksums
+
+## Related
+
+- [[mongo-resource]] · [[postgres-resource]] — the two `MigratableResource` implementations
+- [[redis-resource]] — a non-migratable backend (pub/sub capability instead)

package/build/consts.d.ts

@@ -1,4 +1,20 @@
 import type { JSONSchemaType } from 'ajv';
 import type { ListResult, ResourceRecord } from './types.js';
+/**
+ * When a migration runs relative to the structure reconciliation a db implementation
+ * performs at resource initialization.
+ *
+ * - `pre` — before the structure is reconciled. This is where a change reconciliation
+ *   cannot express correctly belongs: renames, casts that need a `USING` expression,
+ *   backfills that have to precede a `NOT NULL`. Once the migration has reshaped the
+ *   structure, reconciliation observes no drift and emits nothing — the two mechanisms
+ *   never fight because the migration pre-empts the reconciler.
+ * - `post` — after reconciliation. For data backfills into columns reconciliation has
+ *   just created.
+ */
+export declare enum MigrationStage {
+    Pre = "pre",
+    Post = "post"
+}
 export declare const createListSchema: <T extends ResourceRecord>(schema: JSONSchemaType<T>) => JSONSchemaType<ListResult<T>>;
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5D,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,EAAE,QAAQ,cAAc,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CA6CjH,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,oBAAY,cAAc;IACxB,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,EAAE,QAAQ,cAAc,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CA6CjH,CAAA"}

package/build/consts.js

@@ -1,3 +1,20 @@
+/**
+ * When a migration runs relative to the structure reconciliation a db implementation
+ * performs at resource initialization.
+ *
+ * - `pre` — before the structure is reconciled. This is where a change reconciliation
+ *   cannot express correctly belongs: renames, casts that need a `USING` expression,
+ *   backfills that have to precede a `NOT NULL`. Once the migration has reshaped the
+ *   structure, reconciliation observes no drift and emits nothing — the two mechanisms
+ *   never fight because the migration pre-empts the reconciler.
+ * - `post` — after reconciliation. For data backfills into columns reconciliation has
+ *   just created.
+ */
+export var MigrationStage;
+(function (MigrationStage) {
+    MigrationStage["Pre"] = "pre";
+    MigrationStage["Post"] = "post";
+})(MigrationStage || (MigrationStage = {}));
 export const createListSchema = (schema) => ({
     type: 'object',
     properties: {

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAGA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAA2B,MAAyB,EAAiC,EAAE,CAAC,CAAC;IACvH,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,GAAG,MAAM;gBACT,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACtC,GAAG,MAAM,CAAC,UAAU;iBACrB;gBACD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACrE,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE;wBACL,KAAK,EAAE;4BACL,EAAE,IAAI,EAAE,QAAQ,EAAE;4BAClB;gCACE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;oCACpB,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAClB,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;iCACpC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;6BAC5B;yBACF;qBACF;oBACD,QAAQ,EAAE,IAAI;iBACf;gBACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC1C;YACD,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,KAAK;SAC5B;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;IACnB,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,CAAN,IAAY,cAGX;AAHD,WAAY,cAAc;IACxB,6BAAW,CAAA;IACX,+BAAa,CAAA;AACf,CAAC,EAHW,cAAc,KAAd,cAAc,QAGzB;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAA2B,MAAyB,EAAiC,EAAE,CAAC,CAAC;IACvH,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,GAAG,MAAM;gBACT,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACtC,GAAG,MAAM,CAAC,UAAU;iBACrB;gBACD,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACrE,oBAAoB,EAAE,KAAK;aAC5B;SACF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE;wBACL,KAAK,EAAE;4BACL,EAAE,IAAI,EAAE,QAAQ,EAAE;4BAClB;gCACE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;oCACpB,EAAE,IAAI,EAAE,QAAQ,EAAE;oCAClB,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;iCACpC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;6BAC5B;yBACF;qBACF;oBACD,QAAQ,EAAE,IAAI;iBACf;gBACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;gBACxC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC1C;YACD,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,IAAI;YACd,oBAAoB,EAAE,KAAK;SAC5B;KACF;IACD,QAAQ,EAAE,CAAC,OAAO,CAAC;IACnB,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAA"}

package/build/errors.d.ts

@@ -29,4 +29,22 @@ export declare class UnsupportedMethodError extends ResourceError {
     static typeName: string;
     constructor(method: string);
 }
+/**
+ * A registered migration threw while being applied. Resource initialization aborts —
+ * a structure problem has to fail the boot loudly rather than leave the process
+ * running against a half-shaped database.
+ */
+export declare class MigrationError extends ResourceError {
+    static typeName: string;
+    constructor(msg: string);
+}
+/**
+ * A migration name was registered twice with different bodies, or an already applied
+ * migration's body has changed since it ran. Write a new migration instead of editing
+ * one that has already been applied somewhere.
+ */
+export declare class MigrationConflict extends ResourceError {
+    static typeName: string;
+    constructor(msg: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEjD,qBAAa,aAAc,SAAQ,cAAc;IAC/C,OAAuB,QAAQ,SAAkB;gBAErC,OAAO,GAAE,MAAgB;CAGtC;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,OAAuB,QAAQ,SAAgD;IAE/E,gBAAuB,WAAW,EAAE,MAAM,CAAM;gBAEpC,EAAE,EAAE,MAAM;IAKtB,IAAI,EAAE,IAAI,MAAM,CAEf;CACF;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAuB,QAAQ,SAA6C;gBAEhE,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,YAAa,SAAQ,aAAa;IAC7C,OAAuB,QAAQ,SAA0C;gBAE7D,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,OAAuB,QAAQ,SAAgD;gBAEnE,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,OAAuB,QAAQ,SAAsD;gBAEzE,QAAQ,EAAE,MAAM;CAI7B;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,OAAuB,QAAQ,SAAoD;gBAEvE,MAAM,EAAE,MAAM;CAI3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEjD,qBAAa,aAAc,SAAQ,cAAc;IAC/C,OAAuB,QAAQ,SAAkB;gBAErC,OAAO,GAAE,MAAgB;CAGtC;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,OAAuB,QAAQ,SAAgD;IAE/E,gBAAuB,WAAW,EAAE,MAAM,CAAM;gBAEpC,EAAE,EAAE,MAAM;IAKtB,IAAI,EAAE,IAAI,MAAM,CAEf;CACF;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,OAAuB,QAAQ,SAA6C;gBAEhE,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,YAAa,SAAQ,aAAa;IAC7C,OAAuB,QAAQ,SAA0C;gBAE7D,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,OAAuB,QAAQ,SAAgD;gBAEnE,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,OAAuB,QAAQ,SAAsD;gBAEzE,QAAQ,EAAE,MAAM;CAI7B;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,OAAuB,QAAQ,SAAoD;gBAEvE,MAAM,EAAE,MAAM;CAI3B;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,OAAuB,QAAQ,SAA4C;gBAE/D,GAAG,EAAE,MAAM;CAIxB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,OAAuB,QAAQ,SAA+C;gBAElE,GAAG,EAAE,MAAM;CAIxB"}

package/build/errors.js

@@ -51,6 +51,30 @@ export class UnsupportedMethodError extends ResourceError {
         this.type = UnsupportedMethodError.typeName;
     }
 }
+/**
+ * A registered migration threw while being applied. Resource initialization aborts —
+ * a structure problem has to fail the boot loudly rather than leave the process
+ * running against a half-shaped database.
+ */
+export class MigrationError extends ResourceError {
+    static typeName = `${ResourceError.typeName}MigrationError`;
+    constructor(msg) {
+        super(`migration-failed:${msg}`);
+        this.type = MigrationError.typeName;
+    }
+}
+/**
+ * A migration name was registered twice with different bodies, or an already applied
+ * migration's body has changed since it ran. Write a new migration instead of editing
+ * one that has already been applied somewhere.
+ */
+export class MigrationConflict extends ResourceError {
+    static typeName = `${ResourceError.typeName}MigrationConflict`;
+    constructor(msg) {
+        super(`migration-conflict:${msg}`);
+        this.type = MigrationConflict.typeName;
+    }
+}
 ResilientError.registerErrorClass(ResourceError);
 ResilientError.registerErrorClass(UnknownRecordError);
 ResilientError.registerErrorClass(MisshapedRecord);
@@ -58,4 +82,6 @@ ResilientError.registerErrorClass(RecordExists);
 ResilientError.registerErrorClass(RecordUpdateFailed);
 ResilientError.registerErrorClass(UnsupportedArgumentError);
 ResilientError.registerErrorClass(UnsupportedMethodError);
+ResilientError.registerErrorClass(MigrationError);
+ResilientError.registerErrorClass(MigrationConflict);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEjD,MAAM,OAAO,aAAc,SAAQ,cAAc;IACxC,MAAM,CAAU,QAAQ,GAAG,eAAe,CAAA;IAEjD,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,YAAY,OAAO,EAAE,CAAC,CAAA;IACtD,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC5C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,oBAAoB,CAAA;IAExE,MAAM,CAAU,WAAW,GAAW,GAAG,CAAA;IAEhD,YAAY,EAAU;QACpB,KAAK,CAAC,iBAAiB,kBAAkB,CAAC,WAAW,GAAG,EAAE,EAAE,CAAC,CAAA;QAC7D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;IAED,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9D,CAAC;;AAGH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IACzC,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,iBAAiB,CAAA;IAE5E,YAAY,GAAW;QACrB,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;;AAGH,MAAM,OAAO,YAAa,SAAQ,aAAa;IACtC,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,cAAc,CAAA;IAEzE,YAAY,GAAW;QACrB,KAAK,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC5C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,oBAAoB,CAAA;IAE/E,YAAY,GAAW;QACrB,KAAK,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;;AAGH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IAClD,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,0BAA0B,CAAA;IAErF,YAAY,QAAgB;QAC1B,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAA;QACzC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,QAAQ,CAAA;IAC/C,CAAC;;AAGH,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IAChD,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,wBAAwB,CAAA;IAEnF,YAAY,MAAc;QACxB,KAAK,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,QAAQ,CAAA;IAC7C,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA;AAC/C,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,CAAA;AAC3D,cAAc,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAG,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEjD,MAAM,OAAO,aAAc,SAAQ,cAAc;IACxC,MAAM,CAAU,QAAQ,GAAG,eAAe,CAAA;IAEjD,YAAY,UAAkB,OAAO;QACnC,KAAK,CAAC,aAAa,CAAC,QAAQ,EAAE,YAAY,OAAO,EAAE,CAAC,CAAA;IACtD,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC5C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,oBAAoB,CAAA;IAExE,MAAM,CAAU,WAAW,GAAW,GAAG,CAAA;IAEhD,YAAY,EAAU;QACpB,KAAK,CAAC,iBAAiB,kBAAkB,CAAC,WAAW,GAAG,EAAE,EAAE,CAAC,CAAA;QAC7D,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;IAED,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9D,CAAC;;AAGH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IACzC,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,iBAAiB,CAAA;IAE5E,YAAY,GAAW;QACrB,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;;AAGH,MAAM,OAAO,YAAa,SAAQ,aAAa;IACtC,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,cAAc,CAAA;IAEzE,YAAY,GAAW;QACrB,KAAK,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAA;QAC7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAA;IACnC,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAC5C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,oBAAoB,CAAA;IAE/E,YAAY,GAAW;QACrB,KAAK,CAAC,wBAAwB,GAAG,EAAE,CAAC,CAAA;QACpC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;;AAGH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IAClD,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,0BAA0B,CAAA;IAErF,YAAY,QAAgB;QAC1B,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAA;QACzC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC,QAAQ,CAAA;IAC/C,CAAC;;AAGH,MAAM,OAAO,sBAAuB,SAAQ,aAAa;IAChD,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,wBAAwB,CAAA;IAEnF,YAAY,MAAc;QACxB,KAAK,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,QAAQ,CAAA;IAC7C,CAAC;;AAGH;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,aAAa;IACxC,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,gBAAgB,CAAA;IAE3E,YAAY,GAAW;QACrB,KAAK,CAAC,oBAAoB,GAAG,EAAE,CAAC,CAAA;QAChC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAC3C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,mBAAmB,CAAA;IAE9E,YAAY,GAAW;QACrB,KAAK,CAAC,sBAAsB,GAAG,EAAE,CAAC,CAAA;QAClC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA;AAC/C,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,wBAAwB,CAAC,CAAA;AAC3D,cAAc,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAA;AACzD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA"}

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,kBAAkB,GAAI,cAAa,MAAW,EAAE,WAAW,WAAW,GAAG,YAAY,EAAE,OAAO,WAAW,KAAG,WAsBxH,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,MAAM,EAAE,KAAG,CAMxD,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,YAAY,CAAA;AAEtE,eAAO,MAAM,kBAAkB,GAAI,cAAa,MAAW,EAAE,WAAW,WAAW,GAAG,YAAY,EAAE,OAAO,WAAW,KAAG,WAwBxH,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,MAAM,EAAE,KAAG,CAMxD,CAAA"}

package/build/helper.js

@@ -4,13 +4,14 @@ export const prepareListOptions = (defPageSize = 10, criteria, opts) => {
             criteria = {};
             opts = {};
         }
-        else if ('criteria' in criteria) {
-            criteria = criteria.criteria;
-            opts = { pager: criteria.pager };
-        }
-        else if ('pager' in criteria) {
-            opts = { pager: criteria.pager };
-            criteria = {};
+        else if ('criteria' in criteria || 'pager' in criteria) {
+            /**
+             * Both keys have to be read off the original object before it's reassigned —
+             * reading `pager` after narrowing to `.criteria` silently drops the pager.
+             */
+            const options = criteria;
+            opts = { pager: options.pager };
+            criteria = (options.criteria ?? {});
         }
     }
     const size = (opts?.pager?.size ?? defPageSize);

package/build/helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,cAAsB,EAAE,EAAE,QAAqC,EAAE,IAAkB,EAAe,EAAE;IACrI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,QAAQ,GAAG,EAAE,CAAA;YACb,IAAI,GAAG,EAAE,CAAA;QACX,CAAC;aAAM,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAClC,QAAQ,GAAG,QAAQ,CAAC,QAAwB,CAAA;YAC5C,IAAI,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAA8B,EAAE,CAAA;QAC3D,CAAC;aAAM,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,KAA8B,EAAE,CAAA;YACzD,QAAQ,GAAG,EAAE,CAAA;QACf,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,WAAW,CAAC,CAAA;IAC/C,MAAM,KAAK,GAAc;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC;QAC5B,IAAI,EAAE,KAAK,EAAE,CAAC;KACf,CAAA;IAED,OAAO,EAAE,QAAQ,EAAE,QAAwB,EAAE,KAAK,EAAE,CAAA;AACtD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAe,GAAM,EAAE,IAAe,EAAK,EAAE,CACvE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;IAC/C,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,EAAE,EAAO,CAAC,CAAA"}
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,cAAsB,EAAE,EAAE,QAAqC,EAAE,IAAkB,EAAe,EAAE;IACrI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,QAAQ,GAAG,EAAE,CAAA;YACb,IAAI,GAAG,EAAE,CAAA;QACX,CAAC;aAAM,IAAI,UAAU,IAAI,QAAQ,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YACzD;;;eAGG;YACH,MAAM,OAAO,GAAG,QAAuB,CAAA;YACvC,IAAI,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAA;YAC/B,QAAQ,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAiB,CAAA;QACrD,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,WAAW,CAAC,CAAA;IAC/C,MAAM,KAAK,GAAc;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI;QACvB,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC;QAC5B,IAAI,EAAE,KAAK,EAAE,CAAC;KACf,CAAA;IAED,OAAO,EAAE,QAAQ,EAAE,QAAwB,EAAE,KAAK,EAAE,CAAA;AACtD,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAe,GAAM,EAAE,IAAe,EAAK,EAAE,CACvE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;IAC/C,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC,EAAE,EAAO,CAAC,CAAA"}

package/build/index.d.ts

@@ -2,5 +2,6 @@ export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
 export * from './helper.js';
+export * from './migration.js';
 export type * from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,mBAAmB,YAAY,CAAA"}

package/build/index.js

@@ -2,4 +2,5 @@ export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
 export * from './helper.js';
+export * from './migration.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/build/migration.d.ts

@@ -0,0 +1,21 @@
+import type { MigrationRegistry, MigrationReport, MigrationRunOptions, MigrationStore } from './types.js';
+/**
+ * Storage agnostic ledger of code registered migrations for a single resource alias.
+ *
+ * Declaration order is the application order — the registry never sorts by name, so a
+ * migration that depends on an earlier one only has to be registered after it.
+ */
+export declare const createMigrationRegistry: <Tx = unknown>() => MigrationRegistry<Tx>;
+/**
+ * Apply the pending migrations of one stage for one resource alias.
+ *
+ * With `baseline: true` the structure has just been created from the current schema, so
+ * every registered migration is already satisfied by it — they're recorded as applied
+ * without running. Replaying a historical `ADD COLUMN` against a table that was just
+ * created with that column would fail, and replaying a backfill would scan for nothing.
+ *
+ * @throws {MigrationError} a migration threw — initialization must abort.
+ * @throws {MigrationConflict} an already applied migration's body has changed.
+ */
+export declare const runMigrations: <Tx = unknown>(alias: string, registry: MigrationRegistry<Tx>, store: MigrationStore<Tx>, opts?: MigrationRunOptions) => Promise<MigrationReport>;
+//# sourceMappingURL=migration.d.ts.map

package/build/migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../src/migration.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACC,iBAAiB,EAAE,eAAe,EAAE,mBAAmB,EAAE,cAAc,EACnF,MAAM,YAAY,CAAA;AAqBnB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,EAAE,GAAG,OAAO,OAAK,iBAAiB,CAAC,EAAE,CA+B5E,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GAAU,EAAE,GAAG,OAAO,EAC9C,OAAO,MAAM,EACb,UAAU,iBAAiB,CAAC,EAAE,CAAC,EAC/B,OAAO,cAAc,CAAC,EAAE,CAAC,EACzB,OAAO,mBAAmB,KACzB,OAAO,CAAC,eAAe,CAqDzB,CAAA"}

package/build/migration.js.map

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

package/build/types.d.ts

@@ -1,4 +1,5 @@
 import type { BasicConfig, BasicContext, BasicResource, LazyService } from '@owlmeans/context';
+import type { MigrationStage } from './consts.js';
 export interface Resource<T extends ResourceRecord> extends BasicResource {
     /**
      * @throws {UnknownRecordError}
@@ -101,6 +102,73 @@ export interface DbConfig<P extends {} = {}> {
     encryptionKey?: string;
     meta?: P;
 }
+/**
+ * Optional migration capability of a Resource implementation — optional the same way
+ * pub/sub is on redis resources: a backend that supports code migrations extends this
+ * interface (mongo, postgres), a backend with nothing to migrate simply never implements
+ * it. The base {@link Resource} contract stays migration free.
+ *
+ * The capability is automatic: implementations run the registered migrations during
+ * resource initialization (app setup), so a migration only has to be registered — never
+ * invoked. Backends with a durable structure also implement {@link MigrationStore}, the
+ * register that tracks which migrations have been applied.
+ */
+export interface MigratableResource<Tx = unknown> {
+    /**
+     * Register a migration, applied once per database in declaration order.
+     *
+     * Chainable and idempotent: re-registering the same name with the same body is a no-op,
+     * which is what makes it safe to call from a resource maker that `reinitializeContext`
+     * re-runs. Re-registering a *changed* body under a used name throws
+     * {@link MigrationConflict}.
+     */
+    migration: (name: string, apply: (tx: Tx) => Promise<void>, stage?: MigrationStage) => this;
+    /** The registered migrations for this resource's alias. Read-only; use {@link MigratableResource.migration}. */
+    migrations: () => MigrationRegistry<Tx>;
+}
+export interface Migration<Tx = unknown> {
+    name: string;
+    stage: MigrationStage;
+    apply: (tx: Tx) => Promise<void>;
+    /** Stable hash of the migration body — detects edits to an already applied migration. */
+    checksum: string;
+}
+export interface MigrationRegistry<Tx = unknown> {
+    register: (name: string, apply: (tx: Tx) => Promise<void>, stage?: MigrationStage) => MigrationRegistry<Tx>;
+    list: (stage?: MigrationStage) => Migration<Tx>[];
+    has: (name: string) => boolean;
+}
+/**
+ * The database specific half of the migration subsystem. Postgres and Mongo each
+ * provide an implementation; {@link runMigrations} stays storage agnostic.
+ */
+export interface MigrationStore<Tx = unknown> {
+    /** Create the tracking structure if it's absent. */
+    ensure: () => Promise<void>;
+    /** Names already applied for the given resource alias, mapped to their recorded checksum. */
+    applied: (alias: string) => Promise<Record<string, string | null>>;
+    /** Record migrations as applied *without* running them — used on freshly created structures. */
+    baseline: (alias: string, migrations: Migration<Tx>[]) => Promise<void>;
+    /** Run one migration and record it atomically. */
+    run: (alias: string, migration: Migration<Tx>) => Promise<void>;
+}
+export interface MigrationRunOptions {
+    stage?: MigrationStage;
+    /**
+     * The structure has just been created, so every registered migration is already
+     * satisfied by it — record them instead of running them.
+     */
+    baseline?: boolean;
+    /** Throw when an already applied migration's body has changed. Defaults to `true`. */
+    strictChecksum?: boolean;
+}
+export interface MigrationReport {
+    alias: string;
+    stage: MigrationStage;
+    applied: string[];
+    baselined: string[];
+    skipped: string[];
+}
 export interface Config extends BasicConfig {
     dbs?: DbConfig[];
 }

package/build/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/resource",
-  "version": "0.1.14",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,8 +22,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@owlmeans/context": "^0.1.14",
-    "@owlmeans/error": "^0.1.14",
+    "@owlmeans/context": "^0.1.16-rc.0",
+    "@owlmeans/error": "^0.1.16-rc.0",
     "@scure/base": "^1.1.9"
   },
   "peerDependencies": {

package/src/consts.ts

@@ -1,6 +1,23 @@
 import type { JSONSchemaType } from 'ajv'
 import type { ListResult, ResourceRecord } from './types.js'
 
+/**
+ * When a migration runs relative to the structure reconciliation a db implementation
+ * performs at resource initialization.
+ *
+ * - `pre` — before the structure is reconciled. This is where a change reconciliation
+ *   cannot express correctly belongs: renames, casts that need a `USING` expression,
+ *   backfills that have to precede a `NOT NULL`. Once the migration has reshaped the
+ *   structure, reconciliation observes no drift and emits nothing — the two mechanisms
+ *   never fight because the migration pre-empts the reconciler.
+ * - `post` — after reconciliation. For data backfills into columns reconciliation has
+ *   just created.
+ */
+export enum MigrationStage {
+  Pre = 'pre',
+  Post = 'post'
+}
+
 export const createListSchema = <T extends ResourceRecord>(schema: JSONSchemaType<T>): JSONSchemaType<ListResult<T>> => ({
   type: 'object',
   properties: {

package/src/errors.ts

@@ -69,6 +69,34 @@ export class UnsupportedMethodError extends ResourceError {
   }
 }
 
+/**
+ * A registered migration threw while being applied. Resource initialization aborts —
+ * a structure problem has to fail the boot loudly rather than leave the process
+ * running against a half-shaped database.
+ */
+export class MigrationError extends ResourceError {
+  public static override typeName = `${ResourceError.typeName}MigrationError`
+
+  constructor(msg: string) {
+    super(`migration-failed:${msg}`)
+    this.type = MigrationError.typeName
+  }
+}
+
+/**
+ * A migration name was registered twice with different bodies, or an already applied
+ * migration's body has changed since it ran. Write a new migration instead of editing
+ * one that has already been applied somewhere.
+ */
+export class MigrationConflict extends ResourceError {
+  public static override typeName = `${ResourceError.typeName}MigrationConflict`
+
+  constructor(msg: string) {
+    super(`migration-conflict:${msg}`)
+    this.type = MigrationConflict.typeName
+  }
+}
+
 ResilientError.registerErrorClass(ResourceError)
 ResilientError.registerErrorClass(UnknownRecordError)
 ResilientError.registerErrorClass(MisshapedRecord)
@@ -76,3 +104,5 @@ ResilientError.registerErrorClass(RecordExists)
 ResilientError.registerErrorClass(RecordUpdateFailed)
 ResilientError.registerErrorClass(UnsupportedArgumentError)
 ResilientError.registerErrorClass(UnsupportedMethodError)
+ResilientError.registerErrorClass(MigrationError)
+ResilientError.registerErrorClass(MigrationConflict)

package/src/helper.ts

@@ -5,12 +5,14 @@ export const prepareListOptions = (defPageSize: number = 10, criteria?: ListOpti
     if (criteria == null) {
       criteria = {}
       opts = {}
-    } else if ('criteria' in criteria) {
-      criteria = criteria.criteria as ListCriteria
-      opts = { pager: criteria.pager as ListPager | undefined }
-    } else if ('pager' in criteria) {
-      opts = { pager: criteria.pager as ListPager | undefined }
-      criteria = {}
+    } else if ('criteria' in criteria || 'pager' in criteria) {
+      /**
+       * Both keys have to be read off the original object before it's reassigned —
+       * reading `pager` after narrowing to `.criteria` silently drops the pager.
+       */
+      const options = criteria as ListOptions
+      opts = { pager: options.pager }
+      criteria = (options.criteria ?? {}) as ListCriteria
     }
   }
 

package/src/index.ts

@@ -3,4 +3,5 @@ export * from './errors.js'
 export * from './consts.js'
 export * from './service.js'
 export * from './helper.js'
+export * from './migration.js'
 export type * from './types.js'

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { BasicConfig, BasicContext, BasicResource, LazyService } from '@owlmeans/context'
+import type { MigrationStage } from './consts.js'
 
 export interface Resource<T extends ResourceRecord> extends BasicResource {
   /**
@@ -121,6 +122,79 @@ export interface DbConfig<P extends {} = {}> {
   meta?: P
 }
 
+/**
+ * Optional migration capability of a Resource implementation — optional the same way
+ * pub/sub is on redis resources: a backend that supports code migrations extends this
+ * interface (mongo, postgres), a backend with nothing to migrate simply never implements
+ * it. The base {@link Resource} contract stays migration free.
+ *
+ * The capability is automatic: implementations run the registered migrations during
+ * resource initialization (app setup), so a migration only has to be registered — never
+ * invoked. Backends with a durable structure also implement {@link MigrationStore}, the
+ * register that tracks which migrations have been applied.
+ */
+export interface MigratableResource<Tx = unknown> {
+  /**
+   * Register a migration, applied once per database in declaration order.
+   *
+   * Chainable and idempotent: re-registering the same name with the same body is a no-op,
+   * which is what makes it safe to call from a resource maker that `reinitializeContext`
+   * re-runs. Re-registering a *changed* body under a used name throws
+   * {@link MigrationConflict}.
+   */
+  migration: (name: string, apply: (tx: Tx) => Promise<void>, stage?: MigrationStage) => this
+  /** The registered migrations for this resource's alias. Read-only; use {@link MigratableResource.migration}. */
+  migrations: () => MigrationRegistry<Tx>
+}
+
+export interface Migration<Tx = unknown> {
+  name: string
+  stage: MigrationStage
+  apply: (tx: Tx) => Promise<void>
+  /** Stable hash of the migration body — detects edits to an already applied migration. */
+  checksum: string
+}
+
+export interface MigrationRegistry<Tx = unknown> {
+  register: (name: string, apply: (tx: Tx) => Promise<void>, stage?: MigrationStage) => MigrationRegistry<Tx>
+  list: (stage?: MigrationStage) => Migration<Tx>[]
+  has: (name: string) => boolean
+}
+
+/**
+ * The database specific half of the migration subsystem. Postgres and Mongo each
+ * provide an implementation; {@link runMigrations} stays storage agnostic.
+ */
+export interface MigrationStore<Tx = unknown> {
+  /** Create the tracking structure if it's absent. */
+  ensure: () => Promise<void>
+  /** Names already applied for the given resource alias, mapped to their recorded checksum. */
+  applied: (alias: string) => Promise<Record<string, string | null>>
+  /** Record migrations as applied *without* running them — used on freshly created structures. */
+  baseline: (alias: string, migrations: Migration<Tx>[]) => Promise<void>
+  /** Run one migration and record it atomically. */
+  run: (alias: string, migration: Migration<Tx>) => Promise<void>
+}
+
+export interface MigrationRunOptions {
+  stage?: MigrationStage
+  /**
+   * The structure has just been created, so every registered migration is already
+   * satisfied by it — record them instead of running them.
+   */
+  baseline?: boolean
+  /** Throw when an already applied migration's body has changed. Defaults to `true`. */
+  strictChecksum?: boolean
+}
+
+export interface MigrationReport {
+  alias: string
+  stage: MigrationStage
+  applied: string[]
+  baselined: string[]
+  skipped: string[]
+}
+
 export interface Config extends BasicConfig {
   dbs?: DbConfig[]
 }