@ternkit/tern 1.0.0 → 1.2.0

package/dist/runtime/format.js

@@ -0,0 +1,279 @@
+// Message formatting for i18n. This mirrors internal/i18n in Go exactly:
+// both are tested against internal/i18n/testdata/cases.json, so the server
+// and the browser produce the same text and hydration matches.
+const cache = new Map();
+/** Formats one message in the given locale. */
+export function format(locale, message, params = {}) {
+    let nodes = cache.get(message);
+    if (nodes === undefined) {
+        try {
+            nodes = parse(message);
+        }
+        catch {
+            nodes = null;
+        }
+        cache.set(message, nodes);
+    }
+    if (!nodes)
+        return message;
+    return render(nodes, locale, params, undefined);
+}
+function render(nodes, locale, params, hash) {
+    let out = '';
+    for (const n of nodes) {
+        switch (n.type) {
+            case 'text':
+                out += n.text;
+                break;
+            case 'hash':
+                out += hash === undefined ? '#' : formatNumber(hash);
+                break;
+            case 'arg':
+                out += n.name in params ? String(params[n.name]) : `{${n.name}}`;
+                break;
+            case 'plural': {
+                const num = Number(params[n.name] ?? 0) || 0;
+                const body = n.options[`=${formatNumber(num)}`] ?? n.options[pluralCategory(locale, num)] ?? n.options.other;
+                out += render(body, locale, params, num);
+                break;
+            }
+            case 'select': {
+                const body = n.options[String(params[n.name])] ?? n.options.other;
+                out += render(body, locale, params, hash);
+            }
+        }
+    }
+    return out;
+}
+function formatNumber(n) {
+    return String(n);
+}
+export function parse(message) {
+    const p = { s: [...message], i: 0 };
+    const nodes = parseNodes(p, false, false);
+    if (p.i < p.s.length)
+        throw new Error(`unexpected '}' at ${p.i}`);
+    return nodes;
+}
+function parseNodes(p, inBranch, plural) {
+    const out = [];
+    let text = '';
+    const flush = () => {
+        if (text)
+            out.push({ type: 'text', text });
+        text = '';
+    };
+    while (p.i < p.s.length) {
+        const c = p.s[p.i];
+        if (c === "'") {
+            const next = p.s[p.i + 1];
+            if (next === "'") {
+                text += "'";
+                p.i += 2;
+                continue;
+            }
+            if (next !== undefined && '{}#'.includes(next)) {
+                let end = p.i + 1;
+                while (end < p.s.length && p.s[end] !== "'")
+                    end++;
+                text += p.s.slice(p.i + 1, end).join('');
+                p.i = end + 1;
+                continue;
+            }
+            text += c;
+            p.i++;
+        }
+        else if (c === '{') {
+            flush();
+            out.push(parseArgument(p));
+        }
+        else if (c === '}') {
+            if (!inBranch)
+                throw new Error(`unexpected '}' at ${p.i}`);
+            flush();
+            return out;
+        }
+        else if (c === '#' && plural) {
+            flush();
+            out.push({ type: 'hash' });
+            p.i++;
+        }
+        else {
+            text += c;
+            p.i++;
+        }
+    }
+    if (inBranch)
+        throw new Error("unclosed '{'");
+    flush();
+    return out;
+}
+function until(p, stops) {
+    const start = p.i;
+    while (p.i < p.s.length && !stops.includes(p.s[p.i]))
+        p.i++;
+    return p.s.slice(start, p.i).join('');
+}
+function parseArgument(p) {
+    p.i++; // {
+    const name = until(p, ',}').trim();
+    if (!name)
+        throw new Error(`empty argument at ${p.i}`);
+    if (p.i >= p.s.length)
+        throw new Error("unclosed '{'");
+    if (p.s[p.i] === '}') {
+        p.i++;
+        return { type: 'arg', name };
+    }
+    p.i++; // ,
+    const kind = until(p, ',}').trim();
+    if (kind !== 'plural' && kind !== 'select')
+        throw new Error(`unknown argument type "${kind}"`);
+    if (p.s[p.i] !== ',')
+        throw new Error(`${kind} argument "${name}" needs options`);
+    p.i++;
+    const options = {};
+    for (;;) {
+        while (p.i < p.s.length && ' \n\t'.includes(p.s[p.i]))
+            p.i++;
+        if (p.i >= p.s.length)
+            throw new Error("unclosed '{'");
+        if (p.s[p.i] === '}') {
+            p.i++;
+            break;
+        }
+        const key = until(p, '{').trim();
+        if (!key || p.i >= p.s.length)
+            throw new Error(`expected an option in "${name}"`);
+        p.i++; // {
+        options[key] = parseNodes(p, true, kind === 'plural');
+        p.i++; // }
+    }
+    if (!options.other)
+        throw new Error(`${kind} argument "${name}" needs an 'other' option`);
+    return { type: kind, name, options };
+}
+/** The CLDR cardinal plural category of n in locale (see the Go version). */
+export function pluralCategory(locale, n) {
+    const lang = locale.toLowerCase().split(/[-_]/)[0];
+    const i = Math.abs(Math.trunc(n));
+    const isInt = n === Math.trunc(n);
+    const mod10 = i % 10;
+    const mod100 = i % 100;
+    switch (lang) {
+        case 'ja':
+        case 'zh':
+        case 'ko':
+        case 'vi':
+        case 'th':
+        case 'id':
+        case 'ms':
+        case 'lo':
+        case 'my':
+        case 'km':
+            return 'other';
+        case 'fr':
+        case 'pt':
+        case 'hy':
+        case 'ff':
+        case 'kab':
+            if (i === 0 || i === 1)
+                return 'one';
+            break;
+        case 'ru':
+        case 'uk':
+        case 'be':
+        case 'sr':
+        case 'hr':
+        case 'bs':
+            if (!isInt)
+                return 'other';
+            if (mod10 === 1 && mod100 !== 11)
+                return 'one';
+            if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14))
+                return 'few';
+            if (lang === 'ru' || lang === 'uk' || lang === 'be')
+                return 'many';
+            break;
+        case 'pl':
+            if (!isInt)
+                return 'other';
+            if (i === 1)
+                return 'one';
+            if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14))
+                return 'few';
+            return 'many';
+        case 'cs':
+        case 'sk':
+            if (!isInt)
+                return 'many';
+            if (i === 1)
+                return 'one';
+            if (i >= 2 && i <= 4)
+                return 'few';
+            break;
+        case 'ro':
+            if (i === 1 && isInt)
+                return 'one';
+            if (!isInt || i === 0 || (mod100 >= 2 && mod100 <= 19))
+                return 'few';
+            break;
+        case 'lt':
+            if (mod10 === 1 && (mod100 < 11 || mod100 > 19))
+                return 'one';
+            if (mod10 >= 2 && (mod100 < 11 || mod100 > 19))
+                return 'few';
+            break;
+        case 'lv':
+            if (mod10 === 0 || (mod100 >= 11 && mod100 <= 19))
+                return 'zero';
+            if (mod10 === 1 && mod100 !== 11)
+                return 'one';
+            break;
+        case 'ar':
+            if (n === 0)
+                return 'zero';
+            if (n === 1)
+                return 'one';
+            if (n === 2)
+                return 'two';
+            if (mod100 >= 3 && mod100 <= 10)
+                return 'few';
+            if (mod100 >= 11 && mod100 <= 99)
+                return 'many';
+            break;
+        case 'he':
+        case 'iw':
+            if (i === 1 && isInt)
+                return 'one';
+            if (i === 2 && isInt)
+                return 'two';
+            break;
+        case 'ga':
+            if (n === 1)
+                return 'one';
+            if (n === 2)
+                return 'two';
+            if (n >= 3 && n <= 6)
+                return 'few';
+            if (n >= 7 && n <= 10)
+                return 'many';
+            break;
+        case 'cy':
+            if (n === 0)
+                return 'zero';
+            if (n === 1)
+                return 'one';
+            if (n === 2)
+                return 'two';
+            if (n === 3)
+                return 'few';
+            if (n === 6)
+                return 'many';
+            break;
+        default:
+            if (n === 1 && isInt)
+                return 'one';
+    }
+    return 'other';
+}

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

@@ -0,0 +1,50 @@
+import type { Messages } from '../index.js';
+/** A message key from src/locales, or any string when the app has none. */
+export type MessageKey = [keyof Messages] extends [never] ? string : keyof Messages & string;
+type Nested = {
+    [key: string]: string | Nested;
+};
+export interface I18nConfig {
+    defaultLocale: string;
+    locales?: string[];
+    /** Client: lazy loaders. */
+    load?: Record<string, () => Promise<{
+        default: Nested;
+    }>>;
+    /** Server: every locale's messages, eagerly imported. */
+    messages?: Record<string, Nested>;
+}
+export declare function configureI18n(c: I18nConfig | null): void;
+/** Loads a locale's messages (and the default's, for fallbacks) and makes it current. */
+export declare function useLocale(locale: string | undefined): Promise<void>;
+/** Synchronous version for the server renderer, where every locale is loaded. */
+export declare function useLocaleSync(locale: string | undefined): void;
+/**
+ * Translates a message from src/locales into the current locale:
+ *
+ * ```svelte
+ * <h1>{t('welcome', { name: data.user })}</h1>
+ * <p>{t('todos.left', { count: data.left })}</p>
+ * ```
+ *
+ * Messages use ICU syntax for placeholders, plurals and selects. A message
+ * missing from the current locale falls back to the default locale, and
+ * then to the key.
+ */
+export declare function t(key: MessageKey, params?: Record<string, unknown>): string;
+/** The current locale and the ones the app supports. */
+export declare const i18n: {
+    /** The current locale, such as "de", or "" if the app has no src/locales. */
+    readonly locale: string;
+    /** Every locale in src/locales. */
+    readonly locales: string[];
+    /** The locale used for missing messages. */
+    readonly defaultLocale: string;
+};
+/**
+ * Switches the user to another locale: stores it in the locale cookie, which
+ * the server prefers over Accept-Language, and reloads the page's data. For
+ * locales in the URL (a lang route parameter), link to the other URL instead.
+ */
+export declare function setLocale(locale: string, base?: string): Promise<void>;
+export {};

package/dist/runtime/i18n.svelte.js

@@ -0,0 +1,105 @@
+import { format } from './format.js';
+class I18nState {
+    locale = $state('');
+    messages = $state({});
+    fallback = {};
+}
+const state = new I18nState();
+let config = null;
+const loaded = new Map();
+const warned = new Set();
+function flatten(tree, prefix = '', out = {}) {
+    for (const [k, v] of Object.entries(tree)) {
+        const key = prefix ? `${prefix}.${k}` : k;
+        if (typeof v === 'string')
+            out[key] = v;
+        else
+            flatten(v, key, out);
+    }
+    return out;
+}
+export function configureI18n(c) {
+    config = c;
+    if (c?.messages) {
+        for (const [l, m] of Object.entries(c.messages))
+            loaded.set(l, flatten(m));
+    }
+}
+async function messagesFor(locale) {
+    const hit = loaded.get(locale);
+    if (hit)
+        return hit;
+    const loader = config?.load?.[locale];
+    if (!loader)
+        return {};
+    const flat = flatten((await loader()).default);
+    loaded.set(locale, flat);
+    return flat;
+}
+/** Loads a locale's messages (and the default's, for fallbacks) and makes it current. */
+export async function useLocale(locale) {
+    if (!config || !locale)
+        return;
+    const [messages, fallback] = await Promise.all([messagesFor(locale), messagesFor(config.defaultLocale)]);
+    state.fallback = fallback;
+    state.messages = messages;
+    state.locale = locale;
+    if (typeof document !== 'undefined')
+        document.documentElement.lang = locale;
+}
+/** Synchronous version for the server renderer, where every locale is loaded. */
+export function useLocaleSync(locale) {
+    if (!config || !locale)
+        return;
+    state.fallback = loaded.get(config.defaultLocale) ?? {};
+    state.messages = loaded.get(locale) ?? {};
+    state.locale = locale;
+}
+/**
+ * Translates a message from src/locales into the current locale:
+ *
+ * ```svelte
+ * <h1>{t('welcome', { name: data.user })}</h1>
+ * <p>{t('todos.left', { count: data.left })}</p>
+ * ```
+ *
+ * Messages use ICU syntax for placeholders, plurals and selects. A message
+ * missing from the current locale falls back to the default locale, and
+ * then to the key.
+ */
+export function t(key, params) {
+    const message = state.messages[key] ?? state.fallback[key];
+    if (message === undefined) {
+        if (import.meta.env?.DEV && !warned.has(key)) {
+            warned.add(key);
+            console.warn(`[tern] missing message "${key}"`);
+        }
+        return key;
+    }
+    return format(state.locale || config?.defaultLocale || 'en', message, params);
+}
+/** The current locale and the ones the app supports. */
+export const i18n = {
+    /** The current locale, such as "de", or "" if the app has no src/locales. */
+    get locale() {
+        return state.locale;
+    },
+    /** Every locale in src/locales. */
+    get locales() {
+        return config?.locales ?? Object.keys(config?.messages ?? {});
+    },
+    /** The locale used for missing messages. */
+    get defaultLocale() {
+        return config?.defaultLocale ?? '';
+    }
+};
+/**
+ * Switches the user to another locale: stores it in the locale cookie, which
+ * the server prefers over Accept-Language, and reloads the page's data. For
+ * locales in the URL (a lang route parameter), link to the other URL instead.
+ */
+export async function setLocale(locale, base = '') {
+    document.cookie = `locale=${encodeURIComponent(locale)}; path=${base || '/'}; max-age=31536000; samesite=lax`;
+    const { invalidateAll } = await import('./router.svelte.js');
+    await invalidateAll();
+}

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>;

package/dist/runtime/realtime.svelte.js

@@ -0,0 +1,163 @@
+import { onDestroy } from 'svelte';
+/** Closes c when the component that created it is destroyed, if any. */
+function closeWithComponent(c) {
+    try {
+        onDestroy(() => c.close());
+    }
+    catch {
+        // Created outside a component: the caller closes it.
+    }
+}
+const browser = typeof window !== 'undefined';
+function parse(data) {
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return data;
+    }
+}
+/** A server-sent event stream; see stream(). */
+export class EventStreamState {
+    /** The data of the latest event, decoded from JSON when it is JSON. */
+    current = $state(undefined);
+    /** The connection's status. The browser reconnects by itself after errors. */
+    status = $state('connecting');
+    #source = null;
+    constructor(url, options = {}) {
+        this.current = options.initial;
+        if (!browser) {
+            this.status = 'closed';
+            return;
+        }
+        const source = new EventSource(url, { withCredentials: options.withCredentials });
+        this.#source = source;
+        const handle = (e) => {
+            const data = parse(e.data);
+            this.current = data;
+            options.onMessage?.(data, e.type);
+        };
+        for (const name of options.events?.length ? options.events : ['message'])
+            source.addEventListener(name, handle);
+        source.onopen = () => (this.status = 'open');
+        source.onerror = () => (this.status = source.readyState === EventSource.CLOSED ? 'closed' : 'connecting');
+        closeWithComponent(this);
+    }
+    /** Closes the stream. Streams created in a component close with it. */
+    close() {
+        this.#source?.close();
+        this.#source = null;
+        this.status = 'closed';
+    }
+}
+/**
+ * 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 function stream(url, options) {
+    return new EventStreamState(url, options);
+}
+/** A WebSocket connection; see socket(). */
+export class SocketState {
+    /** The latest message received. */
+    last = $state(undefined);
+    /** The connection's status. */
+    status = $state('connecting');
+    #ws = null;
+    #queue = [];
+    #closed = false;
+    #attempt = 0;
+    #timer;
+    #url;
+    #options;
+    constructor(url, options = {}) {
+        this.#url = url;
+        this.#options = options;
+        if (!browser) {
+            this.status = 'closed';
+            return;
+        }
+        this.#connect();
+        closeWithComponent(this);
+    }
+    #connect() {
+        const u = new URL(this.#url, location.href);
+        if (u.protocol === 'http:')
+            u.protocol = 'ws:';
+        else if (u.protocol === 'https:')
+            u.protocol = 'wss:';
+        const ws = new WebSocket(u, this.#options.protocols);
+        this.#ws = ws;
+        this.status = 'connecting';
+        ws.onopen = () => {
+            this.#attempt = 0;
+            this.status = 'open';
+            for (const m of this.#queue.splice(0))
+                ws.send(m);
+        };
+        ws.onmessage = (e) => {
+            const msg = (typeof e.data === 'string' ? parse(e.data) : e.data);
+            this.last = msg;
+            this.#options.onMessage?.(msg);
+        };
+        ws.onclose = (e) => {
+            this.#ws = null;
+            // 1000 is a normal close by the server: don't come back.
+            if (this.#closed || this.#options.reconnect === false || e.code === 1000) {
+                this.status = 'closed';
+                return;
+            }
+            this.status = 'connecting';
+            const delay = Math.min(10_000, 500 * 2 ** this.#attempt++) * (0.75 + Math.random() / 2);
+            this.#timer = setTimeout(() => this.#connect(), delay);
+        };
+    }
+    /** Sends a message as JSON (strings as is). Messages sent while connecting are queued. */
+    send(message) {
+        const data = typeof message === 'string' ? message : JSON.stringify(message);
+        if (this.#ws?.readyState === WebSocket.OPEN)
+            this.#ws.send(data);
+        else if (!this.#closed)
+            this.#queue.push(data);
+    }
+    /** Closes the connection. Sockets created in a component close with it. */
+    close() {
+        this.#closed = true;
+        clearTimeout(this.#timer);
+        this.#ws?.close(1000);
+        this.#ws = null;
+        this.status = 'closed';
+    }
+}
+/**
+ * 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 function socket(url, options) {
+    return new SocketState(url, options);
+}