@jk2908/solas 0.1.0

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

@@ -0,0 +1,95 @@
+import { Router } from './router';
+function callEndpoint(fn, req) {
+    // endpoint modules may export either a zero-arg handler or one that expects the request
+    if (fn.length === 0)
+        return fn();
+    return fn(req);
+}
+function createHandlerGroups(manifest) {
+    return Object.values(manifest)
+        .flat()
+        .reduce((acc, entry) => {
+        // group by method + path so page and endpoint pairs can share one GET handler
+        const key = `${entry.method}/${entry.__path}`;
+        const existing = acc.get(key);
+        if (!existing) {
+            acc.set(key, entry);
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(entry);
+        }
+        else {
+            acc.set(key, [existing, entry]);
+        }
+        return acc;
+    }, new Map());
+}
+function resolveMiddlewares(entry, importMap) {
+    // the manifest keeps middleware paths for serialisable route data, whilst
+    // the import map carries the actual runtime middleware functions
+    const middlewares = importMap[entry.__id]?.middlewares ?? [];
+    return middlewares.filter((value) => value !== null);
+}
+function mergeMiddlewares(left, right) {
+    const merged = [];
+    // unified page plus endpoint routes need one middleware chain, preserving the
+    // declared order but dropping duplicate functions shared by both sides
+    for (const middleware of [...(left ?? []), ...(right ?? [])]) {
+        if (!middleware)
+            continue;
+        if (merged.includes(middleware))
+            continue;
+        merged.push(middleware);
+    }
+    return merged;
+}
+/**
+ * Create the application router from the generated manifest and import map
+ */
+export function createRouter(config, manifest, importMap, rsc) {
+    const router = new Router({
+        trailingSlash: config.trailingSlash,
+    });
+    // static assets stay outside route middleware conventions and are registered once
+    router.add('/assets/*', 'GET', Router.static(config));
+    for (const [, group] of createHandlerGroups(manifest)) {
+        if (!Array.isArray(group)) {
+            if ('paths' in group) {
+                // plain page routes always hand off to the RSC request pipeline
+                router.add(group.__path, group.method.toUpperCase(), req => rsc(req), group.__params, resolveMiddlewares(group, importMap));
+                continue;
+            }
+            const endpoint = importMap[group.__id]?.endpoint;
+            if (!endpoint) {
+                throw new Error(`Missing endpoint handler for ${group.__id}`);
+            }
+            // standalone endpoints resolve directly from the import map and bypass RSC
+            router.add(group.__path, group.method.toUpperCase(), req => callEndpoint(endpoint, req), group.__params, resolveMiddlewares(group, importMap));
+            continue;
+        }
+        if (group.length > 2)
+            throw new Error('Unexpected route group length');
+        const page = group.find((entry) => 'paths' in entry);
+        const endpointEntry = group.find((entry) => !('paths' in entry));
+        if (!page) {
+            throw new Error('Unified route group missing page entry');
+        }
+        const endpoint = endpointEntry ? importMap[endpointEntry.__id]?.endpoint : undefined;
+        // page plus endpoint pairs share one GET registration that chooses between
+        // document or RSC rendering and the endpoint implementation at request time
+        const middlewares = mergeMiddlewares(importMap[page.__id]?.middlewares, endpointEntry ? importMap[endpointEntry.__id]?.middlewares : undefined);
+        router.add(page.__path, 'GET', async req => {
+            const accept = req.headers.get('accept') ?? '';
+            if (accept.includes('text/html') || accept.includes('text/x-component')) {
+                return rsc(req);
+            }
+            if (!endpoint) {
+                throw new Error(`Missing unified endpoint handler for ${page.__path}`);
+            }
+            return callEndpoint(endpoint, req);
+        }, page.__params, middlewares);
+    }
+    // the router already stores the thrown error on the request metadata before
+    // invoking the error hook, so the RSC pipeline can read it back from req
+    return router.error((_err, req) => rsc(req));
+}

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

@@ -0,0 +1,8 @@
+export type PathPattern = {
+    path: string;
+    wildcardNames: Set<string>;
+};
+export declare function toPathPattern(route: string, paramNames?: string[]): {
+    path: string;
+    wildcardNames: Set<string>;
+};

package/dist/internal/router/pattern.js

@@ -0,0 +1,31 @@
+function escapePathSegment(value) {
+    return value.replace(/[\\.+*?^${}()[\]|!:]/g, '\\$&');
+}
+export function toPathPattern(route, paramNames = []) {
+    if (route === '/') {
+        return { path: route, wildcardNames: new Set() };
+    }
+    let paramIndex = 0;
+    let wildcardIndex = 0;
+    const wildcardNames = new Set();
+    const path = route
+        .split('/')
+        .filter(Boolean)
+        .map(segment => {
+        if (segment.startsWith(':')) {
+            paramIndex += 1;
+            return `/${segment}`;
+        }
+        if (segment === '*') {
+            const value = paramNames[paramIndex];
+            const name = value && value !== '*' ? value : `wildcard${wildcardIndex}`;
+            paramIndex += 1;
+            wildcardIndex += 1;
+            wildcardNames.add(name);
+            return `/*${name}`;
+        }
+        return `/${escapePathSegment(segment)}`;
+    })
+        .join('');
+    return { path: path || '/', wildcardNames };
+}

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

@@ -0,0 +1,47 @@
+export declare namespace Prefetcher {
+    type Entry = {
+        promise: Promise<Response>;
+        timeoutId: ReturnType<typeof setTimeout>;
+    };
+}
+export declare class Prefetcher {
+    #private;
+    ttl: number;
+    maxSize: number;
+    constructor({ ttl, maxSize }?: {
+        ttl?: number;
+        maxSize?: number;
+    });
+    /**
+     * Converts a url path to a cache key by normalising it
+     * against a base url
+     */
+    static key(path: string, base: string): string;
+    /**
+     * Evicts the oldest entry from the cache
+     */
+    evict(): void;
+    /**
+     * Returns a boolean indicating whether a cached response exists for the given path
+     */
+    has(path: string): boolean;
+    /**
+     * Retrieves a fresh response promise for the given path if it exists
+     * by cloning the cached response so each consumer gets an unread stream
+     */
+    get(path: string): Promise<Response> | undefined;
+    /**
+     * Caches a response promise for the given path with a timeout to automatically
+     * clear the cache after a certain period (TTL_MS)
+     */
+    set(path: string, promise: Promise<Response>): void;
+    /**
+     * Removes the cached response for the given path and clears the associated timeout
+     */
+    remove(path: string): void;
+    /**
+     * Clears the entire cache and all associated timeouts
+     */
+    clear(): void;
+    [Symbol.dispose](): void;
+}

package/dist/internal/router/prefetcher.js

@@ -0,0 +1,90 @@
+export class Prefetcher {
+    #cache = new Map();
+    ttl = 60_000;
+    maxSize = 32;
+    constructor({ ttl = 60_000, maxSize = 32 } = {}) {
+        this.ttl = ttl;
+        this.maxSize = maxSize;
+    }
+    /**
+     * Converts a url path to a cache key by normalising it
+     * against a base url
+     */
+    static key(path, base) {
+        const url = new URL(path, base);
+        return url.pathname + url.search + url.hash;
+    }
+    /**
+     * Evicts the oldest entry from the cache
+     */
+    evict() {
+        if (this.#cache.size === 0)
+            return;
+        const candidate = this.#cache.entries().next().value;
+        if (!candidate)
+            return;
+        const [key, entry] = candidate;
+        clearTimeout(entry.timeoutId);
+        this.#cache.delete(key);
+    }
+    /**
+     * Returns a boolean indicating whether a cached response exists for the given path
+     */
+    has(path) {
+        return this.#cache.has(path);
+    }
+    /**
+     * Retrieves a fresh response promise for the given path if it exists
+     * by cloning the cached response so each consumer gets an unread stream
+     */
+    get(path) {
+        const promise = this.#cache.get(path)?.promise;
+        if (!promise)
+            return;
+        return promise.then(res => res.clone());
+    }
+    /**
+     * Caches a response promise for the given path with a timeout to automatically
+     * clear the cache after a certain period (TTL_MS)
+     */
+    set(path, promise) {
+        const existing = this.#cache.get(path);
+        if (existing) {
+            clearTimeout(existing.timeoutId);
+            this.#cache.delete(path);
+        }
+        else if (this.#cache.size >= this.maxSize) {
+            this.evict();
+        }
+        const timeoutId = setTimeout(() => {
+            const cached = this.#cache.get(path);
+            if (!cached)
+                return;
+            clearTimeout(cached.timeoutId);
+            this.#cache.delete(path);
+        }, this.ttl);
+        this.#cache.set(path, { promise, timeoutId });
+    }
+    /**
+     * Removes the cached response for the given path and clears the associated timeout
+     */
+    remove(path) {
+        const cached = this.#cache.get(path);
+        if (!cached)
+            return;
+        clearTimeout(cached.timeoutId);
+        this.#cache.delete(path);
+    }
+    /**
+     * Clears the entire cache and all associated timeouts
+     */
+    clear() {
+        for (const entry of this.#cache.values()) {
+            clearTimeout(entry.timeoutId);
+        }
+        this.#cache.clear();
+    }
+    [Symbol.dispose]() {
+        this.clear();
+    }
+}

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

@@ -0,0 +1,174 @@
+import type { ImportMap, Manifest, ManifestEntry, Primitive, View } from '../../types';
+import type { Router } from './router';
+import { Metadata } from '../metadata';
+import { HttpException } from '../navigation/http-exception';
+export declare namespace Resolver {
+    type ReconciledMatch = ReturnType<Resolver['reconcile']>;
+    type CachedEnhancedMatch = Omit<EnhancedMatch, 'params' | 'error'>;
+    type EnhancedMatch = ReconciledMatch & {
+        ui: {
+            layouts: (View<{
+                children?: React.ReactNode;
+                params?: Router.Params;
+            }> | null)[];
+            Page: View<{
+                children?: React.ReactNode;
+                params?: Router.Params;
+            }> | null;
+            '401s': (View<{
+                children?: React.ReactNode;
+                error?: HttpException;
+            }> | null)[];
+            '403s': (View<{
+                children?: React.ReactNode;
+                error?: HttpException;
+            }> | null)[];
+            '404s': (View<{
+                children?: React.ReactNode;
+                error?: HttpException;
+            }> | null)[];
+            '500s': (View<{
+                children?: React.ReactNode;
+                error?: HttpException;
+            }> | null)[];
+            loaders: (View<{
+                children?: React.ReactNode;
+            }> | null)[];
+        };
+        error?: HttpException | Error;
+        endpoint?: (req?: Request & {
+            params?: Router.Params;
+        }) => unknown;
+        metadata?: (input: Metadata.Input<Router.Params>) => Metadata.Task[];
+    };
+}
+/**
+ * Resolve router matches against the application manifest and import map
+ */
+export declare class Resolver {
+    #private;
+    /**
+     * @see {@link Manifest} for the structure of the manifest
+     * @see {@link ImportMap} for the structure of the import map
+     */
+    constructor(manifest: Manifest, importMap: ImportMap);
+    /**
+     * Narrow down a route entry to a page entry if it exists
+     */
+    static narrow(entry?: ManifestEntry | ManifestEntry[]): import("../..").Segment | null;
+    /**
+     * Get the status code for a matched route that may or may not have errored
+     */
+    static getMatchStatusCode(match: Resolver.ReconciledMatch | Resolver.EnhancedMatch | null): 200 | HttpException.StatusCode;
+    /**
+     * Reconcile a router match against a manifest entry
+     */
+    reconcile(path: string, match: Router.Match | null, error?: Error): {
+        params: Router.Params;
+        error: Error | undefined;
+        __id: string;
+        __path: string;
+        __params: string[];
+        __kind: "$P";
+        __depth: number;
+        method: "get";
+        paths: {
+            layouts: (string | null)[];
+            '401s': (string | null)[];
+            '403s': (string | null)[];
+            '404s': (string | null)[];
+            '500s': (string | null)[];
+            loaders: (string | null)[];
+            middlewares: (string | null)[];
+            page?: string | null | undefined;
+        };
+        prerender: "full" | "ppr" | false;
+        dynamic: boolean;
+        wildcard: boolean;
+    } | {
+        params: {};
+        error: HttpException;
+        __id: string;
+        __path: string;
+        __params: string[];
+        __kind: "$P";
+        __depth: number;
+        method: "get";
+        paths: {
+            layouts: (string | null)[];
+            '401s': (string | null)[];
+            '403s': (string | null)[];
+            '404s': (string | null)[];
+            '500s': (string | null)[];
+            loaders: (string | null)[];
+            middlewares: (string | null)[];
+            page?: string | null | undefined;
+        };
+        prerender: "full" | "ppr" | false;
+        dynamic: boolean;
+        wildcard: boolean;
+    } | null;
+    /**
+     * Enhance a matched route with its associated components
+     */
+    enhance(match: Resolver.ReconciledMatch | null): {
+        ui: {
+            layouts: (View<{
+                children?: import("react").ReactNode;
+                params?: Router.Params | undefined;
+            }> | null)[];
+            Page: View<{
+                children?: import("react").ReactNode;
+                params?: Router.Params | undefined;
+            }> | null;
+            '401s': (View<{
+                children?: import("react").ReactNode;
+                error?: HttpException | undefined;
+            }> | null)[];
+            '403s': (View<{
+                children?: import("react").ReactNode;
+                error?: HttpException | undefined;
+            }> | null)[];
+            '404s': (View<{
+                children?: import("react").ReactNode;
+                error?: HttpException | undefined;
+            }> | null)[];
+            '500s': (View<{
+                children?: import("react").ReactNode;
+                error?: HttpException | undefined;
+            }> | null)[];
+            loaders: (View<{
+                children?: import("react").ReactNode;
+            }> | null)[];
+        };
+        endpoint?: ((req?: (Request & {
+            params?: Router.Params | undefined;
+        }) | undefined) => unknown) | undefined;
+        metadata?: ((input: Metadata.Input<Router.Params, Error>) => Metadata.Task[]) | undefined;
+        params: Router.Params | {};
+        error: Error | HttpException | undefined;
+        __id: string;
+        __path: string;
+        __params: string[];
+        __kind: "$P";
+        __depth: number;
+        method: "get";
+        paths: {
+            layouts: (string | null)[];
+            '401s': (string | null)[];
+            '403s': (string | null)[];
+            '404s': (string | null)[];
+            '500s': (string | null)[];
+            loaders: (string | null)[];
+            middlewares: (string | null)[];
+            page?: string | null | undefined;
+        };
+        prerender: "full" | "ppr" | false;
+        dynamic: boolean;
+        wildcard: boolean;
+    } | null;
+    /**
+     * Find the closest ancestor entry for a given path and property
+     */
+    closest(path: string, property: string, value?: Omit<Primitive, 'undefined'>): import("../..").Segment | null;
+}