@dxos/pipeline 0.0.0 → 0.11.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 (44) hide show
  1. package/dist/lib/index.mjs +174 -0
  2. package/dist/lib/index.mjs.map +1 -0
  3. package/dist/lib/testing.mjs +125 -0
  4. package/dist/lib/testing.mjs.map +1 -0
  5. package/dist/types/src/Pipeline.d.ts +10 -0
  6. package/dist/types/src/Pipeline.d.ts.map +1 -1
  7. package/dist/types/src/Progress.d.ts +17 -0
  8. package/dist/types/src/Progress.d.ts.map +1 -0
  9. package/dist/types/src/ProgressReporter.d.ts +19 -0
  10. package/dist/types/src/ProgressReporter.d.ts.map +1 -0
  11. package/dist/types/src/Stage.d.ts +12 -0
  12. package/dist/types/src/Stage.d.ts.map +1 -1
  13. package/dist/types/src/index.d.ts +2 -0
  14. package/dist/types/src/index.d.ts.map +1 -1
  15. package/dist/types/src/testing/benchmark.d.ts +40 -0
  16. package/dist/types/src/testing/benchmark.d.ts.map +1 -0
  17. package/dist/types/src/testing/benchmark.test.d.ts +2 -0
  18. package/dist/types/src/testing/benchmark.test.d.ts.map +1 -0
  19. package/dist/types/src/testing/index.d.ts +3 -0
  20. package/dist/types/src/testing/index.d.ts.map +1 -1
  21. package/dist/types/src/testing/instrument.d.ts +18 -0
  22. package/dist/types/src/testing/instrument.d.ts.map +1 -0
  23. package/dist/types/src/testing/metrics.d.ts +33 -0
  24. package/dist/types/src/testing/metrics.d.ts.map +1 -0
  25. package/dist/types/tsconfig.tsbuildinfo +1 -1
  26. package/package.json +17 -13
  27. package/src/Pipeline.test.ts +74 -1
  28. package/src/Pipeline.ts +46 -0
  29. package/src/Progress.ts +25 -0
  30. package/src/ProgressReporter.ts +59 -0
  31. package/src/Stage.ts +28 -0
  32. package/src/index.ts +2 -0
  33. package/src/testing/benchmark.test.ts +103 -0
  34. package/src/testing/benchmark.ts +113 -0
  35. package/src/testing/index.ts +3 -0
  36. package/src/testing/instrument.ts +57 -0
  37. package/src/testing/metrics.ts +68 -0
  38. package/dist/lib/neutral/chunk-J5LGTIGS.mjs +0 -10
  39. package/dist/lib/neutral/chunk-J5LGTIGS.mjs.map +0 -7
  40. package/dist/lib/neutral/index.mjs +0 -67
  41. package/dist/lib/neutral/index.mjs.map +0 -7
  42. package/dist/lib/neutral/meta.json +0 -1
  43. package/dist/lib/neutral/testing/index.mjs +0 -18
  44. package/dist/lib/neutral/testing/index.mjs.map +0 -7
@@ -0,0 +1,174 @@
1
+ import * as Effect from "effect/Effect";
2
+ import * as Function from "effect/Function";
3
+ import * as Stream from "effect/Stream";
4
+ import { log } from "@dxos/log";
5
+ import * as Cause from "effect/Cause";
6
+ import * as Context from "effect/Context";
7
+ import * as Layer from "effect/Layer";
8
+ import { Progress } from "@dxos/progress";
9
+ //#region \0rolldown/runtime.js
10
+ var __defProp = Object.defineProperty;
11
+ var __exportAll = (all, no_symbols) => {
12
+ let target = {};
13
+ for (var name in all) __defProp(target, name, {
14
+ get: all[name],
15
+ enumerable: true
16
+ });
17
+ if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
18
+ return target;
19
+ };
20
+ //#endregion
21
+ //#region src/Progress.ts
22
+ var Progress_exports = /* @__PURE__ */ __exportAll({
23
+ Progress: () => Progress$1,
24
+ deriveEta: () => deriveEta,
25
+ make: () => make
26
+ });
27
+ var make = Progress.make;
28
+ var deriveEta = Progress.deriveEta;
29
+ var Progress$1 = class Progress$1 extends Context.Tag("@dxos/pipeline/Progress")() {
30
+ /** A fresh in-memory registry. */
31
+ static layer = Layer.sync(Progress$1, () => Progress.make());
32
+ };
33
+ //#endregion
34
+ //#region src/Stage.ts
35
+ var Stage_exports = /* @__PURE__ */ __exportAll({
36
+ DEFAULT_BUFFER_SIZE: () => 16,
37
+ filter: () => filter,
38
+ map: () => map,
39
+ track: () => track,
40
+ window: () => window
41
+ });
42
+ var withBuffer = (options) => (stream) => options.overflow ? Stream.buffer(stream, {
43
+ capacity: options.bufferSize ?? 16,
44
+ strategy: options.overflow
45
+ }) : stream;
46
+ /**
47
+ * 1:1 async transform. `fn` may return `undefined` to no-op for an item; the value is dropped
48
+ * before it reaches the next stage, so the returned stage's `Out` excludes `undefined`.
49
+ * `concurrency` defaults to 1 (ordered). `id` labels the per-item span for tracing.
50
+ *
51
+ * `Out`/`E`/`R` always infer from `fn`'s result; `In` only infers when the stage is composed inline
52
+ * in a `pipe` (pinned by the upstream stream). Built as a standalone value, pin `In` by annotating
53
+ * the callback parameter (`(item: T) => …`) or the binding (`const s: Stage<…> = …`). The four type
54
+ * parameters are intentionally all-or-nothing: passing a partial list (e.g. `map<In, Out>(…)`) is a
55
+ * compile error rather than silently forcing `E`/`R` to `never` and rejecting a service-using `fn`.
56
+ */
57
+ var map = (id, fn, options = {}) => (self) => self.pipe(withBuffer(options), Stream.mapEffect((item) => fn(item).pipe(Effect.withSpan(id)), { concurrency: options.concurrency ?? 1 }), Stream.filter((item) => item !== void 0));
58
+ /**
59
+ * Sliding-window transform: invokes `fn` once per incoming item with a fixed-size rolling view of
60
+ * the last `size` items. The window is bounded by `size`, so memory does not grow with stream
61
+ * length; it composes with (and is distinct from) the overflow buffer, which bounds rate mismatch.
62
+ * `fn` may return `undefined` to no-op, narrowing `Out` the same way {@link map} does. Type
63
+ * parameters follow {@link map}: `Out`/`E`/`R` infer from `fn`, `In` is pinned inline by the
64
+ * upstream or (standalone) by annotating the callback parameter or the binding, and a partial type
65
+ * argument list is a compile error.
66
+ */
67
+ var window = (id, size, fn, options = {}) => {
68
+ if (!Number.isInteger(size) || size < 1) throw new RangeError(`Stage.window size must be a positive integer: ${size}`);
69
+ return (self) => self.pipe(Stream.mapAccum([], (buffer, item) => {
70
+ const next = [...buffer, item].slice(-size);
71
+ return [next, next];
72
+ }), Stream.mapEffect((buffer) => fn(buffer).pipe(Effect.withSpan(id)), { concurrency: 1 }), withBuffer(options), Stream.filter((item) => item !== void 0));
73
+ };
74
+ /** Drop items that do not match `pred`. */
75
+ var filter = (id, pred) => (self) => self.pipe(Stream.filter(pred));
76
+ /**
77
+ * A pass-through stage that reports live progress to the {@link Progress} registry: it registers the
78
+ * task (with an optional item `total`), advances the item index as each item flows through, marks the
79
+ * task done only when the stream ends successfully, and marks it failed if the stream errors.
80
+ * Progress is thus an artifact of the pipeline itself — the same stage works in the app (feeding a
81
+ * reactive panel) and in tests (feeding a file sink).
82
+ */
83
+ var track = (name, options = {}) => (self) => Stream.unwrap(Effect.map(Progress$1, (progress) => {
84
+ const handle = progress.task(name, options);
85
+ return Stream.concat(self.pipe(Stream.tap(() => Effect.sync(() => handle.advance())), Stream.tapErrorCause((cause) => Effect.sync(() => handle.fail(Cause.pretty(cause))))), Stream.execute(Effect.sync(() => handle.done())));
86
+ }));
87
+ //#endregion
88
+ //#region src/Pipeline.ts
89
+ var Pipeline_exports = /* @__PURE__ */ __exportAll({
90
+ abortWith: () => abortWith,
91
+ run: () => run
92
+ });
93
+ var __dxlog_file$1 = "/__w/dxos/dxos/packages/core/compute/pipeline/src/Pipeline.ts";
94
+ /**
95
+ * Drain a composed stream to a sink: apply the pipeline-level overflow buffer and run to
96
+ * completion. Cancellation is structural — interrupting the returned effect interrupts the stream
97
+ * and all in-flight stage work; there are no daemon fibers to leak. Compose with `pipe`, chaining
98
+ * `Stage` transforms ahead of it: `pipe(source, Stage.map(...), Stage.window(...), Pipeline.run({
99
+ * sink }))`. Mirrors `Stream.runForEach`'s own shape: the sink's `E`/`R` (bound once, from `options`)
100
+ * are kept independent of — and unioned with — the piped-in stream's own `E`/`R`, so the incoming
101
+ * stream's generics aren't forced to unify with the sink's at the call site.
102
+ */
103
+ var run = Function.dual(2, (source, options) => source.pipe(Stream.buffer({
104
+ capacity: options.bufferSize ?? 16,
105
+ strategy: options.overflow ?? "suspend"
106
+ }), Stream.runForEach(options.sink)));
107
+ /**
108
+ * Abort a pipeline with an `AbortSignal`.
109
+ *
110
+ * Races the wrapped effect against the signal; losing the race resolves as a genuine fiber
111
+ * interrupt, which skips every subsequent `yield*`/pipe step in the wrapped effect (an interrupt is
112
+ * not a failure — `Effect.tapError` and friends never see it). `onCancel` runs via `Effect.onInterrupt`
113
+ * so every caller gets cancellation cleanup (e.g. resetting a progress monitor stuck at its last
114
+ * `running` snapshot) without each one having to remember to add its own `Effect.onInterrupt`.
115
+ */
116
+ var abortWith = (signal, onCancel = Effect.void) => (effect) => effect.pipe(Effect.raceFirst(Effect.async((resume) => {
117
+ if (signal.aborted) {
118
+ resume(Effect.interrupt);
119
+ return;
120
+ }
121
+ const onAbort = () => {
122
+ resume(Effect.gen(function* () {
123
+ log.info("aborting pipeline", { span: yield* Effect.currentSpan.pipe(Effect.map((span) => span.name), Effect.catchAll((_) => Effect.succeed(void 0))) }, {
124
+ "~LogMeta": "~LogMeta",
125
+ F: __dxlog_file$1,
126
+ L: 84,
127
+ S: this
128
+ });
129
+ return yield* Effect.interrupt;
130
+ }));
131
+ };
132
+ signal.addEventListener("abort", onAbort, { once: true });
133
+ return Effect.sync(() => signal.removeEventListener("abort", onAbort));
134
+ })), Effect.onInterrupt(() => onCancel));
135
+ //#endregion
136
+ //#region src/ProgressReporter.ts
137
+ var ProgressReporter_exports = /* @__PURE__ */ __exportAll({
138
+ layer: () => layer,
139
+ logSink: () => logSink
140
+ });
141
+ var __dxlog_file = "/__w/dxos/dxos/packages/core/compute/pipeline/src/ProgressReporter.ts";
142
+ /** One compact info-log line per snapshot (works everywhere — node, browser, EDGE). */
143
+ var logSink = (snapshot) => Effect.sync(() => log.info("progress", { tasks: snapshot.tasks.map((task) => `${task.name} ${task.current}${task.total !== void 0 ? `/${task.total}` : ""} ${task.status}`) }, {
144
+ "~LogMeta": "~LogMeta",
145
+ F: __dxlog_file,
146
+ L: 21,
147
+ S: void 0
148
+ }));
149
+ /**
150
+ * A reporter layer: subscribes to the {@link Progress} registry and flushes the latest snapshot to
151
+ * `sink` at most once per `throttle` (coalescing bursts), plus a final flush when the scope closes.
152
+ * Reactive consumers (a browser panel) can instead `Progress.subscribe` directly for instant
153
+ * updates; this layer is for rate-limited sinks (file, log, EDGE).
154
+ */
155
+ var layer = (options) => Layer.scopedDiscard(Effect.gen(function* () {
156
+ const progress = yield* Progress$1;
157
+ const throttle = options.throttle ?? "2 seconds";
158
+ let latest;
159
+ const unsubscribe = progress.subscribe((snapshot) => {
160
+ latest = snapshot;
161
+ });
162
+ yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
163
+ const flush = Effect.suspend(() => {
164
+ const snapshot = latest;
165
+ latest = void 0;
166
+ return snapshot ? options.sink(snapshot) : Effect.void;
167
+ });
168
+ yield* Effect.forkScoped(Effect.forever(flush.pipe(Effect.delay(throttle))));
169
+ yield* Effect.addFinalizer(() => options.sink(progress.snapshot()).pipe(Effect.ignore));
170
+ }));
171
+ //#endregion
172
+ export { Pipeline_exports as Pipeline, Progress_exports as Progress, ProgressReporter_exports as ProgressReporter, Stage_exports as Stage };
173
+
174
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../../src/Progress.ts","../../src/Stage.ts","../../src/Pipeline.ts","../../src/ProgressReporter.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Context from 'effect/Context';\nimport * as Layer from 'effect/Layer';\n\nimport { Progress as ProgressCore } from '@dxos/progress';\n\n// The registry primitives now live in @dxos/progress so the pipeline (this Effect service) and the\n// app-toolkit ProgressRegistry capability share one implementation.\nexport type TaskStatus = ProgressCore.TaskStatus;\nexport type TaskProgress = ProgressCore.TaskProgress;\nexport type ProgressSnapshot = ProgressCore.ProgressSnapshot;\nexport type TaskHandle = ProgressCore.TaskHandle;\nexport type ProgressApi = ProgressCore.ProgressApi;\nexport const make = ProgressCore.make;\nexport const deriveEta = ProgressCore.deriveEta;\n\nexport class Progress extends Context.Tag('@dxos/pipeline/Progress')<Progress, ProgressCore.ProgressApi>() {\n /** A fresh in-memory registry. */\n static layer: Layer.Layer<Progress> = Layer.sync(Progress, () => ProgressCore.make());\n}\n","//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Cause from 'effect/Cause';\nimport * as Effect from 'effect/Effect';\nimport * as Stream from 'effect/Stream';\n\nimport * as Progress from './Progress';\n\n/**\n * Overflow policy applied when a consumer cannot keep pace, mapped onto `Stream.buffer` strategies.\n * - `suspend`: back pressure — never drop (default; correct for email/document processing).\n * - `sliding`: drop the oldest buffered item, keep the latest (correct for live transcription).\n * - `dropping`: drop the newest item when the buffer is full.\n */\nexport type Overflow = 'suspend' | 'sliding' | 'dropping';\n\n/** Default bounded-buffer capacity for both pipeline-level and per-stage buffering. */\nexport const DEFAULT_BUFFER_SIZE = 16;\n\n/**\n * A pipeline stage: a pipeable `Stream → Stream` transform, the same shape `Stream.mapEffect` /\n * `Stream.filter` already have — generic over the *input* stream's own error/requirements (`E0`/\n * `R0`) and unioning in the stage's own `E`/`R`, so stages compose in a `pipe` chain the same way\n * Effect's own Stream operators do. Authors build stages with {@link map} / {@link window} /\n * {@link filter}; shared dependencies flow through `R`, provided once at the edge via\n * `Effect.provide`.\n */\nexport type Stage<In, Out, E = never, R = never> = <E0 = never, R0 = never>(\n self: Stream.Stream<In, E0, R0>,\n) => Stream.Stream<Out, E0 | E, R0 | R>;\n\n/** Options shared by buffering stage constructors. */\ntype BufferOptions = {\n /**\n * Per-stage overflow override; when set, a bounded buffer is inserted at the stage's async\n * boundary. For {@link map} the buffer sits *before* `mapEffect`, so under load it sheds/coalesces\n * in-flight input (`sliding` keeps the latest queued item — true latest-wins — `dropping` drops\n * new arrivals while a run is in flight). For {@link window} it sits after windowing (a window\n * must see every item), bounding output rate.\n */\n readonly overflow?: Overflow;\n /** Buffer capacity for the per-stage override. */\n readonly bufferSize?: number;\n};\n\nexport type MapOptions = BufferOptions & {\n /** In-flight parallelism. Defaults to 1 (ordered + back-pressured); higher values may reorder. */\n readonly concurrency?: number;\n};\n\nexport type WindowOptions = BufferOptions;\n\n// A per-stage buffer is inserted only when an overflow override is requested; otherwise the stage\n// stays a pure transform and relies on the pipeline-level buffer.\nconst withBuffer =\n (options: BufferOptions) =>\n <A, E, R>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>\n options.overflow\n ? Stream.buffer(stream, { capacity: options.bufferSize ?? DEFAULT_BUFFER_SIZE, strategy: options.overflow })\n : stream;\n\n/**\n * 1:1 async transform. `fn` may return `undefined` to no-op for an item; the value is dropped\n * before it reaches the next stage, so the returned stage's `Out` excludes `undefined`.\n * `concurrency` defaults to 1 (ordered). `id` labels the per-item span for tracing.\n *\n * `Out`/`E`/`R` always infer from `fn`'s result; `In` only infers when the stage is composed inline\n * in a `pipe` (pinned by the upstream stream). Built as a standalone value, pin `In` by annotating\n * the callback parameter (`(item: T) => …`) or the binding (`const s: Stage<…> = …`). The four type\n * parameters are intentionally all-or-nothing: passing a partial list (e.g. `map<In, Out>(…)`) is a\n * compile error rather than silently forcing `E`/`R` to `never` and rejecting a service-using `fn`.\n */\nexport const map =\n <In, Out, E, R>(\n id: string,\n fn: (item: In) => Effect.Effect<Out, E, R>,\n options: MapOptions = {},\n ): Stage<In, Exclude<Out, undefined>, E, R> =>\n <E0, R0>(self: Stream.Stream<In, E0, R0>) =>\n self.pipe(\n withBuffer(options),\n // The overflow buffer sits *before* `mapEffect`: while a run is in flight it absorbs new\n // input, so `sliding` coalesces to the latest queued item (latest-wins) and `dropping` sheds\n // new arrivals. A buffer after `mapEffect` would bound outputs, not in-flight input, leaving\n // overflow inert.\n Stream.mapEffect((item) => fn(item).pipe(Effect.withSpan(id)), { concurrency: options.concurrency ?? 1 }),\n Stream.filter((item): item is Exclude<Out, undefined> => item !== undefined),\n );\n\n/**\n * Sliding-window transform: invokes `fn` once per incoming item with a fixed-size rolling view of\n * the last `size` items. The window is bounded by `size`, so memory does not grow with stream\n * length; it composes with (and is distinct from) the overflow buffer, which bounds rate mismatch.\n * `fn` may return `undefined` to no-op, narrowing `Out` the same way {@link map} does. Type\n * parameters follow {@link map}: `Out`/`E`/`R` infer from `fn`, `In` is pinned inline by the\n * upstream or (standalone) by annotating the callback parameter or the binding, and a partial type\n * argument list is a compile error.\n */\nexport const window = <In, Out, E, R>(\n id: string,\n size: number,\n fn: (window: readonly In[]) => Effect.Effect<Out, E, R>,\n options: WindowOptions = {},\n): Stage<In, Exclude<Out, undefined>, E, R> => {\n // A window must retain at least one item; a non-positive size makes `.slice(-size)` degenerate\n // (`slice(-0)` returns the whole array, growing unbounded).\n if (!Number.isInteger(size) || size < 1) {\n throw new RangeError(`Stage.window size must be a positive integer: ${size}`);\n }\n\n return <E0, R0>(self: Stream.Stream<In, E0, R0>) =>\n self.pipe(\n Stream.mapAccum([] as readonly In[], (buffer, item) => {\n const next = [...buffer, item].slice(-size);\n return [next, next];\n }),\n Stream.mapEffect((buffer) => fn(buffer).pipe(Effect.withSpan(id)), { concurrency: 1 }),\n withBuffer(options),\n Stream.filter((item): item is Exclude<Out, undefined> => item !== undefined),\n );\n};\n\n/** Drop items that do not match `pred`. */\nexport const filter =\n <In>(id: string, pred: (item: In) => boolean): Stage<In, In> =>\n <E0, R0>(self: Stream.Stream<In, E0, R0>) =>\n self.pipe(Stream.filter(pred));\n\n/**\n * A pass-through stage that reports live progress to the {@link Progress} registry: it registers the\n * task (with an optional item `total`), advances the item index as each item flows through, marks the\n * task done only when the stream ends successfully, and marks it failed if the stream errors.\n * Progress is thus an artifact of the pipeline itself — the same stage works in the app (feeding a\n * reactive panel) and in tests (feeding a file sink).\n */\nexport const track =\n <In>(name: string, options: { total?: number; label?: string } = {}): Stage<In, In, never, Progress.Progress> =>\n <E0, R0>(self: Stream.Stream<In, E0, R0>) =>\n Stream.unwrap(\n Effect.map(Progress.Progress, (progress) => {\n const handle = progress.task(name, options);\n // `done` only on successful completion (a concatenated terminal effect, unreached on error);\n // `fail` on the error path. A finalizer/`ensuring` would report done even for a failed stream.\n return Stream.concat(\n self.pipe(\n Stream.tap(() => Effect.sync(() => handle.advance())),\n Stream.tapErrorCause((cause) => Effect.sync(() => handle.fail(Cause.pretty(cause)))),\n ),\n Stream.execute(Effect.sync(() => handle.done())),\n );\n }),\n );\n","//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport * as Effect from 'effect/Effect';\nimport * as Function from 'effect/Function';\nimport * as Stream from 'effect/Stream';\n\nimport { log } from '@dxos/log';\n\nimport * as Stage from './Stage';\n\n/**\n * Terminal commit for a pipeline: applies a stage's output value. Keeps stages pure — they emit\n * typed `Out` descriptions and the sink performs the side effect (in-memory capture in tests, a\n * database write in production).\n */\nexport type Sink<Out, E = never, R = never> = (out: Out) => Effect.Effect<void, E, R>;\n\nexport type RunOptions<Out, E = never, R = never> = {\n /** Terminal commit for the final stage output. */\n readonly sink: Sink<Out, E, R>;\n /** Pipeline-level overflow policy. Defaults to `suspend` (back pressure, never drop). */\n readonly overflow?: Stage.Overflow;\n /** Pipeline-level bounded-buffer capacity. */\n readonly bufferSize?: number;\n};\n\n/**\n * Drain a composed stream to a sink: apply the pipeline-level overflow buffer and run to\n * completion. Cancellation is structural — interrupting the returned effect interrupts the stream\n * and all in-flight stage work; there are no daemon fibers to leak. Compose with `pipe`, chaining\n * `Stage` transforms ahead of it: `pipe(source, Stage.map(...), Stage.window(...), Pipeline.run({\n * sink }))`. Mirrors `Stream.runForEach`'s own shape: the sink's `E`/`R` (bound once, from `options`)\n * are kept independent of — and unioned with — the piped-in stream's own `E`/`R`, so the incoming\n * stream's generics aren't forced to unify with the sink's at the call site.\n */\nexport const run: {\n <Out, E2, R2>(\n options: RunOptions<Out, E2, R2>,\n ): <E, R>(source: Stream.Stream<Out, E, R>) => Effect.Effect<void, E2 | E, R2 | R>;\n <Out, E, R, E2, R2>(\n source: Stream.Stream<Out, E, R>,\n options: RunOptions<Out, E2, R2>,\n ): Effect.Effect<void, E2 | E, R2 | R>;\n} = Function.dual(2, (source: Stream.Stream<any, any, any>, options: RunOptions<any, any, any>) =>\n source.pipe(\n Stream.buffer({\n capacity: options.bufferSize ?? Stage.DEFAULT_BUFFER_SIZE,\n strategy: options.overflow ?? 'suspend',\n }),\n Stream.runForEach(options.sink),\n ),\n);\n\n/**\n * Abort a pipeline with an `AbortSignal`.\n *\n * Races the wrapped effect against the signal; losing the race resolves as a genuine fiber\n * interrupt, which skips every subsequent `yield*`/pipe step in the wrapped effect (an interrupt is\n * not a failure — `Effect.tapError` and friends never see it). `onCancel` runs via `Effect.onInterrupt`\n * so every caller gets cancellation cleanup (e.g. resetting a progress monitor stuck at its last\n * `running` snapshot) without each one having to remember to add its own `Effect.onInterrupt`.\n */\nexport const abortWith =\n (\n signal: AbortSignal,\n onCancel: Effect.Effect<void> = Effect.void,\n ): (<A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>) =>\n (effect) =>\n effect.pipe(\n Effect.raceFirst(\n Effect.async<never>((resume) => {\n if (signal.aborted) {\n resume(Effect.interrupt);\n return;\n }\n\n const onAbort = () => {\n resume(\n Effect.gen(function* () {\n log.info('aborting pipeline', {\n span: yield* Effect.currentSpan.pipe(\n Effect.map((span) => span.name),\n Effect.catchAll((_) => Effect.succeed(undefined)),\n ),\n });\n return yield* Effect.interrupt;\n }),\n );\n };\n\n signal.addEventListener('abort', onAbort, { once: true });\n return Effect.sync(() => signal.removeEventListener('abort', onAbort));\n }),\n ),\n Effect.onInterrupt(() => onCancel),\n );\n","//\n// Copyright 2026 DXOS.org\n//\n\n// @import-as-namespace\n\nimport type * as Duration from 'effect/Duration';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\n\nimport { log } from '@dxos/log';\n\nimport * as Progress from './Progress';\n\n/** A destination for progress snapshots — a log line, a file, an app surface, an EDGE stream, … */\nexport type ProgressSink = (snapshot: Progress.ProgressSnapshot) => Effect.Effect<void>;\n\n/** One compact info-log line per snapshot (works everywhere — node, browser, EDGE). */\nexport const logSink: ProgressSink = (snapshot) =>\n Effect.sync(() =>\n log.info('progress', {\n tasks: snapshot.tasks.map(\n (task) => `${task.name} ${task.current}${task.total !== undefined ? `/${task.total}` : ''} ${task.status}`,\n ),\n }),\n );\n\n/**\n * A reporter layer: subscribes to the {@link Progress} registry and flushes the latest snapshot to\n * `sink` at most once per `throttle` (coalescing bursts), plus a final flush when the scope closes.\n * Reactive consumers (a browser panel) can instead `Progress.subscribe` directly for instant\n * updates; this layer is for rate-limited sinks (file, log, EDGE).\n */\nexport const layer = (options: {\n readonly sink: ProgressSink;\n readonly throttle?: Duration.DurationInput;\n}): Layer.Layer<never, never, Progress.Progress> =>\n Layer.scopedDiscard(\n Effect.gen(function* () {\n const progress = yield* Progress.Progress;\n const throttle = options.throttle ?? '2 seconds';\n\n let latest: Progress.ProgressSnapshot | undefined;\n const unsubscribe = progress.subscribe((snapshot) => {\n latest = snapshot;\n });\n yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));\n\n const flush = Effect.suspend(() => {\n const snapshot = latest;\n latest = undefined;\n return snapshot ? options.sink(snapshot) : Effect.void;\n });\n\n // Periodic throttled flush while the scope is open; a final flush captures the terminal state.\n yield* Effect.forkScoped(Effect.forever(flush.pipe(Effect.delay(throttle))));\n yield* Effect.addFinalizer(() => options.sink(progress.snapshot()).pipe(Effect.ignore));\n }),\n );\n"],"mappings":"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"}
@@ -0,0 +1,125 @@
1
+ import * as Effect from "effect/Effect";
2
+ import * as Stream from "effect/Stream";
3
+ import * as Cause from "effect/Cause";
4
+ import * as Context from "effect/Context";
5
+ import * as Layer from "effect/Layer";
6
+ import * as Duration from "effect/Duration";
7
+ import * as Clock from "effect/Clock";
8
+ //#region src/testing/metrics.ts
9
+ var Metrics = class Metrics extends Context.Tag("@dxos/pipeline/testing/Metrics")() {
10
+ /** A fresh, in-memory metrics instance. */
11
+ static layer = Layer.sync(Metrics, () => makeMetrics());
12
+ };
13
+ /** Construct a standalone metrics sink (also usable directly in tests). */
14
+ var makeMetrics = () => {
15
+ const values = /* @__PURE__ */ new Map();
16
+ const addNumber = (name, by) => {
17
+ const current = values.get(name);
18
+ if (typeof current === "string") throw new Error(`Metric '${name}' already holds a string label; cannot increment it.`);
19
+ values.set(name, (current ?? 0) + by);
20
+ };
21
+ return {
22
+ inc: (name, by = 1) => Effect.sync(() => addNumber(name, by)),
23
+ record: (name, value) => Effect.sync(() => void values.set(name, value)),
24
+ time: (name, effect) => Effect.timed(effect).pipe(Effect.map(([duration, result]) => {
25
+ addNumber(`${name}.ms`, Duration.toMillis(duration));
26
+ addNumber(`${name}.count`, 1);
27
+ return result;
28
+ })),
29
+ snapshot: Effect.sync(() => Object.fromEntries(values))
30
+ };
31
+ };
32
+ /** Read the ambient {@link Metrics} service and apply `f` to it. */
33
+ var useMetrics = (f) => Effect.flatMap(Metrics, f);
34
+ //#endregion
35
+ //#region src/testing/benchmark.ts
36
+ /**
37
+ * Run a pipeline across variants (e.g. models) and collect a comparable metrics row per variant:
38
+ * total wall-clock, per-stage {@link instrument} counters, and the evaluator's domain metrics. A
39
+ * variant whose program or evaluator fails is recorded with an `error` (plus whatever metrics were
40
+ * captured before it failed) rather than aborting the whole comparison; an interruption
41
+ * (cancellation) is re-raised so the whole run stops promptly.
42
+ */
43
+ var runBenchmark = (options) => Effect.gen(function* () {
44
+ const variants = [];
45
+ for (const variant of options.variants) {
46
+ const metrics = makeMetrics();
47
+ const layer = Layer.succeed(Metrics, metrics);
48
+ const row = yield* Effect.gen(function* () {
49
+ const heapBefore = heapUsedBytes();
50
+ const [duration, output] = yield* Effect.timed(options.program(variant.config));
51
+ const heapAfter = heapUsedBytes();
52
+ const domain = options.evaluate ? yield* options.evaluate(variant.config, output) : {};
53
+ const snapshot = yield* metrics.snapshot;
54
+ return {
55
+ "total.ms": Math.round(Duration.toMillis(duration)),
56
+ ...heapBefore !== void 0 && heapAfter !== void 0 ? { "heap.mb": Math.round((heapAfter - heapBefore) / (1024 * 1024) * 100) / 100 } : {},
57
+ ...snapshot,
58
+ ...domain
59
+ };
60
+ }).pipe(Effect.provide(layer), Effect.catchAllCause((cause) => Cause.isInterruptedOnly(cause) ? Effect.failCause(cause) : metrics.snapshot.pipe(Effect.map((snapshot) => ({
61
+ ...snapshot,
62
+ error: Cause.pretty(cause).split("\n")[0]
63
+ })))));
64
+ variants.push({
65
+ variant: variant.name,
66
+ metrics: row
67
+ });
68
+ }
69
+ return { variants };
70
+ });
71
+ /** Node process heap usage in bytes, or `undefined` off Node (browser) so the metric is simply omitted. */
72
+ var heapUsedBytes = () => typeof process !== "undefined" && typeof process.memoryUsage === "function" ? process.memoryUsage().heapUsed : void 0;
73
+ var format = (value) => value === void 0 ? "" : typeof value === "number" ? String(Math.round(value * 100) / 100) : value;
74
+ /** Render a benchmark result as a fixed-width metric × variant table (metrics as rows). */
75
+ var renderBenchmark = (result) => {
76
+ const metricNames = [...new Set(result.variants.flatMap((variant) => Object.keys(variant.metrics)))].sort();
77
+ const header = ["metric", ...result.variants.map((variant) => variant.variant)];
78
+ const rows = metricNames.map((metric) => [metric, ...result.variants.map((variant) => format(variant.metrics[metric]))]);
79
+ const widths = header.map((_cell, column) => Math.max(...[header, ...rows].map((row) => row[column].length)));
80
+ const line = (row) => row.map((cell, column) => cell.padEnd(widths[column])).join(" ");
81
+ return [
82
+ line(header),
83
+ widths.map((width) => "-".repeat(width)).join(" "),
84
+ ...rows.map(line)
85
+ ].join("\n");
86
+ };
87
+ //#endregion
88
+ //#region src/testing/capture.ts
89
+ var captureSink = () => {
90
+ const items = [];
91
+ const sink = (out) => Effect.sync(() => {
92
+ items.push(out);
93
+ });
94
+ return {
95
+ sink,
96
+ items
97
+ };
98
+ };
99
+ //#endregion
100
+ //#region src/testing/instrument.ts
101
+ /**
102
+ * Wrap a {@link Stage.Stage} to auto-record per-stage metrics — `${name}.in`, `${name}.out`,
103
+ * `${name}.errors` (counts) and `${name}.ms` (summed processing latency) — through the ambient
104
+ * {@link Metrics} service, with no changes to the stage itself. Compose it in place of the stage:
105
+ * `source.pipe(instrument('extract', s), …)`. The wrapped stage additionally requires `Metrics` in
106
+ * its environment (provided at the edge by the benchmark runner).
107
+ *
108
+ * Latency is the wall-clock between the most recent input entering and an output leaving the stage.
109
+ * For a sequential stage (`Stage.map`, the common case) the item just emitted is the last one pulled
110
+ * in, so `${name}.ms` is the true per-item processing time — including drop/filter stages, whose
111
+ * discarded inputs simply never produce an output to attribute. It is only approximate for a stage
112
+ * that reorders or processes items concurrently (concurrency > 1), where the "most recent input" is
113
+ * no longer the one being emitted. Divide `${name}.ms` by `${name}.out` for the average.
114
+ */
115
+ var instrument = (name, stage) => (self) => {
116
+ let lastIn;
117
+ return stage(self.pipe(Stream.tap(() => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => useMetrics((metrics) => metrics.inc(`${name}.in`)).pipe(Effect.zipRight(Effect.sync(() => void (lastIn = now))))))))).pipe(Stream.tap(() => Clock.currentTimeMillis.pipe(Effect.flatMap((now) => {
118
+ const elapsed = lastIn === void 0 ? 0 : now - lastIn;
119
+ return useMetrics((metrics) => metrics.inc(`${name}.out`)).pipe(Effect.zipRight(useMetrics((metrics) => metrics.inc(`${name}.ms`, elapsed))));
120
+ }))), Stream.tapError(() => useMetrics((metrics) => metrics.inc(`${name}.errors`))));
121
+ };
122
+ //#endregion
123
+ export { Metrics, captureSink, instrument, makeMetrics, renderBenchmark, runBenchmark, useMetrics };
124
+
125
+ //# sourceMappingURL=testing.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"testing.mjs","names":[],"sources":["../../src/testing/metrics.ts","../../src/testing/benchmark.ts","../../src/testing/capture.ts","../../src/testing/instrument.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Context from 'effect/Context';\nimport * as Duration from 'effect/Duration';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\n\n/** A single reported metric: a running number (counter/sum) or a label. */\nexport type MetricValue = number | string;\n\n/** A flat name → value map, as merged into a benchmark row. */\nexport type MetricsSnapshot = Record<string, MetricValue>;\n\n/**\n * Metrics sink a benchmark run writes to. Stages opt in to emit domain metrics (`inc`/`record`/\n * `time`); the {@link instrument} wrapper writes per-stage counters through the same service. One\n * instance per benchmark variant, provided at the edge via {@link Metrics.layer}.\n */\nexport interface MetricsApi {\n /** Add `by` (default 1) to a numeric counter. */\n readonly inc: (name: string, by?: number) => Effect.Effect<void>;\n /** Set a value (last write wins) — for labels or gauges. */\n readonly record: (name: string, value: MetricValue) => Effect.Effect<void>;\n /** Time an effect: adds its duration (ms) to `${name}.ms` and increments `${name}.count`. */\n readonly time: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;\n /** Current values. */\n readonly snapshot: Effect.Effect<MetricsSnapshot>;\n}\n\nexport class Metrics extends Context.Tag('@dxos/pipeline/testing/Metrics')<Metrics, MetricsApi>() {\n /** A fresh, in-memory metrics instance. */\n static layer: Layer.Layer<Metrics> = Layer.sync(Metrics, () => makeMetrics());\n}\n\n/** Construct a standalone metrics sink (also usable directly in tests). */\nexport const makeMetrics = (): MetricsApi => {\n const values = new Map<string, MetricValue>();\n const addNumber = (name: string, by: number) => {\n const current = values.get(name);\n // A name used as both a string label (record) and a counter (inc/time) is a caller bug; fail\n // loudly rather than silently discarding the label and counting from zero.\n if (typeof current === 'string') {\n throw new Error(`Metric '${name}' already holds a string label; cannot increment it.`);\n }\n values.set(name, (current ?? 0) + by);\n };\n const api: MetricsApi = {\n inc: (name, by = 1) => Effect.sync(() => addNumber(name, by)),\n record: (name, value) => Effect.sync(() => void values.set(name, value)),\n time: (name, effect) =>\n Effect.timed(effect).pipe(\n Effect.map(([duration, result]) => {\n addNumber(`${name}.ms`, Duration.toMillis(duration));\n addNumber(`${name}.count`, 1);\n return result;\n }),\n ),\n snapshot: Effect.sync(() => Object.fromEntries(values)),\n };\n return api;\n};\n\n/** Read the ambient {@link Metrics} service and apply `f` to it. */\nexport const useMetrics = <A, E, R>(\n f: (metrics: MetricsApi) => Effect.Effect<A, E, R>,\n): Effect.Effect<A, E, R | Metrics> => Effect.flatMap(Metrics, f);\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Cause from 'effect/Cause';\nimport * as Duration from 'effect/Duration';\nimport * as Effect from 'effect/Effect';\nimport * as Layer from 'effect/Layer';\n\nimport { Metrics, type MetricsSnapshot, type MetricValue, makeMetrics } from './metrics';\n\n/** A named configuration to benchmark (e.g. a model). */\nexport type BenchmarkVariant<Config> = {\n readonly name: string;\n readonly config: Config;\n};\n\n/** One variant's merged metrics: `total.ms`, per-stage `instrument` counters, and evaluator output. */\nexport type VariantResult = {\n readonly variant: string;\n readonly metrics: MetricsSnapshot;\n};\n\nexport type BenchmarkResult = {\n readonly variants: readonly VariantResult[];\n};\n\nexport type BenchmarkOptions<Config, Output, E, R> = {\n readonly variants: readonly BenchmarkVariant<Config>[];\n /**\n * Run the (instrumented) pipeline for one variant and return whatever the evaluator needs\n * (e.g. captured sink outputs). Stage counters and any `Metrics` writes are collected\n * automatically. `Metrics` is provided by the runner.\n */\n readonly program: (config: Config) => Effect.Effect<Output, E, R | Metrics>;\n /**\n * Compute domain metrics for the variant. Effectful, so it can query services (fact store, ECHO\n * db) that the pipeline populated. Its returned map is merged over the auto-collected metrics.\n */\n readonly evaluate?: (config: Config, output: Output) => Effect.Effect<MetricsSnapshot, E, R | Metrics>;\n};\n\n/**\n * Run a pipeline across variants (e.g. models) and collect a comparable metrics row per variant:\n * total wall-clock, per-stage {@link instrument} counters, and the evaluator's domain metrics. A\n * variant whose program or evaluator fails is recorded with an `error` (plus whatever metrics were\n * captured before it failed) rather than aborting the whole comparison; an interruption\n * (cancellation) is re-raised so the whole run stops promptly.\n */\nexport const runBenchmark = <Config, Output, E, R>(\n options: BenchmarkOptions<Config, Output, E, R>,\n): Effect.Effect<BenchmarkResult, E, Exclude<R, Metrics>> =>\n Effect.gen(function* () {\n const variants: VariantResult[] = [];\n for (const variant of options.variants) {\n const metrics = makeMetrics();\n const layer = Layer.succeed(Metrics, metrics);\n const row = yield* Effect.gen(function* () {\n const heapBefore = heapUsedBytes();\n const [duration, output] = yield* Effect.timed(options.program(variant.config));\n const heapAfter = heapUsedBytes();\n const domain = options.evaluate ? yield* options.evaluate(variant.config, output) : {};\n const snapshot = yield* metrics.snapshot;\n return {\n 'total.ms': Math.round(Duration.toMillis(duration)),\n // Heap growth across the run (Node only; approximate — subject to GC, and for out-of-process\n // model back-ends like Ollama it reflects harness overhead, not the model's own memory).\n ...(heapBefore !== undefined && heapAfter !== undefined\n ? { 'heap.mb': Math.round(((heapAfter - heapBefore) / (1024 * 1024)) * 100) / 100 }\n : {}),\n ...snapshot,\n ...domain,\n } satisfies MetricsSnapshot;\n }).pipe(\n Effect.provide(layer),\n Effect.catchAllCause((cause) =>\n // A cancelled benchmark must abort, not be recorded as an `error` row and iterated past;\n // only genuine failures/defects degrade to a metrics row.\n Cause.isInterruptedOnly(cause)\n ? Effect.failCause(cause)\n : metrics.snapshot.pipe(\n Effect.map(\n (snapshot) => ({ ...snapshot, error: Cause.pretty(cause).split('\\n')[0] }) satisfies MetricsSnapshot,\n ),\n ),\n ),\n );\n variants.push({ variant: variant.name, metrics: row });\n }\n return { variants };\n });\n\n/** Node process heap usage in bytes, or `undefined` off Node (browser) so the metric is simply omitted. */\nconst heapUsedBytes = (): number | undefined =>\n typeof process !== 'undefined' && typeof process.memoryUsage === 'function'\n ? process.memoryUsage().heapUsed\n : undefined;\n\nconst format = (value: MetricValue | undefined): string =>\n value === undefined ? '' : typeof value === 'number' ? String(Math.round(value * 100) / 100) : value;\n\n/** Render a benchmark result as a fixed-width metric × variant table (metrics as rows). */\nexport const renderBenchmark = (result: BenchmarkResult): string => {\n const metricNames = [...new Set(result.variants.flatMap((variant) => Object.keys(variant.metrics)))].sort();\n const header = ['metric', ...result.variants.map((variant) => variant.variant)];\n const rows = metricNames.map((metric) => [\n metric,\n ...result.variants.map((variant) => format(variant.metrics[metric])),\n ]);\n const widths = header.map((_cell, column) => Math.max(...[header, ...rows].map((row) => row[column].length)));\n const line = (row: readonly string[]) => row.map((cell, column) => cell.padEnd(widths[column])).join(' ');\n return [line(header), widths.map((width) => '-'.repeat(width)).join(' '), ...rows.map(line)].join('\\n');\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Effect from 'effect/Effect';\n\nimport * as Pipeline from '../Pipeline';\n\n/** In-memory sink capturing every emitted value for assertions. */\nexport type CaptureSink<Out> = {\n readonly sink: Pipeline.Sink<Out>;\n readonly items: Out[];\n};\n\nexport const captureSink = <Out>(): CaptureSink<Out> => {\n const items: Out[] = [];\n const sink: Pipeline.Sink<Out> = (out) =>\n Effect.sync(() => {\n items.push(out);\n });\n return { sink, items };\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport * as Clock from 'effect/Clock';\nimport * as Effect from 'effect/Effect';\nimport * as Stream from 'effect/Stream';\n\nimport * as Stage from '../Stage';\nimport { Metrics, useMetrics } from './metrics';\n\n/**\n * Wrap a {@link Stage.Stage} to auto-record per-stage metrics — `${name}.in`, `${name}.out`,\n * `${name}.errors` (counts) and `${name}.ms` (summed processing latency) — through the ambient\n * {@link Metrics} service, with no changes to the stage itself. Compose it in place of the stage:\n * `source.pipe(instrument('extract', s), …)`. The wrapped stage additionally requires `Metrics` in\n * its environment (provided at the edge by the benchmark runner).\n *\n * Latency is the wall-clock between the most recent input entering and an output leaving the stage.\n * For a sequential stage (`Stage.map`, the common case) the item just emitted is the last one pulled\n * in, so `${name}.ms` is the true per-item processing time — including drop/filter stages, whose\n * discarded inputs simply never produce an output to attribute. It is only approximate for a stage\n * that reorders or processes items concurrently (concurrency > 1), where the \"most recent input\" is\n * no longer the one being emitted. Divide `${name}.ms` by `${name}.out` for the average.\n */\nexport const instrument =\n <In, Out, E, R>(name: string, stage: Stage.Stage<In, Out, E, R>): Stage.Stage<In, Out, E, R | Metrics> =>\n (self) => {\n // Timestamp of the most recently ingested item. A sequential stage emits the item it last pulled,\n // so pairing an output with this (rather than FIFO-oldest) stays correct when inputs are dropped.\n let lastIn: number | undefined;\n return stage(\n self.pipe(\n Stream.tap(() =>\n Clock.currentTimeMillis.pipe(\n Effect.flatMap((now) =>\n useMetrics((metrics) => metrics.inc(`${name}.in`)).pipe(\n Effect.zipRight(Effect.sync(() => void (lastIn = now))),\n ),\n ),\n ),\n ),\n ),\n ).pipe(\n Stream.tap(() =>\n Clock.currentTimeMillis.pipe(\n Effect.flatMap((now) => {\n const elapsed = lastIn === undefined ? 0 : now - lastIn;\n return useMetrics((metrics) => metrics.inc(`${name}.out`)).pipe(\n Effect.zipRight(useMetrics((metrics) => metrics.inc(`${name}.ms`, elapsed))),\n );\n }),\n ),\n ),\n Stream.tapError(() => useMetrics((metrics) => metrics.inc(`${name}.errors`))),\n );\n };\n"],"mappings":"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"}
@@ -28,4 +28,14 @@ export declare const run: {
28
28
  <Out, E2, R2>(options: RunOptions<Out, E2, R2>): <E, R>(source: Stream.Stream<Out, E, R>) => Effect.Effect<void, E2 | E, R2 | R>;
29
29
  <Out, E, R, E2, R2>(source: Stream.Stream<Out, E, R>, options: RunOptions<Out, E2, R2>): Effect.Effect<void, E2 | E, R2 | R>;
30
30
  };
31
+ /**
32
+ * Abort a pipeline with an `AbortSignal`.
33
+ *
34
+ * Races the wrapped effect against the signal; losing the race resolves as a genuine fiber
35
+ * interrupt, which skips every subsequent `yield*`/pipe step in the wrapped effect (an interrupt is
36
+ * not a failure — `Effect.tapError` and friends never see it). `onCancel` runs via `Effect.onInterrupt`
37
+ * so every caller gets cancellation cleanup (e.g. resetting a progress monitor stuck at its last
38
+ * `running` snapshot) without each one having to remember to add its own `Effect.onInterrupt`.
39
+ */
40
+ export declare const abortWith: (signal: AbortSignal, onCancel?: Effect.Effect<void>) => (<A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>);
31
41
  //# sourceMappingURL=Pipeline.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Pipeline.d.ts","sourceRoot":"","sources":["../../../src/Pipeline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEtF,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI;IAClD,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EACV,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACnF,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAChC,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;CASxC,CAAC"}
1
+ {"version":3,"file":"Pipeline.d.ts","sourceRoot":"","sources":["../../../src/Pipeline.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAIxC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEtF,MAAM,MAAM,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI;IAClD,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EACV,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAC/B,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IACnF,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAChC,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,GAC/B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;CASxC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,WAEV,WAAW,aACT,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAC5B,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CA6BpE,CAAC"}
@@ -0,0 +1,17 @@
1
+ import * as Context from 'effect/Context';
2
+ import * as Layer from 'effect/Layer';
3
+ import { Progress as ProgressCore } from '@dxos/progress';
4
+ export type TaskStatus = ProgressCore.TaskStatus;
5
+ export type TaskProgress = ProgressCore.TaskProgress;
6
+ export type ProgressSnapshot = ProgressCore.ProgressSnapshot;
7
+ export type TaskHandle = ProgressCore.TaskHandle;
8
+ export type ProgressApi = ProgressCore.ProgressApi;
9
+ export declare const make: () => ProgressCore.ProgressApi;
10
+ export declare const deriveEta: (task: ProgressCore.TaskProgress) => number | undefined;
11
+ declare const Progress_base: Context.TagClass<Progress, "@dxos/pipeline/Progress", ProgressCore.ProgressApi>;
12
+ export declare class Progress extends Progress_base {
13
+ /** A fresh in-memory registry. */
14
+ static layer: Layer.Layer<Progress>;
15
+ }
16
+ export {};
17
+ //# sourceMappingURL=Progress.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Progress.d.ts","sourceRoot":"","sources":["../../../src/Progress.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAI1D,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC;AACjD,MAAM,MAAM,YAAY,GAAG,YAAY,CAAC,YAAY,CAAC;AACrD,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAC;AAC7D,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,WAAW,CAAC;AACnD,eAAO,MAAM,IAAI,gCAAoB,CAAC;AACtC,eAAO,MAAM,SAAS,yDAAyB,CAAC;;AAEhD,qBAAa,QAAS,SAAQ,aAA4E;IACxG,kCAAkC;IAClC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAmD;CACvF"}
@@ -0,0 +1,19 @@
1
+ import type * as Duration from 'effect/Duration';
2
+ import * as Effect from 'effect/Effect';
3
+ import * as Layer from 'effect/Layer';
4
+ import * as Progress from './Progress';
5
+ /** A destination for progress snapshots — a log line, a file, an app surface, an EDGE stream, … */
6
+ export type ProgressSink = (snapshot: Progress.ProgressSnapshot) => Effect.Effect<void>;
7
+ /** One compact info-log line per snapshot (works everywhere — node, browser, EDGE). */
8
+ export declare const logSink: ProgressSink;
9
+ /**
10
+ * A reporter layer: subscribes to the {@link Progress} registry and flushes the latest snapshot to
11
+ * `sink` at most once per `throttle` (coalescing bursts), plus a final flush when the scope closes.
12
+ * Reactive consumers (a browser panel) can instead `Progress.subscribe` directly for instant
13
+ * updates; this layer is for rate-limited sinks (file, log, EDGE).
14
+ */
15
+ export declare const layer: (options: {
16
+ readonly sink: ProgressSink;
17
+ readonly throttle?: Duration.DurationInput;
18
+ }) => Layer.Layer<never, never, Progress.Progress>;
19
+ //# sourceMappingURL=ProgressReporter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ProgressReporter.d.ts","sourceRoot":"","sources":["../../../src/ProgressReporter.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AAEvC,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAExF,uFAAuF;AACvF,eAAO,MAAM,OAAO,EAAE,YAOnB,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,KAAK,YAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,aAAa,CAAC;CAC5C,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAsB5C,CAAC"}
@@ -1,5 +1,6 @@
1
1
  import * as Effect from 'effect/Effect';
2
2
  import * as Stream from 'effect/Stream';
3
+ import * as Progress from './Progress';
3
4
  /**
4
5
  * Overflow policy applied when a consumer cannot keep pace, mapped onto `Stream.buffer` strategies.
5
6
  * - `suspend`: back pressure — never drop (default; correct for email/document processing).
@@ -60,5 +61,16 @@ export declare const map: <In, Out, E, R>(id: string, fn: (item: In) => Effect.E
60
61
  export declare const window: <In, Out, E, R>(id: string, size: number, fn: (window: readonly In[]) => Effect.Effect<Out, E, R>, options?: WindowOptions) => Stage<In, Exclude<Out, undefined>, E, R>;
61
62
  /** Drop items that do not match `pred`. */
62
63
  export declare const filter: <In>(id: string, pred: (item: In) => boolean) => Stage<In, In>;
64
+ /**
65
+ * A pass-through stage that reports live progress to the {@link Progress} registry: it registers the
66
+ * task (with an optional item `total`), advances the item index as each item flows through, marks the
67
+ * task done only when the stream ends successfully, and marks it failed if the stream errors.
68
+ * Progress is thus an artifact of the pipeline itself — the same stage works in the app (feeding a
69
+ * reactive panel) and in tests (feeding a file sink).
70
+ */
71
+ export declare const track: <In>(name: string, options?: {
72
+ total?: number;
73
+ label?: string;
74
+ }) => Stage<In, In, never, Progress.Progress>;
63
75
  export {};
64
76
  //# sourceMappingURL=Stage.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Stage.d.ts","sourceRoot":"","sources":["../../../src/Stage.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;AAExC,sDAAsD;AACtD,KAAK,aAAa,GAAG;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG;IACvC,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC;AAW1C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GACb,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MACR,MAAM,MACN,CAAC,IAAI,EAAE,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,YACjC,UAAU,KAClB,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAUvC,CAAC;AAEN;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAC9B,MAAM,QACJ,MAAM,MACR,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,YAC9C,aAAa,KACrB,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAiBzC,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,MAAM,GAChB,EAAE,MAAM,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,OAAO,KAAG,KAAK,CAAC,EAAE,EAAE,EAAE,CAE3B,CAAC"}
1
+ {"version":3,"file":"Stage.d.ts","sourceRoot":"","sources":["../../../src/Stage.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,KAAK,EACxE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,KAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;AAExC,sDAAsD;AACtD,KAAK,aAAa,GAAG;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG;IACvC,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC;AAW1C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GACb,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MACR,MAAM,MACN,CAAC,IAAI,EAAE,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,YACjC,UAAU,KAClB,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAUvC,CAAC;AAEN;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM,GAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,MAC9B,MAAM,QACJ,MAAM,MACR,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,YAC9C,aAAa,KACrB,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAiBzC,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,MAAM,GAChB,EAAE,MAAM,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,OAAO,KAAG,KAAK,CAAC,EAAE,EAAE,EAAE,CAE3B,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GACf,EAAE,QAAQ,MAAM,YAAW;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAQ,KAAK,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAezG,CAAC"}
@@ -1,3 +1,5 @@
1
1
  export * as Pipeline from './Pipeline';
2
+ export * as Progress from './Progress';
3
+ export * as ProgressReporter from './ProgressReporter';
2
4
  export * as Stage from './Stage';
3
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,gBAAgB,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC"}
@@ -0,0 +1,40 @@
1
+ import * as Effect from 'effect/Effect';
2
+ import { Metrics, type MetricsSnapshot } from './metrics';
3
+ /** A named configuration to benchmark (e.g. a model). */
4
+ export type BenchmarkVariant<Config> = {
5
+ readonly name: string;
6
+ readonly config: Config;
7
+ };
8
+ /** One variant's merged metrics: `total.ms`, per-stage `instrument` counters, and evaluator output. */
9
+ export type VariantResult = {
10
+ readonly variant: string;
11
+ readonly metrics: MetricsSnapshot;
12
+ };
13
+ export type BenchmarkResult = {
14
+ readonly variants: readonly VariantResult[];
15
+ };
16
+ export type BenchmarkOptions<Config, Output, E, R> = {
17
+ readonly variants: readonly BenchmarkVariant<Config>[];
18
+ /**
19
+ * Run the (instrumented) pipeline for one variant and return whatever the evaluator needs
20
+ * (e.g. captured sink outputs). Stage counters and any `Metrics` writes are collected
21
+ * automatically. `Metrics` is provided by the runner.
22
+ */
23
+ readonly program: (config: Config) => Effect.Effect<Output, E, R | Metrics>;
24
+ /**
25
+ * Compute domain metrics for the variant. Effectful, so it can query services (fact store, ECHO
26
+ * db) that the pipeline populated. Its returned map is merged over the auto-collected metrics.
27
+ */
28
+ readonly evaluate?: (config: Config, output: Output) => Effect.Effect<MetricsSnapshot, E, R | Metrics>;
29
+ };
30
+ /**
31
+ * Run a pipeline across variants (e.g. models) and collect a comparable metrics row per variant:
32
+ * total wall-clock, per-stage {@link instrument} counters, and the evaluator's domain metrics. A
33
+ * variant whose program or evaluator fails is recorded with an `error` (plus whatever metrics were
34
+ * captured before it failed) rather than aborting the whole comparison; an interruption
35
+ * (cancellation) is re-raised so the whole run stops promptly.
36
+ */
37
+ export declare const runBenchmark: <Config, Output, E, R>(options: BenchmarkOptions<Config, Output, E, R>) => Effect.Effect<BenchmarkResult, E, Exclude<R, Metrics>>;
38
+ /** Render a benchmark result as a fixed-width metric × variant table (metrics as rows). */
39
+ export declare const renderBenchmark: (result: BenchmarkResult) => string;
40
+ //# sourceMappingURL=benchmark.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../../../src/testing/benchmark.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,EAAE,OAAO,EAAE,KAAK,eAAe,EAAiC,MAAM,WAAW,CAAC;AAEzF,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,CAAC,MAAM,IAAI;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,uGAAuG;AACvG,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC;IAC5E;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC;CACxG,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,WACtC,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,KAC9C,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,CAuCpD,CAAC;AAWL,2FAA2F;AAC3F,eAAO,MAAM,eAAe,WAAY,eAAe,KAAG,MAUzD,CAAC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=benchmark.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"benchmark.test.d.ts","sourceRoot":"","sources":["../../../../src/testing/benchmark.test.ts"],"names":[],"mappings":""}
@@ -1,2 +1,5 @@
1
+ export * from './benchmark';
1
2
  export * from './capture';
3
+ export * from './instrument';
4
+ export * from './metrics';
2
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAIA,cAAc,WAAW,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
@@ -0,0 +1,18 @@
1
+ import * as Stage from '../Stage';
2
+ import { Metrics } from './metrics';
3
+ /**
4
+ * Wrap a {@link Stage.Stage} to auto-record per-stage metrics — `${name}.in`, `${name}.out`,
5
+ * `${name}.errors` (counts) and `${name}.ms` (summed processing latency) — through the ambient
6
+ * {@link Metrics} service, with no changes to the stage itself. Compose it in place of the stage:
7
+ * `source.pipe(instrument('extract', s), …)`. The wrapped stage additionally requires `Metrics` in
8
+ * its environment (provided at the edge by the benchmark runner).
9
+ *
10
+ * Latency is the wall-clock between the most recent input entering and an output leaving the stage.
11
+ * For a sequential stage (`Stage.map`, the common case) the item just emitted is the last one pulled
12
+ * in, so `${name}.ms` is the true per-item processing time — including drop/filter stages, whose
13
+ * discarded inputs simply never produce an output to attribute. It is only approximate for a stage
14
+ * that reorders or processes items concurrently (concurrency > 1), where the "most recent input" is
15
+ * no longer the one being emitted. Divide `${name}.ms` by `${name}.out` for the average.
16
+ */
17
+ export declare const instrument: <In, Out, E, R>(name: string, stage: Stage.Stage<In, Out, E, R>) => Stage.Stage<In, Out, E, R | Metrics>;
18
+ //# sourceMappingURL=instrument.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../../../src/testing/instrument.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,KAAK,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,OAAO,EAAc,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GACpB,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,MAAM,SAAS,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CA8BpG,CAAC"}
@@ -0,0 +1,33 @@
1
+ import * as Context from 'effect/Context';
2
+ import * as Effect from 'effect/Effect';
3
+ import * as Layer from 'effect/Layer';
4
+ /** A single reported metric: a running number (counter/sum) or a label. */
5
+ export type MetricValue = number | string;
6
+ /** A flat name → value map, as merged into a benchmark row. */
7
+ export type MetricsSnapshot = Record<string, MetricValue>;
8
+ /**
9
+ * Metrics sink a benchmark run writes to. Stages opt in to emit domain metrics (`inc`/`record`/
10
+ * `time`); the {@link instrument} wrapper writes per-stage counters through the same service. One
11
+ * instance per benchmark variant, provided at the edge via {@link Metrics.layer}.
12
+ */
13
+ export interface MetricsApi {
14
+ /** Add `by` (default 1) to a numeric counter. */
15
+ readonly inc: (name: string, by?: number) => Effect.Effect<void>;
16
+ /** Set a value (last write wins) — for labels or gauges. */
17
+ readonly record: (name: string, value: MetricValue) => Effect.Effect<void>;
18
+ /** Time an effect: adds its duration (ms) to `${name}.ms` and increments `${name}.count`. */
19
+ readonly time: <A, E, R>(name: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
20
+ /** Current values. */
21
+ readonly snapshot: Effect.Effect<MetricsSnapshot>;
22
+ }
23
+ declare const Metrics_base: Context.TagClass<Metrics, "@dxos/pipeline/testing/Metrics", MetricsApi>;
24
+ export declare class Metrics extends Metrics_base {
25
+ /** A fresh, in-memory metrics instance. */
26
+ static layer: Layer.Layer<Metrics>;
27
+ }
28
+ /** Construct a standalone metrics sink (also usable directly in tests). */
29
+ export declare const makeMetrics: () => MetricsApi;
30
+ /** Read the ambient {@link Metrics} service and apply `f` to it. */
31
+ export declare const useMetrics: <A, E, R>(f: (metrics: MetricsApi) => Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Metrics>;
32
+ export {};
33
+ //# sourceMappingURL=metrics.d.ts.map