dotdo 0.0.1 → 0.0.2

package/dist/db/primitives/dag-scheduler/index.js

@@ -0,0 +1,869 @@
+/**
+ * DAGScheduler - Workflow orchestration primitive
+ *
+ * Provides Directed Acyclic Graph scheduling with:
+ * - Task definitions with dependencies
+ * - Topological sort and cycle detection
+ * - Parallel execution with concurrency limits
+ * - Retry policies with exponential backoff
+ * - State persistence for recovery
+ * - Cron scheduling
+ * - Dynamic task generation
+ * - Cross-DAG dependencies
+ *
+ * @module db/primitives/dag-scheduler
+ */
+/** Create a dependency resolver */
+export function createDependencyResolver() {
+    return {
+        getExecutionOrder(dag) {
+            const result = [];
+            const visited = new Set();
+            const inDegree = new Map();
+            // Calculate in-degrees
+            for (const [id, task] of dag.tasks) {
+                inDegree.set(id, task.dependencies.length);
+            }
+            // Kahn's algorithm
+            const queue = [];
+            for (const [id, degree] of inDegree) {
+                if (degree === 0)
+                    queue.push(id);
+            }
+            while (queue.length > 0) {
+                const id = queue.shift();
+                visited.add(id);
+                result.push(dag.tasks.get(id));
+                // Find all tasks that depend on this one
+                for (const [depId, task] of dag.tasks) {
+                    if (task.dependencies.includes(id)) {
+                        const newDegree = inDegree.get(depId) - 1;
+                        inDegree.set(depId, newDegree);
+                        if (newDegree === 0 && !visited.has(depId)) {
+                            queue.push(depId);
+                        }
+                    }
+                }
+            }
+            return result;
+        },
+        detectCycles(dag) {
+            const visited = new Set();
+            const recursionStack = new Set();
+            const cycles = [];
+            function dfs(id, path) {
+                visited.add(id);
+                recursionStack.add(id);
+                path.push(id);
+                const task = dag.tasks.get(id);
+                if (task) {
+                    for (const dep of task.dependencies) {
+                        if (!visited.has(dep)) {
+                            if (dfs(dep, [...path])) {
+                                return true;
+                            }
+                        }
+                        else if (recursionStack.has(dep)) {
+                            // Found cycle
+                            const cycleStart = path.indexOf(dep);
+                            cycles.push(path.slice(cycleStart));
+                            return true;
+                        }
+                    }
+                }
+                recursionStack.delete(id);
+                return false;
+            }
+            for (const id of dag.tasks.keys()) {
+                if (!visited.has(id)) {
+                    dfs(id, []);
+                }
+            }
+            return cycles.length > 0 ? cycles : null;
+        },
+        getReadyTasks(dag, completed) {
+            const ready = [];
+            for (const [id, task] of dag.tasks) {
+                if (completed.has(id))
+                    continue;
+                const allDepsComplete = task.dependencies.every((dep) => completed.has(dep));
+                if (allDepsComplete) {
+                    ready.push(task);
+                }
+            }
+            return ready;
+        },
+        getDependents(dag, taskId, options) {
+            const directDependents = [];
+            for (const [_, task] of dag.tasks) {
+                if (task.dependencies.includes(taskId)) {
+                    directDependents.push(task);
+                }
+            }
+            if (!options?.transitive) {
+                return directDependents;
+            }
+            // Get transitive dependents
+            const allDependents = new Set();
+            const queue = directDependents.map((t) => t.id);
+            while (queue.length > 0) {
+                const id = queue.shift();
+                if (allDependents.has(id))
+                    continue;
+                allDependents.add(id);
+                for (const [_, task] of dag.tasks) {
+                    if (task.dependencies.includes(id) && !allDependents.has(task.id)) {
+                        queue.push(task.id);
+                    }
+                }
+            }
+            return [...allDependents].map((id) => dag.tasks.get(id));
+        },
+    };
+}
+// ============================================================================
+// TASK NODE FACTORY
+// ============================================================================
+/** Create a task node */
+export function createTaskNode(options) {
+    // Validation
+    if (!options.id || options.id.trim() === '') {
+        throw new Error('Task id cannot be empty');
+    }
+    if (options.dependencies.includes(options.id)) {
+        throw new Error('Task cannot depend on itself');
+    }
+    const uniqueDeps = new Set(options.dependencies);
+    if (uniqueDeps.size !== options.dependencies.length) {
+        throw new Error('Duplicate dependency detected');
+    }
+    return {
+        id: options.id,
+        execute: options.execute,
+        dependencies: options.dependencies,
+        retryPolicy: options.retryPolicy,
+        timeout: options.timeout,
+        metadata: options.metadata,
+        dynamic: options.dynamic,
+        collectDynamic: options.collectDynamic,
+    };
+}
+// ============================================================================
+// DAG FACTORY
+// ============================================================================
+/** Create a DAG */
+export function createDAG(options) {
+    const tasks = new Map();
+    // Check for duplicate IDs
+    const ids = new Set();
+    for (const task of options.tasks) {
+        if (ids.has(task.id)) {
+            throw new Error(`Duplicate task id: ${task.id}`);
+        }
+        ids.add(task.id);
+        tasks.set(task.id, task);
+    }
+    // Validate dependencies exist
+    for (const task of options.tasks) {
+        for (const dep of task.dependencies) {
+            if (!ids.has(dep)) {
+                throw new Error(`Task '${task.id}' depends on unknown task '${dep}'`);
+            }
+        }
+    }
+    // Check for cycles
+    const resolver = createDependencyResolver();
+    const tempDag = {
+        id: options.id,
+        tasks,
+        run: async () => ({}),
+    };
+    const cycles = resolver.detectCycles(tempDag);
+    if (cycles) {
+        throw new Error(`Cycle detected in DAG: ${cycles[0].join(' -> ')}`);
+    }
+    const dag = {
+        id: options.id,
+        tasks,
+        schedule: options.schedule,
+        triggers: options.triggers,
+        run: async (execOptions) => {
+            const executor = createParallelExecutor(execOptions);
+            return executor.execute(dag, execOptions);
+        },
+    };
+    return dag;
+}
+/** Task decorator for fluent API */
+export function task(id, execute, options) {
+    const dependencies = (options?.deps ?? []).map((d) => (typeof d === 'string' ? d : d.id));
+    return createTaskNode({ id, execute, dependencies });
+}
+/** Start building a DAG with fluent API */
+export function dag(id, initialTasks) {
+    const tasks = initialTasks ? [...initialTasks] : [];
+    const builder = {
+        task(taskId, execute, options) {
+            const dependencies = (options?.deps ?? []).map((d) => (typeof d === 'string' ? d : d.id));
+            tasks.push(createTaskNode({
+                id: taskId,
+                execute,
+                dependencies,
+                timeout: options?.timeout,
+                retryPolicy: options?.retryPolicy,
+            }));
+            return builder;
+        },
+        build() {
+            return createDAG({ id, tasks });
+        },
+    };
+    return builder;
+}
+// ============================================================================
+// RETRY POLICY FACTORY
+// ============================================================================
+/** Create a retry policy with computed methods */
+export function createRetryPolicy(config) {
+    const getDelay = (attempt) => {
+        const backoff = config.backoff;
+        switch (backoff.type) {
+            case 'fixed':
+                return backoff.delay;
+            case 'exponential': {
+                const delay = backoff.base * Math.pow(2, attempt - 1);
+                return Math.min(delay, backoff.max);
+            }
+            case 'exponential-jitter': {
+                const baseDelay = backoff.base * Math.pow(2, attempt - 1);
+                const cappedDelay = Math.min(baseDelay, backoff.max);
+                // Add jitter: random value between 0 and cappedDelay
+                return Math.random() * cappedDelay;
+            }
+            case 'custom':
+                return backoff.delays[attempt - 1] ?? backoff.delays[backoff.delays.length - 1];
+            default:
+                return 0;
+        }
+    };
+    const shouldRetry = (attempt, error) => {
+        if (attempt >= config.maxAttempts)
+            return false;
+        if (config.retryableErrors && !config.retryableErrors(error))
+            return false;
+        return true;
+    };
+    return {
+        ...config,
+        getDelay,
+        shouldRetry,
+    };
+}
+/** Create a parallel executor */
+export function createParallelExecutor(defaultOptions) {
+    let cancelled = false;
+    let paused = false;
+    let pausePromise = null;
+    let resumePause = null;
+    const dagCompleteCallbacks = [];
+    const waitForResume = () => {
+        if (!paused)
+            return Promise.resolve();
+        if (!pausePromise) {
+            pausePromise = new Promise((resolve) => {
+                resumePause = resolve;
+            });
+        }
+        return pausePromise;
+    };
+    const executeWithTimeout = async (fn, timeout) => {
+        if (!timeout)
+            return fn();
+        return Promise.race([
+            fn(),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('Task timeout exceeded')), timeout);
+            }),
+        ]);
+    };
+    const executeTask = async (task, context, options) => {
+        const result = {
+            taskId: task.id,
+            status: 'running',
+            attempts: 0,
+            startedAt: new Date(),
+        };
+        const policy = task.retryPolicy ? createRetryPolicy(task.retryPolicy) : null;
+        const maxAttempts = policy?.maxAttempts ?? 1;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            result.attempts = attempt;
+            try {
+                await waitForResume();
+                if (cancelled) {
+                    result.status = 'skipped';
+                    return result;
+                }
+                options?.onTaskStart?.(task);
+                const timeout = task.timeout ?? options?.taskTimeout;
+                const output = await executeWithTimeout(() => task.execute(context), timeout);
+                result.status = 'success';
+                result.output = output;
+                result.completedAt = new Date();
+                options?.onTaskComplete?.(task, result);
+                return result;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (policy && policy.shouldRetry(attempt, err)) {
+                    policy.onRetry?.(attempt, err);
+                    await new Promise((resolve) => setTimeout(resolve, policy.getDelay(attempt)));
+                    continue;
+                }
+                result.status = 'failed';
+                result.error = err;
+                result.completedAt = new Date();
+                options?.onTaskComplete?.(task, result);
+                return result;
+            }
+        }
+        return result;
+    };
+    const executor = {
+        async execute(dag, options) {
+            const mergedOptions = { ...defaultOptions, ...options };
+            const maxConcurrency = mergedOptions?.maxConcurrency ?? Infinity;
+            const resolver = createDependencyResolver();
+            const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+            const run = {
+                runId,
+                dagId: dag.id,
+                status: 'running',
+                taskResults: new Map(),
+                startedAt: new Date(),
+            };
+            // Initialize all tasks as pending
+            for (const [id] of dag.tasks) {
+                run.taskResults.set(id, { taskId: id, status: 'pending', attempts: 0 });
+            }
+            // Track expanded dynamic tasks
+            const dynamicTasks = new Map();
+            const dynamicResults = new Map();
+            const completed = new Set();
+            const failed = new Set();
+            const running = new Set();
+            const skipped = new Set();
+            // Get all tasks including dynamic
+            const getAllTasks = () => {
+                const all = new Map(dag.tasks);
+                for (const [id, task] of dynamicTasks) {
+                    all.set(id, task);
+                }
+                return all;
+            };
+            // Mark downstream tasks as skipped
+            const skipDownstream = (taskId) => {
+                const allTasks = getAllTasks();
+                for (const [id, task] of allTasks) {
+                    if (task.dependencies.includes(taskId) && !completed.has(id) && !failed.has(id)) {
+                        skipped.add(id);
+                        run.taskResults.set(id, { taskId: id, status: 'skipped', attempts: 0 });
+                        skipDownstream(id);
+                    }
+                }
+            };
+            // Process tasks
+            while (true) {
+                await waitForResume();
+                if (cancelled) {
+                    run.status = 'cancelled';
+                    break;
+                }
+                const allTasks = getAllTasks();
+                const pendingCount = allTasks.size - completed.size - failed.size - running.size - skipped.size;
+                if (pendingCount === 0 && running.size === 0) {
+                    break;
+                }
+                // Find ready tasks
+                const ready = [];
+                for (const [id, task] of allTasks) {
+                    if (completed.has(id) || failed.has(id) || running.has(id) || skipped.has(id))
+                        continue;
+                    const allDepsComplete = task.dependencies.every((dep) => completed.has(dep) || dynamicResults.has(dep));
+                    const anyDepFailed = task.dependencies.some((dep) => failed.has(dep) || skipped.has(dep));
+                    if (anyDepFailed) {
+                        skipped.add(id);
+                        run.taskResults.set(id, { taskId: id, status: 'skipped', attempts: 0 });
+                        continue;
+                    }
+                    if (allDepsComplete) {
+                        ready.push(task);
+                    }
+                }
+                if (ready.length === 0 && running.size === 0) {
+                    // No progress possible
+                    break;
+                }
+                // Start tasks up to concurrency limit
+                const toStart = ready.slice(0, maxConcurrency - running.size);
+                const taskPromises = toStart.map(async (task) => {
+                    running.add(task.id);
+                    // Build context with upstream results
+                    const upstreamResults = {};
+                    for (const dep of task.dependencies) {
+                        const depResult = run.taskResults.get(dep);
+                        if (depResult?.status === 'success') {
+                            upstreamResults[dep] = depResult.output;
+                        }
+                    }
+                    // Add dynamic results if collecting
+                    let dynResults;
+                    if (task.collectDynamic) {
+                        // Find the dynamic parent task
+                        for (const dep of task.dependencies) {
+                            if (dynamicResults.has(dep)) {
+                                dynResults = dynamicResults.get(dep);
+                            }
+                        }
+                    }
+                    const context = {
+                        runId,
+                        dagId: dag.id,
+                        upstreamResults,
+                        triggerPayload: mergedOptions?.triggerPayload,
+                        dynamicResults: dynResults,
+                    };
+                    const result = await executeTask(task, context, mergedOptions);
+                    run.taskResults.set(task.id, result);
+                    // Save to state store if available
+                    if (mergedOptions?.stateStore) {
+                        await mergedOptions.stateStore.updateTask(runId, task.id, result);
+                    }
+                    running.delete(task.id);
+                    if (result.status === 'success') {
+                        completed.add(task.id);
+                        // Handle dynamic task expansion
+                        if (task.dynamic) {
+                            // Get the upstream result to expand from (first dependency's output)
+                            const upstreamOutput = task.dependencies.length > 0
+                                ? upstreamResults[task.dependencies[0]]
+                                : result.output;
+                            let expandedTasks = task.dynamic.expand(upstreamOutput);
+                            // Apply max expansion limit
+                            if (task.dynamic.maxExpansion) {
+                                expandedTasks = expandedTasks.slice(0, task.dynamic.maxExpansion);
+                            }
+                            const expandedResults = [];
+                            for (const expandedTask of expandedTasks) {
+                                dynamicTasks.set(expandedTask.id, expandedTask);
+                                run.taskResults.set(expandedTask.id, {
+                                    taskId: expandedTask.id,
+                                    status: 'pending',
+                                    attempts: 0,
+                                });
+                            }
+                            // Store reference for fan-in collection
+                            dynamicResults.set(task.id, expandedResults);
+                            // Execute dynamic tasks and collect results
+                            for (const expandedTask of expandedTasks) {
+                                const dynResult = await executeTask(expandedTask, { runId, dagId: dag.id }, mergedOptions);
+                                run.taskResults.set(expandedTask.id, dynResult);
+                                if (dynResult.status === 'success') {
+                                    completed.add(expandedTask.id);
+                                    expandedResults.push(dynResult.output);
+                                }
+                                else {
+                                    failed.add(expandedTask.id);
+                                }
+                            }
+                        }
+                    }
+                    else if (result.status === 'failed') {
+                        failed.add(task.id);
+                        skipDownstream(task.id);
+                    }
+                });
+                // Wait for at least one task to complete
+                if (taskPromises.length > 0) {
+                    await Promise.race(taskPromises);
+                }
+                else {
+                    // Give other tasks a chance to complete
+                    await new Promise((resolve) => setTimeout(resolve, 1));
+                }
+            }
+            // Determine final status
+            if (run.status !== 'cancelled') {
+                run.status = failed.size > 0 ? 'failed' : 'completed';
+            }
+            run.completedAt = new Date();
+            // Save final state
+            if (mergedOptions?.stateStore) {
+                await mergedOptions.stateStore.saveRun(runId, {
+                    runId,
+                    dagId: dag.id,
+                    status: run.status,
+                    taskResults: run.taskResults,
+                    startedAt: run.startedAt,
+                    completedAt: run.completedAt,
+                });
+            }
+            // Fire completion callbacks
+            for (const callback of dagCompleteCallbacks) {
+                try {
+                    await callback(dag.id, run);
+                }
+                catch {
+                    // Ignore callback errors
+                }
+            }
+            return run;
+        },
+        async cancel() {
+            cancelled = true;
+        },
+        pause() {
+            paused = true;
+            pausePromise = null;
+            resumePause = null;
+        },
+        resume(runIdOrVoid, dag) {
+            // Handle overloaded signature
+            if (typeof runIdOrVoid === 'string' && dag) {
+                // Resume from checkpoint
+                return this.resumeFromCheckpoint(runIdOrVoid, dag);
+            }
+            // Regular resume from pause
+            paused = false;
+            if (resumePause) {
+                resumePause();
+                resumePause = null;
+                pausePromise = null;
+            }
+        },
+        async resumeFromCheckpoint(runId, dag) {
+            const mergedOptions = defaultOptions;
+            const store = mergedOptions?.stateStore;
+            if (!store) {
+                throw new Error('State store required for resume');
+            }
+            const savedState = await store.loadRun(runId);
+            if (!savedState) {
+                throw new Error(`Run ${runId} not found`);
+            }
+            // Create run from saved state
+            const run = {
+                runId: savedState.runId,
+                dagId: savedState.dagId,
+                status: 'running',
+                taskResults: new Map(savedState.taskResults),
+                startedAt: savedState.startedAt,
+            };
+            const resolver = createDependencyResolver();
+            const maxConcurrency = mergedOptions?.maxConcurrency ?? Infinity;
+            const completed = new Set();
+            const failed = new Set();
+            const running = new Set();
+            // Restore completed/failed from saved state
+            for (const [id, result] of run.taskResults) {
+                if (result.status === 'success') {
+                    completed.add(id);
+                }
+                else if (result.status === 'failed') {
+                    failed.add(id);
+                }
+            }
+            // Continue execution
+            while (true) {
+                const pendingCount = dag.tasks.size - completed.size - failed.size - running.size;
+                if (pendingCount === 0 && running.size === 0)
+                    break;
+                const ready = resolver.getReadyTasks(dag, completed).filter((t) => !failed.has(t.id) && !running.has(t.id));
+                if (ready.length === 0 && running.size === 0)
+                    break;
+                const toStart = ready.slice(0, maxConcurrency - running.size);
+                const taskPromises = toStart.map(async (task) => {
+                    running.add(task.id);
+                    const upstreamResults = {};
+                    for (const dep of task.dependencies) {
+                        const depResult = run.taskResults.get(dep);
+                        if (depResult?.status === 'success') {
+                            upstreamResults[dep] = depResult.output;
+                        }
+                    }
+                    const context = {
+                        runId,
+                        dagId: dag.id,
+                        upstreamResults,
+                    };
+                    const result = await executeTask(task, context, mergedOptions);
+                    run.taskResults.set(task.id, result);
+                    await store.updateTask(runId, task.id, result);
+                    running.delete(task.id);
+                    if (result.status === 'success') {
+                        completed.add(task.id);
+                    }
+                    else if (result.status === 'failed') {
+                        failed.add(task.id);
+                    }
+                });
+                if (taskPromises.length > 0) {
+                    await Promise.race(taskPromises);
+                }
+                else {
+                    await new Promise((resolve) => setTimeout(resolve, 1));
+                }
+            }
+            run.status = failed.size > 0 ? 'failed' : 'completed';
+            run.completedAt = new Date();
+            await store.saveRun(runId, {
+                runId,
+                dagId: dag.id,
+                status: run.status,
+                taskResults: run.taskResults,
+                startedAt: run.startedAt,
+                completedAt: run.completedAt,
+            });
+            return run;
+        },
+        onDAGComplete(callback) {
+            dagCompleteCallbacks.push(callback);
+        },
+    };
+    return executor;
+}
+// ============================================================================
+// STATE STORE FACTORY
+// ============================================================================
+/** Create an in-memory state store */
+export function createInMemoryStateStore() {
+    const runs = new Map();
+    return {
+        async saveRun(runId, state) {
+            runs.set(runId, {
+                ...state,
+                taskResults: new Map(state.taskResults),
+            });
+        },
+        async loadRun(runId) {
+            const state = runs.get(runId);
+            if (!state)
+                return null;
+            return {
+                ...state,
+                taskResults: new Map(state.taskResults),
+            };
+        },
+        async updateTask(runId, taskId, result) {
+            const state = runs.get(runId);
+            if (state) {
+                state.taskResults.set(taskId, result);
+            }
+        },
+        async listRuns(dagId, options) {
+            const filtered = [...runs.values()].filter((r) => r.dagId === dagId);
+            if (options?.status) {
+                const statusFiltered = filtered.filter((r) => r.status === options.status);
+                return statusFiltered.slice(0, options?.limit);
+            }
+            return filtered.slice(0, options?.limit);
+        },
+    };
+}
+// ============================================================================
+// CRON TRIGGER FACTORY
+// ============================================================================
+/** Day name to number mapping */
+const DAY_NAMES = {
+    SUN: 0,
+    MON: 1,
+    TUE: 2,
+    WED: 3,
+    THU: 4,
+    FRI: 5,
+    SAT: 6,
+};
+/** Parse a cron expression */
+export function parseCronExpression(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+        throw new Error('Invalid cron expression: must have 5 parts');
+    }
+    const parsePart = (part, min, max) => {
+        if (part === '*')
+            return '*';
+        // Step pattern: */n
+        if (part.startsWith('*/')) {
+            const step = parseInt(part.slice(2), 10);
+            if (isNaN(step) || step <= 0) {
+                throw new Error(`Invalid step value: ${part}`);
+            }
+            return { step };
+        }
+        // Range pattern: n-m
+        if (part.includes('-')) {
+            const [startStr, endStr] = part.split('-');
+            let start = parseInt(startStr, 10);
+            let end = parseInt(endStr, 10);
+            // Handle day names
+            if (isNaN(start) && DAY_NAMES[startStr.toUpperCase()] !== undefined) {
+                start = DAY_NAMES[startStr.toUpperCase()];
+            }
+            if (isNaN(end) && DAY_NAMES[endStr.toUpperCase()] !== undefined) {
+                end = DAY_NAMES[endStr.toUpperCase()];
+            }
+            if (isNaN(start) || isNaN(end) || start < min || end > max) {
+                throw new Error(`Invalid range: ${part}`);
+            }
+            return { start, end };
+        }
+        // Single value
+        let value = parseInt(part, 10);
+        if (isNaN(value) && DAY_NAMES[part.toUpperCase()] !== undefined) {
+            value = DAY_NAMES[part.toUpperCase()];
+        }
+        if (isNaN(value) || value < min || value > max) {
+            throw new Error(`Invalid value: ${part} (must be ${min}-${max})`);
+        }
+        return value;
+    };
+    return {
+        minute: parsePart(parts[0], 0, 59),
+        hour: parsePart(parts[1], 0, 23),
+        dayOfMonth: parsePart(parts[2], 1, 31),
+        month: parsePart(parts[3], 1, 12),
+        dayOfWeek: parsePart(parts[4], 0, 6),
+    };
+}
+/** Create a cron trigger */
+export function createCronTrigger(expression, options) {
+    const parsed = parseCronExpression(expression);
+    const opts = options ?? {};
+    const getNextValue = (current, spec, min, max) => {
+        if (spec === '*') {
+            return { value: current, wrapped: false };
+        }
+        if (typeof spec === 'number') {
+            if (current <= spec) {
+                return { value: spec, wrapped: false };
+            }
+            return { value: spec, wrapped: true };
+        }
+        if ('step' in spec) {
+            const next = Math.ceil(current / spec.step) * spec.step;
+            if (next <= max) {
+                return { value: next, wrapped: false };
+            }
+            return { value: 0, wrapped: true };
+        }
+        if ('start' in spec && 'end' in spec) {
+            if (current >= spec.start && current <= spec.end) {
+                return { value: current, wrapped: false };
+            }
+            if (current < spec.start) {
+                return { value: spec.start, wrapped: false };
+            }
+            return { value: spec.start, wrapped: true };
+        }
+        return { value: current, wrapped: false };
+    };
+    return {
+        expression,
+        options: opts,
+        getNextRun(from) {
+            // Adjust for timezone
+            let date = new Date(from);
+            if (opts.timezone) {
+                // Simple timezone offset (for production, use a proper library)
+                const offset = getTimezoneOffset(opts.timezone, date);
+                date = new Date(date.getTime() + offset);
+            }
+            // Start from next minute
+            date = new Date(date);
+            date.setUTCSeconds(0);
+            date.setUTCMilliseconds(0);
+            date.setUTCMinutes(date.getUTCMinutes() + 1);
+            // Iterate to find next match (max 366 days)
+            for (let i = 0; i < 366 * 24 * 60; i++) {
+                const minute = date.getUTCMinutes();
+                const hour = date.getUTCHours();
+                const dayOfMonth = date.getUTCDate();
+                const month = date.getUTCMonth() + 1;
+                const dayOfWeek = date.getUTCDay();
+                // Check if current time matches
+                if (matchesCronPart(minute, parsed.minute) &&
+                    matchesCronPart(hour, parsed.hour) &&
+                    matchesCronPart(dayOfMonth, parsed.dayOfMonth) &&
+                    matchesCronPart(month, parsed.month) &&
+                    matchesCronPart(dayOfWeek, parsed.dayOfWeek)) {
+                    // Convert back from timezone
+                    if (opts.timezone) {
+                        const offset = getTimezoneOffset(opts.timezone, date);
+                        return new Date(date.getTime() - offset);
+                    }
+                    return date;
+                }
+                // Advance by one minute
+                date.setUTCMinutes(date.getUTCMinutes() + 1);
+            }
+            throw new Error('Could not find next run time');
+        },
+        getMissedRuns(lastRun, now) {
+            if (!opts.catchup)
+                return [];
+            const missed = [];
+            let current = new Date(lastRun);
+            while (true) {
+                const next = this.getNextRun(current);
+                if (next >= now)
+                    break;
+                missed.push(next);
+                current = next;
+            }
+            return missed;
+        },
+    };
+}
+/** Check if a value matches a cron part spec */
+function matchesCronPart(value, spec) {
+    if (spec === '*')
+        return true;
+    if (typeof spec === 'number')
+        return value === spec;
+    if ('step' in spec)
+        return value % spec.step === 0;
+    if ('start' in spec && 'end' in spec)
+        return value >= spec.start && value <= spec.end;
+    return false;
+}
+/** Get timezone offset in milliseconds */
+function getTimezoneOffset(timezone, date) {
+    // Simple implementation for common timezones
+    // In production, use Intl.DateTimeFormat or a library like date-fns-tz
+    const offsets = {
+        'America/New_York': -5 * 60 * 60 * 1000, // EST (simplified, doesn't handle DST)
+        'America/Los_Angeles': -8 * 60 * 60 * 1000,
+        'Europe/London': 0,
+        UTC: 0,
+    };
+    return offsets[timezone] ?? 0;
+}
+// ============================================================================
+// SENSOR FACTORY
+// ============================================================================
+/** Create a sensor */
+export function createSensor(options) {
+    return {
+        id: options.id,
+        async wait() {
+            const startTime = Date.now();
+            while (Date.now() - startTime < options.timeout) {
+                const result = await options.poke();
+                if (result)
+                    return true;
+                await new Promise((resolve) => setTimeout(resolve, options.interval));
+            }
+            throw new Error(`Sensor ${options.id} timeout after ${options.timeout}ms`);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map