@classytic/streamline 1.0.0

package/dist/integrations/fastify.d.mts

@@ -0,0 +1,12 @@
+import { _ as WorkflowHandlers, h as WorkflowDefinition } from "../types-DG85_LzF.mjs";
+
+//#region src/integrations/fastify.d.ts
+interface WorkflowPluginOptions {
+  workflows: Array<{
+    definition: WorkflowDefinition;
+    handlers: WorkflowHandlers;
+  }>;
+}
+declare function workflowPlugin(fastify: unknown, options: WorkflowPluginOptions): Promise<void>;
+//#endregion
+export { workflowPlugin as default };

package/dist/integrations/fastify.mjs

@@ -0,0 +1,23 @@
+import { p as WorkflowEngine, t as createContainer } from "../container-BzpIMrrj.mjs";
+
+//#region src/integrations/fastify.ts
+async function workflowPlugin(fastify, options) {
+	const engines = /* @__PURE__ */ new Map();
+	const fastifyInstance = fastify;
+	for (const { definition, handlers } of options.workflows) {
+		const engine = new WorkflowEngine(definition, handlers, createContainer());
+		engines.set(definition.id, engine);
+	}
+	fastifyInstance.decorate("workflows", engines);
+	fastifyInstance.decorate("getWorkflow", (id) => {
+		const engine = engines.get(id);
+		if (!engine) throw new Error(`Workflow ${id} not found`);
+		return engine;
+	});
+	fastifyInstance.addHook("onClose", async () => {
+		for (const engine of engines.values()) engine.shutdown();
+	});
+}
+
+//#endregion
+export { workflowPlugin as default };

package/dist/telemetry/index.d.mts

@@ -0,0 +1,18 @@
+import { t as WorkflowEventBus } from "../events-C0sZINZq.mjs";
+import { Tracer } from "@opentelemetry/api";
+
+//#region src/telemetry/index.d.ts
+interface TelemetryConfig {
+  tracer: Tracer;
+  /** Event bus to listen to (defaults to globalEventBus) */
+  eventBus?: WorkflowEventBus;
+}
+declare function enableTelemetry(config: TelemetryConfig): void;
+declare function disableTelemetry(): void;
+declare function isTelemetryEnabled(): boolean;
+/**
+ * Get the current event bus used by telemetry (for debugging)
+ */
+declare function getTelemetryEventBus(): WorkflowEventBus | null;
+//#endregion
+export { disableTelemetry, enableTelemetry, getTelemetryEventBus, isTelemetryEnabled };

package/dist/telemetry/index.mjs

@@ -0,0 +1,102 @@
+import { n as globalEventBus } from "../events-B5aTz7kD.mjs";
+
+//#region src/telemetry/index.ts
+const spans = /* @__PURE__ */ new Map();
+const listeners = [];
+let currentEventBus = null;
+let enabled = false;
+function enableTelemetry(config) {
+	if (enabled) return;
+	const { tracer } = config;
+	const eventBus = config.eventBus ?? globalEventBus;
+	currentEventBus = eventBus;
+	enabled = true;
+	const on = (event, handler) => {
+		const fn = (...args) => handler(args[0]);
+		listeners.push({
+			event,
+			fn,
+			bus: eventBus
+		});
+		eventBus.on(event, fn);
+	};
+	on("workflow:started", ({ runId }) => {
+		if (!runId) return;
+		const span = tracer.startSpan(`workflow:${runId}`);
+		span.setAttribute("workflow.runId", runId);
+		spans.set(runId, span);
+	});
+	on("step:started", ({ runId, stepId }) => {
+		if (!runId || !stepId) return;
+		const span = tracer.startSpan(`step:${stepId}`);
+		span.setAttribute("workflow.runId", runId);
+		span.setAttribute("step.id", stepId);
+		spans.set(`${runId}:${stepId}`, span);
+	});
+	on("step:completed", ({ runId, stepId }) => {
+		if (!runId || !stepId) return;
+		const span = spans.get(`${runId}:${stepId}`);
+		if (span) {
+			span.setStatus({ code: 1 });
+			span.end();
+			spans.delete(`${runId}:${stepId}`);
+		}
+	});
+	on("step:failed", ({ runId, stepId, data }) => {
+		if (!runId || !stepId) return;
+		const span = spans.get(`${runId}:${stepId}`);
+		if (span) {
+			const errorData = data;
+			span.setStatus({
+				code: 2,
+				message: errorData?.error?.message
+			});
+			if (errorData?.error) span.recordException(errorData.error);
+			span.end();
+			spans.delete(`${runId}:${stepId}`);
+		}
+	});
+	on("workflow:completed", ({ runId }) => {
+		if (!runId) return;
+		const span = spans.get(runId);
+		if (span) {
+			span.setStatus({ code: 1 });
+			span.end();
+			spans.delete(runId);
+		}
+	});
+	on("workflow:failed", ({ runId, data }) => {
+		if (!runId) return;
+		const span = spans.get(runId);
+		if (span) {
+			const errorData = data;
+			span.setStatus({
+				code: 2,
+				message: errorData?.error?.message
+			});
+			if (errorData?.error) span.recordException(errorData.error);
+			span.end();
+			spans.delete(runId);
+		}
+	});
+}
+function disableTelemetry() {
+	if (!enabled) return;
+	listeners.forEach(({ event, fn, bus }) => bus.off(event, fn));
+	listeners.length = 0;
+	spans.clear();
+	currentEventBus = null;
+	enabled = false;
+}
+function isTelemetryEnabled() {
+	return enabled;
+}
+/**
+* Get the current event bus used by telemetry (for debugging)
+*/
+function getTelemetryEventBus() {
+	return currentEventBus;
+}
+
+//#endregion
+export { disableTelemetry, enableTelemetry, getTelemetryEventBus, isTelemetryEnabled };

package/dist/types-DG85_LzF.d.mts

@@ -0,0 +1,275 @@
+//#region src/core/types.d.ts
+type StepStatus = 'pending' | 'running' | 'waiting' | 'done' | 'failed' | 'skipped';
+type RunStatus = 'draft' | 'running' | 'waiting' | 'done' | 'failed' | 'cancelled';
+interface Step {
+  id: string;
+  name: string;
+  description?: string;
+  /**
+   * Maximum number of execution attempts for this step (including the initial attempt).
+   *
+   * Example: retries=3 means:
+   * - Attempt 1 (initial execution)
+   * - Attempt 2 (first retry after failure)
+   * - Attempt 3 (second retry after failure)
+   * - Total: 3 attempts
+   *
+   * If all attempts fail, the step is marked as 'failed' and the workflow stops.
+   * Uses exponential backoff: 1s, 2s, 4s, 8s, ... (max 60s between retries).
+   *
+   * @default 3
+   */
+  retries?: number;
+  /**
+   * Maximum execution time in milliseconds for this step.
+   * If the step handler doesn't complete within this time, it throws a timeout error.
+   *
+   * @default undefined (no timeout)
+   */
+  timeout?: number;
+  /**
+   * Full condition function with access to context and run.
+   * Return true to execute the step, false to skip.
+   *
+   * @example
+   * ```typescript
+   * step({
+   *   id: 'send-email',
+   *   name: 'Send Email',
+   *   condition: (context, run) => context.shouldSendEmail && run.status === 'running'
+   * })
+   * ```
+   */
+  condition?: (context: unknown, run: WorkflowRun) => boolean | Promise<boolean>;
+  /**
+   * Skip this step if the predicate returns true.
+   * Simpler alternative to condition for basic skip logic.
+   *
+   * @example
+   * ```typescript
+   * step({ id: 'optional-step', name: 'Optional', skipIf: (ctx) => !ctx.featureEnabled })
+   * ```
+   */
+  skipIf?: (context: unknown) => boolean | Promise<boolean>;
+  /**
+   * Only run this step if the predicate returns true.
+   * Simpler alternative to condition for basic run logic.
+   *
+   * @example
+   * ```typescript
+   * step({ id: 'premium-feature', name: 'Premium', runIf: (ctx) => ctx.isPremiumUser })
+   * ```
+   */
+  runIf?: (context: unknown) => boolean | Promise<boolean>;
+}
+interface StepError {
+  message: string;
+  code?: string;
+  retriable?: boolean;
+  stack?: string;
+}
+interface WorkflowError {
+  message: string;
+  code?: string;
+  stack?: string;
+}
+interface WaitingFor {
+  type: 'human' | 'webhook' | 'timer' | 'event';
+  reason: string;
+  resumeAt?: Date;
+  eventName?: string;
+  data?: unknown;
+}
+interface StepState<TOutput = unknown> {
+  stepId: string;
+  status: StepStatus;
+  attempts: number;
+  startedAt?: Date;
+  endedAt?: Date;
+  output?: TOutput;
+  waitingFor?: WaitingFor;
+  error?: StepError;
+  retryAfter?: Date;
+}
+/**
+ * Scheduling metadata for timezone-aware workflow execution
+ */
+interface SchedulingInfo {
+  /**
+   * User's intended local time as ISO string (without timezone suffix)
+   * Format: "YYYY-MM-DDTHH:mm:ss" (e.g., "2024-03-10T09:00:00")
+   * This is the ORIGINAL string the user provided, preserved for accurate rescheduling
+   */
+  scheduledFor: string;
+  /** IANA timezone name (e.g., "America/New_York", "Europe/London") */
+  timezone: string;
+  /** Human-readable local time with timezone abbreviation (e.g., "2024-03-10 09:00:00 EDT") */
+  localTimeDisplay: string;
+  /** UTC execution time - used by scheduler for actual execution */
+  executionTime: Date;
+  /** Whether this time falls during a DST transition */
+  isDSTTransition: boolean;
+  /** Human-readable note about DST adjustments (if any) */
+  dstNote?: string;
+  /** Optional recurrence pattern for repeating workflows */
+  recurrence?: RecurrencePattern;
+}
+/**
+ * Recurrence pattern for scheduled workflows
+ */
+interface RecurrencePattern {
+  /** How often to repeat (daily, weekly, monthly, custom cron) */
+  pattern: 'daily' | 'weekly' | 'monthly' | 'custom';
+  /** For weekly: which days (0=Sunday, 6=Saturday) */
+  daysOfWeek?: number[];
+  /** For monthly: which day of month (1-31) */
+  dayOfMonth?: number;
+  /** Custom cron expression (if pattern='custom') */
+  cronExpression?: string;
+  /** Stop repeating after this date */
+  until?: Date;
+  /** Or stop after N occurrences */
+  count?: number;
+  /** How many times has this recurred so far */
+  occurrences?: number;
+}
+interface WorkflowRun<TContext = Record<string, unknown>> {
+  _id: string;
+  workflowId: string;
+  status: RunStatus;
+  steps: StepState[];
+  currentStepId: string | null;
+  context: TContext;
+  input: unknown;
+  output?: unknown;
+  error?: WorkflowError;
+  createdAt: Date;
+  updatedAt: Date;
+  startedAt?: Date;
+  endedAt?: Date;
+  lastHeartbeat?: Date;
+  paused?: boolean;
+  /** Timezone-aware scheduling metadata (optional - only for scheduled workflows) */
+  scheduling?: SchedulingInfo;
+  userId?: string;
+  tags?: string[];
+  meta?: Record<string, unknown>;
+}
+interface WorkflowDefinition<TContext = Record<string, unknown>> {
+  id: string;
+  name: string;
+  version: string;
+  steps: Step[];
+  createContext: (input: unknown) => TContext;
+  /**
+   * Default values for all steps in this workflow.
+   * Individual steps can override these defaults.
+   */
+  defaults?: {
+    /**
+     * Maximum number of execution attempts for each step (including initial attempt).
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Maximum execution time in milliseconds for each step.
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+  };
+}
+interface StepContext<TContext = Record<string, unknown>> {
+  runId: string;
+  stepId: string;
+  context: TContext;
+  input: unknown;
+  attempt: number;
+  /**
+   * AbortSignal for step cancellation.
+   * Handlers should check this signal and abort long-running operations when triggered.
+   * The signal is aborted when:
+   * - Step timeout is exceeded
+   * - Workflow is cancelled
+   *
+   * @example
+   * ```typescript
+   * async function fetchData(ctx) {
+   *   const response = await fetch(url, { signal: ctx.signal });
+   *   // ...
+   * }
+   * ```
+   */
+  signal: AbortSignal;
+  set: <K extends keyof TContext>(key: K, value: TContext[K]) => Promise<void>;
+  getOutput: <T = unknown>(stepId: string) => T | undefined;
+  wait: (reason: string, data?: unknown) => Promise<never>;
+  waitFor: (eventName: string, reason?: string) => Promise<unknown>;
+  sleep: (ms: number) => Promise<void>;
+  /**
+   * Send a heartbeat to prevent the workflow from being marked as stale.
+   * Use this in long-running steps (5+ minutes) to signal the step is still active.
+   *
+   * Heartbeats are automatically sent every 30 seconds during step execution,
+   * but you can call this manually for extra control.
+   *
+   * @example
+   * ```typescript
+   * async function processLargeDataset(ctx) {
+   *   for (const batch of batches) {
+   *     await processBatch(batch);
+   *     await ctx.heartbeat(); // Signal we're still alive
+   *   }
+   * }
+   * ```
+   */
+  heartbeat: () => Promise<void>;
+  emit: (eventName: string, data: unknown) => void;
+  log: (message: string, data?: unknown) => void;
+}
+type StepHandler<TOutput = unknown, TContext = Record<string, unknown>> = (ctx: StepContext<TContext>) => Promise<TOutput>;
+type WorkflowHandlers<TContext = Record<string, unknown>> = {
+  [stepId: string]: StepHandler<unknown, TContext>;
+};
+/**
+ * Infer context type from WorkflowDefinition
+ * @example
+ * type MyContext = InferContext<typeof myWorkflow>
+ */
+type InferContext<T> = T extends WorkflowDefinition<infer TContext> ? TContext : never;
+/**
+ * Infer context type from WorkflowHandlers
+ * @example
+ * type MyContext = InferHandlersContext<typeof myHandlers>
+ */
+type InferHandlersContext<T> = T extends WorkflowHandlers<infer TContext> ? TContext : never;
+/**
+ * Strongly-typed handlers that match workflow steps
+ * Ensures all step IDs have corresponding handlers
+ * @example
+ * const handlers: TypedHandlers<typeof workflow, MyContext> = { ... }
+ */
+type TypedHandlers<TWorkflow extends WorkflowDefinition<any>, TContext = InferContext<TWorkflow>> = { [K in TWorkflow['steps'][number]['id']]: StepHandler<unknown, TContext> };
+/**
+ * Extract step IDs as union type from workflow definition
+ * @example
+ * type MyStepIds = StepIds<typeof myWorkflow> // 'step1' | 'step2' | 'step3'
+ */
+type StepIds<T extends WorkflowDefinition<any>> = T['steps'][number]['id'];
+/**
+ * Payload for workflow and engine events
+ */
+interface WorkflowEventPayload {
+  runId?: string;
+  stepId?: string;
+  data?: unknown;
+  error?: Error;
+  context?: string;
+  /**
+   * Explicit broadcast flag for resuming multiple workflows.
+   * When true, the event will resume ALL workflows waiting on this event.
+   * When false/undefined with no runId, a warning is logged.
+   */
+  broadcast?: boolean;
+}
+//#endregion
+export { WorkflowHandlers as _, SchedulingInfo as a, StepError as c, StepState as d, StepStatus as f, WorkflowEventPayload as g, WorkflowDefinition as h, RunStatus as i, StepHandler as l, WaitingFor as m, InferHandlersContext as n, Step as o, TypedHandlers as p, RecurrencePattern as r, StepContext as s, InferContext as t, StepIds as u, WorkflowRun as v };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@classytic/streamline",
+  "version": "1.0.0",
+  "description": "MongoDB-native durable workflow orchestration engine. Like Temporal but simpler - supports sleep, wait, retry, parallel execution, human-in-the-loop, and crash recovery. Perfect for payment gateways, approval flows, and scheduled tasks.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./fastify": {
+      "types": "./dist/integrations/fastify.d.mts",
+      "default": "./dist/integrations/fastify.mjs"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry/index.d.mts",
+      "default": "./dist/telemetry/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "workflow",
+    "temporal",
+    "durable",
+    "durable-execution",
+    "orchestration",
+    "mongodb",
+    "mongoose",
+    "sleep",
+    "wait",
+    "resume",
+    "human-in-the-loop",
+    "background-jobs",
+    "state-machine",
+    "crash-recovery",
+    "retry",
+    "parallel",
+    "scheduling",
+    "webhook",
+    "approval-flow",
+    "typescript"
+  ],
+  "author": "Classytic <classytic.dev@gmail.com> (https://github.com/classytic)",
+  "contributors": [
+    "Sadman Chowdhury (https://github.com/siam923)"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/streamline.git"
+  },
+  "homepage": "https://github.com/classytic/streamline#readme",
+  "bugs": {
+    "url": "https://github.com/classytic/streamline/issues"
+  },
+  "peerDependencies": {
+    "@classytic/mongokit": "^3.2.3",
+    "mongoose": "^9.0.0",
+    "@opentelemetry/api": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@classytic/mongokit": "^3.2.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@types/luxon": "^3.7.1",
+    "luxon": "^3.7.2",
+    "semver": "^7.7.3",
+    "@types/node": "^22.0.0",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^3.0.0",
+    "mongodb-memory-server": "^11.0.1",
+    "mongoose": "^9.0.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "luxon": "^3.0.0",
+    "semver": "^7.0.0"
+  }
+}