inngest 4.3.0 → 4.4.0

package/components/execution/engine.cjs

@@ -7,6 +7,7 @@ const require_types = require('../../types.cjs');
 const require_InngestExecution = require('./InngestExecution.cjs');
 const require_types$1 = require('../../helpers/types.cjs');
 const require_functions = require('../../helpers/functions.cjs');
+const require_marker = require('../../helpers/marker.cjs');
 const require_temporal = require('../../helpers/temporal.cjs');
 const require_promises = require('../../helpers/promises.cjs');
 const require_als = require('./als.cjs');
@@ -20,6 +21,7 @@ const require_StepError = require('../StepError.cjs');
 const require_streaming = require('./streaming.cjs');
 const require_StreamTools = require('../StreamTools.cjs');
 const require_utils$1 = require('../triggers/utils.cjs');
+const require_lazyOps = require('./lazyOps.cjs');
 const require_access = require('./otel/access.cjs');
 let zod_v3 = require("zod/v3");
 let hash_js = require("hash.js");
@@ -260,6 +262,8 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		throw new Error("Core loop finished without returning a value");
 	}
 	async checkpoint(steps) {
+		const lazyOps = this.state.lazyOps.drain();
+		if (lazyOps.length > 0) steps = [...steps, ...lazyOps];
 		if (this.options.stepMode === require_types.StepMode.Sync) if (!this.state.checkpointedRun) {
 			const res = await require_promises.retryWithBackoff(() => this.options.client["inngestApi"].checkpointNewRun({
 				runId: this.fnArg.runId,
@@ -517,12 +521,13 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 			return transformResult;
 		};
 		const maybeReturnNewSteps = async () => {
-			const newSteps = await this.filterNewSteps(Array.from(this.state.steps.values()));
-			if (newSteps) return {
+			const allSteps = [...await this.filterNewSteps(Array.from(this.state.steps.values())) ?? [], ...this.state.lazyOps.drain()];
+			if (allSteps.length === 0) return;
+			return {
 				type: "steps-found",
 				ctx: this.fnArg,
 				ops: this.ops,
-				steps: newSteps
+				steps: allSteps
 			};
 		};
 		const attemptCheckpointAndResume = async (stepResult, resume = true, force = false) => {
@@ -668,23 +673,36 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 					sseResponse = extractSseResponse(data, body);
 					resultData = body;
 				} else sseResponse = defaultSseResponse(resultData);
-				const newStepsResult = await maybeReturnNewSteps();
-				if (newStepsResult) return newStepsResult;
+				const newSteps = await this.filterNewSteps(Array.from(this.state.steps.values()));
+				if (newSteps?.length) return this.attachLazyOps({
+					type: "steps-found",
+					ctx: this.fnArg,
+					ops: this.ops,
+					steps: newSteps
+				});
 				await this.streamCloseSucceeded(sseResponse);
 				if (!this.streamTools.activated) this.postCheckpointStream();
 				if (this.options.createResponse) data = await this.options.createResponse(jsonResponse(resultData));
-				return this.transformOutput({ data });
+				return this.attachLazyOps(this.transformOutput({ data }));
 			},
 			"function-rejected": async (checkpoint) => {
 				if (!this.retriability(checkpoint.error)) await this.streamCloseFailed(errorMessage(checkpoint.error));
 				else await this.streamEnd();
 				if (!this.streamTools.activated) this.postCheckpointStream();
-				return this.transformOutput({ error: checkpoint.error });
+				return this.attachLazyOps(this.transformOutput({ error: checkpoint.error }));
 			},
 			"steps-found": async ({ steps }) => {
 				const stepResult = await this.tryExecuteStep(steps);
-				if (stepResult) return stepRanHandler(stepResult);
-				return maybeReturnNewSteps();
+				if (!stepResult) return maybeReturnNewSteps();
+				if (this.state.lazyOps.length === 0) return stepRanHandler(stepResult);
+				const transformed = await stepRanHandler(stepResult);
+				if (transformed.type !== "step-ran") return transformed;
+				return this.attachLazyOps({
+					type: "steps-found",
+					ctx: transformed.ctx,
+					ops: transformed.ops,
+					steps: [transformed.step]
+				});
 			},
 			"step-not-found": ({ step }) => {
 				const { foundSteps, totalFoundSteps } = this.getStepNotFoundDetails();
@@ -707,13 +725,18 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		const asyncCheckpointingHandlers = {
 			"": commonCheckpointHandler,
 			"function-resolved": async (checkpoint, i) => {
+				const lazyOps = this.state.lazyOps.drain();
 				const output = await asyncHandlers["function-resolved"](checkpoint, i);
 				if (output?.type === "function-resolved") {
-					const steps = this.state.checkpointingStepBuffer.concat({
-						op: require_types.StepOpCode.RunComplete,
-						id: hashId(RUN_COMPLETE_STEP_ID),
-						data: output.data
-					});
+					const steps = [
+						...this.state.checkpointingStepBuffer,
+						...lazyOps,
+						{
+							op: require_types.StepOpCode.RunComplete,
+							id: hashId(RUN_COMPLETE_STEP_ID),
+							data: output.data
+						}
+					];
 					if (isNonEmpty(steps)) return {
 						type: "steps-found",
 						ctx: output.ctx,
@@ -721,9 +744,14 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 						steps
 					};
 				}
+				if (output?.type === "steps-found" && lazyOps.length) return {
+					...output,
+					steps: [...output.steps, ...lazyOps]
+				};
+				return output;
 			},
 			"function-rejected": async (checkpoint) => {
-				if (this.state.checkpointingStepBuffer.length) {
+				if (this.state.checkpointingStepBuffer.length || this.state.lazyOps.length > 0) {
 					const fallback = await attemptCheckpointAndResume(void 0, false, true);
 					if (fallback) return fallback;
 				}
@@ -968,7 +996,11 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 	* Validate event data against schemas defined in function triggers.
 	*/
 	async validateEventSchemas() {
-		if (this.options.isFailureHandler) return;
+		if (this.options.handlerKind === "failure") return;
+		if (this.options.handlerKind === "defer") {
+			await this.validateDeferEventSchema();
+			return;
+		}
 		const triggers = this.options.fn.opts.triggers;
 		if (!triggers || triggers.length === 0) return;
 		const fnArgEvents = this.fnArg.events;
@@ -979,6 +1011,17 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		})), triggers);
 	}
 	/**
+	* Validate the deferred event's data against the defer function's own
+	* schema (set via `createDefer`'s `opts.schema`).
+	*/
+	async validateDeferEventSchema() {
+		const fn = this.options.fn;
+		if (!require_marker.isDeferredFunction(fn) || !fn.schema) return;
+		const eventData = this.fnArg.event?.data;
+		const result = await fn.schema["~standard"].validate(eventData);
+		if (result.issues) throw new require_NonRetriableError.NonRetriableError(`defer handler "${fn.id(this.options.client.id)}" schema validation failed: ${JSON.stringify(result.issues)}`);
+	}
+	/**
 	* Using middleware, transform output before returning.
 	*/
 	transformOutput(dataOrError) {
@@ -1001,6 +1044,64 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 			data: require_functions.undefinedToNull(data)
 		};
 	}
+	/**
+	* Drain buffered lazy ops (e.g. `DeferAdd` from `defer()`) and merge them
+	* into `result` so they ship in the same outbound message. Lazy ops are
+	* fire-and-forget and have no natural shipping moment, so each terminal code
+	* path must ship them or they're silently dropped.
+	*/
+	attachLazyOps(result, extras = []) {
+		const lazyOps = this.state.lazyOps.drain();
+		if (lazyOps.length === 0 && extras.length === 0) return result;
+		switch (result.type) {
+			case "function-resolved": {
+				const steps = [
+					...extras,
+					...lazyOps,
+					{
+						op: require_types.StepOpCode.RunComplete,
+						id: hashId(RUN_COMPLETE_STEP_ID),
+						data: require_functions.undefinedToNull(result.data)
+					}
+				];
+				return {
+					type: "steps-found",
+					ctx: result.ctx,
+					ops: result.ops,
+					steps
+				};
+			}
+			case "function-rejected": {
+				const isFinal = result.retriable === false;
+				const steps = [
+					...extras,
+					...lazyOps,
+					{
+						op: isFinal ? require_types.StepOpCode.StepFailed : require_types.StepOpCode.StepError,
+						id: hashId(RUN_COMPLETE_STEP_ID),
+						error: result.error
+					}
+				];
+				return {
+					type: "steps-found",
+					ctx: result.ctx,
+					ops: result.ops,
+					steps
+				};
+			}
+			case "steps-found": return {
+				...result,
+				steps: [
+					...result.steps,
+					...extras,
+					...lazyOps
+				]
+			};
+			default:
+				for (const op of lazyOps) this.state.lazyOps.push(op);
+				return result;
+		}
+	}
 	createExecutionState() {
 		const d = require_promises.createDeferredPromiseWithStack();
 		let checkpointResolve = d.deferred.resolve;
@@ -1023,6 +1124,7 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		const stepsToFulfill = Object.keys(this.options.stepState).length;
 		return {
 			stepState: this.options.stepState,
+			priorDefers: this.options.priorDefers ?? {},
 			stepsToFulfill,
 			steps: /* @__PURE__ */ new Map(),
 			loop,
@@ -1037,6 +1139,7 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 				return this.state.remainingStepsToBeSeen.size === 0;
 			},
 			checkpointingStepBuffer: [],
+			lazyOps: new require_lazyOps.LazyOps(),
 			metadata: /* @__PURE__ */ new Map()
 		};
 	}
@@ -1044,17 +1147,22 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		return Object.fromEntries(this.state.steps);
 	}
 	createFnArg() {
-		const step = this.createStepTools();
+		const { step, defer } = this.createStepTools();
 		const experimentStepRun = step[require_InngestStepTools.experimentStepRunSymbol];
 		let fnArg = {
 			...this.options.data,
 			step,
-			group: require_InngestGroupTools.createGroupTools({ experimentStepRun })
+			group: require_InngestGroupTools.createGroupTools({ experimentStepRun }),
+			defer
 		};
+		if (this.options.handlerKind === "defer") {
+			delete fnArg.event.data._inngest;
+			for (const event of fnArg.events) delete event.data._inngest;
+		}
 		/**
 		* Handle use of the `onFailure` option by deserializing the error.
 		*/
-		if (this.options.isFailureHandler) {
+		if (this.options.handlerKind === "failure") {
 			const eventData = zod_v3.z.object({ error: require_types.jsonErrorSchema }).parse(fnArg.event?.data);
 			fnArg = {
 				...fnArg,
@@ -1183,6 +1291,30 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		};
 		const stepHandler = async ({ args, matchOp, opts }) => {
 			const opId = matchOp(require_InngestStepTools.getStepOptions(args[0]), ...args.slice(1));
+			if (require_lazyOps.isLazyOp(opts, opId)) {
+				const hashedId$1 = _internals.hashId(opId.id);
+				if (this.state.lazyOps.hasId(hashedId$1)) {
+					this.options.client[require_Inngest.internalLoggerSymbol].warn({
+						runId: this.fnArg.runId,
+						id: opId.userland?.id ?? opId.id
+					}, "defer skipped: duplicate ID within run");
+					return;
+				}
+				if (this.state.priorDefers[hashedId$1]) {
+					this.state.lazyOps.markSeen(hashedId$1);
+					return;
+				}
+				this.state.lazyOps.push({
+					id: hashedId$1,
+					op: opId.op,
+					name: opId.name,
+					displayName: opId.displayName ?? opId.id,
+					opts: opId.opts,
+					userland: opId.userland,
+					data: null
+				});
+				return;
+			}
 			if (this.state.executingStep)
  /**
 			* If a step is found after asynchronous actions during another step's
@@ -1304,7 +1436,75 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 			} else pushStepToReport(step);
 			return promise;
 		};
-		return require_InngestStepTools.createStepTools(this.options.client, this, stepHandler);
+		return {
+			step: require_InngestStepTools.createStepTools(this.options.client, this, stepHandler),
+			defer: this.buildDefer(stepHandler)
+		};
+	}
+	/**
+	* Build the `defer(idOrOptions, { function, data })` method exposed on
+	* every handler context. Validates `data` against the target function's
+	* schema (if any) and emits a `DeferAdd` opcode that routes to the
+	* target's companion function slug.
+	*
+	* `defer()` is fire-and-forget: a misuse should not derail the user's
+	* handler. Validation failures (wrong function, async schema validator,
+	* schema mismatch) are logged and the call is silently skipped.
+	*/
+	buildDefer(stepHandler) {
+		return (idOrOptions, { function: deferFn, data }) => {
+			const log = this.options.client[require_Inngest.internalLoggerSymbol];
+			const runId = this.fnArg.runId;
+			try {
+				if (!require_marker.isDeferredFunction(deferFn)) {
+					log.error({ runId }, "defer skipped: function not created via createDefer");
+					return;
+				}
+				const { schema } = deferFn;
+				const deferFnSlug = deferFn.id(this.options.client.id);
+				let input = data;
+				if (schema) {
+					const result = schema["~standard"].validate(data);
+					if (result instanceof Promise) {
+						log.error({ runId }, "defer() requires a synchronous schema validator. The defer call was skipped.");
+						return;
+					}
+					if (result.issues) {
+						log.error({
+							runId,
+							issues: result.issues
+						}, "defer skipped: schema validation failed");
+						return;
+					}
+					input = result.value ?? data;
+				}
+				stepHandler({
+					args: [idOrOptions, input],
+					matchOp: (stepOptions, inputArg) => ({
+						id: stepOptions.id,
+						mode: require_types.StepMode.Sync,
+						op: require_types.StepOpCode.DeferAdd,
+						name: stepOptions.name ?? stepOptions.id,
+						displayName: stepOptions.name ?? stepOptions.id,
+						opts: {
+							fn_slug: deferFnSlug,
+							input: inputArg
+						},
+						userland: { id: stepOptions.id }
+					})
+				}).catch((err) => {
+					log.error({
+						runId,
+						err
+					}, "defer skipped: unexpected error");
+				});
+			} catch (err) {
+				log.error({
+					runId,
+					err
+				}, "defer skipped: unexpected error");
+			}
+		};
 	}
 	/**
 	* Applies middleware transformations to a step, resolves ID collisions,
@@ -1386,14 +1586,19 @@ var InngestExecutionEngine = class extends require_InngestExecution.InngestExecu
 		return userlandStep;
 	}
 	getUserFnToRun() {
-		if (!this.options.isFailureHandler) return this.options.fn["fn"];
-		if (!this.options.fn["onFailureFn"])
+		switch (this.options.handlerKind) {
+			case "defer": return this.options.fn["fn"];
+			case "failure":
+				if (!this.options.fn["onFailureFn"])
  /**
-		* Somehow, we've ended up detecting that this is a failure handler but
-		* doesn't have an `onFailure` function. This should never happen.
-		*/
-		throw new Error("Cannot find function `onFailure` handler");
-		return this.options.fn["onFailureFn"];
+				* Somehow, we've ended up detecting that this is a failure handler
+				* but doesn't have an `onFailure` function. This should never
+				* happen.
+				*/
+				throw new Error("Cannot find function `onFailure` handler");
+				return this.options.fn["onFailureFn"];
+			default: return this.options.fn["fn"];
+		}
 	}
 	initializeTimer(state) {
 		if (!this.options.requestedRunStep) return;