├── static
    └── output.css
├── src
    ├── MiddlewareStradegy.ts
    ├── XerusFileRouterOpts.ts
    ├── middleware
    │   └── middleware.ts
    ├── InitModule.ts
    ├── components
    │   └── components.tsx
    ├── layouts
    │   └── layouts.tsx
    ├── XerusFileRouter.ts
    ├── RouteModule.ts
    ├── ServerManager.ts
    ├── AppFile.ts
    └── AppDir.ts
├── app
    ├── +init.tsx
    ├── +route.tsx
    ├── user
    │   └── :id
    │   │   └── +route.tsx
    └── about
    │   ├── +route.tsx
    │   └── again
    │       └── +route.tsx
├── index.ts
├── .gitignore
├── package.json
├── tsconfig.json
├── example.ts
├── README.md
└── bun.lock


/static/output.css:
--------------------------------------------------------------------------------
1 | body {
2 |   background-color: black;
3 |   color: white;
4 | }
5 | 


--------------------------------------------------------------------------------
/src/MiddlewareStradegy.ts:
--------------------------------------------------------------------------------
1 | 
2 | 
3 | export enum MiddlwareStradegy {
4 |   Isolate,
5 |   Cascade,
6 | }


--------------------------------------------------------------------------------
/src/XerusFileRouterOpts.ts:
--------------------------------------------------------------------------------
1 | 
2 | export type XerusFileRouterOpts = {
3 |   src: string;
4 |   port: number;
5 | };


--------------------------------------------------------------------------------
/app/+init.tsx:
--------------------------------------------------------------------------------
 1 | import { InitModule } from "../src/InitModule";
 2 | import { logger, Xerus } from "xerus/xerus";
 3 | 
 4 | let module = new InitModule();
 5 | 
 6 | module.init(async (app: Xerus) => {
 7 |   app.use(logger);
 8 |   app.static("static");
 9 | });
10 | 
11 | export default module;
12 | 


--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
1 | export * from './src/AppDir'
2 | export * from './src/AppFile'
3 | export * from './src/InitModule'
4 | export * from './src/MiddlewareStradegy'
5 | export * from './src/RouteModule'
6 | export * from './src/ServerManager'
7 | export * from './src/XerusFileRouter'
8 | export * from './src/XerusFileRouterOpts'
9 | 


--------------------------------------------------------------------------------
/src/middleware/middleware.ts:
--------------------------------------------------------------------------------
 1 | import { HTTPContext, Middleware, type MiddlewareNextFn } from "xerus/xerus";
 2 | 
 3 | export const testmw = new Middleware(
 4 |   async (c: HTTPContext, next: MiddlewareNextFn) => {
 5 |     console.log("before");
 6 |     await next();
 7 |     console.log("after");
 8 |   },
 9 | );
10 | 


--------------------------------------------------------------------------------
/src/InitModule.ts:
--------------------------------------------------------------------------------
 1 | import type { Xerus } from "xerus/xerus";
 2 | 
 3 | export class InitModule {
 4 |   initFunc: undefined | ((app: Xerus) => Promise<void>);
 5 |   endpoint: string = '/'
 6 |   constructor() {}
 7 |   async init(callback: (app: Xerus) => Promise<void>) {
 8 |     this.initFunc = callback;
 9 |   }
10 | }
11 | 


--------------------------------------------------------------------------------
/src/components/components.tsx:
--------------------------------------------------------------------------------
 1 | export const Header = (props: { text: string }) => {
 2 |   return (
 3 |     <header>
 4 |       <h1>{props.text}</h1>
 5 |     </header>
 6 |   );
 7 | };
 8 | 
 9 | export const Footer = (props: { text: string }) => {
10 |   return (
11 |     <footer>
12 |       <p>{props.text}</p>
13 |     </footer>
14 |   );
15 | };
16 | 


--------------------------------------------------------------------------------
/app/+route.tsx:
--------------------------------------------------------------------------------
 1 | import type { HTTPContext } from "xerus/xerus";
 2 | import { cascade, isolate, RouteModule } from "../src/RouteModule";
 3 | import { GuestLayout } from "../src/layouts/layouts";
 4 | import { testmw } from "../src/middleware/middleware";
 5 | 
 6 | let module = new RouteModule();
 7 | 
 8 | module.get(async (c: HTTPContext) => {
 9 |   return c.jsx(
10 |     <GuestLayout title="Home Page">
11 |       <h1>Home Page!</h1>
12 |     </GuestLayout>,
13 |   );
14 | }, isolate(testmw));
15 | 
16 | export default module;
17 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | # dependencies (bun install)
 2 | node_modules
 3 | 
 4 | # output
 5 | out
 6 | dist
 7 | *.tgz
 8 | 
 9 | # code coverage
10 | coverage
11 | *.lcov
12 | 
13 | # logs
14 | logs
15 | _.log
16 | report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
17 | 
18 | # dotenv environment variable files
19 | .env
20 | .env.development.local
21 | .env.test.local
22 | .env.production.local
23 | .env.local
24 | 
25 | # caches
26 | .eslintcache
27 | .cache
28 | *.tsbuildinfo
29 | 
30 | # IntelliJ based IDEs
31 | .idea
32 | 
33 | # Finder (MacOS) folder config
34 | .DS_Store
35 | 


--------------------------------------------------------------------------------
/app/user/:id/+route.tsx:
--------------------------------------------------------------------------------
 1 | import type { HTTPContext } from "xerus/xerus";
 2 | import { GuestLayout } from "../../../src/layouts/layouts";
 3 | import { testmw } from "../../../src/middleware/middleware";
 4 | import { RouteModule, isolate } from "../../../src/RouteModule";
 5 | 
 6 | let module = new RouteModule();
 7 | 
 8 | module.get(async (c: HTTPContext) => {
 9 |   return c.jsx(
10 |     <GuestLayout title="Home Page">
11 |       <h1>User {c.getParam('id')}</h1>
12 |     </GuestLayout>,
13 |   );
14 | }, isolate(testmw));
15 | 
16 | export default module;
17 | 


--------------------------------------------------------------------------------
/src/layouts/layouts.tsx:
--------------------------------------------------------------------------------
 1 | import { Footer, Header } from "../components/components";
 2 | 
 3 | export const GuestLayout = (props: {
 4 |   title: string;
 5 |   children?: React.ReactNode;
 6 | }) => {
 7 |   return (
 8 |     <html>
 9 |       <head>
10 |         <title>{props.title}</title>
11 |         <link rel="stylesheet" href="/static/output.css"></link>
12 |       </head>
13 |       <body>
14 |         <Header text="Hello, World!" />
15 |         {props.children}
16 |         <Footer text="GoodBye, World!" />
17 |       </body>
18 |     </html>
19 |   );
20 | };
21 | 


--------------------------------------------------------------------------------
/app/about/+route.tsx:
--------------------------------------------------------------------------------
 1 | import type { HTTPContext } from "xerus/xerus";
 2 | import { RouteModule } from "../../src/RouteModule";
 3 | import { GuestLayout } from "../../src/layouts/layouts";
 4 | import { testmw } from "../../src/middleware/middleware";
 5 | import { cascade } from "../../src/RouteModule";
 6 | 
 7 | let module = new RouteModule();
 8 | 
 9 | module.get(async (c: HTTPContext) => {
10 |   return c.jsx(
11 |     <GuestLayout title="About Page">
12 |       <h1>About Me!</h1>
13 |     </GuestLayout>,
14 |   );
15 | }, cascade(testmw));
16 | 
17 | export default module;
18 | 


--------------------------------------------------------------------------------
/app/about/again/+route.tsx:
--------------------------------------------------------------------------------
 1 | import type { HTTPContext } from "xerus/xerus";
 2 | import { RouteModule } from "../../../src/RouteModule";
 3 | import { GuestLayout } from "../../../src/layouts/layouts";
 4 | import { testmw } from "../../../src/middleware/middleware";
 5 | import { cascade } from "../../../src/RouteModule";
 6 | 
 7 | let module = new RouteModule();
 8 | 
 9 | module.get(async (c: HTTPContext) => {
10 |   return c.jsx(
11 |     <GuestLayout title="About AGAIN Page">
12 |       <h1>About Me AGAIN!</h1>
13 |     </GuestLayout>,
14 |   );
15 | }, cascade(testmw));
16 | 
17 | export default module;
18 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "xerus-router",
 3 |   "module": "index.ts",
 4 |   "type": "module",
 5 |   "private": true,
 6 |   "scripts": {
 7 |     "dev": "bun run --hot ./example.ts",
 8 |     "format": "bunx prettier --write ."
 9 |   },
10 |   "devDependencies": {
11 |     "@types/bun": "latest",
12 |     "prettier": "^3.6.2"
13 |   },
14 |   "peerDependencies": {
15 |     "typescript": "^5"
16 |   },
17 |   "dependencies": {
18 |     "@types/react-dom": "^19.2.2",
19 |     "react-dom": "^19.2.0",
20 |     "react": "^19.2.0",
21 |     "floss": "github:phillip-england/floss#v0.0.2",
22 |     "hoist": "github:phillip-england/hoist#v0.0.6",
23 |     "linkedom": "^0.18.12",
24 |     "xerus": "github:phillip-england/xerus#v0.0.27"
25 |   }
26 | }
27 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     // Environment setup & latest features
 4 |     "lib": ["ESNext"],
 5 |     "target": "ESNext",
 6 |     "module": "Preserve",
 7 |     "moduleDetection": "force",
 8 |     "jsx": "react-jsx",
 9 |     "allowJs": true,
10 | 
11 |     // Bundler mode
12 |     "moduleResolution": "bundler",
13 |     "allowImportingTsExtensions": true,
14 |     "verbatimModuleSyntax": true,
15 |     "noEmit": true,
16 | 
17 |     // Best practices
18 |     "strict": true,
19 |     "skipLibCheck": true,
20 |     "noFallthroughCasesInSwitch": true,
21 |     "noUncheckedIndexedAccess": true,
22 |     "noImplicitOverride": true,
23 | 
24 |     // Some stricter flags (disabled by default)
25 |     "noUnusedLocals": false,
26 |     "noUnusedParameters": false,
27 |     "noPropertyAccessFromIndexSignature": false
28 |   }
29 | }
30 | 


--------------------------------------------------------------------------------
/example.ts:
--------------------------------------------------------------------------------
 1 | // jss is a compiler
 2 | // annotated html in, interactive html out
 3 | // the tailwind of javascript
 4 | 
 5 | import path from "path";
 6 | import { XerusFileRouter } from "./src/XerusFileRouter";
 7 | 
 8 | try {
 9 |   let router = await XerusFileRouter.new({
10 |     src: path.join(process.cwd(), "app"),
11 |     port: 8080,
12 |   });
13 |   await router.serve()
14 | } catch (err: any) {
15 |   wherr(err);
16 | }
17 | 
18 | function wherr(error: Error) {
19 |   const stack = error.stack?.split("\n") || [];
20 |   const locationLine = stack[1]?.trim();
21 |   const match = locationLine?.match(/at (.+):(\d+):(\d+)/);
22 |   if (match) {
23 |     const [, file, line, column] = match;
24 |     console.log(`${file}:${line}:${column}`);
25 |   } else {
26 |     console.log(locationLine || "Unknown location");
27 |   }
28 | 
29 |   console.log(error.message);
30 | }
31 | 


--------------------------------------------------------------------------------
/src/XerusFileRouter.ts:
--------------------------------------------------------------------------------
 1 | import path from "path";
 2 | import { AppDir } from "./AppDir";
 3 | import { ServerManager } from "./ServerManager";
 4 | import type { XerusFileRouterOpts } from "./XerusFileRouterOpts";
 5 | 
 6 | 
 7 | export class XerusFileRouter {
 8 |   opts: XerusFileRouterOpts;
 9 |   serverManager: ServerManager;
10 |   appDir: AppDir;
11 |   constructor(opts: XerusFileRouterOpts, serverManager: ServerManager, appDir: AppDir) {
12 |     this.opts = opts;
13 |     this.serverManager = serverManager;
14 |     this.appDir = appDir;
15 |   }
16 |   static async new(opts: XerusFileRouterOpts) {
17 |     let appDir = await AppDir.load(path.join(opts.src));
18 |     let serverManager = await ServerManager.new(appDir);
19 |     let router = new XerusFileRouter(opts, serverManager, appDir);
20 |     return router;
21 |   }
22 |   async serve() {
23 |     await this.serverManager.listen(this.opts.port);
24 |   }
25 | }
26 | 


--------------------------------------------------------------------------------
/src/RouteModule.ts:
--------------------------------------------------------------------------------
 1 | import type { HTTPContext, HTTPHandleFunc, Middleware } from "xerus/xerus";
 2 | import { MiddlwareStradegy } from "./MiddlewareStradegy";
 3 | 
 4 | 
 5 | export class MiddlewareExport {
 6 |   stradegy: MiddlwareStradegy;
 7 |   middleware: Middleware;
 8 |   endpoint: string;
 9 |   constructor(stradegy: MiddlwareStradegy, middleware: Middleware) {
10 |     this.stradegy = stradegy;
11 |     this.middleware = middleware;
12 |     this.endpoint = "";
13 |   }
14 |   setEndpoint(endpoint: string) {
15 |     this.endpoint = endpoint;
16 |   }
17 | }
18 | 
19 | export function isolate(middleware: Middleware): MiddlewareExport {
20 |   return new MiddlewareExport(MiddlwareStradegy.Isolate, middleware);
21 | }
22 | 
23 | export function cascade(middleware: Middleware): MiddlewareExport {
24 |   return new MiddlewareExport(MiddlwareStradegy.Cascade, middleware);
25 | }
26 | 
27 | export class RouteModule {
28 |   getFunc: undefined | ((c: HTTPContext) => Promise<Response>);
29 |   getMiddleware: MiddlewareExport[] = [];
30 |   postFunc: undefined | ((c: HTTPContext) => Promise<Response>);
31 |   postMiddleware: MiddlewareExport[] = [];
32 |   putFunc: undefined | ((c: HTTPContext) => Promise<Response>);
33 |   putMiddleware: MiddlewareExport[] = [];
34 |   deleteFunc: undefined | ((c: HTTPContext) => Promise<Response>);
35 |   deleteMiddleware: MiddlewareExport[] = [];
36 |   endpoint: string = ''
37 | 
38 |   constructor() {}
39 | 
40 |   get(callback: HTTPHandleFunc, ...middleware: MiddlewareExport[]) {
41 |     this.getFunc = callback;
42 |     this.getMiddleware = middleware;
43 |     return this;
44 |   }
45 | 
46 |   post(callback: HTTPHandleFunc, ...middleware: MiddlewareExport[]) {
47 |     this.postFunc = callback;
48 |     this.postMiddleware = middleware;
49 |     return this;
50 |   }
51 | 
52 |   put(callback: HTTPHandleFunc, ...middleware: MiddlewareExport[]) {
53 |     this.putFunc = callback;
54 |     this.putMiddleware = middleware;
55 |     return this;
56 |   }
57 | 
58 |   delete(callback: HTTPHandleFunc, ...middleware: MiddlewareExport[]) {
59 |     this.deleteFunc = callback;
60 |     this.deleteMiddleware = middleware;
61 |     return this;
62 |   }
63 | }
64 | 


--------------------------------------------------------------------------------
/src/ServerManager.ts:
--------------------------------------------------------------------------------
 1 | import { Xerus, type HTTPHandleFunc, Middleware } from "xerus/xerus";
 2 | import type { AppDir } from "./AppDir";
 3 | import {  MiddlewareExport, type RouteModule } from "./RouteModule";
 4 | import type { InitModule } from "./InitModule";
 5 | 
 6 | export class ServerManager {
 7 |   server: Xerus
 8 |   constructor(app: Xerus) {
 9 |     this.server = app;
10 |   }
11 |   static async new(appDir: AppDir): Promise<ServerManager> {
12 |     let server = await ServerManager.initServer(appDir)
13 |     await ServerManager.registerRoutes(server, appDir)
14 |     let app = new ServerManager(server)
15 |     return app
16 |   }
17 |   static async initServer(appDir: AppDir): Promise<Xerus> {
18 |     let server = new Xerus()
19 |     await appDir.iterAppFiles(async (appFile) => {
20 |       let module = appFile.module as InitModule
21 |       if (module.initFunc) {
22 |         await module.initFunc(server)
23 |       }
24 |     })
25 |     return server
26 |   }
27 |   static async registerRoutes(server: Xerus, appDir: AppDir) {
28 |     await appDir.iterRouteAppFiles(async (appFile) => {
29 |       let module = appFile.module as RouteModule
30 |       if (module.getFunc) {
31 |         let mw = await appDir.loadMiddleware('GET', appFile.endpoint)
32 |         let getFunc = module.getFunc as HTTPHandleFunc
33 |         server.get(appFile.endpoint, getFunc, ...mw)
34 |       }
35 |       if (module.postFunc) {
36 |         let mw = await appDir.loadMiddleware('POST', appFile.endpoint)
37 |         let postFunc = module.postFunc as HTTPHandleFunc
38 |         server.post(appFile.endpoint, postFunc, ...mw)
39 |       }
40 |       if (module.putFunc) {
41 |         let mw = await appDir.loadMiddleware('PUT', appFile.endpoint)
42 |         let putFunc = module.putFunc as HTTPHandleFunc
43 |         server.put(appFile.endpoint, putFunc, ...mw)
44 |       }
45 |       if (module.deleteFunc) {
46 |         let mw = await appDir.loadMiddleware('DELETE', appFile.endpoint)
47 |         let deleteFunc = module.deleteFunc as HTTPHandleFunc
48 |         server.delete(appFile.endpoint, deleteFunc, ...mw)        
49 |       }
50 |     }) 
51 |   }
52 |   async listen(port: number) {
53 |     await this.server.listen(port)
54 |   }
55 | }


--------------------------------------------------------------------------------
/src/AppFile.ts:
--------------------------------------------------------------------------------
  1 | import path from "path";
  2 | import { MiddlewareExport, RouteModule } from "./RouteModule";
  3 | import { InitModule } from "./InitModule";
  4 | 
  5 | export type AppModule = RouteModule | InitModule;
  6 | 
  7 | export enum AppFileType {
  8 |   Init,
  9 |   Route,
 10 | }
 11 | 
 12 | export class AppFile {
 13 |   routesDirPath: string;
 14 |   endpoint: string;
 15 |   filePath: string;
 16 |   module: AppModule;
 17 |   fileType: AppFileType;
 18 |   constructor(
 19 |     routesDirPath: string,
 20 |     filePath: string,
 21 |     endpoint: string,
 22 |     module: AppModule,
 23 |     fileType: AppFileType,
 24 |   ) {
 25 |     this.routesDirPath = routesDirPath;
 26 |     this.endpoint = endpoint;
 27 |     this.filePath = filePath;
 28 |     this.module = module;
 29 |     this.fileType = fileType;
 30 |   }
 31 |   static async load(appDirPath: string, filePath: string): Promise<AppFile> {
 32 |     let [appModule, fileType] = await this.loadFileType(appDirPath, filePath);
 33 |     let parentDirPath = path.dirname(filePath);
 34 |     let endpoint = await AppFile.loadEndpoint(
 35 |       appDirPath,
 36 |       filePath,
 37 |       parentDirPath,
 38 |     );
 39 |     appModule.endpoint = endpoint
 40 |     let appFile = new AppFile(
 41 |       appDirPath,
 42 |       filePath,
 43 |       endpoint,
 44 |       appModule,
 45 |       fileType,
 46 |     );
 47 |     return appFile;
 48 |   }
 49 |   static async loadFileType(
 50 |     appDirPath: string,
 51 |     filePath: string,
 52 |   ): Promise<[AppModule, AppFileType]> {
 53 |     let fileName = path.basename(filePath);
 54 |     let ext = path.extname(fileName);
 55 |     if (ext != ".tsx") {
 56 |       throw new Error(
 57 |         `INVALID APP FILE: only .tsx files allowed, located ${filePath}`,
 58 |       );
 59 |     }
 60 |     let module = await import(filePath);
 61 |     if (!module.default) {
 62 |       throw new Error(
 63 |         `INVALID APP FILE: missing default export at ${filePath}`,
 64 |       );
 65 |     }
 66 |     switch (fileName) {
 67 |       case "+route.tsx": {
 68 |         if (module.default instanceof RouteModule) {
 69 |           return [module.default as RouteModule, AppFileType.Route];
 70 |         }
 71 |         break;
 72 |       }
 73 |       case "+init.tsx": {
 74 |         if (filePath != path.join(appDirPath, "+init.tsx")) {
 75 |           break;
 76 |         }
 77 |         if (module.default instanceof InitModule) {
 78 |           return [module.default as InitModule, AppFileType.Init];
 79 |         }
 80 |         break;
 81 |       }
 82 |     }
 83 |     throw new Error(
 84 |       `INVALID APP FILE: the following file did not match the spec ${filePath}`,
 85 |     );
 86 |   }
 87 |   static async loadEndpoint(
 88 |     appDirPath: string,
 89 |     filePath: string,
 90 |     parentDirPath: string,
 91 |   ): Promise<string> {
 92 |     let rel = path.relative(appDirPath, parentDirPath);
 93 |     let endpoint: string = "/";
 94 |     if (rel != "") {
 95 |       endpoint = "/" + rel;
 96 |     }
 97 |     return endpoint;
 98 |   }
 99 | }
100 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # xerus-filerouter
  2 | 
  3 | ## Installation
  4 | ```bash
  5 | bun add github:phillip-england/xerus-filerouter#v0.0.1
  6 | ```
  7 | 
  8 | ## Info
  9 | `xerus-filerouter` is a file-based router build onto of my lightweight-webframework, [xerus](https://github.com/phillip-england/xerus).
 10 | 
 11 | ## Usage
 12 | To serve from './app':
 13 | ```ts
 14 | import path from "path";
 15 | 
 16 | try {
 17 |   let router = await XerusFileRouter.new({
 18 |     src: path.join(process.cwd(), "app"),
 19 |     port: 8080,
 20 |   });
 21 |   await router.serve()
 22 | } catch (err: any) {
 23 |   console.log(err.message)
 24 | }
 25 | 
 26 | ```
 27 | 
 28 | ## App Initalization
 29 | Assuming `./app` is your project root, `./app/+init.tsx` is where you can run any init logic:
 30 | 
 31 | Below, I set up logging and serving static files.
 32 | 
 33 | `./app/+init.tsx`:
 34 | ```ts
 35 | let module = new InitModule();
 36 | 
 37 | module.init(async (app: Xerus) => {
 38 |   app.use(logger);
 39 |   app.static("static");
 40 | });
 41 | 
 42 | export default module;
 43 | 
 44 | ```
 45 | 
 46 | ## Routes
 47 | Assuming `./app` is your project root, `./app/+route.tsx` will provide the logic for all routes hitting `/`:
 48 | 
 49 | `./app/+route.tsx`:
 50 | ```ts
 51 | let module = new RouteModule();
 52 | 
 53 | module.get(async (c: HTTPContext) => {
 54 |   return c.jsx(
 55 |     <GuestLayout title="Home Page">
 56 |       <h1>Home Page!</h1>
 57 |     </GuestLayout>,
 58 |   );
 59 | });
 60 | 
 61 | export default module;
 62 | ```
 63 | 
 64 | For `/about`, place the following in `./app/about/route.tsx`:
 65 | ```ts
 66 | let module = new RouteModule();
 67 | 
 68 | module.get(async (c: HTTPContext) => {
 69 |   return c.jsx(
 70 |     <GuestLayout title="About Page">
 71 |       <h1>Home Page!</h1>
 72 |     </GuestLayout>,
 73 |   );
 74 | });
 75 | 
 76 | export default module;
 77 | ```
 78 | 
 79 | For dynamic routing, try `./app/user/:id/+route.tsx`:
 80 | ```ts
 81 | let module = new RouteModule();
 82 | 
 83 | module.get(async (c: HTTPContext) => {
 84 |   return c.jsx(
 85 |     <GuestLayout title="User Page">
 86 |       <h1>User {c.getParam('id')}</h1>
 87 |     </GuestLayout>,
 88 |   );
 89 | });
 90 | 
 91 | export default module;
 92 | ```
 93 | 
 94 | ## Middlware
 95 | Middlware is export out of `+route.tsx` file. All middlware can be of type `Cascade` or `Isolate`.
 96 | 
 97 | In short, `Cascade` middleware will pour down onto any file beneath itself in the filesystem whereas `Isolate` middleware will only affect the route it is exported from.
 98 | 
 99 | For example, here we apply the same middleware, once as `Isolate`, then again as `Cascade`:
100 | 
101 | ```ts
102 | const testmw = new Middleware(
103 |   async (c: HTTPContext, next: MiddlewareNextFn) => {
104 |     console.log("before");
105 |     await next();
106 |     console.log("after");
107 |   },
108 | );
109 | 
110 | 
111 | let module = new RouteModule();
112 | 
113 | module.get(async (c: HTTPContext) => {
114 |   return c.jsx(
115 |     <GuestLayout title="Home Page">
116 |       <h1>User {c.getParam('id')}</h1>
117 |     </GuestLayout>,
118 |   );
119 | }, isolate(testmw), cascade(testmw));
120 | 
121 | export default module;
122 | ```
123 | 
124 | Middleware is excuted from top to bottom in sync with the filesystem.


--------------------------------------------------------------------------------
/src/AppDir.ts:
--------------------------------------------------------------------------------
  1 | import { VirtualAsset, VirtualFS } from "hoist";
  2 | import { AppFile, AppFileType } from "./AppFile";
  3 | import type { MiddlewareExport, RouteModule } from "./RouteModule";
  4 | import { MiddlwareStradegy } from "./MiddlewareStradegy";
  5 | import type { Middleware } from "xerus/xerus";
  6 | 
  7 | function sortFilePaths(filepaths: string[]): string[] {
  8 |   return filepaths.sort((a, b) => {
  9 |     // Count depth (number of separators)
 10 |     const depthA = a.split('/').length;
 11 |     const depthB = b.split('/').length;
 12 |     
 13 |     // First sort by depth
 14 |     if (depthA !== depthB) {
 15 |       return depthA - depthB;
 16 |     }
 17 |     
 18 |     // If same depth, sort alphabetically
 19 |     return a.localeCompare(b);
 20 |   });
 21 | }
 22 | 
 23 | export class AppDir {
 24 |   path: string;
 25 |   vfs: VirtualFS;
 26 |   appFiles: AppFile[];
 27 |   constructor(pth: string, vfs: VirtualFS, appFiles: AppFile[]) {
 28 |     this.path = pth;
 29 |     this.vfs = vfs;
 30 |     this.appFiles = appFiles;
 31 |   }
 32 |   static async load(pth: string): Promise<AppDir> {
 33 |     let vfs = await VirtualFS.load(pth);
 34 |     let appFiles = await AppDir.loadAppFiles(pth, vfs);
 35 |     let unsortedMwExports = await AppDir.loadUnsortedMwExports(appFiles);
 36 |     let dir = new AppDir(pth, vfs, appFiles);
 37 |     return dir;
 38 |   }
 39 |   static async loadUnsortedMwExports(appFiles: AppFile[]) {
 40 |     let mwRecord: Record<string, MiddlewareExport[]> = {
 41 |       'GET': [],
 42 |       'POST': [],
 43 |       'PUT': [],
 44 |       'DELETE': []
 45 |     }
 46 |     for (let i = 0; i < appFiles.length; i++) {
 47 |       let appFile = appFiles[i] as AppFile
 48 |       if (appFile.fileType != AppFileType.Route) {
 49 |         continue
 50 |       }
 51 |       let module = appFile.module as RouteModule
 52 |       mwRecord['GET']?.push()
 53 |     }
 54 |   }
 55 |   static async loadAppFiles(pth: string, vfs: VirtualFS): Promise<AppFile[]> {
 56 |     let files: AppFile[] = [];
 57 |     await vfs.iterAssets(async (asset: VirtualAsset, relPath: string) => {
 58 |       if (asset.isDir()) {
 59 |         return;
 60 |       }
 61 |       let routeFile = await AppFile.load(pth, asset.path);
 62 |       files.push(routeFile);
 63 |     });
 64 |     return files;
 65 |   }
 66 |   async iterAppFiles(
 67 |     callback: (appFile: AppFile) => void | Promise<void>,
 68 |   ): Promise<void> {
 69 |     for (let i = 0; i < this.appFiles.length; i++) {
 70 |       let routeFile = this.appFiles[i] as AppFile;
 71 |       await callback(routeFile);
 72 |     }
 73 |   }
 74 |   async loadMiddleware(method: string, endpoint: string): Promise<Middleware[]> {
 75 |     let mw: Middleware[] = []
 76 |     console.log('loading for: ', endpoint)
 77 |     await this.iterRouteAppFiles(async(routeFile: AppFile) => {
 78 |       if (!endpoint.startsWith(routeFile.endpoint)) {
 79 |         return
 80 |       }
 81 |       let includeIsloated = false;
 82 |       if (endpoint == routeFile.endpoint) {
 83 |         includeIsloated = true;
 84 |       }
 85 |       let module = routeFile.module as RouteModule
 86 |       if (method == 'GET') {
 87 |         for (let i = 0; i < module.getMiddleware.length; i++) {
 88 |           let mwExport = module.getMiddleware[i] as MiddlewareExport
 89 |           if (includeIsloated) {
 90 |             mw.push(mwExport.middleware)
 91 |           } else {
 92 |             if (mwExport.stradegy == MiddlwareStradegy.Cascade) {
 93 |               mw.push(mwExport.middleware)
 94 |             }
 95 |           }
 96 |         }
 97 |       }
 98 |     })
 99 |     return mw;
100 |   }
101 |   async iterRouteAppFiles(callback: (routeFile: AppFile) => void | Promise<void>) {
102 |     let filePaths: string[] = []
103 |     for (let i = 0; i < this.appFiles.length; i++) {
104 |       let appFile = this.appFiles[i] as AppFile;
105 |       if (appFile.fileType != AppFileType.Route) {
106 |         continue
107 |       }
108 |       filePaths.push(appFile.filePath)
109 |     }
110 |     sortFilePaths(filePaths)
111 |     for (let i = 0; i < filePaths.length; i++) {
112 |       let filePath = filePaths[i]
113 |         for (let j = 0; j < this.appFiles.length; j++) {
114 |           let appFile = this.appFiles[j] as AppFile
115 |           if (appFile.fileType != AppFileType.Route) {
116 |             continue
117 |           }
118 |           if (appFile.filePath != filePath) {
119 |             continue
120 |           }
121 |           await callback(appFile)
122 |       }
123 |     }
124 |   }
125 | }
126 | 
127 | 
128 | 


--------------------------------------------------------------------------------
/bun.lock:
--------------------------------------------------------------------------------
 1 | {
 2 |   "lockfileVersion": 1,
 3 |   "workspaces": {
 4 |     "": {
 5 |       "name": "jss",
 6 |       "dependencies": {
 7 |         "@types/react-dom": "^19.2.2",
 8 |         "floss": "github:phillip-england/floss#v0.0.2",
 9 |         "hoist": "github:phillip-england/hoist#v0.0.6",
10 |         "linkedom": "^0.18.12",
11 |         "react": "^19.2.0",
12 |         "react-dom": "^19.2.0",
13 |         "xerus": "github:phillip-england/xerus#v0.0.27",
14 |       },
15 |       "devDependencies": {
16 |         "@types/bun": "latest",
17 |         "prettier": "^3.6.2",
18 |       },
19 |       "peerDependencies": {
20 |         "typescript": "^5",
21 |       },
22 |     },
23 |   },
24 |   "packages": {
25 |     "@types/bun": ["@types/bun@1.3.0", "", { "dependencies": { "bun-types": "1.3.0" } }, "sha512-+lAGCYjXjip2qY375xX/scJeVRmZ5cY0wyHYyCYxNcdEXrQ4AOe3gACgd4iQ8ksOslJtW4VNxBJ8llUwc3a6AA=="],
26 | 
27 |     "@types/node": ["@types/node@24.8.1", "", { "dependencies": { "undici-types": "~7.14.0" } }, "sha512-alv65KGRadQVfVcG69MuB4IzdYVpRwMG/mq8KWOaoOdyY617P5ivaDiMCGOFDWD2sAn5Q0mR3mRtUOgm99hL9Q=="],
28 | 
29 |     "@types/react": ["@types/react@19.2.2", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA=="],
30 | 
31 |     "@types/react-dom": ["@types/react-dom@19.2.2", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw=="],
32 | 
33 |     "boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
34 | 
35 |     "bun-types": ["bun-types@1.3.0", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],
36 | 
37 |     "css-select": ["css-select@5.2.2", "", { "dependencies": { "boolbase": "^1.0.0", "css-what": "^6.1.0", "domhandler": "^5.0.2", "domutils": "^3.0.1", "nth-check": "^2.0.1" } }, "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw=="],
38 | 
39 |     "css-what": ["css-what@6.2.2", "", {}, "sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA=="],
40 | 
41 |     "cssom": ["cssom@0.5.0", "", {}, "sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw=="],
42 | 
43 |     "csstype": ["csstype@3.1.3", "", {}, "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw=="],
44 | 
45 |     "dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
46 | 
47 |     "domelementtype": ["domelementtype@2.3.0", "", {}, "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw=="],
48 | 
49 |     "domhandler": ["domhandler@5.0.3", "", { "dependencies": { "domelementtype": "^2.3.0" } }, "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w=="],
50 | 
51 |     "domutils": ["domutils@3.2.2", "", { "dependencies": { "dom-serializer": "^2.0.0", "domelementtype": "^2.3.0", "domhandler": "^5.0.3" } }, "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw=="],
52 | 
53 |     "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
54 | 
55 |     "floss": ["floss@github:phillip-england/floss#3d408b0", { "peerDependencies": { "typescript": "^5" } }, "Phillip-England-floss-3d408b0"],
56 | 
57 |     "hoist": ["hoist@github:phillip-england/hoist#4b11c79", { "dependencies": { "floss": "github.com:phillip-england/floss" }, "peerDependencies": { "typescript": "^5" } }, "Phillip-England-hoist-4b11c79"],
58 | 
59 |     "html-escaper": ["html-escaper@3.0.3", "", {}, "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ=="],
60 | 
61 |     "htmlparser2": ["htmlparser2@10.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.3", "domutils": "^3.2.1", "entities": "^6.0.0" } }, "sha512-TwAZM+zE5Tq3lrEHvOlvwgj1XLWQCtaaibSN11Q+gGBAS7Y1uZSWwXXRe4iF6OXnaq1riyQAPFOBtYc77Mxq0g=="],
62 | 
63 |     "linkedom": ["linkedom@0.18.12", "", { "dependencies": { "css-select": "^5.1.0", "cssom": "^0.5.0", "html-escaper": "^3.0.3", "htmlparser2": "^10.0.0", "uhyphen": "^0.2.0" }, "peerDependencies": { "canvas": ">= 2" }, "optionalPeers": ["canvas"] }, "sha512-jalJsOwIKuQJSeTvsgzPe9iJzyfVaEJiEXl+25EkKevsULHvMJzpNqwvj1jOESWdmgKDiXObyjOYwlUqG7wo1Q=="],
64 | 
65 |     "nth-check": ["nth-check@2.1.1", "", { "dependencies": { "boolbase": "^1.0.0" } }, "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w=="],
66 | 
67 |     "prettier": ["prettier@3.6.2", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ=="],
68 | 
69 |     "react": ["react@19.2.0", "", {}, "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ=="],
70 | 
71 |     "react-dom": ["react-dom@19.2.0", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.0" } }, "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ=="],
72 | 
73 |     "scheduler": ["scheduler@0.27.0", "", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
74 | 
75 |     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
76 | 
77 |     "uhyphen": ["uhyphen@0.2.0", "", {}, "sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA=="],
78 | 
79 |     "undici-types": ["undici-types@7.14.0", "", {}, "sha512-QQiYxHuyZ9gQUIrmPo3IA+hUl4KYk8uSA7cHrcKd/l3p1OTpZcM0Tbp9x7FAtXdAYhlasd60ncPpgu6ihG6TOA=="],
80 | 
81 |     "xerus": ["xerus@github:phillip-england/xerus#7d1ffd1", { "peerDependencies": { "@types/react-dom": "^19.2.2", "react": "^19.2.0", "react-dom": "^19.2.0", "typescript": "^5.0.0" } }, "Phillip-England-xerus-7d1ffd1"],
82 | 
83 |     "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
84 | 
85 |     "hoist/floss": ["floss@git+ssh://github.com:phillip-england/floss#ebe7ce046a55edd2684c48f305db672a366dec43", { "peerDependencies": { "typescript": "^5" } }, "ebe7ce046a55edd2684c48f305db672a366dec43"],
86 |   }
87 | }
88 | 


--------------------------------------------------------------------------------