@vistagenic/vista 0.2.16 → 0.3.2

package/dist/server/route-handler-registry.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Discovery and resolution of file-based API route handlers (`app/**\/route.{ts,tsx,js,jsx}`).
+ *
+ * One scan implementation serves both sides of the framework:
+ *   - the build scanner (build/rsc/server-manifest.ts) records what exists, so route
+ *     handlers land in the emitted manifests alongside pages
+ *   - the request path (server/typed-api-runtime.ts) resolves a URL to a handler file
+ *     plus its dynamic params
+ *
+ * Keeping them on the same function is what stops the build manifest and the runtime
+ * from disagreeing about which files are routes.
+ */
+import { type ParsedRoute, type RouteParams, type RouteSegmentType } from './route-patterns';
+/** Supported HTTP methods for a route handler, in canonical order. */
+export declare const ROUTE_HANDLER_METHODS: readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+export type RouteHandlerMethod = (typeof ROUTE_HANDLER_METHODS)[number];
+export interface DiscoveredRouteHandler {
+    /** URL pattern, e.g. `/api/users/:id`. */
+    pattern: string;
+    /** Absolute path of the route file. */
+    filePath: string;
+    /** Filesystem segments from `app/` to the route file's directory. */
+    sourceSegments: string[];
+    /** Route shape, using the same vocabulary as page routes. */
+    type: RouteSegmentType;
+    /** HTTP methods the file appears to export. */
+    methods: RouteHandlerMethod[];
+    /** Runtime requested via `export const runtime`, when present. */
+    runtime?: string;
+    /** Parsed segments, retained so the resolver does not re-parse per request. */
+    parsed: ParsedRoute;
+}
+export interface ResolvedRouteHandler {
+    filePath: string;
+    pattern: string;
+    params: RouteParams;
+}
+/**
+ * Scan an app directory for route handler files.
+ *
+ * Results are ordered most-specific first, so the first match during resolution is
+ * the correct one.
+ */
+export declare function discoverRouteHandlers(appDir: string): DiscoveredRouteHandler[];
+/**
+ * Cached variant of {@link discoverRouteHandlers}.
+ *
+ * Production builds scan once. Dev re-scans at most every {@link DEV_SCAN_TTL_MS},
+ * which keeps newly added route files visible without turning every request into a
+ * full directory walk.
+ */
+export declare function getRouteHandlers(appDir: string, options?: {
+    isDev?: boolean;
+}): DiscoveredRouteHandler[];
+/** Drop cached discovery results. Exported for tests and for watch-mode invalidation. */
+export declare function clearRouteHandlerCache(appDir?: string): void;
+/**
+ * Resolve a request path to a route handler file and its dynamic params.
+ *
+ * Returns null when no route file matches, leaving the caller free to fall through to
+ * pages, the typed API, or a 404.
+ */
+export declare function resolveRouteHandler(appDir: string, requestPath: string, options?: {
+    isDev?: boolean;
+}): ResolvedRouteHandler | null;

package/dist/server/route-handler-registry.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Discovery and resolution of file-based API route handlers (`app/**\/route.{ts,tsx,js,jsx}`).
+ *
+ * One scan implementation serves both sides of the framework:
+ *   - the build scanner (build/rsc/server-manifest.ts) records what exists, so route
+ *     handlers land in the emitted manifests alongside pages
+ *   - the request path (server/typed-api-runtime.ts) resolves a URL to a handler file
+ *     plus its dynamic params
+ *
+ * Keeping them on the same function is what stops the build manifest and the runtime
+ * from disagreeing about which files are routes.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTE_HANDLER_METHODS = void 0;
+exports.discoverRouteHandlers = discoverRouteHandlers;
+exports.getRouteHandlers = getRouteHandlers;
+exports.clearRouteHandlerCache = clearRouteHandlerCache;
+exports.resolveRouteHandler = resolveRouteHandler;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const route_patterns_1 = require("./route-patterns");
+/** Supported HTTP methods for a route handler, in canonical order. */
+exports.ROUTE_HANDLER_METHODS = [
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+];
+const ROUTE_FILE_BASENAMES = new Set(['route']);
+const ROUTE_FILE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx']);
+const SKIPPED_DIRECTORIES = new Set(['node_modules']);
+/** How long a discovery result is reused in dev before the app dir is re-scanned. */
+const DEV_SCAN_TTL_MS = 250;
+function isRouteFile(fileName) {
+    const extension = path_1.default.extname(fileName);
+    if (!ROUTE_FILE_EXTENSIONS.has(extension)) {
+        return false;
+    }
+    return ROUTE_FILE_BASENAMES.has(path_1.default.basename(fileName, extension));
+}
+/**
+ * Read the exported HTTP methods and requested runtime without executing the module.
+ *
+ * Regex-based on purpose: this mirrors how build/rsc/server-manifest.ts already reads
+ * exports, runs during a filesystem walk, and only feeds the manifest. The runtime
+ * dispatch path reads the real module exports, so a miss here degrades the manifest,
+ * never the request.
+ */
+function readRouteFileMetadata(filePath) {
+    let source = '';
+    try {
+        source = fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return { methods: [] };
+    }
+    const methods = [];
+    for (const method of exports.ROUTE_HANDLER_METHODS) {
+        const declaration = new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+${method}\\b`);
+        const braced = new RegExp(`export\\s*\\{[^}]*\\b${method}\\b[^}]*\\}`);
+        if (declaration.test(source) || braced.test(source)) {
+            methods.push(method);
+        }
+    }
+    const runtimeMatch = /export\s+const\s+runtime\s*=\s*['"]([\w-]+)['"]/.exec(source);
+    return {
+        methods,
+        runtime: runtimeMatch ? runtimeMatch[1] : undefined,
+    };
+}
+function walkForRouteFiles(dir, appDir, results) {
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.') || SKIPPED_DIRECTORIES.has(entry.name)) {
+                continue;
+            }
+            // Parallel slots and interception routes are page-tree concepts; a route
+            // handler underneath one is not reachable by URL.
+            if ((0, route_patterns_1.isParallelRouteSegment)(entry.name) || (0, route_patterns_1.isInterceptionRouteSegment)(entry.name)) {
+                continue;
+            }
+            walkForRouteFiles(fullPath, appDir, results);
+            continue;
+        }
+        if (!entry.isFile() || !isRouteFile(entry.name)) {
+            continue;
+        }
+        const relativeDir = path_1.default.relative(appDir, dir);
+        const sourceSegments = relativeDir
+            .split(path_1.default.sep)
+            .filter((segment) => segment && segment !== '.');
+        const parsed = (0, route_patterns_1.parseRouteSegments)(sourceSegments);
+        if (!parsed) {
+            continue;
+        }
+        const metadata = readRouteFileMetadata(fullPath);
+        results.push({
+            pattern: parsed.pattern,
+            filePath: fullPath,
+            sourceSegments,
+            type: parsed.type,
+            methods: metadata.methods,
+            runtime: metadata.runtime,
+            parsed,
+        });
+    }
+}
+/**
+ * Scan an app directory for route handler files.
+ *
+ * Results are ordered most-specific first, so the first match during resolution is
+ * the correct one.
+ */
+function discoverRouteHandlers(appDir) {
+    if (!appDir || !fs_1.default.existsSync(appDir)) {
+        return [];
+    }
+    const results = [];
+    walkForRouteFiles(appDir, appDir, results);
+    // A directory can hold at most one route file; if several extensions exist, keep a
+    // deterministic winner rather than letting readdir order decide.
+    const byPattern = new Map();
+    for (const entry of results) {
+        const existing = byPattern.get(entry.pattern);
+        if (!existing || entry.filePath.localeCompare(existing.filePath) < 0) {
+            byPattern.set(entry.pattern, entry);
+        }
+    }
+    return Array.from(byPattern.values()).sort((a, b) => (0, route_patterns_1.compareRouteSpecificity)(a.parsed, b.parsed));
+}
+const discoveryCache = new Map();
+/**
+ * Cached variant of {@link discoverRouteHandlers}.
+ *
+ * Production builds scan once. Dev re-scans at most every {@link DEV_SCAN_TTL_MS},
+ * which keeps newly added route files visible without turning every request into a
+ * full directory walk.
+ */
+function getRouteHandlers(appDir, options = {}) {
+    const cached = discoveryCache.get(appDir);
+    const now = Date.now();
+    if (cached && (!options.isDev || now - cached.scannedAt < DEV_SCAN_TTL_MS)) {
+        return cached.handlers;
+    }
+    const handlers = discoverRouteHandlers(appDir);
+    discoveryCache.set(appDir, { handlers, scannedAt: now });
+    return handlers;
+}
+/** Drop cached discovery results. Exported for tests and for watch-mode invalidation. */
+function clearRouteHandlerCache(appDir) {
+    if (appDir) {
+        discoveryCache.delete(appDir);
+        return;
+    }
+    discoveryCache.clear();
+}
+/**
+ * Resolve a request path to a route handler file and its dynamic params.
+ *
+ * Returns null when no route file matches, leaving the caller free to fall through to
+ * pages, the typed API, or a 404.
+ */
+function resolveRouteHandler(appDir, requestPath, options = {}) {
+    const handlers = getRouteHandlers(appDir, options);
+    if (handlers.length === 0) {
+        return null;
+    }
+    const requestSegments = (0, route_patterns_1.splitRequestPath)(requestPath);
+    for (const handler of handlers) {
+        const params = (0, route_patterns_1.matchRouteSegments)(handler.parsed, requestSegments);
+        if (params) {
+            return {
+                filePath: handler.filePath,
+                pattern: handler.pattern,
+                params,
+            };
+        }
+    }
+    return null;
+}

package/dist/server/route-patterns.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Route pattern parsing and matching for file-based API route handlers.
+ *
+ * Shared by the build-time scanner (packages/vista/src/build/rsc/server-manifest.ts)
+ * and the request-time resolver (packages/vista/src/server/typed-api-runtime.ts) so
+ * both sides agree on what `app/api/users/[id]/route.ts` means.
+ *
+ * Patterns use the same `:name` / `:name*` shape the page router already emits, so
+ * `toRegexFromPattern()` in build/manifest.ts consumes them unchanged.
+ *
+ * This module is intentionally filesystem-free and framework-free: it is pure string
+ * work, which keeps it cheap to call per request and straightforward to test.
+ */
+/** A single parsed path segment of a route. */
+export type RouteSegment = {
+    kind: 'static';
+    value: string;
+} | {
+    kind: 'dynamic';
+    paramName: string;
+} | {
+    kind: 'catch-all';
+    paramName: string;
+    optional: boolean;
+};
+export type RouteSegmentType = 'static' | 'dynamic' | 'catch-all';
+export interface ParsedRoute {
+    /** URL pattern, e.g. `/api/users/:id` or `/api/files/:path*`. */
+    pattern: string;
+    /** Parsed segments in order, route groups already removed. */
+    segments: RouteSegment[];
+    /** Coarse route shape, matching the vocabulary the page router uses. */
+    type: RouteSegmentType;
+}
+export type RouteParams = Record<string, string | string[]>;
+/** `(marketing)` - grouping only, contributes nothing to the URL. */
+export declare function isRouteGroupSegment(segment: string): boolean;
+/** `@modal` - parallel route slot. Not addressable as an API route. */
+export declare function isParallelRouteSegment(segment: string): boolean;
+/** `(.)photo`, `(..)feed`, `(...)root` - interception routes. Not addressable either. */
+export declare function isInterceptionRouteSegment(segment: string): boolean;
+/**
+ * Turn filesystem segments (relative to `app/`) into a parsed route.
+ *
+ * Returns null when the path is not addressable as a URL - a parallel slot or an
+ * interception route. Route groups are dropped from the pattern but do not
+ * disqualify the route.
+ */
+export declare function parseRouteSegments(sourceSegments: string[]): ParsedRoute | null;
+/** Split a request pathname into segments, ignoring query string and trailing slash. */
+export declare function splitRequestPath(requestPath: string): string[];
+/**
+ * Match a parsed route against request path segments.
+ *
+ * Returns the extracted params, or null when the route does not match. A catch-all
+ * param is returned as a string array, mirroring the App Router's shape.
+ */
+export declare function matchRouteSegments(route: ParsedRoute, requestSegments: string[]): RouteParams | null;
+/**
+ * Ordering for route resolution: the most specific route wins.
+ *
+ * Static beats dynamic beats catch-all, compared segment by segment, so
+ * `/api/users/me` is preferred over `/api/users/[id]`, which is preferred over
+ * `/api/users/[...rest]`. Ties fall back to the pattern string for stable,
+ * platform-independent ordering.
+ */
+export declare function compareRouteSpecificity(a: ParsedRoute, b: ParsedRoute): number;

package/dist/server/route-patterns.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Route pattern parsing and matching for file-based API route handlers.
+ *
+ * Shared by the build-time scanner (packages/vista/src/build/rsc/server-manifest.ts)
+ * and the request-time resolver (packages/vista/src/server/typed-api-runtime.ts) so
+ * both sides agree on what `app/api/users/[id]/route.ts` means.
+ *
+ * Patterns use the same `:name` / `:name*` shape the page router already emits, so
+ * `toRegexFromPattern()` in build/manifest.ts consumes them unchanged.
+ *
+ * This module is intentionally filesystem-free and framework-free: it is pure string
+ * work, which keeps it cheap to call per request and straightforward to test.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRouteGroupSegment = isRouteGroupSegment;
+exports.isParallelRouteSegment = isParallelRouteSegment;
+exports.isInterceptionRouteSegment = isInterceptionRouteSegment;
+exports.parseRouteSegments = parseRouteSegments;
+exports.splitRequestPath = splitRequestPath;
+exports.matchRouteSegments = matchRouteSegments;
+exports.compareRouteSpecificity = compareRouteSpecificity;
+/** `(marketing)` - grouping only, contributes nothing to the URL. */
+function isRouteGroupSegment(segment) {
+    return segment.length > 2 && segment.startsWith('(') && segment.endsWith(')');
+}
+/** `@modal` - parallel route slot. Not addressable as an API route. */
+function isParallelRouteSegment(segment) {
+    return segment.startsWith('@');
+}
+/** `(.)photo`, `(..)feed`, `(...)root` - interception routes. Not addressable either. */
+function isInterceptionRouteSegment(segment) {
+    return /^\(\.{1,3}\)/.test(segment) || segment.startsWith('(..)(..)');
+}
+function parseSegment(segment) {
+    // [[...slug]] - optional catch-all, also matches the parent path.
+    const optionalCatchAll = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(segment);
+    if (optionalCatchAll) {
+        return { kind: 'catch-all', paramName: optionalCatchAll[1], optional: true };
+    }
+    // [...slug] - catch-all, requires at least one segment.
+    const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(segment);
+    if (catchAll) {
+        return { kind: 'catch-all', paramName: catchAll[1], optional: false };
+    }
+    // [id] - single dynamic segment.
+    const dynamic = /^\[([^\].]+)\]$/.exec(segment);
+    if (dynamic) {
+        return { kind: 'dynamic', paramName: dynamic[1] };
+    }
+    return { kind: 'static', value: segment };
+}
+function segmentToPatternPart(segment) {
+    switch (segment.kind) {
+        case 'static':
+            return segment.value;
+        case 'dynamic':
+            return `:${segment.paramName}`;
+        case 'catch-all':
+            return `:${segment.paramName}*${segment.optional ? '?' : ''}`;
+    }
+}
+/**
+ * Turn filesystem segments (relative to `app/`) into a parsed route.
+ *
+ * Returns null when the path is not addressable as a URL - a parallel slot or an
+ * interception route. Route groups are dropped from the pattern but do not
+ * disqualify the route.
+ */
+function parseRouteSegments(sourceSegments) {
+    const segments = [];
+    for (const rawSegment of sourceSegments) {
+        if (!rawSegment)
+            continue;
+        if (isParallelRouteSegment(rawSegment) || isInterceptionRouteSegment(rawSegment)) {
+            return null;
+        }
+        if (isRouteGroupSegment(rawSegment)) {
+            continue;
+        }
+        segments.push(parseSegment(rawSegment));
+    }
+    const hasCatchAll = segments.some((segment) => segment.kind === 'catch-all');
+    const hasDynamic = segments.some((segment) => segment.kind === 'dynamic');
+    const type = hasCatchAll ? 'catch-all' : hasDynamic ? 'dynamic' : 'static';
+    const pattern = segments.length === 0 ? '/' : `/${segments.map(segmentToPatternPart).join('/')}`;
+    return { pattern, segments, type };
+}
+/** Split a request pathname into segments, ignoring query string and trailing slash. */
+function splitRequestPath(requestPath) {
+    return String(requestPath || '/')
+        .split('?')[0]
+        .split('#')[0]
+        .replace(/\\/g, '/')
+        .split('/')
+        .filter(Boolean)
+        .map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            // A malformed escape sequence is matched literally rather than throwing.
+            return segment;
+        }
+    });
+}
+/**
+ * Match a parsed route against request path segments.
+ *
+ * Returns the extracted params, or null when the route does not match. A catch-all
+ * param is returned as a string array, mirroring the App Router's shape.
+ */
+function matchRouteSegments(route, requestSegments) {
+    const params = {};
+    const { segments } = route;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        if (segment.kind === 'catch-all') {
+            // A catch-all must be the final segment, and swallows everything left.
+            const rest = requestSegments.slice(index);
+            if (rest.length === 0) {
+                if (!segment.optional) {
+                    return null;
+                }
+                params[segment.paramName] = [];
+                return params;
+            }
+            params[segment.paramName] = rest;
+            return params;
+        }
+        const requestSegment = requestSegments[index];
+        if (requestSegment === undefined) {
+            return null;
+        }
+        if (segment.kind === 'static') {
+            if (segment.value !== requestSegment) {
+                return null;
+            }
+            continue;
+        }
+        // Dynamic segments must not match an empty value.
+        if (requestSegment === '') {
+            return null;
+        }
+        params[segment.paramName] = requestSegment;
+    }
+    // Every request segment has to be consumed, otherwise `/a` would match `/a/b`.
+    if (requestSegments.length !== segments.length) {
+        return null;
+    }
+    return params;
+}
+/**
+ * Ordering for route resolution: the most specific route wins.
+ *
+ * Static beats dynamic beats catch-all, compared segment by segment, so
+ * `/api/users/me` is preferred over `/api/users/[id]`, which is preferred over
+ * `/api/users/[...rest]`. Ties fall back to the pattern string for stable,
+ * platform-independent ordering.
+ */
+function compareRouteSpecificity(a, b) {
+    const rank = (segment) => {
+        switch (segment.kind) {
+            case 'static':
+                return 0;
+            case 'dynamic':
+                return 1;
+            case 'catch-all':
+                return 2;
+        }
+    };
+    const length = Math.max(a.segments.length, b.segments.length);
+    for (let index = 0; index < length; index += 1) {
+        const segmentA = a.segments[index];
+        const segmentB = b.segments[index];
+        if (!segmentA)
+            return -1;
+        if (!segmentB)
+            return 1;
+        const difference = rank(segmentA) - rank(segmentB);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return a.pattern.localeCompare(b.pattern);
+}