@blokjs/helper 0.2.0 → 0.4.0

package/dist/types/WorkflowOpts.d.ts

@@ -1,4 +1,15 @@
 import { z } from "zod";
+/**
+ * Validation schema for the workflow envelope (v1 — legacy).
+ *
+ * Note: `trigger` is intentionally permissive (`unknown` value) at this layer
+ * because per-kind validation lives in {@link Trigger.addTrigger} via
+ * `validateTriggerConfig`. Tightening it here would force the legacy HTTP
+ * shape onto every trigger kind.
+ *
+ * @deprecated Prefer {@link WorkflowV2Schema}. v1 shapes are still accepted
+ * and normalized at workflow load time.
+ */
 export declare const WorkflowOptsSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
@@ -9,36 +20,33 @@ export declare const WorkflowOptsSchema: z.ZodObject<{
         type: z.ZodEnum<["local", "module", "runtime.python3", "runtime.nodejs", "runtime.bun", "runtime.go", "runtime.java", "runtime.rust", "runtime.php", "runtime.csharp", "runtime.ruby", "runtime.docker", "runtime.wasm"]>;
         inputs: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         runtime: z.ZodOptional<z.ZodEnum<["nodejs", "bun", "python3", "go", "java", "rust", "php", "csharp", "ruby", "docker", "wasm"]>>;
+        set_var: z.ZodOptional<z.ZodBoolean>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        stop: z.ZodOptional<z.ZodBoolean>;
+        stream_logs: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         node: string;
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }, {
         name: string;
         node: string;
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }>, "many">>;
     nodes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>>;
-    trigger: z.ZodOptional<z.ZodRecord<z.ZodEnum<["http", "grpc", "manual", "cron", "queue", "pubsub", "worker", "webhook", "sse", "websocket"]>, z.ZodObject<{
-        method: z.ZodEnum<["GET", "POST", "PUT", "DELETE", "PATCH", "ANY"]>;
-        path: z.ZodOptional<z.ZodString>;
-        accept: z.ZodDefault<z.ZodString>;
-        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
-    }, "strip", z.ZodTypeAny, {
-        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
-        accept: string;
-        path?: string | undefined;
-        headers?: Record<string, any> | undefined;
-    }, {
-        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
-        path?: string | undefined;
-        accept?: string | undefined;
-        headers?: Record<string, any> | undefined;
-    }>>>;
+    trigger: z.ZodOptional<z.ZodRecord<z.ZodEnum<["http", "grpc", "manual", "cron", "queue", "pubsub", "worker", "webhook", "sse", "websocket"]>, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     version: string;
@@ -48,15 +56,14 @@ export declare const WorkflowOptsSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
     description?: string | undefined;
     nodes?: Record<string, {}> | undefined;
-    trigger?: Partial<Record<"queue" | "http" | "grpc" | "manual" | "cron" | "pubsub" | "worker" | "webhook" | "sse" | "websocket", {
-        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
-        accept: string;
-        path?: string | undefined;
-        headers?: Record<string, any> | undefined;
-    }>> | undefined;
+    trigger?: Partial<Record<"queue" | "http" | "worker" | "grpc" | "manual" | "cron" | "pubsub" | "webhook" | "sse" | "websocket", unknown>> | undefined;
 }, {
     name: string;
     version: string;
@@ -66,14 +73,291 @@ export declare const WorkflowOptsSchema: z.ZodObject<{
         type: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm";
         inputs?: {} | undefined;
         runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
     }[] | undefined;
     description?: string | undefined;
     nodes?: Record<string, {}> | undefined;
-    trigger?: Partial<Record<"queue" | "http" | "grpc" | "manual" | "cron" | "pubsub" | "worker" | "webhook" | "sse" | "websocket", {
-        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
-        path?: string | undefined;
-        accept?: string | undefined;
-        headers?: Record<string, any> | undefined;
-    }>> | undefined;
+    trigger?: Partial<Record<"queue" | "http" | "worker" | "grpc" | "manual" | "cron" | "pubsub" | "webhook" | "sse" | "websocket", unknown>> | undefined;
 }>;
 export type WorkflowOpts = z.infer<typeof WorkflowOptsSchema>;
+/**
+ * Validation schema for the v2 workflow envelope.
+ *
+ * Differences from v1:
+ * - No top-level `nodes{}` map — `inputs` lives directly on each step.
+ * - `steps[]` is required and contains v2 step shapes (id + use + inputs)
+ *   OR branch shapes ({ id, branch: { when, then, else } }).
+ * - `trigger` is required (workflows must have at least one trigger).
+ *
+ * Backward compatibility: v1 workflows are converted to v2 at workflow load
+ * time by the runner's WorkflowNormalizer.
+ *
+ * @example
+ *   {
+ *     name: "World Countries",
+ *     version: "1.0.0",
+ *     trigger: { http: { method: "GET" } },
+ *     steps: [
+ *       { id: "fetch", use: "@blokjs/api-call", inputs: { url: "..." } }
+ *     ]
+ *   }
+ */
+export declare const WorkflowV2Schema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    trigger: z.ZodRecord<z.ZodEnum<["http", "grpc", "manual", "cron", "queue", "pubsub", "worker", "webhook", "sse", "websocket"]>, z.ZodUnknown>;
+    steps: z.ZodArray<z.ZodType<{
+        id: string;
+        use: string;
+        type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+        inputs?: Record<string, unknown> | undefined;
+        runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
+        as?: string | undefined;
+        spread?: boolean | undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: string | undefined;
+        idempotencyKeyTTL?: number | undefined;
+        retry?: {
+            maxAttempts: number;
+            factor?: number | undefined;
+            minTimeoutInMs?: number | undefined;
+            maxTimeoutInMs?: number | undefined;
+        } | undefined;
+        maxDuration?: string | number | undefined;
+    } | {
+        id: string;
+        branch: {
+            when: string;
+            then: unknown[];
+            else?: unknown[];
+        };
+        active?: boolean;
+        stop?: boolean;
+    } | {
+        id: string;
+        subworkflow: string;
+        inputs?: Record<string, unknown>;
+        wait?: boolean;
+        as?: string;
+        spread?: boolean;
+        ephemeral?: boolean;
+        active?: boolean;
+        stop?: boolean;
+        idempotencyKey?: string;
+        idempotencyKeyTTL?: number;
+        retry?: import("./StepOpts").RetryConfig;
+    } | {
+        id: string;
+        wait: {
+            for?: string | number | undefined;
+            until?: string | number | undefined;
+        };
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        concurrencyKey?: undefined;
+        as?: string | undefined;
+        spread?: undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: undefined;
+        retry?: undefined;
+        maxDuration?: undefined;
+    }, z.ZodTypeDef, {
+        id: string;
+        use: string;
+        type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+        inputs?: Record<string, unknown> | undefined;
+        runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
+        as?: string | undefined;
+        spread?: boolean | undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: string | undefined;
+        idempotencyKeyTTL?: number | undefined;
+        retry?: {
+            maxAttempts: number;
+            factor?: number | undefined;
+            minTimeoutInMs?: number | undefined;
+            maxTimeoutInMs?: number | undefined;
+        } | undefined;
+        maxDuration?: string | number | undefined;
+    } | {
+        id: string;
+        branch: {
+            when: string;
+            then: unknown[];
+            else?: unknown[];
+        };
+        active?: boolean;
+        stop?: boolean;
+    } | {
+        id: string;
+        subworkflow: string;
+        inputs?: Record<string, unknown>;
+        wait?: boolean;
+        as?: string;
+        spread?: boolean;
+        ephemeral?: boolean;
+        active?: boolean;
+        stop?: boolean;
+        idempotencyKey?: string;
+        idempotencyKeyTTL?: number;
+        retry?: import("./StepOpts").RetryConfig;
+    } | {
+        id: string;
+        wait: {
+            for?: string | number | undefined;
+            until?: string | number | undefined;
+        };
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        concurrencyKey?: undefined;
+        as?: string | undefined;
+        spread?: undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: undefined;
+        retry?: undefined;
+        maxDuration?: undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    steps: ({
+        id: string;
+        use: string;
+        type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+        inputs?: Record<string, unknown> | undefined;
+        runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
+        as?: string | undefined;
+        spread?: boolean | undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: string | undefined;
+        idempotencyKeyTTL?: number | undefined;
+        retry?: {
+            maxAttempts: number;
+            factor?: number | undefined;
+            minTimeoutInMs?: number | undefined;
+            maxTimeoutInMs?: number | undefined;
+        } | undefined;
+        maxDuration?: string | number | undefined;
+    } | {
+        id: string;
+        branch: {
+            when: string;
+            then: unknown[];
+            else?: unknown[];
+        };
+        active?: boolean;
+        stop?: boolean;
+    } | {
+        id: string;
+        subworkflow: string;
+        inputs?: Record<string, unknown>;
+        wait?: boolean;
+        as?: string;
+        spread?: boolean;
+        ephemeral?: boolean;
+        active?: boolean;
+        stop?: boolean;
+        idempotencyKey?: string;
+        idempotencyKeyTTL?: number;
+        retry?: import("./StepOpts").RetryConfig;
+    } | {
+        id: string;
+        wait: {
+            for?: string | number | undefined;
+            until?: string | number | undefined;
+        };
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        concurrencyKey?: undefined;
+        as?: string | undefined;
+        spread?: undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: undefined;
+        retry?: undefined;
+        maxDuration?: undefined;
+    })[];
+    version: string;
+    trigger: Partial<Record<"queue" | "http" | "worker" | "grpc" | "manual" | "cron" | "pubsub" | "webhook" | "sse" | "websocket", unknown>>;
+    description?: string | undefined;
+}, {
+    name: string;
+    steps: ({
+        id: string;
+        use: string;
+        type?: "local" | "module" | "runtime.python3" | "runtime.nodejs" | "runtime.bun" | "runtime.go" | "runtime.java" | "runtime.rust" | "runtime.php" | "runtime.csharp" | "runtime.ruby" | "runtime.docker" | "runtime.wasm" | undefined;
+        inputs?: Record<string, unknown> | undefined;
+        runtime?: "nodejs" | "bun" | "python3" | "go" | "java" | "rust" | "php" | "csharp" | "ruby" | "docker" | "wasm" | undefined;
+        set_var?: boolean | undefined;
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        stream_logs?: boolean | undefined;
+        as?: string | undefined;
+        spread?: boolean | undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: string | undefined;
+        idempotencyKeyTTL?: number | undefined;
+        retry?: {
+            maxAttempts: number;
+            factor?: number | undefined;
+            minTimeoutInMs?: number | undefined;
+            maxTimeoutInMs?: number | undefined;
+        } | undefined;
+        maxDuration?: string | number | undefined;
+    } | {
+        id: string;
+        branch: {
+            when: string;
+            then: unknown[];
+            else?: unknown[];
+        };
+        active?: boolean;
+        stop?: boolean;
+    } | {
+        id: string;
+        subworkflow: string;
+        inputs?: Record<string, unknown>;
+        wait?: boolean;
+        as?: string;
+        spread?: boolean;
+        ephemeral?: boolean;
+        active?: boolean;
+        stop?: boolean;
+        idempotencyKey?: string;
+        idempotencyKeyTTL?: number;
+        retry?: import("./StepOpts").RetryConfig;
+    } | {
+        id: string;
+        wait: {
+            for?: string | number | undefined;
+            until?: string | number | undefined;
+        };
+        active?: boolean | undefined;
+        stop?: boolean | undefined;
+        concurrencyKey?: undefined;
+        as?: string | undefined;
+        spread?: undefined;
+        ephemeral?: boolean | undefined;
+        idempotencyKey?: undefined;
+        retry?: undefined;
+        maxDuration?: undefined;
+    })[];
+    version: string;
+    trigger: Partial<Record<"queue" | "http" | "worker" | "grpc" | "manual" | "cron" | "pubsub" | "webhook" | "sse" | "websocket", unknown>>;
+    description?: string | undefined;
+}>;
+export type WorkflowV2 = z.infer<typeof WorkflowV2Schema>;

package/dist/types/WorkflowOpts.js

@@ -1,6 +1,17 @@
 import { z } from "zod";
-import { StepInputsSchema, StepOptsSchema } from "./StepOpts";
-import { TriggerOptsSchema, TriggersSchema } from "./TriggerOpts";
+import { StepInputsSchema, StepOptsSchema, V2StepSchema } from "./StepOpts";
+import { TriggersSchema } from "./TriggerOpts";
+/**
+ * Validation schema for the workflow envelope (v1 — legacy).
+ *
+ * Note: `trigger` is intentionally permissive (`unknown` value) at this layer
+ * because per-kind validation lives in {@link Trigger.addTrigger} via
+ * `validateTriggerConfig`. Tightening it here would force the legacy HTTP
+ * shape onto every trigger kind.
+ *
+ * @deprecated Prefer {@link WorkflowV2Schema}. v1 shapes are still accepted
+ * and normalized at workflow load time.
+ */
 export const WorkflowOptsSchema = z.object({
     name: z
         .string({
@@ -17,6 +28,47 @@ export const WorkflowOptsSchema = z.object({
     description: z.string().optional(),
     steps: z.array(StepOptsSchema).optional(),
     nodes: z.record(z.string(), StepInputsSchema).optional(),
-    trigger: z.record(TriggersSchema, TriggerOptsSchema).optional(),
+    trigger: z.record(TriggersSchema, z.unknown()).optional(),
+});
+// =============================================================================
+// V2 — Canonical workflow shape.
+// =============================================================================
+/**
+ * Validation schema for the v2 workflow envelope.
+ *
+ * Differences from v1:
+ * - No top-level `nodes{}` map — `inputs` lives directly on each step.
+ * - `steps[]` is required and contains v2 step shapes (id + use + inputs)
+ *   OR branch shapes ({ id, branch: { when, then, else } }).
+ * - `trigger` is required (workflows must have at least one trigger).
+ *
+ * Backward compatibility: v1 workflows are converted to v2 at workflow load
+ * time by the runner's WorkflowNormalizer.
+ *
+ * @example
+ *   {
+ *     name: "World Countries",
+ *     version: "1.0.0",
+ *     trigger: { http: { method: "GET" } },
+ *     steps: [
+ *       { id: "fetch", use: "@blokjs/api-call", inputs: { url: "..." } }
+ *     ]
+ *   }
+ */
+export const WorkflowV2Schema = z.object({
+    name: z.string().min(3).describe("Workflow display name. Min 3 characters. Shown in Studio."),
+    version: z
+        .string()
+        .min(5, { message: "Format required x.x.x" })
+        .describe("Semantic version (x.x.x). Used for trace recording and audit."),
+    description: z
+        .string()
+        .optional()
+        .describe("What this workflow does. Optional but recommended — surfaces in Studio and CLI."),
+    trigger: z
+        .record(TriggersSchema, z.unknown())
+        .describe("Trigger configuration. Most workflows use { http: { method: 'GET' } }. " +
+        "See TRIGGER_SCHEMAS for per-kind shapes."),
+    steps: z.array(V2StepSchema).min(1).describe("Pipeline of steps to execute in order. At least one step required."),
 });
 //# sourceMappingURL=WorkflowOpts.js.map

package/dist/types/WorkflowOpts.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkflowOpts.js","sourceRoot":"","sources":["../../src/types/WorkflowOpts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC;SACL,MAAM,CAAC;QACP,cAAc,EAAE,kBAAkB;QAClC,kBAAkB,EAAE,uBAAuB;KAC3C,CAAC;SACD,GAAG,CAAC,CAAC,CAAC;IACR,OAAO,EAAE,CAAC;SACR,MAAM,CAAC;QACP,cAAc,EAAE,qBAAqB;QACrC,kBAAkB,EAAE,0BAA0B;KAC9C,CAAC;SACD,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;IAC9C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IACzC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IACxD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,QAAQ,EAAE;CAC/D,CAAC,CAAC"}
+{"version":3,"file":"WorkflowOpts.js","sourceRoot":"","sources":["../../src/types/WorkflowOpts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC;SACL,MAAM,CAAC;QACP,cAAc,EAAE,kBAAkB;QAClC,kBAAkB,EAAE,uBAAuB;KAC3C,CAAC;SACD,GAAG,CAAC,CAAC,CAAC;IACR,OAAO,EAAE,CAAC;SACR,MAAM,CAAC;QACP,cAAc,EAAE,qBAAqB;QACrC,kBAAkB,EAAE,0BAA0B;KAC9C,CAAC;SACD,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;IAC9C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IACzC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IACxD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC;AAIH,gFAAgF;AAChF,iCAAiC;AACjC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,2DAA2D,CAAC;IAC7F,OAAO,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;SAC5C,QAAQ,CAAC,+DAA+D,CAAC;IAC3E,WAAW,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,iFAAiF,CAAC;IAC7F,OAAO,EAAE,CAAC;SACR,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SACnC,QAAQ,CACR,yEAAyE;QACxE,0CAA0C,CAC3C;IACF,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,oEAAoE,CAAC;CAClH,CAAC,CAAC"}

package/dist/utils/parseDuration.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Parse a duration value to milliseconds.
+ *
+ * Accepts:
+ *   - A non-negative finite number (interpreted as milliseconds)
+ *   - A single-unit string: `"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"1d"`
+ *
+ * Rejects:
+ *   - Negative numbers, NaN, Infinity
+ *   - Empty strings, whitespace-only strings
+ *   - Multi-unit strings (`"1h30m"`) — split into separate fields if needed
+ *   - Fractional values (`"1.5h"`) — express as a smaller unit (`"90m"`)
+ *   - Unknown units (`"5y"`)
+ *
+ * The narrow grammar is deliberate: it makes parsing predictable and
+ * round-trippable. For arbitrarily complex schedules, use the cron trigger.
+ *
+ * @example
+ *   parseDuration(5000)      // → 5000
+ *   parseDuration("500ms")   // → 500
+ *   parseDuration("30s")     // → 30000
+ *   parseDuration("5m")      // → 300000
+ *   parseDuration("2h")      // → 7200000
+ *   parseDuration("1d")      // → 86400000
+ *
+ * @throws Error with a helpful message identifying the offending input.
+ */
+export declare function parseDuration(input: number | string): number;
+/**
+ * Same as {@link parseDuration} but returns null instead of throwing on
+ * invalid input. Useful when validating user-supplied config defensively.
+ */
+export declare function tryParseDuration(input: unknown): number | null;

package/dist/utils/parseDuration.js

@@ -0,0 +1,78 @@
+/**
+ * Parse a duration value to milliseconds.
+ *
+ * Accepts:
+ *   - A non-negative finite number (interpreted as milliseconds)
+ *   - A single-unit string: `"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"1d"`
+ *
+ * Rejects:
+ *   - Negative numbers, NaN, Infinity
+ *   - Empty strings, whitespace-only strings
+ *   - Multi-unit strings (`"1h30m"`) — split into separate fields if needed
+ *   - Fractional values (`"1.5h"`) — express as a smaller unit (`"90m"`)
+ *   - Unknown units (`"5y"`)
+ *
+ * The narrow grammar is deliberate: it makes parsing predictable and
+ * round-trippable. For arbitrarily complex schedules, use the cron trigger.
+ *
+ * @example
+ *   parseDuration(5000)      // → 5000
+ *   parseDuration("500ms")   // → 500
+ *   parseDuration("30s")     // → 30000
+ *   parseDuration("5m")      // → 300000
+ *   parseDuration("2h")      // → 7200000
+ *   parseDuration("1d")      // → 86400000
+ *
+ * @throws Error with a helpful message identifying the offending input.
+ */
+export function parseDuration(input) {
+    if (typeof input === "number") {
+        if (!Number.isFinite(input)) {
+            throw new Error(`Invalid duration: ${input} (must be a finite number).`);
+        }
+        if (input < 0) {
+            throw new Error(`Invalid duration: ${input} (must be >= 0).`);
+        }
+        // Allow fractional ms for raw numbers (e.g. precise jitter math).
+        // Floor to integer ms — sub-ms scheduling is meaningless for setTimeout.
+        return Math.floor(input);
+    }
+    if (typeof input !== "string") {
+        throw new Error(`Invalid duration: ${typeof input} (must be a number or string).`);
+    }
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new Error("Invalid duration: empty string.");
+    }
+    // Single-unit grammar: <integer><unit>
+    // Units: ms (milliseconds), s (seconds), m (minutes), h (hours), d (days)
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(trimmed);
+    if (!match) {
+        throw new Error(`Invalid duration: ${JSON.stringify(input)}. Expected a non-negative integer followed by a unit (ms, s, m, h, d), e.g. "500ms", "30s", "5m", "2h", "1d". Multi-unit strings ("1h30m") and fractional values ("1.5h") are not supported.`);
+    }
+    const value = Number.parseInt(match[1], 10);
+    const unit = match[2];
+    const multipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return value * multipliers[unit];
+}
+/**
+ * Same as {@link parseDuration} but returns null instead of throwing on
+ * invalid input. Useful when validating user-supplied config defensively.
+ */
+export function tryParseDuration(input) {
+    if (typeof input !== "number" && typeof input !== "string")
+        return null;
+    try {
+        return parseDuration(input);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=parseDuration.js.map

package/dist/utils/parseDuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseDuration.js","sourceRoot":"","sources":["../../src/utils/parseDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,aAAa,CAAC,KAAsB;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,6BAA6B,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,qBAAqB,KAAK,kBAAkB,CAAC,CAAC;QAC/D,CAAC;QACD,kEAAkE;QAClE,yEAAyE;QACzE,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,qBAAqB,OAAO,KAAK,gCAAgC,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACpD,CAAC;IAED,uCAAuC;IACvC,0EAA0E;IAC1E,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACd,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,8LAA8L,CACxO,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IAEtB,MAAM,WAAW,GAA2B;QAC3C,EAAE,EAAE,CAAC;QACL,CAAC,EAAE,IAAI;QACP,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,SAAS;QACZ,CAAC,EAAE,UAAU;KACb,CAAC;IAEF,OAAO,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,CAAC;QACJ,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC"}