filesystem-routing 0.1.0

package/dist/vite/types.js

@@ -0,0 +1,123 @@
+import { relative } from "node:path";
+import { normalizePath } from "../router.js";
+/**
+ * Type generation for the virtual manifest module.
+ *
+ * The delivered manifest is a runtime value, so a router that derives types
+ * from its route table — `@solidjs/router`'s typed `paths` proxy, say — gets
+ * nothing from it: `RoutePaths` degrades to `any` as soon as the route array
+ * is a plain `RouteDefinition[]` rather than a tuple. Emitting a declaration
+ * that types the module as a *literal tuple* is what keeps those types alive
+ * across the file-routing seam.
+ *
+ * Emission adapters have to preserve the tuple in turn, by mapping with a
+ * `<const T extends readonly ...>` signature rather than a plain `.map`.
+ */
+const HEADER = `// Generated by filesystem-routing. Do not edit.
+// Regenerated whenever a route file is added, changed or removed.`;
+const REF_TYPES = `  /** A code-split ref: the delivery adapter emits it as a dynamic import. */
+  export interface FileRouteLazyRef<M = Record<string, unknown>> {
+    src: string;
+    import(): Promise<M>;
+  }
+
+  /** An eager ref: its picked exports are imported statically. */
+  export interface FileRouteEagerRef<M = Record<string, unknown>> {
+    require(): M;
+  }
+
+  /** A flat entry of the route manifest. */
+  export interface FileRouteEntry {
+    path: string;
+    page?: boolean;
+    $component?: FileRouteLazyRef<any>;
+    $$route?: FileRouteEagerRef<any>;
+    [key: string]: unknown;
+  }
+
+  /** An entry of the nested \`pageRoutes\` view. */
+  export interface FileRouteTreeEntry extends FileRouteEntry {
+    id: string;
+    children?: readonly FileRouteTreeEntry[];
+  }`;
+/** Extensions TypeScript can resolve through a `typeof import(...)`. */
+const TYPED_MODULE = /\.([mc]?[jt]sx?)$/;
+/**
+ * Types a ref by the module it points at, so a page's `default` really is the
+ * component and a `route` export really is the config the module declares —
+ * which is what saves an emission adapter from casting either one. Modules
+ * TypeScript cannot resolve (`.md`, `.mdx`) fall back to the generic ref.
+ */
+function refType(ref, kind, from) {
+    const name = kind === "eager" ? "FileRouteEagerRef" : "FileRouteLazyRef";
+    if (!TYPED_MODULE.test(ref.src))
+        return name;
+    let specifier = normalizePath(relative(from, ref.src)).replace(TYPED_MODULE, "");
+    if (!specifier.startsWith("."))
+        specifier = `./${specifier}`;
+    return `${name}<typeof import(${JSON.stringify(specifier)})>`;
+}
+const isLazyRefKey = (key) => key.startsWith("$") && !key.startsWith("$$");
+const isEagerRefKey = (key) => key.startsWith("$$");
+/**
+ * Types one manifest entry, keeping `path` literal so it reaches path-derived
+ * types intact. Absent refs are typed `?: undefined` rather than omitted, so
+ * an adapter can read `entry.$$route` uniformly across the tuple.
+ */
+function entryType(entry, indent, nested, from) {
+    const inner = indent + "  ";
+    const fields = [`path: ${JSON.stringify(entry.path)}`];
+    if (nested)
+        fields.push(`id: ${JSON.stringify(entry.id)}`);
+    fields.push(`page: ${entry.page ? "true" : "false"}`);
+    // A convention records refs it did not emit as present-but-undefined keys,
+    // so go by the value, not the key.
+    const refKeys = Object.keys(entry).filter(key => key.startsWith("$") && entry[key] !== undefined);
+    for (const key of refKeys) {
+        const kind = isEagerRefKey(key) ? "eager" : "lazy";
+        fields.push(`${key}: ${refType(entry[key], kind, from)}`);
+    }
+    // Reading an absent ref is how adapters branch, so keep the key present.
+    if (!refKeys.some(isLazyRefKey))
+        fields.push(`$component?: undefined`);
+    if (!refKeys.some(isEagerRefKey))
+        fields.push(`$$route?: undefined`);
+    if (nested) {
+        const children = entry.children;
+        fields.push(children?.length
+            ? `children: ${tupleType(children, inner, true, from)}`
+            : `children?: undefined`);
+    }
+    return `{\n${fields.map(field => `${inner}${field};`).join("\n")}\n${indent}}`;
+}
+function tupleType(entries, indent, nested, from) {
+    if (!entries.length)
+        return "readonly []";
+    const inner = indent + "  ";
+    const members = entries
+        .map(entry => `${inner}${entryType(entry, inner, nested, from)}`)
+        .join(",\n");
+    return `readonly [\n${members}\n${indent}]`;
+}
+/**
+ * Builds the ambient declaration for `moduleId`. It is self-contained and
+ * replaces `filesystem-routing/types` — reference one or the other, never
+ * both, or TypeScript sees two declarations of the same module.
+ */
+export function serializeTypes(moduleId, routes, pageRoutes, 
+/** Directory the declaration is written to; module specifiers are relative to it. */
+from) {
+    return `${HEADER}
+
+declare module ${JSON.stringify(moduleId)} {
+${REF_TYPES}
+
+  /** The flat route manifest, in scan order. */
+  const routes: ${tupleType(routes, "  ", false, from)};
+  export default routes;
+
+  /** The page entries, nested by path with grouping segments stripped. */
+  export const pageRoutes: ${tupleType(pageRoutes, "  ", true, from)};
+}
+`;
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "filesystem-routing",
+  "description": "Router-neutral file-system routing: scans a route directory into a neutral route manifest with pluggable conventions and delivery adapters",
+  "license": "MIT",
+  "version": "0.1.0",
+  "author": "Ryan Carniato",
+  "homepage": "https://github.com/solidjs/filesystem-routing#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solidjs/filesystem-routing"
+  },
+  "bugs": {
+    "url": "https://github.com/solidjs/filesystem-routing/issues"
+  },
+  "keywords": [
+    "file-system routing",
+    "file routes",
+    "router",
+    "vite",
+    "vite-plugin",
+    "solid"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tree": {
+      "types": "./dist/tree.d.ts",
+      "default": "./dist/tree.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    },
+    "./types": {
+      "types": "./types.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "types.d.ts"
+  ],
+  "dependencies": {
+    "@babel/core": "^7.29.0",
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__traverse": "^7.28.0",
+    "@types/micromatch": "^4.0.10",
+    "fast-glob": "^3.3.3",
+    "micromatch": "^4.0.8",
+    "oxc-parser": "^0.139.0"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@types/node": "^22.10.0",
+    "prettier": "^3.4.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.6"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pretty": "prettier --write \"{src,test}/**/*.ts\"",
+    "typecheck:dist": "pnpx @arethetypeswrong/cli --pack . --profile esm-only",
+    "release": "pnpm build && changeset publish"
+  }
+}

package/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Types for the virtual route-manifest module served by the Vite delivery
+ * adapter. Frameworks and apps that import the manifest directly reference
+ * this file once:
+ *
+ * ```ts
+ * /// <reference types="filesystem-routing/types" />
+ * ```
+ *
+ * These describe the manifest *as delivered*: the module refs the scanner
+ * records as `{ src, pick }` reach the app as callable imports. A project
+ * serving the manifest from a custom `moduleId` declares that id itself,
+ * with the same two exports.
+ */
+
+declare module "virtual:file-routes" {
+  /** A code-split ref: the delivery adapter emits it as a dynamic import. */
+  export interface FileRouteLazyRef {
+    src: string;
+    import(): Promise<Record<string, unknown>>;
+  }
+
+  /** An eager ref: its picked exports are imported statically. */
+  export interface FileRouteEagerRef {
+    require(): Record<string, unknown>;
+  }
+
+  /** A flat entry of the route manifest. */
+  export interface FileRouteEntry {
+    /**
+     * The route path in the neutral pattern language (`:param`, `:param?`,
+     * `*rest`), with any grouping segments still present.
+     */
+    path: string;
+    /** `true` when the module renders a page. */
+    page?: boolean;
+    /** The page component module. */
+    $component?: FileRouteLazyRef;
+    /** The route config (`route` export), when the module has one. */
+    $$route?: FileRouteEagerRef;
+    /** Refs added by convention extensions, e.g. `$GET` handlers. */
+    [key: string]: unknown;
+  }
+
+  /** An entry of the nested `pageRoutes` view. */
+  export interface FileRouteTreeEntry extends FileRouteEntry {
+    /** The manifest path this entry was nested under, groups included. */
+    id: string;
+    children?: FileRouteTreeEntry[];
+  }
+
+  /** The flat route manifest, in scan order. */
+  const routes: FileRouteEntry[];
+  export default routes;
+
+  /** The page entries, nested by path with grouping segments stripped. */
+  export const pageRoutes: FileRouteTreeEntry[];
+}