@polyphron/viper-react 0.1.2 → 0.3.0

package/dist/db-page.js

@@ -0,0 +1,233 @@
+import { createCollection } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { useMemo, useState, useSyncExternalStore } from "react";
+import { pageComparator, planPage } from "./page-plan.js";
+import { useViper } from "./provider.js";
+// A burst of changes (an import, a batch) asks for the page once.
+const SETTLE = 300;
+const EMPTY = {
+    order: [],
+    page: 1,
+    perPage: 0,
+    totalItems: 0,
+    totalPages: 0,
+};
+// A delete of several rows, as one all-or-nothing batch.
+async function deleteAll(viper, collection, ids) {
+    if (ids.length === 1) {
+        await viper.collection(collection).records.delete(ids[0]);
+        return;
+    }
+    await viper.batch(ids.map((id) => ({ method: "delete", collection, id })));
+}
+/**
+ * Options for `createCollection()`: one server page of `collection`, kept
+ * fresh from realtime. Its totals and row order are under `utils.info()`.
+ * Deleting rows from it hides them at once, sends one all-or-nothing batch,
+ * and puts them back if the server says no.
+ */
+export function viperPageOptions(options) {
+    const { viper, collection, query } = options;
+    const records = viper.collection(collection).records;
+    const compare = pageComparator(query.sort);
+    let info = EMPTY;
+    const listeners = new Set();
+    const rows = new Map();
+    const publish = (next) => {
+        info = next;
+        listeners.forEach((listener) => listener());
+    };
+    // Set while the sync runs: how to reload, and how to take in an event.
+    let live = null;
+    const sync = (params) => {
+        const { begin, write, commit, truncate, markReady, markError } = params;
+        let closed = false;
+        let loading = null;
+        let again = false;
+        let timer;
+        const load = async () => {
+            // One load at a time; a change during a load reloads after it.
+            if (loading) {
+                again = true;
+                return loading;
+            }
+            loading = (async () => {
+                try {
+                    do {
+                        again = false;
+                        const result = await records.list(query);
+                        if (closed)
+                            return;
+                        // Truncate and rewrite in one transaction, so a reload never
+                        // shows an empty page in between.
+                        begin();
+                        truncate();
+                        rows.clear();
+                        for (const record of result.items) {
+                            write({ type: "insert", value: record });
+                            rows.set(record.id, record);
+                        }
+                        commit();
+                        markReady();
+                        publish({
+                            order: result.items.map((r) => r.id),
+                            page: result.page,
+                            perPage: result.perPage,
+                            totalItems: result.totalItems,
+                            totalPages: result.totalPages,
+                        });
+                    } while (again && !closed);
+                }
+                catch (error) {
+                    markError(error);
+                }
+                finally {
+                    loading = null;
+                }
+            })();
+            return loading;
+        };
+        const loadSoon = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => void load(), SETTLE);
+        };
+        const take = (event) => {
+            // The page on screen may be about to change; plan against the next one.
+            if (loading) {
+                again = true;
+                return;
+            }
+            const plan = planPage(event, {
+                rows: info.order.flatMap((id) => rows.get(id) ?? []),
+                page: info.page,
+                totalPages: info.totalPages,
+                sort: query.sort,
+                filter: query.filter,
+                deleted: query.deleted,
+                expand: query.expand,
+            });
+            if (plan.drop || plan.patch) {
+                begin();
+                if (plan.drop) {
+                    write({ type: "delete", key: plan.drop });
+                    rows.delete(plan.drop);
+                }
+                if (plan.patch) {
+                    write({ type: "update", value: plan.patch });
+                    rows.set(plan.patch.id, plan.patch);
+                }
+                commit();
+                let order = info.order.filter((id) => rows.has(id));
+                if (compare) {
+                    order = order
+                        .map((id) => rows.get(id))
+                        .sort(compare)
+                        .map((r) => r.id);
+                }
+                publish({ ...info, order });
+            }
+            if (plan.refetch)
+                loadSoon();
+        };
+        live = { load, take };
+        // Subscribe before loading, so nothing that happens in between is lost.
+        const off = viper.realtime.subscribe(collection, take);
+        const offResync = viper.realtime.onResync(() => void load());
+        void load();
+        return () => {
+            closed = true;
+            live = null;
+            clearTimeout(timer);
+            off();
+            offResync();
+        };
+    };
+    const utils = {
+        info: () => info,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refetch: async () => live?.load(),
+        apply: (event) => live?.take(event),
+    };
+    return {
+        id: `viper-page:${collection}:${JSON.stringify(query)}`,
+        getKey: (record) => record.id,
+        // Records are whole rows, so an update replaces rather than merges.
+        sync: { sync, rowUpdateMode: "full" },
+        utils,
+        onDelete: async ({ transaction }) => {
+            await deleteAll(viper, collection, transaction.mutations.map((m) => String(m.key)));
+            // The rows after them move up.
+            await live?.load();
+        },
+    };
+}
+// Page collections by client and page, so the route that preloads a page and
+// the table that shows it share one collection (and one fetch). One leaves
+// here when its sync stops, after nothing has read it for a while.
+const pages = new WeakMap();
+/**
+ * The page collection for `collection` and `query` on `viper`, made once and
+ * shared. Outside React (a route loader, say) call `.preload()` on it to
+ * start the fetch early.
+ */
+export function viperPage(viper, collection, query) {
+    let byKey = pages.get(viper);
+    if (!byKey) {
+        byKey = new Map();
+        pages.set(viper, byKey);
+    }
+    const key = `${collection}:${JSON.stringify(query)}`;
+    const found = byKey.get(key);
+    if (found)
+        return found;
+    const made = createCollection(viperPageOptions({ viper, collection, query }));
+    // Once it is cleaned up it can't be read again, so the next ask makes a
+    // new one.
+    made.on("status:change", ({ status }) => {
+        if (status === "cleaned-up")
+            byKey.delete(key);
+    });
+    byKey.set(key, made);
+    return made;
+}
+/**
+ * One server page of `collection` as a live list: `records.list` once, then
+ * realtime keeps it fresh, patching rows where it can. While a new `query`
+ * loads, the last page stays on screen.
+ *
+ * ```tsx
+ * const { items, totalPages } = useLivePage<Post>("posts", {
+ *   page, perPage: 30, sort: "-updated", filter,
+ * })
+ * ```
+ */
+export function useLivePage(collection, query) {
+    const viper = useViper();
+    const rows = viperPage(viper, collection, query);
+    // A page is a list, never a single row.
+    const live = useLiveQuery(rows);
+    const info = useSyncExternalStore(rows.utils.subscribe, rows.utils.info, rows.utils.info);
+    const byId = live.state;
+    const ready = live.isReady && !!byId;
+    // The same array until a row or the order changes, so memos below hold.
+    const items = useMemo(() => (ready ? info.order.flatMap((id) => byId.get(id) ?? []) : null), 
+    // live.data changes whenever a row does.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [ready, live.data, info]);
+    // The last page that loaded, shown while the next one does.
+    const [last, setLast] = useState(null);
+    if (items && last?.items !== items)
+        setLast({ items, info });
+    const shown = items ? { items, info } : last;
+    return {
+        items: shown?.items ?? null,
+        totalItems: shown?.info.totalItems ?? 0,
+        totalPages: shown?.info.totalPages ?? 0,
+        loading: !items,
+        error: live.isError ? new Error(`${collection} could not be loaded`) : null,
+        collection: rows,
+    };
+}

package/dist/db-query.d.ts

@@ -0,0 +1,44 @@
+import type { LoadSubsetOptions } from "@tanstack/db";
+/** What a translation produced: a filter (empty when none) and its fidelity. */
+export type Translated = {
+    /** A Viper filter; "" means "no filter", so every row matches. */
+    filter: string;
+    /** True when the filter matches exactly what the query does. */
+    exact: boolean;
+};
+/**
+ * A string as a Viper string literal. Backslash escapes the next character
+ * in Viper's lexer, so escaping `\` and `"` is enough to keep a value from
+ * ever ending its own quotes.
+ */
+export declare function quote(value: string): string;
+/**
+ * A subset's `where` as a Viper filter. Anything Viper cannot say is left out
+ * (so more rows load), and the query filters again in the browser.
+ */
+export declare function toViperFilter(where: LoadSubsetOptions["where"]): Translated;
+/**
+ * A subset's `orderBy` as Viper's `sort` (`-created,title`), or null when a
+ * clause cannot be said. A partial sort would pick the wrong rows for a
+ * limit, so it is all or nothing.
+ */
+export declare function toViperSort(orderBy: LoadSubsetOptions["orderBy"]): string | null;
+/** One page request: which page, how many. */
+export type Window = {
+    page: number;
+    perPage: number;
+};
+/**
+ * The page that holds rows `offset` to `offset + limit`, or null when they
+ * are not a fit for one page (then the caller loads everything that matches).
+ *
+ * ponytail: paging is by offset (page/perPage), with `skipTotal` so the server
+ * runs no COUNT. It is not keyset: Viper's cursor is an opaque, signed
+ * token that only the previous page hands out, while TanStack DB asks for
+ * rows by `offset` (and cursor expressions on field values) with no token,
+ * and a page may be asked for out of order. Mapping an offset to a cursor
+ * would mean walking every page before it, which costs what OFFSET costs.
+ * Turning the cursor expressions into a filter is unsafe with ties and
+ * nulls. Revisit if Viper grows a token-free `after` filter.
+ */
+export declare function toWindow(offset: number, limit: number): Window | null;

package/dist/db-query.js

@@ -0,0 +1,172 @@
+/** A field name is a plain word, so it can go into a filter unquoted. */
+const FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** The comparisons Viper writes the same way TanStack DB names them. */
+const COMPARE = {
+    eq: "=",
+    gt: ">",
+    gte: ">=",
+    lt: "<",
+    lte: "<=",
+};
+/** The same comparison with its two sides swapped. */
+const FLIP = {
+    eq: "eq",
+    gt: "lt",
+    gte: "lte",
+    lt: "gt",
+    lte: "gte",
+};
+const ANY = { text: null, exact: false };
+/**
+ * A string as a Viper string literal. Backslash escapes the next character
+ * in Viper's lexer, so escaping `\` and `"` is enough to keep a value from
+ * ever ending its own quotes.
+ */
+export function quote(value) {
+    return `"${value.replace(/[\\"]/g, "\\$&")}"`;
+}
+// A value as a Viper literal, or null for one Viper has no way to write.
+function literal(value) {
+    if (typeof value === "string")
+        return quote(value);
+    if (typeof value === "boolean")
+        return String(value);
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : quote(value.toISOString());
+    }
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" && Number.isFinite(value)) {
+        // `1e21` is not a Viper number, so keep to plain digits.
+        return /^-?\d+(\.\d+)?$/.test(String(value)) ? String(value) : null;
+    }
+    return null;
+}
+// The field a ref names, or null for a nested or odd-looking path.
+function field(expr) {
+    if (expr.type !== "ref" || expr.path.length !== 1)
+        return null;
+    return FIELD.test(expr.path[0]) ? expr.path[0] : null;
+}
+// `field op value`, with the sides put the right way round.
+function compare(name, args) {
+    let [left, right] = args;
+    let op = name;
+    if (left?.type === "val" && right?.type === "ref") {
+        ;
+        [left, right] = [right, left];
+        op = FLIP[name];
+    }
+    const key = left && field(left);
+    const value = right?.type === "val" ? literal(right.value) : null;
+    if (!key || value === null)
+        return ANY;
+    return { text: `${key} ${COMPARE[op]} ${value}`, exact: true };
+}
+// `field ~ "text"`. Viper's `~` is a case-insensitive "contains", and a
+// pattern holding a `%` is used as written. That is wider than SQL LIKE (no
+// case, no exact match), so the result is never exact.
+function like(args) {
+    const key = args[0] && field(args[0]);
+    const pattern = args[1]?.type === "val" ? args[1].value : null;
+    if (!key || typeof pattern !== "string")
+        return ANY;
+    return { text: `${key} ~ ${quote(pattern)}`, exact: false };
+}
+// `field IN (a, b)` as `(field = a || field = b)`.
+function membership(args) {
+    const key = args[0] && field(args[0]);
+    const list = args[1]?.type === "val" ? args[1].value : null;
+    if (!key || !Array.isArray(list))
+        return ANY;
+    // No id is empty, so this matches nothing, as an empty IN should.
+    if (list.length === 0)
+        return { text: `id = ""`, exact: true };
+    const parts = list.map((item) => literal(item));
+    if (parts.some((part) => part === null))
+        return ANY;
+    return {
+        text: `(${parts.map((part) => `${key} = ${part}`).join(" || ")})`,
+        exact: true,
+    };
+}
+// Walks the expression. "and" may drop a part it cannot say (the rest still
+// narrows); "or" may not (dropping a side would hide rows), so one unsayable
+// side makes the whole "or" unsayable. Viper's language has no "not", so a
+// "not" is left for the browser.
+function walk(expr) {
+    if (expr.type !== "func")
+        return ANY;
+    const { name, args } = expr;
+    if (name in COMPARE)
+        return compare(name, args);
+    if (name === "like" || name === "ilike")
+        return like(args);
+    if (name === "in")
+        return membership(args);
+    if (name === "and" || name === "or") {
+        const parts = args.map(walk);
+        const joiner = name === "and" ? " && " : " || ";
+        if (name === "or" && parts.some((part) => part.text === null))
+            return ANY;
+        const texts = parts.flatMap((part) => part.text === null ? [] : [part.text]);
+        if (texts.length === 0)
+            return ANY;
+        return {
+            text: texts.length === 1 ? texts[0] : `(${texts.join(joiner)})`,
+            exact: parts.every((part) => part.exact),
+        };
+    }
+    return ANY;
+}
+/**
+ * A subset's `where` as a Viper filter. Anything Viper cannot say is left out
+ * (so more rows load), and the query filters again in the browser.
+ */
+export function toViperFilter(where) {
+    if (!where)
+        return { filter: "", exact: true };
+    const piece = walk(where);
+    return { filter: piece.text ?? "", exact: piece.exact };
+}
+/**
+ * A subset's `orderBy` as Viper's `sort` (`-created,title`), or null when a
+ * clause cannot be said. A partial sort would pick the wrong rows for a
+ * limit, so it is all or nothing.
+ */
+export function toViperSort(orderBy) {
+    const names = [];
+    for (const clause of (orderBy ?? [])) {
+        const name = field(clause.expression);
+        if (!name)
+            return null;
+        names.push(clause.compareOptions.direction === "desc" ? `-${name}` : name);
+    }
+    return names.join(",");
+}
+// The most a page holds in Viper.
+const MAX_PER_PAGE = 500;
+/**
+ * The page that holds rows `offset` to `offset + limit`, or null when they
+ * are not a fit for one page (then the caller loads everything that matches).
+ *
+ * ponytail: paging is by offset (page/perPage), with `skipTotal` so the server
+ * runs no COUNT. It is not keyset: Viper's cursor is an opaque, signed
+ * token that only the previous page hands out, while TanStack DB asks for
+ * rows by `offset` (and cursor expressions on field values) with no token,
+ * and a page may be asked for out of order. Mapping an offset to a cursor
+ * would mean walking every page before it, which costs what OFFSET costs.
+ * Turning the cursor expressions into a filter is unsafe with ties and
+ * nulls. Revisit if Viper grows a token-free `after` filter.
+ */
+export function toWindow(offset, limit) {
+    if (limit < 1 || limit > MAX_PER_PAGE)
+        return null;
+    // Whole pages when the offset lines up; otherwise start at row 0 and take
+    // the rows before the window too (they are the same rows, so it is safe).
+    if (offset % limit === 0) {
+        return { page: offset / limit + 1, perPage: limit };
+    }
+    const perPage = offset + limit;
+    return perPage <= MAX_PER_PAGE ? { page: 1, perPage } : null;
+}

package/dist/db.d.ts

@@ -0,0 +1,70 @@
+import type { RecordModel, Viper } from "@polyphron/viper-client";
+import type { Collection, CollectionConfig, Context, InitialQueryBuilder, QueryBuilder } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+export { toViperFilter, toViperSort } from "./db-query.js";
+export { useLivePage, viperPage, viperPageOptions, type LivePage, type PageCollection, type PageInfo, type PageQuery, type PageUtils, type ViperPageOptions, } from "./db-page.js";
+export { pageComparator, planPage, type PagePlan, type PageState, } from "./page-plan.js";
+export { fetchCollectionOptions, fetched, forgetFetched, refetchFetched, useFetched, useFetchedAll, type FetchKey, type FetchOptions, type FetchState, type FetchUtils, type Fetched, type FetchedResult, type Row, } from "./db-fetch.js";
+export { useLiveQuery };
+export type ViperCollectionOptions = {
+    viper: Viper;
+    /** The Viper collection's name, e.g. `posts`. */
+    collection: string;
+    /**
+     * `eager` (the default) loads every record. `on-demand` loads only what
+     * each live query asks for: its `where`, `orderBy` and `limit` become a
+     * Viper filter, sort and page.
+     */
+    syncMode?: "eager" | "on-demand";
+};
+/**
+ * Options for `createCollection()`: a TanStack DB collection that holds every
+ * record the signed-in user's list rule allows (or, in `on-demand` mode, the
+ * ones live queries ask for), and keeps it fresh from
+ * realtime events without asking the server again. Inserts, updates and
+ * deletes show at once and are rolled back if the server says no.
+ *
+ * Insert with your own `id` (15 characters, like Viper's), since the row
+ * needs a key before the server has answered.
+ */
+export declare function viperCollectionOptions<T extends RecordModel = RecordModel>(options: ViperCollectionOptions): CollectionConfig<T, string>;
+/**
+ * The Viper collection `name` for the client in `<ViperProvider>`, made once
+ * and shared: every component asking for the same name and mode gets the same
+ * collection, so its records are fetched once. Use it to insert, update and
+ * delete, and as a `from` in live queries. Nothing about `useRecords` changes.
+ *
+ * ```tsx
+ * const posts = useViperCollection<Post>("posts")
+ * posts.insert({ id: newId(), title: "Hi" })
+ * ```
+ */
+export declare function useViperCollection<T extends RecordModel = RecordModel>(name: string, options?: {
+    syncMode?: "eager" | "on-demand";
+}): Collection<T, string>;
+/** What `useLiveRecords` gives back: `useRecords`' fields, over live rows. */
+export type LiveRecords<T> = {
+    /** The rows the query matches, or null until the first load. */
+    data: T[] | null;
+    error: unknown;
+    /** True until the collection has loaded. */
+    loading: boolean;
+};
+/**
+ * The rows of a Viper collection as a live list, like `useRecords` but read
+ * from the shared collection, so it updates row by row with no refetch. Give
+ * `query` to filter, sort or join; without it you get every row. In
+ * `on-demand` mode `query` is what decides what is loaded.
+ *
+ * ```tsx
+ * const { data, loading } = useLiveRecords<Post>("posts", {
+ *   query: (q, posts) =>
+ *     q.from({ p: posts }).where(({ p }) => eq(p.status, "live")),
+ * })
+ * ```
+ */
+export declare function useLiveRecords<T extends RecordModel = RecordModel>(name: string, options?: {
+    syncMode?: "eager" | "on-demand";
+    /** Builds the query over the collection. A query on one collection returns its rows as they are; a join or a select returns the shape it builds. */
+    query?: (q: InitialQueryBuilder, rows: Collection<T, string>) => QueryBuilder<Context>;
+}): LiveRecords<T>;