orpc-file-based-router 0.1.6 → 0.1.7

package/README.md

@@ -43,97 +43,40 @@ src/routes
   └── sse.ts
 ```
 
-3. Each file should export an oRPC function 
+3. Each file should export an oRPC function (non-oRPC exports will be ignored)
 
-4. Simply replace router in your handlers with the result of the `createRouter`
-function:
+4. Generate your router before starting the server using the `generateRouter` function:
 
 ```typescript
-import { RPCHandler } from "@orpc/server/node";
-import { createRouter } from "orpc-file-based-router";
-
-const routesDir = new URL("./routes", import.meta.url).pathname;
-const router = await createRouter(routesDir);
-
-const handler = new RPCHandler(router);
-
-```
-**Note:** If your environment doesn't support top-level await, just use `lazy` for example in expressjs it could be:
-```typescript
-import { RPCHandler } from "@orpc/server/node";
-import { lazy, createRouter } from "orpc-file-based-router";
+// router-gen.ts
+import { generateRouter } from "orpc-file-based-router";
 
 const routesDir = new URL("./routes", import.meta.url).pathname;
+const outputFile = new URL("./router.ts", import.meta.url).pathname;
 
-const router = lazy(() => createRouter(routesDir))
-
-app.use('/rpc{/*path}', async (req, res, next) => {
-
-    const handler = new RPCHandler(await router());
-
-    const { matched } = await handler.handle(req, res, {
-        prefix: '/rpc',
-    })
-
-    if (matched) {
-        return
-    }
-
-    next()
-})
+generateRouter(routesDir, outputFile);
 ```
 
-## 🔒 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. You can add this code either directly in your server project (e.g., in server.ts or main.ts) or put it into a separate script (e.g., router-gen.ts).
+5. Import and use the generated router in your server:
 
 ```typescript
-import { generateRouter } from "orpc-file-based-router";
+import { RPCHandler } from "@orpc/server/node";
+import { router } from "./router.js"; // Import the generated router
 
-const routesDir = new URL("./routes", import.meta.url).pathname;
-const outputFile = new URL("./router.ts", import.meta.url).pathname;
-generateRouter(routesDir, outputFile);
+const handler = new RPCHandler(router);
 ```
 
-2. Generated router is ready to use in client:
-
-```typescript
-// router.ts
-
-import { me as auth_me__me } from "./routes/auth/me.js"
-import { signin as auth_signin__signin } from "./routes/auth/signin.js"
-import { signup as auth_signup__signup } from "./routes/auth/signup.js"
-import { createPlanet as planets_create__createPlanet } from "./routes/planets/create.js"
-import { indexRoute as planets_index__indexRoute } from "./routes/planets/index.js"
-import { listPlanets as planets_list__listPlanets } from "./routes/planets/list.js"
-import { findPlanet as planets_id_find__findPlanet } from "./routes/planets/{id}/find.js"
-import { updatePlanet as planets_id_update__updatePlanet } from "./routes/planets/{id}/update.js"
-import { sse as sse__sse } from "./routes/sse.js"
-
-export const router = {
-  auth: {
-    me: auth_me__me.route({ path: '/auth/me', method: 'GET' }),
-    signin: auth_signin__signin.route({ path: '/auth/signin', method: 'POST' }),
-    signup: auth_signup__signup.route({ path: '/auth/signup', method: 'POST' })
-  },
-  planets: {
-    create: planets_create__createPlanet.route({ path: '/planets/create', method: 'POST' }),
-    index: planets_index__indexRoute.route({ path: '/planets', method: 'GET' }),
-    list: planets_list__listPlanets.route({ path: '/planets/list', method: 'GET' }),
-    find: planets_id_find__findPlanet.route({ path: '/planets/{id}/find', method: 'GET' }),
-    update: planets_id_update__updatePlanet.route({ path: '/planets/{id}/update', method: 'PUT' })
-  },
-  sse: sse__sse.route({ path: '/sse', method: 'GET' })
-}
+## 🔒 Enhanced Type-Safe Client Configuration
 
+After generating your router (as shown in step 4 above), you can use it in your client:
 
+```typescript
 // lib/orpc.ts
+import { router } from "../router.js"; // Use the same generated router
 const client: RouterClient<typeof router> = createORPCClient(link)
-
 ```
 
+
 ## 🛠 Configuration Options
 
 When using `generateRouter`, you can provide additional options to customize the output:
@@ -141,7 +84,6 @@ When using `generateRouter`, you can provide additional options to customize the
 | 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"` |
-| `enableOpenAPI` | boolean   | false         | `true` | When set to true, each route will be wrapped with OpenAPI .route({ path: '...', method: '...' }) call   |
 | `additionalMethods` | string[]   | false         | `[]` | Additional HTTP methods to recognize from export names.   |
 
 

package/dist/index.cjs

@@ -46,15 +46,6 @@ function walkTree(directory, tree = []) {
 function mergePaths(...paths) {
   return `/${paths.map((path2) => path2.replace(/^\/|\/$/g, "")).filter((path2) => path2 !== "").join("/")}`;
 }
-async function createRouter(routesDir) {
-  const files = walkTree(
-    routesDir
-  );
-  const exports = await generateRoutes(files);
-  return buildRouter(exports, (r, e) => {
-    return r.exports[e].route({ path: `${r.path}` });
-  });
-}
 const lazy = (create) => {
   let cache = null;
   const fn = () => {
@@ -68,6 +59,10 @@ const lazy = (create) => {
   };
   return fn;
 };
+async function createRouter(routesDir) {
+  const msg = "createRouter is deprecated. Please use generateRouter to generate router file at build time. See https://github.com/zeeeeby/orpc-file-based-router?tab=readme-ov-file#quickstart for more details.";
+  throw new Error(msg);
+}
 async function generateRouter(routesDir, outputFile, options) {
   const files = walkTree(
     routesDir
@@ -76,13 +71,10 @@ async function generateRouter(routesDir, outputFile, options) {
   const importPaths = exports.map((x) => path.relative(path.dirname(outputFile), routesDir).concat(x.path));
   const content = buildRouter(exports, (r, e) => {
     const alias = routePathToAlias(r.path, e);
-    if (options?.enableOpenAPI ?? true) {
-      const orpcMeta = isORPCProcedure(r.exports[e]) ? r.exports[e]["~orpc"] : void 0;
-      const method = isMethodExport(e, options?.additionalMethods || []) ? getMethodKey(e) : orpcMeta?.route?.method || "POST";
-      const config = { path: r.path.replace(/\/{0,1}index$/, ""), method };
-      return `${alias}.route({ path: '${config.path}', method: '${config.method}' })`;
-    }
-    return alias;
+    const orpcMeta = isORPCProcedure(r.exports[e]) ? r.exports[e]["~orpc"] : void 0;
+    const method = isMethodExport(e, options?.additionalMethods || []) ? getMethodKey(e) : orpcMeta?.route?.method || "POST";
+    const config = { path: r.path.replace(/\/{0,1}index$/, ""), method };
+    return `${alias}.route({ path: '${config.path}', method: '${config.method}' })`;
   });
   let routerContent = `// This file is auto-generated
 
@@ -155,13 +147,24 @@ async function generateRoutes(files) {
     const parsedFile = path__default.parse(file.rel);
     const routePath = buildRoutePath(parsedFile);
     const exports = await import(MODULE_IMPORT_PREFIX + path__default.join(file.path, file.name));
-    routes.push({
-      exports,
-      path: routePath
-    });
+    const cleanedExports = removeNonOrpcExports(exports);
+    if (Object.keys(cleanedExports).length > 0)
+      routes.push({
+        exports: cleanedExports,
+        path: routePath
+      });
   }
   return routes;
 }
+const removeNonOrpcExports = (exports) => {
+  const cleanedExports = {};
+  for (const key in exports) {
+    if (isORPCProcedure(exports[key])) {
+      cleanedExports[key] = exports[key];
+    }
+  }
+  return cleanedExports;
+};
 
 exports.createRouter = createRouter;
 exports.generateRouter = generateRouter;

package/dist/index.d.cts

@@ -1,8 +1,11 @@
-declare function createRouter(routesDir: string): Promise<Router>;
 declare const lazy: <T>(create: () => Promise<T> | T) => {
     (): Promise<T>;
     reset(): void;
 };
+/**
+ * @deprecated use generateRouter instead. See https://github.com/zeeeeby/orpc-file-based-router?tab=readme-ov-file#quickstart for more details.
+ */
+declare function createRouter(routesDir: string): Promise<void>;
 type GeneratorOptions = {
     /**
      * File extension to append to import statements in the generated router.
@@ -11,17 +14,11 @@ type GeneratorOptions = {
      * @default "" (no extension)
      */
     importExtension?: string;
-    /**
-     * When set to true, each route will be wrapped with OpenAPI .route({ path: '...', method: '...' }) call
-     * @default true
-     */
-    enableOpenAPI?: boolean;
     /**
      * Additional HTTP methods to recognize from export names.
      */
     additionalMethods?: string[];
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
-type Router = Record<string, any>;
 
 export { createRouter, generateRouter, lazy };

package/dist/index.d.mts

@@ -1,8 +1,11 @@
-declare function createRouter(routesDir: string): Promise<Router>;
 declare const lazy: <T>(create: () => Promise<T> | T) => {
     (): Promise<T>;
     reset(): void;
 };
+/**
+ * @deprecated use generateRouter instead. See https://github.com/zeeeeby/orpc-file-based-router?tab=readme-ov-file#quickstart for more details.
+ */
+declare function createRouter(routesDir: string): Promise<void>;
 type GeneratorOptions = {
     /**
      * File extension to append to import statements in the generated router.
@@ -11,17 +14,11 @@ type GeneratorOptions = {
      * @default "" (no extension)
      */
     importExtension?: string;
-    /**
-     * When set to true, each route will be wrapped with OpenAPI .route({ path: '...', method: '...' }) call
-     * @default true
-     */
-    enableOpenAPI?: boolean;
     /**
      * Additional HTTP methods to recognize from export names.
      */
     additionalMethods?: string[];
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
-type Router = Record<string, any>;
 
 export { createRouter, generateRouter, lazy };

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-declare function createRouter(routesDir: string): Promise<Router>;
 declare const lazy: <T>(create: () => Promise<T> | T) => {
     (): Promise<T>;
     reset(): void;
 };
+/**
+ * @deprecated use generateRouter instead. See https://github.com/zeeeeby/orpc-file-based-router?tab=readme-ov-file#quickstart for more details.
+ */
+declare function createRouter(routesDir: string): Promise<void>;
 type GeneratorOptions = {
     /**
      * File extension to append to import statements in the generated router.
@@ -11,17 +14,11 @@ type GeneratorOptions = {
      * @default "" (no extension)
      */
     importExtension?: string;
-    /**
-     * When set to true, each route will be wrapped with OpenAPI .route({ path: '...', method: '...' }) call
-     * @default true
-     */
-    enableOpenAPI?: boolean;
     /**
      * Additional HTTP methods to recognize from export names.
      */
     additionalMethods?: string[];
 };
 declare function generateRouter(routesDir: string, outputFile: string, options?: GeneratorOptions): Promise<void>;
-type Router = Record<string, any>;
 
 export { createRouter, generateRouter, lazy };

package/dist/index.mjs

@@ -40,15 +40,6 @@ function walkTree(directory, tree = []) {
 function mergePaths(...paths) {
   return `/${paths.map((path2) => path2.replace(/^\/|\/$/g, "")).filter((path2) => path2 !== "").join("/")}`;
 }
-async function createRouter(routesDir) {
-  const files = walkTree(
-    routesDir
-  );
-  const exports = await generateRoutes(files);
-  return buildRouter(exports, (r, e) => {
-    return r.exports[e].route({ path: `${r.path}` });
-  });
-}
 const lazy = (create) => {
   let cache = null;
   const fn = () => {
@@ -62,6 +53,10 @@ const lazy = (create) => {
   };
   return fn;
 };
+async function createRouter(routesDir) {
+  const msg = "createRouter is deprecated. Please use generateRouter to generate router file at build time. See https://github.com/zeeeeby/orpc-file-based-router?tab=readme-ov-file#quickstart for more details.";
+  throw new Error(msg);
+}
 async function generateRouter(routesDir, outputFile, options) {
   const files = walkTree(
     routesDir
@@ -70,13 +65,10 @@ async function generateRouter(routesDir, outputFile, options) {
   const importPaths = exports.map((x) => relative(dirname(outputFile), routesDir).concat(x.path));
   const content = buildRouter(exports, (r, e) => {
     const alias = routePathToAlias(r.path, e);
-    if (options?.enableOpenAPI ?? true) {
-      const orpcMeta = isORPCProcedure(r.exports[e]) ? r.exports[e]["~orpc"] : void 0;
-      const method = isMethodExport(e, options?.additionalMethods || []) ? getMethodKey(e) : orpcMeta?.route?.method || "POST";
-      const config = { path: r.path.replace(/\/{0,1}index$/, ""), method };
-      return `${alias}.route({ path: '${config.path}', method: '${config.method}' })`;
-    }
-    return alias;
+    const orpcMeta = isORPCProcedure(r.exports[e]) ? r.exports[e]["~orpc"] : void 0;
+    const method = isMethodExport(e, options?.additionalMethods || []) ? getMethodKey(e) : orpcMeta?.route?.method || "POST";
+    const config = { path: r.path.replace(/\/{0,1}index$/, ""), method };
+    return `${alias}.route({ path: '${config.path}', method: '${config.method}' })`;
   });
   let routerContent = `// This file is auto-generated
 
@@ -149,12 +141,23 @@ async function generateRoutes(files) {
     const parsedFile = path.parse(file.rel);
     const routePath = buildRoutePath(parsedFile);
     const exports = await import(MODULE_IMPORT_PREFIX + path.join(file.path, file.name));
-    routes.push({
-      exports,
-      path: routePath
-    });
+    const cleanedExports = removeNonOrpcExports(exports);
+    if (Object.keys(cleanedExports).length > 0)
+      routes.push({
+        exports: cleanedExports,
+        path: routePath
+      });
   }
   return routes;
 }
+const removeNonOrpcExports = (exports) => {
+  const cleanedExports = {};
+  for (const key in exports) {
+    if (isORPCProcedure(exports[key])) {
+      cleanedExports[key] = exports[key];
+    }
+  }
+  return cleanedExports;
+};
 
 export { createRouter, generateRouter, lazy };

package/package.json

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