@mantajs/core 0.1.7 → 0.2.0-beta.1

package/dist/workflows/progress-helper.js

@@ -0,0 +1,48 @@
+// ctx.progress — fire-and-forget progress reporting for workflow steps.
+// See WORKFLOW_PROGRESS.md §6.2 and §10.2.
+//
+// Invariants:
+// 1. Synchronous return — never awaited on the hot path.
+// 2. Never throws — channel errors are logged and swallowed.
+// 3. No throttle — the channel adapter copes with volume.
+import { MantaError } from '../errors/manta-error.js';
+/**
+ * CancelledError — thrown by step handlers (and by `ctx.forEach`) when the
+ * workflow's AbortSignal has fired. Caught by the engine to trigger the
+ * `cancelled` status path + compensation (WORKFLOW_PROGRESS.md §10.1 step 6).
+ */
+export class CancelledError extends MantaError {
+    constructor(message = 'Workflow cancelled') {
+        super('CONFLICT', message, { code: 'WORKFLOW_CANCELLED' });
+        this.name = 'CancelledError';
+    }
+}
+/**
+ * Build a `ctx.progress` function bound to a specific workflow run.
+ * If no IProgressChannelPort is wired, the returned function is a no-op.
+ *
+ * The returned function:
+ * - Returns `undefined` synchronously (no await on the hot path).
+ * - Never throws — channel errors are swallowed (optionally logged).
+ */
+export function createProgress(wfCtx) {
+    return (current, total, message) => {
+        const channel = wfCtx.progressChannel;
+        if (!channel)
+            return;
+        const stepName = wfCtx.stepName ?? 'unknown';
+        try {
+            const p = channel.set(wfCtx.runId, { stepName, current, total, message, at: Date.now() });
+            if (p && typeof p.catch === 'function') {
+                ;
+                p.catch(() => {
+                    // Progress is observability, not correctness — swallow.
+                });
+            }
+        }
+        catch {
+            // `.set` is spec'd never to throw, but we belt-and-suspenders it anyway.
+        }
+    };
+}
+//# sourceMappingURL=progress-helper.js.map

package/dist/workflows/progress-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-helper.js","sourceRoot":"","sources":["../../src/workflows/progress-helper.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2CAA2C;AAC3C,EAAE;AACF,cAAc;AACd,yDAAyD;AACzD,6DAA6D;AAC7D,0DAA0D;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAGrD;;;;GAIG;AACH,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAY,OAAO,GAAG,oBAAoB;QACxC,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAA;QAC1D,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;IAC9B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAsB;IAEtB,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACjC,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,CAAA;QACrC,IAAI,CAAC,OAAO;YAAE,OAAM;QACpB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,SAAS,CAAA;QAC5C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;YACzF,IAAI,CAAC,IAAI,OAAQ,CAAsB,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBAC7D,CAAC;gBAAC,CAAsB,CAAC,KAAK,CAAC,GAAG,EAAE;oBAClC,wDAAwD;gBAC1D,CAAC,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;QAC3E,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/workflows/step.d.ts

@@ -0,0 +1,103 @@
+import type { StepContext } from './types.js';
+declare function stepCreate(entity: string, data: Record<string, unknown>, ctx: StepContext): Promise<Record<string, unknown>>;
+declare function stepUpdate(entity: string, id: string, data: Record<string, unknown>, ctx: StepContext): Promise<Record<string, unknown>>;
+/**
+ * Unified delete — resolves ALL links for this entity and does the right thing:
+ * - Links with cascadeLeft → soft-delete children + pivot entries
+ * - Links without cascade (many-to-many) → dismiss pivot entries only
+ * - Then soft-delete the entity itself
+ * One function. The framework knows the relationship types.
+ */
+interface DeleteResult {
+    id: string;
+    deletedLinks: Array<{
+        tableName: string;
+        linkId: string;
+    }>;
+    deletedChildren: Array<{
+        entity: string;
+        id: string;
+    }>;
+    dismissedLinks: Array<{
+        tableName: string;
+        linkId: string;
+    }>;
+}
+declare function stepDelete(entity: string, id: string, ctx: StepContext): Promise<DeleteResult>;
+/** Symbol used to tag objects with their entity name (set by create/update steps). */
+export declare const ENTITY_TAG: unique symbol;
+/** An entity ref for step.link() — either a tagged object or an explicit { entity, id }. */
+export interface EntityRef {
+    entity: string;
+    id: string;
+}
+/**
+ * Legacy: Create a link with explicit entity names and IDs.
+ * Used by the old bound proxy in defineCommand.
+ */
+declare function stepLinkExplicit(leftEntity: string, leftId: string, rightEntity: string, rightId: string, ctx: StepContext, extraColumns?: Record<string, unknown>): Promise<{
+    linkId: string;
+}>;
+declare function stepInvoke(moduleName: string, methodName: string, args: unknown[], ctx: StepContext): Promise<unknown>;
+declare function stepEmit(eventName: string, data: Record<string, unknown>, ctx: StepContext): Promise<void>;
+export interface CrudStepConfig {
+    entity: string;
+    serviceSuffix?: string;
+}
+export interface ActionStepConfig<TInput = unknown, TOutput = unknown> {
+    invoke: (input: TInput, ctx: StepContext) => Promise<TOutput>;
+    compensate: (output: TOutput, ctx: StepContext) => Promise<void>;
+}
+declare function stepDismissLink(leftEntity: string, leftId: string, rightEntity: string, rightId: string, ctx: StepContext): Promise<void>;
+declare function stepAction<TInput = unknown, TOutput = unknown>(name: string, config: ActionStepConfig<TInput, TOutput>): (input: TInput, ctx: StepContext) => Promise<TOutput>;
+/**
+ * step — Categorized workflow step API.
+ *
+ * Services (CRUD + compensable methods):
+ *   step.service.catalog.create({ title: 'Widget' }, ctx)
+ *   step.service.catalog.activate(id, ctx)
+ *   step.service.catalog.link.inventoryItem(ctx)
+ *   step.service.catalog.delete(id, ctx)
+ *
+ * Commands (sub-workflows):
+ *   step.command.createProduct({ title: 'Widget' }, ctx)
+ *
+ * Agents (AI calls — typed input/output, checkpointed):
+ *   step.agent.categorizeProduct({ title: 'Widget' }, ctx)
+ *
+ * Actions (external with required compensation):
+ *   step.action('charge-payment', { invoke, compensate })(input, ctx)
+ *
+ * Events (fire-and-forget, buffered):
+ *   step.emit('product.created', data, ctx)
+ */
+/**
+ * Per-link CRUD (pivot-backed). FK-backed intra-module links throw NOT_SUPPORTED at runtime.
+ */
+export interface LinkCrud {
+    list: (where: Record<string, unknown>, ctx: StepContext) => Promise<Record<string, unknown>[]>;
+    create: (data: Record<string, unknown>, ctx: StepContext) => Promise<Record<string, unknown>>;
+    update: (where: Record<string, unknown>, patch: Record<string, unknown>, ctx: StepContext) => Promise<{
+        ok: true;
+    }>;
+    delete: (where: Record<string, unknown>, ctx: StepContext) => Promise<{
+        ok: true;
+    }>;
+}
+export interface MantaStep {
+    emit: typeof stepEmit;
+    action: typeof stepAction;
+    service: MantaGeneratedAppModules;
+    command: Record<string, (input: unknown, ctx: StepContext) => Promise<unknown>>;
+    link: Record<string, LinkCrud>;
+    agent: Record<string, (input: unknown, ctx: StepContext) => Promise<unknown>>;
+    create: typeof stepCreate;
+    update: typeof stepUpdate;
+    delete: typeof stepDelete;
+    linkExplicit: typeof stepLinkExplicit;
+    dismissLink: typeof stepDismissLink;
+    invoke: typeof stepInvoke;
+}
+export declare const step: MantaStep;
+export {};
+//# sourceMappingURL=step.d.ts.map

package/dist/workflows/step.d.ts.map

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