@webstir-io/module-contract 0.3.1 → 0.5.0

package/dist/page-routes.d.ts

@@ -0,0 +1,30 @@
+/** A view that routes a dynamic path pattern to a built frontend page. */
+export interface PageRoute {
+    readonly page: string;
+    readonly pattern: string;
+    readonly name?: string;
+}
+export interface PageRouteMatch {
+    readonly route: PageRoute;
+    readonly params: Record<string, string>;
+}
+/**
+ * Reads the page views declared in `package.json` under `webstir.moduleManifest.views`.
+ * A view routes to a frontend page when it names a `page` and its `renderMode` is `spa`
+ * or omitted. Views without a `page` are left to the backend runtime.
+ */
+export declare function readWorkspacePageRoutes(workspaceRoot: string): Promise<readonly PageRoute[]>;
+/**
+ * Validates view declarations and orders them the way Bun's router ranks overlapping
+ * patterns: segment by segment from the left, a static segment beats a parameter at the
+ * first position where two patterns differ. Declaration order breaks exact ties.
+ */
+export declare function normalizePageRoutes(views: readonly unknown[]): readonly PageRoute[];
+export declare function normalizePagePattern(pattern: string): string;
+/**
+ * A `:param` matches any single path segment, including one containing a dot, exactly as
+ * Bun's router does in watch. Static files are always resolved before patterns are tried.
+ */
+export declare function matchPageRoute(routes: readonly PageRoute[], pathname: string): PageRouteMatch | undefined;
+/** Negative when `left` should be tried before `right`. Mirrors Bun.serve route ranking. */
+export declare function compareSpecificity(left: string, right: string): number;

package/dist/page-routes.js

@@ -0,0 +1,176 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+const PARAM_SEGMENT = /^:([A-Za-z0-9_]+)$/;
+const STATIC_SEGMENT = /^[A-Za-z0-9._~-]+$/;
+/**
+ * Reads the page views declared in `package.json` under `webstir.moduleManifest.views`.
+ * A view routes to a frontend page when it names a `page` and its `renderMode` is `spa`
+ * or omitted. Views without a `page` are left to the backend runtime.
+ */
+export async function readWorkspacePageRoutes(workspaceRoot) {
+    const source = await readFile(path.join(workspaceRoot, 'package.json'), 'utf8');
+    const packageJson = JSON.parse(source);
+    const views = packageJson.webstir?.moduleManifest?.views;
+    return normalizePageRoutes(Array.isArray(views) ? views : []);
+}
+/**
+ * Validates view declarations and orders them the way Bun's router ranks overlapping
+ * patterns: segment by segment from the left, a static segment beats a parameter at the
+ * first position where two patterns differ. Declaration order breaks exact ties.
+ */
+export function normalizePageRoutes(views) {
+    const routes = [];
+    const owners = new Map();
+    for (const view of views) {
+        if (!view || typeof view !== 'object') {
+            continue;
+        }
+        const { name, path: pattern, page, renderMode } = view;
+        if (page === undefined) {
+            continue;
+        }
+        if (typeof page !== 'string' || page.length === 0) {
+            throw new Error('[webstir] a view "page" must be a non-empty page name.');
+        }
+        // The name becomes a path and an address (pages/<name>, /<name>/), so it is one.
+        if (!page
+            .split('/')
+            .every((segment) => STATIC_SEGMENT.test(segment) && segment !== '.' && segment !== '..')) {
+            throw new Error(`[webstir] view page "${page}" is not a page name; use the page's folder under src/frontend/pages, such as "items" or "docs/intro".`);
+        }
+        if (renderMode !== undefined && renderMode !== 'spa') {
+            continue;
+        }
+        if (typeof pattern !== 'string') {
+            throw new Error(`[webstir] the view for page "${page}" needs a "path" pattern.`);
+        }
+        const normalized = normalizePagePattern(pattern);
+        const shape = patternShape(normalized);
+        const owner = owners.get(shape);
+        if (owner && owner !== page) {
+            throw new Error(`[webstir] view path ${normalized} is declared by both "${owner}" and "${page}".`);
+        }
+        owners.set(shape, page);
+        routes.push({
+            page,
+            pattern: normalized,
+            ...(typeof name === 'string' && name.length > 0 ? { name } : {}),
+        });
+    }
+    return sortBySpecificity(routes);
+}
+export function normalizePagePattern(pattern) {
+    const trimmed = pattern.trim();
+    if (!trimmed.startsWith('/')) {
+        throw new Error(`[webstir] view path "${pattern}" must start with "/".`);
+    }
+    const segments = trimmed.split('/').filter((segment) => segment.length > 0);
+    if (segments.length === 0) {
+        throw new Error('[webstir] view path "/" cannot route to a page; use the home page instead.');
+    }
+    const lastSegment = segments[segments.length - 1];
+    if (!PARAM_SEGMENT.test(lastSegment) && path.posix.extname(lastSegment) !== '') {
+        throw new Error(`[webstir] view path "${pattern}" ends in a file name ("${lastSegment}"). Page views serve HTML documents; use a static file or a route for files.`);
+    }
+    const params = new Set();
+    for (const segment of segments) {
+        const param = PARAM_SEGMENT.exec(segment);
+        if (param) {
+            if (params.has(param[1])) {
+                throw new Error(`[webstir] view path "${pattern}" repeats the parameter ":${param[1]}".`);
+            }
+            params.add(param[1]);
+            continue;
+        }
+        if (!STATIC_SEGMENT.test(segment)) {
+            throw new Error(`[webstir] view path "${pattern}" has an invalid segment "${segment}". Use static segments or ":param".`);
+        }
+    }
+    return `/${segments.join('/')}`;
+}
+/**
+ * A `:param` matches any single path segment, including one containing a dot, exactly as
+ * Bun's router does in watch. Static files are always resolved before patterns are tried.
+ */
+export function matchPageRoute(routes, pathname) {
+    const segments = splitRequestPath(pathname);
+    if (!segments) {
+        return undefined;
+    }
+    for (const route of routes) {
+        const params = matchPattern(route.pattern, segments);
+        if (params) {
+            return { route, params };
+        }
+    }
+    return undefined;
+}
+function matchPattern(pattern, segments) {
+    const expectedSegments = pattern.split('/').filter((segment) => segment.length > 0);
+    if (expectedSegments.length !== segments.length) {
+        return undefined;
+    }
+    const params = {};
+    for (let index = 0; index < expectedSegments.length; index += 1) {
+        const expected = expectedSegments[index];
+        const actual = segments[index];
+        const param = PARAM_SEGMENT.exec(expected);
+        if (param) {
+            params[param[1]] = actual;
+            continue;
+        }
+        if (expected !== actual) {
+            return undefined;
+        }
+    }
+    return params;
+}
+function splitRequestPath(pathname) {
+    const segments = [];
+    for (const raw of pathname.split('/')) {
+        if (raw.length === 0) {
+            continue;
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(raw);
+        }
+        catch {
+            return undefined;
+        }
+        if (decoded === '.' || decoded === '..' || decoded.includes('/')) {
+            return undefined;
+        }
+        segments.push(decoded);
+    }
+    return segments.length > 0 ? segments : undefined;
+}
+function sortBySpecificity(routes) {
+    return routes
+        .map((route, index) => ({ route, index }))
+        .sort((left, right) => compareSpecificity(left.route.pattern, right.route.pattern) || left.index - right.index)
+        .map((entry) => entry.route);
+}
+/** Negative when `left` should be tried before `right`. Mirrors Bun.serve route ranking. */
+export function compareSpecificity(left, right) {
+    const leftSegments = left.split('/').filter((segment) => segment.length > 0);
+    const rightSegments = right.split('/').filter((segment) => segment.length > 0);
+    if (leftSegments.length !== rightSegments.length) {
+        return leftSegments.length - rightSegments.length;
+    }
+    for (let index = 0; index < leftSegments.length; index += 1) {
+        const leftIsParam = PARAM_SEGMENT.test(leftSegments[index]);
+        const rightIsParam = PARAM_SEGMENT.test(rightSegments[index]);
+        if (leftIsParam !== rightIsParam) {
+            return leftIsParam ? 1 : -1;
+        }
+    }
+    return 0;
+}
+/** Two patterns that differ only in parameter names match the same paths. */
+function patternShape(pattern) {
+    return pattern
+        .split('/')
+        .map((segment) => (PARAM_SEGMENT.test(segment) ? ':' : segment))
+        .join('/');
+}

package/dist/render-execute.d.ts

@@ -1,4 +1,4 @@
-import { type RenderProgram, type RenderSourceLocation } from './render-program.js';
+import type { RenderProgram, RenderSourceLocation } from './render-program.js';
 export declare const RENDER_CSRF_FIELD = "_csrf";
 export declare class RenderProgramError extends Error {
     readonly loc: RenderSourceLocation;

package/dist/render-execute.js

@@ -1,4 +1,4 @@
-import { RENDER_PROGRAM_VERSION, } from './render-program.js';
+import { RENDER_PROGRAM_VERSION } from './render-version.js';
 export const RENDER_CSRF_FIELD = '_csrf';
 const SAFE_URL_SCHEMES = new Set(['http', 'https', 'mailto', 'tel']);
 const BLOCKED_URL = 'about:invalid';

package/dist/render-program.d.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-export declare const RENDER_PROGRAM_VERSION = 1;
-export declare const RENDER_PROGRAM_FILE = "index.program.json";
+export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION } from './render-version.js';
 export declare const renderSourceLocationSchema: z.ZodObject<{
     file: z.ZodString;
     line: z.ZodNumber;

package/dist/render-program.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-export const RENDER_PROGRAM_VERSION = 1;
-export const RENDER_PROGRAM_FILE = 'index.program.json';
+import { RENDER_PROGRAM_VERSION } from './render-version.js';
+export { RENDER_PROGRAM_FILE, RENDER_PROGRAM_VERSION } from './render-version.js';
 export const renderSourceLocationSchema = z.object({
     file: z.string().min(1),
     line: z.number().int().positive(),

package/dist/render-version.d.ts

@@ -0,0 +1,2 @@
+export declare const RENDER_PROGRAM_VERSION = 1;
+export declare const RENDER_PROGRAM_FILE = "index.program.json";

package/dist/render-version.js

@@ -0,0 +1,2 @@
+export const RENDER_PROGRAM_VERSION = 1;
+export const RENDER_PROGRAM_FILE = 'index.program.json';

package/dist/workspace.d.ts

@@ -0,0 +1,19 @@
+/** What an app is made of, read from its files rather than declared. */
+export interface WorkspaceLayers {
+    /** The app has pages: a `src/frontend/` directory. */
+    readonly pages: boolean;
+    /** The app runs a server: its HTTP entry, `src/backend/index.{ts,tsx,js,mjs}`. */
+    readonly server: boolean;
+}
+export declare function readWorkspaceLayers(workspaceRoot: string): WorkspaceLayers;
+/**
+ * Pages without a server publish as files any static host serves, and their views render at
+ * publish.
+ */
+export declare function isStaticApp(layers: WorkspaceLayers): boolean;
+/**
+ * Whether the app has backend code to compile: its server entry, or a function's or job's own
+ * entry (`src/backend/functions/<name>/index.*`, `src/backend/jobs/<name>/index.*`). Functions and
+ * jobs compile without a server, but are not one.
+ */
+export declare function hasBackendEntries(workspaceRoot: string): boolean;

package/dist/workspace.js

@@ -0,0 +1,34 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+const SERVER_ENTRIES = ['index.ts', 'index.tsx', 'index.js', 'index.mjs'];
+export function readWorkspaceLayers(workspaceRoot) {
+    const root = path.resolve(workspaceRoot);
+    return {
+        pages: existsSync(path.join(root, 'src', 'frontend')),
+        server: SERVER_ENTRIES.some((entry) => existsSync(path.join(root, 'src', 'backend', entry))),
+    };
+}
+/**
+ * Pages without a server publish as files any static host serves, and their views render at
+ * publish.
+ */
+export function isStaticApp(layers) {
+    return layers.pages && !layers.server;
+}
+/**
+ * Whether the app has backend code to compile: its server entry, or a function's or job's own
+ * entry (`src/backend/functions/<name>/index.*`, `src/backend/jobs/<name>/index.*`). Functions and
+ * jobs compile without a server, but are not one.
+ */
+export function hasBackendEntries(workspaceRoot) {
+    const backendRoot = path.join(path.resolve(workspaceRoot), 'src', 'backend');
+    const hasIndex = (directory) => SERVER_ENTRIES.some((entry) => existsSync(path.join(directory, entry)));
+    if (hasIndex(backendRoot))
+        return true;
+    return ['functions', 'jobs'].some((group) => {
+        const groupRoot = path.join(backendRoot, group);
+        if (!existsSync(groupRoot))
+            return false;
+        return readdirSync(groupRoot, { withFileTypes: true }).some((entry) => entry.isDirectory() && hasIndex(path.join(groupRoot, entry.name)));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webstir-io/module-contract",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Public contract definitions for Webstir frontend and backend module providers.",
   "type": "module",
   "main": "dist/index.js",
@@ -16,6 +16,21 @@
       "import": "./dist/client-nav.js",
       "default": "./dist/client-nav.js"
     },
+    "./render": {
+      "types": "./dist/render-execute.d.ts",
+      "import": "./dist/render-execute.js",
+      "default": "./dist/render-execute.js"
+    },
+    "./page-routes": {
+      "types": "./dist/page-routes.d.ts",
+      "import": "./dist/page-routes.js",
+      "default": "./dist/page-routes.js"
+    },
+    "./workspace": {
+      "types": "./dist/workspace.d.ts",
+      "import": "./dist/workspace.js",
+      "default": "./dist/workspace.js"
+    },
     "./ts-rest": {
       "types": "./dist/adapters/ts-rest.d.ts",
       "import": "./dist/adapters/ts-rest.js",