@porulle/jobs-inngest 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unified-commerce-engine contributors
+
+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,20 @@
+# `@porulle/jobs-inngest`
+
+Push execution engine that translates Porulle tasks into Inngest functions. Pass `engine.functions` to your Inngest `serve()` adapter; Inngest owns delivery and retries.
+
+```ts
+import { Inngest } from "inngest";
+import { serve } from "inngest/hono";
+import { InngestExecutionEngine } from "@porulle/jobs-inngest";
+
+const inngest = new Inngest({ id: "store" });
+export const jobs = new InngestExecutionEngine({ client: inngest });
+
+export default defineConfig({ jobs: { adapter: jobs } });
+export const inngestHandler = serve({
+  client: inngest,
+  functions: jobs.functions,
+});
+```
+
+Create the Porulle kernel before serving so task registration has populated `jobs.functions`.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { Inngest } from "inngest";
+import type { EnqueueOptions, ExecutionEngine, ExecutionEngineSetup } from "@porulle/core";
+type InngestFunction = ReturnType<Inngest["createFunction"]>;
+type DebouncePeriod = "1s" | "2s" | "5s" | "10s" | "30s" | "1m";
+export interface InngestExecutionEngineOptions {
+    client?: Inngest;
+    appId?: string;
+    eventPrefix?: string;
+    supersedesDebounce?: DebouncePeriod;
+}
+export declare class InngestExecutionEngine implements ExecutionEngine {
+    readonly execution: {
+        mode: "push";
+    };
+    readonly functions: InngestFunction[];
+    private readonly client;
+    private readonly eventPrefix;
+    private readonly supersedesDebounce;
+    private setup;
+    constructor(options?: InngestExecutionEngineOptions);
+    register(setup: ExecutionEngineSetup): void;
+    enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
+    private createFunction;
+    private eventName;
+    private requireSetup;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,100 @@
+import { Inngest } from "inngest";
+const INNGEST_RETRY_VALUES = [
+    0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+];
+export class InngestExecutionEngine {
+    execution = { mode: "push" };
+    functions = [];
+    client;
+    eventPrefix;
+    supersedesDebounce;
+    setup;
+    constructor(options = {}) {
+        this.client =
+            options.client ?? new Inngest({ id: options.appId ?? "porulle" });
+        this.eventPrefix = options.eventPrefix ?? "porulle/job";
+        this.supersedesDebounce = options.supersedesDebounce ?? "1s";
+    }
+    register(setup) {
+        this.setup = setup;
+        this.functions.splice(0, this.functions.length);
+        for (const task of setup.tasks.values()) {
+            this.functions.push(this.createFunction(task));
+        }
+    }
+    async enqueue(taskSlug, input, options) {
+        const task = this.requireSetup().tasks.get(taskSlug);
+        if (!task)
+            throw new Error(`Unknown task slug: ${taskSlug}`);
+        const organizationId = options.organizationId.trim();
+        if (!organizationId)
+            throw new Error("Jobs enqueue requires a non-empty organizationId.");
+        const taskMaxAttempts = task.retries?.attempts ?? 1;
+        if (options.maxAttempts !== undefined &&
+            options.maxAttempts !== taskMaxAttempts) {
+            throw new Error("Inngest retry counts are fixed when functions are registered; configure retries on TaskDefinition instead of enqueue().");
+        }
+        const taskSupersedes = Boolean(task.concurrency?.supersedes);
+        if (options.supersedes !== undefined &&
+            options.supersedes !== taskSupersedes) {
+            throw new Error("Inngest debounce is fixed when functions are registered; configure supersedes on TaskDefinition instead of enqueue().");
+        }
+        const concurrencyKey = options.concurrencyKey ?? task.concurrency?.key(input);
+        const data = {
+            input,
+            organizationId,
+            maxAttempts: taskMaxAttempts,
+            ...(concurrencyKey ? { concurrencyKey } : {}),
+        };
+        const result = await this.client.send({
+            name: this.eventName(taskSlug),
+            data,
+            ...(options.delayMs !== undefined
+                ? { ts: Date.now() + options.delayMs }
+                : {}),
+        });
+        const id = result.ids[0];
+        if (!id)
+            throw new Error("Inngest did not return an event id.");
+        return id;
+    }
+    createFunction(task) {
+        const exclusive = Boolean(task.concurrency && task.concurrency.exclusive !== false);
+        const retries = INNGEST_RETRY_VALUES[Math.min(Math.max((task.retries?.attempts ?? 1) - 1, 0), 20)];
+        return this.client.createFunction({
+            id: `porulle:${task.slug}`,
+            triggers: [{ event: this.eventName(task.slug) }],
+            retries,
+            ...(exclusive
+                ? { concurrency: { limit: 1, key: "event.data.concurrencyKey" } }
+                : {}),
+            ...(task.concurrency?.supersedes
+                ? {
+                    debounce: {
+                        key: "event.data.concurrencyKey",
+                        period: this.supersedesDebounce,
+                    },
+                }
+                : {}),
+        }, async ({ event, attempt }) => {
+            const data = event.data;
+            const result = await task.handler({
+                input: data.input,
+                ctx: this.requireSetup().context,
+                job: {
+                    attemptNumber: attempt + 1,
+                    maxAttempts: data.maxAttempts,
+                },
+            });
+            return result.output;
+        });
+    }
+    eventName(taskSlug) {
+        return `${this.eventPrefix}/${taskSlug}`;
+    }
+    requireSetup() {
+        if (!this.setup)
+            throw new Error("InngestExecutionEngine must be registered before use.");
+        return this.setup;
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@porulle/jobs-inngest",
+  "version": "0.9.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "inngest": "^4.13.0",
+    "@porulle/core": "0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4",
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "Inngest execution engine for Porulle background jobs.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/jobs-inngest"
+  },
+  "author": "Porulle contributors",
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+import { Inngest } from "inngest";
+import type {
+  EnqueueOptions,
+  ExecutionEngine,
+  ExecutionEngineSetup,
+  TaskDefinition,
+} from "@porulle/core";
+
+interface InngestJobData extends Record<string, unknown> {
+  input: Record<string, unknown>;
+  organizationId: string;
+  maxAttempts: number;
+  concurrencyKey?: string;
+}
+
+type InngestFunction = ReturnType<Inngest["createFunction"]>;
+type DebouncePeriod = "1s" | "2s" | "5s" | "10s" | "30s" | "1m";
+const INNGEST_RETRY_VALUES = [
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+] as const;
+
+export interface InngestExecutionEngineOptions {
+  client?: Inngest;
+  appId?: string;
+  eventPrefix?: string;
+  supersedesDebounce?: DebouncePeriod;
+}
+
+export class InngestExecutionEngine implements ExecutionEngine {
+  readonly execution = { mode: "push" as const };
+  readonly functions: InngestFunction[] = [];
+
+  private readonly client: Inngest;
+  private readonly eventPrefix: string;
+  private readonly supersedesDebounce: DebouncePeriod;
+  private setup: ExecutionEngineSetup | undefined;
+
+  constructor(options: InngestExecutionEngineOptions = {}) {
+    this.client =
+      options.client ?? new Inngest({ id: options.appId ?? "porulle" });
+    this.eventPrefix = options.eventPrefix ?? "porulle/job";
+    this.supersedesDebounce = options.supersedesDebounce ?? "1s";
+  }
+
+  register(setup: ExecutionEngineSetup): void {
+    this.setup = setup;
+    this.functions.splice(0, this.functions.length);
+    for (const task of setup.tasks.values()) {
+      this.functions.push(this.createFunction(task));
+    }
+  }
+
+  async enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options: EnqueueOptions,
+  ): Promise<string> {
+    const task = this.requireSetup().tasks.get(taskSlug);
+    if (!task) throw new Error(`Unknown task slug: ${taskSlug}`);
+    const organizationId = options.organizationId.trim();
+    if (!organizationId)
+      throw new Error("Jobs enqueue requires a non-empty organizationId.");
+    const taskMaxAttempts = task.retries?.attempts ?? 1;
+    if (
+      options.maxAttempts !== undefined &&
+      options.maxAttempts !== taskMaxAttempts
+    ) {
+      throw new Error(
+        "Inngest retry counts are fixed when functions are registered; configure retries on TaskDefinition instead of enqueue().",
+      );
+    }
+    const taskSupersedes = Boolean(task.concurrency?.supersedes);
+    if (
+      options.supersedes !== undefined &&
+      options.supersedes !== taskSupersedes
+    ) {
+      throw new Error(
+        "Inngest debounce is fixed when functions are registered; configure supersedes on TaskDefinition instead of enqueue().",
+      );
+    }
+
+    const concurrencyKey =
+      options.concurrencyKey ?? task.concurrency?.key(input);
+    const data: InngestJobData = {
+      input,
+      organizationId,
+      maxAttempts: taskMaxAttempts,
+      ...(concurrencyKey ? { concurrencyKey } : {}),
+    };
+    const result = await this.client.send({
+      name: this.eventName(taskSlug),
+      data,
+      ...(options.delayMs !== undefined
+        ? { ts: Date.now() + options.delayMs }
+        : {}),
+    });
+    const id = result.ids[0];
+    if (!id) throw new Error("Inngest did not return an event id.");
+    return id;
+  }
+
+  private createFunction(task: TaskDefinition): InngestFunction {
+    const exclusive = Boolean(
+      task.concurrency && task.concurrency.exclusive !== false,
+    );
+    const retries =
+      INNGEST_RETRY_VALUES[
+        Math.min(Math.max((task.retries?.attempts ?? 1) - 1, 0), 20)
+      ]!;
+    return this.client.createFunction(
+      {
+        id: `porulle:${task.slug}`,
+        triggers: [{ event: this.eventName(task.slug) }],
+        retries,
+        ...(exclusive
+          ? { concurrency: { limit: 1, key: "event.data.concurrencyKey" } }
+          : {}),
+        ...(task.concurrency?.supersedes
+          ? {
+              debounce: {
+                key: "event.data.concurrencyKey",
+                period: this.supersedesDebounce,
+              },
+            }
+          : {}),
+      },
+      async ({ event, attempt }) => {
+        const data = event.data as InngestJobData;
+        const result = await task.handler({
+          input: data.input,
+          ctx: this.requireSetup().context,
+          job: {
+            attemptNumber: attempt + 1,
+            maxAttempts: data.maxAttempts,
+          },
+        });
+        return result.output;
+      },
+    );
+  }
+
+  private eventName(taskSlug: string): string {
+    return `${this.eventPrefix}/${taskSlug}`;
+  }
+
+  private requireSetup(): ExecutionEngineSetup {
+    if (!this.setup)
+      throw new Error("InngestExecutionEngine must be registered before use.");
+    return this.setup;
+  }
+}