bunqueue-client 0.1.0 → 0.1.1
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.
- package/README.md +56 -66
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,30 @@
|
|
|
1
|
-
# bunqueue-client
|
|
1
|
+
# bunqueue-client
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
the high-performance job queue server. Talks the native TCP protocol
|
|
5
|
-
(msgpack, pipelined, port 6789) — feature parity with the built-in Bun client,
|
|
6
|
-
but runs on **any** modern JS/TS runtime.
|
|
3
|
+
Official TypeScript client for [bunqueue](https://github.com/egeominotti/bunqueue), the high performance job queue server. The client implements the native TCP protocol (msgpack, pipelined) and provides full feature parity with the built in Bun client, while running on every modern JavaScript runtime.
|
|
7
4
|
|
|
8
|
-
The bunqueue
|
|
9
|
-
Node, Bun, or Deno service produce and consume jobs on it: *one queue, any
|
|
10
|
-
language, any runtime*.
|
|
5
|
+
The bunqueue server runs on Bun, distributed as a binary or a Docker image. This client allows any Node.js, Bun, Deno, or Cloudflare Workers service to produce and consume jobs against it: one queue, any language, any runtime.
|
|
11
6
|
|
|
12
|
-
##
|
|
7
|
+
## Compatibility
|
|
13
8
|
|
|
14
9
|
| Runtime | Status | Notes |
|
|
15
10
|
|---|---|---|
|
|
16
|
-
| Node.js
|
|
17
|
-
| Bun |
|
|
18
|
-
| Deno
|
|
19
|
-
| tsx
|
|
20
|
-
| Cloudflare Workers |
|
|
21
|
-
| Browser |
|
|
11
|
+
| Node.js 20 or later | Supported, 58/58 e2e and 8/8 integration tests | ESM. TypeScript files run directly on Node 22 or later via `--experimental-strip-types` |
|
|
12
|
+
| Bun | Supported, 58/58 e2e and 8/8 integration tests | No additional configuration required |
|
|
13
|
+
| Deno 2 or later | Supported, 58/58 e2e and 8/8 integration tests | Uses `node:` builtins and the npm `msgpackr` package |
|
|
14
|
+
| tsx, ts-node, vitest, jest | Supported | These environments execute on Node.js |
|
|
15
|
+
| Cloudflare Workers | Supported, 11/11 e2e tests inside workerd | Requires the `nodejs_compat` compatibility flag. The runtime is request scoped, so long lived worker loops are not available: consume in batches from Cron Triggers or Durable Object alarms, a pattern covered by the test suite. TLS connections require a publicly trusted certificate |
|
|
16
|
+
| Browser | Not supported | Raw TCP sockets are unavailable. Use the server HTTP API instead |
|
|
22
17
|
|
|
23
|
-
|
|
24
|
-
(`net`, `tls`, `events`, `crypto`, `os`) — no `Bun.*` globals, no
|
|
25
|
-
`bun:`/`deno:` imports. Single runtime dependency: `msgpackr`.
|
|
18
|
+
Portability is guaranteed by design: the client relies exclusively on `node:*` builtins (`net`, `tls`, `events`, `crypto`, `os`), uses no `Bun.*` globals and no runtime specific imports, and carries a single runtime dependency, `msgpackr`.
|
|
26
19
|
|
|
27
|
-
##
|
|
20
|
+
## Installation
|
|
28
21
|
|
|
29
22
|
```bash
|
|
30
|
-
npm install bunqueue-client
|
|
23
|
+
npm install bunqueue-client
|
|
24
|
+
# or: bun add bunqueue-client / pnpm add bunqueue-client / deno add npm:bunqueue-client
|
|
31
25
|
```
|
|
32
26
|
|
|
33
|
-
##
|
|
27
|
+
## Producing jobs
|
|
34
28
|
|
|
35
29
|
```typescript
|
|
36
30
|
import { Queue } from 'bunqueue-client';
|
|
@@ -47,7 +41,7 @@ const counts = await queue.getJobCounts();
|
|
|
47
41
|
queue.close();
|
|
48
42
|
```
|
|
49
43
|
|
|
50
|
-
##
|
|
44
|
+
## Processing jobs
|
|
51
45
|
|
|
52
46
|
```typescript
|
|
53
47
|
import { Worker, UnrecoverableError } from 'bunqueue-client';
|
|
@@ -56,7 +50,7 @@ const worker = new Worker(
|
|
|
56
50
|
'emails',
|
|
57
51
|
async (job) => {
|
|
58
52
|
await job.updateProgress(50);
|
|
59
|
-
if (job.data.invalid) throw new UnrecoverableError('bad payload'); // no retries
|
|
53
|
+
if (job.data.invalid) throw new UnrecoverableError('bad payload'); // no retries, straight to the DLQ
|
|
60
54
|
return { sent: true };
|
|
61
55
|
},
|
|
62
56
|
{ host: 'localhost', port: 6789, concurrency: 10 }
|
|
@@ -65,11 +59,10 @@ const worker = new Worker(
|
|
|
65
59
|
worker.on('completed', (job, result) => console.log(job.id, result));
|
|
66
60
|
worker.on('failed', (job, err) => console.error(job.id, err.message));
|
|
67
61
|
|
|
68
|
-
// later: await worker.close(); // graceful
|
|
62
|
+
// later: await worker.close(); // graceful shutdown, waits for in flight jobs
|
|
69
63
|
```
|
|
70
64
|
|
|
71
|
-
Retry, backoff,
|
|
72
|
-
**server-side** — the worker only pulls, heartbeats and acks.
|
|
65
|
+
Retry, backoff, dead letter queue, stall detection, priorities, and rate limiting all execute server side. The worker only pulls, heartbeats, and acknowledges, which keeps the client thin and the behavior consistent across languages.
|
|
73
66
|
|
|
74
67
|
## Flows
|
|
75
68
|
|
|
@@ -78,14 +71,14 @@ import { FlowProducer } from 'bunqueue-client';
|
|
|
78
71
|
|
|
79
72
|
const flow = new FlowProducer({ host: 'localhost', port: 6789 });
|
|
80
73
|
|
|
81
|
-
// sequential chain: step1
|
|
74
|
+
// sequential chain: step1, then step2, then step3
|
|
82
75
|
await flow.addChain([
|
|
83
76
|
{ name: 'step1', queueName: 'pipeline' },
|
|
84
77
|
{ name: 'step2', queueName: 'pipeline' },
|
|
85
78
|
{ name: 'step3', queueName: 'pipeline' },
|
|
86
79
|
]);
|
|
87
80
|
|
|
88
|
-
// fan
|
|
81
|
+
// fan in: parallel jobs converge into a final job that reads their results
|
|
89
82
|
const { finalId } = await flow.addBulkThen(
|
|
90
83
|
[
|
|
91
84
|
{ name: 'part1', queueName: 'pipeline' },
|
|
@@ -95,7 +88,7 @@ const { finalId } = await flow.addBulkThen(
|
|
|
95
88
|
);
|
|
96
89
|
// inside the 'merge' processor: await job.getChildrenValues()
|
|
97
90
|
|
|
98
|
-
// parent
|
|
91
|
+
// parent and child tree: children always run before the parent
|
|
99
92
|
const node = await flow.add({
|
|
100
93
|
name: 'assemble', queueName: 'orders',
|
|
101
94
|
children: [
|
|
@@ -105,7 +98,7 @@ const node = await flow.add({
|
|
|
105
98
|
});
|
|
106
99
|
```
|
|
107
100
|
|
|
108
|
-
##
|
|
101
|
+
## Scheduling
|
|
109
102
|
|
|
110
103
|
```typescript
|
|
111
104
|
await queue.addCron('daily-report', '0 9 * * *', { type: 'report' });
|
|
@@ -113,53 +106,50 @@ await queue.every('health-ping', 30_000, { type: 'ping' });
|
|
|
113
106
|
await queue.removeJobScheduler('daily-report');
|
|
114
107
|
```
|
|
115
108
|
|
|
116
|
-
##
|
|
109
|
+
## Security
|
|
117
110
|
|
|
118
111
|
```typescript
|
|
119
112
|
const queue = new Queue('emails', {
|
|
120
113
|
host: 'queue.example.com',
|
|
121
114
|
port: 6789,
|
|
122
115
|
token: process.env.BUNQUEUE_TOKEN,
|
|
123
|
-
tls: { caFile: './ca.pem' }, // or `true` for system
|
|
116
|
+
tls: { caFile: './ca.pem' }, // or `true` for system certificate authorities
|
|
124
117
|
});
|
|
125
118
|
```
|
|
126
119
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
`QueueEvents` (in-process subscription — use webhooks or the HTTP SSE/WS
|
|
146
|
-
endpoints instead).
|
|
147
|
-
|
|
148
|
-
## Development
|
|
120
|
+
Authentication uses server side tokens (`AUTH_TOKENS`). Transport security uses native TLS, with support for system certificate authorities, a custom CA bundle, or disabled verification for development environments.
|
|
121
|
+
|
|
122
|
+
## API surface
|
|
123
|
+
|
|
124
|
+
| Area | Capabilities |
|
|
125
|
+
|---|---|
|
|
126
|
+
| Queue | `add`, `addBulk`, full `JobOptions`: priority, delay, attempts, backoff, ttl, timeout, jobId, deduplication, dependsOn, tags, groupId, lifo, removeOnComplete, removeOnFail, durable, repeat, debounce |
|
|
127
|
+
| Query | `getJob`, `getJobByCustomId`, `getJobs` with per state helpers, state, result, progress, `waitForJob`, counts, counts per priority, children values, job logs |
|
|
128
|
+
| Control | pause, resume, drain, obliterate, clean, remove, discard, promote, `retryJob`, `retryJobs`, move to wait or delayed, change priority or delay, update data, extend lock |
|
|
129
|
+
| Dead letter queue | `getDlq`, `retryDlq`, `purgeDlq`, DLQ configuration |
|
|
130
|
+
| Administration | rate limiting, global concurrency, stall configuration, webhooks, stats, metrics, `listQueues`, `getWorkers` |
|
|
131
|
+
| Worker events | `ready`, `active`, `completed`, `failed`, `progress`, `drained`, `error`, `closed`, with automatic lock heartbeats so that jobs longer than the lock TTL survive |
|
|
132
|
+
|
|
133
|
+
The following features require the in process Bun runtime and are intentionally out of scope for this client: embedded mode, sandboxed workers, and `QueueEvents`. Use webhooks or the HTTP SSE and WebSocket endpoints for event streaming.
|
|
134
|
+
|
|
135
|
+
## Quality assurance
|
|
136
|
+
|
|
137
|
+
Every release is validated against a real bunqueue server, spawned fresh for each run, across every supported runtime:
|
|
149
138
|
|
|
150
139
|
```bash
|
|
151
140
|
bun install
|
|
152
|
-
bun run build # tsc
|
|
153
|
-
bun run check #
|
|
154
|
-
|
|
155
|
-
#
|
|
156
|
-
bun tests/
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
bun run test:workers # full suite INSIDE workerd (Cloudflare Workers)
|
|
141
|
+
bun run build # tsc, emits dist/
|
|
142
|
+
bun run check # Biome lint and format verification
|
|
143
|
+
|
|
144
|
+
bun tests/integration.ts # smoke suite
|
|
145
|
+
bun tests/e2e.ts # full surface, edge cases, realistic load
|
|
146
|
+
node --experimental-strip-types tests/e2e.ts # identical suite on Node 22 or later
|
|
147
|
+
deno run -A tests/e2e.ts # identical suite on Deno 2 or later
|
|
148
|
+
bun run test:workers # full suite inside workerd, the Cloudflare Workers runtime
|
|
161
149
|
```
|
|
162
150
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
151
|
+
The e2e suite includes payload limits, unicode integrity, pipelining under concurrency, server crash and restart with automatic reconnection, and a realistic multi queue production scenario with zero loss accounting. Engineering standards: Biome, a maximum of 250 lines per file, and relative imports with explicit `.js` extensions for NodeNext resolution. See `CLAUDE.md` for the full development guide and wire protocol notes.
|
|
152
|
+
|
|
153
|
+
## License
|
|
154
|
+
|
|
155
|
+
MIT. See the [LICENSE](./LICENSE) file. Documentation: [bunqueue.dev/guide/sdks](https://bunqueue.dev/guide/sdks/). Issues and feature requests: [GitHub issues](https://github.com/egeominotti/bunqueue/issues).
|
package/package.json
CHANGED