@astrale-os/kernel-client 0.6.0-beta.4 → 0.6.0-beta.41

package/dist/store/entity-index.js

@@ -92,4 +92,3 @@ export function edgeIdentity(key) {
 function signature(value) {
     return JSON.stringify(value);
 }
-//# sourceMappingURL=entity-index.js.map

package/dist/store/index.d.ts

@@ -1,2 +1 @@
 export { GraphStore, type StoreMutationOptions, type StoreOptions, type StoreQuery, type StoreQueryResponse, type StoreReadOptions, type StoreSnapshot, } from './store.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -1,2 +1 @@
 export { GraphStore, } from './store.js';
-//# sourceMappingURL=index.js.map

package/dist/store/memory.d.ts

@@ -1,4 +1,5 @@
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 import type { GraphApi } from '../graph/index.js';
 import type { StoreQueryResponse, StoreReadOptions, StoreSnapshot } from './store.js';
@@ -24,7 +25,7 @@ export declare class GraphMemory {
     private readonly pending;
     private active;
     constructor(options: GraphMemoryOptions);
-    ensure(key: string, ast: QueryAST, page: QueryPageRequest): QueryShape;
+    ensure(key: string, ast: QueryAST, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined): QueryShape;
     get(key: string): QueryShape | undefined;
     read(shape: QueryShape, options: StoreReadOptions): Promise<StoreQueryResponse>;
     snapshot(shape: QueryShape | undefined): StoreSnapshot;
@@ -46,4 +47,3 @@ export declare class GraphMemory {
     private drain;
     private report;
 }
-//# sourceMappingURL=memory.d.ts.map

package/dist/store/memory.js

@@ -1,5 +1,6 @@
 import { encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
 import { ClientError } from '../errors/index.js';
+import { retainDerivedQueryProvenance } from '../graph/provenance.js';
 import { edgeIdentity, EntityIndex } from './entity-index.js';
 import { OptimisticOverlay } from './optimistic.js';
 import { COLD_SNAPSHOT, QueryShape } from './shape.js';
@@ -13,7 +14,7 @@ export class GraphMemory {
     constructor(options) {
         this.options = options;
     }
-    ensure(key, ast, page) {
+    ensure(key, ast, page, expected) {
         const existing = this.shapes.get(key);
         const now = this.options.now();
         if (existing !== undefined) {
@@ -26,7 +27,7 @@ export class GraphMemory {
         if (this.shapes.size >= this.options.maximumShapes) {
             throw new ClientError('GraphStore shape capacity is exhausted by observed or in-flight queries.');
         }
-        const shape = new QueryShape(key, ast, page, now);
+        const shape = new QueryShape(key, ast, page, expected, now);
         shape.releasedAt = now;
         this.shapes.set(key, shape);
         return shape;
@@ -52,7 +53,7 @@ export class GraphMemory {
         const prior = shape.response;
         this.publish(shape, prior === undefined ? 'loading' : this.overlay.hasAny() ? 'optimistic' : 'refreshing');
         const inflight = this.schedule(async () => {
-            const result = await this.options.graph.query(shape.ast, queryOptions(shape.page, this.options.lifecycle));
+            const result = await this.options.graph.query(shape.ast, queryOptions(shape.page, this.options.lifecycle, shape.expected));
             this.options.requireOpen();
             const integration = this.entities.integrate(result.result);
             shape.references = integration.references;
@@ -182,10 +183,11 @@ export class GraphMemory {
             this.pending.shift()?.reject(error);
     }
     materialize(template, references) {
-        return Object.freeze({
+        const response = Object.freeze({
             result: this.materializeResult(template.result, references),
             page: template.page,
         });
+        return retainDerivedQueryProvenance(template, response);
     }
     materializeResult(template, references) {
         if (template.kind === 'nodes') {
@@ -196,8 +198,9 @@ export class GraphMemory {
                     continue;
                 }
                 const node = this.overlay.node(projection.value.id, this.entities);
-                if (node !== undefined)
-                    nodes.push(Object.freeze({ kind: 'value', value: node }));
+                if (node !== undefined) {
+                    nodes.push(Object.freeze({ kind: 'value', value: materializeNode(node) }));
+                }
             }
             return Object.freeze({
                 kind: 'nodes',
@@ -213,7 +216,7 @@ export class GraphMemory {
                         const value = this.entities.edge(edgeIdentity(item.edge.value));
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeEdge(value) });
                     })();
                 const source = item.source.kind === 'reference'
                     ? item.source
@@ -221,7 +224,7 @@ export class GraphMemory {
                         const value = this.overlay.node(item.source.value.id, this.entities);
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeNode(value) });
                     })();
                 const target = item.target.kind === 'reference'
                     ? item.target
@@ -229,7 +232,7 @@ export class GraphMemory {
                         const value = this.overlay.node(item.target.value.id, this.entities);
                         return value === undefined
                             ? undefined
-                            : Object.freeze({ kind: 'value', value });
+                            : Object.freeze({ kind: 'value', value: materializeNode(value) });
                     })();
                 if (edge !== undefined && source !== undefined && target !== undefined) {
                     edges.push(Object.freeze({ edge, source, target }));
@@ -242,11 +245,13 @@ export class GraphMemory {
         }
         const nodes = references.nodes
             .map((id) => this.overlay.node(id, this.entities))
-            .filter((node) => node !== undefined);
+            .filter((node) => node !== undefined)
+            .map(materializeNode);
         const visibleNodeIds = new Set(nodes.map(({ id }) => id));
         const edges = references.edges
             .map((key) => this.entities.edge(key))
-            .filter((edge) => edge !== undefined && visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target));
+            .filter((edge) => edge !== undefined && visibleNodeIds.has(edge.source) && visibleNodeIds.has(edge.target))
+            .map(materializeEdge);
         const graph = Object.freeze({ nodes: Object.freeze(nodes), edges: Object.freeze(edges) });
         const selection = materializeSelection(template.selection, visibleNodeIds, edges);
         return selection.kind === 'node'
@@ -297,6 +302,12 @@ export class GraphMemory {
         }
     }
 }
+function materializeNode(value) {
+    return Object.freeze({ ...value });
+}
+function materializeEdge(value) {
+    return Object.freeze({ ...value });
+}
 function materializeSelection(selection, visibleNodes, visibleEdges) {
     if (selection.kind === 'node') {
         return Object.freeze({
@@ -310,10 +321,11 @@ function materializeSelection(selection, visibleNodes, visibleEdges) {
         keys: Object.freeze(selection.keys.filter((key) => edges.has(encodeEdgeKey(key)))),
     });
 }
-function queryOptions(page, lifecycle) {
+function queryOptions(page, lifecycle, expected) {
     return Object.freeze({
         signal: lifecycle,
         page,
+        ...(expected === undefined ? {} : { expected }),
     });
 }
 function observeRead(pending, options, lifecycle) {
@@ -394,4 +406,3 @@ function sameSnapshot(left, right) {
     }
     return left.state !== 'failed' || right.state !== 'failed' || left.error === right.error;
 }
-//# sourceMappingURL=memory.js.map

package/dist/store/mutation.d.ts

@@ -3,4 +3,3 @@ import type { GraphApi, MutationAuthor } from '../graph/index.js';
 import type { GraphMemory } from './memory.js';
 import type { StoreMutationOptions } from './store.js';
 export declare function mutateStore(graph: GraphApi, memory: GraphMemory, input: MutationAuthor | MutationASTValue | MutationInput, options?: StoreMutationOptions): Promise<MutationResult>;
-//# sourceMappingURL=mutation.d.ts.map

package/dist/store/mutation.js

@@ -32,4 +32,3 @@ export async function mutateStore(graph, memory, input, options = {}) {
         throw error;
     }
 }
-//# sourceMappingURL=mutation.js.map

package/dist/store/observe.d.ts

@@ -1,4 +1,3 @@
 import type { StoreQuery, StoreReadOptions, StoreSnapshot } from './store.js';
 import type { GraphStore } from './store.js';
 export declare function observeStore<Query extends StoreQuery>(store: GraphStore, query: Query, listener: (snapshot: StoreSnapshot<Query>) => void, options: StoreReadOptions): () => void;
-//# sourceMappingURL=observe.d.ts.map

package/dist/store/observe.js

@@ -15,4 +15,3 @@ export function observeStore(store, query, listener, options) {
     void store.read(admitted, options).catch(() => undefined);
     return unsubscribe;
 }
-//# sourceMappingURL=observe.js.map

package/dist/store/optimistic.d.ts

@@ -10,4 +10,3 @@ export declare class OptimisticOverlay {
     node(id: NodeId, entities: EntityIndex): Node | undefined;
     clear(): void;
 }
-//# sourceMappingURL=optimistic.d.ts.map

package/dist/store/optimistic.js

@@ -41,4 +41,3 @@ function nodeId(input) {
         ? path.ast.anchor.id
         : undefined;
 }
-//# sourceMappingURL=optimistic.js.map

package/dist/store/query-key.d.ts

@@ -1,6 +1,6 @@
 import type { QueryAST as QueryASTValue } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 export declare function admitQuery(input: QueryASTValue): QueryASTValue;
 export declare function admitPage(input: QueryPageRequest): QueryPageRequest;
-export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest): string;
-//# sourceMappingURL=query-key.d.ts.map
+export declare function queryKey(ast: QueryASTValue, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined): string;

package/dist/store/query-key.js

@@ -17,7 +17,11 @@ export function admitPage(input) {
         ...(input.after === undefined ? {} : { after: input.after }),
     });
 }
-export function queryKey(ast, page) {
-    return JSON.stringify([QueryAST.fingerprint(ast), page.size, page.after ?? null]);
+export function queryKey(ast, page, expected) {
+    return JSON.stringify([
+        QueryAST.fingerprint(ast),
+        page.size,
+        page.after ?? null,
+        expected ?? null,
+    ]);
 }
-//# sourceMappingURL=query-key.js.map

package/dist/store/shape.d.ts

@@ -1,5 +1,6 @@
 import type { NodeId } from '@astrale-os/kernel-core/graph/node';
 import type { QueryAST } from '@astrale-os/kernel-core/graph/query';
+import type { DomainDependency } from '@astrale-os/kernel-dsl/v1/schema';
 import type { QueryPageRequest } from '../graph/index.js';
 import type { FactReferences } from './entity-index.js';
 import type { StoreQueryResponse, StoreSnapshot } from './store.js';
@@ -8,6 +9,7 @@ export declare class QueryShape {
     readonly key: string;
     readonly ast: QueryAST;
     readonly page: QueryPageRequest;
+    readonly expected: readonly DomainDependency[] | undefined;
     readonly listeners: Set<() => void>;
     state: ShapeState;
     confirmed?: StoreQueryResponse;
@@ -18,9 +20,8 @@ export declare class QueryShape {
     accessedAt: number;
     refreshedAt?: number;
     snapshot: StoreSnapshot;
-    constructor(key: string, ast: QueryAST, page: QueryPageRequest, now: number);
+    constructor(key: string, ast: QueryAST, page: QueryPageRequest, expected: readonly DomainDependency[] | undefined, now: number);
     get observed(): boolean;
     referencesAny(nodes: ReadonlySet<NodeId>, edges: ReadonlySet<string>): boolean;
 }
 export declare const COLD_SNAPSHOT: StoreSnapshot;
-//# sourceMappingURL=shape.d.ts.map

package/dist/store/shape.js

@@ -2,6 +2,7 @@ export class QueryShape {
     key;
     ast;
     page;
+    expected;
     listeners = new Set();
     state = 'cold';
     confirmed;
@@ -12,10 +13,11 @@ export class QueryShape {
     accessedAt;
     refreshedAt;
     snapshot = COLD_SNAPSHOT;
-    constructor(key, ast, page, now) {
+    constructor(key, ast, page, expected, now) {
         this.key = key;
         this.ast = ast;
         this.page = page;
+        this.expected = expected;
         this.accessedAt = now;
     }
     get observed() {
@@ -27,4 +29,3 @@ export class QueryShape {
     }
 }
 export const COLD_SNAPSHOT = Object.freeze({ state: 'cold' });
-//# sourceMappingURL=shape.js.map

package/dist/store/store.d.ts

@@ -1,14 +1,13 @@
 import type { MutationAST, MutationInput, MutationResult } from '@astrale-os/kernel-core/graph/mutate';
 import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
 import type { QueryResponse } from '../graph/index.js';
-import type { GraphApi, GraphQueryOptions, MutationAuthor } from '../graph/index.js';
-import type { RequestOptions } from '../transport/index.js';
+import type { GraphApi, GraphMutationOptions, GraphQueryOptions, MutationAuthor } from '../graph/index.js';
 export type StoreQuery = QueryAST;
 export type StoreQueryResponse<Query extends StoreQuery = StoreQuery> = QueryResponse<QueryResultFor<Query>>;
 export interface StoreReadOptions extends GraphQueryOptions {
     readonly freshness?: 'cached' | 'refresh';
 }
-export interface StoreMutationOptions extends RequestOptions {
+export interface StoreMutationOptions extends GraphMutationOptions {
     readonly optimistic?: boolean;
 }
 export type StoreSnapshot<Query extends StoreQuery = StoreQuery> = {
@@ -66,4 +65,3 @@ export declare class GraphStore {
     private identity;
     private requireOpen;
 }
-//# sourceMappingURL=store.d.ts.map

package/dist/store/store.js

@@ -1,4 +1,5 @@
 import { ClientError } from '../errors/index.js';
+import { captureExpected } from '../graph/expectation.js';
 import { GraphMemory } from './memory.js';
 import { mutateStore } from './mutation.js';
 import { observeStore } from './observe.js';
@@ -105,7 +106,7 @@ export class GraphStore {
         const identity = this.identity(query, options);
         return {
             ...identity,
-            shape: this.memory.ensure(identity.key, identity.ast, identity.page),
+            shape: this.memory.ensure(identity.key, identity.ast, identity.page, identity.expected),
             options: options,
         };
     }
@@ -121,6 +122,7 @@ export class GraphStore {
             throw new TypeError('Store freshness option is invalid.');
         }
         const page = admitPage(options.page);
+        const expected = captureExpected(options.expected);
         if (options.timeoutMs !== undefined &&
             (!Number.isSafeInteger(options.timeoutMs) ||
                 options.timeoutMs < 1 ||
@@ -128,8 +130,8 @@ export class GraphStore {
             throw new TypeError('Store read timeoutMs must be a positive platform integer.');
         }
         const ast = admitQuery(query);
-        const key = queryKey(ast, page);
-        return { key, ast, page };
+        const key = queryKey(ast, page, expected);
+        return { key, ast, page, expected };
     }
     requireOpen() {
         if (this.closed)
@@ -142,4 +144,3 @@ function positive(input, label) {
     }
     return input;
 }
-//# sourceMappingURL=store.js.map

package/dist/store/store.typecheck.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=store.typecheck.d.ts.map

package/dist/store/store.typecheck.js

@@ -1,11 +1,11 @@
 import { Query } from '../graph/index.js';
 const options = { page: { size: 32 } };
-const nodeGraph = Query.from({ kind: 'node', paths: [path] }).select({ kind: 'graph' });
-const nodeProjection = Query.from({ kind: 'node', paths: [path] }).select({
+const nodeGraph = Query.from({ nodes: [path] }).select({ kind: 'graph' });
+const nodeProjection = Query.from({ nodes: [path] }).select({
     kind: 'nodes',
     projection: { kind: 'reference' },
 });
-const edgeSource = Query.from({ kind: 'edge', definitions: [edge] });
+const edgeSource = Query.from({ edges: [edge] });
 const edgeProjection = edgeSource.select({
     kind: 'edges',
     projection: { edge: 'reference', source: 'value', target: 'reference' },
@@ -13,9 +13,6 @@ const edgeProjection = edgeSource.select({
 const read = store.read(nodeGraph, options);
 const peek = store.peek(nodeProjection, options);
 const snapshot = store.getSnapshot(edgeProjection, options);
-// @ts-expect-error ready is the successful local snapshot state; fresh is retired.
-const retiredFreshSnapshot = { state: 'fresh' };
-void retiredFreshSnapshot;
 store.subscribe(nodeGraph, () => undefined, options);
 store.observe(nodeProjection, (value) => {
     if ('response' in value && value.response !== undefined) {
@@ -35,7 +32,4 @@ store.subscribe(nodeGraph, () => undefined);
 store.getSnapshot(nodeGraph);
 // @ts-expect-error Query-page identity is required for observations.
 store.observe(nodeGraph, () => undefined);
-// @ts-expect-error watch is reserved for a future remote-liveness protocol.
-store.watch(nodeGraph, () => undefined, options);
 void {};
-//# sourceMappingURL=store.typecheck.js.map

package/dist/transport/auto/decision.d.ts

@@ -20,4 +20,3 @@ export declare class AutoDecision {
     release(): void;
     close(): void;
 }
-//# sourceMappingURL=decision.d.ts.map

package/dist/transport/auto/decision.js

@@ -46,4 +46,3 @@ export class AutoDecision {
         this.pending = undefined;
     }
 }
-//# sourceMappingURL=decision.js.map

package/dist/transport/auto/fallback.d.ts

@@ -14,4 +14,3 @@ export declare class InvocationBudget {
 }
 export declare function mayFallback(error: unknown): error is TransportError;
 export declare function warningTarget(input: TransportRequest): TransportRequest['call']['target'];
-//# sourceMappingURL=fallback.d.ts.map

package/dist/transport/auto/fallback.js

@@ -1,4 +1,5 @@
 import { TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { positiveInteger } from '../index.js';
 const MAXIMUM_TIMEOUT_MS = 2_147_483_647;
 /** One invocation-owned total timeout budget shared by selection and fallback. */
@@ -33,10 +34,7 @@ export class InvocationBudget {
         let timer;
         let abort;
         const interrupted = new Promise((_resolve, reject) => {
-            timer = setTimeout(() => reject(new TransportError('Automatic transport decision exceeded its timeout.', {
-                phase: 'timeout',
-                delivery: 'not-sent',
-            })), remaining);
+            timer = setTimeout(() => reject(invocationFailure('Automatic transport decision exceeded its timeout.', 'timeout')), remaining);
             if (this.input?.signal) {
                 abort = () => reject(abortReason(this.input.signal));
                 this.input.signal.addEventListener('abort', abort, { once: true });
@@ -55,16 +53,17 @@ export class InvocationBudget {
     remaining() {
         const remaining = Math.min(MAXIMUM_TIMEOUT_MS, this.timeoutMs - (Date.now() - this.started));
         if (remaining < 1) {
-            throw new TransportError('Automatic transport invocation exceeded its timeout.', {
-                phase: 'timeout',
-                delivery: 'not-sent',
-            });
+            throw invocationFailure('Automatic transport invocation exceeded its timeout.', 'timeout');
         }
         return remaining;
     }
 }
 export function mayFallback(error) {
-    return error instanceof TransportError && error.phase !== 'closed' && error.phase !== 'timeout';
+    return (error instanceof TransportError &&
+        error.context.kind === 'invocation' &&
+        error.context.delivery === 'not-sent' &&
+        error.phase !== 'closed' &&
+        error.phase !== 'timeout');
 }
 export function warningTarget(input) {
     return input.call.target;
@@ -74,4 +73,3 @@ function abortReason(signal) {
         ? signal.reason
         : new Error(signal.reason === undefined ? 'request was cancelled' : String(signal.reason));
 }
-//# sourceMappingURL=fallback.js.map

package/dist/transport/auto/index.d.ts

@@ -1,3 +1,2 @@
 export { AutoTransport, type AutoTransportOptions } from './transport.js';
 export { formatClientWarning, type ClientWarning } from './warning.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/transport/auto/index.js

@@ -1,3 +1,2 @@
 export { AutoTransport } from './transport.js';
 export { formatClientWarning } from './warning.js';
-//# sourceMappingURL=index.js.map

package/dist/transport/auto/transport.d.ts

@@ -35,4 +35,3 @@ export declare class AutoTransport implements Transport {
     private tryWebsocket;
     private requireOpen;
 }
-//# sourceMappingURL=transport.d.ts.map

package/dist/transport/auto/transport.js

@@ -1,4 +1,5 @@
 import { TransportError } from '../../errors/index.js';
+import { invocationFailure } from '../failure.js';
 import { HttpTransport } from '../http/index.js';
 import { positiveInteger } from '../index.js';
 import { WebSocketTransport } from '../websocket/index.js';
@@ -104,7 +105,9 @@ export class AutoTransport {
                     this.decision.release();
                 throw error;
             }
-            if (error instanceof TransportError && error.delivery === 'unknown') {
+            if (error instanceof TransportError &&
+                error.context.kind === 'invocation' &&
+                error.context.delivery === 'unknown') {
                 this.decision.demote();
                 throw error;
             }
@@ -132,10 +135,6 @@ export class AutoTransport {
     requireOpen() {
         if (!this.closed)
             return;
-        throw new TransportError('AutoTransport is closed.', {
-            phase: 'closed',
-            delivery: 'not-sent',
-        });
+        throw invocationFailure('AutoTransport is closed.', 'closed');
     }
 }
-//# sourceMappingURL=transport.js.map

package/dist/transport/auto/warning.d.ts

@@ -11,4 +11,3 @@ export interface ClientWarning {
 }
 export declare function formatClientWarning(warning: ClientWarning): string;
 export declare function emitWarning(warning: ClientWarning, observer: ((warning: ClientWarning) => void) | undefined): void;
-//# sourceMappingURL=warning.d.ts.map

package/dist/transport/auto/warning.js

@@ -9,11 +9,13 @@ export function emitWarning(warning, observer) {
     try {
         if (observer)
             observer(warning);
-        else
-            globalThis.console?.warn(formatClientWarning(warning));
+        else {
+            const runtimeConsole = globalThis
+                .console;
+            runtimeConsole?.warn(formatClientWarning(warning));
+        }
     }
     catch {
         // Warning observation cannot change invocation settlement.
     }
 }
-//# sourceMappingURL=warning.js.map

package/dist/transport/deadline.d.ts

@@ -9,4 +9,3 @@ export declare function controlledSignal(parent: AbortSignal | undefined, timeou
 export declare function positiveInteger(input: number, label: string): number;
 export declare function requireLive(control: ControlledSignal): void;
 export declare function asError(value: unknown): Error;
-//# sourceMappingURL=deadline.d.ts.map

package/dist/transport/deadline.js

@@ -37,4 +37,3 @@ export function requireLive(control) {
 export function asError(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
-//# sourceMappingURL=deadline.js.map

package/dist/transport/failure.d.ts

@@ -0,0 +1,7 @@
+import { TransportError, type InvocationTransportErrorOptions } from '../errors/index.js';
+type InvocationFailureEvidence = Omit<InvocationTransportErrorOptions, 'delivery' | 'phase'> & {
+    readonly delivery?: InvocationTransportErrorOptions['delivery'];
+};
+/** Create invocation transport evidence with the common not-sent default. */
+export declare function invocationFailure(message: string, phase: InvocationTransportErrorOptions['phase'], evidence?: InvocationFailureEvidence): TransportError;
+export {};

package/dist/transport/failure.js

@@ -0,0 +1,9 @@
+import { TransportError } from '../errors/index.js';
+/** Create invocation transport evidence with the common not-sent default. */
+export function invocationFailure(message, phase, evidence = {}) {
+    return TransportError.invocation(message, {
+        ...evidence,
+        phase,
+        delivery: evidence.delivery ?? 'not-sent',
+    });
+}

package/dist/transport/http/byte-stream.d.ts

@@ -0,0 +1,17 @@
+import type { ControlledSignal } from '../index.js';
+/** Single-consumer HTTP byte stream preserving invocation lifetime and backpressure. */
+export declare class HttpByteStream implements AsyncIterable<Uint8Array> {
+    private readonly maximumBytes;
+    private readonly control;
+    private readonly reader;
+    private claimed;
+    private terminal;
+    private bytes;
+    private interruption;
+    constructor(body: ReadableStream<Uint8Array>, maximumBytes: number, control: ControlledSignal);
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+    cancel(reason?: unknown): Promise<void>;
+    private next;
+    private interrupt;
+    private cancelReader;
+}

package/dist/transport/http/byte-stream.js

@@ -0,0 +1,86 @@
+import { ProtocolError } from '../../errors/index.js';
+import { asError } from '../index.js';
+/** Single-consumer HTTP byte stream preserving invocation lifetime and backpressure. */
+export class HttpByteStream {
+    maximumBytes;
+    control;
+    reader;
+    claimed = false;
+    terminal = false;
+    bytes = 0;
+    interruption;
+    constructor(body, maximumBytes, control) {
+        this.maximumBytes = maximumBytes;
+        this.control = control;
+        this.reader = body.getReader();
+        const abort = () => void this.interrupt(control.signal.reason);
+        if (control.signal.aborted)
+            abort();
+        else
+            control.signal.addEventListener('abort', abort, { once: true });
+    }
+    [Symbol.asyncIterator]() {
+        if (this.claimed)
+            throw new TypeError('streaming binary admits exactly one consumer.');
+        this.claimed = true;
+        return {
+            next: () => this.next(),
+            return: async () => {
+                await this.cancel('streaming binary consumer stopped');
+                return { done: true, value: undefined };
+            },
+            throw: async (error) => {
+                await this.cancel('streaming binary consumer failed');
+                throw error;
+            },
+        };
+    }
+    async cancel(reason = 'streaming binary cancelled') {
+        if (this.terminal)
+            return;
+        this.terminal = true;
+        this.control.cancel(reason);
+        await this.cancelReader(reason);
+        this.control.close();
+    }
+    async next() {
+        if (this.interruption !== undefined)
+            throw this.interruption;
+        if (this.terminal)
+            return { done: true, value: undefined };
+        try {
+            const next = await this.reader.read();
+            if (this.interruption !== undefined)
+                throw this.interruption;
+            if (next.done) {
+                this.terminal = true;
+                this.control.close();
+                return { done: true, value: undefined };
+            }
+            this.bytes += next.value.byteLength;
+            if (this.bytes > this.maximumBytes) {
+                throw new ProtocolError(`streaming binary exceeds maximumResponseBytes (${this.maximumBytes}).`);
+            }
+            return { done: false, value: new Uint8Array(next.value) };
+        }
+        catch (error) {
+            await this.cancel(error);
+            throw error;
+        }
+    }
+    async interrupt(reason) {
+        if (this.terminal || this.interruption !== undefined)
+            return;
+        this.interruption = asError(reason ?? new Error('streaming binary was cancelled.'));
+        await this.cancelReader(this.interruption);
+        this.control.close();
+    }
+    async cancelReader(reason) {
+        try {
+            await this.reader.cancel(reason);
+        }
+        catch {
+            // Cancellation follows an already chosen terminal outcome.
+        }
+    }
+}