@ternkit/tern 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Tern Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @ternkit/tern
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client runtime and Vite plugin for [Tern](https://github.com/Unfield/Tern), a full-stack framework with Svelte 5 on the client and Go on the server.
+
+You normally get this package from a new project rather than installing it by hand:
+
+```sh
+go run github.com/Unfield/Tern/cmd/tern@latest new my-app
+```
+
+## What it provides
+
+**`@ternkit/tern`**: the API you use in components.
+
+```svelte
+<script lang="ts">
+	import { page, navigating, goto, enhance } from '@ternkit/tern';
+</script>
+```
+
+| Export | Purpose |
+|---|---|
+| `page` | reactive state for the current page: `url`, `params`, `route`, `status`, `error`, `data`, `form` |
+| `navigating` | the navigation in progress, or `null` |
+| `goto`, `invalidateAll`, `preloadData` | client-side navigation and data |
+| `enhance`, `applyAction` | progressive enhancement for forms that post to Go actions |
+
+**`@ternkit/tern/vite`**: the Vite plugin. It includes the Svelte plugin, so it is the only plugin a Tern app needs.
+
+```js
+// vite.config.js
+import { tern } from '@ternkit/tern/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [tern()] });
+```
+
+## Requirements
+
+- Svelte 5.46 or newer
+- Vite 8
+- The matching version of the Tern Go module and CLI
+
+## Documentation
+
+See the [Tern guide](https://github.com/Unfield/Tern/blob/main/docs/guide.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Client API for Tern apps.
+ *
+ * ```svelte
+ * <script>
+ *   import { page, goto, enhance } from '@ternkit/tern';
+ * </script>
+ * ```
+ */
+export { page, navigating } 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 type { BeforeNavigateEvent, OnNavigateEvent } from './runtime/navigation.js';
+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';
+/** The version of the Tern client runtime. */
+export declare const VERSION = "0.4.0";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * Client API for Tern apps.
+ *
+ * ```svelte
+ * <script>
+ *   import { page, goto, enhance } from '@ternkit/tern';
+ * </script>
+ * ```
+ */
+export { page, navigating } 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';
+/** The version of the Tern client runtime. */
+export const VERSION = '0.4.0';

package/dist/runtime/DefaultError.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import { page } from './state.svelte.js';
+</script>
+
+<main style="font-family: system-ui, sans-serif; max-width: 36rem; margin: 4rem auto; padding: 0 1rem;">
+	<h1>{page.status}</h1>
+	<p>{page.error?.message}</p>
+</main>

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

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const DefaultError: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type DefaultError = InstanceType<typeof DefaultError>;
+export default DefaultError;

package/dist/runtime/Passthrough.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	// Used for layout directories that have a LayoutLoad but no +layout.svelte.
+	let { children }: { children?: Snippet; data?: unknown } = $props();
+</script>
+
+{@render children?.()}

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

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    children?: Snippet;
+    data?: unknown;
+};
+declare const Passthrough: import("svelte").Component<$$ComponentProps, {}, "">;
+type Passthrough = ReturnType<typeof Passthrough>;
+export default Passthrough;

package/dist/runtime/Root.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+	import type { Component } from 'svelte';
+
+	interface Props {
+		/** Layout components, outermost first, then the page or error component. */
+		components: Component<any>[];
+		/** Data for each component, already merged with its parents' data. */
+		data: Record<string, unknown>[];
+		form: unknown;
+	}
+
+	let { components, data, form }: Props = $props();
+</script>
+
+{#snippet level(i: number)}
+	{@const Current = components[i]}
+	{#if Current}
+		{#if i === components.length - 1}
+			<Current data={data[i]} {form} />
+		{:else}
+			<Current data={data[i]}>
+				{@render level(i + 1)}
+			</Current>
+		{/if}
+	{/if}
+{/snippet}
+
+{@render level(0)}

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

@@ -0,0 +1,11 @@
+import type { Component } from 'svelte';
+interface Props {
+    /** Layout components, outermost first, then the page or error component. */
+    components: Component<any>[];
+    /** Data for each component, already merged with its parents' data. */
+    data: Record<string, unknown>[];
+    form: unknown;
+}
+declare const Root: Component<Props, {}, "">;
+type Root = ReturnType<typeof Root>;
+export default Root;

package/dist/runtime/client.d.ts

@@ -0,0 +1 @@
+export { start } from './router.svelte.js';

package/dist/runtime/client.js

@@ -0,0 +1,2 @@
+// Entry point used by the generated .tern/generated/client.js.
+export { start } from './router.svelte.js';

package/dist/runtime/deferred.d.ts

@@ -0,0 +1,29 @@
+/** A resolved or failed deferred value, as streamed by the server. */
+export interface Chunk {
+    id: number;
+    data?: unknown;
+    error?: {
+        message: string;
+    };
+}
+/**
+ * Connects the deferred placeholders of one response to the chunks that
+ * resolve them. IDs are only unique within a response.
+ */
+export declare class DeferredScope {
+    #private;
+    promise(id: number): Promise<unknown>;
+    settle(chunk: Chunk): void;
+    /** Rejects every value still pending, e.g. when the stream ends early. */
+    close(reason: string): void;
+}
+/** Replaces deferred placeholders in data with promises from scope. */
+export declare function revive<T>(value: T, promise: (id: number) => Promise<unknown>): T;
+/**
+ * Reads a response that holds one JSON payload line, optionally followed
+ * by one line per resolved deferred value. Resolves once the payload is
+ * read; deferred values keep streaming in the background.
+ */
+export declare function readStreamed<P extends {
+    nodes?: unknown;
+}>(res: Response): Promise<P>;

package/dist/runtime/deferred.js

@@ -0,0 +1,111 @@
+/**
+ * Connects the deferred placeholders of one response to the chunks that
+ * resolve them. IDs are only unique within a response.
+ */
+export class DeferredScope {
+    #pending = new Map();
+    #early = new Map();
+    promise(id) {
+        const early = this.#early.get(id);
+        if (early) {
+            this.#early.delete(id);
+            return early.error ? Promise.reject(new Error(early.error.message)) : Promise.resolve(early.data);
+        }
+        return new Promise((resolve, reject) => this.#pending.set(id, { resolve, reject }));
+    }
+    settle(chunk) {
+        const p = this.#pending.get(chunk.id);
+        if (!p) {
+            this.#early.set(chunk.id, chunk);
+            return;
+        }
+        this.#pending.delete(chunk.id);
+        if (chunk.error)
+            p.reject(new Error(chunk.error.message));
+        else
+            p.resolve(chunk.data);
+    }
+    /** Rejects every value still pending, e.g. when the stream ends early. */
+    close(reason) {
+        for (const p of this.#pending.values())
+            p.reject(new Error(reason));
+        this.#pending.clear();
+    }
+}
+/** Replaces deferred placeholders in data with promises from scope. */
+export function revive(value, promise) {
+    if (Array.isArray(value)) {
+        return value.map((v) => revive(v, promise));
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 1 && keys[0] === '__tern_deferred' && typeof obj.__tern_deferred === 'number') {
+            return promise(obj.__tern_deferred);
+        }
+        const out = {};
+        for (const k of keys)
+            out[k] = revive(obj[k], promise);
+        return out;
+    }
+    return value;
+}
+/**
+ * Reads a response that holds one JSON payload line, optionally followed
+ * by one line per resolved deferred value. Resolves once the payload is
+ * read; deferred values keep streaming in the background.
+ */
+export async function readStreamed(res) {
+    if (!res.body) {
+        const [first, ...rest] = (await res.text()).split('\n');
+        const scope = new DeferredScope();
+        const payload = JSON.parse(first);
+        payload.nodes = revive(payload.nodes, (id) => scope.promise(id));
+        for (const line of rest)
+            if (line.trim())
+                scope.settle(JSON.parse(line));
+        scope.close('The server did not send this value');
+        return payload;
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let done = false;
+    while (!buffer.includes('\n') && !done) {
+        const r = await reader.read();
+        done = r.done;
+        if (r.value)
+            buffer += decoder.decode(r.value, { stream: true });
+    }
+    const newline = buffer.indexOf('\n');
+    const first = newline < 0 ? buffer : buffer.slice(0, newline);
+    buffer = newline < 0 ? '' : buffer.slice(newline + 1);
+    const scope = new DeferredScope();
+    const payload = JSON.parse(first);
+    payload.nodes = revive(payload.nodes, (id) => scope.promise(id));
+    void (async () => {
+        try {
+            for (;;) {
+                let i;
+                while ((i = buffer.indexOf('\n')) >= 0) {
+                    const line = buffer.slice(0, i);
+                    buffer = buffer.slice(i + 1);
+                    if (line.trim())
+                        scope.settle(JSON.parse(line));
+                }
+                if (done)
+                    break;
+                const r = await reader.read();
+                done = r.done;
+                if (r.value)
+                    buffer += decoder.decode(r.value, { stream: true });
+                if (done && buffer.trim())
+                    buffer += '\n';
+            }
+        }
+        finally {
+            scope.close('The connection closed before this value arrived');
+        }
+    })();
+    return payload;
+}

package/dist/runtime/forms.d.ts

@@ -0,0 +1,39 @@
+import type { ActionReturn } from 'svelte/action';
+import type { ActionResult } from './types.js';
+export interface SubmitInput {
+    action: URL;
+    formData: FormData;
+    formElement: HTMLFormElement;
+    controller: AbortController;
+    submitter: HTMLElement | null;
+    /** Stops the submission. */
+    cancel(): void;
+}
+export interface SubmitResult<Success, Failure> {
+    action: URL;
+    formData: FormData;
+    formElement: HTMLFormElement;
+    result: ActionResult<Success, Failure>;
+    /**
+     * Does what `use:enhance` does by default: reset the form and rerun
+     * loads after a success, then apply the result to the page.
+     */
+    update(opts?: {
+        reset?: boolean;
+        invalidateAll?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Runs before a form is submitted. Return a function to handle the
+ * result yourself; call `update()` in it to keep the default behavior.
+ */
+export type SubmitFunction<Success = Record<string, unknown>, Failure = Record<string, unknown>> = (input: SubmitInput) => void | ((result: SubmitResult<Success, Failure>) => void | Promise<void>) | Promise<void | ((result: SubmitResult<Success, Failure>) => void | Promise<void>)>;
+/**
+ * Progressively enhances a form that posts to a page action. Without
+ * JavaScript the form still works; with it, the page updates in place.
+ *
+ * ```svelte
+ * <form method="POST" action="?/create" use:enhance>
+ * ```
+ */
+export declare function enhance<Success = Record<string, unknown>, Failure = Record<string, unknown>>(form: HTMLFormElement, submit?: SubmitFunction<Success, Failure>): ActionReturn<SubmitFunction<Success, Failure> | undefined>;

package/dist/runtime/forms.js

@@ -0,0 +1,91 @@
+import { applyAction, invalidateAll } from './router.svelte.js';
+// Cloning a form without children reads its own action/method/enctype,
+// even if it contains inputs named "action" or "method".
+function attrs(form) {
+    return HTMLFormElement.prototype.cloneNode.call(form);
+}
+/**
+ * Progressively enhances a form that posts to a page action. Without
+ * JavaScript the form still works; with it, the page updates in place.
+ *
+ * ```svelte
+ * <form method="POST" action="?/create" use:enhance>
+ * ```
+ */
+export function enhance(form, submit = () => { }) {
+    async function defaultUpdate(action, formElement, result, { reset = true, invalidateAll: invalidate = true } = {}) {
+        if (result.type === 'success') {
+            if (reset)
+                HTMLFormElement.prototype.reset.call(formElement);
+            if (invalidate)
+                await invalidateAll();
+        }
+        const samePage = location.origin + location.pathname === action.origin + action.pathname;
+        if (samePage || result.type === 'redirect' || result.type === 'error') {
+            await applyAction(result);
+        }
+    }
+    async function onSubmit(event) {
+        const submitter = event.submitter;
+        const own = attrs(form);
+        const method = submitter?.hasAttribute('formmethod') ? submitter.formMethod : own.method;
+        if (method !== 'post')
+            return;
+        event.preventDefault();
+        const action = new URL(submitter?.hasAttribute('formaction') ? submitter.formAction : own.action);
+        const enctype = submitter?.hasAttribute('formenctype') ? submitter.formEnctype : own.enctype;
+        const formData = new FormData(form, submitter);
+        const controller = new AbortController();
+        let cancelled = false;
+        const callback = await submit({
+            action,
+            formData,
+            formElement: form,
+            controller,
+            submitter,
+            cancel: () => (cancelled = true)
+        });
+        if (cancelled)
+            return;
+        let result;
+        try {
+            const res = await fetch(action, {
+                method: 'POST',
+                headers: { accept: 'application/json', 'x-tern-action': 'true' },
+                body: enctype === 'multipart/form-data'
+                    ? formData
+                    : new URLSearchParams(formData),
+                cache: 'no-store',
+                credentials: 'same-origin',
+                signal: controller.signal
+            });
+            if (res.headers.get('content-type')?.includes('application/json')) {
+                result = await res.json();
+            }
+            else {
+                result = { type: 'error', status: res.status, error: { message: res.statusText || 'Request failed' } };
+            }
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            result = { type: 'error', status: 500, error: { message: err instanceof Error ? err.message : String(err) } };
+        }
+        const update = (opts) => defaultUpdate(action, form, result, opts);
+        if (callback) {
+            await callback({ action, formData, formElement: form, result, update });
+        }
+        else {
+            await update();
+        }
+    }
+    form.addEventListener('submit', onSubmit);
+    return {
+        update(next) {
+            submit = next ?? (() => { });
+        },
+        destroy() {
+            form.removeEventListener('submit', onSubmit);
+        }
+    };
+}

package/dist/runtime/navigation.d.ts

@@ -0,0 +1,55 @@
+import type { Navigation } from './types.js';
+/** Passed to beforeNavigate callbacks. */
+export interface BeforeNavigateEvent extends Navigation {
+    /** True when the browser is about to leave the app (a reload, closing the tab, or another site). */
+    willUnload: boolean;
+    /** Stops the navigation. When leaving the page, the browser asks the user to confirm. */
+    cancel(): void;
+}
+/** Passed to onNavigate callbacks. */
+export interface OnNavigateEvent extends Navigation {
+    /** Resolves when the new page has rendered. */
+    complete: Promise<void>;
+}
+type BeforeFn = (nav: BeforeNavigateEvent) => void;
+type OnFn = (nav: OnNavigateEvent) => void | Promise<void> | (() => void) | Promise<() => void>;
+type AfterFn = (nav: Navigation) => void;
+/**
+ * Runs before every navigation, including leaving the app. Call
+ * `nav.cancel()` to stop it, for example to keep unsaved changes:
+ *
+ * ```js
+ * beforeNavigate((nav) => {
+ *   if (dirty && !confirm('Discard your changes?')) nav.cancel();
+ * });
+ * ```
+ *
+ * Call it while a component initializes; it is removed when the component is destroyed.
+ */
+export declare function beforeNavigate(fn: BeforeFn): void;
+/**
+ * Runs when a client-side navigation has loaded its data, right before the
+ * new page renders. Return a promise to delay rendering, for example to
+ * start a view transition; return a function to run after the navigation.
+ *
+ * ```js
+ * onNavigate((nav) => {
+ *   if (!document.startViewTransition) return;
+ *   return new Promise((resolve) => {
+ *     document.startViewTransition(async () => {
+ *       resolve();
+ *       await nav.complete;
+ *     });
+ *   });
+ * });
+ * ```
+ */
+export declare function onNavigate(fn: OnFn): void;
+/** Runs after every navigation, including the first page load. */
+export declare function afterNavigate(fn: AfterFn): void;
+/** Runs beforeNavigate callbacks; reports whether the navigation may go ahead. */
+export declare function runBefore(nav: Navigation, willUnload: boolean): boolean;
+/** Runs onNavigate callbacks and returns the cleanups to call afterwards. */
+export declare function runOn(nav: Navigation, complete: Promise<void>): Promise<(() => void)[]>;
+export declare function runAfter(nav: Navigation): void;
+export {};

package/dist/runtime/navigation.js

@@ -0,0 +1,69 @@
+import { onMount } from 'svelte';
+const before = new Set();
+const on = new Set();
+const after = new Set();
+/**
+ * Runs before every navigation, including leaving the app. Call
+ * `nav.cancel()` to stop it, for example to keep unsaved changes:
+ *
+ * ```js
+ * beforeNavigate((nav) => {
+ *   if (dirty && !confirm('Discard your changes?')) nav.cancel();
+ * });
+ * ```
+ *
+ * Call it while a component initializes; it is removed when the component is destroyed.
+ */
+export function beforeNavigate(fn) {
+    onMount(() => {
+        before.add(fn);
+        return () => before.delete(fn);
+    });
+}
+/**
+ * Runs when a client-side navigation has loaded its data, right before the
+ * new page renders. Return a promise to delay rendering, for example to
+ * start a view transition; return a function to run after the navigation.
+ *
+ * ```js
+ * onNavigate((nav) => {
+ *   if (!document.startViewTransition) return;
+ *   return new Promise((resolve) => {
+ *     document.startViewTransition(async () => {
+ *       resolve();
+ *       await nav.complete;
+ *     });
+ *   });
+ * });
+ * ```
+ */
+export function onNavigate(fn) {
+    onMount(() => {
+        on.add(fn);
+        return () => on.delete(fn);
+    });
+}
+/** Runs after every navigation, including the first page load. */
+export function afterNavigate(fn) {
+    onMount(() => {
+        after.add(fn);
+        return () => after.delete(fn);
+    });
+}
+/** Runs beforeNavigate callbacks; reports whether the navigation may go ahead. */
+export function runBefore(nav, willUnload) {
+    let cancelled = false;
+    const event = { ...nav, willUnload, cancel: () => (cancelled = true) };
+    for (const fn of before)
+        fn(event);
+    return !cancelled;
+}
+/** Runs onNavigate callbacks and returns the cleanups to call afterwards. */
+export async function runOn(nav, complete) {
+    const results = await Promise.all([...on].map((fn) => fn({ ...nav, complete })));
+    return results.filter((r) => typeof r === 'function');
+}
+export function runAfter(nav) {
+    for (const fn of after)
+        fn(nav);
+}

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

@@ -0,0 +1,19 @@
+import type { ActionResult, ClientManifest, GotoOptions, Payload } from './types.js';
+/** Starts the client. Called by the generated entry module. */
+export declare function start(m: ClientManifest): Promise<void>;
+/** Navigates to href, which may be relative to the current URL. */
+export declare function goto(href: string | URL, opts?: GotoOptions): Promise<void>;
+/**
+ * Reruns the loads that depend on key, as declared with ctx.Depends(key)
+ * in Go, plus the current page's load.
+ */
+export declare function invalidate(key: string): Promise<void>;
+/** Reruns every load for the current page. */
+export declare function invalidateAll(): Promise<void>;
+/**
+ * Loads the data and code for a URL so a later navigation to it is instant.
+ * Tern does this automatically for links; see data-tern-preload.
+ */
+export declare function preloadData(href: string | URL): Promise<Payload | null>;
+/** Applies a form action result to the page, as `use:enhance` does. */
+export declare function applyAction(result: ActionResult): Promise<void>;