@reatomized/convex 0.0.0-stage → 0.1.0

package/dist/browser/reatom/connection_hooks.d.ts

@@ -0,0 +1,11 @@
+import type { AtomLike, Ext } from "@reatom/core";
+/**
+ * Calls `connect` when `target` gains its first subscriber and `disconnect`
+ * when it loses the last one. `target` must have no other connect hook.
+ *
+ * Sets Reatom's internal `onConnect` slot to plain functions: Reatom's queue
+ * calls them in the context's root frame. Unlike `withConnectHook` this makes
+ * no actions, AbortController or AbortError per connection, which matters
+ * with thousands of queries.
+ */
+export declare const withConnectionHooks: <Target extends AtomLike<any, any[], any>>(connect: () => void, disconnect: () => void) => Ext<Target, Target>;

package/dist/browser/reatom/connection_hooks.js

@@ -0,0 +1,15 @@
+/**
+ * Calls `connect` when `target` gains its first subscriber and `disconnect`
+ * when it loses the last one. `target` must have no other connect hook.
+ *
+ * Sets Reatom's internal `onConnect` slot to plain functions: Reatom's queue
+ * calls them in the context's root frame. Unlike `withConnectHook` this makes
+ * no actions, AbortController or AbortError per connection, which matters
+ * with thousands of queries.
+ */
+export const withConnectionHooks = (connect, disconnect) => (target) => {
+    target.__reatom.onConnect = Object.assign(() => connect(), {
+        abort: () => disconnect(),
+    });
+    return target;
+};

package/dist/browser/reatom/errors.d.ts

@@ -0,0 +1,3 @@
+import { FunctionFailure } from "../sync/function_result.js";
+/** The error a failed function call surfaces as: `ConvexError` when it carries data. */
+export declare function functionError(type: "query" | "mutation" | "action", udfPath: string, result: FunctionFailure): Error;

package/dist/browser/reatom/errors.js

@@ -0,0 +1,8 @@
+import { ConvexError } from "convex/values";
+import { createHybridErrorStacktrace, forwardData } from "../logging.js";
+/** The error a failed function call surfaces as: `ConvexError` when it carries data. */
+export function functionError(type, udfPath, result) {
+    return result.errorData !== undefined
+        ? forwardData(result, new ConvexError(createHybridErrorStacktrace(type, udfPath, result)))
+        : new Error(createHybridErrorStacktrace(type, udfPath, result));
+}

package/dist/browser/reatom/index.d.ts

@@ -0,0 +1,6 @@
+export { reatomConvexClient } from "./client.js";
+export type { BaseConvexClientOptions as ReatomConvexClientOptions, ConnectionState, MutationOptions, QueryModification, QueryStatus, ReatomConvexClient, ReatomQuery, ReatomQueryOptions, Transition, } from "./client.js";
+export type { AuthTokenFetcher } from "./auth.js";
+export type { PaginatedQueryState, ReatomPaginatedQuery } from "./paginated.js";
+export type { SocketState } from "./socket.js";
+export type { OptimisticLocalStore } from "convex/browser";

package/dist/browser/reatom/index.js

@@ -0,0 +1,2 @@
+// The entry point of the @reatomized/convex package, built by scripts/build.mjs.
+export { reatomConvexClient } from "./client.js";

package/dist/browser/reatom/optimistic.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Optimistic updates over server results. The overlay holds only the results
+ * updates have set; everything else reads through to the server results of
+ * subscribed queries.
+ */
+import { FunctionArgs, FunctionReference, FunctionReference_future, FunctionReturnType, OptionalRestArgs } from "convex/server";
+import { Value } from "convex/values";
+import { FunctionResult } from "../sync/function_result.js";
+import { OptimisticLocalStore } from "convex/browser";
+import { RequestId } from "../sync/protocol.js";
+import { QueryToken } from "../sync/udf_path_utils.js";
+export type OverlayQuery = {
+    udfPath: string;
+    args: Record<string, Value>;
+    /** `undefined` is a query an update set to loading. */
+    result: FunctionResult | undefined;
+};
+export type Overlay = Map<QueryToken, OverlayQuery>;
+/** Subscribed queries with a server result, in subscription order. */
+export type ServerResults = {
+    get(token: QueryToken): FunctionResult | undefined;
+    all(): Iterable<OverlayQuery & {
+        token: QueryToken;
+    }>;
+};
+/** An optimistic update curried over its mutation's arguments. */
+export type WrappedOptimisticUpdate = (store: OptimisticLocalStore) => void;
+export type OptimisticUpdateAndId = {
+    update: WrappedOptimisticUpdate;
+    mutationId: RequestId;
+};
+/** A store writing into `overlay`; `modifiedQueries` collects the tokens it sets. */
+export declare class OptimisticLocalStoreImpl implements OptimisticLocalStore {
+    private readonly overlay;
+    private readonly server;
+    readonly modifiedQueries: QueryToken[];
+    constructor(overlay: Overlay, server: ServerResults);
+    getQuery<Query extends FunctionReference<"query"> | FunctionReference_future<"query">>(query: Query, ...args: OptionalRestArgs<Query>): undefined | FunctionReturnType<Query>;
+    getAllQueries<Query extends FunctionReference<"query"> | FunctionReference_future<"query">>(query: Query): {
+        args: FunctionArgs<Query>;
+        value: undefined | FunctionReturnType<Query>;
+    }[];
+    setQuery<Query extends FunctionReference<"query"> | FunctionReference_future<"query">>(queryReference: Query, args: FunctionArgs<Query>, value: undefined | FunctionReturnType<Query>): void;
+}

package/dist/browser/reatom/optimistic.js

@@ -0,0 +1,70 @@
+/**
+ * Optimistic updates over server results. The overlay holds only the results
+ * updates have set; everything else reads through to the server results of
+ * subscribed queries.
+ */
+import { getFunctionName, } from "convex/server";
+import { parseArgs } from "../../common/index.js";
+import { canonicalizeUdfPath, serializePathAndArgs, } from "../sync/udf_path_utils.js";
+// An errored query reads as loading, so one failed query doesn't break an
+// update that reads it.
+function queryValue(result) {
+    if (result === undefined || !result.success)
+        return undefined;
+    return result.value;
+}
+/** A store writing into `overlay`; `modifiedQueries` collects the tokens it sets. */
+export class OptimisticLocalStoreImpl {
+    overlay;
+    server;
+    modifiedQueries = [];
+    constructor(overlay, server) {
+        this.overlay = overlay;
+        this.server = server;
+    }
+    getQuery(query, ...args) {
+        const token = serializePathAndArgs(getFunctionName(query), parseArgs(args[0]));
+        const local = this.overlay.get(token);
+        return queryValue(local ? local.result : this.server.get(token));
+    }
+    getAllQueries(query) {
+        const udfPath = canonicalizeUdfPath(getFunctionName(query));
+        const queries = [];
+        // Server results keep their position when an update overrides them;
+        // queries only updates know about come after.
+        const seen = new Set();
+        for (const subscribed of this.server.all()) {
+            seen.add(subscribed.token);
+            if (subscribed.udfPath !== udfPath)
+                continue;
+            const local = this.overlay.get(subscribed.token);
+            queries.push({
+                args: subscribed.args,
+                value: queryValue(local ? local.result : subscribed.result),
+            });
+        }
+        for (const [token, local] of this.overlay) {
+            if (seen.has(token) || local.udfPath !== udfPath)
+                continue;
+            queries.push({
+                args: local.args,
+                value: queryValue(local.result),
+            });
+        }
+        return queries;
+    }
+    setQuery(queryReference, args, value) {
+        const queryArgs = parseArgs(args);
+        const name = getFunctionName(queryReference);
+        const token = serializePathAndArgs(name, queryArgs);
+        this.overlay.set(token, {
+            udfPath: canonicalizeUdfPath(name),
+            args: queryArgs,
+            // An optimistic update has no function logs to show.
+            result: value === undefined
+                ? undefined
+                : { success: true, value, logLines: [] },
+        });
+        this.modifiedQueries.push(token);
+    }
+}

package/dist/browser/reatom/paginated.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Reactive pagination over page queries. Loaded pages stay subscribed and
+ * keep their boundaries; a page the server asks to split is replaced by two
+ * once both halves have loaded. The page list derives itself from its
+ * previous value and the page results it reads, so subscribing it subscribes
+ * exactly the pages in use.
+ */
+import { type Action, type AtomLike, type Computed } from "@reatom/core";
+import { Value } from "convex/values";
+import { FunctionResult } from "../sync/function_result.js";
+import { PaginationStatus } from "../sync/pagination.js";
+import { PaginatedQueryToken, QueryToken } from "../sync/udf_path_utils.js";
+/** What a paginated query needs of a page query. */
+export type PageQuery = {
+    readonly token: QueryToken;
+    readonly result: AtomLike<FunctionResult | undefined, []>;
+};
+/**
+ * The state of a {@link ReatomPaginatedQuery}.
+ *
+ * @public
+ */
+export type PaginatedQueryState<Item> = {
+    results: Item[];
+    status: PaginationStatus;
+    /** The error a page failed with. */
+    error?: Error;
+};
+/**
+ * A paginated query of a {@link ReatomConvexClient}.
+ *
+ * Reading its atoms inside a subscribed Reatom graph subscribes its pages.
+ * Once nothing reads it, it drops its pages and starts over from the first
+ * one.
+ *
+ * @public
+ */
+export interface ReatomPaginatedQuery<Item = Value> {
+    readonly token: PaginatedQueryToken;
+    readonly state: Computed<PaginatedQueryState<Item>>;
+    readonly results: Computed<Item[]>;
+    readonly status: Computed<PaginationStatus>;
+    readonly error: Computed<Error | undefined>;
+    /**
+     * Load `numItems` more items. Returns whether a page load started: not
+     * while a page loads or once the query is exhausted.
+     */
+    readonly loadMore: Action<[numItems: number], boolean>;
+}
+export type PaginatedOptions = {
+    initialNumItems: number;
+    id: number;
+};
+type PageFactory = (udfPath: string, args: Record<string, Value>, paginationOpts: Record<string, Value>) => PageQuery;
+export declare function reatomPaginatedQuery(page: PageFactory, udfPath: string, args: Record<string, Value>, options: PaginatedOptions, name: string): ReatomPaginatedQuery;
+export {};

package/dist/browser/reatom/paginated.js

@@ -0,0 +1,162 @@
+/**
+ * Reactive pagination over page queries. Loaded pages stay subscribed and
+ * keep their boundaries; a page the server asks to split is replaced by two
+ * once both halves have loaded. The page list derives itself from its
+ * previous value and the page results it reads, so subscribing it subscribes
+ * exactly the pages in use.
+ */
+import { action, atom, computed, noop, withComputed, } from "@reatom/core";
+import { asPaginationResult } from "../sync/pagination.js";
+import { serializePaginatedPathAndArgs, } from "../sync/udf_path_utils.js";
+import { withConnectionHooks } from "./connection_hooks.js";
+import { functionError } from "./errors.js";
+const loadedPage = (query) => {
+    const result = query.result();
+    return result?.success ? asPaginationResult(result.value) : undefined;
+};
+export function reatomPaginatedQuery(page, udfPath, args, options, name) {
+    const { initialNumItems, id } = options;
+    const token = serializePaginatedPathAndArgs(udfPath, args, options);
+    const pageAt = (paginationOpts, cursor) => ({
+        query: page(udfPath, args, paginationOpts),
+        cursor,
+    });
+    const firstPage = () => ({
+        keys: [0],
+        pages: new Map([
+            [0, pageAt({ cursor: null, numItems: initialNumItems, id }, null)],
+        ]),
+        splits: new Map(),
+        nextKey: 1,
+    });
+    /** Swaps in the halves of each split once both have loaded. */
+    const completeSplits = (list) => {
+        let next = list;
+        for (const [key, [first, second]] of list.splits) {
+            const halvesLoaded = list.pages.get(first).query.result() !== undefined &&
+                list.pages.get(second).query.result() !== undefined;
+            if (!halvesLoaded)
+                continue;
+            const pages = new Map(next.pages);
+            pages.delete(key);
+            const splits = new Map(next.splits);
+            splits.delete(key);
+            next = {
+                ...next,
+                keys: next.keys.flatMap((current) => current === key ? [first, second] : [current]),
+                pages,
+                splits,
+            };
+        }
+        return next;
+    };
+    /** Starts splitting each active page the server or its size asks to split. */
+    const startSplits = (list) => {
+        let next = list;
+        for (const key of list.keys) {
+            if (next.splits.has(key))
+                continue;
+            const current = list.pages.get(key);
+            const result = loadedPage(current.query);
+            if (!result)
+                continue;
+            const shouldSplit = result.splitCursor &&
+                (result.pageStatus === "SplitRecommended" ||
+                    result.pageStatus === "SplitRequired" ||
+                    // This client-driven page splitting condition may change.
+                    result.page.length > initialNumItems * 2);
+            if (!shouldSplit)
+                continue;
+            const splitCursor = result.splitCursor;
+            const first = next.nextKey;
+            const second = first + 1;
+            const paginationOpts = { numItems: initialNumItems, id };
+            const pages = new Map(next.pages);
+            pages.set(first, pageAt({ ...paginationOpts, cursor: current.cursor, endCursor: splitCursor }, current.cursor));
+            pages.set(second, pageAt({
+                ...paginationOpts,
+                cursor: splitCursor,
+                endCursor: result.continueCursor,
+            }, splitCursor));
+            // Read now, so the halves loading derives the list again.
+            pages.get(first).query.result();
+            pages.get(second).query.result();
+            next = {
+                ...next,
+                pages,
+                splits: new Map(next.splits).set(key, [first, second]),
+                nextKey: second + 1,
+            };
+        }
+        return next;
+    };
+    const pages = atom(null, `${name}.pages`).extend(withComputed((current) => {
+        const next = startSplits(completeSplits(current ?? firstPage()));
+        // Exactly the pages in the list are read, so a replaced page drops.
+        for (const { query } of next.pages.values())
+            query.result();
+        return next;
+    }), 
+    // Like `PaginatedQueryClient`, forget loaded pages once unused.
+    withConnectionHooks(noop, () => {
+        pages.set(null);
+    }));
+    const state = computed(() => {
+        const list = pages();
+        let results = [];
+        // A page is loading; only the last one is supposed to.
+        let hasUndefined = false;
+        let isDone = false;
+        for (const key of list.keys) {
+            const result = list.pages.get(key).query.result();
+            if (result === undefined) {
+                hasUndefined = true;
+                isDone = false;
+                continue;
+            }
+            if (!result.success) {
+                return {
+                    results: [],
+                    status: "LoadingFirstPage",
+                    error: functionError("query", udfPath, result),
+                };
+            }
+            const paginationResult = asPaginationResult(result.value);
+            results = results.concat(paginationResult.page);
+            isDone = !!paginationResult.isDone;
+        }
+        const status = hasUndefined
+            ? results.length === 0
+                ? "LoadingFirstPage"
+                : "LoadingMore"
+            : isDone
+                ? "Exhausted"
+                : "CanLoadMore";
+        return { results, status };
+    }, `${name}.state`);
+    const loadMore = action((numItems) => {
+        const list = pages();
+        const last = list.pages.get(list.keys[list.keys.length - 1]);
+        const result = loadedPage(last.query);
+        // Still loading a page, or no more pages.
+        if (!result || result.isDone)
+            return false;
+        const key = list.nextKey;
+        pages.set({
+            ...list,
+            keys: [...list.keys, key],
+            pages: new Map(list.pages).set(key, pageAt({ cursor: result.continueCursor, numItems, id }, result.continueCursor)),
+            nextKey: key + 1,
+        });
+        return true;
+    }, `${name}.loadMore`);
+    return {
+        token,
+        state,
+        results: computed(() => state().results, `${name}.results`),
+        status: computed(() => state().status, `${name}.status`),
+        error: computed(() => state().error, `${name}.error`),
+        loadMore,
+        pageTokens: () => Array.from(pages().pages.values(), ({ query }) => query.token),
+    };
+}

package/dist/browser/reatom/socket.d.ts

@@ -0,0 +1,52 @@
+import { Logger } from "../logging.js";
+import { ClientMessage, ServerMessage } from "../sync/protocol.js";
+export type SocketState = {
+    state: "disconnected";
+} | {
+    state: "connecting";
+    paused: "yes" | "no";
+} | {
+    state: "ready";
+    paused: "yes" | "no" | "uninitialized";
+} | {
+    state: "stopped";
+} | {
+    state: "terminated";
+};
+export type ReconnectMetadata = {
+    connectionCount: number;
+    lastCloseReason: string | null;
+    clientTs: number;
+};
+export type SocketCallbacks = {
+    onOpen: (reconnectMetadata: ReconnectMetadata) => void;
+    onResume: () => void;
+    /** Returns whether the client has synced past the last reconnect. */
+    onMessage: (message: ServerMessage) => boolean;
+    onServerDisconnectError?: ((message: string) => void) | undefined;
+};
+export declare function monotonicMillis(): number;
+export declare function reatomSocket(uri: string, options: {
+    webSocketConstructor: typeof WebSocket;
+    logger: Logger;
+    debug: boolean;
+}, callbacks: SocketCallbacks, name: string): {
+    /** The state machine position, without the socket handle. */
+    state: import("@reatom/core").Atom<SocketState, [newState: SocketState]>;
+    /** Times a socket reached `ready`. */
+    connectionCount: import("@reatom/core").Atom<number, [newState: number]>;
+    retries: import("@reatom/core").Atom<number, [newState: number]>;
+    hasEverConnected: import("@reatom/core").Atom<boolean, [newState: boolean]>;
+    send: (message: ClientMessage) => boolean;
+    /** Opens the first socket. */
+    start(): void;
+    /** Closes the socket until `tryRestart`. */
+    stop(): Promise<void>;
+    /** Reconnects after `stop`, unless terminated meanwhile. */
+    tryRestart(): void;
+    pause(): void;
+    resume(): void;
+    /** Closes the socket for good. */
+    terminate(): Promise<void>;
+};
+export type ReatomSocket = ReturnType<typeof reatomSocket>;