observed-js 0.1.0 → 0.3.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.
- package/README.md +86 -562
- package/dist/actions/index.d.ts +201 -1
- package/dist/actions/index.d.ts.map +1 -1
- package/dist/actions/index.js +1002 -86
- package/dist/actions/index.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/scheduler/index.d.ts +74 -2
- package/dist/scheduler/index.d.ts.map +1 -1
- package/dist/scheduler/index.js +198 -5
- package/dist/scheduler/index.js.map +1 -1
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,589 +1,113 @@
|
|
|
1
1
|
# observed-js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Action scheduling for async handlers with concurrency + sliding-window rate limiting, plus “wide events” observability (attachments, retries, timeouts, cancellation, progress).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
- Zero deps, ESM-only. Node >= 18.
|
|
6
|
+
- Types infer from your handler (no explicit generics).
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
- Observability - built for wide events
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
- 🔄 **Concurrency Control** - Limit parallel execution to manage resource usage
|
|
11
|
-
- ⏱️ **Rate Limiting** - Sliding window algorithm for precise throttling
|
|
12
|
-
- 🔁 **Automatic Retry** - Configurable backoff strategies (linear/exponential) with jitter
|
|
13
|
-
- 📊 **Wide Events** - Capture rich, structured context for every invocation
|
|
14
|
-
- 📦 **Batch Operations** - Process multiple items with `invokeAll()` or stream results with `invokeStream()`
|
|
15
|
-
- 💪 **Type Safe** - Full TypeScript support with automatic type inference from handlers
|
|
16
|
-
- 🪶 **Zero Dependencies** - Lightweight and focused
|
|
17
|
-
|
|
18
|
-
## Installation
|
|
10
|
+
## Install
|
|
19
11
|
|
|
20
12
|
```bash
|
|
21
13
|
npm install observed-js
|
|
22
14
|
```
|
|
23
15
|
|
|
24
|
-
## Quick
|
|
25
|
-
|
|
26
|
-
```typescript
|
|
27
|
-
import { createAction } from "observed-js";
|
|
28
|
-
|
|
29
|
-
// Create an action with automatic type inference
|
|
30
|
-
const fetchUser = createAction(async (userId: string) => {
|
|
31
|
-
const response = await fetch(`/api/users/${userId}`);
|
|
32
|
-
return response.json();
|
|
33
|
-
})
|
|
34
|
-
.setConcurrency(5) // Max 5 parallel requests
|
|
35
|
-
.setRateLimit(10) // Max 10 requests/second
|
|
36
|
-
.setRetry({ // Retry on failure
|
|
37
|
-
maxRetries: 3,
|
|
38
|
-
backoff: 'exponential',
|
|
39
|
-
baseDelay: 100
|
|
40
|
-
});
|
|
41
|
-
|
|
42
|
-
// Invoke the action
|
|
43
|
-
const { actionId, data } = fetchUser.invoke("user-123");
|
|
44
|
-
const user = await data; // Type-safe result
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
## Core Concepts
|
|
48
|
-
|
|
49
|
-
### Actions
|
|
50
|
-
|
|
51
|
-
Actions are created using `createAction()` with an async handler function. The library automatically infers input and output types:
|
|
52
|
-
|
|
53
|
-
```typescript
|
|
54
|
-
const processImage = createAction(async (imageUrl: string, width: number) => {
|
|
55
|
-
// Process the image...
|
|
56
|
-
return { url: processedUrl, dimensions: { width, height } };
|
|
57
|
-
});
|
|
58
|
-
|
|
59
|
-
// TypeScript knows the exact input and output types
|
|
60
|
-
const result = await processImage.invoke("image.jpg", 800).data;
|
|
61
|
-
// result is typed as { url: string, dimensions: { width: number, height: number } }
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### Concurrency Control
|
|
65
|
-
|
|
66
|
-
Limit how many operations run in parallel:
|
|
67
|
-
|
|
68
|
-
```typescript
|
|
69
|
-
const action = createAction(handler)
|
|
70
|
-
.setConcurrency(3); // Max 3 concurrent executions
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
Default is **1** (sequential execution) for safe-by-default behavior.
|
|
74
|
-
|
|
75
|
-
### Rate Limiting
|
|
76
|
-
|
|
77
|
-
Control execution rate using a sliding window algorithm:
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
const action = createAction(handler)
|
|
81
|
-
.setRateLimit(100); // Max 100 executions per second
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
Tasks exceeding the limit are automatically queued and executed when the window allows.
|
|
85
|
-
|
|
86
|
-
### Retry with Backoff
|
|
87
|
-
|
|
88
|
-
Automatically retry failed operations with configurable strategies:
|
|
89
|
-
|
|
90
|
-
```typescript
|
|
91
|
-
const action = createAction(handler)
|
|
92
|
-
.setRetry({
|
|
93
|
-
maxRetries: 3, // Number of retry attempts
|
|
94
|
-
backoff: 'exponential', // 'linear' or 'exponential'
|
|
95
|
-
baseDelay: 100, // Base delay in ms
|
|
96
|
-
maxDelay: 10000, // Cap for exponential growth
|
|
97
|
-
jitter: true, // Add randomness to prevent thundering herd
|
|
98
|
-
shouldRetry: (error) => { // Optional: selective retry
|
|
99
|
-
return error instanceof NetworkError;
|
|
100
|
-
}
|
|
101
|
-
});
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
**Backoff strategies:**
|
|
105
|
-
- **Linear**: `baseDelay * attemptNumber`
|
|
106
|
-
- **Exponential**: `baseDelay * 2^(attemptNumber - 1)` (capped at `maxDelay`)
|
|
107
|
-
- **Jitter**: Multiplies delay by random factor (0.5 to 1.0) when enabled
|
|
108
|
-
|
|
109
|
-
### Wide Events
|
|
16
|
+
## Quick start
|
|
110
17
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
```typescript
|
|
18
|
+
```ts
|
|
114
19
|
import { createAction, withContext } from "observed-js";
|
|
115
20
|
|
|
116
|
-
const
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
ctx.attach("queryDurationMs", result.duration);
|
|
125
|
-
|
|
126
|
-
return result;
|
|
127
|
-
})
|
|
128
|
-
).onEvent((event) => {
|
|
129
|
-
logger.info({
|
|
130
|
-
actionId: event.actionId,
|
|
131
|
-
input: event.input,
|
|
132
|
-
output: event.output,
|
|
133
|
-
duration: event.duration,
|
|
134
|
-
attachments: event.attachments, // All attached context
|
|
135
|
-
error: event.error
|
|
136
|
-
});
|
|
137
|
-
});
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
**Context features:**
|
|
141
|
-
- `.attach(key, value)` for single key-value pairs
|
|
142
|
-
- `.attach(object)` for bulk attachment
|
|
143
|
-
- Objects are deep-merged when attaching to the same key
|
|
144
|
-
- Primitives overwrite previous values
|
|
145
|
-
|
|
146
|
-
### Batch Operations
|
|
147
|
-
|
|
148
|
-
Process multiple items with two different patterns:
|
|
149
|
-
|
|
150
|
-
#### `invokeAll()` - Promise.all style
|
|
151
|
-
|
|
152
|
-
Returns all results in input order (using Promise.allSettled internally):
|
|
153
|
-
|
|
154
|
-
```typescript
|
|
155
|
-
const action = createAction(handler);
|
|
156
|
-
|
|
157
|
-
const results = await action.invokeAll([
|
|
158
|
-
["input1"],
|
|
159
|
-
["input2"],
|
|
160
|
-
["input3"]
|
|
161
|
-
]);
|
|
162
|
-
|
|
163
|
-
// Each result is a discriminated union
|
|
164
|
-
results.forEach((result, index) => {
|
|
165
|
-
if (result.error) {
|
|
166
|
-
console.error(`Item ${index} failed:`, result.error);
|
|
167
|
-
} else {
|
|
168
|
-
console.log(`Item ${index} succeeded:`, result.data);
|
|
169
|
-
}
|
|
170
|
-
});
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
#### `invokeStream()` - AsyncGenerator
|
|
174
|
-
|
|
175
|
-
Yields results as they complete (out-of-order):
|
|
176
|
-
|
|
177
|
-
```typescript
|
|
178
|
-
const action = createAction(handler).setConcurrency(5);
|
|
179
|
-
|
|
180
|
-
for await (const result of action.invokeStream([
|
|
181
|
-
["input1"],
|
|
182
|
-
["input2"],
|
|
183
|
-
["input3"]
|
|
184
|
-
])) {
|
|
185
|
-
console.log(`Completed item ${result.index}`);
|
|
186
|
-
if (result.error) {
|
|
187
|
-
console.error("Failed:", result.error);
|
|
188
|
-
} else {
|
|
189
|
-
console.log("Success:", result.data);
|
|
190
|
-
}
|
|
191
|
-
}
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Both methods:
|
|
195
|
-
- Work with concurrency and rate limiting
|
|
196
|
-
- Individual failures don't fail the entire batch
|
|
197
|
-
- Return discriminated unions with `data` or `error`
|
|
198
|
-
|
|
199
|
-
## API Reference
|
|
200
|
-
|
|
201
|
-
### `createAction(handler)`
|
|
202
|
-
|
|
203
|
-
Creates a new action with automatic type inference.
|
|
204
|
-
|
|
205
|
-
**Parameters:**
|
|
206
|
-
- `handler: (...args: I) => Promise<O> | O` - Async function to execute
|
|
207
|
-
|
|
208
|
-
**Returns:** `ActionBuilder<I, O>`
|
|
209
|
-
|
|
210
|
-
```typescript
|
|
211
|
-
const action = createAction(async (input: string) => {
|
|
212
|
-
return { result: input.toUpperCase() };
|
|
213
|
-
});
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
### `withContext(handler)`
|
|
217
|
-
|
|
218
|
-
Wraps a handler to receive `InvocationContext` as the first parameter.
|
|
219
|
-
|
|
220
|
-
**Parameters:**
|
|
221
|
-
- `handler: (ctx: InvocationContext, ...args: I) => Promise<O> | O`
|
|
222
|
-
|
|
223
|
-
**Returns:** Handler function compatible with `createAction()`
|
|
224
|
-
|
|
225
|
-
```typescript
|
|
226
|
-
const action = createAction(
|
|
227
|
-
withContext(async (ctx, input: string) => {
|
|
228
|
-
ctx.attach("inputLength", input.length);
|
|
229
|
-
return process(input);
|
|
230
|
-
})
|
|
231
|
-
);
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
### `ActionBuilder` Methods
|
|
235
|
-
|
|
236
|
-
#### `.setConcurrency(limit: number)`
|
|
237
|
-
|
|
238
|
-
Set maximum concurrent executions (default: 1).
|
|
239
|
-
|
|
240
|
-
```typescript
|
|
241
|
-
action.setConcurrency(5);
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
#### `.setRateLimit(limit: number)`
|
|
245
|
-
|
|
246
|
-
Set maximum executions per second (default: Infinity).
|
|
247
|
-
|
|
248
|
-
```typescript
|
|
249
|
-
action.setRateLimit(100);
|
|
250
|
-
```
|
|
251
|
-
|
|
252
|
-
#### `.setRetry(options: RetryOptions)`
|
|
253
|
-
|
|
254
|
-
Configure automatic retry behavior.
|
|
255
|
-
|
|
256
|
-
```typescript
|
|
257
|
-
action.setRetry({
|
|
258
|
-
maxRetries: 3,
|
|
259
|
-
backoff: 'exponential',
|
|
260
|
-
baseDelay: 100,
|
|
261
|
-
maxDelay: 10000,
|
|
262
|
-
jitter: true,
|
|
263
|
-
shouldRetry: (error) => error instanceof TransientError
|
|
264
|
-
});
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
#### `.onEvent(callback: EventCallback)`
|
|
268
|
-
|
|
269
|
-
Register a callback to receive wide events.
|
|
270
|
-
|
|
271
|
-
```typescript
|
|
272
|
-
action.onEvent((event) => {
|
|
273
|
-
console.log({
|
|
274
|
-
actionId: event.actionId,
|
|
275
|
-
duration: event.duration,
|
|
276
|
-
attachments: event.attachments,
|
|
277
|
-
error: event.error
|
|
278
|
-
});
|
|
279
|
-
});
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
#### `.invoke(...args: I)`
|
|
283
|
-
|
|
284
|
-
Execute the action with given arguments.
|
|
285
|
-
|
|
286
|
-
**Returns:** `{ actionId: string, data: Promise<O> }`
|
|
287
|
-
|
|
288
|
-
```typescript
|
|
289
|
-
const { actionId, data } = action.invoke("input");
|
|
290
|
-
const result = await data;
|
|
291
|
-
```
|
|
292
|
-
|
|
293
|
-
#### `.invokeAll(payloads: I[])`
|
|
294
|
-
|
|
295
|
-
Execute multiple invocations, returning all results in order.
|
|
296
|
-
|
|
297
|
-
**Returns:** `Promise<BatchResult<O>[]>`
|
|
298
|
-
|
|
299
|
-
```typescript
|
|
300
|
-
const results = await action.invokeAll([
|
|
301
|
-
["input1"],
|
|
302
|
-
["input2"]
|
|
303
|
-
]);
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
#### `.invokeStream(payloads: I[])`
|
|
307
|
-
|
|
308
|
-
Execute multiple invocations, yielding results as they complete.
|
|
309
|
-
|
|
310
|
-
**Returns:** `AsyncGenerator<BatchResult<O> & { index: number }>`
|
|
311
|
-
|
|
312
|
-
```typescript
|
|
313
|
-
for await (const result of action.invokeStream([["input1"], ["input2"]])) {
|
|
314
|
-
console.log(`Item ${result.index} completed`);
|
|
315
|
-
}
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
### Types
|
|
319
|
-
|
|
320
|
-
#### `InvocationContext`
|
|
321
|
-
|
|
322
|
-
Context object for attaching observability data.
|
|
323
|
-
|
|
324
|
-
```typescript
|
|
325
|
-
interface InvocationContext {
|
|
326
|
-
readonly actionId: string;
|
|
327
|
-
attach(key: string, value: unknown): void;
|
|
328
|
-
attach(data: Record<string, unknown>): void;
|
|
329
|
-
}
|
|
330
|
-
```
|
|
331
|
-
|
|
332
|
-
#### `WideEvent<I, O>`
|
|
333
|
-
|
|
334
|
-
Complete event record after invocation.
|
|
335
|
-
|
|
336
|
-
```typescript
|
|
337
|
-
interface WideEvent<I extends any[], O> {
|
|
338
|
-
actionId: string;
|
|
339
|
-
startedAt: number;
|
|
340
|
-
completedAt: number;
|
|
341
|
-
duration: number;
|
|
342
|
-
input: I;
|
|
343
|
-
output?: O;
|
|
344
|
-
error?: Error;
|
|
345
|
-
attachments: Record<string, unknown>;
|
|
346
|
-
retryAttempt?: number;
|
|
347
|
-
totalAttempts?: number;
|
|
348
|
-
retryDelays?: number[];
|
|
349
|
-
isRetry?: boolean;
|
|
350
|
-
willRetry?: boolean;
|
|
351
|
-
}
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
#### `RetryOptions`
|
|
355
|
-
|
|
356
|
-
Retry configuration options.
|
|
357
|
-
|
|
358
|
-
```typescript
|
|
359
|
-
interface RetryOptions {
|
|
360
|
-
maxRetries: number;
|
|
361
|
-
backoff: 'linear' | 'exponential';
|
|
362
|
-
baseDelay?: number; // Default: 100ms
|
|
363
|
-
maxDelay?: number; // Default: 30000ms
|
|
364
|
-
jitter?: boolean; // Default: false
|
|
365
|
-
shouldRetry?: (error: unknown) => boolean;
|
|
366
|
-
}
|
|
367
|
-
```
|
|
368
|
-
|
|
369
|
-
## Examples
|
|
370
|
-
|
|
371
|
-
Check out the [examples/](examples/) directory for comprehensive examples:
|
|
372
|
-
|
|
373
|
-
- [01-basic-action.ts](examples/01-basic-action.ts) - Basic action creation and invocation
|
|
374
|
-
- [02-concurrency.ts](examples/02-concurrency.ts) - Concurrency control
|
|
375
|
-
- [03-rate-limiting.ts](examples/03-rate-limiting.ts) - Rate limiting
|
|
376
|
-
- [04-wide-events.ts](examples/04-wide-events.ts) - Wide events and context attachment
|
|
377
|
-
- [05-batch-invocation.ts](examples/05-batch-invocation.ts) - Batch processing
|
|
378
|
-
- [06-combining-features.ts](examples/06-combining-features.ts) - Combining multiple features
|
|
379
|
-
- [07-real-world-scenarios.ts](examples/07-real-world-scenarios.ts) - Production use cases
|
|
380
|
-
- [08-error-handling.ts](examples/08-error-handling.ts) - Error handling patterns
|
|
381
|
-
- [09-retry-examples.ts](examples/09-retry-examples.ts) - Retry strategies
|
|
382
|
-
|
|
383
|
-
Run examples with:
|
|
384
|
-
|
|
385
|
-
```bash
|
|
386
|
-
npx tsx examples/01-basic-action.ts
|
|
387
|
-
|
|
388
|
-
# Or run all examples
|
|
389
|
-
npx tsx examples/run-all.ts
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
## Use Cases
|
|
393
|
-
|
|
394
|
-
### API Client with Rate Limiting
|
|
395
|
-
|
|
396
|
-
```typescript
|
|
397
|
-
const apiCall = createAction(async (endpoint: string) => {
|
|
398
|
-
return fetch(`https://api.example.com${endpoint}`).then(r => r.json());
|
|
399
|
-
})
|
|
400
|
-
.setRateLimit(50) // API allows 50 req/sec
|
|
401
|
-
.setConcurrency(10) // Keep 10 connections open
|
|
402
|
-
.setRetry({
|
|
403
|
-
maxRetries: 3,
|
|
404
|
-
backoff: 'exponential',
|
|
405
|
-
baseDelay: 200
|
|
406
|
-
});
|
|
407
|
-
|
|
408
|
-
const data = await apiCall.invoke("/users/123").data;
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
### Image Processing Pipeline
|
|
412
|
-
|
|
413
|
-
```typescript
|
|
414
|
-
const processImage = createAction(
|
|
415
|
-
withContext(async (ctx, imageUrl: string) => {
|
|
416
|
-
ctx.attach("imageUrl", imageUrl);
|
|
417
|
-
|
|
418
|
-
const image = await downloadImage(imageUrl);
|
|
419
|
-
ctx.attach("originalSize", image.size);
|
|
420
|
-
|
|
421
|
-
const processed = await resize(image, 800, 600);
|
|
422
|
-
ctx.attach("processedSize", processed.size);
|
|
423
|
-
|
|
424
|
-
const uploaded = await uploadToStorage(processed);
|
|
425
|
-
ctx.attach("storageUrl", uploaded.url);
|
|
426
|
-
|
|
427
|
-
return uploaded;
|
|
428
|
-
})
|
|
21
|
+
const fetchUser = createAction(
|
|
22
|
+
withContext(async (ctx, userId: string) => {
|
|
23
|
+
ctx.attach({ userId });
|
|
24
|
+
const res = await fetch(`/api/users/${userId}`);
|
|
25
|
+
const user = await res.json();
|
|
26
|
+
ctx.attach({ status: res.status });
|
|
27
|
+
return user;
|
|
28
|
+
})
|
|
429
29
|
)
|
|
430
|
-
.setConcurrency(
|
|
431
|
-
.
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
});
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
const
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
30
|
+
.setConcurrency(5)
|
|
31
|
+
.setRateLimit(10)
|
|
32
|
+
.setRetry({ maxRetries: 3, backoff: "exponential", baseDelay: 100 })
|
|
33
|
+
.onEvent((e) => {
|
|
34
|
+
// `e` includes input/output/error/duration/priority/metadata/attachments
|
|
35
|
+
console.log(e.actionId, e.duration, e.attachments);
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
const { data } = fetchUser.invoke("user-123");
|
|
39
|
+
const user = await data;
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Key ideas
|
|
43
|
+
|
|
44
|
+
### Wrappers opt-in handler extras
|
|
45
|
+
- `withContext((ctx, ...args) => ...)`: enables `ctx.attach()` and handler-driven progress (`ctx.setTotal()`, `ctx.incrementProgress()`).
|
|
46
|
+
- `withAbortSignal((signal, ...args) => ...)`: enables cooperative cancellation and cooperative timeouts via `setTimeout({ abortSignal: true })`.
|
|
47
|
+
|
|
48
|
+
### Batch execution
|
|
49
|
+
- `invokeAll(payloads)`: returns results in input order (individual failures don’t fail the batch).
|
|
50
|
+
- `invokeStream(payloads)`: yields results as they complete (out of order) with an `index`.
|
|
51
|
+
|
|
52
|
+
### Cancellation & timeouts
|
|
53
|
+
- Every invocation handle has `cancel(reason?)`.
|
|
54
|
+
- `ActionBuilder.cancelAll()` cancels active invocations; `ActionBuilder.clearQueue()` cancels queued ones.
|
|
55
|
+
- `setTimeout(ms | { duration, abortSignal?, throwOnTimeout? })` captures timeout metadata in wide events.
|
|
56
|
+
|
|
57
|
+
### Callback isolation
|
|
58
|
+
Errors thrown inside `.onEvent()` / `.onProgress()` are logged and do not fail the action.
|
|
59
|
+
|
|
60
|
+
## API at a glance
|
|
61
|
+
|
|
62
|
+
- Creation: `createAction(handler)`, wrappers: `withContext`, `withAbortSignal`.
|
|
63
|
+
- Builder config: `setConcurrency`, `setRateLimit`, `setPriority`, `setRetry`, `setTimeout`.
|
|
64
|
+
- Observability: `onEvent`, `onProgress`.
|
|
65
|
+
- Invoke: `invoke`, `invokeAll`, `invokeStream`.
|
|
66
|
+
- Control/inspection: `cancelAll`, `clearQueue`, `getQueueLength`, `getActiveCount`.
|
|
67
|
+
|
|
68
|
+
Full types live in `src/actions/index.ts` and are exported from `src/index.ts`.
|
|
69
|
+
|
|
70
|
+
## API reference (compact)
|
|
71
|
+
|
|
72
|
+
| Item | Signature | Notes |
|
|
73
|
+
| --- | --- | --- |
|
|
74
|
+
| Create action | `createAction(handler)` | Infers input/output from `handler`; returns an `ActionBuilder`. |
|
|
75
|
+
| Wrapper (context) | `withContext((ctx, ...args) => handler)` | Enables `ctx.attach()` + handler-driven progress. |
|
|
76
|
+
| Wrapper (abort signal) | `withAbortSignal((signal, ...args) => handler)` | Enables cooperative cancellation + cooperative timeouts (`setTimeout({ abortSignal: true })`). |
|
|
77
|
+
| Invoke | `action.invoke(...args[, { priority, metadata }])` | Returns `{ actionId, data, eventLogged, cancel, cancelled, cancelReason }`. |
|
|
78
|
+
| Batch invoke (all) | `action.invokeAll(payloads[, { priority, metadata }])` | Returns `BatchResult[]` in input order; each item is `{ data }` or `{ error }`. |
|
|
79
|
+
| Batch invoke (stream) | `action.invokeStream(payloads[, { priority, metadata }])` | Yields `BatchResult` as each completes (out of order) with `index`. |
|
|
80
|
+
| Configure | `.setConcurrency(n)`, `.setRateLimit(n)`, `.setPriority(p)` | Priority is `low\|normal\|high\|critical\|number` (0–100). |
|
|
81
|
+
| Retry | `.setRetry({ maxRetries, backoff, ... })` | Backoff is `linear` or `exponential` (+ optional jitter / shouldRetry). |
|
|
82
|
+
| Timeout | `.setTimeout(ms \| { duration, abortSignal?, throwOnTimeout? })` | Emits timeout metadata in `WideEvent`; `TimeoutError` available. |
|
|
83
|
+
| Events/progress | `.onEvent(cb)`, `.onProgress(cb[, { throttle }])` | Callback errors are isolated (logged, not thrown). |
|
|
84
|
+
| Cancellation | `handle.cancel(reason?)`, `action.cancelAll(...)`, `action.clearQueue(...)` | Cancel state is captured in `WideEvent` (`CancellationError` available). |
|
|
443
85
|
|
|
444
|
-
|
|
86
|
+
## Examples
|
|
445
87
|
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
const deliverWebhook = createAction(
|
|
450
|
-
withContext(async (ctx, payload: WebhookPayload) => {
|
|
451
|
-
ctx.attach("webhookId", payload.id);
|
|
452
|
-
ctx.attach("targetUrl", payload.url);
|
|
453
|
-
|
|
454
|
-
const response = await fetch(payload.url, {
|
|
455
|
-
method: 'POST',
|
|
456
|
-
body: JSON.stringify(payload.data),
|
|
457
|
-
headers: { 'Content-Type': 'application/json' }
|
|
458
|
-
});
|
|
459
|
-
|
|
460
|
-
if (!response.ok) throw new NetworkError(`HTTP ${response.status}`);
|
|
461
|
-
|
|
462
|
-
ctx.attach("statusCode", response.status);
|
|
463
|
-
return { delivered: true };
|
|
464
|
-
})
|
|
465
|
-
)
|
|
466
|
-
.setConcurrency(10)
|
|
467
|
-
.setRateLimit(100)
|
|
468
|
-
.setRetry({
|
|
469
|
-
maxRetries: 5,
|
|
470
|
-
backoff: 'exponential',
|
|
471
|
-
baseDelay: 1000,
|
|
472
|
-
maxDelay: 30000,
|
|
473
|
-
jitter: true,
|
|
474
|
-
shouldRetry: (err) => err instanceof NetworkError
|
|
475
|
-
})
|
|
476
|
-
.onEvent((event) => {
|
|
477
|
-
webhookLogger.log({
|
|
478
|
-
webhookId: event.attachments.webhookId,
|
|
479
|
-
success: !event.error,
|
|
480
|
-
attempts: event.totalAttempts,
|
|
481
|
-
duration: event.duration
|
|
482
|
-
});
|
|
483
|
-
});
|
|
484
|
-
```
|
|
88
|
+
- See `examples/` and `examples/README.md`.
|
|
89
|
+
- Run one: `npx tsx examples/01-basic-action.ts`
|
|
90
|
+
- Run all: `npx tsx examples/run-all.ts`
|
|
485
91
|
|
|
486
92
|
## Development
|
|
487
93
|
|
|
488
|
-
### Setup
|
|
489
|
-
|
|
490
94
|
```bash
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
npm
|
|
95
|
+
npm test
|
|
96
|
+
npm run test:actions
|
|
97
|
+
npm run test:scheduler
|
|
98
|
+
npm run test:wide-events
|
|
99
|
+
npm run build
|
|
100
|
+
npm run dev
|
|
494
101
|
```
|
|
495
102
|
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
```bash
|
|
499
|
-
npm run test # Run all tests
|
|
500
|
-
npm run test:actions # Actions tests only
|
|
501
|
-
npm run test:scheduler # Scheduler tests only
|
|
502
|
-
npm run test:wide-events # Wide events tests only
|
|
503
|
-
npm run test:retry # Retry tests only
|
|
504
|
-
npm run build # TypeScript compilation
|
|
505
|
-
npm run dev # Watch mode compilation
|
|
506
|
-
```
|
|
507
|
-
|
|
508
|
-
### Testing
|
|
509
|
-
|
|
510
|
-
Tests use a custom lightweight framework. See [src/tests/helpers.ts](src/tests/helpers.ts):
|
|
511
|
-
|
|
512
|
-
```typescript
|
|
513
|
-
import { test, assert } from "./helpers.js";
|
|
514
|
-
|
|
515
|
-
await test("should execute actions", async () => {
|
|
516
|
-
const action = createAction(async (x: number) => x * 2);
|
|
517
|
-
const result = await action.invoke(5).data;
|
|
518
|
-
assert.strictEqual(result, 10);
|
|
519
|
-
})();
|
|
520
|
-
```
|
|
521
|
-
|
|
522
|
-
## Design Philosophy
|
|
523
|
-
|
|
524
|
-
1. **Safe by default** - Concurrency defaults to 1 (sequential execution)
|
|
525
|
-
2. **Type inference over explicit generics** - Let TypeScript infer types from handlers
|
|
526
|
-
3. **Observability first** - Wide events are a core feature, not an afterthought
|
|
527
|
-
4. **Isolated failures** - Errors in tasks or event callbacks don't break the queue
|
|
528
|
-
5. **Composable features** - All features work together seamlessly
|
|
529
|
-
6. **Zero magic** - Explicit, predictable behavior with clear semantics
|
|
530
|
-
|
|
531
|
-
## Architecture
|
|
532
|
-
|
|
533
|
-
```
|
|
534
|
-
┌─────────────────┐
|
|
535
|
-
│ ActionBuilder │ ← Fluent API (public interface)
|
|
536
|
-
└────────┬────────┘
|
|
537
|
-
│
|
|
538
|
-
├─ setConcurrency()
|
|
539
|
-
├─ setRateLimit()
|
|
540
|
-
├─ setRetry()
|
|
541
|
-
├─ onEvent()
|
|
542
|
-
│
|
|
543
|
-
↓
|
|
544
|
-
┌─────────────────────┐
|
|
545
|
-
│ ExecutionScheduler │ ← Internal queue & flow control
|
|
546
|
-
└─────────┬───────────┘
|
|
547
|
-
│
|
|
548
|
-
├─ FIFO queue
|
|
549
|
-
├─ Sliding window rate limiting
|
|
550
|
-
├─ Concurrency slots
|
|
551
|
-
│
|
|
552
|
-
↓
|
|
553
|
-
┌──────────┐
|
|
554
|
-
│ Handler │ ← User's async function
|
|
555
|
-
└──────────┘
|
|
556
|
-
```
|
|
557
|
-
|
|
558
|
-
## License
|
|
559
|
-
|
|
560
|
-
MIT © [Alexander Mason](https://github.com/yourusername)
|
|
103
|
+
Design rationale (cancellation/priority/timeouts/progress/retry/wide-events) lives in `docs/plan/`.
|
|
561
104
|
|
|
562
105
|
## Contributing
|
|
563
106
|
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
- **Never rewrite existing tests** - Only add new tests
|
|
569
|
-
- **Prioritize observability** - Wide events should guide feature design
|
|
570
|
-
- **Check plan docs** - Review [docs/plan/](docs/plan/) before implementing features
|
|
571
|
-
- **Use `.js` extensions** - Import statements must use `.js` even for `.ts` files (ESM requirement)
|
|
572
|
-
- **Type inference** - Avoid explicit generics; let TypeScript infer types
|
|
573
|
-
|
|
574
|
-
## Related Projects
|
|
107
|
+
- Issues/PRs welcome.
|
|
108
|
+
- Keep the project ESM-first (imports in `src/**` use `.js` extensions).
|
|
109
|
+
- Tests run via `tsx` (`npm test`); prefer adding tests over editing existing `src/tests/*.test.ts`.
|
|
575
110
|
|
|
576
|
-
|
|
577
|
-
- [p-queue](https://github.com/sindresorhus/p-queue) - Promise queue with priority
|
|
578
|
-
- [bottleneck](https://github.com/SGrondin/bottleneck) - Rate limiting
|
|
579
|
-
|
|
580
|
-
**What makes `observed-js` different?**
|
|
581
|
-
|
|
582
|
-
- First-class wide event support for structured observability
|
|
583
|
-
- Unified API combining concurrency, rate limiting, and retries
|
|
584
|
-
- Type inference from handler functions
|
|
585
|
-
- Built for production observability from day one
|
|
586
|
-
|
|
587
|
-
## Responsible AI Disclosure
|
|
111
|
+
## License
|
|
588
112
|
|
|
589
|
-
|
|
113
|
+
[MIT](LICENSE)
|