@ternkit/tern 1.2.1 → 1.4.0

package/dist/goscript/index.svelte.d.ts

@@ -1,3 +1,5 @@
+import { applyPatch, type PatchOp } from './patch.js';
+export { applyPatch, type PatchOp };
 type Instance = {
     call(name: string, args: string): string | null;
     destroy(): void;
@@ -30,9 +32,38 @@ export declare function useGo(id: string, initial: Record<string, unknown>, runt
 declare global {
     var __tern_live_initial: ((id: string, props: string) => string) | undefined;
 }
-export interface LiveComponent extends GoComponent {
+/** A Func of a live component, as the markup sees it. */
+export interface LiveFunc<A extends unknown[] = unknown[], R = unknown> {
+    (...args: A): Promise<R>;
+    /** Whether a call is waiting for the server. */
+    readonly pending: boolean;
+    /** The last call's error message (from goscript.Fail), or null. */
+    readonly error: string | null;
+    /** Calls the Func, showing values for these state names until it returns. */
+    optimistic(values: Record<string, unknown>, ...args: A): Promise<R>;
+    /** A version that waits until calls stop for ms (default 200), for input events. */
+    debounce(ms?: number): (...args: A) => void;
+}
+export interface LiveComponent<S extends Record<string, unknown> = Record<string, unknown>> extends GoComponent {
+    readonly state: S;
     /** The server-rendered state, embedded in the page for hydration. */
     readonly stateScript: string;
+    /** Whether the page is connected to the server. */
+    readonly connected: boolean;
+    /** Whether any call is waiting for the server. */
+    readonly pending: boolean;
+    /** Why the component failed to mount (such as goscript Reject's message), or null. */
+    readonly error: string | null;
+    /** Whether the state has arrived; the markup renders once it has. */
+    readonly loaded: boolean;
+    /** Everything the parent passed, such as children snippets and onevent handlers. */
+    readonly props: Record<string, any>;
+    /** Bindable state: bind:value={live.bind.name} for a State declared with goscript.Bind. */
+    readonly bind: S;
+    /** Sets a State declared with goscript.Bind; the page shows value at once. */
+    set<K extends keyof S & string>(name: K, value: S[K]): Promise<void>;
+    /** The Func named name. */
+    fn<A extends unknown[] = unknown[], R = unknown>(name: string): LiveFunc<A, R>;
 }
 /**
  * Mounts a live Go component; code generated from <script lang="go" live>
@@ -41,4 +72,3 @@ export interface LiveComponent extends GoComponent {
  * /_tern/live, where its Go instance runs.
  */
 export declare function useLive(id: string, uid: string, props: () => Record<string, unknown>): LiveComponent;
-export {};

package/dist/goscript/index.svelte.js

@@ -1,7 +1,10 @@
 // The browser side of the experimental <script lang="go">: loads the app's
 // Go WebAssembly module once, mounts a Go instance per component, and keeps
 // the values Go publishes in Svelte state. See docs/experimental-go-script.md.
+import { untrack } from 'svelte';
 import { getBase } from '../runtime/base.js';
+import { applyPatch } from './patch.js';
+export { applyPatch };
 let loading = null;
 function load(runtime, wasm) {
     loading ??= (async () => {
@@ -65,6 +68,87 @@ export function useGo(id, initial, runtime, wasm, props) {
         }
     };
 }
+function clone(v) {
+    return v === undefined ? v : JSON.parse(JSON.stringify(v));
+}
+/** The browser side of one live component instance. */
+class LiveInstance {
+    id;
+    props;
+    /** What the markup shows: the server's values, or optimistic ones while a call is pending. */
+    state;
+    /** The server's values, as last sent. */
+    #server;
+    #holds = new Map();
+    calls = new Map();
+    pendingCalls = $state({});
+    errors = $state({});
+    error = $state(null);
+    /** Whether the component has its state: from the server render, or the first message. */
+    loaded = $state(false);
+    mounted = false;
+    constructor(id, props, initial) {
+        this.id = id;
+        this.props = props;
+        const { __tern_error: error, ...values } = initial ?? {};
+        this.state = $state(clone(values));
+        this.#server = clone(values);
+        this.loaded = initial !== null;
+        if (typeof error === 'string')
+            this.error = error;
+    }
+    apply(m) {
+        this.loaded = true;
+        for (const [name, v] of Object.entries(m.set ?? {})) {
+            this.#server[name] = clone(v);
+            if (!this.#holds.has(name))
+                this.state[name] = v;
+        }
+        for (const [name, ops] of Object.entries(m.patch ?? {})) {
+            this.#server[name] = applyPatch(this.#server[name], clone(ops));
+            if (!this.#holds.has(name))
+                this.state[name] = applyPatch(this.state[name], ops);
+        }
+    }
+    /** Shows value for name until the operation holding it settles. */
+    hold(name, value) {
+        this.#holds.set(name, (this.#holds.get(name) ?? 0) + 1);
+        this.state[name] = value;
+    }
+    release(names) {
+        for (const name of names) {
+            const n = (this.#holds.get(name) ?? 1) - 1;
+            if (n > 0) {
+                this.#holds.set(name, n);
+                continue;
+            }
+            this.#holds.delete(name);
+            this.state[name] = clone(this.#server[name]);
+        }
+    }
+    begin(seq, call) {
+        this.calls.set(seq, call);
+        this.pendingCalls[call.name] = (this.pendingCalls[call.name] ?? 0) + 1;
+    }
+    settle(seq, value, error) {
+        const call = this.calls.get(seq);
+        if (!call)
+            return;
+        this.calls.delete(seq);
+        this.pendingCalls[call.name] = (this.pendingCalls[call.name] ?? 1) - 1;
+        this.release(call.holds);
+        this.errors[call.name] = error ?? null;
+        if (error)
+            call.reject(new Error(error));
+        else
+            call.resolve(value);
+    }
+    /** The values to restore after reconnecting to a new server process. */
+    snapshot() {
+        return $state.snapshot(this.state);
+    }
+}
+const status = $state({ connected: false });
 class LiveConnection {
     #ws = null;
     #refs = new Map();
@@ -76,6 +160,12 @@ class LiveConnection {
     constructor(url) {
         this.#url = url;
     }
+    #mountMessage(ref, r) {
+        const props = untrack(() => r.props());
+        // After a reconnect, the server has forgotten the instance: values
+        // declared with Bind or Restore come back from what the page shows.
+        return JSON.stringify({ op: 'mount', ref, id: r.id, props, restore: r.mounted ? r.snapshot() : undefined });
+    }
     #connect() {
         const u = new URL(this.#url, location.href);
         u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
@@ -83,40 +173,71 @@ class LiveConnection {
         this.#ws = ws;
         ws.onopen = () => {
             this.#attempt = 0;
-            // After a reconnect, the server has forgotten every instance.
-            for (const [ref, r] of this.#refs)
-                ws.send(JSON.stringify({ op: 'mount', ref, id: r.id, props: r.props() }));
-            for (const m of this.#queue.splice(0))
-                ws.send(m);
+            status.connected = true;
+            for (const [ref, r] of this.#refs) {
+                ws.send(this.#mountMessage(ref, r));
+                r.mounted = true;
+            }
+            for (const m of this.#queue.splice(0)) {
+                if (m.ref !== undefined && !this.#refs.has(m.ref))
+                    continue;
+                ws.send(m.data);
+                if (m.seq !== undefined)
+                    this.#markSent(m.ref, m.seq);
+            }
         };
         ws.onmessage = (e) => {
             const m = JSON.parse(e.data);
             const r = this.#refs.get(m.ref);
             if (!r)
                 return;
-            if (m.op === 'state' && m.name)
-                r.state[m.name] = m.value;
-            else if (m.op === 'result') {
-                r.pending.get(m.seq)?.(m.error ? Promise.reject(new Error(m.error)) : m.value);
-                r.pending.delete(m.seq);
+            if (m.op === 'state')
+                r.apply(m);
+            else if (m.op === 'result')
+                r.settle(m.seq, m.value, m.error);
+            else if (m.op === 'event') {
+                const handler = untrack(() => r.props())['on' + m.name];
+                if (typeof handler === 'function')
+                    handler(m.value);
             }
-            else if (m.op === 'error')
+            else if (m.op === 'error') {
+                r.error = m.error ?? 'error';
+                r.loaded = true;
                 console.error(`[tern] live component ${r.id}: ${m.error}`);
+            }
         };
         ws.onclose = () => {
-            this.#ws = null;
+            if (this.#ws === ws)
+                this.#ws = null;
+            status.connected = false;
+            // Calls that reached the old connection have no answer coming.
+            for (const r of this.#refs.values()) {
+                for (const [seq, call] of r.calls)
+                    if (call.sent)
+                        r.settle(seq, undefined, 'connection lost');
+            }
             if (this.#refs.size === 0)
                 return;
-            const delay = Math.min(10_000, 300 * 2 ** this.#attempt++);
-            setTimeout(() => this.#refs.size && this.#connect(), delay);
+            const delay = Math.min(10_000, 250 * 2 ** this.#attempt++) * (0.75 + Math.random() / 2);
+            setTimeout(() => this.#refs.size && !this.#ws && this.#connect(), delay);
         };
     }
+    #markSent(ref, seq) {
+        const call = this.#refs.get(ref)?.calls.get(seq);
+        if (call)
+            call.sent = true;
+    }
     #send(m) {
         const data = JSON.stringify(m);
-        if (this.#ws?.readyState === WebSocket.OPEN)
+        const seq = m.seq;
+        const ref = m.ref;
+        if (this.#ws?.readyState === WebSocket.OPEN) {
             this.#ws.send(data);
+            if (seq !== undefined)
+                this.#markSent(ref, seq);
+        }
         else {
-            this.#queue.push(data);
+            this.#queue.push({ data, seq, ref });
             if (!this.#ws)
                 this.#connect();
         }
@@ -124,7 +245,12 @@ class LiveConnection {
     mount(r) {
         const ref = this.#nextRef++;
         this.#refs.set(ref, r);
-        this.#send({ op: 'mount', ref, id: r.id, props: r.props() });
+        if (this.#ws?.readyState === WebSocket.OPEN) {
+            this.#ws.send(this.#mountMessage(ref, r));
+            r.mounted = true;
+        }
+        else if (!this.#ws)
+            this.#connect();
         return ref;
     }
     unmount(ref) {
@@ -132,19 +258,44 @@ class LiveConnection {
         if (this.#ws?.readyState === WebSocket.OPEN)
             this.#ws.send(JSON.stringify({ op: 'unmount', ref }));
         if (this.#refs.size === 0) {
-            this.#ws?.close(1000);
+            const ws = this.#ws;
             this.#ws = null;
+            this.#queue = [];
+            ws?.close(1000);
         }
     }
-    call(ref, name, args) {
+    props(ref, props) {
+        this.#send({ op: 'props', ref, props });
+    }
+    call(ref, name, args, optimistic) {
         const r = this.#refs.get(ref);
         if (!r)
-            return Promise.resolve(undefined);
+            return Promise.reject(new Error('not mounted'));
         const seq = this.#seq++;
-        return new Promise((resolve) => {
-            r.pending.set(seq, resolve);
-            this.#send({ op: 'call', ref, seq, name, args });
+        const holds = Object.keys(optimistic ?? {});
+        for (const k of holds)
+            r.hold(k, optimistic[k]);
+        const p = new Promise((resolve, reject) => {
+            r.begin(seq, { resolve, reject, name, holds, sent: false });
         });
+        this.#send({ op: 'call', ref, seq, name, args });
+        // The error is also in fn.error; don't report unawaited calls as
+        // unhandled rejections.
+        p.catch(() => { });
+        return p;
+    }
+    set(ref, name, value) {
+        const r = this.#refs.get(ref);
+        if (!r)
+            return Promise.reject(new Error('not mounted'));
+        const seq = this.#seq++;
+        r.hold(name, value);
+        const p = new Promise((resolve, reject) => {
+            r.begin(seq, { resolve, reject, name: '$set:' + name, holds: [name], sent: false });
+        });
+        this.#send({ op: 'set', ref, seq, name, value: $state.snapshot(value) });
+        p.catch(() => { });
+        return p;
     }
 }
 let connection = null;
@@ -159,7 +310,9 @@ function escapeJSON(s) {
  */
 export function useLive(id, uid, props) {
     const elementID = `tern-live-${uid}`;
-    let initial = {};
+    // After a client-side navigation there is no server-rendered state: the
+    // markup waits for the first message (see the preprocessor).
+    let initial = null;
     let stateScript = '';
     if (typeof window === 'undefined') {
         const raw = globalThis.__tern_live_initial?.(id, JSON.stringify(props())) ?? '{}';
@@ -173,14 +326,13 @@ export function useLive(id, uid, props) {
             stateScript = el.outerHTML;
         }
     }
-    const state = $state(initial);
+    const inst = new LiveInstance(id, props, initial);
     let ref = 0;
     let ready = $state(false);
     if (typeof window !== 'undefined') {
         $effect(() => {
             connection ??= new LiveConnection(`${getBase()}/_tern/live`);
-            const live = { id, props, state, pending: new Map() };
-            ref = connection.mount(live);
+            ref = connection.mount(inst);
             ready = true;
             return () => {
                 connection?.unmount(ref);
@@ -188,17 +340,91 @@ export function useLive(id, uid, props) {
                 ready = false;
             };
         });
+        // New props from the parent go to the server without remounting.
+        let sent = JSON.stringify(untrack(props));
+        $effect(() => {
+            const next = JSON.stringify(props());
+            if (next !== sent && ref) {
+                sent = next;
+                connection.props(ref, JSON.parse(next));
+            }
+        });
     }
+    const call = (name, args, optimistic) => {
+        if (!ref || !connection)
+            return Promise.reject(new Error('not mounted'));
+        return connection.call(ref, name, args.map(toArg), optimistic);
+    };
+    const funcs = new Map();
+    const fn = (name) => {
+        let f = funcs.get(name);
+        if (f)
+            return f;
+        const debounced = new Map();
+        f = Object.assign((...args) => call(name, args), {
+            optimistic: (values, ...args) => call(name, args, values),
+            debounce: (ms = 200) => {
+                let d = debounced.get(ms);
+                if (!d) {
+                    let timer;
+                    d = (...args) => {
+                        const converted = args.map(toArg); // read input values now
+                        clearTimeout(timer);
+                        timer = setTimeout(() => void call(name, converted), ms);
+                    };
+                    debounced.set(ms, d);
+                }
+                return d;
+            }
+        });
+        Object.defineProperties(f, {
+            pending: { get: () => (inst.pendingCalls[name] ?? 0) > 0 },
+            error: { get: () => inst.errors[name] ?? null }
+        });
+        funcs.set(name, f);
+        return f;
+    };
+    const set = (name, value) => {
+        if (!ref || !connection) {
+            inst.state[name] = value;
+            return Promise.resolve();
+        }
+        return connection.set(ref, name, value).then(() => undefined);
+    };
+    const bind = new Proxy({}, {
+        get: (_, name) => (typeof name === 'string' ? inst.state[name] : undefined),
+        set: (_, name, value) => {
+            if (typeof name === 'string')
+                void set(name, value);
+            return true;
+        }
+    });
     return {
-        state,
+        state: inst.state,
         stateScript,
+        bind,
+        fn: fn,
+        set: set,
         get ready() {
             return ready;
         },
+        get props() {
+            return props();
+        },
+        get connected() {
+            return status.connected;
+        },
+        get pending() {
+            return Object.values(inst.pendingCalls).some((n) => n > 0);
+        },
+        get error() {
+            return inst.error;
+        },
+        get loaded() {
+            return inst.loaded;
+        },
         call(name, ...args) {
-            if (!ref || !connection)
-                return undefined;
-            return connection.call(ref, name, args.map(toArg));
+            return call(name, args);
         }
     };
 }

package/dist/goscript/patch.d.ts

@@ -0,0 +1,6 @@
+type Key = string | number;
+/** One patch operation from the server. */
+export type PatchOp = ['s', Key[], unknown] | ['d', Key[]] | ['a', Key[], number, number, unknown[]];
+/** Applies a patch to root and returns the new root. */
+export declare function applyPatch(root: unknown, ops: PatchOp[]): unknown;
+export {};

package/dist/goscript/patch.js

@@ -0,0 +1,25 @@
+// Applying the patches live components send; see internal/jsondiff.
+/** Applies a patch to root and returns the new root. */
+export function applyPatch(root, ops) {
+    for (const op of ops) {
+        const path = op[1];
+        if (path.length === 0) {
+            if (op[0] === 's')
+                root = op[2];
+            else if (op[0] === 'a')
+                root.splice(op[2], op[3], ...op[4]);
+            continue;
+        }
+        let parent = root;
+        for (const k of path.slice(0, -1))
+            parent = parent[k];
+        const last = path[path.length - 1];
+        if (op[0] === 's')
+            parent[last] = op[2];
+        else if (op[0] === 'd')
+            delete parent[last];
+        else
+            parent[last].splice(op[2], op[3], ...op[4]);
+    }
+    return root;
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { goto, invalidate, invalidateAll, preloadData, applyAction } from './run
 export { beforeNavigate, onNavigate, afterNavigate } from './runtime/navigation.js';
 export type { BeforeNavigateEvent, OnNavigateEvent } from './runtime/navigation.js';
 export { enhance } from './runtime/forms.js';
+export { validate, checkField, type FormField, type FormErrors } from './runtime/validate.js';
 export type { SubmitFunction, SubmitInput, SubmitResult } from './runtime/forms.js';
 export type { ActionResult, GotoOptions, Navigation, NavigationTarget, NavigationType } from './runtime/types.js';
 export { ApiError, createApi } from './runtime/api.js';
@@ -28,4 +29,4 @@ export type { MessageKey } from './runtime/i18n.svelte.js';
 export interface Messages {
 }
 /** The version of the Tern client runtime. */
-export declare const VERSION = "1.2.1";
+export declare const VERSION = "1.4.0";

package/dist/index.js

@@ -11,9 +11,10 @@ export { page, navigating, env } from './runtime/state.svelte.js';
 export { goto, invalidate, invalidateAll, preloadData, applyAction } from './runtime/router.svelte.js';
 export { beforeNavigate, onNavigate, afterNavigate } from './runtime/navigation.js';
 export { enhance } from './runtime/forms.js';
+export { validate, checkField } from './runtime/validate.js';
 export { ApiError, createApi } from './runtime/api.js';
 export { stream, socket, EventStreamState, SocketState } from './runtime/realtime.svelte.js';
 export { default as Image } from './image/Image.svelte';
 export { t, i18n, setLocale } from './runtime/i18n.svelte.js';
 /** The version of the Tern client runtime. */
-export const VERSION = '1.2.1';
+export const VERSION = '1.4.0';

package/dist/runtime/validate.d.ts

@@ -0,0 +1,31 @@
+/** A form field's rules, as tern gen writes them. */
+export interface FormField<Name extends string = string> {
+    name: Name;
+    label: string;
+    kind: 'string' | 'int' | 'float' | 'bool' | 'date' | 'datetime' | 'strings';
+    required?: boolean;
+    rules?: {
+        name: string;
+        arg?: string;
+    }[];
+    message?: string;
+    secret?: boolean;
+}
+/** Errors by field name; empty when the form is valid. */
+export type FormErrors<Name extends string = string> = Partial<Record<Name, string>>;
+/** Reads a date or a date and time as Go does, or null. Times without a zone are UTC. */
+export declare function parseFormTime(kind: 'date' | 'datetime', s: string): number | null;
+/**
+ * Returns why a field's values are invalid, or "". values are its posted
+ * values; other reads another field's first value, for same=.
+ */
+export declare function checkField(f: FormField, values: string[], other?: (name: string) => string, labelOf?: (name: string) => string): string;
+/**
+ * Checks a form against its rules, as kit.FormAction will on the server:
+ *
+ * ```ts
+ * import { forms } from './$forms';
+ * const errors = validate(forms.create, new FormData(formElement));
+ * ```
+ */
+export declare function validate<Name extends string>(fields: FormField<Name>[], data: FormData | Record<string, unknown>): FormErrors<Name>;