snapback4 0.0.1

package/README.md

@@ -0,0 +1,21 @@
+# snapback4
+
+The client for Snapback 4, one of two parallel candidates for the successor
+to Snapback 2 (see LLP 3000 in the repository). Version 0.0.x is week one:
+this package carries the **contract** every screen is written against, a
+**labelled mock client** so an application can be written before the
+mechanism exists, and the **React hooks** over the contract. Nothing here
+talks to a server yet; the replica, the outbox and the interpreter arrive in
+weeks two and three.
+
+```ts
+import { isReady, type Read, type Write } from "snapback4/contract";
+import { createMockClient, page } from "snapback4/mock";
+import { SnapbackProvider, useQuery, useMutation } from "snapback4/react";
+```
+
+The contract fits on an index card. A read is `{ data, complete, fresh,
+since?, next? } | { loading } | { denied }`; a row this device changed and
+the server has not confirmed carries `pending: true`; a write is `pending |
+sent | failed(why)`; the app's link is `online | offline | signed-out`.
+Everything else is the runtime's business.

package/dist/contract.d.ts

@@ -0,0 +1,99 @@
+/** An opaque page position minted by whoever evaluated the page. Pass it back unchanged. */
+export type Cursor = string & {
+    readonly __cursor: "Cursor";
+};
+/** The authenticated subject a rule sees as `viewer`. */
+export type Principal = string & {
+    readonly __principal: "Principal";
+};
+/** Why something was refused. `family` and `code` are stable; `rewrite` compiles. */
+export interface Refusal {
+    readonly code: string;
+    readonly family: string;
+    readonly message: string;
+    readonly site?: string;
+    readonly rewrite?: string;
+    readonly guide?: string;
+    readonly rule?: string;
+    readonly retryable?: boolean;
+}
+/**
+ * A read. `complete` is false beyond a sync horizon or at an online-only site.
+ * `fresh` is transport truth: the value reflects the server now. When it does
+ * not, `since` is the wall-clock time (ms) of the newest server state it does
+ * reflect, so a screen can say "as of three minutes ago".
+ */
+export type Read<T> = {
+    readonly data: T;
+    readonly complete: boolean;
+    readonly fresh: boolean;
+    readonly since?: number;
+    readonly next?: Cursor | null;
+} | {
+    readonly loading: true;
+} | {
+    readonly denied: Refusal;
+};
+/** A row this device changed and the server has not yet confirmed carries `pending: true`. */
+export interface Pending {
+    readonly pending?: boolean;
+}
+/** A write. Three outcomes, all terminal or durable. `id` is client-minted and stable across replay. */
+export type Write = {
+    readonly state: "pending";
+    readonly id: string;
+} | {
+    readonly state: "sent";
+    readonly id: string;
+    readonly seq: number;
+} | {
+    readonly state: "failed";
+    readonly id: string;
+    readonly why: Refusal;
+};
+/** The app's relationship to its server. */
+export type Link = "online" | "offline" | "signed-out";
+/** A named operation. `Args` and `Result` are inferred from the authored program. */
+export interface Op<Args, Result> {
+    readonly kind: "query" | "mutation";
+    readonly name: string;
+    readonly __args?: Args;
+    readonly __result?: Result;
+}
+export type Query<Args, Result> = Op<Args, Result> & {
+    readonly kind: "query";
+};
+export type Mutation<Args, Result> = Op<Args, Result> & {
+    readonly kind: "mutation";
+};
+export type ArgsOf<O> = O extends Op<infer A, unknown> ? A : never;
+export type ResultOf<O> = O extends Op<unknown, infer R> ? R : never;
+/** A live read: the current value and a way to hear it change. */
+export interface Observed<T> {
+    getSnapshot(): Read<T>;
+    subscribe(notify: () => void): () => void;
+    close(): void;
+}
+/** The whole client, as a screen sees it. Everything else is `why`. */
+export interface Client {
+    query<A, R>(op: Query<A, R>, args: A): Promise<Read<R>>;
+    observe<A, R>(op: Query<A, R>, args: A): Observed<R>;
+    mutate<A, R>(op: Mutation<A, R>, args: A): Promise<Write>;
+    link(): Link;
+    onLink(notify: (link: Link) => void): () => void;
+    viewer(): Principal | null;
+    close(): Promise<void>;
+}
+export declare function isReady<T>(read: Read<T>): read is {
+    readonly data: T;
+    readonly complete: boolean;
+    readonly fresh: boolean;
+    readonly since?: number;
+    readonly next?: Cursor | null;
+};
+export declare function isLoading<T>(read: Read<T>): read is {
+    readonly loading: true;
+};
+export declare function isDenied<T>(read: Read<T>): read is {
+    readonly denied: Refusal;
+};

package/dist/contract.js

@@ -0,0 +1,12 @@
+// The index card (LLP 3000 §2; LLP 2000.000 §8). These are the only words a
+// screen may need. The mechanism is built to fit them; a screen that needs a
+// word not here is a defect in the mechanism, not a gap in the card.
+export function isReady(read) {
+    return "data" in read;
+}
+export function isLoading(read) {
+    return "loading" in read;
+}
+export function isDenied(read) {
+    return "denied" in read;
+}

package/dist/mock.d.ts

@@ -0,0 +1,34 @@
+import type { Client, Cursor, Link, Principal, Refusal } from "./contract.ts";
+export type Row = Record<string, unknown> & {
+    id: string;
+    pending?: boolean;
+};
+export type Tables = Record<string, Map<string, Row>>;
+/** A query function may return a page: rows plus the cursor of the next page. */
+export type Page<R> = {
+    readonly page: true;
+    readonly data: R;
+    readonly next: Cursor | null;
+};
+export declare function page<R>(data: R, next: Cursor | null): Page<R>;
+export interface MockOps {
+    readonly queries: Record<string, (tables: Tables, args: never, viewer: Principal | null) => unknown>;
+    /** Returns the ids of rows it created or changed, or a Refusal. */
+    readonly mutations: Record<string, (tables: Tables, args: never, viewer: Principal | null, mint: () => string) => readonly string[] | Refusal>;
+}
+export interface MockClient extends Client {
+    readonly tables: Tables;
+    setLink(link: Link): void;
+    /** Settle every write the fake server has admitted. */
+    settle(): Promise<void>;
+}
+export interface MockOptions {
+    readonly viewer: Principal | null;
+    readonly tables: Tables;
+    readonly ops: MockOps;
+    readonly link?: Link;
+    readonly commitDelayMs?: number;
+}
+/** MOCK id: time-ordered and unique per process; the real client mints 128-bit ids. */
+export declare function mockId(): string;
+export declare function createMockClient(options: MockOptions): MockClient;

package/dist/mock.js

@@ -0,0 +1,129 @@
+// MOCK — labelled as LLP 2000 §4 requires. No server, no store, no
+// interpreter, no transport: operations are plain functions over in-memory
+// tables, commits settle after a virtual delay, and the link is a switch the
+// app flips. Its only job is to let the reference application be written
+// against the card before the mechanism exists. Nothing here is measured.
+export function page(data, next) {
+    return { page: true, data, next };
+}
+function isPage(value) {
+    return typeof value === "object" && value !== null && value.page === true;
+}
+let minted = 0;
+/** MOCK id: time-ordered and unique per process; the real client mints 128-bit ids. */
+export function mockId() {
+    minted += 1;
+    return `m${Date.now().toString(36)}-${minted.toString(36)}`;
+}
+export function createMockClient(options) {
+    const tables = options.tables;
+    let link = options.link ?? "online";
+    let seq = 0;
+    let version = 0;
+    let lastServer = Date.now();
+    const listeners = new Set();
+    const linkListeners = new Set();
+    const queue = [];
+    const delay = options.commitDelayMs ?? 30;
+    const bump = () => { version += 1; for (const l of listeners)
+        l(); };
+    const isRefusal = (v) => typeof v === "object" && v !== null && "code" in v && "family" in v;
+    const evaluate = (op, args) => {
+        const fn = options.ops.queries[op.name];
+        if (!fn)
+            return { denied: { code: "E_OP", family: "op", message: `unknown query ${op.name}` } };
+        if (link === "signed-out")
+            return { denied: { code: "E_AUTH", family: "auth", message: "sign in to read" } };
+        const value = fn(tables, args, options.viewer);
+        const fresh = link === "online";
+        if (isPage(value))
+            return fresh ? { data: value.data, complete: true, fresh, next: value.next } : { data: value.data, complete: true, fresh, since: lastServer, next: value.next };
+        return fresh ? { data: value, complete: true, fresh } : { data: value, complete: true, fresh, since: lastServer };
+    };
+    function settleOne(entry) {
+        seq += 1;
+        for (const id of entry.touched) {
+            const row = tables[entry.table]?.get(id);
+            if (row)
+                delete row.pending;
+        }
+        lastServer = Date.now();
+        entry.resolve({ state: "sent", id: entry.id, seq });
+    }
+    const client = {
+        tables,
+        async query(op, args) {
+            return evaluate(op, args);
+        },
+        observe(op, args) {
+            let seen = -1;
+            let snapshot = { loading: true };
+            const subs = new Set();
+            const listener = () => { for (const s of subs)
+                s(); };
+            listeners.add(listener);
+            return {
+                getSnapshot() {
+                    if (seen !== version) {
+                        seen = version;
+                        snapshot = evaluate(op, args);
+                    }
+                    return snapshot;
+                },
+                subscribe(notify) { subs.add(notify); return () => subs.delete(notify); },
+                close() { listeners.delete(listener); subs.clear(); },
+            };
+        },
+        async mutate(op, args) {
+            const fn = options.ops.mutations[op.name];
+            const id = mockId();
+            if (!fn)
+                return { state: "failed", id, why: { code: "E_OP", family: "op", message: `unknown mutation ${op.name}` } };
+            if (link === "signed-out")
+                return { state: "failed", id, why: { code: "E_AUTH", family: "auth", message: "sign in to write" } };
+            const outcome = fn(tables, args, options.viewer, () => id);
+            if (isRefusal(outcome))
+                return { state: "failed", id, why: outcome };
+            const table = op.name.split(".")[0] ?? "";
+            for (const rowId of outcome) {
+                const row = tables[table]?.get(rowId);
+                if (row)
+                    row.pending = true;
+            }
+            bump();
+            if (link === "offline") {
+                // Durable admission without a server: the write stays pending until the link returns.
+                return await new Promise((resolve) => {
+                    queue.push({ id, touched: outcome, table, resolve: () => { } });
+                    resolve({ state: "pending", id });
+                });
+            }
+            return await new Promise((resolve) => {
+                const entry = { id, touched: outcome, table, resolve };
+                setTimeout(() => { settleOne(entry); bump(); }, delay);
+            });
+        },
+        link: () => link,
+        onLink(notify) { linkListeners.add(notify); return () => linkListeners.delete(notify); },
+        viewer: () => options.viewer,
+        async close() { listeners.clear(); linkListeners.clear(); },
+        setLink(next) {
+            link = next;
+            for (const l of linkListeners)
+                l(next);
+            if (next === "online")
+                void client.settle();
+            bump();
+        },
+        async settle() {
+            await new Promise((r) => setTimeout(r, delay));
+            while (queue.length > 0) {
+                const entry = queue.shift();
+                if (entry)
+                    settleOne(entry);
+            }
+            bump();
+        },
+    };
+    return client;
+}

package/dist/react.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { Client, Cursor, Link, Mutation, Principal, Query, Read, Write } from "./contract.ts";
+export declare function SnapbackProvider({ client, children }: {
+    client: Client;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useClient(): Client;
+/** One live read. Re-renders when the value changes; never throws. */
+export declare function useQuery<A, R>(op: Query<A, R>, args: A): Read<R>;
+export declare function usePage<A extends {
+    c?: Cursor | null;
+}, R extends readonly unknown[]>(op: Query<A, R>, args: Omit<A, "c">): {
+    items: R[number][];
+    hasMore: boolean;
+    read: Read<R>;
+    loadMore: () => void;
+};
+/** A write. `run` never throws; `last` is the most recent outcome. */
+export declare function useMutation<A, R>(op: Mutation<A, R>): {
+    run: (args: A) => Promise<Write>;
+    last: Write | undefined;
+    inFlight: boolean;
+};
+export declare function useLink(): Link;
+export declare function useViewer(): Principal | null;

package/dist/react.js

@@ -0,0 +1,113 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The React arm: one provider, five hooks, nothing a screen must reconcile.
+// Every hook returns a value from the card (contract.ts) and nothing else.
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { isReady } from "./contract.js";
+const ClientContext = createContext(null);
+export function SnapbackProvider({ client, children }) {
+    return _jsx(ClientContext.Provider, { value: client, children: children });
+}
+export function useClient() {
+    const client = useContext(ClientContext);
+    if (!client)
+        throw new Error("useClient: no <SnapbackProvider> above this component");
+    return client;
+}
+const LOADING = { loading: true };
+/** One live read. Re-renders when the value changes; never throws. */
+export function useQuery(op, args) {
+    const client = useClient();
+    const key = JSON.stringify(args);
+    const observed = useMemo(() => client.observe(op, args), [client, op, key]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => observed.close(), [observed]);
+    return useSyncExternalStore(observed.subscribe, observed.getSnapshot, () => LOADING);
+}
+/** A page resource: the pages a screen has asked for, concatenated, and a way to ask for one more. */
+class Pages {
+    client;
+    op;
+    args;
+    observed = [];
+    cursors = [null];
+    subs = new Set();
+    cache = null;
+    unsubscribe = [];
+    constructor(client, op, args) {
+        this.client = client;
+        this.op = op;
+        this.args = args;
+        this.open(null);
+    }
+    open(c) {
+        const observed = this.client.observe(this.op, { ...this.args, c });
+        this.observed.push(observed);
+        this.unsubscribe.push(observed.subscribe(() => this.notify()));
+    }
+    notify() { this.cache = null; for (const s of this.subs)
+        s(); }
+    subscribe = (notify) => { this.subs.add(notify); return () => { this.subs.delete(notify); }; };
+    getSnapshot = () => {
+        if (this.cache)
+            return this.cache;
+        const reads = this.observed.map((o) => o.getSnapshot());
+        const items = [];
+        let hasMore = false;
+        let last = LOADING;
+        for (const read of reads) {
+            last = read;
+            if (!isReady(read))
+                break;
+            items.push(...read.data);
+            hasMore = read.next != null;
+        }
+        this.cache = { items, hasMore, read: last };
+        return this.cache;
+    };
+    loadMore = () => {
+        const last = this.observed[this.observed.length - 1]?.getSnapshot();
+        if (!last || !isReady(last) || last.next == null)
+            return;
+        if (this.cursors.includes(last.next))
+            return;
+        this.cursors.push(last.next);
+        this.open(last.next);
+        this.notify();
+    };
+    close() { for (const u of this.unsubscribe)
+        u(); for (const o of this.observed)
+        o.close(); }
+}
+export function usePage(op, args) {
+    const client = useClient();
+    const key = JSON.stringify(args);
+    const pages = useMemo(() => new Pages(client, op, args), [client, op, key]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => () => pages.close(), [pages]);
+    const snapshot = useSyncExternalStore(pages.subscribe, pages.getSnapshot, pages.getSnapshot);
+    return { items: snapshot.items, hasMore: snapshot.hasMore, read: snapshot.read, loadMore: pages.loadMore };
+}
+/** A write. `run` never throws; `last` is the most recent outcome. */
+export function useMutation(op) {
+    const client = useClient();
+    const [last, setLast] = useState(undefined);
+    const [inFlight, setInFlight] = useState(false);
+    const alive = useRef(true);
+    useEffect(() => () => { alive.current = false; }, []);
+    const run = useCallback(async (args) => {
+        setInFlight(true);
+        const outcome = await client.mutate(op, args);
+        if (alive.current) {
+            setLast(outcome);
+            setInFlight(false);
+        }
+        return outcome;
+    }, [client, op]);
+    return { run, last, inFlight };
+}
+export function useLink() {
+    const client = useClient();
+    const subscribe = useCallback((notify) => client.onLink(() => notify()), [client]);
+    return useSyncExternalStore(subscribe, client.link, client.link);
+}
+export function useViewer() {
+    return useClient().viewer();
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "snapback4",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Snapback 4 client: the contract (the card), a labelled mock client, and React hooks. Week one of LLP 3000; nothing here talks to a server yet.",
+  "exports": {
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "import": "./dist/contract.js"
+    },
+    "./mock": {
+      "types": "./dist/mock.d.ts",
+      "import": "./dist/mock.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/expo/snapback.git",
+    "directory": "snapback4/packages/snapback4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}