@lotiai/composer 0.2.0 → 0.2.1

package/dist/internal/dag-sync-fanout.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFanOutStep = isFanOutStep;
+exports.fanOut = fanOut;
+/**
+ * Runtime type guard for detecting FanOut nodes within a step array.
+ */
+function isFanOutStep(value) {
+    return "__fanOut" in value && value.__fanOut != null;
+}
+/**
+ * Factory function for creating type-safe FanOut nodes.
+ *
+ * Usage:
+ *   const fo = fanOut<ParentBag>()({
+ *     name: "startTldIngestions",
+ *     needs: ["tlds"] as const,
+ *     childWorkflow: ingestCzdsTld,
+ *     mapInput: (bag) => bag.tlds.map(tld => ({ tld })),
+ *     provides: ["tldResults"] as const,
+ *     aggregateResults: (results) => ({ tldResults: results }),
+ *     concurrency: 5,
+ *   });
+ *
+ * The double-call pattern (fanOut<ParentBag>()({...})) matches the step()
+ * factory -- ParentBag is explicit, all other generics are inferred from
+ * the definition object.
+ *
+ * Generic parameters:
+ * - ParentBag (explicit): The parent workflow's bag type
+ * - Name (inferred): Literal string name of this fanOut node
+ * - Needs (inferred): Bag keys this fanOut requires as input
+ * - Provides (inferred): Bag keys this fanOut produces as output
+ * - W (inferred): The child workflow type (carries Bag, RequiredInitial, etc.)
+ */
+function fanOut() {
+    return (definition) => {
+        if (definition.concurrency != null &&
+            (!Number.isFinite(definition.concurrency) || definition.concurrency < 1)) {
+            throw new Error(`FanOut "${definition.name}": concurrency must be a positive finite number, got ${definition.concurrency}`);
+        }
+        return {
+            name: definition.name,
+            needs: definition.needs,
+            provides: definition.provides,
+            run: async () => {
+                throw new Error(`FanOut "${definition.name}" cannot be executed directly. ` +
+                    `Use the workflow runtime (runSyncWorkflow or Temporal).`);
+            },
+            __fanOut: {
+                childWorkflow: definition.childWorkflow,
+                mapInput: definition.mapInput,
+                aggregateResults: definition.aggregateResults,
+                concurrency: definition.concurrency ?? Infinity,
+            },
+        };
+    };
+}
+//# sourceMappingURL=dag-sync-fanout.js.map

package/dist/internal/dag-sync-fanout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag-sync-fanout.js","sourceRoot":"","sources":["../../src/internal/dag-sync-fanout.ts"],"names":[],"mappings":";;AA6DA,oCAIC;AA2BD,wBA+CC;AAjFD;;GAEG;AACH,SAAgB,YAAY,CAC1B,KAAoC;IAEpC,OAAO,UAAU,IAAI,KAAK,IAAK,KAAoC,CAAC,QAAQ,IAAI,IAAI,CAAC;AACvF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,MAAM;IACpB,OAAO,CAKL,UAYD,EAA4C,EAAE;QAC7C,IACE,UAAU,CAAC,WAAW,IAAI,IAAI;YAC9B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,UAAU,CAAC,WAAW,GAAG,CAAC,CAAC,EACxE,CAAC;YACD,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,CAAC,IAAI,wDAAwD,UAAU,CAAC,WAAW,EAAE,CAC3G,CAAC;QACJ,CAAC;QAED,OAAO;YACL,IAAI,EAAE,UAAU,CAAC,IAAI;YACrB,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,QAAQ,EAAE,UAAU,CAAC,QAAQ;YAC7B,GAAG,EAAE,KAAK,IAAI,EAAE;gBACd,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,CAAC,IAAI,iCAAiC;oBACzD,yDAAyD,CAC5D,CAAC;YACJ,CAAC;YACD,QAAQ,EAAE;gBACR,aAAa,EAAE,UAAU,CAAC,aAAa;gBACvC,QAAQ,EAAE,UAAU,CAAC,QAAiD;gBACtE,gBAAgB,EACd,UAAU,CAAC,gBAAiE;gBAC9E,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,QAAQ;aAChD;SACF,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/internal/dag-sync-step.d.ts

@@ -0,0 +1,230 @@
+import type { WorkerProfile } from "./async/config/worker-profiles";
+type LongDurationUnit = "second" | "seconds" | "minute" | "minutes" | "hour" | "hours" | "day" | "days";
+type ShortDurationUnit = "ms" | "s" | "m" | "h" | "d";
+/**
+ * Compile-time validated Temporal duration string.
+ * Supports long form ("6 hours", "30 minutes") and short form ("6h", "30m").
+ */
+export type DurationString = `${number} ${LongDurationUnit}` | `${number}${ShortDurationUnit}`;
+/**
+ * Async (Temporal) runtime utilities injected into the step context.
+ * Available on `ctx` via intersection with the application context type.
+ *
+ * In async execution, these methods delegate to the Temporal activity context.
+ * In sync execution and tests, they are no-ops.
+ */
+export interface AsyncStepRuntime {
+    /**
+     * Report progress to Temporal. Call periodically in long-running activities to:
+     * 1. Prove liveness -- Temporal cancels the activity if no heartbeat arrives
+     *    within `asyncHeartbeatTimeout`.
+     * 2. Record progress -- on retry, the new attempt can read the last heartbeat's
+     *    details via `getHeartbeatDetails()` to resume work.
+     *
+     * `details` is any JSON-serializable value describing progress, e.g.
+     * `{ domainsIngested: 42000 }` or `{ phase: "uploading_to_s3" }`.
+     */
+    heartbeat(details?: unknown): void;
+    /**
+     * Retrieve the most recent heartbeat details from a previous attempt.
+     * Returns `undefined` on the first attempt or when no heartbeat was recorded.
+     * Use with `heartbeat()` to implement resumable long-running activities.
+     */
+    getHeartbeatDetails<T = unknown>(): T | undefined;
+}
+/**
+ * Per-step retry policy override. All fields are optional; unset fields
+ * fall back to the framework defaults (3 attempts, coefficient 2, 1s initial, 60s max).
+ */
+export interface StepRetryPolicy {
+    maximumAttempts?: number;
+    backoffCoefficient?: number;
+    initialInterval?: DurationString;
+    maximumInterval?: DurationString;
+}
+/**
+ * A Step represents a single unit of work in the workflow.
+ *
+ * Generic Parameters:
+ * - Bag: The complete data type that flows through the workflow
+ * - Needs: Array of field names this step requires as input
+ * - Provides: Array of field names this step will output
+ * - Context: The execution context available to this step (default: unknown)
+ * - Name: The literal string type of the step name (enables compile-time step identity)
+ *
+ * The type system ensures:
+ * - Steps can only access fields they declare in 'needs'
+ * - Steps must return exactly the fields they declare in 'provides'
+ * - Dependencies are validated at compile-time
+ * - Each step has a unique type based on its name (for checkpoint validation)
+ */
+export type Step<Bag extends Record<string, any>, Needs extends readonly (keyof Bag)[], Provides extends readonly (keyof Bag)[], Context = unknown, Name extends string = string> = {
+    name: Name;
+    needs: Needs;
+    provides: Provides;
+    run: (context: Context & AsyncStepRuntime, bag: Pick<Bag, Needs[number]>) => Promise<{
+        [K in Provides[number]]: Bag[K];
+    }> | {
+        [K in Provides[number]]: Bag[K];
+    };
+    /**
+     * Worker profile for Temporal execution - determines which worker pool this step runs on.
+     * If not specified, defaults to "standard".
+     * Only used for Temporal (async) execution. Sync execution ignores it.
+     */
+    workerProfile?: WorkerProfile;
+    /**
+     * Maximum time the activity may run from start to completion.
+     * If not specified, defaults to "5 minutes".
+     * Only used for Temporal (async) execution. Sync execution ignores it.
+     */
+    asyncStartToCloseTimeout?: DurationString;
+    /**
+     * Maximum time between heartbeats before Temporal considers the activity dead.
+     * When set, the step should call `ctx.heartbeat()` periodically.
+     * If not specified, no heartbeat timeout is enforced.
+     * Only used for Temporal (async) execution. Sync execution ignores it.
+     */
+    asyncHeartbeatTimeout?: DurationString;
+    /**
+     * Per-step retry policy override. Unset fields fall back to framework defaults.
+     * Only used for Temporal (async) execution. Sync execution ignores it.
+     */
+    asyncRetry?: StepRetryPolicy;
+    /**
+     * Workflow path tracks the logical ancestry of this step for observability.
+     * Used to create proper span hierarchy even when steps are flattened.
+     * Example: ["parentWorkflow", "childWorkflow"] for a step in a composed child workflow
+     */
+    workflowPath?: string[];
+    /**
+     * Original run function before validation wrapper was applied.
+     * Used for versioning/hashing to detect actual implementation changes.
+     * This is an internal field and should not be called directly - use `run` instead.
+     * @internal
+     */
+    _originalRun?: (context: Context & AsyncStepRuntime, bag: Pick<Bag, Needs[number]>) => Promise<{
+        [K in Provides[number]]: Bag[K];
+    }> | {
+        [K in Provides[number]]: Bag[K];
+    };
+};
+/**
+ * Type that represents valid JSON primitive values
+ */
+type JSONPrimitive = string | number | boolean | null;
+/**
+ * Type representing non-serializable types that should be caught at compile time.
+ * Must stay in sync with the runtime check in validateSerializable() above.
+ */
+type NonSerializableType = Date | Map<any, any> | Set<any> | ((...args: any[]) => any) | symbol | bigint;
+/**
+ * Depth-limited serializability checking using tuple-based recursion.
+ *
+ * Uses a depth counter pattern to avoid TypeScript's "excessive stack depth" error
+ * while still catching nested non-serializable types up to 4 levels deep.
+ *
+ * This catches patterns like:
+ * - { foo: Date }                    (Level 1)
+ * - { foo: { bar: Date } }           (Level 2)
+ * - { foo: { bar: { baz: Date } } }  (Level 3)
+ * - Arrays at any level: [{ nested: { date: Date } }]
+ *
+ * Runtime validateSerializable() provides comprehensive checking for deeper nesting.
+ */
+/** Depth decrement: Decr[D] = D-1, with Decr[0] = never as stop signal. */
+type Decr = [never, 0, 1, 2];
+/** Depth increment for NonSerializableProp search. */
+type Incr = [1, 2, 3, 4];
+/**
+ * Checks if a type is JSON-serializable up to D levels deep.
+ *
+ * Depth behavior:
+ * - D=0: Only checks if T itself is a primitive or NonSerializableType
+ * - D=1: Checks T and its direct children
+ * - D=2: Checks T, children, and grandchildren
+ * - D=3: Checks 4 levels deep (default)
+ */
+type IsSerializable<T, D extends number = 3> = T extends JSONPrimitive | undefined ? true : T extends NonSerializableType ? false : D extends 0 ? true : T extends Array<infer U> ? IsSerializable<U, Decr[D]> : T extends object ? false extends IsSerializable<T[keyof T], Decr[D]> ? false : true : true;
+/**
+ * Find a top-level property that fails serialization at depth D.
+ * D=0 checks for directly non-serializable types; D>0 uses IsSerializable.
+ */
+type FindPropFailingAt<T, D extends number> = T extends object ? D extends 0 ? {
+    [K in keyof T]: T[K] extends NonSerializableType ? K : never;
+}[keyof T] : {
+    [K in keyof T]: IsSerializable<T[K], Decr[D]> extends false ? K : never;
+}[keyof T] : never;
+/**
+ * Find a top-level property containing non-serializable data.
+ * Searches from shallowest (D=0) to deepest (D=3) to find the most relevant property.
+ */
+type NonSerializableProp<T, D extends number = 0> = T extends object ? D extends 4 ? never : FindPropFailingAt<T, D> extends never ? NonSerializableProp<T, Incr[D]> : FindPropFailingAt<T, D> : never;
+/**
+ * Error type that includes the offending property name in the error message.
+ */
+type SerializationErrorWithProp<PropName> = PropName extends string ? {
+    [K in `SERIALIZATION_ERROR: Property '${PropName}' contains non-serializable type (Date/Map/Set/Function/Symbol/BigInt). Use toSerializable()`]: never;
+} : {
+    "SERIALIZATION_ERROR: Contains non-serializable type. Use toSerializable()": never;
+};
+/**
+ * Type assertion that produces a compile error if T contains non-serializable types.
+ * Returns T unchanged if serializable, otherwise returns an error type with the property name.
+ *
+ * This provides compile-time feedback with a clear, actionable error message.
+ */
+export type AssertSerializable<T> = IsSerializable<T> extends true ? T : SerializationErrorWithProp<NonSerializableProp<T>>;
+/**
+ * COMPILE-TIME vs RUNTIME VALIDATION:
+ *
+ * What we CAN catch at compile-time:
+ * ✅ Properties that exist in the Bag type but are not in the 'provides' array
+ *    Example: If Bag has 'foo' but provides is ['rules'], returning { rules, foo } will error
+ *
+ * What we CANNOT catch at compile-time (TypeScript limitation):
+ * ❌ Properties that don't exist in the Bag type at all
+ *    Example: If 'baz' is not in Bag, returning { priceCents, baz } will NOT error at compile time
+ *    This is due to TypeScript's structural typing allowing extra properties in object literals
+ *
+ * Solution: We use a hybrid approach:
+ * 1. Compile-time checking for properties in Bag (StrictStepReturn type)
+ * 2. Runtime validation for ALL excess properties (validateStepReturn function)
+ */
+type PropertyNotInProvidesError<K extends PropertyKey> = `❌ ERROR: Property '${K extends string ? K : string}' is not in the 'provides' array. Either remove it from the return value or add it to 'provides'.`;
+export type StrictStepReturn<Bag, Keys extends keyof Bag> = {
+    [K in Keys]: Bag[K];
+} & {
+    [K in keyof Bag as K extends Keys ? never : K]?: PropertyNotInProvidesError<K>;
+};
+/**
+ * Factory function for creating type-safe steps with validation.
+ *
+ * This function provides:
+ * 1. Clean generic inference - you don't need to specify types manually
+ * 2. Compile-time validation via StrictStepReturn type
+ * 3. Runtime validation wrapper for additional safety
+ *
+ * Usage:
+ *   const myStep = step<Bag, MyContext>()({
+ *     name: "processData",
+ *     needs: ["input"],
+ *     provides: ["output"],
+ *     run: async (context, bag) => ({ output: processInput(bag.input) })
+ *   });
+ *
+ * The double function call pattern allows TypeScript to infer the Bag type
+ * from the first call, then infer Needs/Provides from the step definition.
+ */
+export declare function step<Bag extends Record<string, any>, Context = unknown>(): <const Name extends string, const Needs extends readonly (keyof Bag)[], const Provides extends readonly (keyof Bag)[]>(stepDefinition: {
+    name: Name;
+    needs: Needs;
+    provides: Provides;
+    workerProfile?: WorkerProfile;
+    asyncStartToCloseTimeout?: DurationString;
+    asyncHeartbeatTimeout?: DurationString;
+    asyncRetry?: StepRetryPolicy;
+    run: (context: Context & AsyncStepRuntime, bag: Pick<Bag, Needs[number]>) => Promise<AssertSerializable<StrictStepReturn<Bag, Provides[number]>>> | AssertSerializable<StrictStepReturn<Bag, Provides[number]>>;
+}) => Step<Bag, Needs, Provides, Context, Name>;
+export {};
+//# sourceMappingURL=dag-sync-step.d.ts.map

package/dist/internal/dag-sync-step.d.ts.map

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

package/dist/internal/dag-sync-step.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.step = step;
+/**
+ * Validates that a value is JSON-serializable for Temporal activity boundaries.
+ * Returns detailed error information about non-serializable values.
+ */
+function validateSerializable(value, path = "root") {
+    // Handle primitives and special cases using a switch statement
+    if (value === null || value === undefined) {
+        return { valid: true };
+    }
+    const valueType = typeof value;
+    switch (valueType) {
+        case "string":
+        case "number":
+        case "boolean":
+            return { valid: true };
+        case "object":
+            // Check for Date
+            if (value instanceof Date) {
+                return {
+                    valid: false,
+                    path,
+                    type: "Date",
+                    value,
+                };
+            }
+            // Check for Map/Set - these serialize to {} and lose all data
+            if (value instanceof Map) {
+                return {
+                    valid: false,
+                    path,
+                    type: "Map",
+                    value: `Map with ${value.size} entries`,
+                };
+            }
+            if (value instanceof Set) {
+                return {
+                    valid: false,
+                    path,
+                    type: "Set",
+                    value: `Set with ${value.size} entries`,
+                };
+            }
+            // Handle arrays
+            if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    const result = validateSerializable(value[i], `${path}[${i}]`);
+                    if (!result.valid) {
+                        return result;
+                    }
+                }
+                return { valid: true };
+            }
+            // Handle plain objects
+            for (const [key, val] of Object.entries(value)) {
+                const result = validateSerializable(val, `${path}.${key}`);
+                if (!result.valid) {
+                    return result;
+                }
+            }
+            return { valid: true };
+        default:
+            // Unknown type
+            return {
+                valid: false,
+                path,
+                type: valueType,
+                value: String(value).slice(0, 100),
+            };
+    }
+}
+/**
+ * Runtime validation function that ensures step return objects contain exactly
+ * the properties declared in the 'provides' array - no more, no less.
+ *
+ * This provides a safety net to catch:
+ * 1. Excess properties that TypeScript's structural typing might allow through
+ * 2. Missing properties when TypeScript is bypassed with 'as any'
+ * 3. Non-serializable values that would fail when crossing Temporal boundaries
+ *
+ * The return type strips compile-time assertion wrappers (AssertSerializable, StrictStepReturn)
+ * and returns the clean mapped type. This is safe because:
+ * - If the input had non-serializable types, we'd have a compile error at the call site
+ * - The runtime validation throws if the actual value doesn't match provides
+ */
+function validateStepReturn(result, provides) {
+    const expected = result;
+    const returnKeys = Object.keys(expected);
+    const providesKeys = provides.map(String);
+    // Check for unexpected extra properties
+    for (const key of returnKeys) {
+        if (!providesKeys.includes(key)) {
+            throw new Error(`Step returned unexpected property "${key}". Only properties declared in "provides" are allowed: [${providesKeys.join(", ")}]\n\n` +
+                `💡 Fix: Either remove "${key}" from the return object, or add "${key}" to the "provides" array.`);
+        }
+    }
+    // Check for missing required properties
+    for (const key of providesKeys) {
+        if (!(key in expected)) {
+            throw new Error(`Step failed to return required property "${key}". All properties declared in "provides" must be returned: [${providesKeys.join(", ")}]\n\n` +
+                `💡 Fix: Make sure your step returns an object containing "${key}".`);
+        }
+    }
+    // Validate serializability (critical for async Temporal workflows)
+    const serializationResult = validateSerializable(expected);
+    if (!serializationResult.valid) {
+        throw new Error(`Step returned non-serializable value at path "${serializationResult.path}".\n` +
+            `Type: ${serializationResult.type}\n` +
+            `Value: ${JSON.stringify(serializationResult.value, null, 2)}\n\n` +
+            `💡 Fix: Use toSerializable() to convert values before returning from steps.\n` +
+            `   All values must be JSON-serializable because they cross Temporal activity boundaries.\n\n` +
+            `   - Date objects: toSerializable() converts these to ISO strings automatically\n` +
+            `   - MikroORM entities: toSerializable() handles Refs, Collections, and getters\n` +
+            `   - Map/Set: Convert to objects or arrays first (Object.fromEntries() / Array.from())\n` +
+            `   - Functions: Return their results, not the functions themselves\n` +
+            `   - BigInt: Convert to number or string first`);
+    }
+    // Cast is safe: we've validated the object matches the provides array exactly
+    return expected;
+}
+/**
+ * Factory function for creating type-safe steps with validation.
+ *
+ * This function provides:
+ * 1. Clean generic inference - you don't need to specify types manually
+ * 2. Compile-time validation via StrictStepReturn type
+ * 3. Runtime validation wrapper for additional safety
+ *
+ * Usage:
+ *   const myStep = step<Bag, MyContext>()({
+ *     name: "processData",
+ *     needs: ["input"],
+ *     provides: ["output"],
+ *     run: async (context, bag) => ({ output: processInput(bag.input) })
+ *   });
+ *
+ * The double function call pattern allows TypeScript to infer the Bag type
+ * from the first call, then infer Needs/Provides from the step definition.
+ */
+function step() {
+    return (stepDefinition) => {
+        const originalRun = stepDefinition.run;
+        const wrappedRun = async (context, bag) => {
+            const result = await originalRun(context, bag);
+            return validateStepReturn(result, stepDefinition.provides);
+        };
+        return {
+            ...stepDefinition,
+            run: wrappedRun,
+            // Cast needed: originalRun's return type includes compile-time assertion wrappers
+            // (AssertSerializable, StrictStepReturn) but _originalRun expects the clean type.
+            // The wrappers only produce errors at compile-time; at runtime it's always the valid type.
+            _originalRun: originalRun,
+        };
+    };
+}
+//# sourceMappingURL=dag-sync-step.js.map

package/dist/internal/dag-sync-step.js.map

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