@jk2908/solas 0.1.0

package/dist/internal/router/resolver.js

@@ -0,0 +1,356 @@
+import { lazy } from 'react';
+import { Logger } from '../../utils/logger';
+import { Build } from '../build';
+import { Metadata } from '../metadata';
+import { HttpException, isHttpException } from '../navigation/http-exception';
+const logger = new Logger();
+const IS_DEV = import.meta.env.DEV;
+/**
+ * Resolve router matches against the application manifest and import map
+ */
+export class Resolver {
+    /**
+     * Cache of enhanced matches
+     */
+    static #enhancedMatchCache = new Map();
+    /**
+     * Cache of loaded modules from dynamic imports
+     */
+    static #moduleCache = new WeakMap();
+    #manifest = {};
+    #importMap = {};
+    /**
+     * @see {@link Manifest} for the structure of the manifest
+     * @see {@link ImportMap} for the structure of the import map
+     */
+    constructor(manifest, importMap) {
+        this.#manifest = manifest;
+        this.#importMap = importMap;
+    }
+    /**
+     * Narrow down a route entry to a page entry if it exists
+     */
+    static narrow(entry) {
+        if (Array.isArray(entry)) {
+            return entry.find(e => e.__kind === Build.EntryKind.PAGE) || null;
+        }
+        return entry?.__kind === Build.EntryKind.PAGE ? entry : null;
+    }
+    /**
+     * Get the status code for a matched route that may or may not have errored
+     */
+    static getMatchStatusCode(match) {
+        if (!match)
+            return 404;
+        if ('error' in match) {
+            return match.error instanceof HttpException ? match.error.status : 500;
+        }
+        return 200;
+    }
+    static #withRequestState(cached, match) {
+        // the cached match only stores route structure, while params and errors
+        // still belong to this request so merge them back in here
+        return {
+            ...cached,
+            params: match.params,
+            error: match.error,
+        };
+    }
+    /**
+     * Load and cache a module from a dynamic import
+     */
+    static #load(loader) {
+        if (IS_DEV) {
+            // in dev always call the loader directly so hot updates are not hidden
+            // behind the prod cache
+            return {
+                promise: loader(),
+            };
+        }
+        let entry = Resolver.#moduleCache.get(loader);
+        if (entry)
+            return entry;
+        // cache the in-flight import so repeated lookups share one load
+        const promise = loader()
+            .then(mod => {
+            const entry = Resolver.#moduleCache.get(loader);
+            if (entry)
+                entry.module = mod;
+            return mod;
+        })
+            .catch(err => {
+            Resolver.#moduleCache.delete(loader);
+            throw err;
+        });
+        entry = { promise };
+        Resolver.#moduleCache.set(loader, entry);
+        return entry;
+    }
+    /**
+     * Lazily load and cache a component from a dynamic import
+     */
+    static #view(loader) {
+        const entry = Resolver.#load(loader);
+        logger.debug('[#view]', loader.toString().slice(0, 60), entry.module ? 'SYNC' : 'LAZY');
+        if (entry.module?.default) {
+            // if the module already loaded, return the component directly
+            entry.Component = entry.module.default;
+            return entry.Component;
+        }
+        // if we already created a lazy wrapper for this module
+        // reuse it
+        if (entry.Component)
+            return entry.Component;
+        // otherwise create the lazy wrapper once and keep it on the cache entry
+        const Component = lazy(() => entry.promise.then(mod => ({ default: mod.default })));
+        entry.Component = Component;
+        return entry.Component;
+    }
+    /**
+     * Reconcile a router match against a manifest entry
+     */
+    reconcile(path, match, error) {
+        if (match) {
+            const entry = Resolver.narrow(this.#manifest[match.route.path]);
+            if (entry) {
+                // normal case, the router matched a page route so just attach request state
+                return {
+                    ...entry,
+                    params: match.params,
+                    error,
+                };
+            }
+        }
+        // if nothing matched directly, walk back up the path
+        // and look for the nearest user 404 boundary
+        const entry = this.closest(path, 'paths.404s');
+        if (entry) {
+            // reuse that route entry but force it into a 404 state
+            return {
+                ...entry,
+                params: {},
+                error: isHttpException(error) && error.status === 404
+                    ? error
+                    : new HttpException(404, 'Not found'),
+            };
+        }
+        return null;
+    }
+    /**
+     * Enhance a matched route with its associated components
+     */
+    enhance(match) {
+        if (!match)
+            return null;
+        const { __id } = match;
+        // if in dev skip the cache to always get the latest changes
+        // and not break hmr
+        const cached = IS_DEV ? undefined : Resolver.#enhancedMatchCache.get(__id);
+        if (cached) {
+            logger.debug('[enhance]', __id, 'CACHED');
+            // cached ui can be reused, but params and errors still come from
+            // this request
+            return Resolver.#withRequestState(cached, match);
+        }
+        const entry = this.#importMap[__id];
+        if (!entry)
+            return null;
+        const { params, error, ...rest } = match;
+        const enhanced = {
+            ui: {
+                layouts: [],
+                Page: null,
+                '401s': [],
+                '403s': [],
+                '404s': [],
+                '500s': [],
+                loaders: [],
+            },
+            ...rest,
+        };
+        // build the renderable ui shape from the import map, with a static shell
+        // and dynamic imports for everything else
+        if (entry.shell) {
+            enhanced.ui.layouts = [
+                entry.shell.default,
+            ];
+        }
+        if (entry.layouts?.length) {
+            // layouts are stored after the shell and can each load lazily
+            const dynamicLayouts = entry.layouts.map(l => l
+                ? Resolver.#view(l)
+                : null);
+            enhanced.ui.layouts = [...enhanced.ui.layouts, ...dynamicLayouts];
+        }
+        if (entry.page) {
+            // the page is the leaf view for this route
+            enhanced.ui.Page = Resolver.#view(entry.page);
+        }
+        if (entry['401s']?.length) {
+            enhanced.ui['401s'] = entry['401s'].map(e => e
+                ? Resolver.#view(e)
+                : null);
+        }
+        if (entry['403s']?.length) {
+            enhanced.ui['403s'] = entry['403s'].map(e => e
+                ? Resolver.#view(e)
+                : null);
+        }
+        // load 404 boundaries
+        if (entry['404s']?.length) {
+            enhanced.ui['404s'] = entry['404s'].map(e => e
+                ? Resolver.#view(e)
+                : null);
+        }
+        if (entry['500s']?.length) {
+            enhanced.ui['500s'] = entry['500s'].map(e => e
+                ? Resolver.#view(e)
+                : null);
+        }
+        // loading components are per route level they are not inherited like layouts
+        // or boundaries
+        if (entry.loaders?.length) {
+            enhanced.ui.loaders = entry.loaders.map(l => l
+                ? Resolver.#view(l)
+                : null);
+        }
+        if (entry.endpoint)
+            enhanced.endpoint = entry.endpoint;
+        // collect metadata loaders once per route so they can turn into request
+        // specific tasks later when params and errors are known
+        const metadataSources = [];
+        if (entry.shell) {
+            metadataSources.push({
+                priority: Metadata.PRIORITY[Build.EntryKind.SHELL],
+                load: () => Promise.resolve(entry.shell?.metadata),
+            });
+        }
+        if (entry.layouts?.length) {
+            for (const layout of entry.layouts) {
+                if (!layout)
+                    continue;
+                const loaded = Resolver.#load(layout);
+                metadataSources.push({
+                    priority: Metadata.PRIORITY[Build.EntryKind.LAYOUT],
+                    load: () => loaded.module
+                        ? Promise.resolve(loaded.module.metadata)
+                        : loaded.promise.then(module => module.metadata),
+                });
+            }
+        }
+        if (entry.page) {
+            const loaded = Resolver.#load(entry.page);
+            metadataSources.push({
+                priority: Metadata.PRIORITY[Build.EntryKind.PAGE],
+                load: () => loaded.module
+                    ? Promise.resolve(loaded.module.metadata)
+                    : loaded.promise.then(module => module.metadata),
+            });
+        }
+        if (entry['401s']?.length) {
+            for (const errLoader of entry['401s']) {
+                if (!errLoader)
+                    continue;
+                const loaded = Resolver.#load(errLoader);
+                metadataSources.push({
+                    priority: Metadata.PRIORITY[Build.EntryKind['401']],
+                    when: 'error',
+                    status: 401,
+                    load: () => loaded.module
+                        ? Promise.resolve(loaded.module.metadata)
+                        : loaded.promise.then(module => module.metadata),
+                });
+            }
+        }
+        if (entry['403s']?.length) {
+            for (const errLoader of entry['403s']) {
+                if (!errLoader)
+                    continue;
+                const loaded = Resolver.#load(errLoader);
+                metadataSources.push({
+                    priority: Metadata.PRIORITY[Build.EntryKind['403']],
+                    when: 'error',
+                    status: 403,
+                    load: () => loaded.module
+                        ? Promise.resolve(loaded.module.metadata)
+                        : loaded.promise.then(module => module.metadata),
+                });
+            }
+        }
+        if (entry['404s']?.length) {
+            for (const errLoader of entry['404s']) {
+                if (!errLoader)
+                    continue;
+                const loaded = Resolver.#load(errLoader);
+                metadataSources.push({
+                    priority: Metadata.PRIORITY[Build.EntryKind['404']],
+                    when: 'error',
+                    status: 404,
+                    load: () => loaded.module
+                        ? Promise.resolve(loaded.module.metadata)
+                        : loaded.promise.then(module => module.metadata),
+                });
+            }
+        }
+        if (entry['500s']?.length) {
+            for (const errLoader of entry['500s']) {
+                if (!errLoader)
+                    continue;
+                const loaded = Resolver.#load(errLoader);
+                metadataSources.push({
+                    priority: Metadata.PRIORITY[Build.EntryKind['500']],
+                    when: 'error',
+                    status: 500,
+                    load: () => loaded.module
+                        ? Promise.resolve(loaded.module.metadata)
+                        : loaded.promise.then(module => module.metadata),
+                });
+            }
+        }
+        enhanced.metadata = ({ params, error }) => 
+        // metadata execution still happens per request because params and errors
+        // can differ
+        Metadata.tasks(metadataSources, { params, error }, err => {
+            logger.error(`[enhance.metadata]: ${__id}`, err);
+        });
+        if (!IS_DEV)
+            Resolver.#enhancedMatchCache.set(__id, enhanced);
+        return {
+            ...enhanced,
+            params,
+            error,
+        };
+    }
+    /**
+     * Find the closest ancestor entry for a given path and property
+     */
+    closest(path, property, value) {
+        const parts = path.split('/').filter(Boolean);
+        const segments = property.split('.');
+        // walk from the current path back towards the root until we find a match
+        for (let i = parts.length; i >= 0; i--) {
+            const testPath = i === 0 ? '/' : `/${parts.slice(0, i).join('/')}`;
+            const entry = this.#manifest[testPath];
+            if (!entry)
+                continue;
+            const pageEntry = Resolver.narrow(entry);
+            if (!pageEntry)
+                continue;
+            let curr = pageEntry;
+            // follow the dotted property path step by step on the matched entry
+            for (const segment of segments) {
+                if (!curr || typeof curr !== 'object')
+                    break;
+                if (!(segment in curr))
+                    break;
+                curr = curr[segment];
+            }
+            if (curr === undefined)
+                continue;
+            if (value && curr !== value)
+                continue;
+            return pageEntry;
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,11 @@
+export declare namespace Navigation {
+    type GoOptions = {
+        replace?: boolean;
+        query?: Record<string, string | number | boolean>;
+    };
+}
+export declare const RouterContext: import("react").Context<{
+    go: (to: string, opts?: Navigation.GoOptions | undefined) => Promise<string>;
+    prefetch: (path: string) => void;
+    isNavigating: boolean;
+}>;

package/dist/internal/router/router-context.js

@@ -0,0 +1,7 @@
+'use client';
+import { createContext } from 'react';
+export const RouterContext = createContext({
+    go: async () => '',
+    prefetch: () => { },
+    isNavigating: false,
+});

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

@@ -0,0 +1,6 @@
+import type { RSCPayload } from '../env/rsc';
+export declare function RouterProvider({ children, setPayload, isNavigating }: {
+    children: React.ReactNode;
+    setPayload?: (payload: RSCPayload) => void;
+    isNavigating?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/internal/router/router-provider.js

@@ -0,0 +1,131 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { createFromFetch } from '@vitejs/plugin-rsc/browser';
+import { Solas } from '../../solas';
+import { Logger } from '../../utils/logger';
+import { Prefetcher } from './prefetcher';
+import { RouterContext } from './router-context';
+const DEFAULT_GO_CONFIG = {
+    replace: false,
+};
+const logger = new Logger();
+const prefetcher = new Prefetcher();
+export function RouterProvider({ children, setPayload, isNavigating = false, }) {
+    // id to track active navigations
+    const id = useRef(0);
+    // abort controller for in-flight navigation
+    const controller = useRef(null);
+    /**
+     * Navigate to a new route
+     * @param to the destination url (absolute or relative to origin)
+     * @param opts navigation options
+     * @returns the path that was navigated to (relative to origin)
+     */
+    const go = useCallback(async (to, opts = {}) => {
+        id.current += 1;
+        const navigationId = id.current;
+        controller.current?.abort();
+        controller.current = null;
+        const url = new URL(to, window.location.origin);
+        const replace = opts?.replace ?? DEFAULT_GO_CONFIG.replace;
+        if (opts?.query) {
+            for (const [key, value] of Object.entries(opts.query)) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const path = Prefetcher.key(url.toString(), window.location.origin);
+        // distinguish an actual prior prefetch from a cache entry we create
+        // opportunistically for this navigation
+        const existing = prefetcher.has(path);
+        try {
+            let promise = prefetcher.get(path);
+            if (!promise) {
+                const ctrl = new AbortController();
+                controller.current = ctrl;
+                promise = fetch(path, {
+                    headers: { accept: 'text/x-component' },
+                    signal: ctrl.signal,
+                });
+            }
+            if (!prefetcher.has(path))
+                prefetcher.set(path, promise);
+            // if another navigation has started since this one, ignore the result
+            // and return early
+            if (navigationId !== id.current)
+                return path;
+            const res = await createFromFetch(promise);
+            // check again if another navigation has started while we were awaiting
+            // the response
+            if (navigationId !== id.current)
+                return path;
+            // this state update is already wrapped in a
+            // transition before being passed as props
+            setPayload?.(res);
+            if (replace) {
+                window.history.replaceState(null, '', path);
+            }
+            else {
+                window.history.pushState(null, '', path);
+            }
+            window.dispatchEvent(new CustomEvent(Solas.Events.names.NAVIGATION, { detail: { path } }));
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                return path;
+            }
+            window.dispatchEvent(new CustomEvent(Solas.Events.names.NAVIGATION_ERROR, {
+                detail: {
+                    path,
+                    error: err instanceof Error ? err.message : Logger.print(err),
+                },
+            }));
+            logger.error('[navigation] failed', err);
+        }
+        finally {
+            if (navigationId === id.current)
+                controller.current = null;
+            // preserve entries that were already prefetched so nearby follow-up
+            // navigations can still reuse them within the prefetch TTL window
+            if (!existing) {
+                // entries created by go() only serve as in-flight dedupe for this
+                // navigation (i.e. not intentionally prefetched)
+                prefetcher.remove(path);
+            }
+        }
+        return path;
+    }, [setPayload]);
+    /**
+     * Prefetch a route's assets by fetching the RSC payload
+     * @param path the route path to prefetch (absolute or relative to origin)
+     * @returns void
+     */
+    const prefetch = useCallback((path) => {
+        const connection = window.navigator.connection;
+        if (document.visibilityState === 'hidden')
+            return;
+        if (connection?.saveData)
+            return;
+        if (['2g', 'slow-2g'].includes(connection?.effectiveType ?? ''))
+            return;
+        const key = Prefetcher.key(path, window.location.origin);
+        if (prefetcher.has(key))
+            return;
+        prefetcher.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
+    }, []);
+    useEffect(() => {
+        const handler = () => go(window.location.href, { replace: true });
+        window.addEventListener('popstate', handler);
+        return () => {
+            controller.current?.abort();
+            controller.current = null;
+            window.removeEventListener('popstate', handler);
+        };
+    }, [go]);
+    const value = useMemo(() => ({
+        go,
+        prefetch,
+        isNavigating,
+    }), [go, prefetch, isNavigating]);
+    return _jsx(RouterContext, { value: value, children: children });
+}

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

@@ -0,0 +1,79 @@
+import type { HttpMethod, PluginConfig, SolasRequest } from '../../types';
+export declare namespace Router {
+    type Params = Record<string, string | string[]>;
+    type Handler = (req: SolasRequest) => Response | Promise<Response>;
+    type ErrorHandler = (err: Error, req: SolasRequest) => Response | Promise<Response>;
+    type Middleware = (req: SolasRequest, next: () => Promise<Response>) => Response | Promise<Response>;
+    type Token = {
+        kind: 'static' | 'dynamic' | 'wildcard';
+        value: string;
+    };
+    type Route = {
+        path: string;
+        method: string;
+        handler?: Handler;
+        middleware: Middleware[];
+        tokens: Token[];
+        length: number;
+        score: number;
+        wildcard: boolean;
+    };
+    type Match = {
+        route: Route;
+        params: Params;
+    };
+    type Options = {
+        trailingSlash?: boolean;
+    };
+    type Registry = {
+        static: Map<string, Route>;
+        dynamic: {
+            byLength: Map<number, Route[]>;
+            byPrefix: Map<string, Route[]>;
+        };
+        wildcard: {
+            byPrefix: Map<string, Route[]>;
+            fallback: Route[];
+        };
+    };
+}
+/**
+ * Handle routing and matching for server requests
+ */
+export declare class Router {
+    #private;
+    opts: Router.Options;
+    constructor(opts?: Router.Options);
+    /**
+     * Register middleware for all routes
+     */
+    use(...middleware: Router.Middleware[]): this;
+    /**
+     * Register an error handler for routing failures
+     */
+    error(handler: Router.ErrorHandler): this;
+    /**
+     * Register a route handler
+     */
+    add(path: string, method: string, handler: Router.Handler, params?: string[], middleware?: Router.Middleware[]): this;
+    /**
+     * Match a path and method, returning params and route
+     */
+    match(path: string, method: HttpMethod): {
+        route: Router.Route;
+        params: Router.Params;
+    } | null;
+    /**
+     * Handle an incoming request
+     */
+    fetch(req: Request): Promise<Response>;
+    /**
+     * Serve static assets from the output directory
+     * @note generated /assets/* handlers bypass +middleware conventions
+     */
+    static static(config: PluginConfig): (req: Request) => Promise<Response>;
+    /**
+     * Serve a file with optional compression content negotiation
+     */
+    static serve(filePath: string, req: Request, precompress?: boolean, headers?: Record<string, string>): Promise<Response>;
+}