@polyphron/viper-react 0.1.2 → 0.2.1

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,69 @@
+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 { 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>;

package/dist/db.js

@@ -0,0 +1,330 @@
+import { createCollection } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { toViperFilter, toViperSort, toWindow } from "./db-query.js";
+import { useViper } from "./provider.js";
+export { toViperFilter, toViperSort } from "./db-query.js";
+export { useLivePage, viperPage, viperPageOptions, } from "./db-page.js";
+export { pageComparator, planPage, } from "./page-plan.js";
+export { useLiveQuery };
+/**
+ * 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 function viperCollectionOptions(options) {
+    const { viper, collection } = options;
+    const onDemand = options.syncMode === "on-demand";
+    const records = viper.collection(collection).records;
+    // Set while the sync is running, so a mutation can write the server's
+    // answer into the collection.
+    let sink = null;
+    const sync = (params) => {
+        const { begin, write, commit, truncate, markReady, markError } = params;
+        // The `updated` we hold for each synced row: what makes an old realtime
+        // event (our own write coming back, say) unable to undo a newer one.
+        const versions = new Map();
+        let closed = false;
+        let loading = false;
+        let again = false;
+        // Events that arrive while a load is in flight, replayed after it.
+        let buffered = [];
+        // On-demand: subset loads in flight (they buffer events too), and the
+        // subsets live queries hold now, so a reload can fetch them again.
+        let pending = 0;
+        const subsets = new Map();
+        const stamp = (record) => Date.parse(record.updated) || 0;
+        const put = (record) => {
+            const seen = versions.get(record.id);
+            if (seen !== undefined && stamp(record) < seen)
+                return;
+            write({ type: seen === undefined ? "insert" : "update", value: record });
+            versions.set(record.id, stamp(record));
+        };
+        const remove = (id) => {
+            const seen = versions.get(id);
+            if (seen === undefined)
+                return;
+            write({ type: "delete", key: id });
+            versions.delete(id);
+        };
+        const apply = (event) => {
+            if (event.action === "delete")
+                remove(event.record.id);
+            else if (event.action !== "refresh")
+                put(event.record);
+        };
+        // A subset is held once per load; it is let go when each is unloaded.
+        const release = (subset) => {
+            const count = subsets.get(subset) ?? 0;
+            if (count > 1)
+                subsets.set(subset, count - 1);
+            else
+                subsets.delete(subset);
+        };
+        // Every row the held subsets want, or the whole collection when eager.
+        const fetchAll = async () => {
+            if (!onDemand)
+                return records.listAll();
+            const found = await Promise.all([...subsets.keys()].map(fetchSubset));
+            const byId = new Map();
+            for (const item of found.flat())
+                byId.set(item.id, item);
+            return [...byId.values()];
+        };
+        // One subset: the rows its `where` names, sorted, and its window when it
+        // has a limit. A `where` we could only half say loads wider and never
+        // takes a window, since the window would be cut from the wrong rows.
+        const fetchSubset = async (subset) => {
+            const { filter, exact } = toViperFilter(subset.where);
+            const sort = toViperSort(subset.orderBy);
+            const window = exact && sort && subset.limit !== undefined
+                ? toWindow(subset.offset ?? 0, subset.limit)
+                : null;
+            // Core always sends `offset` along with `cursor`, so the cursor
+            // expressions are left alone and the offset does the paging. Only the
+            // rows are wanted, so `skipTotal` spares the server its COUNT (see
+            // toWindow for why this is not a keyset cursor).
+            if (!window) {
+                return records.listAll({
+                    filter: filter || undefined,
+                    sort: sort || undefined,
+                });
+            }
+            const result = await records.list({
+                filter: filter || undefined,
+                sort: sort || undefined,
+                skipTotal: true,
+                ...window,
+            });
+            return result.items;
+        };
+        const load = async () => {
+            // One load at a time; a request during a load runs another after it.
+            if (loading) {
+                again = true;
+                return;
+            }
+            loading = true;
+            try {
+                do {
+                    again = false;
+                    const items = await fetchAll();
+                    if (closed)
+                        return;
+                    // Truncate and rewrite in one transaction, so a reload never
+                    // shows an empty list in between.
+                    begin();
+                    truncate();
+                    versions.clear();
+                    items.forEach(put);
+                    const missed = buffered;
+                    if (pending === 0)
+                        buffered = [];
+                    missed.forEach(apply);
+                    commit();
+                    markReady();
+                } while (again);
+            }
+            catch (error) {
+                markError(error);
+            }
+            finally {
+                loading = false;
+            }
+        };
+        sink = {
+            put,
+            remove,
+            write: (fn) => {
+                begin();
+                fn();
+                commit();
+            },
+        };
+        // Subscribe before loading, so nothing that happens in between is lost.
+        const off = viper.realtime.subscribe(collection, (event) => {
+            if (event.action === "refresh") {
+                void load();
+            }
+            else if (loading || pending > 0) {
+                buffered.push(event);
+            }
+            else {
+                begin();
+                apply(event);
+                commit();
+            }
+        });
+        const offResync = viper.realtime.onResync(() => void load());
+        const cleanup = () => {
+            closed = true;
+            sink = null;
+            off();
+            offResync();
+        };
+        if (!onDemand) {
+            void load();
+            return cleanup;
+        }
+        // Nothing to load until a query asks. Every realtime event is applied,
+        // not only those matching a held subset: the list rule already decided
+        // this user may see the row, and a live query drops what does not match
+        // it. Skipping non-matching events would need the where evaluated here,
+        // and would miss a new row that a query should show.
+        markReady();
+        return {
+            cleanup,
+            loadSubset: async (subset) => {
+                pending++;
+                subsets.set(subset, (subsets.get(subset) ?? 0) + 1);
+                try {
+                    const items = await fetchSubset(subset);
+                    if (closed)
+                        return;
+                    begin();
+                    items.forEach(put);
+                    buffered.forEach(apply);
+                    await commit();
+                }
+                catch (error) {
+                    release(subset);
+                    throw error;
+                }
+                finally {
+                    pending--;
+                    if (pending === 0 && !loading)
+                        buffered = [];
+                }
+            },
+            unloadSubset: release,
+        };
+    };
+    // Puts what the server answered into the collection, in place of our guess.
+    // A write the user may make on a row they may not see afterwards (the view
+    // rule now hides it) answers with only ids, so that row is dropped rather
+    // than kept as the partial guess.
+    const store = (saved) => {
+        sink?.write(() => {
+            for (const record of saved) {
+                if (!record)
+                    continue;
+                if (hiddenAnswer(record))
+                    sink?.remove(record.id);
+                else
+                    sink?.put(record);
+            }
+        });
+    };
+    return {
+        getKey: (record) => record.id,
+        // Records are whole rows, so an update replaces rather than merges.
+        sync: { sync, rowUpdateMode: "full" },
+        syncMode: onDemand ? "on-demand" : "eager",
+        onInsert: async ({ transaction }) => {
+            const saved = await save(viper, records, collection, transaction.mutations);
+            store(saved);
+        },
+        onUpdate: async ({ transaction }) => {
+            const saved = await save(viper, records, collection, transaction.mutations);
+            store(saved);
+        },
+        onDelete: async ({ transaction }) => {
+            await save(viper, records, collection, transaction.mutations);
+            sink?.write(() => {
+                for (const m of transaction.mutations)
+                    sink?.remove(m.key);
+            });
+        },
+    };
+}
+// True when a write's answer holds only the ids, which is what the server
+// sends when the view rule no longer lets the caller see the saved row.
+function hiddenAnswer(record) {
+    return Object.keys(record).every((key) => key === "id" || key === "collectionId" || key === "collectionName");
+}
+// Sends the mutations: one call for one, a single all-or-nothing batch for
+// several. Resolves to the saved records, in order (null for a delete).
+async function save(viper, records, collection, mutations) {
+    if (mutations.length > 1) {
+        return viper.batch(mutations.map((m) => toOp(collection, m)));
+    }
+    const m = mutations[0];
+    if (m.type === "insert")
+        return [await records.create(m.modified)];
+    if (m.type === "update")
+        return [await records.update(m.key, m.changes)];
+    await records.delete(m.key);
+    return [null];
+}
+// One mutation as a batch write.
+function toOp(collection, m) {
+    if (m.type === "insert") {
+        return { method: "create", collection, body: m.modified };
+    }
+    if (m.type === "update") {
+        return { method: "update", collection, id: m.key, body: m.changes };
+    }
+    return { method: "delete", collection, id: m.key };
+}
+// Collections made by `useViperCollection`, one per client, name and mode, so
+// two components asking for `posts` share one copy of it (and one fetch).
+const made = new WeakMap();
+/**
+ * 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 function useViperCollection(name, options = {}) {
+    const viper = useViper();
+    const mode = options.syncMode ?? "eager";
+    let byName = made.get(viper);
+    if (!byName) {
+        byName = new Map();
+        made.set(viper, byName);
+    }
+    const key = `${mode}:${name}`;
+    let found = byName.get(key);
+    if (!found) {
+        found = createCollection(viperCollectionOptions({ viper, collection: name, syncMode: mode }));
+        byName.set(key, found);
+    }
+    return found;
+}
+/**
+ * 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 function useLiveRecords(name, options = {}) {
+    const rows = useViperCollection(name, options);
+    const { query } = options;
+    const live = useLiveQuery({
+        query: (q) => query
+            ? query(q, rows)
+            : q.from({ row: rows }),
+    });
+    return {
+        data: live.isReady ? live.data : null,
+        error: live.isError ? new Error(`${name} could not be loaded`) : null,
+        loading: live.isLoading || live.isIdle,
+    };
+}

package/dist/page-plan.d.ts

@@ -0,0 +1,29 @@
+import type { RealtimeEvent, RecordModel } from "@polyphron/viper-client";
+/** One page as the server sent it, and how it was asked for. */
+export type PageState<T extends RecordModel = RecordModel> = {
+    /** The rows, in the server's order. */
+    rows: T[];
+    page: number;
+    /** -1 when unknown. */
+    totalPages: number;
+    /** The sort the page was asked for, like `-updated,title`. */
+    sort?: string;
+    filter?: string;
+    deleted?: boolean;
+    /** The `expand` it was asked for, like `author,tags.owner`. */
+    expand?: string;
+};
+/** What to do: write `patch` in, take `drop` out, and maybe ask again. */
+export type PagePlan<T extends RecordModel = RecordModel> = {
+    patch?: T;
+    drop?: string;
+    refetch: boolean;
+};
+/**
+ * Orders rows as the server does for `sort`, or null when the sort has a
+ * field the browser can't order the same way (text in the database's
+ * collation, numbers, lists).
+ */
+export declare function pageComparator<T extends RecordModel>(sort: string | undefined): ((a: T, b: T) => number) | null;
+/** What `event` does to `page`. */
+export declare function planPage<T extends RecordModel>(event: RealtimeEvent<T>, page: PageState<T>): PagePlan<T>;