@jay-framework/stack-route-scanner 0.5.0

package/README.md

@@ -0,0 +1,94 @@
+# Jay Stack Route Scanner
+
+A utility for scanning a directory structure and generating route definitions for Jay stack applications. Supports static, parameterized, optional, and catch-all routes, and can convert them to Express-compatible route strings.
+
+## Overview
+
+The route-scanner walks your pages directory and produces a list of route definitions based on the folder and file structure. It is used internally by the Jay stack dev server, but can also be used standalone for custom routing logic or integrations.
+
+## Features
+
+- **Static routes** (e.g. `/about`)
+- **Root route** (e.g. `/`)
+- **Parameterized routes** (e.g. `/user/[id]` → `/user/:id`)
+- **Optional parameter routes** (e.g. `/blog/[[slug]]` → `/blog/:slug?`)
+- **Catch-all routes** (e.g. `/files/[...path]` → `/files/:path*`)
+- **Nested routes** (arbitrary nesting of the above)
+- **Express route conversion**
+
+## Usage
+
+```ts
+import { scanRoutes, routeToExpressRoute } from '@jay-framework/stack-route-scanner';
+
+const routes = await scanRoutes('./src/pages', {
+  jayHtmlFilename: 'page.jay-html',
+  compFilename: 'page.ts',
+});
+
+routes.forEach((route) => {
+  console.log('Route:', route.rawRoute, 'Express:', routeToExpressRoute(route));
+});
+```
+
+## Supported Routing Patterns
+
+Given a directory structure like:
+
+```
+src/pages/
+├── page.jay-html                // root route ('/')
+├── about/
+│   └── page.jay-html            // '/about'
+├── user/
+│   └── [id]/
+│       └── page.jay-html        // '/user/[id]' → '/user/:id'
+├── blog/
+│   └── [[slug]]/
+│       └── page.jay-html        // '/blog/[[slug]]' → '/blog/:slug?'
+├── files/
+│   └── [...path]/
+│       └── page.jay-html        // '/files/[...path]' → '/files/:path*'
+```
+
+### Segment Syntax
+
+- `segment/` — static segment (e.g. `/about`)
+- `[param]/` — required parameter (e.g. `/user/:id`)
+- `[[param]]/` — optional parameter (e.g. `/blog/:slug?`)
+- `[...param]/` — catch-all parameter (e.g. `/files/:path*`)
+
+### Example Output
+
+For the above structure, `scanRoutes` will produce route objects like:
+
+```js
+[
+  { rawRoute: '', segments: [] }, // '/'
+  { rawRoute: '/about', segments: ['about'] },
+  { rawRoute: '/user/[id]', segments: ['user', { name: 'id', type: 'single' }] },
+  { rawRoute: '/blog/[[slug]]', segments: ['blog', { name: 'slug', type: 'optional' }] },
+  { rawRoute: '/files/[...path]', segments: ['files', { name: 'path', type: 'catchAll' }] },
+];
+```
+
+And `routeToExpressRoute(route)` will convert these to:
+
+- `/` (root)
+- `/about`
+- `/user/:id`
+- `/blog/:slug?`
+- `/files/:path*`
+
+## API
+
+### `scanRoutes(rootDir, options)`
+
+- `rootDir`: Path to the pages directory
+- `options.jayHtmlFilename`: Name of the HTML file to look for (default: `page.jay-html`)
+- `options.compFilename`: Name of the component file to look for (default: `page.ts`)
+- Returns: Array of route objects with `compPath`, `jayHtmlPath`, `rawRoute`, and `segments`
+
+### `routeToExpressRoute(route)`
+
+- Converts a route object to an Express-compatible route string

package/dist/index.d.mts

@@ -0,0 +1,26 @@
+declare enum JayRouteParamType {
+    single = 0,
+    catchAll = 1,
+    optional = 2
+}
+interface JayRouteParam {
+    name: string;
+    type: JayRouteParamType;
+}
+type JayRouteSegment = string | JayRouteParam;
+type JayRoute = {
+    segments: JayRouteSegment[];
+    rawRoute: string;
+    jayHtmlPath: string;
+    compPath: string;
+};
+type JayRoutes = JayRoute[];
+interface ScanFilesOptions {
+    jayHtmlFilename: string;
+    compFilename: string;
+}
+declare function scanRoutes(baseDir: string, options: ScanFilesOptions): Promise<JayRoutes>;
+
+declare function routeToExpressRoute(route: JayRoute): string;
+
+export { type JayRoute, type JayRouteParam, JayRouteParamType, type JayRouteSegment, type JayRoutes, type ScanFilesOptions, routeToExpressRoute, scanRoutes };

package/dist/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const fs = require("fs");
+const path = require("path");
+var JayRouteParamType = /* @__PURE__ */ ((JayRouteParamType2) => {
+  JayRouteParamType2[JayRouteParamType2["single"] = 0] = "single";
+  JayRouteParamType2[JayRouteParamType2["catchAll"] = 1] = "catchAll";
+  JayRouteParamType2[JayRouteParamType2["optional"] = 2] = "optional";
+  return JayRouteParamType2;
+})(JayRouteParamType || {});
+const PARSE_PARAM = /^\[(\[)?(\.\.\.)?([^\]]+)\]?\]$/;
+function convertToRoutePath(BASE_DIR, jayHtmlPath, { jayHtmlFilename, compFilename }) {
+  let rawRoute = jayHtmlPath.replace(BASE_DIR, "").replace(`/${jayHtmlFilename}`, "").replace("\\", "/");
+  const segments = rawRoute.split("/").filter((segment) => segment.length > 0).map((segment) => {
+    const match = segment.match(PARSE_PARAM);
+    if (!match)
+      return segment;
+    const isOptional = !!match[1];
+    const isCatchAll = !!match[2];
+    const name = match[3];
+    return {
+      name,
+      type: isOptional ? 2 : isCatchAll ? 1 : 0
+      /* single */
+    };
+  });
+  const compPath = jayHtmlPath.replace(jayHtmlFilename, compFilename);
+  return { segments, jayHtmlPath, compPath, rawRoute };
+}
+async function scanDirectory(BASE_DIR, directory, options) {
+  let routes = [];
+  const items = await fs.promises.readdir(directory, { withFileTypes: true });
+  for (const item of items) {
+    const fullPath = path.join(directory, item.name);
+    if (item.isDirectory()) {
+      routes = [...routes, ...await scanDirectory(BASE_DIR, fullPath, options)];
+    } else if (item.name === options.jayHtmlFilename) {
+      const route = convertToRoutePath(BASE_DIR, fullPath, options);
+      routes.push(route);
+    }
+  }
+  return routes;
+}
+async function scanRoutes(baseDir, options) {
+  const BASE_DIR = path.resolve(baseDir);
+  return await scanDirectory(BASE_DIR, BASE_DIR, options);
+}
+function routeToExpressRoute(route) {
+  return "/" + route.segments.map((segment) => {
+    if (typeof segment === "string")
+      return segment;
+    else {
+      if (segment.type === JayRouteParamType.single)
+        return `:${segment.name}`;
+      else if (segment.type === JayRouteParamType.optional)
+        return `:${segment.name}?`;
+      else
+        return `:${segment.name}*`;
+    }
+  }).join("/");
+}
+exports.JayRouteParamType = JayRouteParamType;
+exports.routeToExpressRoute = routeToExpressRoute;
+exports.scanRoutes = scanRoutes;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jay-framework/stack-route-scanner",
+  "version": "0.5.0",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.mts",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@types/node": "^20.11.5",
+    "nodemon": "^3.0.3",
+    "replace-in-file": "^7.1.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}