@efebia/fastify-auto-import 1.1.0 → 1.2.0

package/README.md

@@ -70,6 +70,7 @@ A `fastify-plugin` compatible plugin. Register it with `fastify.register()`.
 | `routeFile` | `string` | `'routes'` | File name (without extension) to import from each subdirectory. |
 | `excludedDirectories` | `string[]` | `[]` | Subdirectory names to skip. |
 | `recursive` | `boolean` | `false` | Scan nested subdirectories for route files, not just direct children. |
+| `fileBasedRouting` | `boolean` | `false` | Derive each folder's URL prefix from its path. See below. |
 | `log` | `pino.BaseLogger` | Fastify logger | Logger instance for import errors. |
 
 ## Recursive mode
@@ -104,6 +105,29 @@ Without `recursive`, only `users/routes.ts` and `orders/routes.ts` would be regi
 
 `excludedDirectories` still applies at every depth — a matching directory name is skipped along with all its descendants.
 
+## File-based routing
+
+Set `fileBasedRouting: true` to make folders the URL. It walks the whole tree (no need for `recursive`).
+
+```
+src/routes/
+  api/
+    users/
+      routes.ts            ← /api/users
+      get.ts               ← plain handler, imported by routes.ts (not auto-loaded)
+      [userId]/
+        routes.ts          ← /api/users/:userId
+    (private)/
+      tasks/routes.ts      ← /api/tasks  ((private) adds no segment)
+```
+
+- The full folder path is the URL. Each `routes.ts` is registered flat, in its own encapsulated scope, with that path as `prefix`, so it only declares paths relative to its folder (`app.get('/', ...)`, `app.get('/export', ...)`).
+- Scopes are independent: hooks in a parent folder's `routes.ts` never apply to child folders (and vice versa).
+- `[id]` becomes `:id`. Folders named `_x` or `(group)` add no segment.
+- Only the `routes` file is loaded. Anything else in the folder (handlers, schemas) is yours to import from it.
+- Middleware is not built in. Add hooks or `preHandler`s in each `routes.ts` that needs them.
+- `excludedDirectories` and `routeFile` behave as usual.
+
 ## License
 
 MIT

package/lib/cjs/globber.d.ts

@@ -6,7 +6,16 @@ export type Globber = {
     log?: pino.BaseLogger;
     excludedDirectories?: string[];
     recursive?: boolean;
+    fileBasedRouting?: boolean;
 };
-export declare const globFiles: (opts: Required<Globber> & {
+export declare const getPackageType: (directory: string) => Promise<any>;
+export declare const resolvePluginsDirectory: (opts: Pick<Globber, "directory" | "startingDirectory"> & {
+    directory: string;
+}) => Promise<{
+    packageType: any;
+    pluginsDirectory: string;
+}>;
+export declare const importPlugin: (dir: string, fileName: string, packageType: string, entries: string[], log?: pino.BaseLogger) => Promise<any | undefined>;
+export declare const globFiles: (opts: Required<Omit<Globber, "fileBasedRouting">> & {
     log?: pino.BaseLogger;
 }) => Promise<any[]>;

package/lib/cjs/globber.js

@@ -36,12 +36,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.globFiles = void 0;
+exports.globFiles = exports.importPlugin = exports.resolvePluginsDirectory = exports.getPackageType = void 0;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = __importStar(require("node:url"));
 const pkg_up_1 = __importDefault(require("pkg-up"));
-const serial_js_1 = require("./serial.js");
 const getPackageType = async (directory) => {
     const nearestPackage = await (0, pkg_up_1.default)({ cwd: directory });
     if (nearestPackage) {
@@ -52,19 +51,40 @@ const getPackageType = async (directory) => {
         return JSON.parse(file).type;
     }
 };
+exports.getPackageType = getPackageType;
+const resolvePluginsDirectory = async (opts) => {
+    const packageType = await (0, exports.getPackageType)(opts.directory);
+    const startingDirectory = packageType === 'module' ? node_path_1.default.dirname((0, node_url_1.fileURLToPath)(opts.startingDirectory)) : opts.startingDirectory;
+    return { packageType, pluginsDirectory: node_path_1.default.join(startingDirectory, opts.directory) };
+};
+exports.resolvePluginsDirectory = resolvePluginsDirectory;
+const importPlugin = async (dir, fileName, packageType, entries, log) => {
+    const name = fileName.replace('.js', '');
+    if (!entries.some((f) => f === `${name}.js` || f === `${name}.ts`))
+        return undefined;
+    const osPath = node_path_1.default.join(dir, packageType === 'module' ? `${name}.js` : name);
+    try {
+        if (packageType === 'module') {
+            return (await Promise.resolve(`${node_url_1.default.pathToFileURL(osPath).href}`).then(s => __importStar(require(s)))).default;
+        }
+        return require(osPath);
+    }
+    catch (e) {
+        log === null || log === void 0 ? void 0 : log.error({ error: e, path: osPath }, '@efebia/fastify-auto-import error on importing plugin');
+        throw e;
+    }
+};
+exports.importPlugin = importPlugin;
 const collectRecursivePlugins = async (dir, opts) => {
-    var _a;
     const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
-    const results = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        if (opts.excludedDirectories.includes(entry.name))
-            continue;
+    const dirEntries = entries.filter((entry) => entry.isDirectory() && !opts.excludedDirectories.includes(entry.name));
+    const perDirResults = await Promise.all(dirEntries.map(async (entry) => {
+        var _a;
         const subDir = node_path_1.default.join(dir, entry.name);
         const subEntries = await (0, promises_1.readdir)(subDir);
         const routeFileName = opts.routeFile.replace('.js', '');
         const hasRouteFile = subEntries.some((f) => f === `${routeFileName}.js` || f === `${routeFileName}.ts`);
+        const own = [];
         if (hasRouteFile) {
             const osPath = node_path_1.default.join(subDir, opts.packageType === 'module' ? `${routeFileName}.js` : routeFileName);
             const href = node_url_1.default.pathToFileURL(osPath).href;
@@ -72,12 +92,12 @@ const collectRecursivePlugins = async (dir, opts) => {
                 if (opts.packageType === 'module') {
                     const imported = await Promise.resolve(`${href}`).then(s => __importStar(require(s)));
                     if (imported.default)
-                        results.push(imported.default);
+                        own.push(imported.default);
                 }
                 else {
                     const imported = require(osPath);
                     if (imported)
-                        results.push(imported);
+                        own.push(imported);
                 }
             }
             catch (e) {
@@ -86,12 +106,12 @@ const collectRecursivePlugins = async (dir, opts) => {
             }
         }
         const nested = await collectRecursivePlugins(subDir, opts);
-        results.push(...nested);
-    }
-    return results;
+        return [...own, ...nested];
+    }));
+    return perDirResults.flat();
 };
 const globFiles = async (opts) => {
-    const packageType = await getPackageType(opts.directory);
+    const packageType = await (0, exports.getPackageType)(opts.directory);
     const startingDirectory = packageType === 'module' ? node_path_1.default.dirname((0, node_url_1.fileURLToPath)(opts.startingDirectory)) : opts.startingDirectory;
     const pluginsDirectory = node_path_1.default.join(startingDirectory, opts.directory);
     if (opts.recursive) {
@@ -105,7 +125,7 @@ const globFiles = async (opts) => {
     }
     const routesDirectories = await (0, promises_1.readdir)(pluginsDirectory);
     const filteredDirectories = routesDirectories.filter(dir => !opts.excludedDirectories.includes(dir));
-    const importedFiles = await (0, serial_js_1.serial)(filteredDirectories.map((dir) => async () => {
+    const importedFiles = await Promise.all(filteredDirectories.map(async (dir) => {
         var _a;
         const osPath = node_path_1.default.join(pluginsDirectory, dir, packageType === 'module' ? `${opts.routeFile.replace(".js", "")}.js` : opts.routeFile.replace(".js", ""));
         const href = node_url_1.default.pathToFileURL(osPath).href;

package/lib/cjs/index.js

@@ -5,9 +5,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
 const globber_js_1 = require("./globber.js");
+const router_js_1 = require("./router.js");
 const plugin = (0, fastify_plugin_1.default)(async (fastify, opts) => {
-    var _a, _b, _c, _d;
-    const globbedFiles = await (0, globber_js_1.globFiles)(Object.assign(Object.assign({}, opts), { routeFile: (_a = opts.routeFile) !== null && _a !== void 0 ? _a : 'routes', directory: (_b = opts.directory) !== null && _b !== void 0 ? _b : 'src/plugins', log: opts.log || fastify.log, excludedDirectories: (_c = opts.excludedDirectories) !== null && _c !== void 0 ? _c : [], recursive: (_d = opts.recursive) !== null && _d !== void 0 ? _d : false }));
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (opts.fileBasedRouting) {
+        const directory = (_a = opts.directory) !== null && _a !== void 0 ? _a : 'src/plugins';
+        const { packageType, pluginsDirectory } = await (0, globber_js_1.resolvePluginsDirectory)(Object.assign(Object.assign({}, opts), { directory }));
+        const routes = await (0, router_js_1.scanRoutes)(pluginsDirectory, {
+            routeFile: (_b = opts.routeFile) !== null && _b !== void 0 ? _b : 'routes',
+            packageType,
+            excludedDirectories: (_c = opts.excludedDirectories) !== null && _c !== void 0 ? _c : [],
+            log: opts.log || fastify.log,
+        });
+        await (0, router_js_1.registerRoutes)(fastify, routes);
+        return;
+    }
+    const globbedFiles = await (0, globber_js_1.globFiles)(Object.assign(Object.assign({}, opts), { routeFile: (_d = opts.routeFile) !== null && _d !== void 0 ? _d : 'routes', directory: (_e = opts.directory) !== null && _e !== void 0 ? _e : 'src/plugins', log: opts.log || fastify.log, excludedDirectories: (_f = opts.excludedDirectories) !== null && _f !== void 0 ? _f : [], recursive: (_g = opts.recursive) !== null && _g !== void 0 ? _g : false }));
     await Promise.all(globbedFiles.map(async (globbedFile) => {
         await fastify.register(globbedFile);
     }));

package/lib/cjs/router.d.ts

@@ -0,0 +1,16 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+import type pino from "pino";
+export type RouteEntry = {
+    prefix: string;
+    plugin: FastifyPluginAsync;
+};
+export declare const segmentToPrefix: (name: string) => string;
+type ScanOptions = {
+    routeFile: string;
+    packageType: string;
+    excludedDirectories: string[];
+    log?: pino.BaseLogger;
+};
+export declare const scanRoutes: (dir: string, opts: ScanOptions, prefix?: string) => Promise<RouteEntry[]>;
+export declare const registerRoutes: (fastify: FastifyInstance, routes: RouteEntry[]) => Promise<void>;
+export {};

package/lib/cjs/router.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRoutes = exports.scanRoutes = exports.segmentToPrefix = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const promises_1 = require("node:fs/promises");
+const globber_js_1 = require("./globber.js");
+const segmentToPrefix = (name) => {
+    if (name.startsWith("_") || /^\(.*\)$/.test(name))
+        return "";
+    const param = name.match(/^\[(.+)\]$/);
+    if (param)
+        return `/:${param[1]}`;
+    return `/${name}`;
+};
+exports.segmentToPrefix = segmentToPrefix;
+const scanRoutes = async (dir, opts, prefix = "") => {
+    const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+    const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const plugin = await (0, globber_js_1.importPlugin)(dir, opts.routeFile, opts.packageType, files, opts.log);
+    const nested = await Promise.all(entries
+        .filter((e) => e.isDirectory() && !opts.excludedDirectories.includes(e.name))
+        .map((e) => (0, exports.scanRoutes)(node_path_1.default.join(dir, e.name), opts, prefix + (0, exports.segmentToPrefix)(e.name))));
+    return [...(plugin ? [{ prefix, plugin }] : []), ...nested.flat()];
+};
+exports.scanRoutes = scanRoutes;
+const registerRoutes = async (fastify, routes) => {
+    for (const { prefix, plugin } of routes) {
+        await fastify.register(plugin, prefix ? { prefix } : {});
+    }
+};
+exports.registerRoutes = registerRoutes;

package/lib/esm/globber.d.ts

@@ -6,7 +6,16 @@ export type Globber = {
     log?: pino.BaseLogger;
     excludedDirectories?: string[];
     recursive?: boolean;
+    fileBasedRouting?: boolean;
 };
-export declare const globFiles: (opts: Required<Globber> & {
+export declare const getPackageType: (directory: string) => Promise<any>;
+export declare const resolvePluginsDirectory: (opts: Pick<Globber, "directory" | "startingDirectory"> & {
+    directory: string;
+}) => Promise<{
+    packageType: any;
+    pluginsDirectory: string;
+}>;
+export declare const importPlugin: (dir: string, fileName: string, packageType: string, entries: string[], log?: pino.BaseLogger) => Promise<any | undefined>;
+export declare const globFiles: (opts: Required<Omit<Globber, "fileBasedRouting">> & {
     log?: pino.BaseLogger;
 }) => Promise<any[]>;

package/lib/esm/globber.js

@@ -2,8 +2,7 @@ import { readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import url, { fileURLToPath } from "node:url";
 import pkgUp from "pkg-up";
-import { serial } from "./serial.js";
-const getPackageType = async (directory) => {
+export const getPackageType = async (directory) => {
     const nearestPackage = await pkgUp({ cwd: directory });
     if (nearestPackage) {
         if ('require' in global) {
@@ -13,19 +12,37 @@ const getPackageType = async (directory) => {
         return JSON.parse(file).type;
     }
 };
+export const resolvePluginsDirectory = async (opts) => {
+    const packageType = await getPackageType(opts.directory);
+    const startingDirectory = packageType === 'module' ? path.dirname(fileURLToPath(opts.startingDirectory)) : opts.startingDirectory;
+    return { packageType, pluginsDirectory: path.join(startingDirectory, opts.directory) };
+};
+export const importPlugin = async (dir, fileName, packageType, entries, log) => {
+    const name = fileName.replace('.js', '');
+    if (!entries.some((f) => f === `${name}.js` || f === `${name}.ts`))
+        return undefined;
+    const osPath = path.join(dir, packageType === 'module' ? `${name}.js` : name);
+    try {
+        if (packageType === 'module') {
+            return (await import(url.pathToFileURL(osPath).href)).default;
+        }
+        return require(osPath);
+    }
+    catch (e) {
+        log === null || log === void 0 ? void 0 : log.error({ error: e, path: osPath }, '@efebia/fastify-auto-import error on importing plugin');
+        throw e;
+    }
+};
 const collectRecursivePlugins = async (dir, opts) => {
-    var _a;
     const entries = await readdir(dir, { withFileTypes: true });
-    const results = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        if (opts.excludedDirectories.includes(entry.name))
-            continue;
+    const dirEntries = entries.filter((entry) => entry.isDirectory() && !opts.excludedDirectories.includes(entry.name));
+    const perDirResults = await Promise.all(dirEntries.map(async (entry) => {
+        var _a;
         const subDir = path.join(dir, entry.name);
         const subEntries = await readdir(subDir);
         const routeFileName = opts.routeFile.replace('.js', '');
         const hasRouteFile = subEntries.some((f) => f === `${routeFileName}.js` || f === `${routeFileName}.ts`);
+        const own = [];
         if (hasRouteFile) {
             const osPath = path.join(subDir, opts.packageType === 'module' ? `${routeFileName}.js` : routeFileName);
             const href = url.pathToFileURL(osPath).href;
@@ -33,12 +50,12 @@ const collectRecursivePlugins = async (dir, opts) => {
                 if (opts.packageType === 'module') {
                     const imported = await import(href);
                     if (imported.default)
-                        results.push(imported.default);
+                        own.push(imported.default);
                 }
                 else {
                     const imported = require(osPath);
                     if (imported)
-                        results.push(imported);
+                        own.push(imported);
                 }
             }
             catch (e) {
@@ -47,9 +64,9 @@ const collectRecursivePlugins = async (dir, opts) => {
             }
         }
         const nested = await collectRecursivePlugins(subDir, opts);
-        results.push(...nested);
-    }
-    return results;
+        return [...own, ...nested];
+    }));
+    return perDirResults.flat();
 };
 export const globFiles = async (opts) => {
     const packageType = await getPackageType(opts.directory);
@@ -66,7 +83,7 @@ export const globFiles = async (opts) => {
     }
     const routesDirectories = await readdir(pluginsDirectory);
     const filteredDirectories = routesDirectories.filter(dir => !opts.excludedDirectories.includes(dir));
-    const importedFiles = await serial(filteredDirectories.map((dir) => async () => {
+    const importedFiles = await Promise.all(filteredDirectories.map(async (dir) => {
         var _a;
         const osPath = path.join(pluginsDirectory, dir, packageType === 'module' ? `${opts.routeFile.replace(".js", "")}.js` : opts.routeFile.replace(".js", ""));
         const href = url.pathToFileURL(osPath).href;

package/lib/esm/index.js

@@ -1,8 +1,21 @@
 import fp from 'fastify-plugin';
-import { globFiles } from './globber.js';
+import { globFiles, resolvePluginsDirectory } from './globber.js';
+import { registerRoutes, scanRoutes } from './router.js';
 const plugin = fp(async (fastify, opts) => {
-    var _a, _b, _c, _d;
-    const globbedFiles = await globFiles(Object.assign(Object.assign({}, opts), { routeFile: (_a = opts.routeFile) !== null && _a !== void 0 ? _a : 'routes', directory: (_b = opts.directory) !== null && _b !== void 0 ? _b : 'src/plugins', log: opts.log || fastify.log, excludedDirectories: (_c = opts.excludedDirectories) !== null && _c !== void 0 ? _c : [], recursive: (_d = opts.recursive) !== null && _d !== void 0 ? _d : false }));
+    var _a, _b, _c, _d, _e, _f, _g;
+    if (opts.fileBasedRouting) {
+        const directory = (_a = opts.directory) !== null && _a !== void 0 ? _a : 'src/plugins';
+        const { packageType, pluginsDirectory } = await resolvePluginsDirectory(Object.assign(Object.assign({}, opts), { directory }));
+        const routes = await scanRoutes(pluginsDirectory, {
+            routeFile: (_b = opts.routeFile) !== null && _b !== void 0 ? _b : 'routes',
+            packageType,
+            excludedDirectories: (_c = opts.excludedDirectories) !== null && _c !== void 0 ? _c : [],
+            log: opts.log || fastify.log,
+        });
+        await registerRoutes(fastify, routes);
+        return;
+    }
+    const globbedFiles = await globFiles(Object.assign(Object.assign({}, opts), { routeFile: (_d = opts.routeFile) !== null && _d !== void 0 ? _d : 'routes', directory: (_e = opts.directory) !== null && _e !== void 0 ? _e : 'src/plugins', log: opts.log || fastify.log, excludedDirectories: (_f = opts.excludedDirectories) !== null && _f !== void 0 ? _f : [], recursive: (_g = opts.recursive) !== null && _g !== void 0 ? _g : false }));
     await Promise.all(globbedFiles.map(async (globbedFile) => {
         await fastify.register(globbedFile);
     }));

package/lib/esm/router.d.ts

@@ -0,0 +1,16 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+import type pino from "pino";
+export type RouteEntry = {
+    prefix: string;
+    plugin: FastifyPluginAsync;
+};
+export declare const segmentToPrefix: (name: string) => string;
+type ScanOptions = {
+    routeFile: string;
+    packageType: string;
+    excludedDirectories: string[];
+    log?: pino.BaseLogger;
+};
+export declare const scanRoutes: (dir: string, opts: ScanOptions, prefix?: string) => Promise<RouteEntry[]>;
+export declare const registerRoutes: (fastify: FastifyInstance, routes: RouteEntry[]) => Promise<void>;
+export {};

package/lib/esm/router.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+import { readdir } from "node:fs/promises";
+import { importPlugin } from "./globber.js";
+export const segmentToPrefix = (name) => {
+    if (name.startsWith("_") || /^\(.*\)$/.test(name))
+        return "";
+    const param = name.match(/^\[(.+)\]$/);
+    if (param)
+        return `/:${param[1]}`;
+    return `/${name}`;
+};
+export const scanRoutes = async (dir, opts, prefix = "") => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const plugin = await importPlugin(dir, opts.routeFile, opts.packageType, files, opts.log);
+    const nested = await Promise.all(entries
+        .filter((e) => e.isDirectory() && !opts.excludedDirectories.includes(e.name))
+        .map((e) => scanRoutes(path.join(dir, e.name), opts, prefix + segmentToPrefix(e.name))));
+    return [...(plugin ? [{ prefix, plugin }] : []), ...nested.flat()];
+};
+export const registerRoutes = async (fastify, routes) => {
+    for (const { prefix, plugin } of routes) {
+        await fastify.register(plugin, prefix ? { prefix } : {});
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@efebia/fastify-auto-import",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",