@efebia/fastify-auto-import 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @efebia/fastify-auto-import
+
+Fastify plugin that automatically discovers and registers route plugins from a directory.
+
+## Install
+
+```bash
+npm install @efebia/fastify-auto-import
+```
+
+## Usage
+
+```ts
+import Fastify from 'fastify';
+import autoImport from '@efebia/fastify-auto-import';
+
+const fastify = Fastify();
+
+await fastify.register(autoImport, {
+  // Required: the starting directory (use import.meta.url in ESM)
+  startingDirectory: import.meta.url,
+  // Directory to scan, relative to startingDirectory (default: 'src/plugins')
+  directory: 'src/plugins',
+  // File name to import from each subdirectory (default: 'routes')
+  routeFile: 'routes',
+  // Subdirectories to skip (default: [])
+  excludedDirectories: ['_shared'],
+});
+```
+
+Given the following structure:
+
+```
+src/plugins/
+  users/
+    routes.ts
+  orders/
+    routes.ts
+  _shared/
+    utils.ts   ← skipped
+```
+
+The plugin will register `users/routes.ts` and `orders/routes.ts` as Fastify plugins.
+
+Each route file must export a default Fastify plugin:
+
+```ts
+// src/plugins/users/routes.ts
+import type { FastifyPluginAsync } from 'fastify';
+
+const plugin: FastifyPluginAsync = async (fastify) => {
+  fastify.get('/users', async () => ({ users: [] }));
+};
+
+export default plugin;
+```
+
+## API
+
+### `autoImport` (default export)
+
+A `fastify-plugin` compatible plugin. Register it with `fastify.register()`.
+
+**Options** (`Globber`):
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `startingDirectory` | `string` | — | **Required.** Base directory. Pass `import.meta.url` (ESM) or `__dirname` (CJS). |
+| `directory` | `string` | `'src/plugins'` | Directory to scan for route subdirectories, relative to `startingDirectory`. |
+| `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. |
+| `log` | `pino.BaseLogger` | Fastify logger | Logger instance for import errors. |
+
+## Recursive mode
+
+By default the plugin only looks at **direct subdirectories** of `directory`. Set `recursive: true` to walk the entire tree and register every subdirectory that contains a route file, at any depth.
+
+```ts
+await fastify.register(autoImport, {
+  startingDirectory: import.meta.url,
+  directory: 'src/plugins',
+  recursive: true,
+});
+```
+
+Given this structure:
+
+```
+src/plugins/
+  users/
+    routes.ts          ← registered
+    profile/
+      routes.ts        ← registered (nested)
+  orders/
+    routes.ts          ← registered
+    items/
+      routes.ts        ← registered (nested)
+  _shared/
+    utils.ts           ← skipped (no routes file)
+```
+
+Without `recursive`, only `users/routes.ts` and `orders/routes.ts` would be registered. With `recursive: true`, `users/profile/routes.ts` and `orders/items/routes.ts` are picked up as well.
+
+`excludedDirectories` still applies at every depth — a matching directory name is skipped along with all its descendants.
+
+## License
+
+MIT

package/lib/cjs/globber.d.ts

@@ -5,7 +5,8 @@ export type Globber = {
     startingDirectory: string;
     log?: pino.BaseLogger;
     excludedDirectories?: string[];
+    recursive?: boolean;
 };
 export declare const globFiles: (opts: Required<Globber> & {
     log?: pino.BaseLogger;
-}) => Promise<never[]>;
+}) => Promise<any[]>;

package/lib/cjs/globber.js

@@ -52,10 +52,57 @@ const getPackageType = async (directory) => {
         return JSON.parse(file).type;
     }
 };
+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 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`);
+        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;
+            try {
+                if (opts.packageType === 'module') {
+                    const imported = await Promise.resolve(`${href}`).then(s => __importStar(require(s)));
+                    if (imported.default)
+                        results.push(imported.default);
+                }
+                else {
+                    const imported = require(osPath);
+                    if (imported)
+                        results.push(imported);
+                }
+            }
+            catch (e) {
+                (_a = opts.log) === null || _a === void 0 ? void 0 : _a.error({ error: e, path: osPath }, '@efebia/fastify-auto-import error on importing plugin');
+                throw e;
+            }
+        }
+        const nested = await collectRecursivePlugins(subDir, opts);
+        results.push(...nested);
+    }
+    return results;
+};
 const globFiles = async (opts) => {
     const packageType = await 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) {
+        const plugins = await collectRecursivePlugins(pluginsDirectory, {
+            routeFile: opts.routeFile,
+            packageType,
+            excludedDirectories: opts.excludedDirectories,
+            log: opts.log,
+        });
+        return plugins.filter(Boolean);
+    }
     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 () => {
@@ -72,7 +119,7 @@ const globFiles = async (opts) => {
         catch (e) {
             console.log(e);
             (_a = opts.log) === null || _a === void 0 ? void 0 : _a.error({ error: e, path: osPath }, "@efebia/fastify-auto-import error on importing plugin");
-            return null;
+            throw e;
         }
     }));
     return importedFiles.filter((e) => e);

package/lib/cjs/index.js

@@ -6,8 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fastify_plugin_1 = __importDefault(require("fastify-plugin"));
 const globber_js_1 = require("./globber.js");
 const plugin = (0, fastify_plugin_1.default)(async (fastify, opts) => {
-    var _a, _b, _c;
-    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 : [] }));
+    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 }));
     await Promise.all(globbedFiles.map(async (globbedFile) => {
         await fastify.register(globbedFile);
     }));

package/lib/esm/globber.d.ts

@@ -5,7 +5,8 @@ export type Globber = {
     startingDirectory: string;
     log?: pino.BaseLogger;
     excludedDirectories?: string[];
+    recursive?: boolean;
 };
 export declare const globFiles: (opts: Required<Globber> & {
     log?: pino.BaseLogger;
-}) => Promise<never[]>;
+}) => Promise<any[]>;

package/lib/esm/globber.js

@@ -13,10 +13,57 @@ const getPackageType = async (directory) => {
         return JSON.parse(file).type;
     }
 };
+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 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`);
+        if (hasRouteFile) {
+            const osPath = path.join(subDir, opts.packageType === 'module' ? `${routeFileName}.js` : routeFileName);
+            const href = url.pathToFileURL(osPath).href;
+            try {
+                if (opts.packageType === 'module') {
+                    const imported = await import(href);
+                    if (imported.default)
+                        results.push(imported.default);
+                }
+                else {
+                    const imported = require(osPath);
+                    if (imported)
+                        results.push(imported);
+                }
+            }
+            catch (e) {
+                (_a = opts.log) === null || _a === void 0 ? void 0 : _a.error({ error: e, path: osPath }, '@efebia/fastify-auto-import error on importing plugin');
+                throw e;
+            }
+        }
+        const nested = await collectRecursivePlugins(subDir, opts);
+        results.push(...nested);
+    }
+    return results;
+};
 export const globFiles = async (opts) => {
     const packageType = await getPackageType(opts.directory);
     const startingDirectory = packageType === 'module' ? path.dirname(fileURLToPath(opts.startingDirectory)) : opts.startingDirectory;
     const pluginsDirectory = path.join(startingDirectory, opts.directory);
+    if (opts.recursive) {
+        const plugins = await collectRecursivePlugins(pluginsDirectory, {
+            routeFile: opts.routeFile,
+            packageType,
+            excludedDirectories: opts.excludedDirectories,
+            log: opts.log,
+        });
+        return plugins.filter(Boolean);
+    }
     const routesDirectories = await readdir(pluginsDirectory);
     const filteredDirectories = routesDirectories.filter(dir => !opts.excludedDirectories.includes(dir));
     const importedFiles = await serial(filteredDirectories.map((dir) => async () => {
@@ -33,7 +80,7 @@ export const globFiles = async (opts) => {
         catch (e) {
             console.log(e);
             (_a = opts.log) === null || _a === void 0 ? void 0 : _a.error({ error: e, path: osPath }, "@efebia/fastify-auto-import error on importing plugin");
-            return null;
+            throw e;
         }
     }));
     return importedFiles.filter((e) => e);

package/lib/esm/index.js

@@ -1,8 +1,8 @@
 import fp from 'fastify-plugin';
 import { globFiles } from './globber.js';
 const plugin = fp(async (fastify, opts) => {
-    var _a, _b, _c;
-    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 : [] }));
+    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 }));
     await Promise.all(globbedFiles.map(async (globbedFile) => {
         await fastify.register(globbedFile);
     }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@efebia/fastify-auto-import",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,20 +12,19 @@
     "pkg-up": "^3.1.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.2.5",
     "@types/node": "^18.11.18",
-    "jest": "^29.3.1",
-    "ts-jest": "^29.0.3",
+    "tsx": "^4.20.3",
     "typescript": "~5.8.3"
   },
   "files": [
     "/lib"
   ],
   "scripts": {
-    "test": "yarn node $(yarn bin jest)",
-    "build:esm": "tsc --module nodenext --moduleResolution nodenext --outDir lib/esm",
-    "build:cjs": "tsc --module commonjs --moduleResolution node --outDir lib/cjs",
-    "build": "yarn build:esm && yarn build:cjs"
+    "build:esm": "tsc -p ./tsconfig.build.json --module nodenext --moduleResolution nodenext --outDir lib/esm",
+    "build:cjs": "tsc -p ./tsconfig.build.json --module commonjs --moduleResolution node --outDir lib/cjs",
+    "build": "yarn build:esm && yarn build:cjs",
+    "test": "node --import tsx --test ./**/*.test.ts",
+    "test:only": "node --import tsx --test-only ./**/*.test.ts"
   },
   "exports": {
     ".": {