@jk2908/solas 0.1.0

package/dist/internal/prerender.js

@@ -0,0 +1,422 @@
+import path from 'node:path';
+import { compile } from 'path-to-regexp';
+import { Solas } from '../solas';
+import { Logger } from '../utils/logger';
+import { Time } from '../utils/time';
+import { toPathPattern } from './router/pattern';
+const logger = new Logger();
+export { Prerender };
+var Prerender;
+(function (Prerender) {
+    const DEFAULT_TIMEOUT_MS = 15_000;
+    const DEFAULT_CONCURRENCY = 4;
+    let Artifact;
+    (function (Artifact) {
+        const manifestCache = new Map();
+        /**
+         * Get the root directory path where prerender artifacts are stored,
+         * based on the output directory specified in the configuration
+         */
+        function getRootPath(outDir) {
+            return path.join(outDir, Solas.Config.GENERATED_DIR, 'ppr');
+        }
+        Artifact.getRootPath = getRootPath;
+        /**
+         * Get the file system path for the prerender artifact manifest, which
+         * contains metadata about all prerendered routes and their artifacts
+         */
+        function getManifestPath(outDir) {
+            return path.join(getRootPath(outDir), 'manifest.json');
+        }
+        Artifact.getManifestPath = getManifestPath;
+        /**
+         * Get the file system path for storing prerender artifacts for a given route
+         */
+        function getPath(outDir, pathname) {
+            const root = path.resolve(getRootPath(outDir));
+            const dir = pathname === '/' ? 'index' : pathname.replace(/^\//, '');
+            const artifactPath = path.resolve(root, dir);
+            // this also runs at request time, so make sure the pathname cannot escape the artifact folder
+            if (artifactPath !== root && !artifactPath.startsWith(`${root}${path.sep}`)) {
+                throw new Error('[prerender] invalid artifact path');
+            }
+            return artifactPath;
+        }
+        Artifact.getPath = getPath;
+        /**
+         * Load the prerender artifact manifest for faster runtime route mode checks
+         */
+        async function loadManifest(outDir) {
+            // if we already loaded this outDir, return cached result
+            // (either a valid manifest or null when it was missing/invalid)
+            if (manifestCache.has(outDir)) {
+                return manifestCache.get(outDir) ?? null;
+            }
+            const file = Bun.file(getManifestPath(outDir));
+            // no manifest means no prerender metadata to use
+            if (!(await file.exists())) {
+                manifestCache.set(outDir, null);
+                return null;
+            }
+            try {
+                // parse once, then validate the shape before trusting any fields
+                const value = JSON.parse(await file.text());
+                if (!value || typeof value !== 'object') {
+                    manifestCache.set(outDir, null);
+                    return null;
+                }
+                const generatedAt = value.generatedAt;
+                const routes = value.routes;
+                if (typeof generatedAt !== 'number') {
+                    manifestCache.set(outDir, null);
+                    return null;
+                }
+                if (!routes || typeof routes !== 'object') {
+                    manifestCache.set(outDir, null);
+                    return null;
+                }
+                // verify each route entry so runtime can rely on mode/files safely
+                for (const entry of Object.values(routes)) {
+                    if (!entry || typeof entry !== 'object') {
+                        manifestCache.set(outDir, null);
+                        return null;
+                    }
+                    const { mode, createdAt, files } = entry;
+                    // only allow known modes
+                    if (mode !== 'full' && mode !== 'ppr') {
+                        manifestCache.set(outDir, null);
+                        return null;
+                    }
+                    if (typeof createdAt !== 'number') {
+                        manifestCache.set(outDir, null);
+                        return null;
+                    }
+                    if (files !== undefined) {
+                        if (!Array.isArray(files)) {
+                            manifestCache.set(outDir, null);
+                            return null;
+                        }
+                        // only allow known artifact file labels
+                        for (const f of files) {
+                            if (f !== 'html' &&
+                                f !== 'prelude' &&
+                                f !== 'postponed' &&
+                                f !== 'metadata') {
+                                manifestCache.set(outDir, null);
+                                return null;
+                            }
+                        }
+                    }
+                }
+                const manifest = { generatedAt, routes };
+                // cache validated manifest to avoid reparsing on every request
+                manifestCache.set(outDir, manifest);
+                return manifest;
+            }
+            catch {
+                manifestCache.set(outDir, null);
+                return null;
+            }
+        }
+        Artifact.loadManifest = loadManifest;
+        /**
+         * Load the postponed state for a given route from the file system, if it exists
+         */
+        async function loadPostponedState(outDir, pathname) {
+            let file;
+            try {
+                file = Bun.file(path.join(getPath(outDir, pathname), 'postponed.json'));
+            }
+            catch (err) {
+                logger.warn(`[prerender:artifacts] rejected postponed state path for ${pathname}`, Logger.print(err));
+                return null;
+            }
+            if (!(await file.exists()))
+                return null;
+            try {
+                return JSON.parse(await file.text());
+            }
+            catch {
+                return null;
+            }
+        }
+        Artifact.loadPostponedState = loadPostponedState;
+        /**
+         * Load the prelude HTML for a given route from the file system, if it exists
+         */
+        async function loadPrelude(outDir, pathname) {
+            let file;
+            try {
+                file = Bun.file(path.join(getPath(outDir, pathname), 'prelude.html'));
+            }
+            catch (err) {
+                logger.warn(`[prerender:artifacts] rejected prelude path for ${pathname}`, Logger.print(err));
+                return null;
+            }
+            if (!(await file.exists()))
+                return null;
+            try {
+                return await file.text();
+            }
+            catch {
+                return null;
+            }
+        }
+        Artifact.loadPrelude = loadPrelude;
+        /**
+         * Load the prerender artifact metadata for a given route from the file system, if it exists and is valid
+         */
+        async function loadMetadata(outDir, pathname) {
+            let file;
+            try {
+                file = Bun.file(path.join(getPath(outDir, pathname), 'metadata.json'));
+            }
+            catch (err) {
+                logger.warn(`[prerender:artifacts] rejected metadata path for ${pathname}`, Logger.print(err));
+                return null;
+            }
+            if (!(await file.exists()))
+                return null;
+            try {
+                const value = JSON.parse(await file.text());
+                if (!value || typeof value !== 'object')
+                    return null;
+                const schema = value.schema;
+                const route = value.route;
+                const createdAt = value.createdAt;
+                const mode = value.mode;
+                if (typeof schema !== 'string')
+                    return null;
+                if (typeof route !== 'string')
+                    return null;
+                if (typeof createdAt !== 'number')
+                    return null;
+                if (mode !== 'full' && mode !== 'ppr')
+                    return null;
+                return { schema, route, createdAt, mode };
+            }
+            catch {
+                return null;
+            }
+        }
+        Artifact.loadMetadata = loadMetadata;
+        /**
+         * Check if a prerender artifact is compatible with the current application version and route,
+         * based on its metadata
+         */
+        function isCompatible(artifactMetadata, pathname, mode) {
+            const schema = Solas.getVersion();
+            return (artifactMetadata.schema === schema &&
+                artifactMetadata.route === pathname &&
+                artifactMetadata.mode === mode);
+        }
+        Artifact.isCompatible = isCompatible;
+        /**
+         * Compose the prelude HTML and the resume stream into a single HTML stream, by injecting the resume stream
+         * into the prelude at the appropriate location (before </body> or </html>)
+         */
+        function composePreludeAndResume(prelude, resumeStream) {
+            const lower = prelude.toLowerCase();
+            const bodyClose = lower.lastIndexOf('</body>');
+            const htmlClose = lower.lastIndexOf('</html>');
+            const splitAt = bodyClose >= 0 && htmlClose > bodyClose ? bodyClose : prelude.length;
+            return new ReadableStream({
+                async start(controller) {
+                    const encoder = new TextEncoder();
+                    const decoder = new TextDecoder();
+                    controller.enqueue(new TextEncoder().encode(prelude.slice(0, splitAt)));
+                    const reader = resumeStream.getReader();
+                    let strippedLeadingClose = false;
+                    try {
+                        while (true) {
+                            const { value, done } = await reader.read();
+                            if (done)
+                                break;
+                            if (!value)
+                                continue;
+                            if (!strippedLeadingClose) {
+                                strippedLeadingClose = true;
+                                const text = decoder.decode(value);
+                                const trimmed = text.replace(/^\s*<\/body>\s*<\/html>/i, '');
+                                if (trimmed.length > 0)
+                                    controller.enqueue(encoder.encode(trimmed));
+                                continue;
+                            }
+                            controller.enqueue(value);
+                        }
+                    }
+                    finally {
+                        reader.releaseLock();
+                        controller.close();
+                    }
+                },
+            });
+        }
+        Artifact.composePreludeAndResume = composePreludeAndResume;
+    })(Artifact = Prerender.Artifact || (Prerender.Artifact = {}));
+    let Runtime;
+    (function (Runtime) {
+        /**
+         * Custom error class to indicate that prerendering has been postponed to request-time
+         */
+        class Postponed extends Error {
+            constructor(message = 'postponed') {
+                super(message);
+                this.name = 'Postponed';
+            }
+        }
+        Runtime.Postponed = Postponed;
+        /**
+         * Type guard to check if an error is a Postponed error, including wrapped errors like
+         * AbortError or TimeoutError
+         */
+        function isPostponed(error) {
+            if (error instanceof Postponed)
+                return true;
+            if (error instanceof Error &&
+                (error.name === 'AbortError' || error.name === 'TimeoutError')) {
+                if (error.cause instanceof Postponed)
+                    return true;
+            }
+            return false;
+        }
+        Runtime.isPostponed = isPostponed;
+    })(Runtime = Prerender.Runtime || (Prerender.Runtime = {}));
+    let Build;
+    (function (Build) {
+        /**
+         * Get the prerender timeout value from the environment variable, or return the default
+         * if it's not set or invalid
+         */
+        function getTimeout() {
+            const v = Number(process.env.SOLAS_PRERENDER_TIMEOUT_MS);
+            if (!Number.isFinite(v) || v <= 0) {
+                return DEFAULT_TIMEOUT_MS;
+            }
+            return v;
+        }
+        Build.getTimeout = getTimeout;
+        /**
+         * Get the prerender concurrency value from the environment variable, or return the default
+         * if it's not set or invalid
+         */
+        function getConcurrency() {
+            const v = Number(process.env.SOLAS_PRERENDER_CONCURRENCY);
+            if (!Number.isInteger(v) || v <= 0) {
+                return DEFAULT_CONCURRENCY;
+            }
+            return v;
+        }
+        Build.getConcurrency = getConcurrency;
+        /**
+         * Extract the prerendering mode ('full', 'ppr', or false) from the source code of a route module, by
+         * looking for an exported `prerender` binding and validating its value
+         */
+        async function getStaticFlag(filePath, buildContext) {
+            return buildContext.exportReader.literal(filePath, 'prerender', (v) => v === 'full' || v === 'ppr' || v === false);
+        }
+        Build.getStaticFlag = getStaticFlag;
+        /**
+         * Get the list of static parameters for a dynamic route, by looking for an exported `params` function
+         * in the route module and calling it to get the list of parameter objects
+         */
+        async function getStaticParams(filePath, buildContext) {
+            const params = await buildContext.exportReader.value(filePath, 'params', (v) => typeof v === 'function');
+            if (!params)
+                return [];
+            const resolved = await Time.timeout(Promise.try(() => params()), getTimeout(), `static params for ${filePath}`);
+            if (!Array.isArray(resolved))
+                return [];
+            return resolved;
+        }
+        Build.getStaticParams = getStaticParams;
+        /**
+         * Generate the list of prerenderable routes for a dynamic route, by combining the static parameters obtained from
+         * the route module with the route pattern, and filtering out any routes that still contain dynamic segments
+         */
+        function getDynamicRouteList(route, paramNames, staticParams) {
+            if (!staticParams.length)
+                return [];
+            const { path: compilePath, wildcardNames } = toPathPattern(route, paramNames);
+            const toPath = compile(compilePath);
+            return staticParams
+                .map(value => {
+                try {
+                    return toPath(Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+                        key,
+                        wildcardNames.has(key)
+                            ? Array.isArray(entry)
+                                ? entry.map(part => String(part))
+                                : [String(entry)]
+                            : Array.isArray(entry)
+                                ? entry.map(part => String(part)).join('/')
+                                : String(entry),
+                    ])));
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((value) => value !== null)
+                .filter(r => !r.includes(':') && !r.includes('*'));
+        }
+        Build.getDynamicRouteList = getDynamicRouteList;
+        /**
+         * Function to prerender a single route by making a request to the route with special headers, and returning the
+         * result which includes either the prerender artifact or an error/status code if the prerendering failed or was
+         * postponed to request-time
+         */
+        async function get(app, route, opts) {
+            const url = `${opts.origin ?? `http://${Solas.Config.SLUG}.local`}${route}`;
+            const res = await Time.timeout(app.fetch(new Request(url, {
+                headers: {
+                    Accept: 'text/html',
+                    [`x-${Solas.Config.SLUG}-prerender`]: '1',
+                    [`x-${Solas.Config.SLUG}-prerender-artifact`]: '1',
+                },
+            })), opts.timeout, `route ${route}`);
+            if (!(res instanceof Response)) {
+                const error = new TypeError(`Invalid response for ${route}`);
+                logger.error(`[prerender:get] ${error.message}`, error);
+                throw error;
+            }
+            if (!res.ok)
+                return { route, status: res.status };
+            return { route, artifact: await res.json() };
+        }
+        Build.get = get;
+        /**
+         * Run the prerendering process for a list of routes, with a specified concurrency limit and timeout for
+         * each route, by calling the 'get' function for each route and yielding the results as they
+         * become available
+         */
+        async function* run(app, routes, opts) {
+            const limit = Math.max(1, Math.min(opts.concurrency ?? 4, routes.length || 1));
+            let index = 0;
+            const pending = new Map();
+            function enqueue() {
+                while (index < routes.length && pending.size < limit) {
+                    const i = index++;
+                    const value = routes[i];
+                    pending.set(i, get(app, value, {
+                        timeout: opts.timeout,
+                        origin: opts.origin,
+                    })
+                        .then(result => ({ index: i, result }))
+                        .catch(err => ({
+                        index: i,
+                        result: { route: value, error: err },
+                    })));
+                }
+            }
+            enqueue();
+            while (pending.size > 0) {
+                const settled = await Promise.race(pending.values());
+                pending.delete(settled.index);
+                yield settled.result;
+                enqueue();
+            }
+        }
+        Build.run = run;
+    })(Build = Prerender.Build || (Prerender.Build = {}));
+})(Prerender || (Prerender = {}));

package/dist/internal/render/head.d.ts

@@ -0,0 +1,4 @@
+import { type Metadata as Collection } from '../metadata';
+export declare function Head({ metadata: m }: {
+    metadata?: Collection.Item | Promise<Collection.Item>;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/internal/render/head.js

@@ -0,0 +1,38 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { use } from 'react';
+import { Solas } from '../../solas';
+import { Logger } from '../../utils/logger';
+const logger = new Logger();
+const cache = new WeakMap();
+export function Head({ metadata: m, }) {
+    if (!m)
+        return null;
+    const metadata = use(toSafeUsable(m));
+    return (_jsxs(_Fragment, { children: [
+            _jsx("meta", { name: "generator", content: Solas.Config.NAME }), metadata.title && _jsx("title", { children: metadata.title.toString() }), metadata.meta?.map(meta => {
+                if ('charSet' in meta) {
+                    return _jsx("meta", { charSet: meta.charSet }, meta.charSet);
+                }
+                if ('name' in meta) {
+                    return (_jsx("meta", { name: meta.name, content: meta.content?.toString() }, meta.name));
+                }
+                if ('httpEquiv' in meta) {
+                    return (_jsx("meta", { httpEquiv: meta.httpEquiv, content: meta.content?.toString() }, meta.httpEquiv));
+                }
+                if ('property' in meta) {
+                    return (_jsx("meta", { property: meta.property, content: meta.content?.toString() }, meta.property));
+                }
+                return null;
+            }), metadata.link?.map(link => (_jsx("link", { ...link }, `${link.rel}${link.href ?? ''}`)))] }));
+}
+function toSafeUsable(metadata) {
+    const cached = cache.get(metadata);
+    if (cached)
+        return cached;
+    const safe = Promise.resolve(metadata).catch(err => {
+        logger.error('[head] failed to resolve metadata', err);
+        return {};
+    });
+    cache.set(metadata, safe);
+    return safe;
+}

package/dist/internal/render/tree.d.ts

@@ -0,0 +1,47 @@
+import type { Resolver } from '../router/resolver';
+type Match = NonNullable<Resolver.EnhancedMatch>;
+/**
+ * Render the resolved route tree for a matched page
+ *
+ * The shell is always `layouts[0]`. Every deeper segment is then wrapped from
+ * the inside out in this order:
+ *
+ * 1. `Layout`
+ * 2. `Suspense` with that segment's loading fallback
+ * 3. `HttpExceptionBoundary` with that segment's status boundaries
+ *
+ * The shell level is applied last using the same outer wrapper order:
+ * `HttpExceptionBoundary` -> `Suspense` -> `Shell`
+ *
+ * @example
+ * ```tsx
+ *   <HttpExceptionBoundary shell>
+ *     <Suspense fallback={<ShellLoading />}>
+ *       <Shell>
+ *         <HttpExceptionBoundary segmentN>
+ *           <Suspense fallback={<LoadingN />}>
+ *             <LayoutN>
+ *               ...
+ *                 <HttpExceptionBoundary segment1>
+ *                   <Suspense fallback={<Loading1 />}>
+ *                     <Layout1>
+ *                       <Page />
+ *                     </Layout1>
+ *                   </Suspense>
+ *                 </HttpExceptionBoundary>
+ *               ...
+ *             </LayoutN>
+ *           </Suspense>
+ *         </HttpExceptionBoundary>
+ *       </Shell>
+ *     </Suspense>
+ *   </HttpExceptionBoundary>
+ * ```
+ */
+export declare function Tree({ depth, params, error, ui }: {
+    depth: Match['__depth'];
+    params: Match['params'];
+    error: Match['error'];
+    ui: Match['ui'];
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/render/tree.js

@@ -0,0 +1,108 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense } from 'react';
+import { HttpException, isHttpException } from '../navigation/http-exception';
+import { HttpExceptionBoundary } from '../navigation/http-exception-boundary';
+import DefaultErr from '../ui/defaults/error';
+/**
+ * Render the resolved route tree for a matched page
+ *
+ * The shell is always `layouts[0]`. Every deeper segment is then wrapped from
+ * the inside out in this order:
+ *
+ * 1. `Layout`
+ * 2. `Suspense` with that segment's loading fallback
+ * 3. `HttpExceptionBoundary` with that segment's status boundaries
+ *
+ * The shell level is applied last using the same outer wrapper order:
+ * `HttpExceptionBoundary` -> `Suspense` -> `Shell`
+ *
+ * @example
+ * ```tsx
+ *   <HttpExceptionBoundary shell>
+ *     <Suspense fallback={<ShellLoading />}>
+ *       <Shell>
+ *         <HttpExceptionBoundary segmentN>
+ *           <Suspense fallback={<LoadingN />}>
+ *             <LayoutN>
+ *               ...
+ *                 <HttpExceptionBoundary segment1>
+ *                   <Suspense fallback={<Loading1 />}>
+ *                     <Layout1>
+ *                       <Page />
+ *                     </Layout1>
+ *                   </Suspense>
+ *                 </HttpExceptionBoundary>
+ *               ...
+ *             </LayoutN>
+ *           </Suspense>
+ *         </HttpExceptionBoundary>
+ *       </Shell>
+ *     </Suspense>
+ *   </HttpExceptionBoundary>
+ * ```
+ */
+export function Tree({ depth, params, error, ui, }) {
+    const { layouts, Page, '401s': unauthorized, '403s': forbidden, '404s': notFounds, '500s': serverErrors, loaders, } = ui;
+    const Shell = layouts[0];
+    if (!Shell)
+        throw new Error('Shell layout is required in the route tree');
+    // build the inner inner (everything after shell)
+    let inner = null;
+    // map http status codes to exception components
+    const httpExceptionMap = {
+        401: unauthorized,
+        403: forbidden,
+        404: notFounds,
+        500: serverErrors,
+    };
+    if (error && isHttpException(error)) {
+        const Exception = httpExceptionMap[error.status].slice(0, depth + 1).findLast(e => e !== null) ??
+            DefaultErr;
+        inner = (_jsxs(_Fragment, { children: [
+                _jsx("meta", { name: "robots", content: "noindex,nofollow" }), _jsx(Exception, { error: error })
+            ] }));
+    }
+    else if (Page) {
+        inner = _jsx(Page, { params: params });
+    }
+    // wrap from innermost to layouts[1] (skip shell)
+    for (let idx = layouts.length - 1; idx >= 1; idx--) {
+        const Layout = layouts[idx];
+        const Loading = loaders[idx];
+        const Unauthorized = unauthorized[idx];
+        const Forbidden = forbidden[idx];
+        const NotFound = notFounds[idx];
+        const ServerError = serverErrors[idx];
+        // wrap in layout
+        if (Layout) {
+            inner = (_jsx(Layout, { params: params, children: inner }, `l:${idx}`));
+        }
+        // wrap in suspense (for this segment's loading state)
+        if (Loading) {
+            inner = _jsx(Suspense, { fallback: _jsx(Loading, {}), children: inner });
+        }
+        const errorBoundaries = {
+            401: Unauthorized ? (_jsx(Unauthorized, { error: new HttpException(401, 'Unauthorized') })) : null,
+            403: Forbidden ? _jsx(Forbidden, { error: new HttpException(403, 'Forbidden') }) : null,
+            404: NotFound ? _jsx(NotFound, { error: new HttpException(404, 'Not found') }) : null,
+            500: ServerError ? (_jsx(ServerError, { error: new HttpException(500, 'Internal Server Error') })) : null,
+        };
+        // wrap in error boundaries (if supplied for this segment's http errors)
+        if (Object.values(errorBoundaries).some(c => c !== null)) {
+            inner = (_jsx(HttpExceptionBoundary, { components: errorBoundaries, children: inner }));
+        }
+    }
+    // now wrap with shell structure: shell renders immediately,
+    // inner streams inside Suspense
+    const ShellLoading = loaders[0];
+    const ShellUnauthorized = unauthorized[0];
+    const ShellForbidden = forbidden[0];
+    const ShellNotFound = notFounds[0];
+    const ShellServerError = serverErrors[0];
+    return (_jsx(HttpExceptionBoundary, { components: {
+            401: ShellUnauthorized ? _jsx(ShellUnauthorized, {}) : null,
+            403: ShellForbidden ? _jsx(ShellForbidden, {}) : null,
+            404: ShellNotFound ? _jsx(ShellNotFound, {}) : null,
+            500: ShellServerError ? _jsx(ShellServerError, {}) : null,
+        }, children: _jsx(Suspense, { fallback: ShellLoading ? _jsx(ShellLoading, {}) : null, children: _jsx(Shell, { params: params, children: inner }) }) }));
+}

package/dist/internal/router/create-router.d.ts

@@ -0,0 +1,6 @@
+import type { ImportMap, Manifest, PluginConfig, SolasRequest } from '../../types';
+import { Router } from './router';
+/**
+ * Create the application router from the generated manifest and import map
+ */
+export declare function createRouter(config: Pick<PluginConfig, 'precompress' | 'trailingSlash'>, manifest: Manifest, importMap: ImportMap, rsc: (req: SolasRequest) => Response | Promise<Response>): Router;