@porulle/jobs-trigger 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,12 @@
+# `@porulle/jobs-trigger`
+
+Push execution engine that translates Porulle tasks into Trigger.dev tasks and enqueues them with the Trigger.dev SDK.
+
+```ts
+import { TriggerExecutionEngine } from "@porulle/jobs-trigger";
+
+export const jobs = new TriggerExecutionEngine();
+export default defineConfig({ jobs: { adapter: jobs } });
+```
+
+Import the module that creates the Porulle kernel from the Trigger.dev task directory. Registration calls Trigger.dev's `task()` API for every configured task; the Trigger.dev runtime then owns execution and retries.

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { AnyTask } from "@trigger.dev/sdk";
+import type { EnqueueOptions, ExecutionEngine, ExecutionEngineSetup } from "@porulle/core";
+type DebounceDelay = "1s" | "2s" | "5s" | "10s" | "30s" | "1m";
+export interface TriggerExecutionEngineOptions {
+    queuePrefix?: string;
+    supersedesDebounce?: DebounceDelay;
+}
+export declare class TriggerExecutionEngine implements ExecutionEngine {
+    readonly execution: {
+        mode: "push";
+    };
+    readonly tasks: AnyTask[];
+    private readonly queuePrefix;
+    private readonly supersedesDebounce;
+    private setup;
+    constructor(options?: TriggerExecutionEngineOptions);
+    register(setup: ExecutionEngineSetup): void;
+    enqueue(taskSlug: string, input: Record<string, unknown>, options: EnqueueOptions): Promise<string>;
+    private createTask;
+    private translateRetry;
+    private requireSetup;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,99 @@
+import { task as createTriggerTask, tasks as triggerTasks, } from "@trigger.dev/sdk";
+export class TriggerExecutionEngine {
+    execution = { mode: "push" };
+    tasks = [];
+    queuePrefix;
+    supersedesDebounce;
+    setup;
+    constructor(options = {}) {
+        this.queuePrefix = options.queuePrefix ?? "porulle";
+        this.supersedesDebounce = options.supersedesDebounce ?? "1s";
+    }
+    register(setup) {
+        this.setup = setup;
+        this.tasks.splice(0, this.tasks.length);
+        for (const definition of setup.tasks.values()) {
+            this.tasks.push(this.createTask(definition));
+        }
+    }
+    async enqueue(taskSlug, input, options) {
+        const definition = this.requireSetup().tasks.get(taskSlug);
+        if (!definition)
+            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 concurrencyKey = options.concurrencyKey ?? definition.concurrency?.key(input);
+        const exclusive = Boolean(definition.concurrency && definition.concurrency.exclusive !== false);
+        const supersedes = options.supersedes ?? definition.concurrency?.supersedes;
+        const maxAttempts = options.maxAttempts ?? definition.retries?.attempts ?? 1;
+        const payload = {
+            input,
+            organizationId,
+            maxAttempts,
+            ...(concurrencyKey ? { concurrencyKey } : {}),
+        };
+        const handle = await triggerTasks.trigger(taskSlug, payload, {
+            maxAttempts,
+            ...(exclusive && concurrencyKey ? { concurrencyKey } : {}),
+            ...(options.delayMs !== undefined
+                ? { delay: new Date(Date.now() + options.delayMs) }
+                : {}),
+            ...(supersedes && concurrencyKey
+                ? {
+                    debounce: {
+                        key: concurrencyKey,
+                        delay: this.supersedesDebounce,
+                        mode: "trailing",
+                    },
+                }
+                : {}),
+        });
+        return handle.id;
+    }
+    createTask(definition) {
+        const exclusive = Boolean(definition.concurrency && definition.concurrency.exclusive !== false);
+        const retry = this.translateRetry(definition);
+        return createTriggerTask({
+            id: definition.slug,
+            ...(exclusive
+                ? {
+                    queue: {
+                        name: `${this.queuePrefix}-${definition.slug.replaceAll("/", "-")}`,
+                        concurrencyLimit: 1,
+                    },
+                }
+                : {}),
+            ...(retry ? { retry } : {}),
+            run: async (payload, { ctx }) => {
+                const result = await definition.handler({
+                    input: payload.input,
+                    ctx: this.requireSetup().context,
+                    job: {
+                        attemptNumber: ctx.attempt.number,
+                        maxAttempts: payload.maxAttempts,
+                    },
+                });
+                return result.output;
+            },
+        });
+    }
+    translateRetry(definition) {
+        const retries = definition.retries;
+        if (!retries)
+            return undefined;
+        const delay = retries.backoff?.delay ?? 1_000;
+        return {
+            maxAttempts: retries.attempts,
+            factor: retries.backoff?.type === "exponential" ? 2 : 1,
+            minTimeoutInMs: delay,
+            ...(retries.backoff?.type === "fixed" ? { maxTimeoutInMs: delay } : {}),
+            randomize: false,
+        };
+    }
+    requireSetup() {
+        if (!this.setup)
+            throw new Error("TriggerExecutionEngine must be registered before use.");
+        return this.setup;
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@porulle/jobs-trigger",
+  "version": "0.9.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@trigger.dev/sdk": "^4.5.4",
+    "@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": "Trigger.dev 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-trigger"
+  },
+  "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,140 @@
+import {
+  task as createTriggerTask,
+  tasks as triggerTasks,
+} from "@trigger.dev/sdk";
+import type { AnyTask } from "@trigger.dev/sdk";
+import type {
+  EnqueueOptions,
+  ExecutionEngine,
+  ExecutionEngineSetup,
+  TaskDefinition,
+} from "@porulle/core";
+
+interface TriggerJobPayload {
+  input: Record<string, unknown>;
+  organizationId: string;
+  maxAttempts: number;
+  concurrencyKey?: string;
+}
+
+type DebounceDelay = "1s" | "2s" | "5s" | "10s" | "30s" | "1m";
+
+export interface TriggerExecutionEngineOptions {
+  queuePrefix?: string;
+  supersedesDebounce?: DebounceDelay;
+}
+
+export class TriggerExecutionEngine implements ExecutionEngine {
+  readonly execution = { mode: "push" as const };
+  readonly tasks: AnyTask[] = [];
+
+  private readonly queuePrefix: string;
+  private readonly supersedesDebounce: DebounceDelay;
+  private setup: ExecutionEngineSetup | undefined;
+
+  constructor(options: TriggerExecutionEngineOptions = {}) {
+    this.queuePrefix = options.queuePrefix ?? "porulle";
+    this.supersedesDebounce = options.supersedesDebounce ?? "1s";
+  }
+
+  register(setup: ExecutionEngineSetup): void {
+    this.setup = setup;
+    this.tasks.splice(0, this.tasks.length);
+    for (const definition of setup.tasks.values()) {
+      this.tasks.push(this.createTask(definition));
+    }
+  }
+
+  async enqueue(
+    taskSlug: string,
+    input: Record<string, unknown>,
+    options: EnqueueOptions,
+  ): Promise<string> {
+    const definition = this.requireSetup().tasks.get(taskSlug);
+    if (!definition) 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 concurrencyKey =
+      options.concurrencyKey ?? definition.concurrency?.key(input);
+    const exclusive = Boolean(
+      definition.concurrency && definition.concurrency.exclusive !== false,
+    );
+    const supersedes = options.supersedes ?? definition.concurrency?.supersedes;
+    const maxAttempts =
+      options.maxAttempts ?? definition.retries?.attempts ?? 1;
+    const payload: TriggerJobPayload = {
+      input,
+      organizationId,
+      maxAttempts,
+      ...(concurrencyKey ? { concurrencyKey } : {}),
+    };
+    const handle = await triggerTasks.trigger(taskSlug, payload, {
+      maxAttempts,
+      ...(exclusive && concurrencyKey ? { concurrencyKey } : {}),
+      ...(options.delayMs !== undefined
+        ? { delay: new Date(Date.now() + options.delayMs) }
+        : {}),
+      ...(supersedes && concurrencyKey
+        ? {
+            debounce: {
+              key: concurrencyKey,
+              delay: this.supersedesDebounce,
+              mode: "trailing" as const,
+            },
+          }
+        : {}),
+    });
+    return handle.id;
+  }
+
+  private createTask(definition: TaskDefinition): AnyTask {
+    const exclusive = Boolean(
+      definition.concurrency && definition.concurrency.exclusive !== false,
+    );
+    const retry = this.translateRetry(definition);
+    return createTriggerTask({
+      id: definition.slug,
+      ...(exclusive
+        ? {
+            queue: {
+              name: `${this.queuePrefix}-${definition.slug.replaceAll("/", "-")}`,
+              concurrencyLimit: 1,
+            },
+          }
+        : {}),
+      ...(retry ? { retry } : {}),
+      run: async (payload: TriggerJobPayload, { ctx }) => {
+        const result = await definition.handler({
+          input: payload.input,
+          ctx: this.requireSetup().context,
+          job: {
+            attemptNumber: ctx.attempt.number,
+            maxAttempts: payload.maxAttempts,
+          },
+        });
+        return result.output;
+      },
+    });
+  }
+
+  private translateRetry(definition: TaskDefinition) {
+    const retries = definition.retries;
+    if (!retries) return undefined;
+    const delay = retries.backoff?.delay ?? 1_000;
+    return {
+      maxAttempts: retries.attempts,
+      factor: retries.backoff?.type === "exponential" ? 2 : 1,
+      minTimeoutInMs: delay,
+      ...(retries.backoff?.type === "fixed" ? { maxTimeoutInMs: delay } : {}),
+      randomize: false,
+    };
+  }
+
+  private requireSetup(): ExecutionEngineSetup {
+    if (!this.setup)
+      throw new Error("TriggerExecutionEngine must be registered before use.");
+    return this.setup;
+  }
+}