@jk2908/solas 0.1.0

package/dist/internal/router/router.js

@@ -0,0 +1,417 @@
+import path from 'node:path';
+import { match as createMatch } from 'path-to-regexp';
+import { Solas } from '../../solas';
+import { maybeActionWithParsedFormData } from '../env/rsc';
+import { HttpException } from '../navigation/http-exception';
+import { toPathPattern } from './pattern';
+/**
+ * Handle routing and matching for server requests
+ */
+export class Router {
+    opts;
+    static #matchers = new WeakMap();
+    #routes = {
+        // exact match by method + path
+        static: new Map(),
+        dynamic: {
+            // candidate routes bucketed by segment length
+            byLength: new Map(),
+            // fast path for static prefixes
+            byPrefix: new Map(),
+        },
+        // wildcard routes checked last, narrowed by first literal segment when possible
+        wildcard: {
+            byPrefix: new Map(),
+            fallback: [],
+        },
+    };
+    #middleware = { global: [] };
+    #onError;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.fetch = this.fetch.bind(this);
+    }
+    /**
+     * Register middleware for all routes
+     */
+    use(...middleware) {
+        this.#middleware.global.push(...middleware);
+        return this;
+    }
+    /**
+     * Register an error handler for routing failures
+     */
+    error(handler) {
+        this.#onError = handler;
+        return this;
+    }
+    /**
+     * Register a route handler
+     */
+    add(path, method, handler, params, middleware = []) {
+        const segments = Router.#split(path);
+        const tokens = [];
+        let score = 0;
+        let wildcard = false;
+        // turn the route path into tokens once so registration and matching can
+        // share the same specificity rules
+        for (const segment of segments) {
+            if (segment === '*') {
+                wildcard = true;
+                tokens.push({ kind: 'wildcard', value: params?.[0] ?? '*' });
+                continue;
+            }
+            if (segment.startsWith(':')) {
+                tokens.push({ kind: 'dynamic', value: segment.slice(1) });
+                score += 1;
+                continue;
+            }
+            tokens.push({ kind: 'static', value: segment });
+            score += 2;
+        }
+        const route = {
+            path,
+            method: method.toUpperCase(),
+            handler,
+            middleware: [...middleware],
+            tokens,
+            length: segments.length,
+            score,
+            wildcard,
+        };
+        // static route, easy map set
+        if (!path.includes(':') && !path.includes('*')) {
+            this.#routes.static.set(`${route.method}:${path}`, route);
+            return this;
+        }
+        // wildcard route, push to end of list
+        if (wildcard) {
+            const prefix = route.tokens[0]?.kind === 'static' ? route.tokens[0].value : undefined;
+            if (prefix) {
+                const prefixed = this.#routes.wildcard.byPrefix.get(prefix) ?? [];
+                prefixed.push(route);
+                this.#routes.wildcard.byPrefix.set(prefix, prefixed);
+            }
+            else {
+                this.#routes.wildcard.fallback.push(route);
+            }
+            return this;
+        }
+        // dynamic routes are looked up through two indexes; one grouped
+        // by segment count, and one grouped by the first static segment
+        const bucket = this.#routes.dynamic.byLength.get(route.length) ?? [];
+        bucket.push(route);
+        this.#routes.dynamic.byLength.set(route.length, bucket);
+        // only routes that start with a literal segment go into the prefix index.
+        // Routes that start dynamically still fall back to the length-based
+        // lookup, so this shortcut doesn't accidentally skip a better match
+        const prefix = route.tokens[0]?.kind === 'static' ? route.tokens[0].value : undefined;
+        if (prefix) {
+            const prefixed = this.#routes.dynamic.byPrefix.get(prefix) ?? [];
+            prefixed.push(route);
+            this.#routes.dynamic.byPrefix.set(prefix, prefixed);
+        }
+        return this;
+    }
+    /**
+     * Match a path and method, returning params and route
+     */
+    match(path, method) {
+        const direct = this.#routes.static.get(`${method}:${path}`);
+        // direct match - quick return
+        if (direct)
+            return { route: direct, params: {} };
+        // HEAD falls back to GET when HEAD is not explicitly defined
+        if (method === 'HEAD') {
+            const directGet = this.#routes.static.get(`GET:${path}`);
+            if (directGet)
+                return { route: directGet, params: {} };
+        }
+        // else dynamic/wildcard match
+        const segments = Router.#split(path);
+        // try the leading-static prefix bucket first
+        const prefixed = this.#routes.dynamic.byPrefix.get(segments[0] ?? '');
+        const prefixedMatch = prefixed ? Router.#pick(prefixed, segments, method) : null;
+        if (prefixedMatch)
+            return prefixedMatch;
+        // if the prefix bucket has no winner, fall back to all dynamic
+        // routes with the same segment count
+        const dynamicMatch = Router.#pick(this.#routes.dynamic.byLength.get(segments.length) ?? [], segments, method);
+        if (dynamicMatch)
+            return dynamicMatch;
+        // finally check wildcard routes, prefixed first, then fully generic ones
+        const wildcardPrefixed = this.#routes.wildcard.byPrefix.get(segments[0] ?? '');
+        const wildcardMatch = wildcardPrefixed
+            ? Router.#pick(wildcardPrefixed, segments, method)
+            : null;
+        if (wildcardMatch)
+            return wildcardMatch;
+        const wildcardFallbackMatch = Router.#pick(this.#routes.wildcard.fallback, segments, method);
+        if (wildcardFallbackMatch)
+            return wildcardFallbackMatch;
+        // no match
+        return null;
+    }
+    /**
+     * Handle an incoming request
+     */
+    async fetch(req) {
+        const url = new URL(req.url);
+        const path = Router.#normalise(url.pathname, this.opts.trailingSlash);
+        let match = null;
+        let action = false;
+        try {
+            if (path !== url.pathname) {
+                // rebuild the request with the canonical pathname so downstream code
+                // sees the same url the router matched against
+                url.pathname = path;
+                req = new Request(url.toString(), req);
+            }
+            const { action: isAction, formData: parsedFormData } = await maybeActionWithParsedFormData(req);
+            action = isAction;
+            const method = req.method.toUpperCase();
+            // action requests stay on the same pathname only the method is
+            // normalised to GET this lets page/layout routes match for
+            // rerender action execution still reads POST body and
+            // may redirect()
+            match = this.match(path, action ? 'GET' : method);
+            if (!match) {
+                const error = new HttpException(404, 'Not found');
+                // unmatched requests still pass through the shared error hook with the
+                // same request metadata shape as matched requests
+                return (this.#onError?.(error, Object.assign(req, {
+                    [Solas.Config.REQUEST_META]: { match: null, error, action },
+                })) ?? new Response(error.message, { status: error.status }));
+            }
+            const matched = match;
+            // attach routing state to the request once so middleware and handlers can
+            // read the same per-request metadata
+            const request = Object.assign(req, {
+                [Solas.Config.REQUEST_META]: { match: matched, action, parsedFormData },
+            });
+            // global middleware stays outside route middleware by preserving
+            // registration order here before composition in #run
+            const stack = [...this.#middleware.global, ...matched.route.middleware];
+            return this.#run(stack, request, () => matched.route.handler?.(request) ?? new Response('Not found', { status: 404 }));
+        }
+        catch (err) {
+            // normalise unknown throwables so the error hook always receives an Error
+            const error = err instanceof Error ? err : new Error(String(err), { cause: err });
+            const request = Object.assign(req, {
+                [Solas.Config.REQUEST_META]: { match, error, action },
+            });
+            if (this.#onError)
+                return this.#onError(error, request);
+            if (error instanceof HttpException) {
+                return new Response(error.message, { status: error.status });
+            }
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    }
+    /**
+     * Run middleware stack
+     */
+    #run(stack, req, next) {
+        // compose middleware stack
+        let run = () => Promise.resolve(next());
+        // unwind stack
+        for (let i = stack.length - 1; i >= 0; i -= 1) {
+            const handler = stack[i];
+            const prev = run;
+            run = () => Promise.resolve(handler(req, prev));
+        }
+        // run composed middleware stack
+        return run();
+    }
+    /**
+     * Serve static assets from the output directory
+     * @note generated /assets/* handlers bypass +middleware conventions
+     */
+    static static(config) {
+        return async (req) => {
+            const pathname = new URL(req.url).pathname;
+            const outDir = path.resolve(Solas.Config.OUT_DIR);
+            const staticRoot = path.resolve(outDir, 'client');
+            let decodedPathname = pathname;
+            try {
+                // validate any percent-encoding before resolving the asset path
+                decodedPathname = decodeURIComponent(pathname);
+            }
+            catch {
+                return new Response('Bad Request', { status: 400 });
+            }
+            const relativePath = decodedPathname.replace(/^\/+/, '');
+            const filePath = path.resolve(staticRoot, relativePath);
+            // keep asset requests pinned under the client output root even if the
+            // incoming path contains traversal segments
+            if (filePath !== staticRoot && !filePath.startsWith(`${staticRoot}${path.sep}`)) {
+                return new Response('Forbidden', { status: 403 });
+            }
+            // emitted assets are fingerprinted so they can be cached aggressively
+            return Router.serve(filePath, req, config.precompress, {
+                'Cache-Control': 'public, immutable, max-age=31536000',
+            });
+        };
+    }
+    /**
+     * Serve a file with optional compression content negotiation
+     */
+    static async serve(filePath, req, precompress = false, headers = {}) {
+        const accept = req.headers.get('accept-encoding') ?? '';
+        let file = Bun.file(filePath);
+        let encoding = null;
+        if (precompress) {
+            // prefer a precompressed variant when the client accepts it and one was emitted
+            if (accept.includes('br')) {
+                const brotli = Bun.file(`${filePath}.br`);
+                if (await brotli.exists()) {
+                    file = brotli;
+                    encoding = 'br';
+                }
+            }
+        }
+        if (!(await file.exists())) {
+            return new Response('Not found', { status: 404 });
+        }
+        // get mime type from original path, not compressed variant
+        const mimeType = Bun.file(filePath).type;
+        const res = new Response(file, {
+            headers: {
+                'Content-Type': headers['Content-Type'] ?? mimeType,
+            },
+        });
+        for (const [key, value] of Object.entries(headers)) {
+            res.headers.set(key, value);
+        }
+        if (precompress)
+            res.headers.set('Vary', 'Accept-Encoding');
+        if (encoding)
+            res.headers.set('Content-Encoding', encoding);
+        return res;
+    }
+    /**
+     * Normalise a path based on router options
+     */
+    static #normalise(path, trailingSlash = true) {
+        if (!trailingSlash) {
+            // collapse non-root trailing slashes when the router runs in slashless mode
+            return path.endsWith('/') && path !== '/' ? path.slice(0, -1) : path;
+        }
+        if (path === '/')
+            return path;
+        // otherwise make non-root paths canonical with a trailing slash
+        return path.endsWith('/') ? path : `${path}/`;
+    }
+    /**
+     * Split a path into segments
+     */
+    static #split(path) {
+        if (path === '/')
+            return [];
+        const parts = [];
+        let start = 0;
+        // walk the string once so we avoid empty segments from repeated or edge slashes
+        for (let i = 0; i <= path.length; i += 1) {
+            const char = path[i];
+            if (char !== '/' && i !== path.length)
+                continue;
+            if (i > start) {
+                parts.push(path.slice(start, i));
+            }
+            start = i + 1;
+        }
+        return parts;
+    }
+    /**
+     * Get or create a path matcher for a route using path-to-regexp
+     */
+    static #getMatcher(route) {
+        const cached = Router.#matchers.get(route);
+        if (cached)
+            return cached;
+        // convert route tokens back into a path pattern for path-to-regexp to compile
+        const { path } = toPathPattern(route.path, route.tokens.filter(token => token.kind !== 'static').map(token => token.value));
+        // create a matcher function for this route and cache it
+        const matcher = createMatch(path, {
+            decode: false,
+        });
+        Router.#matchers.set(route, matcher);
+        return matcher;
+    }
+    /**
+     * Rank token kinds so more specific segments win before broader ones
+     */
+    static #getTokenRank(token) {
+        if (!token)
+            return -1;
+        if (token.kind === 'static')
+            return 2;
+        if (token.kind === 'dynamic')
+            return 1;
+        return 0;
+    }
+    /**
+     * Compare two routes and prefer the one with the more specific segment pattern
+     */
+    static #compare(a, b) {
+        const length = Math.max(a.tokens.length, b.tokens.length);
+        for (let index = 0; index < length; index += 1) {
+            // prefer static over dynamic and dynamic over wildcard at the
+            // first segment position where the two routes differ
+            const diff = Router.#getTokenRank(a.tokens[index]) - Router.#getTokenRank(b.tokens[index]);
+            if (diff !== 0)
+                return diff;
+        }
+        // if the token kinds line up, reuse the old coarse score
+        if (a.score !== b.score)
+            return a.score - b.score;
+        // final stable tie-break for routes with the same pattern shape
+        // sort alphabetically by path string
+        return a.path < b.path ? 1 : a.path > b.path ? -1 : 0;
+    }
+    /**
+     * Find the best matching route from a candidate list using explicit specificity rules
+     */
+    static #pick(routes, segments, method) {
+        let best = null;
+        let bestParams = null;
+        for (const route of routes) {
+            // HEAD can reuse GET routes when HEAD is not registered explicitly
+            if (route.method !== method && !(method === 'HEAD' && route.method === 'GET')) {
+                continue;
+            }
+            // skip routes that do not fit this path. Only compare specificity
+            // across matched routes
+            const params = Router.#fit(route, segments);
+            if (!params)
+                continue;
+            // replace the winner only when this route is strictly more specific
+            if (!best || Router.#compare(route, best) > 0) {
+                best = route;
+                bestParams = params;
+            }
+        }
+        if (!best)
+            return null;
+        return { route: best, params: bestParams ?? {} };
+    }
+    /**
+     * Fit a route against path segments
+     */
+    static #fit(route, segments) {
+        if (route.wildcard) {
+            // wildcard routes only require the fixed prefix before the catch-all segment
+            if (segments.length < route.length - 1)
+                return null;
+        }
+        else if (route.length !== segments.length) {
+            return null;
+        }
+        // defer the actual param extraction to the cached path-to-regexp matcher so
+        // dynamic and wildcard params stay consistent with registration
+        const matched = Router.#getMatcher(route)(segments.length ? `/${segments.join('/')}` : '/');
+        if (!matched)
+            return null;
+        return matched.params;
+    }
+}

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

@@ -0,0 +1,5 @@
+export declare function useRouter(): {
+    go: (to: string, opts?: import("./router-context").Navigation.GoOptions | undefined) => Promise<string>;
+    prefetch: (path: string) => void;
+    isNavigating: boolean;
+};

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

@@ -0,0 +1,5 @@
+import { use } from 'react';
+import { RouterContext } from './router-context';
+export function useRouter() {
+    return use(RouterContext);
+}

package/dist/internal/server/cookies.d.ts

@@ -0,0 +1,6 @@
+import { Cookies } from '../../utils/cookies';
+/**
+ * Get the request cookies as a Cookies instance
+ * @returns a read-only Cookies instance containing the request cookies
+ */
+export declare function cookies(): Readonly<ReturnType<typeof Cookies.parse>>;

package/dist/internal/server/cookies.js

@@ -0,0 +1,17 @@
+import { Cookies } from '../../utils/cookies';
+import { RequestContext } from '../env/request-context';
+import { dynamic } from './dynamic';
+/**
+ * Get the request cookies as a Cookies instance
+ * @returns a read-only Cookies instance containing the request cookies
+ */
+export function cookies() {
+    dynamic();
+    const { req, cache } = RequestContext.use();
+    // use request cache if possible to avoid reparsing
+    if (cache.cookies)
+        return cache.cookies;
+    const parsed = Cookies.parse(req.headers.get('cookie'));
+    cache.cookies = parsed;
+    return parsed;
+}

package/dist/internal/server/dynamic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Declaratively mark render below this call as request-time only
+ * @description in prerender mode this suspends forever so the nearest Suspense
+ * boundary renders its fallback into the static shell. In request mode this
+ * resolves immediately
+ * @returns void during normal requests or prerender not in ppr mode
+ * @throws if called in prerender mode (the desired effect)
+ */
+export declare function dynamic(): void;

package/dist/internal/server/dynamic.js

@@ -0,0 +1,22 @@
+import { Logger } from '../../utils/logger';
+import { RequestContext } from '../env/request-context';
+const logger = new Logger();
+const NEVER = new Promise(() => { });
+/**
+ * Declaratively mark render below this call as request-time only
+ * @description in prerender mode this suspends forever so the nearest Suspense
+ * boundary renders its fallback into the static shell. In request mode this
+ * resolves immediately
+ * @returns void during normal requests or prerender not in ppr mode
+ * @throws if called in prerender mode (the desired effect)
+ */
+export function dynamic() {
+    const { prerender } = RequestContext.use();
+    if (!prerender)
+        return;
+    if (prerender !== 'ppr') {
+        logger.warn('[dynamic]', "dynamic() was called but prerender mode is not 'ppr'. This means the component will be rendered at build time, which may not be what you intended");
+        return;
+    }
+    throw NEVER;
+}

package/dist/internal/server/headers.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get the request headers as a read-only map
+ * @returns a read-only map of request headers
+ */
+export declare function headers(): ReadonlyMap<string, string>;

package/dist/internal/server/headers.js

@@ -0,0 +1,19 @@
+import { RequestContext } from '../env/request-context';
+import { dynamic } from './dynamic';
+/**
+ * Get the request headers as a read-only map
+ * @returns a read-only map of request headers
+ */
+export function headers() {
+    dynamic();
+    const { req, cache } = RequestContext.use();
+    // use request cache if possible to avoid reconstructing the map
+    if (cache.headers)
+        return cache.headers;
+    const map = new Map();
+    req.headers.forEach((value, key) => {
+        map.set(key, value);
+    });
+    cache.headers = map;
+    return map;
+}

package/dist/internal/server/url.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get the request url as a URL instance
+ * @returns a URL instance containing the request url
+ */
+export declare function url(): URL;

package/dist/internal/server/url.js

@@ -0,0 +1,16 @@
+import { RequestContext } from '../env/request-context';
+import { dynamic } from './dynamic';
+/**
+ * Get the request url as a URL instance
+ * @returns a URL instance containing the request url
+ */
+export function url() {
+    dynamic();
+    const { req, cache } = RequestContext.use();
+    // use request cache if possible
+    if (cache.url)
+        return cache.url;
+    const parsed = new URL(req.url);
+    cache.url = parsed;
+    return parsed;
+}

package/dist/internal/ui/defaults/error.d.ts

@@ -0,0 +1,4 @@
+import type { HttpException } from '../../navigation/http-exception';
+export default function Err({ error }: {
+    error: HttpException | Error;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/internal/ui/defaults/error.js

@@ -0,0 +1,6 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export default function Err({ error }) {
+    const title = 'status' in error ? `${error.status} - ${error.message}` : error.message;
+    return (_jsxs(_Fragment, { children: [
+            _jsx("meta", { name: "robots", content: "noindex,nofollow" }), _jsx("title", { children: title }), _jsx("h1", { children: title }), _jsx("p", { children: error.message }), error?.stack && _jsx("pre", { children: error.stack })] }));
+}

package/dist/internal/ui/error-boundary.d.ts

@@ -0,0 +1,26 @@
+import { Component } from 'react';
+import type { BoundaryError } from '../../types';
+export type Props = {
+    fallback: ((error: BoundaryError, reset: () => void) => React.ReactNode) | React.ReactNode;
+    onError?: (error: BoundaryError) => void;
+    children: React.ReactNode;
+};
+/**
+ * A component that catches synchronous errors in its child component tree and displays a fallback UI
+ * @param props - the props for the component
+ * @param props.fallback - the fallback UI to display when an error occurs, can be a function, React node or component
+ * @param props.onReset - a callback function to call when the error is reset
+ * @param props.children - the child components to render
+ * @returns Component
+ */
+export declare class ErrorBoundary extends Component<Props, {
+    error: BoundaryError | null;
+}> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    componentDidCatch(error: Error): void;
+    reset(onReset?: () => void): void;
+    render(): import("react").ReactNode;
+}

package/dist/internal/ui/error-boundary.js

@@ -0,0 +1,41 @@
+'use client';
+import { Component } from 'react';
+import { isKnownError } from '../env/utils';
+/**
+ * A component that catches synchronous errors in its child component tree and displays a fallback UI
+ * @param props - the props for the component
+ * @param props.fallback - the fallback UI to display when an error occurs, can be a function, React node or component
+ * @param props.onReset - a callback function to call when the error is reset
+ * @param props.children - the child components to render
+ * @returns Component
+ */
+export class ErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { error: null };
+        this.reset = this.reset.bind(this);
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error) {
+        this.props.onError?.(error);
+    }
+    reset(onReset) {
+        if (this.state.error)
+            this.setState({ error: null });
+        onReset?.();
+    }
+    render() {
+        const { error } = this.state;
+        if (!error)
+            return this.props.children;
+        // possible framework control-flow error, re-throw to be caught
+        // by appropriate HttpException or Redirect boundaries
+        if (isKnownError(error))
+            throw error;
+        return typeof this.props.fallback === 'function'
+            ? this.props.fallback(error, this.reset)
+            : this.props.fallback;
+    }
+}

package/dist/navigation.d.ts

@@ -0,0 +1,6 @@
+export { HttpException, abort, isHttpException, } from './internal/navigation/http-exception';
+export { HttpExceptionBoundary } from './internal/navigation/http-exception-boundary';
+export { Link } from './internal/navigation/link';
+export { Redirect, isRedirect, redirect } from './internal/navigation/redirect';
+export { RedirectBoundary } from './internal/navigation/redirect-boundary';
+export { useSearchParams } from './internal/navigation/use-search-params';

package/dist/navigation.js

@@ -0,0 +1,6 @@
+export { HttpException, abort, isHttpException, } from './internal/navigation/http-exception';
+export { HttpExceptionBoundary } from './internal/navigation/http-exception-boundary';
+export { Link } from './internal/navigation/link';
+export { Redirect, isRedirect, redirect } from './internal/navigation/redirect';
+export { RedirectBoundary } from './internal/navigation/redirect-boundary';
+export { useSearchParams } from './internal/navigation/use-search-params';

package/dist/prerender.d.ts

@@ -0,0 +1 @@
+export { Prerender } from './internal/prerender';

package/dist/prerender.js

@@ -0,0 +1 @@
+export { Prerender } from './internal/prerender';

package/dist/router.d.ts

@@ -0,0 +1,4 @@
+export { createRouter } from './internal/router/create-router';
+export { Router } from './internal/router/router';
+export { RouterProvider } from './internal/router/router-provider';
+export { useRouter } from './internal/router/use-router';

package/dist/router.js

@@ -0,0 +1,4 @@
+export { createRouter } from './internal/router/create-router';
+export { Router } from './internal/router/router';
+export { RouterProvider } from './internal/router/router-provider';
+export { useRouter } from './internal/router/use-router';

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+export { cookies } from './internal/server/cookies';
+export { dynamic } from './internal/server/dynamic';
+export { headers } from './internal/server/headers';
+export { url } from './internal/server/url';

package/dist/server.js

@@ -0,0 +1,4 @@
+export { cookies } from './internal/server/cookies';
+export { dynamic } from './internal/server/dynamic';
+export { headers } from './internal/server/headers';
+export { url } from './internal/server/url';