orpc-file-based-router 0.1.0 → 0.1.2

package/README.md

@@ -1,15 +1,15 @@
 # orpc-file-based-router
 
-A plugin for [oRPC](https://orpc.unnoq.com) that automatically creates an oRPC router configuration based on your file
-structure, similar to Next.js, express-file-routing
+A plugin for [oRPC](https://orpc.unnoq.com) that automatically generates an oRPC router configuration based on your file
+structure, inspired by Next.js and express-file-routing approaches.
 
-## Highlights
+## ✨ Highlights
 
-- 📁 **File-based structure**: Organize your API endpoints intuitively through your filesystem
-- 🔄 **Zero configuration**: Generate routes automatically based on your directory structure
-- ⚡️ **Development speed**: Eliminate boilerplate code and reduce maintenance overhead
-- 🔍 **Dynamic routing**: Support for path parameters using `{param}` syntax in file names
-- 📑 **Index handling**: Support for index routes via `index.ts` files
+- 📁 **File-based Structure**: Organize your API endpoints intuitively through your filesystem
+- 🔄 **Zero Configuration**: Generate routes automatically based on your directory structure
+- ⚡️ **Development Speed**: Eliminate boilerplate code and reduce maintenance overhead
+- 🔍 **Dynamic Routing**: Support for path parameters using `{param}` syntax in file names
+- 📑 **Index Routes**: Support for index routes via `index.ts` files
 
 > ⚠️ **IMPORTANT:** At this time, the plugin's functionality is only guaranteed
 > in nodejs runtime
@@ -62,21 +62,35 @@ const router = await createRouter(routesDir);
 const handler = new RPCHandler(router);
 
 ```
-> **Note:** If your environment doesn't support top-level await, wrap your server startup code in an async function:
-> ```typescript
-> async function startServer() {
->   const router = await createRouter(routesDir);
->   const handler = new RPCHandler(router);
->   // ... start your server
-> }
-> startServer();
-> ```
+> **Note:** If your environment doesn't support top-level await, just use `cachedRouter` for example in expressjs it could be:
+```typescript
+import { RPCHandler } from "@orpc/server/node";
+import { cachedRouter } from "orpc-file-based-router";
+
+const routesDir = new URL("./routes", import.meta.url).pathname;
+const router = cachedRouter(routesDir)
 
-## Type-Safe Client Configuration (Optional)
+app.use('/rpc{/*path}', async (req, res, next) => {
 
-If you plan to use [oRPC client](https://orpc.unnoq.com/docs/client/client-side), you can set up automatic configuration generation, which can be used for client typing.
+    const handler = new RPCHandler(await router.getRouter());
+
+    const { matched } = await handler.handle(req, res, {
+        prefix: '/rpc',
+    })
+
+    if (matched) {
+        return
+    }
+
+    next()
+})
+```
 
-1. Add the following code to your main server file (e.g., `server.ts` or `main.ts`) or anywhere else. This will automatically regenerate the router configuration each time your server starts:
+## 🔒 Type-Safe Client Configuration (Optional)
+
+For users of the [oRPC client](https://orpc.unnoq.com/docs/client/client-side), we provide automatic configuration generation for enhanced type safety and improved developer experience.
+
+1. Add the following code to your main server file (e.g., `server.ts` or `main.ts`). This will automatically regenerate the router configuration each time your server starts:
 
 ```typescript
 import { generateRouter } from "orpc-file-based-router";
@@ -121,6 +135,16 @@ const client: RouterClient<typeof router> = createORPCClient(link)
 
 ```
 
-## License
+## 🛠 Configuration Options
+
+When using `generateRouter`, you can provide additional options to customize the output:
+
+| Field              | Type      | Required | Default Value | Description                                                                                                                     |
+|-------------------|----------|--------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------|
+| `importExtension` | string   | false         | `""`(No extension) | File extension to append to import statements in the generated router. Useful when your build setup requires specific extensions. <br>Example: `.js` → `import { me } from "./routes/auth/me.js"` |
+
+
+
+## 📄 License
 
-MIT
+MIT License - feel free to use this in your own projects!

package/dist/index.cjs

@@ -36,6 +36,17 @@ async function createRouter(routesDir) {
     return r.exports[e].route({ path: `${r.path}` });
   });
 }
+async function cachedRouter(routesDir) {
+  let router = null;
+  return {
+    getRouter: async () => {
+      if (!router) {
+        router = await createRouter(routesDir);
+      }
+      return router;
+    }
+  };
+}
 async function generateRouter(routesDir, outputFile, options) {
   const files = walkTree(
     routesDir
@@ -43,7 +54,7 @@ async function generateRouter(routesDir, outputFile, options) {
   const exports = await generateRoutes(files);
   const importPaths = exports.map((x) => path.relative(path.dirname(outputFile), routesDir).concat(x.path));
   const content = buildRouter(exports, (r, e) => {
-    return `${e}.route({ path: '${r.path}' })`;
+    return `${e}.route({ path: '${r.path.replace(/\/{0,1}index$/, "")}' })`;
   });
   let routerContent = `// This file is auto-generated
 
@@ -120,5 +131,6 @@ async function generateRoutes(files) {
   return routes;
 }
 
+exports.cachedRouter = cachedRouter;
 exports.createRouter = createRouter;
 exports.generateRouter = generateRouter;

package/dist/index.d.cts

@@ -1,8 +1,17 @@
 declare function createRouter(routesDir: string): Promise<Router>;
+declare function cachedRouter(routesDir: string): Promise<{
+    getRouter: () => Promise<Router>;
+}>;
 type GeneratorOptions = {
+    /**
+     * File extension to append to import statements in the generated router.
+     * Useful when your build setup requires specific extensions.
+     * @example ".js" will generate imports like: import { me } from "./routes/auth/me.js"
+     * @default "" (no extension)
+     */
     importExtension?: string;
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
 type Router = Record<string, any>;
 
-export { createRouter, generateRouter };
+export { cachedRouter, createRouter, generateRouter };

package/dist/index.d.mts

@@ -1,8 +1,17 @@
 declare function createRouter(routesDir: string): Promise<Router>;
+declare function cachedRouter(routesDir: string): Promise<{
+    getRouter: () => Promise<Router>;
+}>;
 type GeneratorOptions = {
+    /**
+     * File extension to append to import statements in the generated router.
+     * Useful when your build setup requires specific extensions.
+     * @example ".js" will generate imports like: import { me } from "./routes/auth/me.js"
+     * @default "" (no extension)
+     */
     importExtension?: string;
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
 type Router = Record<string, any>;
 
-export { createRouter, generateRouter };
+export { cachedRouter, createRouter, generateRouter };

package/dist/index.d.ts

@@ -1,8 +1,17 @@
 declare function createRouter(routesDir: string): Promise<Router>;
+declare function cachedRouter(routesDir: string): Promise<{
+    getRouter: () => Promise<Router>;
+}>;
 type GeneratorOptions = {
+    /**
+     * File extension to append to import statements in the generated router.
+     * Useful when your build setup requires specific extensions.
+     * @example ".js" will generate imports like: import { me } from "./routes/auth/me.js"
+     * @default "" (no extension)
+     */
     importExtension?: string;
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
 type Router = Record<string, any>;
 
-export { createRouter, generateRouter };
+export { cachedRouter, createRouter, generateRouter };

package/dist/index.mjs

@@ -30,6 +30,17 @@ async function createRouter(routesDir) {
     return r.exports[e].route({ path: `${r.path}` });
   });
 }
+async function cachedRouter(routesDir) {
+  let router = null;
+  return {
+    getRouter: async () => {
+      if (!router) {
+        router = await createRouter(routesDir);
+      }
+      return router;
+    }
+  };
+}
 async function generateRouter(routesDir, outputFile, options) {
   const files = walkTree(
     routesDir
@@ -37,7 +48,7 @@ async function generateRouter(routesDir, outputFile, options) {
   const exports = await generateRoutes(files);
   const importPaths = exports.map((x) => relative(dirname(outputFile), routesDir).concat(x.path));
   const content = buildRouter(exports, (r, e) => {
-    return `${e}.route({ path: '${r.path}' })`;
+    return `${e}.route({ path: '${r.path.replace(/\/{0,1}index$/, "")}' })`;
   });
   let routerContent = `// This file is auto-generated
 
@@ -114,4 +125,4 @@ async function generateRoutes(files) {
   return routes;
 }
 
-export { createRouter, generateRouter };
+export { cachedRouter, createRouter, generateRouter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orpc-file-based-router",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "File-based router plugin for oRPC - automatically generate oRPC router from your file structure",
   "author": "zeeeeby",
   "license": "MIT",