@classytic/streamline 1.0.0

package/dist/index.mjs

@@ -0,0 +1,1102 @@
+import { a as StepNotFoundError, c as WorkflowNotFoundError, i as MaxRetriesExceededError, n as ErrorCode, o as StepTimeoutError, r as InvalidStateError, s as WorkflowError, t as DataCorruptionError } from "./errors-BqunvWPz.mjs";
+import { A as isValidStepTransition, C as RUN_STATUS_VALUES, D as isStepStatus, E as isRunStatus, M as logger, O as isTerminalState, S as shouldSkipStep, T as deriveRunStatus, _ as COMPUTED, a as singleTenantPlugin, b as createCondition, c as RUN_STATUS, d as WorkflowRunModel, f as WorkflowCache, g as validateRetryConfig, h as validateId, i as workflowRunRepository, j as WaitSignal, k as isValidRunTransition, l as STEP_STATUS, m as hookRegistry, n as isStreamlineContainer, o as tenantFilterPlugin, p as WorkflowEngine, r as createWorkflowRepository, s as CommonQueries, t as createContainer, u as WorkflowQueryBuilder, v as SCHEDULING, w as STEP_STATUS_VALUES, x as isConditionalStep, y as conditions } from "./container-BzpIMrrj.mjs";
+import { n as globalEventBus, t as WorkflowEventBus } from "./events-B5aTz7kD.mjs";
+import { randomBytes, randomUUID } from "node:crypto";
+import mongoose, { Schema } from "mongoose";
+import semver from "semver";
+import { DateTime } from "luxon";
+
+//#region src/workflow/define.ts
+/**
+* Simplified Workflow Definition API
+*
+* Inspired by Vercel's workflow - cleaner, function-based syntax.
+* No compiler needed - just cleaner ergonomics.
+*
+* @example
+* ```typescript
+* import { createWorkflow } from '@classytic/streamline';
+*
+* const userSignup = createWorkflow('user-signup', {
+*   steps: {
+*     createUser: async (ctx) => {
+*       return { id: crypto.randomUUID(), email: ctx.input.email };
+*     },
+*     sendWelcome: async (ctx) => {
+*       const user = ctx.getOutput('createUser');
+*       await sendEmail(user.email, 'Welcome!');
+*     },
+*     onboard: async (ctx) => {
+*       await ctx.sleep(5000);
+*       await sendOnboardingEmail(ctx.getOutput('createUser'));
+*     },
+*   },
+*   context: (input) => ({ email: input.email }),
+* });
+*
+* // Start workflow
+* const run = await userSignup.start({ email: 'test@example.com' });
+* ```
+*/
+const toName = (id) => id.replace(/-/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/\b\w/g, (c) => c.toUpperCase());
+/**
+* Create a workflow with inline step handlers
+*
+* @example
+* ```typescript
+* const orderProcess = createWorkflow('order-process', {
+*   steps: {
+*     validate: async (ctx) => validateOrder(ctx.input),
+*     charge: async (ctx) => chargeCard(ctx.getOutput('validate')),
+*     fulfill: async (ctx) => shipOrder(ctx.getOutput('charge')),
+*     notify: async (ctx) => sendConfirmation(ctx.context.email),
+*   },
+*   context: (input) => ({ orderId: input.id, email: input.email }),
+* });
+*
+* await orderProcess.start({ id: '123', email: 'user@example.com' });
+* ```
+*
+* @example Custom container for testing
+* ```typescript
+* const container = createContainer();
+* const workflow = createWorkflow('test-workflow', {
+*   steps: { ... },
+*   container
+* });
+* ```
+*/
+function createWorkflow(id, config) {
+	validateId(id, "workflow");
+	const stepIds = Object.keys(config.steps);
+	if (stepIds.length === 0) throw new Error("Workflow must have at least one step");
+	if (config.defaults) validateRetryConfig(config.defaults.retries, config.defaults.timeout);
+	const definition = {
+		id,
+		name: toName(id),
+		version: config.version ?? "1.0.0",
+		steps: stepIds.map((stepId) => ({
+			id: stepId,
+			name: toName(stepId)
+		})),
+		createContext: config.context ?? ((input) => input),
+		defaults: config.defaults
+	};
+	const container = config.container ?? createContainer();
+	const engine = new WorkflowEngine(definition, config.steps, container, { ...config.autoExecute !== void 0 && { autoExecute: config.autoExecute } });
+	const waitFor = async (runId, options = {}) => {
+		const { pollInterval = 1e3, timeout } = options;
+		const startTime = Date.now();
+		while (true) {
+			const run = await engine.get(runId);
+			if (!run) throw new WorkflowNotFoundError(runId);
+			if (isTerminalState(run.status)) return run;
+			if (timeout && Date.now() - startTime >= timeout) throw new Error(`Timeout waiting for workflow "${runId}" to complete after ${timeout}ms. Current status: ${run.status}`);
+			await new Promise((resolve) => setTimeout(resolve, pollInterval));
+		}
+	};
+	return {
+		start: (input, meta) => engine.start(input, meta),
+		get: (runId) => engine.get(runId),
+		execute: (runId) => engine.execute(runId),
+		resume: (runId, payload) => engine.resume(runId, payload),
+		cancel: (runId) => engine.cancel(runId),
+		pause: (runId) => engine.pause(runId),
+		rewindTo: (runId, stepId) => engine.rewindTo(runId, stepId),
+		waitFor,
+		shutdown: () => engine.shutdown(),
+		definition,
+		engine,
+		container
+	};
+}
+
+//#endregion
+//#region src/features/hooks.ts
+/**
+* Hooks & Webhooks
+*
+* Inspired by Vercel's workflow hooks - pause execution and wait for external input.
+*
+* @example
+* ```typescript
+* const approval = createWorkflow('doc-approval', {
+*   steps: {
+*     request: async (ctx) => {
+*       await sendApprovalEmail(ctx.input.docId);
+*       return createHook(ctx, 'approval');
+*     },
+*     process: async (ctx) => {
+*       const { approved } = ctx.getOutput<{ approved: boolean }>('request');
+*       if (approved) await publishDoc(ctx.input.docId);
+*     },
+*   },
+* });
+*
+* // Resume hook from API route
+* const result = await resumeHook(token, { approved: true });
+* console.log(result.run); // The resumed workflow run
+* ```
+*/
+/**
+* Create a hook that pauses workflow until external input.
+* The token includes a crypto-random suffix for security.
+*
+* IMPORTANT: Pass the returned token to ctx.wait() to enable token validation:
+* ```typescript
+* const hook = createHook(ctx, 'approval');
+* return ctx.wait(hook.token, { hookToken: hook.token }); // Token stored for validation
+* ```
+*
+* @example
+* ```typescript
+* // In step handler
+* async function waitForApproval(ctx) {
+*   const hook = createHook(ctx, 'waiting-for-approval');
+*   console.log('Resume with token:', hook.token);
+*   return ctx.wait(hook.token, { hookToken: hook.token }); // Token validated on resume
+* }
+*
+* // From API route
+* await resumeHook('token-123', { approved: true });
+* ```
+*/
+function createHook(ctx, reason, options) {
+	const randomSuffix = randomBytes(16).toString("hex");
+	const token = options?.token ?? `${ctx.runId}:${ctx.stepId}:${randomSuffix}`;
+	return {
+		token,
+		path: `/hooks/${token}`
+	};
+}
+/**
+* Resume a paused workflow by hook token.
+*
+* Security: If the workflow was paused with a hookToken in waitingFor.data,
+* this function validates the token before resuming.
+*
+* Multi-worker support: Falls back to DB lookup if engine not in local registry.
+*
+* @example
+* ```typescript
+* // API route handler
+* app.post('/hooks/:token', async (req, res) => {
+*   const result = await resumeHook(req.params.token, req.body);
+*   res.json({ success: true, runId: result.runId, status: result.run.status });
+* });
+* ```
+*/
+async function resumeHook(token, payload) {
+	const [runId] = token.split(":");
+	if (!runId) throw new Error(`Invalid hook token: ${token}`);
+	const engine = hookRegistry.getEngine(runId);
+	if (!engine) throw new Error(`No engine registered for workflow ${runId}. Ensure the workflow was started with createWorkflow() and the engine is still running. For multi-worker deployments, ensure all workers use shared state or implement a custom resume endpoint.`);
+	const run = await engine.container.repository.getById(runId);
+	if (!run) throw new Error(`Workflow not found for token: ${token}`);
+	if (run.status !== "waiting") throw new Error(`Workflow ${runId} is not waiting (status: ${run.status})`);
+	const storedToken = (run.steps.find((s) => s.status === "waiting")?.waitingFor?.data)?.hookToken;
+	if (storedToken && storedToken !== token) throw new Error(`Invalid hook token for workflow ${runId}`);
+	const resumedRun = await engine.resume(runId, payload);
+	return {
+		runId: run._id,
+		run: resumedRun
+	};
+}
+/**
+* Generate a deterministic token for idempotent hooks
+*
+* @example
+* ```typescript
+* // Slack bot - same channel always gets same token
+* const token = hookToken('slack', channelId);
+* const hook = createHook(ctx, 'slack-message', { token });
+* ```
+*/
+function hookToken(...parts) {
+	return parts.join(":");
+}
+
+//#endregion
+//#region src/storage/definition.model.ts
+/**
+* Workflow Definition Model (Optional)
+*
+* Stores workflow definitions in MongoDB for:
+* - Versioning: Track workflow changes over time
+* - Auditing: Who created/modified workflows
+* - Dynamic loading: Load workflows from DB instead of code
+* - Collaboration: Teams can share workflow definitions
+*
+* Note: This is OPTIONAL. You can define workflows in code without this model.
+*/
+const WorkflowDefinitionSchema = new Schema({
+	workflowId: {
+		type: String,
+		required: true,
+		index: true
+	},
+	name: {
+		type: String,
+		required: true
+	},
+	description: String,
+	version: {
+		type: String,
+		required: true,
+		default: "1.0.0"
+	},
+	versionMajor: {
+		type: Number,
+		required: true
+	},
+	versionMinor: {
+		type: Number,
+		required: true
+	},
+	versionPatch: {
+		type: Number,
+		required: true
+	},
+	steps: [{
+		id: {
+			type: String,
+			required: true
+		},
+		name: {
+			type: String,
+			required: true
+		},
+		retries: Number,
+		timeout: Number,
+		condition: String
+	}],
+	defaults: {
+		retries: Number,
+		timeout: Number
+	},
+	createdBy: String,
+	updatedBy: String,
+	isActive: {
+		type: Boolean,
+		default: true
+	},
+	tags: [String],
+	metadata: Schema.Types.Mixed
+}, {
+	collection: "workflow_definitions",
+	timestamps: true
+});
+WorkflowDefinitionSchema.pre("save", function() {
+	if (this.isModified("version")) {
+		const parsed = semver.parse(this.version);
+		if (!parsed) throw new Error(`Invalid semver version: ${this.version}`);
+		this.versionMajor = parsed.major;
+		this.versionMinor = parsed.minor;
+		this.versionPatch = parsed.patch;
+	}
+});
+WorkflowDefinitionSchema.index({ name: 1 });
+WorkflowDefinitionSchema.index({ isActive: 1 });
+WorkflowDefinitionSchema.index({ tags: 1 });
+WorkflowDefinitionSchema.index({
+	workflowId: 1,
+	version: 1
+}, { unique: true });
+WorkflowDefinitionSchema.index({
+	workflowId: 1,
+	isActive: 1,
+	versionMajor: -1,
+	versionMinor: -1,
+	versionPatch: -1
+});
+/**
+* MULTI-TENANCY & CUSTOM INDEXES
+*
+* This model is intentionally unopinionated about multi-tenancy.
+* Different apps have different needs (tenantId, orgId, workspaceId, etc.)
+*
+* To add custom indexes for your app:
+*
+* import { WorkflowDefinitionModel } from '@classytic/streamline';
+*
+* // Add your custom indexes
+* WorkflowDefinitionModel.collection.createIndex({ tenantId: 1, isActive: 1 });
+* WorkflowDefinitionModel.collection.createIndex({ orgId: 1, createdAt: -1 });
+*
+* OR extend the schema:
+*
+* import { WorkflowDefinitionModel } from '@classytic/streamline';
+* WorkflowDefinitionModel.schema.add({ tenantId: String });
+* WorkflowDefinitionModel.schema.index({ tenantId: 1, isActive: 1 });
+*/
+/**
+* Export WorkflowDefinitionModel with hot-reload safety
+* 
+* The pattern checks if the model already exists before creating a new one.
+* This prevents "OverwriteModelError" in development with hot module replacement.
+*/
+let WorkflowDefinitionModel;
+if (mongoose.models.WorkflowDefinition) WorkflowDefinitionModel = mongoose.models.WorkflowDefinition;
+else WorkflowDefinitionModel = mongoose.model("WorkflowDefinition", WorkflowDefinitionSchema);
+/**
+* Repository for WorkflowDefinition
+* Optional: Use if you want to store workflows in MongoDB
+*/
+const workflowDefinitionRepository = {
+	async create(definition) {
+		if (definition.version) {
+			const parsed = semver.parse(definition.version);
+			if (!parsed) throw new Error(`Invalid semver version: ${definition.version}`);
+			definition.versionMajor = parsed.major;
+			definition.versionMinor = parsed.minor;
+			definition.versionPatch = parsed.patch;
+		}
+		return (await WorkflowDefinitionModel.create(definition)).toObject();
+	},
+	async getLatestVersion(workflowId) {
+		return await WorkflowDefinitionModel.findOne({
+			workflowId,
+			isActive: true
+		}).sort({
+			versionMajor: -1,
+			versionMinor: -1,
+			versionPatch: -1
+		}).lean();
+	},
+	async getByVersion(workflowId, version) {
+		return await WorkflowDefinitionModel.findOne({
+			workflowId,
+			version
+		}).lean();
+	},
+	async getActiveDefinitions() {
+		return await WorkflowDefinitionModel.aggregate([
+			{ $match: { isActive: true } },
+			{ $sort: {
+				versionMajor: -1,
+				versionMinor: -1,
+				versionPatch: -1
+			} },
+			{ $group: {
+				_id: "$workflowId",
+				doc: { $first: "$$ROOT" }
+			} },
+			{ $replaceRoot: { newRoot: "$doc" } },
+			{ $sort: { createdAt: -1 } }
+		]);
+	},
+	async getVersionHistory(workflowId) {
+		return await WorkflowDefinitionModel.find({ workflowId }).sort({
+			versionMajor: -1,
+			versionMinor: -1,
+			versionPatch: -1
+		}).lean();
+	},
+	async update(workflowId, version, updates) {
+		if (updates.version) {
+			const parsed = semver.parse(updates.version);
+			if (!parsed) throw new Error(`Invalid semver version: ${updates.version}`);
+			updates.versionMajor = parsed.major;
+			updates.versionMinor = parsed.minor;
+			updates.versionPatch = parsed.patch;
+		}
+		return await WorkflowDefinitionModel.findOneAndUpdate({
+			workflowId,
+			version
+		}, updates, { returnDocument: "after" }).lean();
+	},
+	async deactivate(workflowId, version) {
+		const filter = { workflowId };
+		if (version) filter.version = version;
+		await WorkflowDefinitionModel.updateMany(filter, { isActive: false });
+	},
+	async deactivateOldVersions(workflowId, keepVersion) {
+		await WorkflowDefinitionModel.updateMany({
+			workflowId,
+			version: { $ne: keepVersion }
+		}, { isActive: false });
+	}
+};
+
+//#endregion
+//#region src/utils/visualization.ts
+function getStepTimeline(run) {
+	return run.steps.map((step) => ({
+		id: step.stepId,
+		status: step.status,
+		duration: step.startedAt && step.endedAt ? step.endedAt.getTime() - step.startedAt.getTime() : null,
+		startedAt: step.startedAt,
+		endedAt: step.endedAt
+	}));
+}
+function getWorkflowProgress(run) {
+	const total = run.steps.length;
+	const completed = run.steps.filter((s) => s.status === "done").length;
+	return {
+		completed,
+		total,
+		percentage: total > 0 ? Math.round(completed / total * 100) : 0
+	};
+}
+function getStepUIStates(run) {
+	const currentIndex = run.steps.findIndex((s) => s.stepId === run.currentStepId);
+	return run.steps.map((step, index) => ({
+		...step,
+		isCurrentStep: step.stepId === run.currentStepId,
+		isPastStep: index < currentIndex,
+		isFutureStep: index > currentIndex,
+		canRewindTo: index <= currentIndex && step.status === "done"
+	}));
+}
+function getWaitingInfo(run) {
+	const waitingStep = run.steps.find((s) => s.status === "waiting");
+	if (!waitingStep?.waitingFor) return null;
+	return {
+		stepId: waitingStep.stepId,
+		type: waitingStep.waitingFor.type,
+		reason: waitingStep.waitingFor.reason,
+		resumeAt: waitingStep.waitingFor.resumeAt,
+		eventName: waitingStep.waitingFor.eventName,
+		data: waitingStep.waitingFor.data
+	};
+}
+function canRewindTo(run, stepId) {
+	const step = run.steps.find((s) => s.stepId === stepId);
+	if (!step) return false;
+	return run.steps.findIndex((s) => s.stepId === stepId) <= run.steps.findIndex((s) => s.stepId === run.currentStepId) && step.status === "done";
+}
+function getExecutionPath(run) {
+	return run.steps.filter((s) => s.status === "done").map((s) => s.stepId);
+}
+
+//#endregion
+//#region src/scheduling/timezone-handler.ts
+/**
+* TimezoneHandler - Industry-standard timezone conversion with DST edge case handling
+*
+* Handles two critical DST edge cases:
+* 1. Spring Forward (non-existent time): When clocks jump forward, e.g., 2:30 AM doesn't exist
+* 2. Fall Back (ambiguous time): When clocks fall back, e.g., 1:30 AM occurs twice
+*
+* Design Philosophy:
+* - Store both intent (timezone + local time) AND execution time (UTC)
+* - Gracefully handle invalid times by adjusting forward
+* - Warn users about ambiguous times during fall back
+* - Use IANA timezone database (not abbreviations like "EST")
+*
+* @example
+* ```typescript
+* const handler = new TimezoneHandler();
+*
+* // Schedule for 9:00 AM New York time
+* const result = handler.calculateExecutionTime(
+*   '2024-03-10T09:00:00',
+*   'America/New_York'
+* );
+*
+* console.log(result.executionTime); // UTC time for scheduler
+* console.log(result.isDSTTransition); // false (9 AM is safe)
+* ```
+*/
+var TimezoneHandler = class {
+	/**
+	* Calculate UTC execution time from user's local timezone intent
+	*
+	* @param scheduledFor - Local date/time as ISO string WITHOUT timezone (naive datetime)
+	*                       Format: "YYYY-MM-DDTHH:mm:ss" (e.g., "2024-03-10T09:00:00")
+	*                       
+	*                       This represents the LOCAL time in the target timezone.
+	*                       Do NOT include timezone offset (Z, +00:00, etc.)
+	* 
+	* @param timezone - IANA timezone name (e.g., "America/New_York", "Europe/London")
+	* @returns Calculation result with execution time and DST metadata
+	*
+	* @throws {Error} If timezone is invalid or scheduledFor format is invalid
+	*
+	* @example Basic Usage
+	* ```typescript
+	* // Schedule for 9:00 AM New York time
+	* const result = handler.calculateExecutionTime(
+	*   '2024-03-10T09:00:00',
+	*   'America/New_York'
+	* );
+	* console.log(result.executionTime); // UTC Date object for scheduler
+	* console.log(result.localTimeDisplay); // "2024-03-10 09:00:00 EDT"
+	* ```
+	*
+	* @example Spring Forward Edge Case (non-existent time)
+	* ```typescript
+	* const result = handler.calculateExecutionTime(
+	*   '2024-03-10T02:30:00', // 2:30 AM doesn't exist (DST springs forward)
+	*   'America/New_York'
+	* );
+	* // Result: Adjusted to 3:30 AM, isDSTTransition=true, dstNote explains adjustment
+	* ```
+	*
+	* @example Fall Back Edge Case (ambiguous time)
+	* ```typescript
+	* const result = handler.calculateExecutionTime(
+	*   '2024-11-03T01:30:00', // 1:30 AM occurs twice (DST falls back)
+	*   'America/New_York'
+	* );
+	* // Result: Uses first occurrence (DST), isDSTTransition=true, dstNote warns of ambiguity
+	* ```
+	*/
+	calculateExecutionTime(scheduledFor, timezone) {
+		if (!DateTime.local().setZone(timezone).isValid) throw new Error(`Invalid timezone: ${timezone}. Use IANA timezone names like "America/New_York"`);
+		let isoString;
+		if (scheduledFor instanceof Date) isoString = `${scheduledFor.getFullYear()}-${String(scheduledFor.getMonth() + 1).padStart(2, "0")}-${String(scheduledFor.getDate()).padStart(2, "0")}T${String(scheduledFor.getHours()).padStart(2, "0")}:${String(scheduledFor.getMinutes()).padStart(2, "0")}:${String(scheduledFor.getSeconds()).padStart(2, "0")}`;
+		else isoString = scheduledFor;
+		const dt = DateTime.fromISO(isoString, { zone: timezone });
+		if (!dt.isValid) throw new Error(`Invalid scheduledFor: "${scheduledFor}". Expected ISO format without timezone: "YYYY-MM-DDTHH:mm:ss" (e.g., "2024-03-10T09:00:00")`);
+		const year = dt.year;
+		const month = dt.month;
+		const day = dt.day;
+		const hour = dt.hour;
+		const minute = dt.minute;
+		const second = dt.second;
+		const dtInZone = DateTime.fromObject({
+			year,
+			month,
+			day,
+			hour,
+			minute,
+			second
+		}, { zone: timezone });
+		if (!dtInZone.isValid) {
+			const reason = dtInZone.invalidReason || "unknown";
+			const adjustedDt = DateTime.fromObject({
+				year,
+				month,
+				day,
+				hour: hour + 1,
+				minute,
+				second
+			}, { zone: timezone });
+			return {
+				executionTime: adjustedDt.toUTC().toJSDate(),
+				localTimeDisplay: adjustedDt.toFormat("yyyy-MM-dd HH:mm:ss ZZZZ"),
+				isDSTTransition: true,
+				dstNote: `Scheduled time ${hour}:${String(minute).padStart(2, "0")} does not exist due to DST spring forward. Adjusted to ${adjustedDt.hour}:${String(adjustedDt.minute).padStart(2, "0")}. Reason: ${reason}`
+			};
+		}
+		const oneHourLater = dtInZone.plus({ hours: 1 });
+		if (dtInZone.isInDST !== oneHourLater.isInDST && dtInZone.offset !== oneHourLater.offset) return {
+			executionTime: dtInZone.toUTC().toJSDate(),
+			localTimeDisplay: dtInZone.toFormat("yyyy-MM-dd HH:mm:ss ZZZZ"),
+			isDSTTransition: true,
+			dstNote: `Scheduled time ${hour}:${String(minute).padStart(2, "0")} is ambiguous due to DST fall back (occurs twice). Using first occurrence (${dtInZone.offsetNameShort}). Consider scheduling outside 1-2 AM window during fall transitions.`
+		};
+		return {
+			executionTime: dtInZone.toUTC().toJSDate(),
+			localTimeDisplay: dtInZone.toFormat("yyyy-MM-dd HH:mm:ss ZZZZ"),
+			isDSTTransition: false
+		};
+	}
+	/**
+	* Validate if a timezone is recognized by IANA database
+	*
+	* @param timezone - Timezone string to validate
+	* @returns true if valid, false otherwise
+	*
+	* @example
+	* ```typescript
+	* handler.isValidTimezone('America/New_York'); // true
+	* handler.isValidTimezone('EST'); // false (use IANA names)
+	* handler.isValidTimezone('Invalid/Zone'); // false
+	* ```
+	*/
+	isValidTimezone(timezone) {
+		try {
+			return DateTime.local().setZone(timezone).isValid;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Get current offset for a timezone (useful for debugging)
+	*
+	* @param timezone - IANA timezone name
+	* @returns Offset in minutes from UTC (e.g., -300 for EST)
+	*
+	* @example
+	* ```typescript
+	* handler.getCurrentOffset('America/New_York'); // -300 (EST) or -240 (EDT)
+	* ```
+	*/
+	getCurrentOffset(timezone) {
+		const dt = DateTime.local().setZone(timezone);
+		if (!dt.isValid) throw new Error(`Invalid timezone: ${timezone}`);
+		return dt.offset;
+	}
+	/**
+	* Check if a timezone is currently in DST
+	*
+	* @param timezone - IANA timezone name
+	* @returns true if currently observing DST, false otherwise
+	*
+	* @example
+	* ```typescript
+	* handler.isInDST('America/New_York'); // true in summer, false in winter
+	* ```
+	*/
+	isInDST(timezone) {
+		const dt = DateTime.local().setZone(timezone);
+		if (!dt.isValid) throw new Error(`Invalid timezone: ${timezone}`);
+		return dt.isInDST;
+	}
+};
+/**
+* Singleton instance for convenience
+* Use this for most cases unless you need custom configuration
+*/
+const timezoneHandler = new TimezoneHandler();
+
+//#endregion
+//#region src/scheduling/scheduling.service.ts
+/**
+* Scheduling Service - Facade for timezone-aware workflow scheduling
+*
+* Provides high-level API for scheduling workflows at specific times with full timezone support.
+* Handles DST transitions, recurrence patterns, and multi-tenant isolation.
+*
+* Design Philosophy:
+* - Simple API: One method to schedule, one to reschedule, one to cancel
+* - Smart Defaults: Sensible timezone handling with clear DST warnings
+* - Zero Surprises: Explicit about what time workflow will actually execute
+* - Resource Efficient: Uses keyset pagination for large-scale scheduling
+* - Unified Container: Uses the same container/repository for scheduling and execution
+*
+* @example Basic Scheduling
+* ```typescript
+* import { SchedulingService } from '@classytic/streamline/scheduling';
+* import { myWorkflow, myHandlers } from './workflows';
+*
+* const service = new SchedulingService(myWorkflow, myHandlers);
+*
+* // Schedule workflow for 9:00 AM New York time
+* const run = await service.schedule({
+*   scheduledFor: '2024-03-15T09:00:00',
+*   timezone: 'America/New_York',
+*   input: { task: 'Send morning email' }
+* });
+*
+* console.log(run.scheduling?.executionTime); // UTC time when scheduler will execute
+* console.log(run.scheduling?.localTimeDisplay); // "2024-03-15 09:00:00 EDT"
+* console.log(run.scheduling?.isDSTTransition); // false (9 AM is safe)
+* ```
+*
+* @example Multi-Tenant Scheduling
+* ```typescript
+* const service = new SchedulingService(workflow, handlers, {
+*   multiTenant: {
+*     tenantField: 'context.tenantId',
+*     strict: true
+*   }
+* });
+*
+* const run = await service.schedule({
+*   scheduledFor: '2024-12-25T10:00:00',
+*   timezone: 'America/Los_Angeles',
+*   input: { postContent: 'Happy Holidays!' },
+*   tenantId: 'client-123'
+* });
+* ```
+*/
+/**
+* SchedulingService - High-level API for timezone-aware workflow scheduling
+*
+* Combines WorkflowEngine, TimezoneHandler, and Repository for easy scheduling.
+* Handles all the complexity of timezone conversion, DST transitions, and scheduling.
+*
+* IMPORTANT: Uses a unified container for both scheduling and execution to ensure
+* consistent multi-tenant isolation and proper hook registration.
+*
+* @typeParam TContext - Workflow context type
+*/
+var SchedulingService = class {
+	engine;
+	workflow;
+	timezoneHandler;
+	/** Exposed for testing and advanced use cases */
+	container;
+	constructor(workflow, handlers, config = {}) {
+		this.workflow = workflow;
+		this.timezoneHandler = new TimezoneHandler();
+		if (config.container) if ("repository" in config.container && "eventBus" in config.container && "cache" in config.container) this.container = config.container;
+		else this.container = createContainer(config.container);
+		else if (config.multiTenant) this.container = createContainer({ repository: { multiTenant: config.multiTenant } });
+		else this.container = createContainer();
+		this.engine = new WorkflowEngine(workflow, handlers, this.container, { autoExecute: config.autoExecute !== false });
+	}
+	/** Get the repository (uses container's repository) */
+	get repository() {
+		return this.container.repository;
+	}
+	/**
+	* Convert Date to ISO string format (YYYY-MM-DDTHH:mm:ss)
+	* Uses local components to preserve the "naive" datetime interpretation
+	*/
+	convertDateToISOString(date) {
+		return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}T${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}:${String(date.getSeconds()).padStart(2, "0")}`;
+	}
+	/**
+	* Schedule a workflow for future execution at a specific timezone
+	*
+	* @param options - Scheduling options with timezone information
+	* @returns Created workflow run with scheduling metadata
+	* @throws {Error} If timezone is invalid or scheduling fails
+	*
+	* @example
+	* ```typescript
+	* const run = await service.schedule({
+	*   scheduledFor: '2024-06-15T14:30:00',
+	*   timezone: 'Europe/London',
+	*   input: { userId: '123', action: 'send-reminder' }
+	* });
+	*
+	* // Check if DST transition affected scheduling
+	* if (run.scheduling?.isDSTTransition) {
+	*   console.warn('DST Note:', run.scheduling.dstNote);
+	* }
+	* ```
+	*/
+	async schedule(options) {
+		const scheduledForString = options.scheduledFor instanceof Date ? this.convertDateToISOString(options.scheduledFor) : options.scheduledFor;
+		const timezoneResult = this.timezoneHandler.calculateExecutionTime(scheduledForString, options.timezone);
+		const now = /* @__PURE__ */ new Date();
+		if (timezoneResult.executionTime.getTime() < now.getTime() - SCHEDULING.PAST_SCHEDULE_GRACE_MS) {
+			const minutesInPast = Math.round((now.getTime() - timezoneResult.executionTime.getTime()) / 6e4);
+			logger.warn("Scheduling workflow in the past - will execute immediately", {
+				workflowId: this.workflow.id,
+				minutesInPast,
+				scheduledFor: timezoneResult.localTimeDisplay,
+				currentTime: now.toISOString()
+			});
+		}
+		const context = {
+			...this.workflow.createContext(options.input),
+			...options.tenantId && { tenantId: options.tenantId }
+		};
+		const steps = this.workflow.steps.map((step) => ({
+			stepId: step.id,
+			status: "pending",
+			attempts: 0
+		}));
+		const firstStepId = this.workflow.steps[0]?.id || null;
+		const workflowRunData = {
+			_id: randomUUID(),
+			workflowId: this.workflow.id,
+			status: "draft",
+			steps,
+			currentStepId: firstStepId,
+			context,
+			input: options.input,
+			createdAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date(),
+			scheduling: {
+				scheduledFor: scheduledForString,
+				timezone: options.timezone,
+				localTimeDisplay: timezoneResult.localTimeDisplay,
+				executionTime: timezoneResult.executionTime,
+				isDSTTransition: timezoneResult.isDSTTransition,
+				dstNote: timezoneResult.dstNote,
+				recurrence: options.recurrence
+			},
+			userId: options.userId,
+			tags: options.tags,
+			meta: options.meta
+		};
+		return await this.repository.create(workflowRunData);
+	}
+	/**
+	* Reschedule an existing workflow to a new time
+	*
+	* @param runId - Workflow run ID to reschedule
+	* @param newScheduledFor - New local date/time as ISO string (format: "YYYY-MM-DDTHH:mm:ss")
+	* @param newTimezone - Optional new timezone (if changing timezone)
+	* @returns Updated workflow run
+	* @throws {Error} If workflow not found or already executed
+	*
+	* @example Reschedule to different time (same timezone)
+	* ```typescript
+	* await service.reschedule(runId, '2024-06-16T15:00:00');
+	* ```
+	*
+	* @example Reschedule to different time AND timezone
+	* ```typescript
+	* await service.reschedule(
+	*   runId,
+	*   '2024-06-16T10:00:00',
+	*   'America/New_York'
+	* );
+	* ```
+	*/
+	async reschedule(runId, newScheduledFor, newTimezone) {
+		const run = await this.repository.getById(runId);
+		if (!run) throw new Error(`Workflow run ${runId} not found`);
+		if (run.status !== "draft") throw new Error(`Cannot reschedule workflow ${runId} with status ${run.status}. Only draft workflows can be rescheduled.`);
+		if (!run.scheduling) throw new Error(`Workflow run ${runId} is not a scheduled workflow`);
+		const timezone = newTimezone || run.scheduling.timezone;
+		const timezoneResult = this.timezoneHandler.calculateExecutionTime(newScheduledFor, timezone);
+		const updateData = {
+			scheduling: {
+				scheduledFor: newScheduledFor instanceof Date ? this.convertDateToISOString(newScheduledFor) : newScheduledFor,
+				timezone,
+				localTimeDisplay: timezoneResult.localTimeDisplay,
+				executionTime: timezoneResult.executionTime,
+				isDSTTransition: timezoneResult.isDSTTransition,
+				dstNote: timezoneResult.dstNote,
+				recurrence: run.scheduling.recurrence
+			},
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		return await this.repository.update(runId, updateData);
+	}
+	/**
+	* Cancel a scheduled workflow
+	*
+	* @param runId - Workflow run ID to cancel
+	* @returns Cancelled workflow run
+	* @throws {Error} If workflow not found or already executed
+	*
+	* @example
+	* ```typescript
+	* await service.cancelScheduled(runId);
+	* ```
+	*/
+	async cancelScheduled(runId) {
+		const run = await this.repository.getById(runId);
+		if (!run) throw new Error(`Workflow run ${runId} not found`);
+		if (run.status !== "draft") throw new Error(`Cannot cancel workflow ${runId} with status ${run.status}. Only draft workflows can be cancelled.`);
+		const cancelData = {
+			status: "cancelled",
+			updatedAt: /* @__PURE__ */ new Date(),
+			endedAt: /* @__PURE__ */ new Date()
+		};
+		return await this.repository.update(runId, cancelData);
+	}
+	/**
+	* Get scheduled workflows (with pagination)
+	*
+	* Supports both offset (page-based) and keyset (cursor-based) pagination.
+	* Use keyset pagination for large datasets (>10k workflows) for better performance.
+	*
+	* @param options - Query and pagination options
+	* @returns Paginated results with scheduled workflows
+	*
+	* @example Offset Pagination (Simple)
+	* ```typescript
+	* const result = await service.getScheduled({
+	*   page: 1,
+	*   limit: 50,
+	*   tenantId: 'client-123'
+	* });
+	*
+	* console.log(result.data); // Array of workflows
+	* console.log(result.hasNextPage); // true if more pages exist
+	* ```
+	*
+	* @example Keyset Pagination (Efficient for large datasets)
+	* ```typescript
+	* // First page
+	* const result = await service.getScheduled({
+	*   cursor: null,
+	*   limit: 1000
+	* });
+	*
+	* // Next page
+	* const nextResult = await service.getScheduled({
+	*   cursor: result.nextCursor,
+	*   limit: 1000
+	* });
+	* ```
+	*
+	* @example Filter by execution time range
+	* ```typescript
+	* const result = await service.getScheduled({
+	*   executionTimeRange: {
+	*     from: new Date('2024-06-01'),
+	*     to: new Date('2024-06-30')
+	*   },
+	*   limit: 100
+	* });
+	* ```
+	*/
+	async getScheduled(options = {}) {
+		const { page = 1, limit = 100, cursor, tenantId, executionTimeRange, recurring } = options;
+		const filters = {
+			status: "draft",
+			"scheduling.executionTime": { $exists: true },
+			paused: { $ne: true }
+		};
+		if (executionTimeRange) filters["scheduling.executionTime"] = {
+			$gte: executionTimeRange.from,
+			$lte: executionTimeRange.to
+		};
+		if (recurring !== void 0) if (recurring) filters["scheduling.recurrence"] = { $exists: true };
+		else filters["scheduling.recurrence"] = { $exists: false };
+		return await this.repository.getAll({
+			filters,
+			sort: { "scheduling.executionTime": 1 },
+			page,
+			limit,
+			cursor: cursor ?? void 0,
+			...tenantId && { tenantId }
+		});
+	}
+	/**
+	* Get workflow run by ID
+	*
+	* @param runId - Workflow run ID
+	* @returns Workflow run or null if not found
+	*/
+	async get(runId) {
+		try {
+			return await this.repository.getById(runId);
+		} catch (error) {
+			const err = error;
+			if (err.status === 404 || err.message?.includes("not found")) return null;
+			throw error;
+		}
+	}
+	/**
+	* Execute a scheduled workflow immediately (bypass schedule)
+	*
+	* @param runId - Workflow run ID to execute
+	* @returns Executed workflow run
+	* @throws {Error} If workflow not found or not in draft status
+	*
+	* @example
+	* ```typescript
+	* // Execute a scheduled workflow now instead of waiting for execution time
+	* const run = await service.executeNow(runId);
+	* ```
+	*/
+	async executeNow(runId) {
+		const run = await this.repository.getById(runId);
+		if (!run) throw new Error(`Workflow run ${runId} not found`);
+		if (run.status !== "draft") throw new Error(`Cannot execute workflow ${runId} with status ${run.status}. Only draft workflows can be executed.`);
+		const updateData = {
+			status: "running",
+			startedAt: /* @__PURE__ */ new Date(),
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+		await this.repository.update(runId, updateData);
+		hookRegistry.register(runId, this.engine);
+		return await this.engine.execute(runId);
+	}
+};
+
+//#endregion
+//#region src/features/parallel.ts
+async function executeWithConcurrency(tasks, concurrency) {
+	const results = new Array(tasks.length);
+	const errors = [];
+	const executing = /* @__PURE__ */ new Set();
+	for (let i = 0; i < tasks.length; i++) {
+		const index = i;
+		const promise = tasks[index]().then((result) => {
+			results[index] = result;
+		}).catch((error) => {
+			errors.push({
+				index,
+				error
+			});
+		}).finally(() => {
+			executing.delete(promise);
+		});
+		executing.add(promise);
+		if (executing.size >= concurrency) await Promise.race(executing);
+	}
+	await Promise.all(executing);
+	if (errors.length > 0) {
+		errors.sort((a, b) => a.index - b.index);
+		throw errors[0].error;
+	}
+	return results;
+}
+async function executeWithConcurrencySettled(tasks, concurrency) {
+	const results = new Array(tasks.length);
+	const executing = /* @__PURE__ */ new Set();
+	for (let i = 0; i < tasks.length; i++) {
+		const index = i;
+		const promise = tasks[index]().then((value) => {
+			results[index] = {
+				success: true,
+				value
+			};
+		}).catch((reason) => {
+			results[index] = {
+				success: false,
+				reason
+			};
+		}).finally(() => {
+			executing.delete(promise);
+		});
+		executing.add(promise);
+		if (executing.size >= concurrency) await Promise.race(executing);
+	}
+	await Promise.all(executing);
+	return results;
+}
+/**
+* Execute multiple async tasks in parallel with configurable mode,
+* concurrency limits, and timeouts.
+*
+* @param tasks - Array of async task functions to execute
+* @param options - Execution options (mode, concurrency, timeout)
+* @returns Array of results (exact type depends on mode)
+*
+* @example Basic parallel execution
+* ```typescript
+* const results = await executeParallel([
+*   () => fetch('/api/users'),
+*   () => fetch('/api/posts'),
+*   () => fetch('/api/comments'),
+* ]);
+* ```
+*
+* @example With concurrency limit
+* ```typescript
+* // Only 2 requests at a time
+* const results = await executeParallel(urlTasks, { concurrency: 2 });
+* ```
+*
+* @example With allSettled mode (never throws)
+* ```typescript
+* const results = await executeParallel(tasks, { mode: 'allSettled' });
+* for (const result of results) {
+*   if (result.success) {
+*     console.log('Success:', result.value);
+*   } else {
+*     console.log('Failed:', result.reason);
+*   }
+* }
+* ```
+*/
+async function executeParallel(tasks, options = {}) {
+	const { mode = "all", concurrency = Infinity, timeout } = options;
+	const wrappedTasks = timeout ? tasks.map((task) => () => Promise.race([task(), new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`Task timeout after ${timeout}ms`)), timeout))])) : tasks;
+	if (concurrency !== Infinity && (mode === "race" || mode === "any")) throw new Error(`executeParallel: mode '${mode}' cannot be combined with concurrency limiting. The '${mode}' mode requires all tasks to start simultaneously to determine the winner. Either remove the concurrency limit or use mode 'all' or 'allSettled'.`);
+	if (concurrency !== Infinity) switch (mode) {
+		case "allSettled": return executeWithConcurrencySettled(wrappedTasks, concurrency);
+		default: return executeWithConcurrency(wrappedTasks, concurrency);
+	}
+	switch (mode) {
+		case "all": return Promise.all(wrappedTasks.map((t) => t()));
+		case "race": return [await Promise.race(wrappedTasks.map((t) => t()))];
+		case "any": return Promise.any(wrappedTasks.map((t) => t())).then((result) => [result]);
+		case "allSettled": return (await Promise.allSettled(wrappedTasks.map((t) => t()))).map((result) => result.status === "fulfilled" ? {
+			success: true,
+			value: result.value
+		} : {
+			success: false,
+			reason: result.reason
+		});
+		default: return Promise.all(wrappedTasks.map((t) => t()));
+	}
+}
+
+//#endregion
+export { COMPUTED, CommonQueries, DataCorruptionError, ErrorCode, InvalidStateError, MaxRetriesExceededError, RUN_STATUS, RUN_STATUS_VALUES, STEP_STATUS, STEP_STATUS_VALUES, SchedulingService, StepNotFoundError, StepTimeoutError, TimezoneHandler, WaitSignal, WorkflowCache, WorkflowDefinitionModel, WorkflowEngine, WorkflowError, WorkflowEventBus, WorkflowNotFoundError, WorkflowQueryBuilder, WorkflowRunModel, canRewindTo, conditions, createCondition, createContainer, createHook, createWorkflow, createWorkflowRepository, deriveRunStatus, executeParallel, getExecutionPath, getStepTimeline, getStepUIStates, getWaitingInfo, getWorkflowProgress, globalEventBus, hookRegistry, hookToken, isConditionalStep, isRunStatus, isStepStatus, isStreamlineContainer, isTerminalState, isValidRunTransition, isValidStepTransition, resumeHook, shouldSkipStep, singleTenantPlugin, tenantFilterPlugin, timezoneHandler, workflowDefinitionRepository, workflowRunRepository };