inngest/components/InngestMetadata.d.ts

Official SDK for Inngest.com. Inngest is the reliability layer for modern applications. Inngest combines durable execution, events, and queues into a zero-infra platform with built-in observability.

import { MaybePromise, Simplify } from "../helpers/types.js";
import { Middleware } from "./middleware/middleware.js";
import { ExperimentalStepTools } from "./InngestStepTools.js";
import { SendEventBaseOutput } from "../types.js";
import { Inngest } from "./Inngest.js";

//#region src/components/InngestMetadata.d.ts

/**
 * The level at which to attach the metadata.
 */
type MetadataScope = "run" | "step" | "step_attempt" | "extended_trace";
/**
 * Metadata of the same kind attached to the same item at the same scope are combined.
 */
type MetadataKind = "inngest.experiment" | "inngest.warnings" | `userland.${string}`;
/**
 * The operation use to combine multiple metadata updates of the same kind.
 */
type MetadataOpcode = "merge";
/**
 * A metadata update containing `values` to be merged according to `op`
 * at the configured `scope` for the configured `kind`.
 */
type MetadataUpdate = {
  kind: MetadataKind;
  scope: MetadataScope;
  op: MetadataOpcode;
  values: MetadataValues;
};
type MetadataValues = Record<string, unknown>;
/**
 * Configures and sends metadata updates.
 *
 * This is used to limit the available methods as target is
 * configured and the specified scope narrows.
 */
type MetadataBuilder<Extras = {}> = Simplify<{
  /**
   * Sets the metadata context to a specific (or current if omitted) run.
   */
  run(id?: string): Simplify<Omit<MetadataBuilder<Extras>, "run">>;
  /**
   * Sets the metadata context to a specific (or current if omitted) step.
   */
  step(id?: string, index?: number): Simplify<Omit<MetadataBuilder<Extras>, "run" | "step">>;
  /**
   * Sets the metadata context to a specific (or current if omitted) step attempt.
   */
  attempt(index?: number): Simplify<Omit<MetadataBuilder<Extras>, "run" | "step" | "attempt">>;
  /**
   * Sets the metadata context to a specific span.
   */
  span(id: string): Simplify<Omit<MetadataBuilder<Extras>, "run" | "step" | "attempt" | "span">>;
  /**
   * Attach metadata to the configured run/step/step attempt/span.
   *
   * By default it will attach metadata to the current run if
   * executed inside the body of `createFunction` or to the
   * current step attempt if executed inside `step.run`.
   */
  update(values: Record<string, unknown>, kind?: string): Promise<void>;
} & Extras>;
/**
 * A wrapper around `MetadataBuilder` to attach metadata as a step.
 */
type MetadataStepTool = MetadataBuilder<{
  /**
   * Allows many `updates` to be sent with the same scope.
   */
  do: (fn: (builder: MetadataBuilder) => Promise<void>) => Promise<void>;
}>;
declare const metadataSymbol: unique symbol;
/**
 * Middleware that enables the experimental step.metadata() feature.
 *
 * @example
 * ```ts
 * import { metadataMiddleware } from "inngest/experimental";
 *
 * const inngest = new Inngest({
 *   id: "my-app",
 *   middleware: [metadataMiddleware()],
 * });
 * ```
 */
declare const metadataMiddleware: () => {
  new ({
    client
  }: {
    client: Inngest.Any;
  }): {
    readonly id: "inngest:metadata";
    transformFunctionInput(arg: Middleware.TransformFunctionInputArgs): Middleware.TransformFunctionInputArgs & {
      ctx: {
        step: {
          /**
           * Create a durable metadata update wrapped in a step
           *
           * @param memoizationId - The step ID used for the step itself, ensuring the
           *   metadata update is only performed once even on function retries.
           *
           * @example
           * ```ts
           * // Update metadata for the current run
           * await step.metadata("update-status").update({ status: "processing" });
           *
           * // Update metadata for a different run
           * await step.metadata("notify-parent")
           *   .run(parentRunId)
           *   .update({ childCompleted: true });
           * ```
           */
          metadata: ExperimentalStepTools[typeof metadataSymbol];
        };
      };
    };
    readonly client: Inngest.Any;
    functionOutputTransform: Middleware.DefaultStaticTransform;
    stepOutputTransform: Middleware.DefaultStaticTransform;
    onMemoizationEnd?(arg: Middleware.OnMemoizationEndArgs): MaybePromise<void>;
    onRunComplete?(arg: Middleware.OnRunCompleteArgs): MaybePromise<void>;
    onRunError?(arg: Middleware.OnRunErrorArgs): MaybePromise<void>;
    onRunStart?(arg: Middleware.OnRunStartArgs): MaybePromise<void>;
    onStepComplete?(arg: Middleware.OnStepCompleteArgs): MaybePromise<void>;
    onStepError?(arg: Middleware.OnStepErrorArgs): MaybePromise<void>;
    onStepStart?(arg: Middleware.OnStepStartArgs): MaybePromise<void>;
    transformSendEvent?(arg: Middleware.TransformSendEventArgs): MaybePromise<Middleware.TransformSendEventArgs>;
    transformStepInput?(arg: Middleware.TransformStepInputArgs): MaybePromise<Middleware.TransformStepInputArgs>;
    wrapFunctionHandler?(args: Middleware.WrapFunctionHandlerArgs): Promise<unknown>;
    wrapRequest?(args: Middleware.WrapRequestArgs): Promise<Middleware.Response>;
    wrapSendEvent?(args: Middleware.WrapSendEventArgs): Promise<SendEventBaseOutput>;
    wrapStep?(args: Middleware.WrapStepArgs): Promise<unknown>;
    wrapStepHandler?(args: Middleware.WrapStepHandlerArgs): Promise<unknown>;
  };
  onRegister({
    client
  }: Middleware.OnRegisterArgs): void;
};
//#endregion
export { MetadataBuilder, MetadataKind, MetadataOpcode, MetadataScope, MetadataStepTool, MetadataUpdate, metadataMiddleware, metadataSymbol };
//# sourceMappingURL=InngestMetadata.d.ts.map