@sayiir/flow-js 0.5.0-rc1

package/dist/task.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Task definition for workflow steps.
+ *
+ * The `task()` function wraps a function with metadata (id, timeout, retries)
+ * and optionally Zod schemas for input/output validation. The Flow builder
+ * reads these properties when constructing workflows.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.task = task;
+const duration_js_1 = require("./duration.js");
+/**
+ * Define a named task with optional configuration.
+ *
+ * ```ts
+ * const getUser = task("get-user", async (id: number) => {
+ *   return await db.getUser(id);
+ * }, { timeout: "30s", retries: 3 });
+ * ```
+ */
+function task(id, fn, opts) {
+    const metadata = buildMetadata(id, opts);
+    // Wrap the function with optional Zod validation
+    const wrapped = wrapWithValidation(fn, opts?.input, opts?.output);
+    // Brand the function as a TaskFn
+    const taskFn = wrapped;
+    Object.defineProperties(taskFn, {
+        _taskId: { value: id, enumerable: false },
+        _metadata: { value: metadata, enumerable: false },
+        _inputSchema: { value: opts?.input, enumerable: false },
+        _outputSchema: { value: opts?.output, enumerable: false },
+        _rawFn: { value: fn, enumerable: false },
+    });
+    return taskFn;
+}
+/** Build metadata from task options. */
+function buildMetadata(id, opts) {
+    const metadata = {
+        displayName: id,
+        description: opts?.description,
+        tags: opts?.tags,
+    };
+    if (opts?.timeout != null) {
+        metadata.timeoutSecs = (0, duration_js_1.parseDuration)(opts.timeout) / 1000;
+    }
+    if (opts?.retry) {
+        metadata.retries = buildRetryPolicy(opts.retry);
+    }
+    else if (opts?.retries != null) {
+        metadata.retries = {
+            maxRetries: opts.retries,
+            initialDelaySecs: 1.0,
+            backoffMultiplier: 2.0,
+        };
+    }
+    if (opts?.priority != null) {
+        if (opts.priority < 1 || opts.priority > 5) {
+            throw new RangeError(`priority must be between 1 and 5, got ${opts.priority}`);
+        }
+        metadata.priority = opts.priority;
+    }
+    if (opts?.tags != null) {
+        if (opts.tags.length > 20) {
+            throw new RangeError(`too many tags: ${opts.tags.length} (max 20)`);
+        }
+        for (const tag of opts.tags) {
+            if (!tag) {
+                throw new RangeError("tags must not contain empty strings");
+            }
+            if (tag.length > 64) {
+                throw new RangeError(`tag too long: '${tag}' (${tag.length} chars, max 64)`);
+            }
+        }
+    }
+    return metadata;
+}
+/** Convert a RetryPolicy to the config format. */
+function buildRetryPolicy(policy) {
+    return {
+        maxRetries: policy.maxAttempts,
+        initialDelaySecs: (0, duration_js_1.parseDuration)(policy.initialDelay) / 1000,
+        backoffMultiplier: policy.backoffMultiplier ?? 2.0,
+        maxDelaySecs: policy.maxDelay != null ? (0, duration_js_1.parseDuration)(policy.maxDelay) / 1000 : undefined,
+    };
+}
+/** Wrap a function with optional Zod validation. */
+function wrapWithValidation(fn, inputSchema, outputSchema) {
+    if (!inputSchema && !outputSchema) {
+        return fn;
+    }
+    return (input) => {
+        const validated = inputSchema ? inputSchema.parse(input) : input;
+        const result = fn(validated);
+        if (!outputSchema)
+            return result;
+        // Handle both sync and async results
+        if (result instanceof Promise) {
+            return result.then((v) => outputSchema.parse(v));
+        }
+        return outputSchema.parse(result);
+    };
+}
+//# sourceMappingURL=task.js.map

package/dist/task.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Core type definitions for the Sayiir workflow engine.
+ */
+/** Duration as milliseconds (number) or human-readable string parsed by `ms` (e.g. "30s", "5m", "1h"). */
+export type Duration = string | number;
+/** Retry policy for task execution. */
+export interface RetryPolicy {
+    maxAttempts: number;
+    initialDelay: Duration;
+    backoffMultiplier?: number;
+    maxDelay?: Duration;
+}
+/** Task options for configuring step behavior. */
+export interface TaskOptions<TIn = any, TOut = unknown> {
+    timeout?: Duration;
+    retries?: number;
+    retry?: RetryPolicy;
+    description?: string;
+    tags?: string[];
+    priority?: number;
+    input?: ZodLike<TIn>;
+    output?: ZodLike<TOut>;
+}
+/** Step options for inline `.then()` steps. */
+export interface StepOptions {
+    timeout?: Duration;
+    retries?: number;
+    retry?: RetryPolicy;
+}
+/**
+ * A task callback: receives input data and returns output (sync or async).
+ *
+ * Used internally in registries and native bindings wherever a
+ * task function reference is stored.
+ */
+export type TaskCallback = (input: any) => unknown | Promise<unknown>;
+/** Minimal Zod-like schema interface (avoids hard dependency). */
+export interface ZodLike<T = any> {
+    parse(data: unknown): T;
+    _output: T;
+}
+/**
+ * Discriminated union for workflow status.
+ * Enables TypeScript narrowing: `if (status.status === "completed") { status.output }`
+ */
+export type WorkflowStatus<TOut = unknown> = {
+    status: "completed";
+    output: TOut;
+} | {
+    status: "in_progress";
+} | {
+    status: "failed";
+    error: string;
+} | {
+    status: "cancelled";
+    reason?: string;
+    cancelledBy?: string;
+} | {
+    status: "paused";
+    reason?: string;
+    pausedBy?: string;
+} | {
+    status: "waiting";
+    wakeAt: string;
+    delayId: string;
+} | {
+    status: "awaiting_signal";
+    signalId: string;
+    signalName: string;
+    wakeAt?: string;
+};
+/** Error classes */
+export declare class WorkflowError extends Error {
+    constructor(message: string);
+}
+export declare class TaskError extends WorkflowError {
+    constructor(message: string);
+}
+export declare class BackendError extends WorkflowError {
+    constructor(message: string);
+}
+/**
+ * Result from a loop body task.
+ *
+ * Return `LoopResult.again(value)` to continue iterating,
+ * or `LoopResult.done(value)` to exit the loop.
+ *
+ * Serializes as `{ _loop: "again"|"done", value: ... }` matching the
+ * Rust `LoopResult<T>` serde format.
+ */
+export type LoopResult<T> = {
+    _loop: "again";
+    value: T;
+} | {
+    _loop: "done";
+    value: T;
+};
+/** Factory functions for creating `LoopResult` values. */
+export declare const LoopResult: {
+    /** Continue the loop with a new value. */
+    readonly again: <T>(value: T) => LoopResult<T>;
+    /** Exit the loop with a final value. */
+    readonly done: <T>(value: T) => LoopResult<T>;
+};
+/** Policy for when max iterations is reached. */
+export type MaxIterationsPolicy = "fail" | "exit_with_last";
+/** Options for a loop step. */
+export interface LoopOptions {
+    /** Maximum number of iterations (default: 10). */
+    maxIterations?: number;
+    /** What to do when max iterations is reached (default: "fail"). */
+    onMax?: MaxIterationsPolicy;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Core type definitions for the Sayiir workflow engine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopResult = exports.BackendError = exports.TaskError = exports.WorkflowError = void 0;
+/** Error classes */
+class WorkflowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkflowError";
+    }
+}
+exports.WorkflowError = WorkflowError;
+class TaskError extends WorkflowError {
+    constructor(message) {
+        super(message);
+        this.name = "TaskError";
+    }
+}
+exports.TaskError = TaskError;
+class BackendError extends WorkflowError {
+    constructor(message) {
+        super(message);
+        this.name = "BackendError";
+    }
+}
+exports.BackendError = BackendError;
+/** Factory functions for creating `LoopResult` values. */
+exports.LoopResult = {
+    /** Continue the loop with a new value. */
+    again(value) {
+        return { _loop: "again", value };
+    },
+    /** Exit the loop with a final value. */
+    done(value) {
+        return { _loop: "done", value };
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAgEH,oBAAoB;AACpB,MAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AALD,sCAKC;AAED,MAAa,SAAU,SAAQ,aAAa;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AALD,8BAKC;AAED,MAAa,YAAa,SAAQ,aAAa;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AALD,oCAKC;AAaD,0DAA0D;AAC7C,QAAA,UAAU,GAAG;IACxB,0CAA0C;IAC1C,KAAK,CAAI,KAAQ;QACf,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACnC,CAAC;IACD,wCAAwC;IACxC,IAAI,CAAI,KAAQ;QACd,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;CACO,CAAC"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@sayiir/flow-js",
+  "version": "0.5.0-rc1",
+  "description": "Pure TypeScript workflow builder DSL for Sayiir — no native dependencies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "ms": "^2.1.3"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/ms": "^2.1.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://docs.sayiir.dev",
+  "bugs": {
+    "url": "https://github.com/sayiir/sayiir/issues"
+  },
+  "author": "Sayiir",
+  "keywords": [
+    "workflow",
+    "durable",
+    "orchestration",
+    "task",
+    "typescript",
+    "builder",
+    "dsl"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sayiir/sayiir"
+  },
+  "scripts": {
+    "build:ts": "tsc",
+    "build": "pnpm run build:ts",
+    "typecheck": "tsc --noEmit"
+  }
+}