@decaf-ts/for-nano 0.5.18 → 0.6.0

package/README.md

@@ -268,8 +268,114 @@ await NanoAdapter.createDatabase(url, "mydb");
 // ... createUser/deleteUser, deleteDatabase, etc.
 ```
 
+## Task Engine guardrails for migration orchestration
 
+Migration command runners and the integration tests rely on a dedicated `RamAdapter` task engine that never shares an alias with the adapters being migrated. `MigrationService.migrateAdapters` enforces this guardrail by comparing every adapter alias and rejecting runs where the task engine would also be a migration target. Keep your task engine adapter isolated (for example `new RamAdapter({}, "decaf-cli-task-engine")`) and set `concurrency: 1` so version steps stay sequential.
 
+```ts
+import { RamAdapter } from "@decaf-ts/core/ram";
+import { TaskService } from "@decaf-ts/core/tasks";
+
+const taskEngineAdapter = new RamAdapter({}, "decaf-cli-task-engine");
+const taskService = new TaskService();
+await taskService.boot({
+  adapter: taskEngineAdapter,
+  workerId: "nano-migration-worker",
+  leaseMs: 10_000,
+  logTailMax: 250,
+});
+```
+
+Reserve `leaseMs` for longer-running migrations, tune `pollMsBusy`/`pollMsIdle`, and attach a `TaskEventBus` if you want progress logs in the CLI output. `taskService.track(taskId)` can then stream the same progress/log events that the integration tests already observe.
+
+## Migration lifecycle and @migration semantics for Nano
+
+`@migration` metadata controls ordering and flavour targeting:
+
+```ts
+@migration("1.1.0-add-category-field", {
+  precedence: "1.1.0",
+  flavour: "nano",
+  rules: [
+    async (_, adapter) => Boolean(await adapter.exists("for_nano_migration_products")),
+  ],
+})
+class AddCategoryMigration extends AbsMigration<NanoAdapter> { ... }
+```
+
+- `reference`: the canonical label (usually the semver string) used for logging, precedence tokens, and version normalization.
+- `precedence`: a constructor, reference string, or object pointing to another migration to force ordering when version/flavour collide.
+- `flavour`: limits execution to the Nano flavour (the for-nano tests only execute Nano-scoped migrations).
+- `rules`: async predicates `(qr, adapter, ctx)` that gate execution; a `false` result skips the migration without failing the run.
+
+`MigrationService` also expects handlers for `retrieveLastVersion` and `setCurrentVersion`. These functions are invoked per flavour so you can persist the head (e.g., in a `VersionRepo`). During the live integration test we initialize the version map at `"1.0.0"` and let `setCurrentVersion` advance it to the target version once the required property addition/backfill completes.
+
+Use `MigrationService.migrateAdapters([nanoAdapter], { toVersion: "2.0.0", handlers: {...}, taskMode: true, taskService })` once your `NanoAdapter` is initialized. `taskMode: true` queues one `CompositeTask` per version and calls `setCurrentVersion` immediately after each task resolves, which keeps the persistent version marker aligned with the latest fully applied hop. Normal mode updates the version only after the whole batch finishes.
+
+`MigrationService.retry(taskId)` rewrites the failed `TaskModel` to `PENDING`, clears `error`, `leaseOwner`, and timestamps, and re-enqueues the same version so the CLI can resume from the failing point. Because the version marker wasn't advanced for the failed task, rerunning the CLI with the same `toVersion` continues at the correct semantic boundary. Our tests ensure that every migration adds a required property/column and fills existing documents with the default value before the next version runs.
+
+
+
+
+## Live migration workflow
+
+Migration integration suites run against live CouchDB instances. `for-nano` tests are intentionally limited to `RamAdapter` + `NanoAdapter` so they stay independent of SQL modules. That means:
+
+- Every migration must add a new required property/column and backfill every existing document with the default value before continuing.
+- Use `MigrationService.migrateAdapters([nanoAdapter], config)` with flavour-scoped handlers so the last executed version is persisted independently per adapter.
+- If you turn on `taskMode`, boot a separate `RamAdapter` (alias distinct from the ones being migrated) before you create the `TaskService`. The migration guard throws if the task engine adapter alias is also a migration target.
+
+```ts
+@migration("1.1.0-add-isActive", {
+  precedence: "1.1.0",
+  flavour: "nano",
+})
+export class AddIsActiveMigration implements Migration<any, NanoAdapter> {
+  async up(_, adapter) {
+    const repo = new Repository(adapter, UserModel);
+    const users = await repo.select().execute();
+    await Promise.all(
+      users.map((user) => repo.update({ ...user, isActive: true }))
+    );
+  }
+}
+```
+
+```ts
+const migrations = await MigrationService.migrateAdapters(
+  [nanoAdapter],
+  {
+    toVersion: "1.1.0",
+    flavours: ["nano"],
+    taskMode: true,
+    taskService,
+    handlers: {
+      nano: {
+        retrieveLastVersion: async (adapter) =>
+          (await versionRepo(adapter).read("nano"))?.version,
+        setCurrentVersion: async (version, adapter) =>
+          await versionRepo(adapter).upsert("nano", { version }),
+      },
+    },
+  }
+);
+for (const migration of migrations) {
+  await migration.track();
+}
+```
+
+`MigrationService` starts by calling the flavour-specific `retrieveLastVersion` handler so it knows which version the database already holds, then filters decorated migrations whose normalized versions are strictly greater than `currentVersion` and less than or equal to `toVersion`. `setCurrentVersion` is invoked after every successfully completed version: inline runs update once at the very end, while task mode updates immediately after each tracked `CompositeTask`. This guarantees the recorded `currentVersion` always equals the last fully finished hop, so rerunning the command will skip completed versions and replay only the pending ones. When a task fails, call `MigrationService.retry(taskId)` (optionally `taskService.track(id)` to observe progress) to reset the `TaskModel` to `PENDING`, clear its error/lease metadata, and let the TaskEngine reclaim the same version without revisiting already finished steps.
+
+The `@migration` decorator handles ordering and targeting. The key arguments are:
+
+- `reference`: the name/semver label used in logs and dependency graphs.
+- `precedence`: optional hint (a constructor, string, or object) that the sorter uses when two migrations share the same version and flavour.
+- `flavour`: restricts the migration to one adapter flavour (`"nano"`, `"type-orm"`, etc.). Omit it for generic migrations or to let `includeGenericInTaskMode` decide when to run.
+- `rules`: async predicates that gate execution (`(qr, adapter, ctx) => Promise<boolean>`). When a rule returns `false` the migration is skipped without error.
+
+The CLI migrations guard enforces that the `TaskEngine` runs on a separate `RamAdapter` alias that is never one of the migrating adapters, keeping persistence targets isolated and preventing lease conflicts.
+
+Use `MigrationRule`s (the `rules` array in `@migration`) to gate execution based on adapter state. Keep every migration focused on one version jump so the live suites can always rerun and verify the required schema change and backfill.
 
 ## Coding Principles
 

package/lib/esm/index.d.ts

@@ -13,7 +13,7 @@ export * from "./adapter";
  * @const VERSION
  * @memberOf module:for-nano
  */
-export declare const VERSION = "0.5.17";
+export declare const VERSION = "0.5.18";
 /**
  * @description Package version identifier
  * @summary Stores the current package version string for the for-nano module

package/lib/esm/index.js

@@ -18,7 +18,7 @@ export * from "./adapter.js";
  * @const VERSION
  * @memberOf module:for-nano
  */
-export const VERSION = "0.5.17";
+export const VERSION = "0.5.18";
 /**
  * @description Package version identifier
  * @summary Stores the current package version string for the for-nano module

package/lib/index.cjs

@@ -35,7 +35,7 @@ __exportStar(require("./adapter.cjs"), exports);
  * @const VERSION
  * @memberOf module:for-nano
  */
-exports.VERSION = "0.5.17";
+exports.VERSION = "0.5.18";
 /**
  * @description Package version identifier
  * @summary Stores the current package version string for the for-nano module

package/lib/index.d.ts

@@ -13,7 +13,7 @@ export * from "./adapter";
  * @const VERSION
  * @memberOf module:for-nano
  */
-export declare const VERSION = "0.5.17";
+export declare const VERSION = "0.5.18";
 /**
  * @description Package version identifier
  * @summary Stores the current package version string for the for-nano module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/for-nano",
-  "version": "0.5.18",
+  "version": "0.6.0",
   "description": "decaf-ts persistence adapter for CouchDB via nano",
   "type": "module",
   "exports": {