@ternkit/tern 1.1.0 → 1.2.1

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

@@ -0,0 +1,44 @@
+type Instance = {
+    call(name: string, args: string): string | null;
+    destroy(): void;
+};
+type GoGlobal = {
+    mount(id: string, props: string, emit: (name: string, value: string) => void): Instance | Error;
+};
+declare global {
+    var __tern_go: GoGlobal | undefined;
+    var __tern_go_ready: (() => void) | undefined;
+    var Go: (new () => {
+        importObject: WebAssembly.Imports;
+        run(instance: WebAssembly.Instance): Promise<void>;
+    }) | undefined;
+}
+export interface GoComponent {
+    /** The values Go published with State and Derived. */
+    readonly state: Record<string, unknown>;
+    /** Whether the Go instance is running; until then the state is the build-time initial state. */
+    readonly ready: boolean;
+    /** Calls a Func; returns its result, or undefined before the module loads. */
+    call(name: string, ...args: unknown[]): unknown;
+}
+/**
+ * Mounts a Go component; code generated from <script lang="go"> calls it.
+ * initial is the state Setup produced at build time, so server rendering and
+ * the first paint match what Go will compute.
+ */
+export declare function useGo(id: string, initial: Record<string, unknown>, runtime: () => Promise<unknown>, wasm: string, props: () => Record<string, unknown>): GoComponent;
+declare global {
+    var __tern_live_initial: ((id: string, props: string) => string) | undefined;
+}
+export interface LiveComponent extends GoComponent {
+    /** The server-rendered state, embedded in the page for hydration. */
+    readonly stateScript: string;
+}
+/**
+ * Mounts a live Go component; code generated from <script lang="go" live>
+ * calls it. On the server, Setup runs in Go for the render, and the state
+ * goes into the page; in the browser, the component connects to
+ * /_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

@@ -0,0 +1,204 @@
+// 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 { getBase } from '../runtime/base.js';
+let loading = null;
+function load(runtime, wasm) {
+    loading ??= (async () => {
+        await runtime(); // defines globalThis.Go
+        const go = new globalThis.Go();
+        const ready = new Promise((resolve) => (globalThis.__tern_go_ready = resolve));
+        const res = await WebAssembly.instantiateStreaming(fetch(wasm), go.importObject);
+        void go.run(res.instance);
+        await ready;
+        return globalThis.__tern_go;
+    })();
+    return loading;
+}
+function toArg(a) {
+    if (typeof Event !== 'undefined' && a instanceof Event) {
+        const t = a.target;
+        return { type: a.type, value: t?.value ?? '', checked: !!t?.checked, key: a.key ?? '' };
+    }
+    return a;
+}
+/**
+ * Mounts a Go component; code generated from <script lang="go"> calls it.
+ * initial is the state Setup produced at build time, so server rendering and
+ * the first paint match what Go will compute.
+ */
+export function useGo(id, initial, runtime, wasm, props) {
+    const state = $state({ ...initial });
+    let instance = null;
+    let ready = $state(false);
+    if (typeof window !== 'undefined') {
+        $effect(() => {
+            let alive = true;
+            const json = JSON.stringify(props());
+            void load(runtime, wasm).then((go) => {
+                if (!alive)
+                    return;
+                const m = go.mount(id, json, (name, value) => (state[name] = JSON.parse(value)));
+                if (m instanceof Error)
+                    throw m;
+                instance = m;
+                ready = true;
+            });
+            return () => {
+                alive = false;
+                instance?.destroy();
+                instance = null;
+                ready = false;
+            };
+        });
+    }
+    return {
+        state,
+        get ready() {
+            return ready;
+        },
+        call(name, ...args) {
+            if (!instance)
+                return undefined;
+            const out = instance.call(name, JSON.stringify(args.map(toArg)));
+            return out === null ? undefined : JSON.parse(out);
+        }
+    };
+}
+class LiveConnection {
+    #ws = null;
+    #refs = new Map();
+    #queue = [];
+    #nextRef = 1;
+    #seq = 1;
+    #attempt = 0;
+    #url;
+    constructor(url) {
+        this.#url = url;
+    }
+    #connect() {
+        const u = new URL(this.#url, location.href);
+        u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+        const ws = new WebSocket(u);
+        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);
+        };
+        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);
+            }
+            else if (m.op === 'error')
+                console.error(`[tern] live component ${r.id}: ${m.error}`);
+        };
+        ws.onclose = () => {
+            this.#ws = null;
+            if (this.#refs.size === 0)
+                return;
+            const delay = Math.min(10_000, 300 * 2 ** this.#attempt++);
+            setTimeout(() => this.#refs.size && this.#connect(), delay);
+        };
+    }
+    #send(m) {
+        const data = JSON.stringify(m);
+        if (this.#ws?.readyState === WebSocket.OPEN)
+            this.#ws.send(data);
+        else {
+            this.#queue.push(data);
+            if (!this.#ws)
+                this.#connect();
+        }
+    }
+    mount(r) {
+        const ref = this.#nextRef++;
+        this.#refs.set(ref, r);
+        this.#send({ op: 'mount', ref, id: r.id, props: r.props() });
+        return ref;
+    }
+    unmount(ref) {
+        this.#refs.delete(ref);
+        if (this.#ws?.readyState === WebSocket.OPEN)
+            this.#ws.send(JSON.stringify({ op: 'unmount', ref }));
+        if (this.#refs.size === 0) {
+            this.#ws?.close(1000);
+            this.#ws = null;
+        }
+    }
+    call(ref, name, args) {
+        const r = this.#refs.get(ref);
+        if (!r)
+            return Promise.resolve(undefined);
+        const seq = this.#seq++;
+        return new Promise((resolve) => {
+            r.pending.set(seq, resolve);
+            this.#send({ op: 'call', ref, seq, name, args });
+        });
+    }
+}
+let connection = null;
+function escapeJSON(s) {
+    return s.replace(/</g, '\\u003c');
+}
+/**
+ * Mounts a live Go component; code generated from <script lang="go" live>
+ * calls it. On the server, Setup runs in Go for the render, and the state
+ * goes into the page; in the browser, the component connects to
+ * /_tern/live, where its Go instance runs.
+ */
+export function useLive(id, uid, props) {
+    const elementID = `tern-live-${uid}`;
+    let initial = {};
+    let stateScript = '';
+    if (typeof window === 'undefined') {
+        const raw = globalThis.__tern_live_initial?.(id, JSON.stringify(props())) ?? '{}';
+        initial = JSON.parse(raw);
+        stateScript = `<script type="application/json" id="${elementID}">${escapeJSON(raw)}</script>`;
+    }
+    else {
+        const el = document.getElementById(elementID);
+        if (el) {
+            initial = JSON.parse(el.textContent || '{}');
+            stateScript = el.outerHTML;
+        }
+    }
+    const state = $state(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);
+            ready = true;
+            return () => {
+                connection?.unmount(ref);
+                ref = 0;
+                ready = false;
+            };
+        });
+    }
+    return {
+        state,
+        stateScript,
+        get ready() {
+            return ready;
+        },
+        call(name, ...args) {
+            if (!ref || !connection)
+                return undefined;
+            return connection.call(ref, name, args.map(toArg));
+        }
+    };
+}

package/dist/image/Image.svelte

@@ -1,12 +1,21 @@
 <script lang="ts">
 	import type { HTMLImgAttributes } from 'svelte/elements';
+	import { getBase } from '../runtime/base.js';
 	import type { Picture } from './types.js';
 
 	interface Props extends Omit<HTMLImgAttributes, 'src' | 'srcset' | 'width' | 'height'> {
-		/** The image, from `import picture from './photo.jpg?image'`. */
-		src: Picture;
+		/**
+		 * The image: from `import picture from './photo.jpg?image'`, or the URL
+		 * of a remote image, which the images plugin resizes (give its width
+		 * and height then).
+		 */
+		src: Picture | string;
 		/** Describes the image; use "" for decorative images. */
 		alt: string;
+		/** The width the image is shown at, in CSS pixels; required for URLs. */
+		width?: number;
+		/** The height for that width; required for URLs. */
+		height?: number;
 		/**
 		 * How wide the image is displayed, so the browser picks the right file,
 		 * such as "(min-width: 768px) 50vw, 100vw". Defaults to its full width.
@@ -16,20 +25,34 @@
 		priority?: boolean;
 	}
 
-	let { src, alt, sizes, priority = false, ...rest }: Props = $props();
-	const fallbackSizes = $derived(`(min-width: ${src.width}px) ${src.width}px, 100vw`);
+	let { src, alt, width, height, sizes, priority = false, ...rest }: Props = $props();
+
+	// The widths the images plugin serves (plugins/images.Widths).
+	const widths = [64, 128, 256, 384, 640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+
+	const picture = $derived.by((): Picture => {
+		if (typeof src !== 'string') return src;
+		const w = width ?? 1200;
+		const h = height ?? Math.round(w * 0.75);
+		// Up to twice the shown width, for high-density screens.
+		const chosen = widths.filter((x) => x <= w * 2);
+		if (!chosen.length || chosen.at(-1)! < w * 2) chosen.push(widths.find((x) => x >= w * 2) ?? widths.at(-1)!);
+		const url = (x: number) => `${getBase()}/_tern/image?url=${encodeURIComponent(src as string)}&w=${x}`;
+		return { src: url(chosen.find((x) => x >= w) ?? chosen.at(-1)!), width: w, height: h, srcset: chosen.map((x) => `${url(x)} ${x}w`).join(', '), sources: [] };
+	});
+	const fallbackSizes = $derived(`(min-width: ${picture.width}px) ${picture.width}px, 100vw`);
 </script>
 
 <picture>
-	{#each src.sources as source (source.type)}
+	{#each picture.sources as source (source.type)}
 		<source type={source.type} srcset={source.srcset} sizes={sizes ?? fallbackSizes} />
 	{/each}
 	<img
-		src={src.src}
-		srcset={src.srcset}
+		src={picture.src}
+		srcset={picture.srcset}
 		sizes={sizes ?? fallbackSizes}
-		width={src.width}
-		height={src.height}
+		width={picture.width}
+		height={picture.height}
 		{alt}
 		loading={priority ? 'eager' : 'lazy'}
 		fetchpriority={priority ? 'high' : undefined}

package/dist/image/Image.svelte.d.ts

@@ -1,10 +1,18 @@
 import type { HTMLImgAttributes } from 'svelte/elements';
 import type { Picture } from './types.js';
 interface Props extends Omit<HTMLImgAttributes, 'src' | 'srcset' | 'width' | 'height'> {
-    /** The image, from `import picture from './photo.jpg?image'`. */
-    src: Picture;
+    /**
+     * The image: from `import picture from './photo.jpg?image'`, or the URL
+     * of a remote image, which the images plugin resizes (give its width
+     * and height then).
+     */
+    src: Picture | string;
     /** Describes the image; use "" for decorative images. */
     alt: string;
+    /** The width the image is shown at, in CSS pixels; required for URLs. */
+    width?: number;
+    /** The height for that width; required for URLs. */
+    height?: number;
     /**
      * How wide the image is displayed, so the browser picks the right file,
      * such as "(min-width: 768px) 50vw, 100vw". Defaults to its full width.

package/dist/index.d.ts

@@ -14,6 +14,9 @@ export type { BeforeNavigateEvent, OnNavigateEvent } from './runtime/navigation.
 export { enhance } from './runtime/forms.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';
+export { stream, socket, EventStreamState, SocketState } from './runtime/realtime.svelte.js';
+export type { ConnectionStatus, StreamOptions, SocketOptions } from './runtime/realtime.svelte.js';
 export { default as Image } from './image/Image.svelte';
 export type { Picture } from './image/types.js';
 export { t, i18n, setLocale } from './runtime/i18n.svelte.js';
@@ -25,4 +28,4 @@ export type { MessageKey } from './runtime/i18n.svelte.js';
 export interface Messages {
 }
 /** The version of the Tern client runtime. */
-export declare const VERSION = "1.1.0";
+export declare const VERSION = "1.2.1";

package/dist/index.js

@@ -11,7 +11,9 @@ 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 { 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.1.0';
+export const VERSION = '1.2.1';

package/dist/runtime/api.d.ts

@@ -0,0 +1,18 @@
+/** An error answer from a typed endpoint. */
+export declare class ApiError extends Error {
+    /** The HTTP status. */
+    readonly status: number;
+    /** The decoded response body, if it was JSON. */
+    readonly body: unknown;
+    constructor(status: number, message: string, body: unknown);
+}
+type Options = {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+};
+/** Creates the $api client from $routes' route(); generated code calls it. */
+export declare function createApi(route: (pattern: string, params?: Record<string, unknown>) => string): (endpoint: string, options?: Options) => Promise<unknown>;
+export {};

package/dist/runtime/api.js

@@ -0,0 +1,55 @@
+/** An error answer from a typed endpoint. */
+export class ApiError extends Error {
+    /** The HTTP status. */
+    status;
+    /** The decoded response body, if it was JSON. */
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Creates the $api client from $routes' route(); generated code calls it. */
+export function createApi(route) {
+    return async function api(endpoint, options = {}) {
+        const space = endpoint.indexOf(' ');
+        const method = endpoint.slice(0, space);
+        let url = route(endpoint.slice(space + 1), options.params ?? {});
+        const headers = { Accept: 'application/json' };
+        const init = { method, headers, credentials: 'same-origin', signal: options.signal };
+        if (method === 'GET' || method === 'HEAD' || method === 'DELETE') {
+            const q = new URLSearchParams();
+            for (const [k, v] of Object.entries(options.query ?? {})) {
+                if (v === undefined || v === null)
+                    continue;
+                for (const item of Array.isArray(v) ? v : [v])
+                    q.append(k, item instanceof Date ? item.toISOString() : String(item));
+            }
+            const qs = q.toString();
+            if (qs)
+                url += '?' + qs;
+        }
+        else {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body ?? {});
+        }
+        const res = await (options.fetch ?? fetch)(url, init);
+        const text = await res.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        if (!res.ok) {
+            const message = data?.message ?? res.statusText;
+            throw new ApiError(res.status, message, data);
+        }
+        return data;
+    };
+}

package/dist/runtime/base.d.ts

@@ -0,0 +1,2 @@
+export declare function setBase(b: string): void;
+export declare function getBase(): string;

package/dist/runtime/base.js

@@ -0,0 +1,10 @@
+// The app's base path, for components that build URLs outside $routes
+// (such as <Image>). The router sets it in the browser and the renderer on
+// the server, so both render the same URLs.
+let base = '';
+export function setBase(b) {
+    base = b;
+}
+export function getBase() {
+    return base;
+}

package/dist/runtime/realtime.svelte.d.ts

@@ -0,0 +1,78 @@
+export type ConnectionStatus = 'connecting' | 'open' | 'closed';
+export interface StreamOptions<T> {
+    /** Event names to listen for. The default is the unnamed "message" event. */
+    events?: string[];
+    /** The value of current before the first event, such as data from a load. */
+    initial?: T;
+    /** Called for each event, with its decoded data and name. */
+    onMessage?: (data: T, event: string) => void;
+    /** Send cookies to another origin. */
+    withCredentials?: boolean;
+}
+/** A server-sent event stream; see stream(). */
+export declare class EventStreamState<T> {
+    #private;
+    /** The data of the latest event, decoded from JSON when it is JSON. */
+    current: T | undefined;
+    /** The connection's status. The browser reconnects by itself after errors. */
+    status: ConnectionStatus;
+    constructor(url: string, options?: StreamOptions<T>);
+    /** Closes the stream. Streams created in a component close with it. */
+    close(): void;
+}
+/**
+ * Subscribes to server-sent events from an endpoint that uses
+ * ctx.EventStream or realtime.Stream:
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { stream } from '@ternkit/tern';
+ *   let { data } = $props();
+ *   const monitors = stream<Monitor[]>('/api/monitors/events', { events: ['monitors'], initial: data.monitors });
+ * </script>
+ *
+ * {#each monitors.current ?? [] as m}…{/each}
+ * ```
+ *
+ * During server rendering it does not connect and current is the initial
+ * value. Created in a component, it closes when the component is destroyed.
+ */
+export declare function stream<T = unknown>(url: string, options?: StreamOptions<T>): EventStreamState<T>;
+export interface SocketOptions<In> {
+    /** Called for each message, decoded from JSON when it is JSON. */
+    onMessage?: (message: In) => void;
+    /** WebSocket subprotocols. */
+    protocols?: string[];
+    /** Reconnect with backoff after the connection drops. The default is true. */
+    reconnect?: boolean;
+}
+/** A WebSocket connection; see socket(). */
+export declare class SocketState<In = unknown, Out = unknown> {
+    #private;
+    /** The latest message received. */
+    last: In | undefined;
+    /** The connection's status. */
+    status: ConnectionStatus;
+    constructor(url: string, options?: SocketOptions<In>);
+    /** Sends a message as JSON (strings as is). Messages sent while connecting are queued. */
+    send(message: Out): void;
+    /** Closes the connection. Sockets created in a component close with it. */
+    close(): void;
+}
+/**
+ * Opens a WebSocket to an endpoint that uses ctx.WebSocket, with JSON
+ * messages and automatic reconnection:
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { socket } from '@ternkit/tern';
+ *   const chat = socket<ChatMessage, { text: string }>('/api/chat', { onMessage: (m) => messages.push(m) });
+ * </script>
+ *
+ * <button onclick={() => chat.send({ text })}>Send</button>
+ * ```
+ *
+ * It does not connect during server rendering. Created in a component, it
+ * closes when the component is destroyed.
+ */
+export declare function socket<In = unknown, Out = unknown>(url: string, options?: SocketOptions<In>): SocketState<In, Out>;