orpc-file-based-router 0.1.5 → 0.1.7

package/README.md

@@ -43,98 +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:
+## 🔒 Enhanced Type-Safe Client Configuration
 
-> ⚠️ If you don't want plugin to generate openapi `route({})` suffix, just set parameter `includeRoute` to `false`
+After generating your router (as shown in step 4 above), you can use it in your client:
 
 ```typescript
-// router.ts
-import { me } from "./routes/auth/me";
-import { signin } from "./routes/auth/signin";
-import { signup } from "./routes/auth/signup";
-import { createPlanet } from "./routes/planets/create";
-import { indexRoute } from "./routes/planets";
-import { listPlanets } from "./routes/planets/list";
-import { findPlanet } from "./routes/planets/{id}/find";
-import { updatePlanet } from "./routes/planets/{id}/update";
-import { sse } from "./routes/sse";
-
-export const router = {
-  auth: {
-    me: me.route({ path: "/auth/me" }),
-    signin: signin.route({ path: "/auth/signin" }),
-    signup: signup.route({ path: "/auth/signup" }),
-  },
-  planets: {
-    create: createPlanet.route({ path: "/planets/create" }),
-    indexRoute: indexRoute.route({ path: "/planets" }),
-    list: listPlanets.route({ path: "/planets/list" }),
-    find: findPlanet.route({ path: "/planets/{id}/find" }),
-    update: updatePlanet.route({ path: "/planets/{id}/update" }),
-  },
-  sse: sse.route({ path: "/sse" }),
-};
-
-
 // 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:
@@ -142,9 +84,20 @@ 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"` |
-| `includeRoute` | boolean   | false         | `true` | When set to true, each route will be wrapped with openapi `.route({ path: '...' })` call   |
+| `additionalMethods` | string[]   | false         | `[]` | Additional HTTP methods to recognize from export names.   |
+
 
+## Examples
+### HTTP Method Matching
+If you export functions named e.g. `get`, `post`, `put`, `patch`, `delete/del` etc. from a route file, those will get matched their corresponding http method automatically.
 
+```typescript
+// ./routes/planets.ts
+
+export const get = orpc.handler(async ({ input, context }) => {})
+
+export const post = orpc.handler(async ({ input, context }) => {})
+```
 
 ## 📄 License
 

package/dist/index.cjs

@@ -7,6 +7,25 @@ function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'defau
 
 const path__default = /*#__PURE__*/_interopDefaultCompat(path);
 
+const METHOD_EXPORTS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD"
+];
+
+const getMethodKey = (method) => {
+  let methodKey = method.toUpperCase();
+  if (methodKey === "DEL") return "DELETE";
+  return methodKey;
+};
+const isMethodExport = (exportName, extraMethods) => {
+  const methods = [...METHOD_EXPORTS, ...extraMethods].map(getMethodKey);
+  return methods.includes(getMethodKey(exportName));
+};
+
 function walkTree(directory, tree = []) {
   const results = [];
   for (const fileName of node_fs.readdirSync(directory)) {
@@ -27,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 = () => {
@@ -49,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
@@ -56,20 +70,25 @@ 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) => {
-    if (options?.includeRoute ?? true) {
-      return `${e}.route({ path: '${r.path.replace(/\/{0,1}index$/, "")}' })`;
-    }
-    return e;
+    const alias = routePathToAlias(r.path, e);
+    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
 
 `;
   const extension = options?.importExtension || "";
-  routerContent += importPaths.map((x, i) => `import { ${Object.keys(exports[i].exports).join(", ")} } from "./${x}${extension}"`).join("\n");
+  routerContent += importPaths.map((x, i) => `import { ${Object.keys(exports[i].exports).map((y) => `${y} as ${routePathToAlias(exports[i].path, y)}`).join(", ")} } from "./${x}${extension}"`).join("\n");
   routerContent += "\n\nexport const router = ";
   routerContent += JSON.stringify(content, null, 2).replace(/"/g, "").replace(/(\s*)([a-zA-Z0-9]+-[a-zA-Z0-9-]+):/g, '$1"$2":');
   node_fs.writeFileSync(path.join(outputFile), routerContent);
 }
+function routePathToAlias(routePath, methodName) {
+  const cleanPath = routePath.replace(/\{(\w+)\}/g, "$1").replace(/-/g, "_");
+  return cleanPath.split("/").filter(Boolean).join("_") + "__" + methodName;
+}
 function buildRoutePath(parsedFile) {
   const directory = parsedFile.dir === parsedFile.root ? "" : parsedFile.dir;
   const name = `/${parsedFile.name}`;
@@ -128,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.
@@ -12,13 +15,10 @@ type GeneratorOptions = {
      */
     importExtension?: string;
     /**
-     * Include openapi route paths in the generated router.
-     * When set to true, each route will have its openapi path
-     * @default true
+     * Additional HTTP methods to recognize from export names.
      */
-    includeRoute?: boolean;
+    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.
@@ -12,13 +15,10 @@ type GeneratorOptions = {
      */
     importExtension?: string;
     /**
-     * Include openapi route paths in the generated router.
-     * When set to true, each route will have its openapi path
-     * @default true
+     * Additional HTTP methods to recognize from export names.
      */
-    includeRoute?: boolean;
+    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.
@@ -12,13 +15,10 @@ type GeneratorOptions = {
      */
     importExtension?: string;
     /**
-     * Include openapi route paths in the generated router.
-     * When set to true, each route will have its openapi path
-     * @default true
+     * Additional HTTP methods to recognize from export names.
      */
-    includeRoute?: boolean;
+    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

@@ -1,6 +1,25 @@
 import { writeFileSync, readdirSync, statSync } from 'node:fs';
 import path, { relative, dirname, join } from 'node:path';
 
+const METHOD_EXPORTS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD"
+];
+
+const getMethodKey = (method) => {
+  let methodKey = method.toUpperCase();
+  if (methodKey === "DEL") return "DELETE";
+  return methodKey;
+};
+const isMethodExport = (exportName, extraMethods) => {
+  const methods = [...METHOD_EXPORTS, ...extraMethods].map(getMethodKey);
+  return methods.includes(getMethodKey(exportName));
+};
+
 function walkTree(directory, tree = []) {
   const results = [];
   for (const fileName of readdirSync(directory)) {
@@ -21,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 = () => {
@@ -43,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
@@ -50,20 +64,25 @@ 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) => {
-    if (options?.includeRoute ?? true) {
-      return `${e}.route({ path: '${r.path.replace(/\/{0,1}index$/, "")}' })`;
-    }
-    return e;
+    const alias = routePathToAlias(r.path, e);
+    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
 
 `;
   const extension = options?.importExtension || "";
-  routerContent += importPaths.map((x, i) => `import { ${Object.keys(exports[i].exports).join(", ")} } from "./${x}${extension}"`).join("\n");
+  routerContent += importPaths.map((x, i) => `import { ${Object.keys(exports[i].exports).map((y) => `${y} as ${routePathToAlias(exports[i].path, y)}`).join(", ")} } from "./${x}${extension}"`).join("\n");
   routerContent += "\n\nexport const router = ";
   routerContent += JSON.stringify(content, null, 2).replace(/"/g, "").replace(/(\s*)([a-zA-Z0-9]+-[a-zA-Z0-9-]+):/g, '$1"$2":');
   writeFileSync(join(outputFile), routerContent);
 }
+function routePathToAlias(routePath, methodName) {
+  const cleanPath = routePath.replace(/\{(\w+)\}/g, "$1").replace(/-/g, "_");
+  return cleanPath.split("/").filter(Boolean).join("_") + "__" + methodName;
+}
 function buildRoutePath(parsedFile) {
   const directory = parsedFile.dir === parsedFile.root ? "" : parsedFile.dir;
   const name = `/${parsedFile.name}`;
@@ -122,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.5",
+  "version": "0.1.7",
   "description": "File-based router plugin for oRPC - automatically generate oRPC router from your file structure",
   "author": "zeeeeby",
   "license": "MIT",