effect-inngest 0.1.0

package/dist/Function.d.ts

@@ -0,0 +1,384 @@
+import { Duration, Schema } from "effect";
+
+//#region src/Function.d.ts
+declare namespace Function_d_exports {
+  export { CronTrigger, EventTrigger, FunctionOptions, InngestFunction, Trigger, TriggerInput, TypeId, make };
+}
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+declare const TypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+type TypeId = typeof TypeId;
+type EventSchema = Schema.Schema.Any & {
+  readonly _tag: string;
+};
+/**
+ * An event-based trigger configuration.
+ *
+ * @since 0.1.0
+ * @category triggers
+ */
+interface EventTrigger<E extends EventSchema = EventSchema> {
+  readonly event: E;
+  readonly if?: string;
+}
+/**
+ * A cron-based trigger configuration.
+ *
+ * @since 0.1.0
+ * @category triggers
+ */
+interface CronTrigger {
+  readonly cron: string;
+}
+/**
+ * A trigger configuration for a function.
+ *
+ * @since 0.1.0
+ * @category triggers
+ */
+type Trigger<E extends EventSchema = EventSchema> = EventTrigger<E> | CronTrigger;
+/**
+ * @since 0.1.0
+ * @category triggers
+ */
+type TriggerInput<E extends EventSchema = EventSchema> = Trigger<E> | ReadonlyArray<Trigger<E>>;
+interface ConcurrencyOption {
+  /**
+   * The concurrency limit for this option, adding a limit on how many concurrent
+   * steps can execute at once.
+   */
+  readonly limit: number;
+  /**
+   * An optional concurrency key, as an expression using the common expression language
+   * (CEL). The result of this expression is used to create new concurrency groups, or
+   * sub-queues, for each function run.
+   *
+   * The event is passed into this expression as "event".
+   *
+   * Examples:
+   * - `event.data.user_id`: this evaluates to the user_id in the event.data object.
+   * - `event.data.user_id + "-" + event.data.account_id`: creates a new group per user/account
+   * - `"ai"`: references a custom string
+   */
+  readonly key?: string;
+  /**
+   * An optional scope for the concurrency group. By default, concurrency limits are
+   * scoped to functions - one function's concurrency limits do not impact other functions.
+   *
+   * Changing this "scope" allows concurrency limits to work across environments (eg. production
+   * vs branch environments) or across your account (global).
+   */
+  readonly scope?: "fn" | "env" | "account";
+}
+interface RateLimitOption {
+  /**
+   * An optional key to use for rate limiting, similar to idempotency.
+   */
+  readonly key?: string;
+  /**
+   * The number of times to allow the function to run per the given `period`.
+   */
+  readonly limit: number;
+  /**
+   * The period of time to allow the function to run `limit` times.
+   */
+  readonly period: Duration.DurationInput;
+}
+interface ThrottleOption {
+  /**
+   * An optional expression which returns a throttling key for controlling throttling.
+   * Every unique key is its own throttle limit. Event data may be used within this
+   * expression, eg "event.data.user_id".
+   */
+  readonly key?: string;
+  /**
+   * The total number of runs allowed to start within the given `period`. The limit is
+   * applied evenly over the period.
+   */
+  readonly limit: number;
+  /**
+   * The period of time for the rate limit. Run starts are evenly spaced through
+   * the given period. The minimum granularity is 1 second.
+   */
+  readonly period: Duration.DurationInput;
+  /**
+   * The number of runs allowed to start in the given window in a single burst.
+   * A burst > 1 bypasses smoothing for the burst and allows many runs to start
+   * at once, if desired. Defaults to 1, which disables bursting.
+   */
+  readonly burst?: number;
+}
+interface DebounceOption {
+  /**
+   * An optional key to use for debouncing.
+   */
+  readonly key?: string;
+  /**
+   * The period of time to delay after receiving the last trigger to run the function.
+   */
+  readonly period: Duration.DurationInput;
+  /**
+   * The maximum time that a debounce can be extended before running.
+   * If events are continually received within the given period, a function
+   * will always run after the given timeout period.
+   */
+  readonly timeout?: Duration.DurationInput;
+}
+interface BatchEventsOption {
+  /**
+   * The maximum number of events to be consumed in one batch.
+   */
+  readonly maxSize: number;
+  /**
+   * How long to wait before invoking the function with a list of events.
+   * If timeout is reached, the function will be invoked with a batch
+   * even if it's not filled up to `maxSize`.
+   */
+  readonly timeout: Duration.DurationInput;
+  /**
+   * An optional key to use for batching.
+   */
+  readonly key?: string;
+  /**
+   * An optional boolean expression to determine an event's eligibility for batching.
+   */
+  readonly if?: string;
+}
+interface PriorityOption {
+  /**
+   * An expression to use to determine the priority of a function run. The
+   * expression can return a number between `-600` and `600`, where `600`
+   * declares that this run should be executed before any others enqueued in
+   * the last 600 seconds (10 minutes), and `-600` declares that this run
+   * should be executed after any others enqueued in the last 600 seconds.
+   */
+  readonly run?: string;
+}
+interface TimeoutsOption {
+  /**
+   * Start represents the timeout for starting a function. If the time
+   * between scheduling and starting a function exceeds this value, the
+   * function will be cancelled.
+   *
+   * This is, essentially, the amount of time that a function sits in the
+   * queue before starting.
+   */
+  readonly start?: Duration.DurationInput;
+  /**
+   * Finish represents the time between a function starting and the function
+   * finishing. If a function takes longer than this time to finish, the
+   * function is marked as cancelled.
+   */
+  readonly finish?: Duration.DurationInput;
+}
+interface SingletonOption {
+  /**
+   * An optional key expression used to scope singleton execution.
+   * Each unique key has its own singleton lock. Event data can be referenced,
+   * e.g. "event.data.user_id".
+   */
+  readonly key?: string;
+  /**
+   * Determines how to handle new runs when one is already active for the same key.
+   * - `"skip"` skips the new run.
+   * - `"cancel"` cancels the existing run and starts the new one.
+   */
+  readonly mode: "skip" | "cancel";
+}
+interface CancellationOption {
+  /**
+   * The name of the event that should cancel the function run.
+   */
+  readonly event: string;
+  /**
+   * The expression that must evaluate to true in order to cancel the function run. There
+   * are two variables available in this expression:
+   * - event, referencing the original function's event trigger
+   * - async, referencing the new cancel event.
+   */
+  readonly if?: string;
+  /**
+   * An optional timeout that the cancel is valid for. If this isn't
+   * specified, cancellation triggers are valid for up to a year or until the
+   * function ends.
+   */
+  readonly timeout?: Duration.DurationInput;
+}
+type Retries = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+interface FunctionOptions {
+  /**
+   * A name for the function as it will appear in the Inngest Cloud UI.
+   */
+  readonly name?: string;
+  /**
+   * A description of the function.
+   */
+  readonly description?: string;
+  /**
+   * Specifies the maximum number of retries for all steps across this function.
+   * Can be a number from `0` to `20`. Defaults to `3`.
+   */
+  readonly retries?: Retries;
+  /**
+   * Concurrency specifies a limit on the total number of concurrent steps that
+   * can occur across all runs of the function. A value of 0 (or undefined) means
+   * use the maximum available concurrency.
+   *
+   * Specifying just a number means specifying only the concurrency limit. A
+   * maximum of two concurrency options can be specified.
+   */
+  readonly concurrency?: number | ConcurrencyOption | readonly [ConcurrencyOption, ConcurrencyOption];
+  /**
+   * Rate limit function runs, only running them a given number of times (limit) per
+   * period. Note that rate limit is a lossy, hard limit. Once the limit is hit,
+   * new runs will be skipped.
+   */
+  readonly rateLimit?: RateLimitOption;
+  /**
+   * Throttles function runs, only running them a given number of times (limit) per
+   * period. Once the limit is hit, new runs will be enqueued and will start when there's
+   * capacity.
+   */
+  readonly throttle?: ThrottleOption;
+  /**
+   * Debounce delays functions for the `period` specified.
+   */
+  readonly debounce?: DebounceOption;
+  /**
+   * Allow the specification of an idempotency key using event data.
+   */
+  readonly idempotency?: string;
+  /**
+   * Configure how the priority of a function run is decided.
+   */
+  readonly priority?: PriorityOption;
+  /**
+   * Ensures that only one run of the function is active at a time for a given key.
+   */
+  readonly singleton?: SingletonOption;
+  /**
+   * Configuration for cancelling a function run based on incoming events.
+   */
+  readonly cancelOn?: ReadonlyArray<CancellationOption>;
+  /**
+   * Configure timeouts for the function.
+   */
+  readonly timeouts?: TimeoutsOption;
+  /**
+   * Batch events configuration.
+   */
+  readonly batchEvents?: BatchEventsOption;
+}
+interface RegistrationConfig {
+  readonly appId: string;
+  readonly url: string;
+}
+interface FunctionRegistration {
+  readonly id: string;
+  readonly name: string;
+  readonly triggers: ReadonlyArray<{
+    event?: string;
+    cron?: string;
+    expression?: string;
+  }>;
+  readonly steps: {
+    readonly step: {
+      readonly id: string;
+      readonly name: string;
+      readonly runtime: {
+        readonly type: "http";
+        readonly url: string;
+      };
+      readonly retries?: {
+        readonly attempts: number;
+      };
+    };
+  };
+  readonly cancel?: ReadonlyArray<{
+    event: string;
+    if?: string;
+    timeout?: string;
+  }>;
+  readonly timeouts?: {
+    start?: string;
+    finish?: string;
+  };
+}
+/**
+ * An Inngest function definition.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+interface InngestFunction<Tag extends string, Triggers extends Trigger, Success extends Schema.Schema.Any, Options extends FunctionOptions = FunctionOptions> {
+  readonly [TypeId]: TypeId;
+  readonly _tag: Tag;
+  readonly key: string;
+  readonly triggers: ReadonlyArray<Triggers>;
+  readonly success: Success;
+  readonly options: Options;
+  readonly toRegistration: (config: RegistrationConfig) => FunctionRegistration;
+}
+/**
+ * @since 0.1.0
+ * @category models
+ */
+declare namespace InngestFunction {
+  type Any = InngestFunction<string, Trigger, Schema.Schema.Any, FunctionOptions>;
+  type Tag<F> = F extends InngestFunction<infer T, any, any, any> ? T : never;
+  type Triggers<F> = F extends InngestFunction<any, infer T, any, any> ? T : never;
+  type Events<F> = F extends InngestFunction<any, infer T, any, any> ? (T extends EventTrigger<infer E> ? E : never) : never;
+  type EventType<F> = F extends InngestFunction<any, infer T, any, any> ? T extends EventTrigger<infer E> ? Schema.Schema.Type<E> : never : never;
+  type Success<F> = F extends InngestFunction<any, any, infer S, any> ? Schema.Schema.Type<S> : never;
+  type Options<F> = F extends InngestFunction<any, any, any, infer O> ? O : never;
+}
+type NormalizeTriggers<T extends TriggerInput> = T extends ReadonlyArray<Trigger> ? T[number] : T;
+/**
+ * @since 0.1.0
+ * @category constructors
+ * @example
+ * ```ts
+ * // Event trigger
+ * const Fn1 = InngestFunction.make("Hello", {
+ *   trigger: { event: HelloEvent },
+ *   success: Schema.Void,
+ * })
+ *
+ * // Event trigger with CEL filter
+ * const Fn2 = InngestFunction.make("Hello", {
+ *   trigger: { event: HelloEvent, if: "event.data.name != ''" },
+ *   success: Schema.Void,
+ * })
+ *
+ * // Cron trigger
+ * const Fn3 = InngestFunction.make("Scheduled", {
+ *   trigger: { cron: "0 * * * *" },
+ *   success: Schema.Void,
+ * })
+ *
+ * // Multiple triggers
+ * const Fn4 = InngestFunction.make("Multi", {
+ *   trigger: [
+ *     { event: HelloEvent },
+ *     { cron: "0 0 * * *" },
+ *   ],
+ *   success: Schema.Void,
+ * })
+ * ```
+ */
+declare function make<const Tag extends string, T extends TriggerInput, S extends Schema.Schema.Any, const O extends FunctionOptions = {}>(tag: Tag, options: {
+  readonly trigger: T;
+  readonly success: S;
+} & O): InngestFunction<Tag, NormalizeTriggers<T>, S, O>;
+//#endregion
+export { CronTrigger, EventTrigger, FunctionOptions, Function_d_exports, InngestFunction, Trigger, TriggerInput, TypeId, make };

package/dist/Function.js

@@ -0,0 +1,104 @@
+import { __exportAll } from "./_virtual/rolldown_runtime.js";
+import { timeStr } from "./internal/helpers.js";
+import { Array, Duration, Predicate, Schema } from "effect";
+
+//#region src/Function.ts
+/**
+* @since 0.1.0
+*/
+var Function_exports = /* @__PURE__ */ __exportAll({
+	TypeId: () => TypeId,
+	make: () => make
+});
+/**
+* @since 0.1.0
+* @category type ids
+*/
+const TypeId = Symbol.for("effect-inngest/Function");
+const isEventTrigger = (t) => Predicate.hasProperty(t, "event");
+const Proto = {
+	[TypeId]: TypeId,
+	toRegistration(config) {
+		const triggers = [];
+		for (const t of this.triggers) if (isEventTrigger(t)) triggers.push({
+			event: t.event._tag,
+			expression: t.if
+		});
+		else triggers.push({ cron: t.cron });
+		const opts = this.options;
+		const cancel = opts.cancelOn?.map((c) => ({
+			event: c.event,
+			if: c.if,
+			timeout: c.timeout ? timeStr(c.timeout) : void 0
+		}));
+		const timeouts = opts.timeouts?.start || opts.timeouts?.finish ? {
+			start: opts.timeouts.start ? timeStr(opts.timeouts.start) : void 0,
+			finish: opts.timeouts.finish ? timeStr(opts.timeouts.finish) : void 0
+		} : void 0;
+		const fnId = `${config.appId}-${this._tag}`;
+		const stepUrl = new URL(config.url);
+		stepUrl.searchParams.set("fnId", fnId);
+		stepUrl.searchParams.set("stepId", "step");
+		return {
+			id: fnId,
+			name: opts.name ?? this._tag,
+			triggers,
+			steps: { step: {
+				id: "step",
+				name: "step",
+				runtime: {
+					type: "http",
+					url: stepUrl.href
+				},
+				retries: { attempts: opts.retries ?? 3 }
+			} },
+			cancel: cancel && cancel.length > 0 ? cancel : void 0,
+			timeouts
+		};
+	}
+};
+/**
+* @since 0.1.0
+* @category constructors
+* @example
+* ```ts
+* // Event trigger
+* const Fn1 = InngestFunction.make("Hello", {
+*   trigger: { event: HelloEvent },
+*   success: Schema.Void,
+* })
+*
+* // Event trigger with CEL filter
+* const Fn2 = InngestFunction.make("Hello", {
+*   trigger: { event: HelloEvent, if: "event.data.name != ''" },
+*   success: Schema.Void,
+* })
+*
+* // Cron trigger
+* const Fn3 = InngestFunction.make("Scheduled", {
+*   trigger: { cron: "0 * * * *" },
+*   success: Schema.Void,
+* })
+*
+* // Multiple triggers
+* const Fn4 = InngestFunction.make("Multi", {
+*   trigger: [
+*     { event: HelloEvent },
+*     { cron: "0 0 * * *" },
+*   ],
+*   success: Schema.Void,
+* })
+* ```
+*/
+function make(tag, options) {
+	const fn = Object.create(Proto);
+	fn._tag = tag;
+	fn.key = `effect-inngest/Function/${tag}`;
+	fn.triggers = Array.ensure(options.trigger);
+	fn.success = options.success;
+	fn.options = options;
+	return fn;
+}
+
+//#endregion
+export { Function_exports, TypeId, make };

package/dist/Group.d.ts

@@ -0,0 +1,152 @@
+import { InngestClient } from "./Client.js";
+import { InngestFunction } from "./Function.js";
+import { HandlerContext } from "./internal/step.js";
+import * as HttpApp from "@effect/platform/HttpApp";
+import * as HttpClient from "@effect/platform/HttpClient";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+//#region src/Group.d.ts
+declare namespace Group_d_exports {
+  export { Handler, HandlerContext, HandlerFn, HandlerFrom, HandlerRequirements, HandlersFrom, HandlersRequirements, InngestGroup, ToHandler, TypeId, make, toHttpApp, toWebHandler };
+}
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+declare const TypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+type TypeId = typeof TypeId;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+type HandlerFn<F extends InngestFunction.Any> = (context: HandlerContext<F>) => Effect.Effect<InngestFunction.Success<F>, unknown, unknown>;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+type HandlersFrom<Fns extends InngestFunction.Any> = { readonly [F in Fns as InngestFunction.Tag<F>]: HandlerFn<F> };
+/**
+ * @since 0.1.0
+ * @category models
+ */
+type HandlerFrom<Fns extends InngestFunction.Any, Tag extends InngestFunction.Tag<Fns>> = Extract<Fns, {
+  readonly _tag: Tag;
+}> extends infer Current ? Current extends InngestFunction.Any ? HandlerFn<Current> : never : never;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+type HandlersRequirements<H> = H extends Record<string, (...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, unknown, infer R>> ? R : never;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+type HandlerRequirements<Handler> = Handler extends ((...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, unknown, infer R>) ? R : never;
+/**
+ * A nominal type representing a registered handler for a specific function tag.
+ * @since 0.1.0
+ * @category models
+ */
+interface Handler<Tag extends string> {
+  readonly _: unique symbol;
+  readonly tag: Tag;
+  readonly handler: (context: unknown) => Effect.Effect<unknown, unknown, unknown>;
+  readonly context: Context.Context<never>;
+}
+/**
+ * Maps a function to its Handler type.
+ * @since 0.1.0
+ * @category models
+ */
+type ToHandler<F extends InngestFunction.Any> = F extends InngestFunction<infer _Tag, infer _Triggers, infer _Success> ? Handler<_Tag> : never;
+/**
+ * @since 0.1.0
+ * @category models
+ */
+interface InngestGroup<Fns extends InngestFunction.Any> {
+  readonly [TypeId]: TypeId;
+  readonly functions: ReadonlyMap<string, Fns>;
+  /**
+   * Implement all handlers for the functions in this group.
+   */
+  readonly toLayer: <H extends HandlersFrom<Fns>>(handlers: H) => Layer.Layer<ToHandler<Fns>, never, HandlersRequirements<H>>;
+  /**
+   * Implement a single handler from the group.
+   */
+  readonly toLayerHandler: <Tag extends InngestFunction.Tag<Fns>, H extends HandlerFrom<Fns, Tag>>(tag: Tag, handler: H) => Layer.Layer<Handler<Tag>, never, HandlerRequirements<H>>;
+}
+/**
+ * @since 0.1.0
+ * @category models
+ */
+declare namespace InngestGroup {
+  type Any = InngestGroup<InngestFunction.Any>;
+  type Functions<G> = G extends InngestGroup<infer Fns> ? Fns : never;
+  type FunctionTags<G> = G extends InngestGroup<infer Fns> ? InngestFunction.Tag<Fns> : never;
+  type Handlers<G> = G extends InngestGroup<infer Fns> ? HandlersFrom<Fns> : never;
+}
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+declare const make: <Fns extends ReadonlyArray<InngestFunction.Any>>(...fns: Fns) => InngestGroup<Fns[number]>;
+/**
+ * Build an HttpApp from an InngestGroup.
+ *
+ * @since 0.1.0
+ * @category http
+ * @example
+ * ```ts
+ * import { Effect, Layer } from "effect"
+ * import { HttpServer } from "@effect/platform"
+ * import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+ * import { InngestGroup, InngestClient } from "effect-inngest"
+ *
+ * InngestGroup.toHttpApp(MyGroup).pipe(
+ *   Effect.flatMap((app) => HttpServer.serve(app)),
+ *   Effect.provide(InngestClient.layer({ id: "my-app" })),
+ *   Effect.provide(NodeHttpServer.layer({ port: 3000 })),
+ *   NodeRuntime.runMain,
+ * )
+ * ```
+ */
+declare const toHttpApp: (group: InngestGroup.Any) => HttpApp.Default<never, InngestClient | HttpClient.HttpClient>;
+/**
+ * Create a standalone web handler from an InngestGroup.
+ *
+ * @since 0.1.0
+ * @category http
+ * @example
+ * ```ts
+ * import { InngestGroup, InngestClient } from "effect-inngest"
+ * import { HttpClient } from "@effect/platform"
+ * import { FetchHttpClient } from "@effect/platform"
+ *
+ * const { handler, dispose } = InngestGroup.toWebHandler(MyGroup, {
+ *   layer: InngestClient.layer({ id: "my-app" }).pipe(
+ *     Layer.provide(FetchHttpClient.layer),
+ *   ),
+ * })
+ *
+ * // Use with any web framework
+ * Bun.serve({ fetch: handler, port: 3000 })
+ *
+ * // Call dispose() on shutdown
+ * process.on("SIGTERM", dispose)
+ * ```
+ */
+declare const toWebHandler: <R, E>(group: InngestGroup.Any, options: {
+  readonly layer: Layer.Layer<InngestClient | HttpClient.HttpClient | R, E, never>;
+  readonly memoMap?: Layer.MemoMap;
+}) => {
+  readonly handler: (request: Request) => Promise<Response>;
+  readonly dispose: () => Promise<void>;
+};
+//#endregion
+export { Group_d_exports, Handler, type HandlerContext, HandlerFn, HandlerFrom, HandlerRequirements, HandlersFrom, HandlersRequirements, InngestGroup, ToHandler, TypeId, make, toHttpApp, toWebHandler };