@farm.js/jobs 0.1.49 → 0.1.51-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +124 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,132 @@
1
1
  # @farm.js/jobs
2
2
 
3
- Jobs integration primitives for Farm.js
3
+ Background jobs for Farm.js applications on Trigger.dev or Inngest. Tasks are declared once with
4
+ typed input and output, and the integration mounts routes to trigger, batch, schedule, check, and
5
+ cancel runs on the selected provider.
4
6
 
5
7
  See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
6
8
 
9
+ ## Install
10
+
7
11
  ```bash
8
- npm install @farm.js/jobs
12
+ pnpm add @farm.js/jobs
13
+ ```
14
+
15
+ The package has no provider SDK dependency: it calls the Trigger.dev and Inngest APIs over HTTP. To
16
+ scaffold the registry entry and a jobs console in an existing app, run
17
+ `farm add integration trigger --ui` or `farm add integration inngest --ui`.
18
+
19
+ ## How it runs
20
+
21
+ Farm is the control plane. It starts runs of a task or function that already exists on the
22
+ provider and reads their status back. It does not execute or deploy the local `run` callback, so
23
+ deploy matching provider code and keep its input and output in step with the task definition.
24
+
25
+ A task's provider id is its `id`, or its key in kebab case, such as `send-welcome-email`.
26
+ Trigger.dev runs the task with that id. Inngest receives the event `farm/send-welcome-email`, and
27
+ `eventNamePrefix` changes the `farm` prefix.
28
+
29
+ ## Configure
30
+
31
+ ```ts
32
+ // src/lib/jobs.ts
33
+ import { defineTasks, task } from "@farm.js/jobs";
34
+
35
+ export const tasks = defineTasks({
36
+ sendWelcomeEmail: task({
37
+ defaults: { retry: { attempts: 3 }, tags: ["email"] },
38
+ async run(input: { userId: string }) {
39
+ return { messageId: `msg_${input.userId}` };
40
+ },
41
+ }),
42
+ });
9
43
  ```
10
44
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
45
+ ```ts
46
+ // src/lib/integrations.ts
47
+ import { jobs, trigger } from "@farm.js/jobs";
48
+ import { tasks } from "./jobs";
49
+
50
+ export const appIntegrations = {
51
+ jobs: jobs({ runtime: trigger({ apiKey: process.env.TRIGGER_SECRET_KEY }), tasks }),
52
+ } as const;
53
+ ```
54
+
55
+ Use `runtime: inngest({ ... })` to run on Inngest instead. Settings fall back to the environment:
56
+
57
+ | Variable | Purpose |
58
+ | --------------------- | --------------------------------------------------- |
59
+ | `TRIGGER_SECRET_KEY` | Trigger.dev key for triggering, status, and cancel. |
60
+ | `TRIGGER_PROJECT_REF` | Trigger.dev project reference, as `projectRef`. |
61
+ | `INNGEST_EVENT_KEY` | Sends Inngest events. |
62
+ | `INNGEST_SIGNING_KEY` | Reads Inngest run status. |
63
+ | `INNGEST_APP_ID` | Inngest app id, as `appId`. |
64
+
65
+ `apiBaseUrl`, and `eventBaseUrl` on Inngest, point at another API host.
66
+
67
+ ## Trigger and check runs
68
+
69
+ Server code calls the routes through `api` from `createIntegrations` in `@farm.js/core/client`.
70
+ Task input goes directly in `body`, and launch options go under `$options`. Use `$input` for the
71
+ input when it has its own `input` or `options` fields.
72
+
73
+ ```ts
74
+ const queued = await api.jobs.sendWelcomeEmail.trigger({
75
+ body: { userId: "usr_123", $options: { delay: "10m", tags: ["signup"] } },
76
+ });
77
+
78
+ const run = await api.jobs.sendWelcomeEmail.status({
79
+ query: { handleId: queued.data!.handleId },
80
+ });
81
+
82
+ if (run.data?.status === "completed") console.log(run.data.output);
83
+ ```
84
+
85
+ `schedule` takes `$schedule: { at }` or `$schedule: { after }`, `batchTrigger` takes `items`, and
86
+ `cancel` takes a `handleId`, so keep handle ids that later requests need.
87
+
88
+ ## Routes and access
89
+
90
+ Each task mounts `trigger`, `batch-trigger`, `schedule`, `status`, and `cancel` under
91
+ `/api/jobs/<task>`, with the task key in kebab case. `GET /api/jobs/tasks` lists task metadata, and
92
+ `basePath` moves them all.
93
+
94
+ The routes answer only in-process server calls through `api` by default, and HTTP requests get
95
+ `403`. To let HTTP callers, such as `apiClient` in the browser, reach them, pass `authorize`:
96
+
97
+ ```ts
98
+ jobs({
99
+ runtime,
100
+ tasks,
101
+ async authorize(request) {
102
+ const user = await getUser(request);
103
+ return user ? { caller: user.id } : false;
104
+ },
105
+ });
106
+ ```
107
+
108
+ It also receives `{ task, operation }`. Return `true`, `{ caller }`, `false` for `403`, or a
109
+ `Response`. `status` and `cancel` accept any handle id, so check that the run belongs to the
110
+ caller. An HTTP caller's `idempotencyKey` is scoped to the task and the returned `caller`, and the
111
+ task's own `defaults.idempotencyKey` wins over it.
112
+
113
+ ## Runtime capabilities
114
+
115
+ | Capability | Trigger.dev | Inngest |
116
+ | ---------------------------------------------------------- | ----------- | ------- |
117
+ | delay, schedule, batch trigger, idempotency key | yes | yes |
118
+ | debounce, tags, cancel, queue, retry, ttl, concurrency key | yes | no |
119
+
120
+ `jobs()` throws at startup when an Inngest task sets `queue`, `retry`, `ttl`, `concurrencyKey`, or
121
+ `tags` defaults. Task metadata carries `capabilities`, which `supportsJobsRuntimeCapability` reads.
122
+
123
+ ## Documentation
124
+
125
+ - [Jobs integration](https://farmjs.dev/docs/integrations/jobs)
126
+ - [Trigger.dev](https://farmjs.dev/docs/integrations/trigger) and
127
+ [Inngest](https://farmjs.dev/docs/integrations/inngest)
128
+ - [`examples/jobs-integration`](https://github.com/farming-labs/farm.js/tree/main/examples/jobs-integration)
129
+ switches between both runtimes with `JOBS_RUNTIME`
130
+
131
+ Report issues and find examples in the
132
+ [Farm.js repository](https://github.com/farming-labs/farm.js).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@farm.js/jobs",
3
- "version": "0.1.49",
3
+ "version": "0.1.51-beta.0",
4
4
  "description": "Jobs integration primitives for Farm.js",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -25,8 +25,8 @@
25
25
  "access": "public"
26
26
  },
27
27
  "dependencies": {
28
- "@farm.js/core": "0.1.49",
29
- "@farm.js/integration-utils": "0.1.49"
28
+ "@farm.js/core": "0.1.51-beta.0",
29
+ "@farm.js/integration-utils": "0.1.51-beta.0"
30
30
  },
31
31
  "scripts": {
32
32
  "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",