@qilin-agent/remote-mock 0.0.0-stage → 3.1.4

package/lib/types/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Endpoint-named mock for Typert Remote traffic: a table of unary answers and
+ * stream scripts keyed by `<namespace>/<method>`, scripted-stream control, a
+ * carrier log, and the Connection carrier face the `connection` plugin
+ * accepts through explicit installation or a page transport. Values are whatever the test
+ * registers; the only declaration is whether an endpoint is unary or a
+ * stream. Browser-safe: no DOM, React, or Node imports, no runtime import
+ * from another harness package.
+ * @module @qilin-agent/remote-mock
+ */
+export { RemoteMock, ok } from './remote-mock.ts';
+export type { OpenStreams, RemoteMockOptions, RemoteTable, StreamFilter, UnaryRuleFn } from './remote-mock.ts';
+export { frames, openStream, streamHandle, streamMethod } from './streams.ts';
+export type { StreamHandle, StreamScript } from './streams.ts';
+export { MockClientStream } from './streams.ts';
+export type { LoggedCall, LoggedMiss, LoggedStream, MockLog } from './log.ts';
+export type { MockedRemote } from './remote-proxy.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/log.d.ts

@@ -0,0 +1,96 @@
+/** What a `RemoteMock` saw: answered calls, opened streams, and requests without a rule. */
+/** One unary call, logged when its rule is selected and settled when the rule does. */
+export interface LoggedCall {
+    readonly endpoint: string;
+    /** Positional args as the caller passed them. */
+    readonly args: readonly unknown[];
+    /** `pending` until the rule settles, then `answered` or `failed`. */
+    readonly state: 'pending' | 'answered' | 'failed';
+    /** The answer once `answered`, the thrown error once `failed`. */
+    readonly result: unknown;
+    /** Global order across calls and stream opens. */
+    readonly seq: number;
+}
+/** One stream open and its current state. */
+export interface LoggedStream {
+    readonly endpoint: string;
+    /** Positional args the stream was opened with. */
+    readonly args: readonly unknown[];
+    readonly state: 'open' | 'ended' | 'failed' | 'cancelled';
+    /** Items delivered to the consumer so far. */
+    readonly pushed: number;
+    /** Global order across calls and stream opens. */
+    readonly seq: number;
+}
+/** One request that found no rule. */
+export interface LoggedMiss {
+    readonly endpoint: string;
+    readonly mode: 'unary' | 'stream';
+}
+/** Read side of the log. */
+export interface MockLog {
+    /**
+     * Unary calls, oldest first, with their live state.
+     * @param endpoint - restrict to one endpoint.
+     * @returns matching entries.
+     */
+    calls(endpoint?: string): readonly LoggedCall[];
+    /**
+     * Stream opens, oldest first, with their live state.
+     * @param endpoint - restrict to one endpoint.
+     * @returns matching entries.
+     */
+    streams(endpoint?: string): readonly LoggedStream[];
+    /**
+     * The first positional arg of every unary call and stream open, oldest first: the request object of the Gateway's
+     * one-parameter endpoints. Without `endpoint`, every endpoint the client asked the Host for, except the Gateway's
+     * own `$`-prefixed ones (`$events`).
+     * @param endpoint - restrict to one endpoint.
+     * @returns the requests.
+     */
+    requests(endpoint?: string): readonly unknown[];
+    /** Requests that found no rule, oldest first. */
+    unmatched(): readonly LoggedMiss[];
+}
+/** Mutable call entry the dispatcher settles. */
+export interface CallRecord extends LoggedCall {
+    state: LoggedCall['state'];
+    result: unknown;
+}
+/** Mutable stream entry shared with the live stream. */
+export interface StreamRecord extends LoggedStream {
+    state: LoggedStream['state'];
+    pushed: number;
+}
+/** The mock's log store. */
+export declare class MockLogStore implements MockLog {
+    private readonly callEntries;
+    private readonly streamEntries;
+    private readonly missEntries;
+    private seq;
+    calls(endpoint?: string): readonly LoggedCall[];
+    streams(endpoint?: string): readonly LoggedStream[];
+    requests(endpoint?: string): readonly unknown[];
+    unmatched(): readonly LoggedMiss[];
+    /**
+     * Record one call whose rule was selected.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the mutable entry the dispatcher settles.
+     */
+    call(endpoint: string, args: readonly unknown[]): CallRecord;
+    /**
+     * Record one stream open.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the mutable entry the stream updates.
+     */
+    stream(endpoint: string, args: readonly unknown[]): StreamRecord;
+    /**
+     * Record one request without a rule.
+     * @param endpoint - endpoint.
+     * @param mode - how it was requested.
+     */
+    miss(endpoint: string, mode: 'unary' | 'stream'): void;
+}
+//# sourceMappingURL=log.d.ts.map

package/lib/types/remote-mock.d.ts

@@ -0,0 +1,190 @@
+/** `RemoteMock`: an endpoint table (unary answers or stream scripts), live stream control, a log, and the Connection carrier face. */
+import type { ClientConnectionRpc } from '@qilin-agent/client-connection/client';
+import { type MockLog } from './log.ts';
+import { type StreamScript } from './streams.ts';
+import { type MockedRemote } from './remote-proxy.ts';
+/** A unary handler receives the caller's positional arguments, without its trailing `AbortSignal`. */
+export type UnaryRuleFn<Args extends readonly unknown[] = readonly unknown[], Result = unknown> = (...args: Args) => Result;
+/** Endpoint defaults: unary values or positional handlers, stream scripts, and stream declarations. */
+export interface RemoteTable {
+    readonly unary?: Readonly<Record<string, unknown>>;
+    readonly stream?: Readonly<Record<string, StreamScript>>;
+    /** Endpoints declared as streams without a script, so an open finds a stream miss rather than a unary one. */
+    readonly streams?: readonly string[];
+}
+/** Construction options. */
+export interface RemoteMockOptions {
+    /** Host facts the built-in `$events` ready frame carries; default `{ home: '/home/mock' }`. */
+    readonly host?: {
+        readonly home: string;
+    };
+}
+/** Filter over the args a stream was opened with. */
+export type StreamFilter = (args: readonly unknown[]) => boolean;
+/** Control and synchronization for streams opened by registered scripts; native overrides are excluded. */
+export interface OpenStreams {
+    /**
+     * Push one item into every open stream on `endpoint`, optionally filtered by its open args.
+     * @param endpoint - endpoint.
+     * @param item - item to deliver.
+     * @param where - filter over open args.
+     * @returns how many streams received it.
+     */
+    push(endpoint: string, item: unknown, where?: StreamFilter): number;
+    /**
+     * End every matching open stream.
+     * @param endpoint - endpoint.
+     * @param where - filter over open args.
+     * @returns how many streams ended.
+     */
+    end(endpoint: string, where?: StreamFilter): number;
+    /**
+     * Fail every matching open stream with `error`.
+     * @param endpoint - endpoint.
+     * @param error - error the consumer's read rejects with.
+     * @param where - filter over open args.
+     * @returns how many streams failed.
+     */
+    fail(endpoint: string, error: Error, where?: StreamFilter): number;
+    /**
+     * Resolve once registered scripts have opened `endpoint` at least `count` times in total.
+     * @param endpoint - endpoint.
+     * @param count - opens to wait for.
+     */
+    opened(endpoint: string, count: number): Promise<void>;
+    /**
+     * Resolve once the consumer of every matching stream has pulled everything pushed so far and, for a stream still
+     * open, waits for more; a settled stream counts once its queue is empty, and a stream nobody reads never drains.
+     * Pulled means taken from the queue: a consumer that processes items asynchronously after pulling them may still
+     * be working on the last one.
+     * @param endpoint - endpoint.
+     * @param where - filter over open args.
+     */
+    drained(endpoint: string, where?: StreamFilter): Promise<void>;
+}
+/**
+ * The success envelope the Client's Remote callers read: `{ ok: true, value }`.
+ * @param value - success value.
+ * @returns the envelope.
+ */
+export declare function ok<T>(value: T): {
+    readonly ok: true;
+    readonly value: T;
+};
+/**
+ * Endpoint-named Remote mock. `dispatch` / `open` are the core; `rpc` is the
+ * same core as the decoded carrier accepted by the Connection installer.
+ */
+export declare class RemoteMock {
+    /**
+     * Create a mock whose `$events` stream answers the Gateway client's opening
+     * with one ready frame and then stays open, so the assembled client connects.
+     * @param options - host facts for the ready frame.
+     * @returns the mock.
+     */
+    static create(options?: RemoteMockOptions): RemoteMock;
+    private readonly unaryDefaults;
+    private readonly scripts;
+    private live;
+    private openWaiters;
+    private readonly logStore;
+    private readonly unaryMocks;
+    private readonly streamMocks;
+    /** The carrier's uplink for the open in progress through {@link open}; a direct call has none. */
+    private carrierUplink;
+    private readonly proxy;
+    /**
+     * Native mock functions for every namespace: configure answers and inspect calls without declaring method names.
+     * Explicit stream registrations select stream mocks; all other methods use unary mocks.
+     * Native overrides belong to this instance; `mockReset()` restores the implementation reading current defaults.
+     * Generated declarations provide exact signatures; absent declarations weaken only this test-owned proxy.
+     */
+    readonly remote: MockedRemote;
+    /** Everything observed so far. */
+    readonly log: MockLog;
+    /** Control over streams opened by registered scripts. */
+    readonly streams: OpenStreams;
+    /**
+     * The Connection carrier face: `call` dispatches, `open` opens; payloads carry
+     * `{ args }` as the whole-client proxies (an array) or the Gateway's own
+     * endpoints (one object) send them, and a call aborted by its signal rejects.
+     */
+    readonly rpc: ClientConnectionRpc;
+    private constructor();
+    /**
+     * Set the endpoint's default positional-argument handler without changing its native mock overrides.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param rule - handler computing the answer.
+     * @returns this.
+     */
+    unary<Args extends readonly unknown[]>(endpoint: string, rule: UnaryRuleFn<Args>): this;
+    /**
+     * Set the endpoint's default answer, including explicit `undefined`, without changing its native mock overrides.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param rule - default answer.
+     * @returns this.
+     */
+    unary(endpoint: string, rule: unknown): this;
+    /**
+     * Declare `endpoint` as a stream and replace its default script when supplied. A declaration without a script
+     * preserves any existing script; an endpoint declared without one fails an open as a stream miss.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param script - script (`frames` / `openStream` build the common ones).
+     * @returns this.
+     */
+    stream(endpoint: string, script?: StreamScript): this;
+    /**
+     * Register endpoint defaults without changing native mock overrides.
+     * @param table - unary answers and stream scripts.
+     * @returns this.
+     */
+    load(table: RemoteTable): this;
+    /**
+     * Whether `endpoint` is declared a stream (with or without a script) or has a unary rule — the one declaration
+     * the whole-client proxies need; an endpoint neither declared nor ruled is dispatched as a unary call.
+     * @param endpoint - endpoint.
+     * @returns the mode, or undefined when nothing is registered.
+     */
+    modeOf(endpoint: string): 'unary' | 'stream' | undefined;
+    /**
+     * Registered endpoints and accessed proxy methods, sorted.
+     * @returns endpoint names.
+     */
+    endpoints(): readonly string[];
+    /**
+     * Answer one unary call with the registered rule's value, verbatim. The call
+     * is logged as soon as its rule is selected and settles with the rule: a
+     * rule that throws or rejects fails the call with that error.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the answer.
+     * @throws {Error} when no rule is registered (logged as unmatched).
+     */
+    dispatch(endpoint: string, args: readonly unknown[]): Promise<unknown>;
+    private unaryMock;
+    private unaryAnswer;
+    /**
+     * Open through the endpoint's native mock, which is called with the generated
+     * signature's arguments only; its default runs the registered script as a
+     * controlled stream. A native override returns its own iterable: the caller
+     * owns consumption and cancellation, outside `OpenStreams`.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @param signal - consumer cancellation.
+     * @param uplink - the carrier's uplink for this open, which the script reads as `StreamHandle.uplink`;
+     *   absent for a direct call, whose returned handle owns the uplink.
+     * @returns the controlled script stream or the native override's caller-owned iterable.
+     * @throws {Error} when the default runs without a registered script (logged as unmatched).
+     */
+    open(endpoint: string, args: readonly unknown[], signal: AbortSignal, uplink?: AsyncIterable<unknown>): AsyncIterable<unknown>;
+    private streamMock;
+    private openScript;
+    /** Throw when any request found no rule, naming the endpoints and the registered ones. */
+    assertNoUnmatched(): void;
+    private noRuleMessage;
+    /** Streams on `endpoint` still open or still holding items their consumer has not pulled; the rest are forgotten. */
+    private matching;
+    private forEachOpen;
+    private wakeOpened;
+}
+//# sourceMappingURL=remote-mock.d.ts.map

package/lib/types/remote-proxy.d.ts

@@ -0,0 +1,15 @@
+/** Lazy namespace access for native Remote mocks; production Remote declarations stay unchanged. */
+import type { MaybeMockedDeep } from '@vitest/spy';
+import type { TypertRemoteNamespaceMap } from '@qilin-agent/typert-protocol';
+/**
+ * Native mocks for every generated Remote namespace, or an unrestricted local proxy without generated types.
+ * @template Api - generated namespace map available in the caller's TypeScript program.
+ */
+export type MockedRemote<Api = TypertRemoteNamespaceMap> = keyof Api extends never ? any : MaybeMockedDeep<Api>;
+/**
+ * Cache accessed namespaces and expose the current native mock for each method.
+ * @param method - selects a stable endpoint mock for its configured invocation mode.
+ * @returns enumerable accessed namespaces and methods; symbols and thenable probes remain inert.
+ */
+export declare function createRemoteProxy(method: (endpoint: string) => unknown): Record<string, object>;
+//# sourceMappingURL=remote-proxy.d.ts.map

package/lib/types/streams.d.ts

@@ -0,0 +1,153 @@
+/** Stream scripts and the pushable, abort-aware stream a script drives. */
+import { type RemoteStreamHandle } from '@qilin-agent/typert-protocol';
+import type { StreamRecord } from './log.ts';
+/**
+ * Type a fake stream method's result as the handle a generated Client method
+ * returns. The uplink members are inert: a fake built on it drives the downlink only.
+ * @param source - downlink items the fake yields.
+ * @returns a handle that iterates `source`.
+ */
+export declare function streamHandle<Out, In = never>(source: AsyncIterable<Out>): RemoteStreamHandle<Out, In>;
+/** Downlink item type of one generated stream method. */
+type StreamItem<Method> = Method extends (...args: never[]) => RemoteStreamHandle<infer Out, unknown> ? Out : never;
+/**
+ * Lift a fake stream method written as an async generator function into the
+ * signature of the generated method it stands in for.
+ * @param method - fake taking the method's arguments and yielding its downlink items.
+ * @returns the fake returning {@link streamHandle} of each call.
+ */
+export declare function streamMethod<Method extends (...args: never[]) => RemoteStreamHandle<unknown, unknown>>(method: (...args: Parameters<Method>) => AsyncIterable<StreamItem<Method>>): Method;
+/** Test-side controls over one open stream. */
+export interface StreamHandle {
+    /** Queue one item for the consumer. */
+    push(item: unknown): void;
+    /** End the stream after the queued items drain. */
+    end(): void;
+    /** Fail the consumer's next read with `error` after the queued items drain. */
+    fail(error: Error): void;
+    /** Aborts when the opening signal aborts or the consumer returns early. */
+    readonly signal: AbortSignal;
+    /**
+     * Uplink items for the script: the carrier's iterable when the open came
+     * through `rpc.open`, otherwise what the returned handle's `send()` and
+     * `end()` feed.
+     */
+    readonly uplink: AsyncIterable<unknown>;
+}
+/**
+ * How a stream endpoint answers an open: receives the open args and the
+ * handle; the stream stays open after the script returns until `end()` or
+ * `fail()`. A script that throws or rejects fails the stream with that error.
+ */
+export type StreamScript = (args: readonly unknown[], stream: StreamHandle) => void | Promise<void>;
+/**
+ * Script yielding `items`, then ending.
+ * @param items - items in order.
+ * @returns the script.
+ */
+export declare function frames(items: readonly unknown[]): StreamScript;
+/**
+ * Script yielding `initial`, then staying open for `streams.push`.
+ * @param initial - items yielded on open.
+ * @returns the script.
+ */
+export declare function openStream(initial?: readonly unknown[]): StreamScript;
+/** One open stream: a queue the script pushes into and a single consumer reads from; the log entry tracks its state. */
+export declare class MockStream implements StreamHandle, AsyncIterable<unknown> {
+    readonly record: StreamRecord;
+    private readonly sourceSignal;
+    readonly uplink: AsyncIterable<unknown>;
+    private readonly release;
+    private readonly queue;
+    private settled;
+    private waiting;
+    private drainWaiters;
+    private readonly cancellation;
+    readonly signal: AbortSignal;
+    /** Consumer cancellation listener; attached while the stream is open, removed when it settles or cancels. */
+    private readonly onAbort;
+    /** Items pushed but not yet pulled by the consumer. */
+    get queued(): number;
+    /**
+     * @param record - log entry this stream updates.
+     * @param sourceSignal - cancellation from the caller that opened the stream.
+     * @param uplink - the uplink the script reads.
+     * @param release - closes the uplink this stream owns; called once, when the stream settles, is cancelled, or the consumer leaves.
+     */
+    constructor(record: StreamRecord, sourceSignal: AbortSignal, uplink: AsyncIterable<unknown>, release: () => void);
+    push(item: unknown): void;
+    end(): void;
+    fail(error: Error): void;
+    /** The consumer left: cancel the stream and drop what it left. */
+    dispose(): void;
+    /**
+     * Start `script` on this stream.
+     * @param script - the registered script.
+     * @param args - open args.
+     */
+    run(script: StreamScript, args: readonly unknown[]): void;
+    /**
+     * Resolve once the consumer has pulled every queued item and waits for the next one, or the stream is no longer
+     * open and holds nothing the consumer could still pull (a consumer that returns discards what it left).
+     * @returns settles when drained.
+     */
+    drained(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+    private next;
+    private pull;
+    private finish;
+    private settle;
+    private cancel;
+    private isDrained;
+    private wakeDrained;
+}
+/**
+ * The uplink a direct handle owns: `send()` pushes, `end()` half-closes, and
+ * `close()` ends it and drops unread items once the stream settles, is
+ * cancelled, or the consumer leaves. The script reads it as `StreamHandle.uplink`.
+ */
+export declare class HandleUplink implements AsyncIterable<unknown> {
+    private readonly items;
+    private done;
+    private waiter;
+    /**
+     * Queues one uplink item for the script, or completes the read waiting for it.
+     * @param item - the item the handle's `send()` carried.
+     * @throws {Error} after `end()`.
+     */
+    push(item: unknown): void;
+    /** Half-closes the uplink: pending and later reads complete as done; repeated calls are no-ops. */
+    end(): void;
+    /** Ends the uplink and drops unread items; the owning stream calls it on settle or cancel, the script's iterator on `return()`. */
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+}
+/**
+ * The handle a direct `mock.remote` stream call returns, as a generated method
+ * would: iterate it for the script's downlink, `send()` and `end()` feed
+ * `StreamHandle.uplink`, `dispose()` cancels the stream. `send()` applies the
+ * real handle's check, so a non-lossless JSON item throws and a top-level
+ * `undefined` passes. A stream opened through `rpc.open` reads the carrier's
+ * uplink instead, and this handle owns none.
+ */
+export declare class MockClientStream implements RemoteStreamHandle<unknown, unknown> {
+    private readonly stream;
+    private readonly uplink;
+    /**
+     * @param stream - the script-side stream.
+     * @param uplink - the uplink this handle feeds; absent when the carrier supplied one.
+     */
+    constructor(stream: MockStream, uplink: HandleUplink | undefined);
+    send(item: unknown): void;
+    end(): void;
+    dispose(): void;
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+}
+/**
+ * The `Error` a thrown value stands for: itself, or a new Error carrying its string form.
+ * @param reason - thrown value.
+ * @returns the error.
+ */
+export declare function toError(reason: unknown): Error;
+export {};
+//# sourceMappingURL=streams.d.ts.map

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@qilin-agent/remote-mock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Endpoint-named mock for Typert Remote traffic: unary answers and stream scripts per <namespace>/<method>, live stream control, a log, and the Connection carrier face whole-client specs install",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/test-support/remote-mock"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@vitest/spy": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@qilin-agent/typert-protocol": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@qilin-agent/typert-protocol": "3.1.4",
+    "@qilin-agent/api-settings-controller": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-connection": "3.1.4"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ]
 }