effect-inngest 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Shestopal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,457 @@
+<div align="center">
+  <br />
+  <img src="./logo.png" alt="Effect Inngest" width="180" />
+  <h1>Effect Inngest</h1>
+  <p><strong>Build durable, type-safe workflows with Effect and Inngest</strong></p>
+  <p>The native Effect SDK for <a href="https://inngest.com">Inngest</a> — full type inference, composable steps, and dependency injection.</p>
+  <br />
+
+<a href="#getting-started">Getting Started</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#features">Features</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="#api-reference">API Reference</a>
+<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+<a href="./examples">Examples</a>
+<br />
+<br />
+
+</div>
+
+---
+
+## What is Effect Inngest?
+
+Effect Inngest brings the power of [Effect](https://effect.website) to [Inngest's](https://inngest.com) durable execution platform. Define event schemas once, and types flow automatically through triggers, handlers, and step operations — no manual annotations needed.
+
+```typescript
+import { InngestFunction, InngestGroup, InngestClient } from "effect-inngest";
+import { Effect, Schema, Layer } from "effect";
+
+// Define events as TaggedClass
+class UserSignup extends Schema.TaggedClass<UserSignup>()("user/signup", {
+  userId: Schema.String,
+  email: Schema.String,
+}) {}
+
+// Create a function — event type is inferred from the trigger
+const ProcessSignup = InngestFunction.make("process-signup", {
+  trigger: { event: UserSignup },
+  success: Schema.Void,
+});
+
+// Create group and implement handler
+const Group = InngestGroup.make(ProcessSignup);
+
+class UserOnboarded extends Schema.TaggedClass<UserOnboarded>()("user/onboarded", {
+  userId: Schema.String,
+}) {}
+
+const Handlers = Group.toLayer({
+  "process-signup": ({ event, step }) =>
+    Effect.gen(function* () {
+      // event is typed as UserSignup
+      yield* step.run("send-welcome", sendWelcomeEmail(event.email));
+      yield* step.sleep("delay", "1 hour");
+      yield* step.sendEvent("notify", new UserOnboarded({ userId: event.userId }));
+    }),
+});
+```
+
+<h3><a href="#getting-started">Get started →</a></h3>
+
+---
+
+## Features
+
+- 🧙‍♂️ **Full type inference** — Payload types flow from schemas through triggers to handlers
+- ⚡ **Effect-native steps** — `step.run`, `step.sleep`, `step.waitForEvent` return proper Effects
+- 🔌 **Dependency injection** — Use Effect's Layer system for services in handlers
+- 🛡️ **Schema validation** — Define events once with Effect Schema, validated everywhere
+- 🚀 **Zero boilerplate** — No code generation, no manual type annotations
+- 🔄 **Parallel execution** — Run steps concurrently with `Effect.all`
+- 🌐 **Multi-runtime** — Works with Bun, Node.js, and Cloudflare Workers
+- 🪶 **Lightweight** — Minimal dependencies, tree-shakeable
+
+---
+
+## Installation
+
+```bash
+npm install effect-inngest effect @effect/platform
+```
+
+<details>
+<summary>Other package managers</summary>
+
+```bash
+# pnpm
+pnpm add effect-inngest effect @effect/platform
+
+# yarn
+yarn add effect-inngest effect @effect/platform
+
+# bun
+bun add effect-inngest effect @effect/platform
+```
+
+</details>
+
+---
+
+## Quick Start
+
+Copy this into a file called `inngest-demo.ts` and run it:
+
+```typescript
+import { FetchHttpClient } from "@effect/platform";
+import { BunHttpServer, BunRuntime } from "@effect/platform-bun";
+import * as HttpMiddleware from "@effect/platform/HttpMiddleware";
+import * as HttpServer from "@effect/platform/HttpServer";
+import { Duration, Effect, Layer, Schema } from "effect";
+import { InngestFunction, InngestGroup, InngestClient } from "effect-inngest";
+
+// 1. Define your events as TaggedClass
+class UserSignup extends Schema.TaggedClass<UserSignup>()("user/signup", {
+  userId: Schema.String,
+  email: Schema.String,
+}) {}
+
+class UserWelcomeSent extends Schema.TaggedClass<UserWelcomeSent>()("user/welcome-sent", {
+  userId: Schema.String,
+}) {}
+
+// 2. Define your functions
+const ProcessSignup = InngestFunction.make("process-signup", {
+  trigger: { event: UserSignup },
+  success: { welcomed: Schema.Boolean },
+});
+
+const DailyDigest = InngestFunction.make("daily-digest", {
+  trigger: { cron: "0 9 * * *" },
+});
+
+// 3. Create function group and implement handlers
+const App = InngestGroup.make(ProcessSignup, DailyDigest);
+
+const Handlers = App.toLayer({
+  "process-signup": ({ event, step }) =>
+    Effect.gen(function* () {
+      // event is typed as UserSignup
+      yield* Effect.log(`Processing signup for ${event.email}`);
+
+      // Durable step - memoized across retries
+      const user = yield* step.run("create-user", Effect.succeed({ id: event.userId, email: event.email }));
+
+      // Sleep durably
+      yield* step.sleep("welcome-delay", Duration.seconds(5));
+
+      // Send follow-up event
+      yield* step.sendEvent("notify", new UserWelcomeSent({ userId: user.id }));
+
+      return { welcomed: true };
+    }),
+
+  "daily-digest": ({ step }) => step.run("send-digest", Effect.log("Sending daily digest...")),
+});
+
+// 4. Create client and start server
+const Client = InngestClient.layer({
+  id: "my-app",
+  mode: "dev",
+}).pipe(Layer.provide(FetchHttpClient.layer));
+
+const Server = Layer.unwrapEffect(
+  Effect.gen(function* () {
+    const app = yield* InngestGroup.toHttpApp(App);
+    return HttpServer.serve(app, HttpMiddleware.logger).pipe(
+      HttpServer.withLogAddress,
+      Layer.provide(BunHttpServer.layer({ port: 3000 })),
+    );
+  }),
+).pipe(Layer.provide(Handlers), Layer.provide(Client), Layer.provide(FetchHttpClient.layer));
+
+// Run it
+BunRuntime.runMain(Layer.launch(Server));
+```
+
+Then in two terminals:
+
+```bash
+# Terminal 1: Start your app
+bun inngest-demo.ts
+
+# Terminal 2: Start Inngest dev server
+bunx inngest-cli@latest dev -u http://localhost:3000
+```
+
+Open http://localhost:8288 to trigger events and watch your functions run.
+
+---
+
+## Getting Started
+
+### 1. Define your events as TaggedClass
+
+```typescript
+import { Schema } from "effect";
+
+class UserSignup extends Schema.TaggedClass<UserSignup>()("user/signup", {
+  userId: Schema.String,
+  email: Schema.String,
+  plan: Schema.Literal("free", "pro", "enterprise"),
+}) {}
+
+class OrderPlaced extends Schema.TaggedClass<OrderPlaced>()("order/placed", {
+  orderId: Schema.String,
+  items: Schema.Array(Schema.Struct({ sku: Schema.String, qty: Schema.Number })),
+  total: Schema.Number,
+}) {}
+```
+
+### 2. Define your functions
+
+```typescript
+import { InngestFunction } from "effect-inngest";
+
+// Event-triggered function
+const ProcessSignup = InngestFunction.make("process-signup", {
+  trigger: [{ event: UserSignup }], // pass multiple triggers as Array.
+  success: { welcomeEmailSent: Schema.Boolean },
+});
+
+// Cron-triggered function
+const DailyReport = InngestFunction.make("daily-report", {
+  trigger: { cron: "0 9 * * *" },
+});
+```
+
+### 3. Create a function group and implement handlers
+
+```typescript
+import { InngestGroup } from "effect-inngest";
+import { Effect, Duration } from "effect";
+
+const AppFunctions = InngestGroup.make(ProcessSignup, DailyReport);
+
+const HandlersLive = AppFunctions.toLayer({
+  "process-signup": ({ event, step }) =>
+    Effect.gen(function* () {
+      yield* step.run("create-user", createUser(event));
+      yield* step.sleep("delay", Duration.minutes(5));
+      yield* step.sendEvent("welcome", new UserWelcomeSent({ userId: event.userId }));
+      return { welcomeEmailSent: true };
+    }),
+
+  "daily-report": ({ step }) => step.run("generate", Effect.log("Generating report...")),
+});
+```
+
+### 4. Create a web handler
+
+```typescript
+import { InngestClient, InngestGroup } from "effect-inngest";
+import { FetchHttpClient } from "@effect/platform";
+import { Layer } from "effect";
+
+const ClientLive = InngestClient.layer({
+  id: "my-app",
+  mode: "cloud",
+  signingKey: process.env.INNGEST_SIGNING_KEY,
+  eventKey: process.env.INNGEST_EVENT_KEY,
+}).pipe(Layer.provide(FetchHttpClient.layer));
+
+const { handler, dispose } = InngestGroup.toWebHandler(AppFunctions, {
+  layer: Layer.mergeAll(HandlersLive, ClientLive),
+});
+
+// Use with Bun
+Bun.serve({ port: 3000, fetch: handler });
+```
+
+---
+
+## Step Operations
+
+All step operations are durable — they're memoized and survive retries:
+
+```typescript
+({ step }) =>
+  Effect.gen(function* () {
+    // Run any Effect with memoization
+    const user = yield* step.run("fetch-user", fetchUser(userId));
+
+    // Sleep for a duration
+    yield* step.sleep("wait", Duration.hours(24));
+
+    // Sleep until a timestamp
+    yield* step.sleepUntil("deadline", new Date("2024-12-31"));
+
+    // Wait for an event (returns Option)
+    const payment = yield* step.waitForEvent("await-payment", PaymentReceived, {
+      timeout: Duration.days(7),
+      if: `async.data.orderId == "${orderId}"`,
+    });
+
+    // Invoke another function
+    const result = yield* step.invoke("process", {
+      function: ProcessOrder,
+      data: { orderId: "123" },
+    });
+
+    // Send events
+    yield* step.sendEvent("notify", new OrderShipped({ orderId }));
+  });
+```
+
+### Parallel Execution
+
+Run steps in parallel with Effect's concurrency:
+
+```typescript
+const [user, orders, prefs] =
+  yield *
+  Effect.all(
+    [step.run("user", fetchUser(id)), step.run("orders", fetchOrders(id)), step.run("prefs", fetchPreferences(id))],
+    { concurrency: "unbounded" },
+  );
+```
+
+---
+
+## Dependency Injection
+
+Use Effect's Layer system for clean dependency injection:
+
+```typescript
+import { Context, Layer } from "effect";
+
+// Define a service
+class EmailService extends Context.Tag("EmailService")<
+  EmailService,
+  { readonly send: (to: string, body: string) => Effect.Effect<void> }
+>() {}
+
+// Use in handler
+const HandlersLive = AppFunctions.toLayer({
+  "process-signup": ({ event, step }) =>
+    Effect.gen(function* () {
+      const email = yield* EmailService;
+      yield* step.run("send", email.send(event.email, "Welcome!"));
+      return { welcomeEmailSent: true };
+    }),
+});
+
+// Provide implementation
+const EmailServiceLive = Layer.succeed(EmailService, {
+  send: (to, body) => Effect.log(`Sending to ${to}: ${body}`),
+});
+
+const { handler } = InngestGroup.toWebHandler(AppFunctions, {
+  layer: Layer.mergeAll(HandlersLive.pipe(Layer.provide(EmailServiceLive)), ClientLive),
+});
+```
+
+---
+
+## Function Options
+
+Configure retries, concurrency, rate limiting, and more:
+
+```typescript
+const ProcessOrder = InngestFunction.make("process-order", {
+  trigger: { event: OrderPlaced },
+  retries: 5,
+  concurrency: { limit: 10, key: "event.data.userId" },
+  rateLimit: { limit: 100, period: Duration.minutes(1) },
+  throttle: { limit: 50, period: Duration.seconds(10) },
+  debounce: { period: Duration.seconds(5) },
+  idempotency: "event.data.orderId",
+  timeouts: { finish: Duration.hours(1) },
+  cancelOn: [{ event: "order/cancelled", if: "event.data.orderId == async.data.orderId" }],
+  priority: { run: "event.data.isPremium ? 100 : 0" },
+});
+```
+
+---
+
+## Error Handling
+
+Control retry behavior with typed errors:
+
+```typescript
+import { NonRetriableError, RetryAfterError } from "effect-inngest";
+
+// Don't retry this error
+yield * new NonRetriableError({ message: "Card permanently declined" });
+
+// Retry after a specific duration (retryAfter in milliseconds)
+yield * new RetryAfterError({ message: "Rate limited", retryAfter: 60000 });
+```
+
+---
+
+## API Reference
+
+### Core Modules
+
+| Module              | Description                                            |
+| ------------------- | ------------------------------------------------------ |
+| `InngestFunction`   | Function definition with trigger-based event inference |
+| `InngestGroup`      | Group functions, create handlers, and serve HTTP       |
+| `InngestClient`     | Client configuration and event operations              |
+| `NonRetriableError` | Error to skip retries                                  |
+| `RetryAfterError`   | Error to retry after delay                             |
+
+### Step Methods
+
+| Method                                     | Description                        |
+| ------------------------------------------ | ---------------------------------- |
+| `step.run(id, effect)`                     | Execute an effect with memoization |
+| `step.sleep(id, duration)`                 | Sleep for a duration               |
+| `step.sleepUntil(id, timestamp)`           | Sleep until a timestamp            |
+| `step.waitForEvent(id, EventSchema, opts)` | Wait for an event with timeout     |
+| `step.invoke(id, opts)`                    | Invoke another function            |
+| `step.sendEvent(id, TaggedEvent)`          | Send events to Inngest             |
+
+---
+
+## Examples
+
+See the [`examples/`](./examples) directory:
+
+| Example                                     | Description                                    |
+| ------------------------------------------- | ---------------------------------------------- |
+| [simple.ts](./examples/simple.ts)           | Minimal hello world with parallel steps        |
+| [KitchenSink.ts](./examples/KitchenSink.ts) | Complete e-commerce workflow with all features |
+
+```bash
+# Run an example
+bun examples/simple.ts
+
+# Start Inngest dev server
+bunx inngest-cli@latest dev -u http://localhost:9999
+```
+
+---
+
+## Current Limitations
+
+This library is under active development. The following Inngest features are **not yet supported**:
+
+| Feature                | Status               |
+| ---------------------- | -------------------- |
+| Middleware             | 🚧 Not yet supported |
+| AI Steps (`step.ai.*`) | 🚧 Not yet supported |
+| Encryption             | 🚧 Not yet supported |
+
+---
+
+## Requirements
+
+- **TypeScript** 5.4+ with `strict: true`
+- **Effect** 3.x
+
+## License
+
+MIT

package/dist/Client.d.ts

@@ -0,0 +1,167 @@
+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";
+import * as Schema from "effect/Schema";
+import * as Config from "effect/Config";
+import * as ConfigError from "effect/ConfigError";
+
+//#region src/Client.d.ts
+declare namespace Client_d_exports {
+  export { EventPayload, InngestClient, layer, layerConfig, layerFromEnv };
+}
+/**
+ * @since 0.1.0
+ * @category type ids
+ * @internal
+ */
+declare const TypeId: unique symbol;
+/**
+ * @since 0.1.0
+ * @category type ids
+ * @internal
+ */
+type TypeId = typeof TypeId;
+type ClientMode = "dev" | "cloud";
+interface ClientConfig {
+  /**
+   * The ID of this instance, most commonly a reference to the application it
+   * resides in.
+   *
+   * The ID of your client should remain the same for its lifetime; if you'd
+   * like to change the name of your client as it appears in the Inngest UI,
+   * change the `name` property instead.
+   */
+  readonly id: string;
+  /**
+   * Inngest event key, used to send events to Inngest Cloud. If not provided,
+   * will search for the `INNGEST_EVENT_KEY` environment variable. If neither
+   * can be found, a warning will be shown and any attempts to send events in
+   * cloud mode will throw an error.
+   */
+  readonly eventKey?: string | undefined;
+  /**
+   * Inngest signing key, used for request signature verification.
+   * If not provided, will search for the `INNGEST_SIGNING_KEY` environment variable.
+   */
+  readonly signingKey?: string | undefined;
+  /**
+   * Fallback signing key for key rotation scenarios.
+   * If not provided, will search for the `INNGEST_SIGNING_KEY_FALLBACK` environment variable.
+   */
+  readonly signingKeyFallback?: string | undefined;
+  /**
+   * The base URL for the Inngest API (registration, run fetching, etc.)
+   * Defaults to https://api.inngest.com/ in cloud mode.
+   */
+  readonly apiBaseUrl?: string | undefined;
+  /**
+   * The base URL for sending events.
+   * Defaults to https://inn.gs/ in cloud mode.
+   */
+  readonly eventBaseUrl?: string | undefined;
+  /**
+   * Can be used to explicitly set the client to Development Mode or Cloud Mode.
+   * If not set, mode is inferred from environment variables (INNGEST_DEV, NODE_ENV, etc.)
+   *
+   * Development mode will turn off signature verification and default to using
+   * a local URL to access a local Dev Server.
+   */
+  readonly mode?: ClientMode | undefined;
+  /**
+   * The Inngest environment to send events to. Defaults to whichever
+   * environment this client's event key is associated with.
+   *
+   * It's likely you never need to change this unless you're trying to sync
+   * multiple systems together using branch names.
+   */
+  readonly env?: string | undefined;
+  /**
+   * The application-specific version identifier. This can be an arbitrary value
+   * such as a version string, a Git commit SHA, or any other unique identifier.
+   */
+  readonly appVersion?: string | undefined;
+  /**
+   * The host where this app is served. Used for registration.
+   */
+  readonly serveHost?: string | undefined;
+  /**
+   * The path where the Inngest serve handler is mounted. Used for registration.
+   */
+  readonly servePath?: string | undefined;
+}
+declare const EventPayload: Schema.Struct<{
+  name: typeof Schema.String;
+  data: typeof Schema.Unknown;
+  ts: Schema.optional<typeof Schema.Number>;
+  id: Schema.optional<typeof Schema.String>;
+  v: Schema.optional<typeof Schema.String>;
+}>;
+declare const SendEventResponse: Schema.Struct<{
+  ids: Schema.optionalWith<Schema.Array$<typeof Schema.String>, {
+    default: () => never[];
+  }>;
+  status: Schema.optional<typeof Schema.Number>;
+}>;
+type EventPayload = typeof EventPayload.Type;
+type SendEventResponse = typeof SendEventResponse.Type;
+declare const SendEventError_base: Schema.TaggedErrorClass<SendEventError, "SendEventError", {
+  readonly _tag: Schema.tag<"SendEventError">;
+} & {
+  message: typeof Schema.String;
+  events: Schema.Array$<typeof Schema.String>;
+}>;
+declare class SendEventError extends SendEventError_base {}
+interface InngestClientService {
+  readonly [TypeId]: TypeId;
+  readonly config: ClientConfig;
+  readonly mode: ClientMode;
+  readonly eventBaseUrl: string;
+  readonly apiBaseUrl: string;
+  readonly sendEvent: (events: ReadonlyArray<EventPayload>) => Effect.Effect<SendEventResponse, SendEventError>;
+}
+declare const InngestClient_base: Context.TagClass<InngestClient, "effect-inngest/InngestClient", InngestClientService>;
+/**
+ * InngestClient service for communicating with Inngest.
+ *
+ * @since 0.1.0
+ * @category context
+ */
+declare class InngestClient extends InngestClient_base {}
+/**
+ * Create an InngestClient layer from a config.
+ *
+ * @since 0.1.0
+ * @category layers
+ * @example
+ * ```ts
+ * const ClientLive = InngestClient.layer({
+ *   id: "my-app",
+ *   eventKey: "my-event-key",
+ * })
+ * ```
+ */
+declare const layer: (config: ClientConfig) => Layer.Layer<InngestClient, never, HttpClient.HttpClient>;
+/**
+ * Create an InngestClient layer from Effect Config.
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+declare const layerConfig: (config: Config.Config.Wrap<ClientConfig>) => Layer.Layer<InngestClient, ConfigError.ConfigError, HttpClient.HttpClient>;
+/**
+ * Create an InngestClient layer from environment variables.
+ *
+ * Uses:
+ * - INNGEST_APP_ID or "app" as id
+ * - INNGEST_EVENT_KEY for event key
+ * - INNGEST_SIGNING_KEY for signing key
+ *
+ * Mode is inferred from environment (INNGEST_DEV, NODE_ENV, etc.)
+ *
+ * @since 0.1.0
+ * @category layers
+ */
+declare const layerFromEnv: Layer.Layer<InngestClient, ConfigError.ConfigError, HttpClient.HttpClient>;
+//#endregion
+export { Client_d_exports, EventPayload, InngestClient, layer, layerConfig, layerFromEnv };