@actuallab/core 14.3.26 → 14.3.34
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 +83 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# @actuallab/core
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@actuallab/core)
|
|
4
|
+
[](https://fusion.actuallab.net/PartTS-Core)
|
|
5
|
+
[](https://github.com/ActualLab/Fusion/blob/master/LICENSE)
|
|
6
|
+
|
|
7
|
+
Core primitives shared by every [ActualLab.Fusion](https://fusion.actuallab.net/) TypeScript
|
|
8
|
+
package — `Result<T>`, `AsyncContext`, `AsyncLock`, `PromiseSource`, events, retry policies, and
|
|
9
|
+
cancellation helpers. It is the TypeScript counterpart of parts of `ActualLab.Core` in .NET, and it
|
|
10
|
+
has **zero runtime dependencies**.
|
|
11
|
+
|
|
12
|
+
You rarely install it directly: `@actuallab/rpc`, `@actuallab/fusion`, `@actuallab/fusion-rpc`, and
|
|
13
|
+
`@actuallab/fusion-react` all depend on it. Install it explicitly when you want its primitives on
|
|
14
|
+
their own.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install @actuallab/core
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
ESM-first with a CJS fallback; ships its own `.d.ts`.
|
|
23
|
+
|
|
24
|
+
## What's inside
|
|
25
|
+
|
|
26
|
+
| API | Description |
|
|
27
|
+
|-----|-------------|
|
|
28
|
+
| `Result<T>`, `result`, `errorResult`, `resultFrom`, `resultFromAsync` | Immutable value-or-error container (.NET's `Result<T>`) |
|
|
29
|
+
| `PromiseSource<T>`, `PromiseSourceWithTimeout<T>` | Externally-resolvable promise (.NET's `TaskCompletionSource<T>`) |
|
|
30
|
+
| `AsyncContext`, `AsyncContextKey`, `abortSignalKey` | `AsyncLocal<T>`-like typed context; backed by `AsyncLocalStorage` on Node ≥ 20.16 |
|
|
31
|
+
| `AsyncLock`, `AsyncSignal` | Promise-based mutual exclusion and signalling |
|
|
32
|
+
| `EventHandlerSet<T>` | Typed multicast pub/sub with `whenNext()` |
|
|
33
|
+
| `isCancellation`, `cancellationError`, `delayAsync`, `abortPromise`, `awaitWithCleanup` | `AbortSignal`-based cancellation, with .NET's "cancellation is not a failure" semantics |
|
|
34
|
+
| `RetryDelaySeq`, `RetryDelayer`, `retry` | Exponential-backoff retry policies |
|
|
35
|
+
| `throttle`, `debounce`, `serialize` | Higher-order async operators |
|
|
36
|
+
| `RingBuffer`, `DisposableBag` | Small collections / lifetime helpers |
|
|
37
|
+
| `Log`, `LogLevel`, `initLogging`, `LogLevelController` | Scoped logging used by all Fusion TS packages |
|
|
38
|
+
|
|
39
|
+
## Examples
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
import { Result, result, errorResult, resultFrom } from '@actuallab/core';
|
|
43
|
+
|
|
44
|
+
const ok = result(42);
|
|
45
|
+
ok.hasValue; // true
|
|
46
|
+
ok.value; // 42
|
|
47
|
+
ok.valueOrUndefined; // 42 — never throws
|
|
48
|
+
|
|
49
|
+
const err = errorResult<number>(new Error('fail'));
|
|
50
|
+
err.hasError; // true
|
|
51
|
+
err.value; // throws Error("fail")
|
|
52
|
+
|
|
53
|
+
resultFrom(() => JSON.parse('{}')); // Result<any>, exception captured
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { AsyncContext, AsyncContextKey } from '@actuallab/core';
|
|
58
|
+
|
|
59
|
+
const userKey = new AsyncContextKey<string>('user', 'anonymous');
|
|
60
|
+
const ctx = AsyncContext.empty.with(userKey, 'Alice');
|
|
61
|
+
|
|
62
|
+
ctx.run(() => AsyncContext.current!.get(userKey)); // "Alice"
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
import { AsyncLock, delayAsync, RetryDelaySeq } from '@actuallab/core';
|
|
67
|
+
|
|
68
|
+
const lock = new AsyncLock();
|
|
69
|
+
await lock.run(async () => { /* critical section */ });
|
|
70
|
+
|
|
71
|
+
await delayAsync(1000, abortSignal); // abortable delay
|
|
72
|
+
RetryDelaySeq.exp(1000, 30000); // 1s, 1.4s, 2s, 2.8s, … (×√2, ±10% spread), capped at 30s
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Documentation
|
|
76
|
+
|
|
77
|
+
- [`@actuallab/core` reference](https://fusion.actuallab.net/PartTS-Core) — full API tables and semantics
|
|
78
|
+
- [TypeScript port overview](https://fusion.actuallab.net/PartTS) — architecture, `AsyncContext` rules, .NET differences
|
|
79
|
+
- [Fusion documentation](https://fusion.actuallab.net/)
|
|
80
|
+
|
|
81
|
+
## License
|
|
82
|
+
|
|
83
|
+
MIT — see [LICENSE](https://github.com/ActualLab/Fusion/blob/master/LICENSE).
|