@actuallab/rpc 12.2.23 → 12.3.2

package/dist/index.d.cts

@@ -734,29 +734,44 @@ interface RpcStreamRef {
     readonly allowReconnect: boolean;
     readonly isRealTime: boolean;
 }
+/** Configuration options for creating a local (origin-side) RpcStream. */
+interface RpcStreamOptions<T> {
+    ackPeriod?: number;
+    ackAdvance?: number;
+    allowReconnect?: boolean;
+    isRealTime?: boolean;
+    canSkipTo?: (item: T) => boolean;
+}
 /**
  * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
  * Returns null if the value is not a valid stream reference.
  */
 declare function parseStreamRef(value: unknown): RpcStreamRef | null;
 /**
- * Client-side RPC stream — consumes items sent by the server via system calls
- * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable<T> for for-await-of consumption.
+ * Dual-mode RPC stream — works as both local (origin-side) and remote (target-side).
  *
- * Wire protocol:
- * - Client sends Ack(0, hostId) to start the stream
- * - Server sends I (single item) / B (batch) messages
- * - Client acks every ackPeriod items for flow control
- * - Server sends End to signal completion (with optional error)
- * - Client sends AckEnd to acknowledge completion
+ * **Local mode**: wraps an AsyncIterable and carries streaming configuration
+ * (IsRealTime, CanSkipTo, etc.). Created by service methods and sent to the
+ * remote peer via RpcStreamSender.
+ *
+ * **Remote mode**: consumes items sent by the server via system calls
+ * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable for for-await-of consumption.
+ *
+ * This mirrors the .NET RpcStream<T> design where the same type serves both roles.
  */
 declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     readonly id: RpcObjectId;
-    readonly kind: 1;
+    readonly kind: RpcObjectKind;
     readonly allowReconnect: boolean;
-    readonly peer: RpcPeer;
+    readonly isRealTime: boolean;
+    readonly canSkipTo: (item: T) => boolean;
     readonly ackPeriod: number;
     readonly ackAdvance: number;
+    readonly localSource?: AsyncIterable<T>;
+    readonly peer: RpcPeer;
+    private _sender?;
+    private _toRefValue?;
+    private _whenSent?;
     private _buffer;
     private _nextExpectedIndex;
     private _consumerWaiting;
@@ -766,7 +781,27 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     private _started;
     private _iterating;
     private _ackSentUpTo;
+    /** Create a local (origin-side) stream wrapping an async iterable with optional configuration. */
+    constructor(source: AsyncIterable<T>, options?: RpcStreamOptions<T>);
+    /** Create a remote (target-side) stream from a parsed stream reference and peer. */
     constructor(ref: RpcStreamRef, peer: RpcPeer);
+    /**
+     * For local streams: resolves when the sender finishes pumping (after `toRef()` was called).
+     * Rejects if the source throws. Throws if `toRef()` hasn't been called yet.
+     */
+    get whenSent(): Promise<void>;
+    /**
+     * For local streams: bind to a peer, create and register an `RpcStreamSender`,
+     * start pumping items from the local source in the background, and return the
+     * stream reference.
+     *
+     * For binary peers the ref is a MessagePack-compatible object
+     * (`{ SerializedId, AckPeriod, AckAdvance, AllowReconnect }`);
+     * for text peers it is a comma-separated string.
+     *
+     * Can only be called once per stream.
+     */
+    toRef(peer: RpcPeer): unknown;
     /** Called by system call handler when a single item arrives ($sys.I). */
     onItem(index: number, item: T): void;
     /** Called by system call handler when a batch arrives ($sys.B). */
@@ -804,6 +839,7 @@ declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
  * - Client sends AckEnd to acknowledge completion
  */
 declare class RpcStreamSender<T> implements IRpcObject {
+    private static readonly _emptyGuid;
     readonly id: RpcObjectId;
     readonly kind: 0;
     readonly allowReconnect: boolean;
@@ -817,11 +853,12 @@ declare class RpcStreamSender<T> implements IRpcObject {
     private _started;
     private _lastAckedIndex;
     private _ackWaiting;
+    private _resetRequested;
     constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean);
     /** Returns the stream reference string for the $sys.Ok response. */
     toRef(): string;
     /** Called by system call handler when $sys.Ack is received from the client. */
-    onAck(nextIndex: number, _hostId: string): void;
+    onAck(nextIndex: number, hostId: string): void;
     /** Called by system call handler when $sys.AckEnd is received from the client. */
     onAckEnd(_hostId: string): void;
     /** Send a single item to the client. */
@@ -930,4 +967,4 @@ declare function xxh3_64str(input: string, seed?: bigint): bigint;
  */
 declare function computeMethodHash(methodName: string): number;
 
-export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };
+export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };

package/dist/index.d.ts

@@ -734,29 +734,44 @@ interface RpcStreamRef {
     readonly allowReconnect: boolean;
     readonly isRealTime: boolean;
 }
+/** Configuration options for creating a local (origin-side) RpcStream. */
+interface RpcStreamOptions<T> {
+    ackPeriod?: number;
+    ackAdvance?: number;
+    allowReconnect?: boolean;
+    isRealTime?: boolean;
+    canSkipTo?: (item: T) => boolean;
+}
 /**
  * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
  * Returns null if the value is not a valid stream reference.
  */
 declare function parseStreamRef(value: unknown): RpcStreamRef | null;
 /**
- * Client-side RPC stream — consumes items sent by the server via system calls
- * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable<T> for for-await-of consumption.
+ * Dual-mode RPC stream — works as both local (origin-side) and remote (target-side).
  *
- * Wire protocol:
- * - Client sends Ack(0, hostId) to start the stream
- * - Server sends I (single item) / B (batch) messages
- * - Client acks every ackPeriod items for flow control
- * - Server sends End to signal completion (with optional error)
- * - Client sends AckEnd to acknowledge completion
+ * **Local mode**: wraps an AsyncIterable and carries streaming configuration
+ * (IsRealTime, CanSkipTo, etc.). Created by service methods and sent to the
+ * remote peer via RpcStreamSender.
+ *
+ * **Remote mode**: consumes items sent by the server via system calls
+ * ($sys.I, $sys.B, $sys.End) and implements AsyncIterable for for-await-of consumption.
+ *
+ * This mirrors the .NET RpcStream<T> design where the same type serves both roles.
  */
 declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     readonly id: RpcObjectId;
-    readonly kind: 1;
+    readonly kind: RpcObjectKind;
     readonly allowReconnect: boolean;
-    readonly peer: RpcPeer;
+    readonly isRealTime: boolean;
+    readonly canSkipTo: (item: T) => boolean;
     readonly ackPeriod: number;
     readonly ackAdvance: number;
+    readonly localSource?: AsyncIterable<T>;
+    readonly peer: RpcPeer;
+    private _sender?;
+    private _toRefValue?;
+    private _whenSent?;
     private _buffer;
     private _nextExpectedIndex;
     private _consumerWaiting;
@@ -766,7 +781,27 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     private _started;
     private _iterating;
     private _ackSentUpTo;
+    /** Create a local (origin-side) stream wrapping an async iterable with optional configuration. */
+    constructor(source: AsyncIterable<T>, options?: RpcStreamOptions<T>);
+    /** Create a remote (target-side) stream from a parsed stream reference and peer. */
     constructor(ref: RpcStreamRef, peer: RpcPeer);
+    /**
+     * For local streams: resolves when the sender finishes pumping (after `toRef()` was called).
+     * Rejects if the source throws. Throws if `toRef()` hasn't been called yet.
+     */
+    get whenSent(): Promise<void>;
+    /**
+     * For local streams: bind to a peer, create and register an `RpcStreamSender`,
+     * start pumping items from the local source in the background, and return the
+     * stream reference.
+     *
+     * For binary peers the ref is a MessagePack-compatible object
+     * (`{ SerializedId, AckPeriod, AckAdvance, AllowReconnect }`);
+     * for text peers it is a comma-separated string.
+     *
+     * Can only be called once per stream.
+     */
+    toRef(peer: RpcPeer): unknown;
     /** Called by system call handler when a single item arrives ($sys.I). */
     onItem(index: number, item: T): void;
     /** Called by system call handler when a batch arrives ($sys.B). */
@@ -804,6 +839,7 @@ declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
  * - Client sends AckEnd to acknowledge completion
  */
 declare class RpcStreamSender<T> implements IRpcObject {
+    private static readonly _emptyGuid;
     readonly id: RpcObjectId;
     readonly kind: 0;
     readonly allowReconnect: boolean;
@@ -817,11 +853,12 @@ declare class RpcStreamSender<T> implements IRpcObject {
     private _started;
     private _lastAckedIndex;
     private _ackWaiting;
+    private _resetRequested;
     constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean);
     /** Returns the stream reference string for the $sys.Ok response. */
     toRef(): string;
     /** Called by system call handler when $sys.Ack is received from the client. */
-    onAck(nextIndex: number, _hostId: string): void;
+    onAck(nextIndex: number, hostId: string): void;
     /** Called by system call handler when $sys.AckEnd is received from the client. */
     onAckEnd(_hostId: string): void;
     /** Send a single item to the client. */
@@ -930,4 +967,4 @@ declare function xxh3_64str(input: string, seed?: bigint): bigint;
  */
 declare function computeMethodHash(methodName: string): number;
 
-export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };
+export { ARG_DELIMITER, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteObjectTracker, RpcSerializationFormat, RpcSerializationFormatResolver, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamOptions, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };