@rxferrix/client 0.0.0-stage → 0.2.0

package/dist/remote_query_set.js

@@ -0,0 +1,87 @@
+import { applyDiff, DiffMismatch } from "./diff.js";
+import { RxFerrixError } from "./errors.js";
+import { formatVersion, versionsEqual, } from "./protocol.js";
+export class TransitionVersionMismatch extends Error {
+    constructor(expected, got) {
+        super(`Transition startVersion ${formatVersion(got)} does not match client version ${formatVersion(expected)}`);
+    }
+}
+/**
+ * The server's view of the world for the current socket: the StateVersion and the latest result for every query.
+ * Transitions are validated (`startVersion` must equal the current version) and then applied atomically.
+ */
+export class RemoteQuerySet {
+    _version = { querySet: 0, identity: 0, ts: 0 };
+    results = new Map();
+    get version() {
+        return this._version;
+    }
+    result(queryId) {
+        return this.results.get(queryId);
+    }
+    /**
+     * Applies a transition. Modifications for queries that `isKnown` rejects (removed locally while the transition was
+     * in flight) are ignored. Throws {@link TransitionVersionMismatch} without changing anything when the transition
+     * does not start at the current version, and {@link DiffMismatch} when a result diff doesn't fit the result held.
+     */
+    transition(message, isKnown) {
+        if (!versionsEqual(message.startVersion, this._version)) {
+            throw new TransitionVersionMismatch(this._version, message.startVersion);
+        }
+        // Diffs are applied first, against the results as they were: if one doesn't fit, nothing changes.
+        const diffed = new Map();
+        for (const modification of message.modifications ?? []) {
+            if (modification.type !== "QueryUpdated" || !("diff" in modification) || !isKnown(modification.queryId))
+                continue;
+            const current = this.results.get(modification.queryId);
+            if (current?.status !== "success") {
+                throw new DiffMismatch(`query ${modification.queryId} has no result to apply a diff to`);
+            }
+            diffed.set(modification, applyDiff(current.value, modification.diff));
+        }
+        const changed = [];
+        const logLines = [];
+        for (const modification of message.modifications ?? []) {
+            const queryId = modification.queryId;
+            if (!isKnown(queryId))
+                continue;
+            switch (modification.type) {
+                case "QueryUpdated":
+                    this.results.set(queryId, {
+                        status: "success",
+                        value: "diff" in modification ? diffed.get(modification) : modification.value,
+                    });
+                    break;
+                case "QueryFailed":
+                    this.results.set(queryId, {
+                        status: "error",
+                        error: RxFerrixError.fromServer(modification.errorMessage, modification.errorData),
+                    });
+                    break;
+                case "QueryRemoved":
+                    this.results.delete(queryId);
+                    break;
+                default:
+                    continue;
+            }
+            changed.push(queryId);
+            if ("logLines" in modification && modification.logLines && modification.logLines.length > 0) {
+                logLines.push({ queryId, lines: modification.logLines });
+            }
+        }
+        this._version = { ...message.endVersion };
+        return { changed, logLines };
+    }
+    /** Forgets a query's result (it was removed from the local query set). */
+    remove(queryId) {
+        this.results.delete(queryId);
+    }
+    /**
+     * A new socket starts from a fresh server state (all versions 0). Results are kept so the UI keeps showing the
+     * last known data until the re-subscribed queries report again.
+     */
+    resetVersion() {
+        this._version = { querySet: 0, identity: 0, ts: 0 };
+    }
+}
+//# sourceMappingURL=remote_query_set.js.map

package/dist/remote_query_set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote_query_set.js","sourceRoot":"","sources":["../src/remote_query_set.ts"],"names":[],"mappings":"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"}

package/dist/request_manager.d.ts

@@ -0,0 +1,57 @@
+import { RxFerrixError } from "./errors.js";
+import type { ActionMessage, ActionResponseMessage, MutationMessage, MutationResponseMessage, RequestId } from "./protocol.js";
+export interface SettledMutation {
+    requestId: RequestId;
+    settle: () => void;
+}
+/**
+ * Tracks in-flight mutations and actions.
+ *
+ * A mutation's promise resolves only once BOTH its successful `MutationResponse { ts: M }` has arrived AND the client
+ * has applied a Transition with `endVersion.ts >= M` (read-your-writes). Failures reject immediately.
+ *
+ * Settling is split in two (`settle` callbacks are returned rather than invoked) so the client can update its query
+ * view (dropping optimistic updates) before promise continuations run.
+ */
+export declare class RequestManager {
+    private nextRequestId;
+    private readonly requests;
+    allocateRequestId(): RequestId;
+    trackMutation(message: MutationMessage): Promise<unknown>;
+    trackAction(message: ActionMessage): Promise<unknown>;
+    /** Messages that still have to go out on the current socket, in request order. */
+    unsent(): (MutationMessage | ActionMessage)[];
+    /** The message went out on the current socket. */
+    markSent(requestId: RequestId): void;
+    /**
+     * Handles a MutationResponse. `observedTs` is the ts of the last applied Transition, or null when the client's view
+     * is not currently consistent with the server (right after a reconnect).
+     *
+     * Returns the settled mutation (whose optimistic update must be dropped), or null if it is still waiting for its
+     * ts to be observed (or the requestId is unknown).
+     */
+    onMutationResponse(response: MutationResponseMessage, observedTs: number | null): SettledMutation | null;
+    /** Handles an ActionResponse. Returns the settle callback, or null for an unknown request. */
+    onActionResponse(response: ActionResponseMessage): (() => void) | null;
+    /** A Transition with `endVersion.ts = ts` was applied: completes every mutation with a commit ts <= ts. */
+    removeCompleted(ts: number): SettledMutation[];
+    /**
+     * The socket dropped. Mutations without a response will be re-sent on the next socket. Actions that were already
+     * sent are rejected because they are not idempotent; actions that never left the client stay queued.
+     */
+    onSocketClosed(): {
+        settle: () => void;
+        requestId: RequestId;
+    }[];
+    /** Rejects everything (client closed). */
+    rejectAll(error: RxFerrixError): void;
+    hasInflight(): boolean;
+    hasInflightMutations(): boolean;
+    counts(): {
+        mutations: number;
+        actions: number;
+        oldestStartedAt: number | null;
+    };
+    udfPathOf(requestId: RequestId): string | undefined;
+}
+//# sourceMappingURL=request_manager.d.ts.map

package/dist/request_manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request_manager.d.ts","sourceRoot":"","sources":["../src/request_manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,uBAAuB,EACvB,SAAS,EACV,MAAM,eAAe,CAAC;AAuBvB,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAE1D,iBAAiB,IAAI,SAAS;IAI9B,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAczD,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAarD,kFAAkF;IAClF,MAAM,IAAI,CAAC,eAAe,GAAG,aAAa,CAAC,EAAE;IAU7C,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAKpC;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,GAAG,IAAI;IAiBxG,8FAA8F;IAC9F,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI;IAYtE,2GAA2G;IAC3G,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,EAAE;IAW9C;;;OAGG;IACH,cAAc,IAAI;QAAE,MAAM,EAAE,MAAM,IAAI,CAAC;QAAC,SAAS,EAAE,SAAS,CAAA;KAAE,EAAE;IAkBhE,0CAA0C;IAC1C,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAMrC,WAAW,IAAI,OAAO;IAItB,oBAAoB,IAAI,OAAO;IAK/B,MAAM,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IAYhF,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS;CAGpD"}

package/dist/request_manager.js

@@ -0,0 +1,163 @@
+import { CONNECTION_LOST, RxFerrixError } from "./errors.js";
+/**
+ * Tracks in-flight mutations and actions.
+ *
+ * A mutation's promise resolves only once BOTH its successful `MutationResponse { ts: M }` has arrived AND the client
+ * has applied a Transition with `endVersion.ts >= M` (read-your-writes). Failures reject immediately.
+ *
+ * Settling is split in two (`settle` callbacks are returned rather than invoked) so the client can update its query
+ * view (dropping optimistic updates) before promise continuations run.
+ */
+export class RequestManager {
+    nextRequestId = 0;
+    requests = new Map();
+    allocateRequestId() {
+        return this.nextRequestId++;
+    }
+    trackMutation(message) {
+        return new Promise((resolve, reject) => {
+            this.requests.set(message.requestId, {
+                kind: "mutation",
+                message,
+                sent: false,
+                completed: null,
+                startedAt: Date.now(),
+                resolve,
+                reject,
+            });
+        });
+    }
+    trackAction(message) {
+        return new Promise((resolve, reject) => {
+            this.requests.set(message.requestId, {
+                kind: "action",
+                message,
+                sent: false,
+                startedAt: Date.now(),
+                resolve,
+                reject,
+            });
+        });
+    }
+    /** Messages that still have to go out on the current socket, in request order. */
+    unsent() {
+        const out = [];
+        for (const request of this.requests.values()) {
+            if (request.sent)
+                continue;
+            if (request.kind === "mutation" && request.completed)
+                continue;
+            out.push(request.message);
+        }
+        return out;
+    }
+    /** The message went out on the current socket. */
+    markSent(requestId) {
+        const request = this.requests.get(requestId);
+        if (request)
+            request.sent = true;
+    }
+    /**
+     * Handles a MutationResponse. `observedTs` is the ts of the last applied Transition, or null when the client's view
+     * is not currently consistent with the server (right after a reconnect).
+     *
+     * Returns the settled mutation (whose optimistic update must be dropped), or null if it is still waiting for its
+     * ts to be observed (or the requestId is unknown).
+     */
+    onMutationResponse(response, observedTs) {
+        const request = this.requests.get(response.requestId);
+        if (!request || request.kind !== "mutation" || request.completed)
+            return null;
+        if (!response.success) {
+            this.requests.delete(response.requestId);
+            const error = RxFerrixError.fromServer(response.errorMessage, response.errorData);
+            return { requestId: response.requestId, settle: () => request.reject(error) };
+        }
+        request.completed = { ts: response.ts, result: response.result };
+        if (observedTs !== null && observedTs >= response.ts) {
+            this.requests.delete(response.requestId);
+            const result = response.result;
+            return { requestId: response.requestId, settle: () => request.resolve(result) };
+        }
+        return null;
+    }
+    /** Handles an ActionResponse. Returns the settle callback, or null for an unknown request. */
+    onActionResponse(response) {
+        const request = this.requests.get(response.requestId);
+        if (!request || request.kind !== "action")
+            return null;
+        this.requests.delete(response.requestId);
+        if (response.success) {
+            const result = response.result;
+            return () => request.resolve(result);
+        }
+        const error = RxFerrixError.fromServer(response.errorMessage, response.errorData);
+        return () => request.reject(error);
+    }
+    /** A Transition with `endVersion.ts = ts` was applied: completes every mutation with a commit ts <= ts. */
+    removeCompleted(ts) {
+        const settled = [];
+        for (const [requestId, request] of this.requests) {
+            if (request.kind !== "mutation" || !request.completed || request.completed.ts > ts)
+                continue;
+            this.requests.delete(requestId);
+            const result = request.completed.result;
+            settled.push({ requestId, settle: () => request.resolve(result) });
+        }
+        return settled;
+    }
+    /**
+     * The socket dropped. Mutations without a response will be re-sent on the next socket. Actions that were already
+     * sent are rejected because they are not idempotent; actions that never left the client stay queued.
+     */
+    onSocketClosed() {
+        const rejected = [];
+        for (const [requestId, request] of this.requests) {
+            if (request.kind === "mutation") {
+                if (!request.completed)
+                    request.sent = false;
+                continue;
+            }
+            if (!request.sent)
+                continue;
+            this.requests.delete(requestId);
+            const error = new RxFerrixError(`Connection lost while action "${request.message.udfPath}" was in flight`, { code: CONNECTION_LOST });
+            rejected.push({ requestId, settle: () => request.reject(error) });
+        }
+        return rejected;
+    }
+    /** Rejects everything (client closed). */
+    rejectAll(error) {
+        const all = [...this.requests.values()];
+        this.requests.clear();
+        for (const request of all)
+            request.reject(error);
+    }
+    hasInflight() {
+        return this.requests.size > 0;
+    }
+    hasInflightMutations() {
+        for (const request of this.requests.values())
+            if (request.kind === "mutation")
+                return true;
+        return false;
+    }
+    counts() {
+        let mutations = 0;
+        let actions = 0;
+        let oldest = null;
+        for (const request of this.requests.values()) {
+            if (request.kind === "mutation")
+                mutations++;
+            else
+                actions++;
+            if (oldest === null || request.startedAt < oldest)
+                oldest = request.startedAt;
+        }
+        return { mutations, actions, oldestStartedAt: oldest };
+    }
+    udfPathOf(requestId) {
+        return this.requests.get(requestId)?.message.udfPath;
+    }
+}
+//# sourceMappingURL=request_manager.js.map

package/dist/request_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request_manager.js","sourceRoot":"","sources":["../src/request_manager.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -0,0 +1,45 @@
+/**
+ * File uploads to a RxFerrix server.
+ *
+ * The flow: a mutation returns `ctx.storage.generate_upload_url()`, the client `POST`s the file to it
+ * with {@link uploadFile}, and a second mutation stores the returned `Id<"_storage">` in a document. Serve it with
+ * the URL from `ctx.storage.get_url(id)` (`/api/storage/<id>`).
+ *
+ * ```ts
+ * const url = await client.mutation(api.files.generateUploadUrl, {});
+ * const storageId = await uploadFile(url, file, { onProgress: ({ loaded, total }) => (pct = loaded / total) });
+ * await client.mutation(api.files.attach, { storageId });
+ * ```
+ */
+import type { Id } from "./api.js";
+export interface UploadProgress {
+    /** Bytes sent so far. */
+    loaded: number;
+    /** Total bytes to send. */
+    total: number;
+}
+export interface UploadFileOptions {
+    /** Called as the upload progresses (with `XMLHttpRequest`; with `fetch`, only at the start and the end). */
+    onProgress?: (progress: UploadProgress) => void;
+    /** Aborts the upload; the promise rejects with an `AbortError`. */
+    signal?: AbortSignal;
+    /** The `Content-Type` to store. Default: the Blob's `type` (none if empty). */
+    contentType?: string;
+    /** The original file name to store. Default: `File.name` for a `File`; `null` sends none. */
+    filename?: string | null;
+    /** Base for a root-relative upload URL (`/api/storage/upload?…`). Default: the page's `location`. */
+    baseUrl?: string;
+    /** `fetch` to use when `XMLHttpRequest` is unavailable (or `transport: "fetch"`). Default: `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Force a transport. Default: `XMLHttpRequest` when available (browsers, for progress events), else `fetch`. */
+    transport?: "xhr" | "fetch";
+}
+/** The final URL: `uploadUrl` resolved against `baseUrl`, with `filename` appended. */
+export declare function uploadRequestUrl(uploadUrl: string, filename: string | null | undefined, baseUrl?: string): string;
+/**
+ * Upload `file` to an upload URL from `ctx.storage.generate_upload_url()` and return the new file's
+ * `Id<"_storage">`. Rejects with a {@link RxFerrixError} whose `code` is the server's (`file_too_large`,
+ * `upload_url_expired`, `upload_url_used`, `invalid_upload_url`, `rate_limited`, ...), or `network_error`.
+ */
+export declare function uploadFile(uploadUrl: string, file: Blob, options?: UploadFileOptions): Promise<Id<"_storage">>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAInC,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,4GAA4G;IAC5G,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qGAAqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kHAAkH;IAClH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,iHAAiH;IACjH,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;CAC7B;AAOD,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAYjH;AAyBD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAYxH"}

package/dist/storage.js

@@ -0,0 +1,120 @@
+import { RxFerrixError } from "./errors.js";
+/** The final URL: `uploadUrl` resolved against `baseUrl`, with `filename` appended. */
+export function uploadRequestUrl(uploadUrl, filename, baseUrl) {
+    const base = baseUrl ?? (typeof location !== "undefined" ? location.href : undefined);
+    let url;
+    try {
+        url = base === undefined ? new URL(uploadUrl) : new URL(uploadUrl, base);
+    }
+    catch {
+        throw new RxFerrixError(`Invalid upload URL ${JSON.stringify(uploadUrl)} (pass options.baseUrl for relative URLs)`, {
+            code: "invalid_upload_url",
+        });
+    }
+    if (filename)
+        url.searchParams.set("filename", filename);
+    return url.toString();
+}
+function parseResult(status, text) {
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        // Not JSON (e.g. a proxy's error page).
+    }
+    if (status >= 200 && status < 300) {
+        const id = body?.storageId;
+        if (typeof id !== "string")
+            throw new RxFerrixError(`Unexpected upload response: ${text.slice(0, 200)}`);
+        return id;
+    }
+    const err = body;
+    if (err && typeof err === "object" && (err.errorMessage || err.errorData)) {
+        throw RxFerrixError.fromServer(err.errorMessage, err.errorData ?? null);
+    }
+    throw new RxFerrixError(`Upload failed with HTTP ${status}`, { code: status === 413 ? "file_too_large" : "http_error" });
+}
+function abortError(signal) {
+    return signal?.reason ?? new DOMException("The upload was aborted", "AbortError");
+}
+/**
+ * Upload `file` to an upload URL from `ctx.storage.generate_upload_url()` and return the new file's
+ * `Id<"_storage">`. Rejects with a {@link RxFerrixError} whose `code` is the server's (`file_too_large`,
+ * `upload_url_expired`, `upload_url_used`, `invalid_upload_url`, `rate_limited`, ...), or `network_error`.
+ */
+export async function uploadFile(uploadUrl, file, options = {}) {
+    const filename = options.filename !== undefined
+        ? options.filename
+        : typeof File !== "undefined" && file instanceof File && file.name
+            ? file.name
+            : null;
+    const url = uploadRequestUrl(uploadUrl, filename, options.baseUrl);
+    const contentType = options.contentType ?? (file.type || undefined);
+    if (options.signal?.aborted)
+        throw abortError(options.signal);
+    const useXhr = options.transport ? options.transport === "xhr" : typeof XMLHttpRequest === "function";
+    return useXhr ? uploadWithXhr(url, file, contentType, options) : uploadWithFetch(url, file, contentType, options);
+}
+function uploadWithXhr(url, file, contentType, options) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        const { signal, onProgress } = options;
+        const onAbort = () => xhr.abort();
+        const cleanup = () => signal?.removeEventListener("abort", onAbort);
+        xhr.open("POST", url);
+        if (contentType)
+            xhr.setRequestHeader("Content-Type", contentType);
+        if (onProgress) {
+            xhr.upload.onprogress = (e) => {
+                onProgress({ loaded: e.loaded, total: e.lengthComputable ? e.total : file.size });
+            };
+        }
+        xhr.onload = () => {
+            cleanup();
+            try {
+                const id = parseResult(xhr.status, xhr.responseText);
+                onProgress?.({ loaded: file.size, total: file.size });
+                resolve(id);
+            }
+            catch (e) {
+                reject(e);
+            }
+        };
+        xhr.onerror = () => {
+            cleanup();
+            reject(new RxFerrixError("The upload failed: network error", { code: "network_error" }));
+        };
+        xhr.onabort = () => {
+            cleanup();
+            reject(abortError(signal));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        xhr.send(file);
+    });
+}
+async function uploadWithFetch(url, file, contentType, options) {
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    options.onProgress?.({ loaded: 0, total: file.size });
+    let res;
+    try {
+        res = await fetchFn(url, {
+            method: "POST",
+            body: file,
+            headers: contentType ? { "Content-Type": contentType } : {},
+            signal: options.signal,
+        });
+    }
+    catch (e) {
+        if (options.signal?.aborted)
+            throw abortError(options.signal);
+        throw new RxFerrixError(`The upload failed: ${e instanceof Error ? e.message : String(e)}`, {
+            code: "network_error",
+            cause: e,
+        });
+    }
+    const id = parseResult(res.status, await res.text());
+    options.onProgress?.({ loaded: file.size, total: file.size });
+    return id;
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/testing.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Test utilities: a scriptable fake of the RxFerrix sync endpoint (`@rxferrix/client/testing`).
+ *
+ * ```ts
+ * const server = new FakeServer();
+ * const client = new RxFerrixClient("http://localhost", { webSocketConstructor: server.WebSocket });
+ * server.open();                       // the socket connects
+ * await flushMicrotasks();             // batched ModifyQuerySet goes out
+ * server.sent;                         // what the client sent on this socket
+ * server.transition({ querySet: 1, ts: 1 }, [{ type: "QueryUpdated", queryId: 0, value: [] }]);
+ * ```
+ */
+import type { ClientMessage, ServerMessage, StateVersion } from "./protocol.js";
+type Modification = Extract<ServerMessage, {
+    type: "Transition";
+}>["modifications"][number];
+export declare class FakeSocket {
+    readonly url: string;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readyState: number;
+    readonly sent: ClientMessage[];
+    closedByClient: boolean;
+    /** The server-side StateVersion of this socket, advanced by `transition`. */
+    version: StateVersion;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: string;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    constructor(url: string);
+    send(data: string): void;
+    close(): void;
+}
+export declare class FakeServer {
+    readonly sockets: FakeSocket[];
+    readonly WebSocket: typeof WebSocket;
+    constructor();
+    /** The most recently created socket. */
+    get socket(): FakeSocket;
+    /** Everything the client sent on the current socket. */
+    get sent(): ClientMessage[];
+    /** Messages of one type sent on the current socket. */
+    sentOfType<T extends ClientMessage["type"]>(type: T): Extract<ClientMessage, {
+        type: T;
+    }>[];
+    /** Returns and forgets what the client sent on the current socket so far. */
+    drain(): ClientMessage[];
+    open(): void;
+    push(message: ServerMessage | Record<string, unknown>): void;
+    /**
+     * Pushes a Transition from the socket's current version. `end` overrides fields of the end version; unspecified
+     * fields keep their current value.
+     */
+    transition(end: Partial<StateVersion>, modifications?: Modification[]): void;
+    /** The server closes the current socket. */
+    close(code?: number, reason?: string): void;
+}
+/** Lets queued microtasks (query-set flush, promise continuations) run. */
+export declare function flushMicrotasks(): Promise<void>;
+export {};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhF,KAAK,YAAY,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5F,qBAAa,UAAU;IAiBT,QAAQ,CAAC,GAAG,EAAE,MAAM;IAhBhC,MAAM,CAAC,QAAQ,CAAC,UAAU,KAAK;IAC/B,MAAM,CAAC,QAAQ,CAAC,IAAI,KAAK;IACzB,MAAM,CAAC,QAAQ,CAAC,OAAO,KAAK;IAC5B,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK;IAE3B,UAAU,SAAyB;IACnC,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAM;IACpC,cAAc,UAAS;IACvB,6EAA6E;IAC7E,OAAO,EAAE,YAAY,CAAuC;IAE5D,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC9C,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC1D,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACxE,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;gBAE1B,GAAG,EAAE,MAAM;IAEhC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,KAAK,IAAI,IAAI;CAKd;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,CAAM;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,SAAS,CAAC;;IAarC,wCAAwC;IACxC,IAAI,MAAM,IAAI,UAAU,CAIvB;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,aAAa,EAAE,CAE1B;IAED,uDAAuD;IACvD,UAAU,CAAC,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,EAAE;IAI3F,6EAA6E;IAC7E,KAAK,IAAI,aAAa,EAAE;IAIxB,IAAI,IAAI,IAAI;IAMZ,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAM5D;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,aAAa,GAAE,YAAY,EAAO,GAAG,IAAI;IAQhF,4CAA4C;IAC5C,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAkB,GAAG,IAAI;CAKnD;AAED,2EAA2E;AAC3E,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAErD"}