@kubun/store-workflow 0.16.0 → 0.17.1

package/lib/api.d.ts

@@ -1,5 +1,5 @@
 import type { Adapter } from '@kubun/db-adapter';
-import type { Kysely } from 'kysely';
+import { type Kysely } from 'kysely';
 import type { WorkflowInstance, WorkflowSchedule, WorkflowTables } from './tables.js';
 export type WorkflowStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
 export type WorkflowNextAction = {
@@ -46,6 +46,10 @@ export type FinishInput = {
     status: 'completed' | 'cancelled';
     state: unknown;
 };
+export type PurgeFinishedInput = {
+    before: number;
+    limit: number;
+};
 export type ListFilter = {
     name?: string;
     queue?: string;
@@ -85,6 +89,7 @@ export type UpsertAdaptiveScheduleInput = {
 };
 export type WorkflowStoreAPI = {
     insertInstance(input: InsertInstanceInput): Promise<InsertInstanceResult>;
+    insertInstanceTx(input: InsertInstanceInput): Promise<InsertInstanceResult>;
     claim(instanceID: string, bootID: string, leaseMs: number, now: number): Promise<WorkflowInstanceRow | null>;
     claimDue(queue: string, limit: number, bootID: string, leaseMs: number, now: number): Promise<Array<WorkflowInstanceRow>>;
     renew(instanceID: string, bootID: string, leaseMs: number, now: number): Promise<boolean>;
@@ -97,6 +102,7 @@ export type WorkflowStoreAPI = {
     listRunnableQueues(now: number): Promise<Array<string>>;
     get(instanceID: string): Promise<WorkflowInstanceRow | null>;
     list(filter?: ListFilter): Promise<Array<WorkflowInstanceRow>>;
+    purgeFinished(input: PurgeFinishedInput): Promise<number>;
     insertSchedule(input: InsertScheduleInput, now: number): Promise<void>;
     upsertAdaptiveSchedule(input: UpsertAdaptiveScheduleInput, now: number): Promise<WorkflowScheduleRow>;
     getSchedule(id: string): Promise<WorkflowScheduleRow | null>;

package/lib/api.js

@@ -1,3 +1,11 @@
+import { sql } from 'kysely';
+// The statuses a run never leaves on its own. `failed` is one: only an
+// explicit `retryFailed` re-arms it, and not once retention has deleted it.
+const FINISHED_STATUSES = [
+    'completed',
+    'failed',
+    'cancelled'
+];
 // --- Serialization helpers ---
 // ParseJSONResultsPlugin usually parses JSON columns back to objects, but a
 // value can still arrive as a string (adapter/driver dependent). Handle both.
@@ -30,100 +38,108 @@ export function createWorkflowStore(db, adapter) {
     async function readRow(tx, instanceID) {
         return await tx.selectFrom('kubun_workflow_instances').selectAll().where('instance_id', '=', instanceID).executeTakeFirst();
     }
+    // Shared body for insertInstance/insertInstanceTx: the pre-checks + guarded
+    // insert, run against whichever `tx` the caller hands in. insertInstance
+    // opens its own `db.transaction()` and passes that; insertInstanceTx passes
+    // `db` directly, assuming it is already the caller's open transaction.
+    async function insertInstanceOnTx(tx, input) {
+        const queue = input.queue ?? input.name;
+        const runAfter = input.runAfter ?? input.createdAt;
+        const updatedAt = input.updatedAt ?? input.createdAt;
+        if (input.idempotencyKey != null) {
+            const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
+            if (existing != null) {
+                return {
+                    row: rowToInstance(existing),
+                    created: false,
+                    reason: 'idempotent'
+                };
+            }
+        }
+        if (input.singletonKey != null) {
+            const active = await tx.selectFrom('kubun_workflow_instances').selectAll().where('name', '=', input.name).where('singleton_key', '=', input.singletonKey).where('status', 'in', [
+                'pending',
+                'running'
+            ]).executeTakeFirst();
+            if (active != null) {
+                return {
+                    row: rowToInstance(active),
+                    created: false,
+                    reason: 'singleton'
+                };
+            }
+        }
+        // ON CONFLICT DO NOTHING makes the insert atomic against a racer this
+        // snapshot's pre-checks could not yet see: two inserts for the same
+        // idempotency_key (the cross-hub idempotent retry) or the same active
+        // singleton both clear the pre-checks, and the unique indexes arbitrate.
+        // The loser inserts nothing and reads the winner's row below — no
+        // adapter-specific constraint-error parsing.
+        await tx.insertInto('kubun_workflow_instances').values({
+            instance_id: input.instanceID,
+            name: input.name,
+            queue,
+            idempotency_key: input.idempotencyKey ?? null,
+            singleton_key: input.singletonKey ?? null,
+            priority: input.priority ?? 0,
+            state: encodeJSON(input.state ?? {}),
+            next_action: encodeNextAction(input.nextAction ?? null),
+            status: 'pending',
+            attempts: 0,
+            run_after: runAfter,
+            lease_owner: null,
+            lease_expires: null,
+            last_error: null,
+            created_at: input.createdAt,
+            updated_at: updatedAt
+        }).onConflict((oc)=>oc.doNothing()).execute();
+        const row = await tx.selectFrom('kubun_workflow_instances').selectAll().where('instance_id', '=', input.instanceID).executeTakeFirst();
+        if (row != null) {
+            return {
+                row: rowToInstance(row),
+                created: true
+            };
+        }
+        // The insert was a no-op: a concurrent racer holds the conflicting key.
+        // Return its row as the idempotent/singleton hit, mirroring the pre-checks.
+        if (input.idempotencyKey != null) {
+            const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
+            if (existing != null) {
+                return {
+                    row: rowToInstance(existing),
+                    created: false,
+                    reason: 'idempotent'
+                };
+            }
+        }
+        if (input.singletonKey != null) {
+            const active = await tx.selectFrom('kubun_workflow_instances').selectAll().where('name', '=', input.name).where('singleton_key', '=', input.singletonKey).where('status', 'in', [
+                'pending',
+                'running'
+            ]).executeTakeFirst();
+            if (active != null) {
+                return {
+                    row: rowToInstance(active),
+                    created: false,
+                    reason: 'singleton'
+                };
+            }
+        }
+        // A no-op insert with no recoverable conflicting row means the constraint
+        // hit was neither unique index we recover from — surface it, never a
+        // silent empty return.
+        throw new Error(`Workflow instance "${input.instanceID}" insert did nothing but no conflicting row was found`);
+    }
     return {
         async insertInstance (input) {
-            const queue = input.queue ?? input.name;
-            const runAfter = input.runAfter ?? input.createdAt;
-            const updatedAt = input.updatedAt ?? input.createdAt;
             // The transaction gives the pre-checks and the insert one snapshot. The
             // partial unique index is the race backstop; the graceful created:false
             // return is the sequential pre-check path, so no driver error strings are
             // parsed.
-            return await db.transaction().execute(async (tx)=>{
-                if (input.idempotencyKey != null) {
-                    const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
-                    if (existing != null) {
-                        return {
-                            row: rowToInstance(existing),
-                            created: false,
-                            reason: 'idempotent'
-                        };
-                    }
-                }
-                if (input.singletonKey != null) {
-                    const active = await tx.selectFrom('kubun_workflow_instances').selectAll().where('name', '=', input.name).where('singleton_key', '=', input.singletonKey).where('status', 'in', [
-                        'pending',
-                        'running'
-                    ]).executeTakeFirst();
-                    if (active != null) {
-                        return {
-                            row: rowToInstance(active),
-                            created: false,
-                            reason: 'singleton'
-                        };
-                    }
-                }
-                // ON CONFLICT DO NOTHING makes the insert atomic against a racer this
-                // snapshot's pre-checks could not yet see: two inserts for the same
-                // idempotency_key (the cross-hub idempotent retry) or the same active
-                // singleton both clear the pre-checks, and the unique indexes arbitrate.
-                // The loser inserts nothing and reads the winner's row below — no
-                // adapter-specific constraint-error parsing.
-                await tx.insertInto('kubun_workflow_instances').values({
-                    instance_id: input.instanceID,
-                    name: input.name,
-                    queue,
-                    idempotency_key: input.idempotencyKey ?? null,
-                    singleton_key: input.singletonKey ?? null,
-                    priority: input.priority ?? 0,
-                    state: encodeJSON(input.state ?? {}),
-                    next_action: encodeNextAction(input.nextAction ?? null),
-                    status: 'pending',
-                    attempts: 0,
-                    run_after: runAfter,
-                    lease_owner: null,
-                    lease_expires: null,
-                    last_error: null,
-                    created_at: input.createdAt,
-                    updated_at: updatedAt
-                }).onConflict((oc)=>oc.doNothing()).execute();
-                const row = await tx.selectFrom('kubun_workflow_instances').selectAll().where('instance_id', '=', input.instanceID).executeTakeFirst();
-                if (row != null) {
-                    return {
-                        row: rowToInstance(row),
-                        created: true
-                    };
-                }
-                // The insert was a no-op: a concurrent racer holds the conflicting key.
-                // Return its row as the idempotent/singleton hit, mirroring the pre-checks.
-                if (input.idempotencyKey != null) {
-                    const existing = await tx.selectFrom('kubun_workflow_instances').selectAll().where('idempotency_key', '=', input.idempotencyKey).executeTakeFirst();
-                    if (existing != null) {
-                        return {
-                            row: rowToInstance(existing),
-                            created: false,
-                            reason: 'idempotent'
-                        };
-                    }
-                }
-                if (input.singletonKey != null) {
-                    const active = await tx.selectFrom('kubun_workflow_instances').selectAll().where('name', '=', input.name).where('singleton_key', '=', input.singletonKey).where('status', 'in', [
-                        'pending',
-                        'running'
-                    ]).executeTakeFirst();
-                    if (active != null) {
-                        return {
-                            row: rowToInstance(active),
-                            created: false,
-                            reason: 'singleton'
-                        };
-                    }
-                }
-                // A no-op insert with no recoverable conflicting row means the constraint
-                // hit was neither unique index we recover from — surface it, never a
-                // silent empty return.
-                throw new Error(`Workflow instance "${input.instanceID}" insert did nothing but no conflicting row was found`);
-            });
+            return await db.transaction().execute((tx)=>insertInstanceOnTx(tx, input));
+        },
+        async insertInstanceTx (input) {
+            return await insertInstanceOnTx(db, input);
         },
         async claim (instanceID, bootID, leaseMs, now) {
             // One atomic UPDATE. Claimable when pending, or when a running lease has
@@ -273,6 +289,49 @@ export function createWorkflowStore(db, adapter) {
             const rows = await query.execute();
             return rows.map(rowToInstance);
         },
+        async purgeFinished (input) {
+            if (!Number.isFinite(input.before)) {
+                throw new Error('purgeFinished: before must be a finite number');
+            }
+            if (!Number.isInteger(input.limit) || input.limit <= 0) {
+                throw new Error('purgeFinished: limit must be a positive integer');
+            }
+            const { before, limit } = input;
+            // Finished before the cutoff, and holding no lease that outlives it.
+            const finished = (eb)=>eb.and([
+                    eb('status', 'in', FINISHED_STATUSES),
+                    eb('updated_at', '<', before),
+                    eb.or([
+                        eb('lease_expires', 'is', null),
+                        eb('lease_expires', '<', before)
+                    ])
+                ]);
+            // One statement, so the keep rule and the delete see the same rows. A
+            // row of a scheduled subject is only deleted while a newer row of the
+            // same (name, singleton_key) exists; the newest never has one, so no
+            // batch and no concurrent cleanup can delete it. A row only gets newer
+            // by being written, and a written row is no longer past the cutoff.
+            const result = await db.deleteFrom('kubun_workflow_instances').where('instance_id', 'in', (eb)=>eb.selectFrom('kubun_workflow_instances as i').select('i.instance_id').where('i.status', 'in', FINISHED_STATUSES).where('i.updated_at', '<', before).where((inner)=>inner.or([
+                        inner('i.lease_expires', 'is', null),
+                        inner('i.lease_expires', '<', before)
+                    ])).where((inner)=>inner.or([
+                        inner('i.singleton_key', 'is', null),
+                        inner.not(inner.exists(inner.selectFrom('kubun_workflow_schedules as s').select('s.id').whereRef('s.workflow_name', '=', 'i.name')// Adaptive schedule ids are `<name>:<subject>`; the
+                        // `||` concatenation is portable across SQLite and Postgres.
+                        .where('s.id', '=', sql`${sql.ref('i.name')} || ':' || ${sql.ref('i.singleton_key')}`))),
+                        inner.exists(inner.selectFrom('kubun_workflow_instances as n').select('n.instance_id').whereRef('n.name', '=', 'i.name').whereRef('n.singleton_key', '=', 'i.singleton_key').where((order)=>order.or([
+                                order('n.updated_at', '>', order.ref('i.updated_at')),
+                                order.and([
+                                    order('n.updated_at', '=', order.ref('i.updated_at')),
+                                    order('n.instance_id', '>', order.ref('i.instance_id'))
+                                ])
+                            ])))
+                    ])).orderBy('i.updated_at').orderBy('i.instance_id').limit(limit))// Re-checked on the row being deleted: a row re-armed or claimed
+            // between the candidate read and the delete (Postgres, read committed)
+            // is kept.
+            .where(finished).executeTakeFirst();
+            return Number(result?.numDeletedRows ?? 0n);
+        },
         // --- Schedules ---
         async insertSchedule (input, now) {
             await db.insertInto('kubun_workflow_schedules').values({

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import type { StoreProvider } from '@kubun/db';
 import type { WorkflowStoreAPI } from './api.js';
-export type { AdvanceScheduleAdaptiveInput, CheckpointInput, FailInput, FinishInput, InsertInstanceInput, InsertInstanceResult, InsertReason, InsertScheduleInput, ListFilter, WorkflowInstanceRow, WorkflowNextAction, WorkflowScheduleRow, WorkflowStatus, WorkflowStoreAPI, } from './api.js';
+export type { AdvanceScheduleAdaptiveInput, CheckpointInput, FailInput, FinishInput, InsertInstanceInput, InsertInstanceResult, InsertReason, InsertScheduleInput, ListFilter, PurgeFinishedInput, WorkflowInstanceRow, WorkflowNextAction, WorkflowScheduleRow, WorkflowStatus, WorkflowStoreAPI, } from './api.js';
 export { createWorkflowStore } from './api.js';
 export { workflowStoreDefinition } from './definition.js';
 export { WORKFLOW_SINGLETON_UNIQUE_INDEX } from './migrations.js';

package/lib/migrations.js

@@ -38,6 +38,17 @@ export function getWorkflowMigrations(ctx) {
                 'status',
                 'lease_expires'
             ]).execute();
+            // Retention scan: finished rows oldest first.
+            await db.schema.createIndex('idx_workflow_instances_finished').ifNotExists().on('kubun_workflow_instances').columns([
+                'status',
+                'updated_at'
+            ]).execute();
+            // Newest instance of a singleton subject: the row retention keeps.
+            await db.schema.createIndex('idx_workflow_instances_subject').ifNotExists().on('kubun_workflow_instances').columns([
+                'name',
+                'singleton_key',
+                'updated_at'
+            ]).execute();
             await db.schema.createTable('kubun_workflow_schedules').ifNotExists().addColumn('id', t.text, (col)=>col.notNull().primaryKey()).addColumn('workflow_name', t.text, (col)=>col.notNull()).addColumn('params', t.json, (col)=>col.notNull())// Exactly one of cron / every is set; both nullable, the store persists
             // them without parsing.
             .addColumn('cron', t.text).addColumn('every', t.text)// Default keeps existing interval inserts working unchanged.
@@ -54,6 +65,8 @@ export function getWorkflowMigrations(ctx) {
         async down (db) {
             await db.schema.dropIndex('idx_workflow_schedules_due').ifExists().execute();
             await db.schema.dropTable('kubun_workflow_schedules').ifExists().execute();
+            await db.schema.dropIndex('idx_workflow_instances_subject').ifExists().execute();
+            await db.schema.dropIndex('idx_workflow_instances_finished').ifExists().execute();
             await db.schema.dropIndex('idx_workflow_instances_recovery').ifExists().execute();
             await db.schema.dropIndex('idx_workflow_instances_claim').ifExists().execute();
             await db.schema.dropIndex(WORKFLOW_SINGLETON_UNIQUE_INDEX).ifExists().execute();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/store-workflow",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,13 +15,13 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/db": "^0.16.0",
-    "@kubun/db-adapter": "^0.16.0",
-    "kysely": "^0.29.5"
+    "@kubun/db": "^0.17.0",
+    "@kubun/db-adapter": "^0.17.0",
+    "kysely": "^0.29.6"
   },
   "devDependencies": {
-    "@kubun/db-better-sqlite": "^0.16.0",
-    "@kubun/db-postgres": "^0.16.0",
+    "@kubun/db-better-sqlite": "^0.17.0",
+    "@kubun/db-postgres": "^0.17.1",
     "@testcontainers/postgresql": "^12.1.0"
   },
   "publishConfig": {
@@ -30,8 +30,8 @@
   "scripts": {
     "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
-    "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
-    "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
+    "build:js": "del 'lib/**/*.js' && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del 'lib/**/*.d.ts' 'lib/**/*.d.ts.map' && tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
     "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",