@moureau/pipeflow 0.0.1 → 0.0.3

package/dist/types/transport/streamobject/field-stream/field-stream.d.ts

@@ -0,0 +1,85 @@
+/**
+ * FieldStream — the semantic completion core shared by every source adapter.
+ *
+ * A FieldStream registers completion handlers (`when`/`whenItem`/`whenObjectDone`)
+ * and dispatches completion events to them. It knows nothing about JSON, wire
+ * records, SSE, or any particular producer: subclasses turn their source into
+ * completion events via the protected emit helpers.
+ *
+ * Implementations:
+ *   - StreamObject       — consumes an AsyncIterable of text chunks (JSON source)
+ *   - ConversationStream — consumes conversation events (provider-native source)
+ *
+ * Lifecycle, per object:
+ *
+ *   STREAMING ──emitObject──▶ DONE
+ *       │
+ *       ├──cancel()──▶ CANCELLED
+ *       └──fail()────▶ FAILED
+ *
+ * Exactly-once: within an object, completion handlers fire at most once per
+ * boundary and never after a terminal state (events after DONE/CANCELLED/
+ * FAILED are dropped). cancel() is idempotent. Multi-object sources call
+ * beginObject() to start each object.
+ *
+ * `when` means completion, not mutation: handlers never see chunks or source
+ * format. Handlers are invoked synchronously at the completion boundary and
+ * never block the producer; async handlers run concurrently and their
+ * rejections are routed to onError.
+ *
+ * Errors: delivered to onError handlers when registered; otherwise the
+ * subclass decides (StreamObject rejects start(); callers of `fail()` get the
+ * throw).
+ */
+import type { Event, FieldValue, ScalarValue, Schema } from "../reference/reference.js";
+export type FieldHandler = (value: FieldValue) => void;
+export type ItemHandler = (value: ScalarValue, index: number) => void;
+export type ObjectDoneHandler = (object: Record<string, unknown>) => void;
+export type ErrorHandler = (error: Error) => void;
+export interface FieldStreamOptions {
+    /** Invoked by cancel() — e.g. to abort the producer's request. */
+    onCancel?: () => void;
+}
+export declare abstract class FieldStream {
+    protected readonly schema: Schema;
+    private readonly fieldHandlers;
+    private readonly itemHandlers;
+    private readonly objectHandlers;
+    private readonly errorHandlers;
+    private readonly onCancel;
+    /** Stream-level: set by cancel(); consumed by source-driven subclasses. */
+    protected cancelled: boolean;
+    private objectState;
+    constructor(schema: Schema, options?: FieldStreamOptions);
+    when(field: string | string[], handler: FieldHandler): this;
+    whenItem(field: string | string[], handler: ItemHandler): this;
+    whenObjectDone(handler: ObjectDoneHandler): this;
+    onError(handler: ErrorHandler): this;
+    /**
+     * Abort the current object and stop the producer (idempotent). The object
+     * will not complete; already-delivered items remain valid partial state.
+     */
+    cancel(): void;
+    /** Start a new object's lifecycle (multi-object sources call this per object). */
+    protected beginObject(): void;
+    /** Emit a completed field value (subclasses call this at the completion boundary). */
+    protected emitField(field: number, value: FieldValue): void;
+    /** Emit a completed array item. */
+    protected emitItem(field: number, index: number, value: ScalarValue): void;
+    /**
+     * Complete the current object: materializes and fires whenObjectDone exactly
+     * once (a second call, or a call after cancel/fail, is ignored).
+     */
+    protected emitObject(events: Event[]): void;
+    /** Abort the current object without completing it (idempotent). */
+    protected cancelObject(): void;
+    /**
+     * Route a source/adapter failure to onError (or rethrow when unhandled) and
+     * mark the current object failed.
+     */
+    protected fail(error: unknown): void;
+    protected get objectCompleted(): boolean;
+    protected resolveIndex(field: string | string[]): number;
+    private fire;
+    private dispatchError;
+}

package/dist/types/transport/streamobject/field-stream/index.d.ts

@@ -0,0 +1,2 @@
+export { FieldStream } from "./field-stream.js";
+export type { ErrorHandler, FieldHandler, FieldStreamOptions, ItemHandler, ObjectDoneHandler, } from "./field-stream.js";

package/dist/types/transport/streamobject/index.d.ts

@@ -0,0 +1,8 @@
+export { FieldStream } from "./field-stream/index.js";
+export type { ErrorHandler, FieldHandler, FieldStreamOptions, ItemHandler, ObjectDoneHandler, } from "./field-stream/index.js";
+export { StreamObject } from "./stream-object/index.js";
+export type { StreamObjectOptions } from "./stream-object/index.js";
+export { IncrementalJsonParser, JsonToStreamObjectAdapter } from "./json-adapter/index.js";
+export type { JsonAdapterCallbacks, JsonValue } from "./json-adapter/index.js";
+export { ReferenceDecoder, Receiver, decode, encodeText, executeRecords, materializeObject, parseBooleanPayload, parseIntegerPayload, parseNumberPayload, } from "./reference/index.js";
+export type { Decoder, Event, FieldDef, FieldType, FieldValue, Payload, ScalarValue, Schema, StreamRecord, } from "./reference/index.js";

package/dist/types/transport/streamobject/json-adapter/index.d.ts

@@ -0,0 +1,2 @@
+export { IncrementalJsonParser, JsonToStreamObjectAdapter } from "./json-adapter.js";
+export type { JsonAdapterCallbacks, JsonValue } from "./json-adapter.js";

package/dist/types/transport/streamobject/json-adapter/json-adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Incremental JSON → StreamObject adapter.
+ *
+ * Consumes a JSON token stream (e.g. LLM output deltas) and emits StreamObject
+ * field-completion events as soon as each schema field's value is complete —
+ * without waiting for the rest of the object. This is the designed production
+ * shape of the protocol: the model emits ordinary output, deterministic
+ * software does the parsing, and consumers react at field boundaries.
+ *
+ * The wire encoding is irrelevant here; only the Event model matters.
+ */
+import type { Event, FieldValue, ScalarValue, Schema } from "../reference/reference.js";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Minimal incremental JSON parser. Emits every completed value with its path. */
+export declare class IncrementalJsonParser {
+    private readonly onValueDone;
+    private readonly stack;
+    private value;
+    private started;
+    private done;
+    constructor(onValueDone: (path: string[], value: JsonValue) => void);
+    push(chunk: string): void;
+    private pushChar;
+    private dispatch;
+    private startValue;
+    private feedValue;
+    private completeValue;
+    private closeContainer;
+}
+export interface JsonAdapterCallbacks {
+    onFieldDone?: (field: number, value: FieldValue) => void;
+    /** Fires for each completed array element, before the array field completes. */
+    onItemDone?: (field: number, index: number, value: ScalarValue) => void;
+    /** Fires when the root object closes. */
+    onObjectDone?: () => void;
+}
+/**
+ * Feeds a JSON token stream into the reference Event model and emits a
+ * completion hierarchy as soon as each piece is known:
+ *
+ *   VALUE_COMPLETE  → every parsed value (parser level, per path)
+ *   ITEM_COMPLETE   → each array element of an array-typed schema field
+ *   FIELD_COMPLETE  → a schema field's whole value (incl. a closed array)
+ *   OBJECT_COMPLETE → the object closed
+ *
+ * The v0.1 wire decoder only exposes FIELD/OBJECT; item completion is a
+ * semantic projection of array boundaries that every source already carries
+ * (each JSON array element, each array append), not a wire record. Strictly
+ * typed against the schema — a value that violates its field type throws.
+ */
+export declare class JsonToStreamObjectAdapter {
+    private readonly fields;
+    private readonly parser;
+    private readonly events;
+    private readonly onFieldDone;
+    private readonly onItemDone;
+    private readonly onObjectDone;
+    constructor(schema: Schema, callbacks?: JsonAdapterCallbacks);
+    push(chunk: string): void;
+    getEvents(): Event[];
+    private handleValue;
+    private matchArrayItem;
+}

package/dist/types/transport/streamobject/reference/index.d.ts

@@ -0,0 +1,2 @@
+export { ReferenceDecoder, Receiver, decode, encodeText, executeRecords, materializeObject, parseBooleanPayload, parseIntegerPayload, parseNumberPayload, } from "./reference.js";
+export type { Decoder, Event, FieldDef, FieldType, FieldValue, Payload, ScalarValue, Schema, StreamRecord, } from "./reference.js";

package/dist/types/transport/streamobject/reference/reference.d.ts

@@ -0,0 +1,127 @@
+/**
+ * StreamObject Protocol v0.1 — reference implementation (the executable spec).
+ *
+ * Deliberately boring: no arena, no pooling, no typed-array chunk chains.
+ * Its purpose is to pin down semantics so the optimized receiver can be
+ * validated against it instead of inventing behavior.
+ *
+ * Layering:
+ *   records --(encodeText)--> text --(fragment)--> chunks
+ *   chunks --(ReferenceDecoder)--> events
+ *   records --(Receiver / executeRecords)--> events   <- the oracle
+ *
+ * Contract (the property every decoder must satisfy):
+ *   decode(fragment(encodeText(records)))  ===  executeRecords(records)
+ *
+ * See README.md (in this directory) for the normative spec this implements.
+ */
+export type Payload = string;
+export type StreamRecord = {
+    kind: "append";
+    field: number;
+    payload: Payload;
+} | {
+    kind: "complete";
+    field: number;
+} | {
+    kind: "object-complete";
+} | {
+    kind: "object-abort";
+};
+export type FieldType = "string" | "integer" | "number" | "boolean";
+export interface FieldDef {
+    path: string[];
+    type: FieldType;
+    mode?: "array";
+    /** Required for array fields. */
+    maxItems?: number;
+    /** Scalar: cap on accumulated payload length. Array: cap per item. */
+    maxLength?: number;
+}
+export type Schema = FieldDef[];
+export type ScalarValue = string | number | boolean;
+export type FieldValue = ScalarValue | ScalarValue[];
+export type Event = {
+    kind: "field";
+    field: number;
+    value: FieldValue;
+}
+/** Adapter-observable item completion (arrays); not emitted by the v0.1 wire decoder. */
+ | {
+    kind: "item";
+    field: number;
+    index: number;
+    value: ScalarValue;
+} | {
+    kind: "object-complete";
+} | {
+    kind: "object-abort";
+};
+export declare function parseIntegerPayload(s: string): number | null;
+export declare function parseNumberPayload(s: string): number | null;
+export declare function parseBooleanPayload(s: string): boolean | null;
+export declare class Receiver {
+    private readonly schema;
+    private readonly state;
+    private readonly acc;
+    private readonly events;
+    private readonly onEvent;
+    private ended;
+    constructor(schema: Schema, onEvent?: (event: Event) => void);
+    append(field: number, payload: string): void;
+    complete(field: number): void;
+    objectComplete(): void;
+    objectAbort(): void;
+    getEvents(): Event[];
+    get isEnded(): boolean;
+    private assertActive;
+    private assertField;
+    private emit;
+}
+/** The oracle: execute logical records directly. */
+export declare function executeRecords(schema: Schema, records: StreamRecord[]): Event[];
+export declare function materializeObject(schema: Schema, events: Event[]): Record<string, unknown>;
+export declare function encodeText(records: StreamRecord[]): string;
+/**
+ * The contract every implementation (including the future arena-backed
+ * receiver) must satisfy:
+ *
+ *   push(fragment(encodeText(records))) + end()  ===  executeRecords(schema, records)
+ */
+export interface Decoder {
+    push(chunk: string): void;
+    end(): Event[];
+}
+export declare class ReferenceDecoder implements Decoder {
+    private readonly receiver;
+    private state;
+    private fieldId;
+    private length;
+    private payload;
+    private remaining;
+    constructor(schema: Schema, onEvent?: (event: Event) => void);
+    push(chunk: string): void;
+    end(): Event[];
+    private onHeader;
+    private onFieldId;
+    private onLength;
+    private onPayload;
+    private onPayloadEnd;
+    private onControl;
+    private onAbort;
+    private reset;
+}
+/** Decode a sequence of transport chunks into events. */
+export declare function decode(chunks: string[], schema: Schema): Event[];
+export type Rng = () => number;
+export declare function mulberry32(seed: number): Rng;
+export declare function fragment(text: string, rng: Rng): string[];
+/** Every single-cut fragmentation of a message. */
+export declare function allSingleCuts(text: string): string[][];
+/** Every composition into 1..n chunks — 2^(n-1) cases. Only for small messages. */
+export declare function allCompositions(text: string): string[][];
+export declare function randomSchema(rng: Rng): Schema;
+/** Records for one field: appends (one item each for arrays), maybe a completion. */
+export declare function fieldRecords(rng: Rng, schema: Schema, field: number): StreamRecord[];
+/** A valid record sequence for the schema, randomly scheduled. */
+export declare function generateValidRecords(rng: Rng, schema: Schema): StreamRecord[];

package/dist/types/transport/streamobject/stream-object/index.d.ts

@@ -0,0 +1,2 @@
+export { StreamObject } from "./stream-object.js";
+export type { ErrorHandler, FieldHandler, ItemHandler, ObjectDoneHandler, StreamObjectOptions, } from "./stream-object.js";

package/dist/types/transport/streamobject/stream-object/stream-object.d.ts

@@ -0,0 +1,31 @@
+/**
+ * StreamObject — consumes an AsyncIterable of text chunks through the
+ * incremental JSON adapter and exposes the FieldStream completion API.
+ *
+ *   const stream = new StreamObject(source, schema);
+ *   stream.when("summary", (summary) => { ... });            // field completion
+ *   stream.whenItem("searchQueries", (query, i) => { ... }); // item completion
+ *   stream.whenObjectDone((object) => { ... });              // whole object
+ *   stream.onError((error) => { ... });                      // failures
+ *   await stream.start();
+ *
+ * `when` means completion, not mutation: handlers never see chunks, JSON,
+ * SSE, or the wire codec. Handlers are invoked synchronously at the
+ * completion boundary and never block the source; async handlers run
+ * concurrently and their rejections are routed to onError. `cancel()` stops
+ * the source and invokes the optional onCancel hook (e.g. to abort the
+ * producer's request).
+ *
+ * Errors: delivered to onError handlers when registered; otherwise start()
+ * rejects with the error. Cancelling the stream is not an error.
+ */
+import { FieldStream, type FieldStreamOptions } from "../field-stream/field-stream.js";
+import type { Schema } from "../reference/reference.js";
+export type { ErrorHandler, FieldHandler, FieldStreamOptions, ItemHandler, ObjectDoneHandler, } from "../field-stream/field-stream.js";
+export type StreamObjectOptions = FieldStreamOptions;
+export declare class StreamObject extends FieldStream {
+    private readonly source;
+    private started;
+    constructor(source: AsyncIterable<string>, schema: Schema, options?: StreamObjectOptions);
+    start(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moureau/pipeflow",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
   "private": false,
   "sideEffects": false,
@@ -28,6 +28,12 @@
       "require": "./dist/cjs/index.js",
       "default": "./dist/esm/index.js"
     },
+    "./client": {
+      "types": "./dist/types/client/index.d.ts",
+      "import": "./dist/esm/client/index.js",
+      "require": "./dist/cjs/client/index.js",
+      "default": "./dist/esm/client/index.js"
+    },
     "./providers": {
       "types": "./dist/types/providers/index.d.ts",
       "import": "./dist/esm/providers/index.js",
@@ -63,13 +69,31 @@
       "import": "./dist/esm/transport/*/index.js",
       "require": "./dist/cjs/transport/*/index.js",
       "default": "./dist/esm/transport/*/index.js"
+    },
+    "./conversations": {
+      "types": "./dist/types/conversations/index.d.ts",
+      "import": "./dist/esm/conversations/index.js",
+      "require": "./dist/cjs/conversations/index.js",
+      "default": "./dist/esm/conversations/index.js"
+    },
+    "./conversations/*": {
+      "types": "./dist/types/conversations/*/index.d.ts",
+      "import": "./dist/esm/conversations/*/index.js",
+      "require": "./dist/cjs/conversations/*/index.js",
+      "default": "./dist/esm/conversations/*/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "bun scripts/build.mjs",
     "prepublishOnly": "bun run build",
     "test": "bun test",
+    "test:unit": "bun test src/index.test.ts src/agents src/conversations src/providers src/persistence src/transport",
+    "test:e2e": "bun test src/e2e",
+    "benchmark": "bun scripts/benchmark.ts",
+    "benchmark:stream": "bun scripts/benchmark-conversation-stream.ts",
     "typecheck": "bunx tsc --noEmit"
   },
   "devDependencies": {
@@ -78,5 +102,8 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
   }
 }