@brickkit/redis-world 0.11.0 → 0.12.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.
@@ -0,0 +1,89 @@
1
+ import { a as validateRetention, i as hasRetention, n as RunRetention, r as createReaper, t as KeepRuns } from "./reaper-SOJDwnBw.js";
2
+ import { Storage, Streamer } from "@workflow/world";
3
+ import { Redis } from "ioredis";
4
+ /**
5
+ * The run id the SDK asks the world for when a run starts. Without options it is
6
+ * a fresh ULID. With `runKey` and `runKeyTime` it is the same ULID every time, so
7
+ * starting the same run twice creates one run: the second start finds it already
8
+ * there.
9
+ *
10
+ * The id is a real ULID. Its time is `runKeyTime`, not the clock, because the SDK
11
+ * seeds a workflow's clock from the time in its run id. Pass the time the run is
12
+ * for, such as when the event it handles happened, and the same time on every
13
+ * attempt.
14
+ *
15
+ * @param options - The options given to `start()`. `runKey` is a non-empty string
16
+ * that names the run (at most 1024 characters), and `runKeyTime` is milliseconds
17
+ * since the epoch.
18
+ * @returns The id without its `wrun_` prefix, which the SDK adds.
19
+ * @throws When `runKey` is not a usable string, or comes without a valid `runKeyTime`.
20
+ */
21
+ export declare function createRunId(options?: Readonly<Record<string, unknown>>): string;
22
+ /**
23
+ * The idempotency key for the message that starts a run, which is the only
24
+ * message that carries the run's input. `start()` sends no key of its own, so a
25
+ * second start of the same run would otherwise queue a second first delivery.
26
+ *
27
+ * The key only covers a first message that is still queued or running. Once the
28
+ * run has started, the queue does not enqueue the message at all (see
29
+ * `runHasStarted` in `createQueue`): the runtime runs a run's first step from the
30
+ * first message, in parallel with `run_created`, so a late second one would run
31
+ * that step's code again.
32
+ *
33
+ * @param message - The queue payload.
34
+ * @returns A key for a run's first message, and `undefined` for every other message.
35
+ */
36
+ export declare function initialMessageKey(message: unknown): string | undefined;
37
+ interface StreamerConfig {
38
+ redis: Redis;
39
+ keyPrefix: string;
40
+ }
41
+ /**
42
+ * Create a streamer implementation using Redis Streams.
43
+ *
44
+ * Uses Redis auto-generated stream entry IDs (timestamp-sequence format)
45
+ * instead of custom IDs, since Redis Streams require IDs in
46
+ * `<millisecondsTime>-<sequenceNumber>` format.
47
+ *
48
+ * Key layout (every key is scoped to the run that owns the stream, so two runs
49
+ * can use the same stream name without sharing chunks):
50
+ * - `<prefix>stream:<runId>:<name>` Redis Stream of the chunks plus the eof marker
51
+ * - `<prefix>streams:by_run:<runId>` Set of the run's stream names
52
+ * - `<prefix>stream_notify` pub/sub channel carrying live chunks
53
+ */
54
+ export declare function createStreamer(config: StreamerConfig): Streamer & {
55
+ close(): Promise<void>;
56
+ };
57
+ /**
58
+ * Creates a namespaced debug logger.
59
+ * Logs to stderr to avoid corrupting CLI JSON output on stdout.
60
+ *
61
+ * Control via WORKFLOW_DEBUG environment variable:
62
+ * WORKFLOW_DEBUG=1 // Enable all
63
+ * WORKFLOW_DEBUG=mysql-world // Specific namespace
64
+ * WORKFLOW_DEBUG=mysql-world,redis-world // Multiple namespaces
65
+ */
66
+ export declare function createDebugLogger(namespace: string): (...args: unknown[]) => void;
67
+ /**
68
+ * Load an env file when present without making a `.env` file mandatory.
69
+ *
70
+ * Node 24 provides the parser natively, so published worlds do not need a
71
+ * runtime dependency solely to load local development configuration.
72
+ */
73
+ export declare function loadOptionalEnvFile(path?: string): void;
74
+ /**
75
+ * JSON replacer that encodes Uint8Array as a tagged object with base64 data.
76
+ */
77
+ export declare function uint8ArrayReplacer(_key: string, value: unknown): unknown;
78
+ /**
79
+ * Is there a `Uint8Array` anywhere in the graph?
80
+ *
81
+ * Must stay exact: `JSON.stringify` turns a bare `Uint8Array` into
82
+ * `{"0":1,...}` without complaint, so a miss is data corruption, not a slow
83
+ * path. The walk allocates nothing, which is why it beats the replacer over
84
+ * the same nodes.
85
+ */
86
+ export declare function hasBinary(value: unknown): boolean;
87
+ export declare function createStorage(redis: Redis, keyPrefix: string, maxEventsPerRun?: number): Storage;
88
+ export { type KeepRuns, type RunRetention, createReaper, hasRetention, validateRetention };
89
+ //# sourceMappingURL=internal.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"internal.d.ts","names":[],"sources":["../src/run-id.ts","../src/streamer.ts","../src/internal/debug.ts","../src/internal/env.ts","../src/internal/serialization.ts","../src/shared.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;wBAmCgB,YACd,UAAU,SAAS;;;;;;;;;;;;;;;wBAmCL,kBAAkB;UCDxB;EACR,OAAO;EACP;;;;;;;;;;;;;;;wBA6Ec,eACd,QAAQ,iBACP;EAAa,SAAS;;;;;;;;;;;wBC9IT,kBAAkB,wBAAiB;;;;;;;wBCHnC,oBAAoB;;;;wBCuBpB,mBAAmB,cAAc;;;;;;;;;wBAmEjC,UAAU;wBCpFV,cACd,OAAO,OACP,mBACA,2BACC"}
@@ -0,0 +1,3 @@
1
+ import { a as validateRetention, c as uint8ArrayReplacer, d as initialMessageKey, i as hasRetention, l as createDebugLogger, n as createStreamer, r as createReaper, s as hasBinary, t as createStorage, u as createRunId } from "./shared-Bhvu4aZA.js";
2
+ import { t as loadOptionalEnvFile } from "./env-DMwDVTiZ.js";
3
+ export { createDebugLogger, createReaper, createRunId, createStorage, createStreamer, hasBinary, hasRetention, initialMessageKey, loadOptionalEnvFile, uint8ArrayReplacer, validateRetention };
@@ -0,0 +1,45 @@
1
+ import { Redis } from "ioredis";
2
+ /** How long finished runs are kept, using `age` and `count` limits. */
3
+ interface KeepRuns {
4
+ /** Delete runs that finished more than this many seconds ago. */
5
+ age?: number;
6
+ /** Keep at most this many of the newest runs; delete the rest. */
7
+ count?: number;
8
+ }
9
+ /**
10
+ * Retention for run data (the run, its event log, steps, hooks, and streams),
11
+ * per terminal status. A status without a policy is kept forever.
12
+ */
13
+ interface RunRetention {
14
+ completed?: KeepRuns;
15
+ failed?: KeepRuns;
16
+ cancelled?: KeepRuns;
17
+ /** How often each worker looks for expired runs (ms). Default: 60000 */
18
+ sweepIntervalMs?: number;
19
+ /** Runs deleted per status per sweep. Default: 200 */
20
+ batchSize?: number;
21
+ }
22
+ interface Reaper {
23
+ start(): void;
24
+ stop(): Promise<void>;
25
+ /** One pass over every status; returns the number of runs deleted. */
26
+ sweep(): Promise<number>;
27
+ }
28
+ declare function validateRetention(retention: RunRetention | undefined): void;
29
+ declare function hasRetention(retention: RunRetention | undefined): retention is RunRetention;
30
+ /**
31
+ * Deletes finished runs once they pass their retention. Safe to run on every
32
+ * worker: one lock per interval picks a single sweeper, and deleting a run is
33
+ * idempotent anyway. A run's own key and index entries go last, in one
34
+ * transaction, so a crash part-way leaves the run listed and the next sweep
35
+ * finishes the job.
36
+ */
37
+ declare function createReaper(options: {
38
+ redis: Redis;
39
+ keyPrefix: string;
40
+ retention: RunRetention;
41
+ /** Logs sweep failures; each world passes its own debug namespace. */
42
+ log?: (...args: unknown[]) => void;
43
+ }): Reaper;
44
+ export { validateRetention as a, hasRetention as i, RunRetention as n, createReaper as r, KeepRuns as t };
45
+ //# sourceMappingURL=reaper-SOJDwnBw.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reaper-SOJDwnBw.d.ts","names":[],"sources":["../src/reaper.ts"],"mappings":";;UAIiB;;EAEf;;EAEA;;;;;;UAOe;EACf,YAAY;EACZ,SAAS;EACT,YAAY;;EAEZ;;EAEA;;UAQe;EACf;EACA,QAAQ;;EAER,SAAS;;iBAGK,kBAAkB,WAAW;iBAwB7B,aACd,WAAW,2BACV,aAAa;;;;;;;;iBAaA,aAAa;EAC3B,OAAO;EACP;EACA,WAAW;;EAEX,UAAU;IACR"}