@jk2908/solas 0.1.0

package/dist/internal/env/ssr.d.ts

@@ -0,0 +1,42 @@
+import type { ReactFormState } from 'react-dom/client';
+type Opts = {
+    formState?: ReactFormState;
+    nonce?: string;
+    ppr?: boolean;
+    route?: string;
+};
+/**
+ * SSR handler - returns a ReadableStream response for HTML requests
+ */
+declare function ssr(rscStream: ReadableStream<Uint8Array>, opts?: Opts): Promise<ReadableStream<any>>;
+/**
+ * Build-time prerender artifact generation
+ * @description for PPR routes this returns static prelude HTML + opaque postponed state
+ */
+declare function prerender(rscStream: ReadableStream<Uint8Array>, opts?: Opts): Promise<{
+    schema: string;
+    route: string;
+    createdAt: number;
+    mode: string;
+    html: string;
+    postponed?: undefined;
+} | {
+    schema: string;
+    route: string;
+    createdAt: number;
+    mode: string;
+    html: string;
+    postponed: import("react-dom/static").PostponedState;
+}>;
+/**
+ * Request-time resume for PPR routes
+ */
+declare function resume(rscStream: ReadableStream<Uint8Array>, postponedState: unknown, opts?: Pick<Opts, 'nonce'> & {
+    injectPayload?: boolean;
+}): Promise<ReadableStream<any>>;
+export type SSRModule = {
+    prerender: typeof prerender;
+    resume: typeof resume;
+    ssr: typeof ssr;
+};
+export { prerender, resume, ssr };

package/dist/internal/env/ssr.js

@@ -0,0 +1,149 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, use } from 'react';
+import { resume as reactResume, renderToReadableStream } from 'react-dom/server.edge';
+import { prerender as reactPrerender } from 'react-dom/static.edge';
+import { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+import { injectRSCPayload } from 'rsc-html-stream/server';
+import { Solas } from '../../solas';
+import { Logger } from '../../utils/logger';
+import { getKnownDigest } from './utils';
+import { RedirectBoundary } from '../navigation/redirect-boundary';
+import { Prerender } from '../prerender';
+import { Head } from '../render/head';
+import { RouterProvider } from '../router/router-provider';
+import { ErrorBoundary } from '../ui/error-boundary';
+const logger = new Logger();
+function A({ payloadPromise }) {
+    const payload = use(payloadPromise);
+    return (_jsx(RedirectBoundary, { children: _jsxs(RouterProvider, { children: [
+                _jsx(ErrorBoundary, { fallback: null, children: _jsx(Suspense, { fallback: null, children: _jsx(Head, { metadata: payload.metadata }) }) }), payload.root] }) }));
+}
+/**
+ * SSR handler - returns a ReadableStream response for HTML requests
+ */
+async function ssr(rscStream, opts = {}) {
+    const { formState, nonce, ppr = false } = opts;
+    const [s1, s2] = rscStream.tee();
+    const payloadPromise = createFromReadableStream(s1);
+    const bootstrapScriptContent = await import.meta.viteRsc.loadBootstrapScriptContent('index');
+    // ppr uses react prerender where prelude is the static shell
+    // dynamic content is streamed via suspense
+    // rsc payload is injected after
+    if (ppr) {
+        const { prelude } = await reactPrerender(_jsx(A, { payloadPromise: payloadPromise }), {
+            bootstrapScriptContent,
+            onError(err) {
+                const digest = getKnownDigest(err);
+                if (digest)
+                    return digest;
+                logger.error('[ssr:ppr]', err);
+            },
+        });
+        return prelude.pipeThrough(injectRSCPayload(s2, { nonce }));
+    }
+    const htmlStream = await renderToReadableStream(_jsx(A, { payloadPromise: payloadPromise }), {
+        bootstrapScriptContent,
+        nonce,
+        formState,
+        onError(err) {
+            const digest = getKnownDigest(err);
+            if (digest)
+                return digest;
+            logger.error('[ssr]', err);
+        },
+    });
+    return htmlStream.pipeThrough(injectRSCPayload(s2, { nonce }));
+}
+/**
+ * Build-time prerender artifact generation
+ * @description for PPR routes this returns static prelude HTML + opaque postponed state
+ */
+async function prerender(rscStream, opts = {}) {
+    const { ppr = false, nonce, route } = opts;
+    if (!route) {
+        const err = new Error('missing route in ssr.prerender() opts');
+        logger.error('[ssr:prerender]', err);
+        throw err;
+    }
+    const [s1, s2] = rscStream.tee();
+    const payloadPromise = createFromReadableStream(s1);
+    const bootstrapScriptContent = await import.meta.viteRsc.loadBootstrapScriptContent('index');
+    const schema = Solas.getVersion();
+    if (ppr) {
+        const controller = new AbortController();
+        // abort on a macrotask so sync and microtask work still lands in prelude
+        // unresolved work is captured as postponed state for resume
+        setTimeout(() => {
+            controller.abort(new Prerender.Runtime.Postponed());
+        }, 0);
+        const { prelude, postponed } = await reactPrerender(_jsx(A, { payloadPromise: payloadPromise }), {
+            bootstrapScriptContent,
+            signal: controller.signal,
+            onError(err) {
+                if (Prerender.Runtime.isPostponed(err))
+                    return;
+                const digest = getKnownDigest(err);
+                if (digest)
+                    return digest;
+                logger.error('[ssr:prerender:ppr]', err);
+            },
+        });
+        // if prerender produced no postponed state, this route is effectively
+        // fully prerenderable. Emit full HTML with embedded RSC payload
+        if (postponed == null) {
+            return {
+                schema,
+                route,
+                createdAt: Date.now(),
+                mode: 'full',
+                html: await new Response(prelude.pipeThrough(injectRSCPayload(s2, { nonce }))).text(),
+            };
+        }
+        return {
+            schema,
+            route,
+            createdAt: Date.now(),
+            mode: 'ppr',
+            html: await new Response(prelude).text(),
+            postponed,
+        };
+    }
+    const stream = await renderToReadableStream(_jsx(A, { payloadPromise: payloadPromise }), {
+        bootstrapScriptContent,
+        onError(err) {
+            const digest = getKnownDigest(err);
+            if (digest)
+                return digest;
+            logger.error('[ssr:prerender:full]', err);
+        },
+    });
+    await stream.allReady;
+    return {
+        schema,
+        route,
+        createdAt: Date.now(),
+        mode: 'full',
+        html: await new Response(stream.pipeThrough(injectRSCPayload(s2, { nonce }))).text(),
+    };
+}
+/**
+ * Request-time resume for PPR routes
+ */
+async function resume(rscStream, postponedState, opts = {}) {
+    const { nonce, injectPayload = true } = opts;
+    const [s1, s2] = rscStream.tee();
+    const payloadPromise = createFromReadableStream(s1);
+    const htmlStream = await reactResume(_jsx(A, { payloadPromise: payloadPromise }), postponedState, {
+        nonce,
+        onError(err) {
+            const digest = getKnownDigest(err);
+            if (digest)
+                return digest;
+            logger.error('[ssr:resume]', err);
+        },
+    });
+    if (!injectPayload)
+        return htmlStream;
+    return htmlStream.pipeThrough(injectRSCPayload(s2, { nonce }));
+}
+export { prerender, resume, ssr };

package/dist/internal/env/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function getKnownDigest(err: unknown): string | null;
+export declare function isKnownError(err: unknown): boolean;

package/dist/internal/env/utils.js

@@ -0,0 +1,28 @@
+import { HTTP_EXCEPTION_DIGEST_PREFIX } from '../navigation/http-exception';
+import { REDIRECT_DIGEST_PREFIX } from '../navigation/redirect';
+const possibilities = [HTTP_EXCEPTION_DIGEST_PREFIX, REDIRECT_DIGEST_PREFIX];
+export function getKnownDigest(err) {
+    if (typeof err === 'object' &&
+        err !== null &&
+        'digest' in err &&
+        typeof err.digest === 'string') {
+        for (const p of possibilities) {
+            if (!err.digest.startsWith(p))
+                continue;
+            return err.digest;
+        }
+    }
+    return null;
+}
+export function isKnownError(err) {
+    if (getKnownDigest(err))
+        return true;
+    if (err instanceof Error) {
+        if (err.name === 'AbortError')
+            return true;
+        if (err.message === 'The render was aborted by the server without a reason') {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/internal/metadata.d.ts

@@ -0,0 +1,81 @@
+import type { HttpException } from './navigation/http-exception';
+import { Build } from './build';
+type EntryKind = typeof Build.EntryKind;
+export declare namespace Metadata {
+    type EntrySource = Exclude<EntryKind[keyof EntryKind], typeof Build.EntryKind.ENDPOINT | typeof Build.EntryKind.MIDDLEWARE>;
+    export const PRIORITY: Record<EntrySource, number>;
+    type TagValue = string | number | boolean | undefined;
+    export type MetaTag = {
+        charSet: string;
+    } | {
+        name: string;
+        content: TagValue;
+    } | {
+        httpEquiv: string;
+        content: TagValue;
+    } | {
+        property: string;
+        content: TagValue;
+    };
+    export type LinkTag = {
+        rel: string;
+        href?: string;
+        as?: string;
+        type?: string;
+        media?: string;
+        sizes?: string;
+        crossOrigin?: 'anonymous' | 'use-credentials';
+    };
+    export type Item = {
+        title?: TagValue;
+        meta?: MetaTag[];
+        link?: LinkTag[];
+    };
+    export type Input<TParams = unknown, TError = Error> = {
+        params?: TParams;
+        error?: TError;
+    };
+    export type Task = {
+        priority: number;
+        task: Promise<Item>;
+    };
+    export type RunMode = 'always' | 'error';
+    /**
+     * A cached way to load one metadata export for a route.
+     * The export itself is loaded once route structure is known, then resolved
+     * later with request-specific input such as params or an error.
+     */
+    export type Source = {
+        priority: Task['priority'];
+        when?: RunMode;
+        status?: HttpException.StatusCode;
+        load: () => Promise<unknown>;
+    };
+    export class Collection {
+        #private;
+        constructor(base?: Item);
+        /**
+         * Adds tasks to the collection
+         */
+        add(...tasks: Task[]): this;
+        /**
+         * Merges metadata from all sources, sorted by priority
+         */
+        run(): Promise<Item>;
+        /**
+         * Get a clone of the base metadata
+         */
+        get base(): Item;
+    }
+    /**
+     * Normalise a metadata export into a promise of a metadata object
+     * Supports both plain object exports and metadata(input) functions
+     */
+    export function resolve(metadata: unknown, input: Input, onError?: (err: unknown) => void): Promise<{}>;
+    /**
+     * Turn cached metadata exports into concrete work for the current request/render
+     */
+    export function tasks(sources: Source[], input: Input, onError?: (err: unknown) => void): Task[];
+    export {};
+}
+export {};

package/dist/internal/metadata.js

@@ -0,0 +1,185 @@
+import { Build } from './build';
+import { isHttpException } from './navigation/http-exception';
+const TITLE_TEMPLATE_STR = '%s';
+export { Metadata };
+var Metadata;
+(function (Metadata) {
+    Metadata.PRIORITY = {
+        [Build.EntryKind.SHELL]: 10,
+        [Build.EntryKind.LAYOUT]: 20,
+        [Build.EntryKind.PAGE]: 30,
+        [Build.EntryKind['401']]: 40,
+        [Build.EntryKind['403']]: 40,
+        [Build.EntryKind['404']]: 40,
+        [Build.EntryKind['500']]: 40,
+        [Build.EntryKind.LOADING]: 50,
+    };
+    class Collection {
+        /**
+         * The base metadata object
+         * @description - normally extends config.metadata
+         */
+        #base = {};
+        /**
+         * The collection of metadata tasks with their priorities
+         * @description - each task is a promise that resolves to a metadata object
+         */
+        #collection = [];
+        constructor(base) {
+            if (base)
+                this.#base = base;
+        }
+        /**
+         * Merges multiple metadata objects into one
+         */
+        static #merge(...items) {
+            if (!items.length)
+                return {};
+            let titleTemplate;
+            let title;
+            const metaMap = new Map();
+            const linkMap = new Map();
+            for (const item of items) {
+                if (item.title) {
+                    const titleStr = item.title.toString();
+                    if (titleStr.includes(TITLE_TEMPLATE_STR)) {
+                        titleTemplate = titleStr;
+                    }
+                    else {
+                        title = titleStr;
+                    }
+                }
+                if (item.meta) {
+                    for (const tag of item.meta) {
+                        metaMap.set(Collection.#getMetaTagKey(tag), tag);
+                    }
+                }
+                if (item.link) {
+                    for (const tag of item.link) {
+                        linkMap.set(Collection.#getLinkTagKey(tag), tag);
+                    }
+                }
+            }
+            const metadata = {};
+            // build final title
+            if (titleTemplate && title) {
+                metadata.title = titleTemplate.replace(TITLE_TEMPLATE_STR, title);
+            }
+            else {
+                metadata.title = title ?? titleTemplate?.replace(TITLE_TEMPLATE_STR, '').trim();
+            }
+            // assign final tags
+            metadata.meta = [...metaMap.values()];
+            metadata.link = [...linkMap.values()];
+            return metadata;
+        }
+        /**
+         * Clones an object using structuredClone w/ JSON fallback
+         */
+        static #clone(obj) {
+            if (typeof structuredClone === 'function') {
+                return structuredClone(obj);
+            }
+            return JSON.parse(JSON.stringify(obj));
+        }
+        /**
+         * Gets a unique key for the meta tag
+         */
+        static #getMetaTagKey(tag) {
+            return 'name' in tag && tag.name
+                ? `name:${tag.name}`
+                : 'property' in tag && tag.property
+                    ? `property:${tag.property}`
+                    : 'httpEquiv' in tag && tag.httpEquiv
+                        ? `httpEquiv:${tag.httpEquiv}`
+                        : 'charSet' in tag && tag.charSet
+                            ? 'charSet'
+                            : JSON.stringify(tag);
+        }
+        /**
+         * Gets a unique key for the link tag
+         */
+        static #getLinkTagKey(tag) {
+            return tag.rel + (tag.href ?? '');
+        }
+        /**
+         * Adds tasks to the collection
+         */
+        add(...tasks) {
+            for (const { task, priority } of tasks) {
+                this.#collection.push({ priority, task });
+            }
+            return this;
+        }
+        /**
+         * Merges metadata from all sources, sorted by priority
+         */
+        async run() {
+            const items = [...this.#collection].sort((a, b) => a.priority - b.priority);
+            if (items.length === 0)
+                return Collection.#clone(this.#base);
+            let merged = Collection.#clone(this.#base);
+            const res = await Promise.allSettled(items.map(entry => entry.task));
+            const ok = res
+                .filter((result) => result.status === 'fulfilled')
+                .map(result => result.value);
+            if (ok.length)
+                merged = Collection.#merge(merged, ...ok);
+            return merged;
+        }
+        /**
+         * Get a clone of the base metadata
+         */
+        get base() {
+            return Collection.#clone(this.#base);
+        }
+    }
+    Metadata.Collection = Collection;
+    /**
+     * Normalise a metadata export into a promise of a metadata object
+     * Supports both plain object exports and metadata(input) functions
+     */
+    function resolve(metadata, input, onError) {
+        if (!metadata)
+            return Promise.resolve({});
+        if (typeof metadata === 'function') {
+            try {
+                return Promise.resolve(metadata(input)).catch(err => {
+                    onError?.(err);
+                    return {};
+                });
+            }
+            catch (err) {
+                onError?.(err);
+                return Promise.resolve({});
+            }
+        }
+        if (typeof metadata === 'object')
+            return Promise.resolve(metadata);
+        return Promise.resolve({});
+    }
+    Metadata.resolve = resolve;
+    /**
+     * Turn cached metadata exports into concrete work for the current request/render
+     */
+    function tasks(sources, input, onError) {
+        const tasks = [];
+        for (const source of sources) {
+            if (source.when === 'error' && !input.error)
+                continue;
+            if (source.status !== undefined) {
+                if (!input.error ||
+                    !isHttpException(input.error) ||
+                    input.error.status !== source.status) {
+                    continue;
+                }
+            }
+            tasks.push({
+                task: source.load().then(metadata => resolve(metadata, input, onError)),
+                priority: source.priority,
+            });
+        }
+        return tasks;
+    }
+    Metadata.tasks = tasks;
+})(Metadata || (Metadata = {}));

package/dist/internal/navigation/http-exception-boundary.d.ts

@@ -0,0 +1,12 @@
+import type { BoundaryError } from '../../types';
+import { type HttpException } from './http-exception';
+type ComponentsMap = Partial<Record<HttpException.StatusCode, React.ReactElement | null>>;
+export type Props = {
+    fallback: ((error: BoundaryError) => React.ReactNode) | React.ReactNode;
+    children: React.ReactNode;
+};
+export declare function HttpExceptionBoundary({ components, children }: {
+    components: ComponentsMap;
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/navigation/http-exception-boundary.js

@@ -0,0 +1,48 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from 'react';
+import { HTTP_EXCEPTION_DIGEST_PREFIX, isHttpException, } from './http-exception';
+function isSupportedStatusCode(value) {
+    return value === 401 || value === 403 || value === 404 || value === 500;
+}
+class Boundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    render() {
+        const { error } = this.state;
+        if (!error)
+            return this.props.children;
+        return typeof this.props.fallback === 'function'
+            ? this.props.fallback(error)
+            : this.props.fallback;
+    }
+}
+export function HttpExceptionBoundary({ components, children, }) {
+    return (_jsx(Boundary, { fallback: err => {
+            if (!isHttpException(err))
+                throw err;
+            if ('digest' in err && typeof err.digest === 'string') {
+                const [type, ...rest] = err.digest.split(':');
+                if (type === HTTP_EXCEPTION_DIGEST_PREFIX) {
+                    const [code] = rest;
+                    const status = Number(code);
+                    if (!isSupportedStatusCode(status))
+                        throw err;
+                    const component = components[status];
+                    // if no component is provided for this status code, re-throw
+                    // the error to be caught by a higher-level boundary
+                    // (e.g. the root boundary)
+                    if (!component)
+                        throw err;
+                    return (_jsxs(_Fragment, { children: [
+                            _jsx("meta", { name: "robots", content: "noindex,nofollow" }), component] }));
+                }
+            }
+            throw err;
+        }, children: children }));
+}

package/dist/internal/navigation/http-exception.d.ts

@@ -0,0 +1,33 @@
+export declare namespace HttpException {
+    type Payload = string | Record<string, unknown>;
+    type StatusCode = 401 | 403 | 404 | 500;
+    type Options = {
+        payload?: Payload;
+        cause?: unknown;
+    };
+}
+export declare const HTTP_EXCEPTION_NAME_MAP: Record<HttpException.StatusCode, string>;
+/**
+ * An exception representing an HTTP error, with an optional payload
+ * and cause
+ */
+export declare class HttpException extends Error {
+    readonly status: HttpException.StatusCode;
+    readonly message: string;
+    payload?: HttpException.Payload;
+    digest?: string;
+    constructor(status: HttpException.StatusCode, message: string, opts?: HttpException.Options);
+}
+export declare const HTTP_EXCEPTION_DIGEST_PREFIX = "HTTP_EXCEPTION";
+/**
+ * Check if an error is an HTTPException
+ * @description uses the digest property to work across server/client boundaries
+ */
+export declare function isHttpException(err: unknown): err is HttpException;
+/**
+ * Throw an HTTPException
+ */
+export declare function abort(status: HttpException.StatusCode, message: string, opts?: {
+    payload?: HttpException.Payload;
+    cause?: unknown;
+}): never;

package/dist/internal/navigation/http-exception.js

@@ -0,0 +1,45 @@
+export const HTTP_EXCEPTION_NAME_MAP = {
+    401: 'UNAUTHORIZED',
+    403: 'FORBIDDEN',
+    404: 'NOT_FOUND',
+    500: 'INTERNAL_SERVER_ERROR',
+};
+/**
+ * An exception representing an HTTP error, with an optional payload
+ * and cause
+ */
+export class HttpException extends Error {
+    status;
+    message;
+    payload;
+    digest;
+    constructor(status, message, opts) {
+        super(message, { cause: opts?.cause });
+        this.status = status;
+        this.message = message;
+        this.name = HTTP_EXCEPTION_NAME_MAP[status];
+        this.payload = opts?.payload;
+        this.digest = `${HTTP_EXCEPTION_DIGEST_PREFIX}:${status}:${message}`;
+    }
+}
+export const HTTP_EXCEPTION_DIGEST_PREFIX = 'HTTP_EXCEPTION';
+/**
+ * Check if an error is an HTTPException
+ * @description uses the digest property to work across server/client boundaries
+ */
+export function isHttpException(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'digest' in err &&
+        typeof err.digest === 'string' &&
+        err.digest.startsWith(HTTP_EXCEPTION_DIGEST_PREFIX));
+}
+/**
+ * Throw an HTTPException
+ */
+export function abort(status, message, opts) {
+    throw new HttpException(status, message, {
+        payload: opts?.payload,
+        cause: opts?.cause,
+    });
+}

package/dist/internal/navigation/link.d.ts

@@ -0,0 +1,13 @@
+type Props = {
+    href: string;
+    prefetch?: 'intent' | 'hover' | 'none';
+} & React.ComponentPropsWithRef<'a'>;
+/**
+ * A link component that navigates to a given href
+ * @param href - the href to navigate to
+ * @param prefetch - when to prefetch the linked page, defaults to 'intent'
+ * @param rest - other props to pass to the underlying anchor element
+ * @returns a link element that navigates to the given href
+ */
+export declare function Link({ children, href, prefetch, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
+export {};