@devmoods/express-extras 0.35.1 → 0.37.0

package/dist/cache.d.ts

@@ -1,4 +1,8 @@
 import { type RedisClient } from './redis.js';
+export interface CacheOptions {
+    key?: string;
+    expiresMs?: number | null;
+}
 export interface CacheAdapter {
     get(key: string): Promise<any>;
     set(key: string, value: any, expires?: number | null | undefined): Promise<void>;
@@ -13,5 +17,6 @@ export declare function createCache(adapter: CacheAdapter): {
     set: (key: string, value: any, expires?: number | null | undefined) => Promise<void>;
     get: (key: string) => Promise<any>;
     clear: (key?: string) => Promise<void>;
-    wrap: <T>(key: string, expiresMs: number | null | undefined, fn: () => Promise<T>) => Promise<T>;
+    wrap: <T>(key: string, options: CacheOptions | number | null, fn: () => Promise<T>) => Promise<T>;
+    decorate: <T, Arguments extends any[]>(options: CacheOptions | number | null, fn: (...args: Arguments) => T | Promise<T>) => (...args: Arguments) => Promise<T>;
 };

package/dist/cache.js

@@ -53,19 +53,41 @@ export function createMemoryCacheAdapter() {
     };
 }
 export function createCache(adapter) {
-    async function cached(key, expiresMs, fn) {
+    async function cached(key, options, fn) {
         const cachedValue = await adapter.get(key);
         if (cachedValue != null) {
             return cachedValue;
         }
+        const expiresMs = typeof options === 'number' || options == null
+            ? options
+            : options.expiresMs;
         const result = await fn();
         await adapter.set(key, result, expiresMs);
         return result;
     }
+    function cachedFn(options, fn) {
+        return async (...args) => {
+            const baseKey = typeof options === 'object' && options != null
+                ? options.key
+                : undefined;
+            const cacheKey = `${baseKey ?? Buffer.from(fn.toString()).toString('hex')}-${JSON.stringify(args)}`;
+            const cachedValue = await adapter.get(cacheKey);
+            if (cachedValue != null) {
+                return cachedValue;
+            }
+            const expiresMs = typeof options === 'number' || options == null
+                ? options
+                : options.expiresMs;
+            const result = await fn(...args);
+            await adapter.set(cacheKey, result, expiresMs);
+            return result;
+        };
+    }
     return {
         set: adapter.set.bind(adapter),
         get: adapter.get.bind(adapter),
         clear: adapter.clear.bind(adapter),
         wrap: cached,
+        decorate: cachedFn,
     };
 }

package/dist/cli.js

@@ -31,7 +31,7 @@ export class CLI {
             const timer = startTimer();
             try {
                 await action(...args);
-                this.greenLine(`Command succeeded in ${timer.getDuration().toFixed(4)}s`);
+                this.greenLine(`Command succeeded in ${timer.getDuration().toFixed(4)}s`, stderr);
             }
             catch (error) {
                 this.redLine(error.message);

package/dist/email.d.ts

@@ -6,12 +6,12 @@ export interface EmailOptions {
     pass?: string;
     senderName: string;
     senderAddress: string;
+    onEmailSent?: (payload: Record<string, any>) => void | Promise<void>;
 }
 export interface SendEmailOptions extends nodemailer.SendMailOptions {
     message: string;
 }
-export declare function createEmail({ host, port, user, pass, senderName, senderAddress, }: EmailOptions): {
+export declare function createEmail({ host, port, user, pass, senderName, senderAddress, onEmailSent, }: EmailOptions): {
     send: ({ to, subject, message, ...rest }: SendEmailOptions) => Promise<void>;
     transporter: nodemailer.Transporter<import("nodemailer/lib/smtp-transport/index.js").SentMessageInfo, import("nodemailer/lib/smtp-transport/index.js").Options>;
-    readonly outbox: Record<string, any>[];
 };

package/dist/email.js

@@ -1,14 +1,13 @@
 import * as nodemailer from 'nodemailer';
 import { getLogger } from './logger.js';
 const logger = getLogger('email');
-export function createEmail({ host, port, user, pass, senderName, senderAddress, }) {
+export function createEmail({ host, port, user, pass, senderName, senderAddress, onEmailSent, }) {
     const transporter = nodemailer.createTransport({
         host,
         port: parseInt(port || '587', 10),
         secure: false,
         auth: { user, pass },
     });
-    const outbox = [];
     const send = async ({ to, subject, message, ...rest }) => {
         const payload = {
             from: `${senderName} <${senderAddress}>`,
@@ -18,17 +17,11 @@ export function createEmail({ host, port, user, pass, senderName, senderAddress,
             ...rest,
         };
         const result = await transporter.sendMail(payload);
-        outbox.push(payload);
-        if (outbox.length > 5) {
-            outbox.shift();
-        }
+        await onEmailSent?.(payload);
         logger.info('email-sent', { email: result });
     };
     return {
         send,
         transporter,
-        get outbox() {
-            return outbox;
-        },
     };
 }

package/dist/faktory.d.ts

@@ -3,26 +3,32 @@ export interface JobsOptions {
     queueName: string;
     faktory?: typeof create;
 }
-export type JobContext = Record<string, any>;
-export declare function createJobs({ queueName, faktory: createFactory, }: JobsOptions): {
-    job: <K extends Record<string, any>, T extends (input: K, ctx: JobContext) => undefined | Promise<any>>(fn: T) => {
+export type AnyJobContext = Record<string, any>;
+export interface JobOptions {
+    retry?: number;
+    priority?: number;
+    at?: Date | string;
+}
+export declare function createJobs<GlobalContext extends AnyJobContext>({ queueName, faktory: createFactory, }: JobsOptions): {
+    job: <Arguments extends Record<string, any>, Fn extends (input: Arguments, ctx: GlobalContext) => undefined | Promise<any>>(optionsOrFn: JobOptions | Fn, fnOrUndefined?: Fn) => {
         $job: boolean;
         jobName: string;
+        options: JobOptions;
         readonly executionCount: number;
-        delay(args?: Parameters<T>[0]): Promise<`${string}-${string}-${string}-${string}-${string}`>;
-        execute(args: Parameters<T>[0], context: JobContext): Promise<any>;
+        delay(args?: Parameters<Fn>[0]): Promise<`${string}-${string}-${string}-${string}-${string}`>;
+        execute(args: Parameters<Fn>[0], context: GlobalContext): Promise<any>;
     };
     queueName: string;
 };
 export type Job = ReturnType<ReturnType<typeof createJobs>['job']>;
-export interface FaktoryWorkerOptions {
+export interface FaktoryWorkerOptions<GlobalContext> {
     jobs: unknown[];
     queueName: string;
     faktory?: typeof create;
-    jobContext?: JobContext;
+    jobContext?: GlobalContext;
 }
 export declare function useJobId(): string | undefined;
-export declare function createFaktoryWorker({ queueName, jobs, faktory: createFactory, jobContext, }: FaktoryWorkerOptions): Promise<{
+export declare function createFaktoryWorker<GlobalContext>({ queueName, jobs, faktory: createFactory, jobContext, }: FaktoryWorkerOptions<GlobalContext>): Promise<{
     start(workerOptions?: WorkerOptions): Promise<void>;
     stop(): Promise<void>;
 }>;

package/dist/faktory.js

@@ -7,7 +7,12 @@ const logger = getLogger('faktory');
 const JOB_ID = 'jobId';
 export function createJobs({ queueName, faktory: createFactory = create, }) {
     const faktory = createFactory();
-    function job(fn) {
+    function job(optionsOrFn, fnOrUndefined) {
+        const fn = typeof optionsOrFn === 'function' ? optionsOrFn : fnOrUndefined;
+        const options = typeof optionsOrFn === 'function' ? {} : optionsOrFn;
+        if (!fn) {
+            throw new Error('job() must get a function has the first or second argument');
+        }
         const jobName = fn.name;
         let executionCount = 0;
         if (!jobName) {
@@ -16,6 +21,7 @@ export function createJobs({ queueName, faktory: createFactory = create, }) {
         return {
             $job: true,
             jobName,
+            options,
             get executionCount() {
                 return executionCount;
             },
@@ -26,6 +32,7 @@ export function createJobs({ queueName, faktory: createFactory = create, }) {
                     const j = client.job(jobName, args);
                     j.jid = jid;
                     j.queue = queueName;
+                    Object.assign(j, options);
                     await j.push();
                     await client.close();
                 }

package/dist/listen.d.ts

@@ -7,7 +7,7 @@ interface StoppableServer extends Server {
 export declare function stoppable(server: Server, grace?: number): StoppableServer;
 interface ExpressServerOptions {
     onShutdown?(): Promise<void> | void;
-    healthCheck?(): Promise<unknown>;
+    healthCheck?(type?: 'live' | 'ready'): Promise<unknown>;
 }
 export declare function createExpressServer(app: Application, options?: ExpressServerOptions): {
     start(): Promise<void>;

package/dist/listen.js

@@ -6,6 +6,7 @@ import {} from 'express';
 import { getLogger } from './logger.js';
 import { before, route } from './middleware.js';
 import { envPort, readEnv } from './utils.js';
+import { validateQuery } from './validate.js';
 const logger = getLogger('http');
 const READINESS_PERIOD = readEnv.number('READINESS_PERIOD_MS', 0);
 const GRACE_PERIOD = readEnv.number('GRACE_PERIOD_MS', 20000);
@@ -96,16 +97,23 @@ export function createExpressServer(app, options = {}) {
         process.on(signal, onSignal);
     }
     if (!app.get('__healthAttached')) {
-        app.get('/health', before(), route(async () => {
+        app.get('/health', before(), validateQuery({
+            type: 'object',
+            properties: {
+                type: { type: 'string', enum: ['live', 'ready'] },
+            },
+        }), route(async (req) => {
             const timestamp = new Date().toISOString();
             try {
                 if (stopping) {
                     throw new Error();
                 }
-                const meta = await options.healthCheck?.();
-                return { status: 'ok', meta, timestamp };
+                const type = req.query.type;
+                const meta = await options.healthCheck?.(type);
+                return { status: 'ok', type, meta, timestamp };
             }
-            catch {
+            catch (error) {
+                logger.error(error, 'Failed health check');
                 return [503, { status: 'error', timestamp }];
             }
         }));

package/dist/manage.js

@@ -1,9 +1,9 @@
 import { program } from 'commander';
 import {} from 'express';
-import { parseExpressApp } from 'express-route-parser';
 import { hashPassword } from './auth.js';
 import { CLI } from './cli.js';
 import { asCli } from './migrate.js';
+import { parseRoutes } from './routes.js';
 export function registerManagementCommand(register) {
     const cli = new CLI({ printStackTraces: process.argv.includes('--verbose') });
     register(program.command.bind(program), cli);
@@ -17,12 +17,23 @@ export function registerDefaultCommands(app) {
         const migrate = command('migrate');
         asCli(migrate, cli);
     });
-    registerManagementCommand((command, cli) => command('routes').action(cli.wrap(async () => {
+    registerManagementCommand((command, cli) => command('routes')
+        .option('--openapi', 'Output OpenAPI schema')
+        .option('--json', 'Output JSON')
+        .action(cli.wrap(async (options) => {
         if (!app)
             return;
-        const routes = parseExpressApp(app);
+        if (options.openapi) {
+            console.error('Not implemented yet');
+            return;
+        }
+        const routes = parseRoutes(app);
+        if (options.json) {
+            console.log(JSON.stringify(routes, null, 2));
+            return;
+        }
         for (const route of routes) {
-            cli.writeLine(`${route.method.toLocaleUpperCase().padEnd(5)} ${route.path}\n`);
+            cli.writeLine(`${route.method.padEnd(7)} ${route.path}\n`);
         }
     })));
     registerManagementCommand((command, cli) => {

package/dist/redis.js

@@ -2,8 +2,10 @@ import { createClient } from 'redis';
 import { readEnv } from './utils.js';
 export function createRedis({ url = readEnv('REDIS_URL', ''), onError, } = {}) {
     const client = createClient({ url });
-    if (onError) {
-        client.on('error', onError);
-    }
+    // Always attach a listener even if
+    // onError is not provided.
+    client.on('error', (error) => {
+        onError?.(error);
+    });
     return client;
 }

package/dist/routes.d.ts

@@ -1,2 +1,22 @@
 import { type Express, type RequestHandler } from 'express';
 export declare function createDocsRouter(app: Express, extras?: Record<string, any>): RequestHandler;
+export declare function parseRoutes(app: Express): {
+    method: string;
+    path: string;
+    params: {
+        type: string;
+        properties: {
+            [k: string]: {
+                type: string;
+            };
+        };
+        required: string[];
+    } | null;
+    query: {} | null;
+    body: {} | null;
+}[];
+export interface Key {
+    name: string;
+    optional: boolean;
+    offset: number;
+}

package/dist/routes.js

@@ -1,11 +1,168 @@
 import {} from 'express';
-import { parseExpressApp } from 'express-route-parser';
 import { route } from './middleware.js';
 export function createDocsRouter(app, extras = {}) {
     return route(async () => {
         return {
             ...extras,
-            routes: parseExpressApp(app),
+            routes: parseRoutes(app),
         };
     });
 }
+export function parseRoutes(app) {
+    return new ExpressPathParser(app).getPaths().map((routeMetadata) => {
+        const { method, path, pathParams, metadata } = routeMetadata;
+        return {
+            method: method.toLocaleUpperCase(),
+            path,
+            params: buildPathParamsSchema(pathParams),
+            query: metadata
+                ?.filter((m) => typeof m === 'object' && m != null && 'querySchema' in m)
+                .at(-1)?.querySchema ?? null,
+            body: metadata
+                ?.filter((m) => typeof m === 'object' && m != null && 'bodySchema' in m)
+                .at(-1)?.bodySchema ?? null,
+        };
+    });
+}
+const buildPathParamsSchema = (pathParams) => {
+    const required = [];
+    const params = [];
+    for (const param of pathParams) {
+        if (param.in !== 'path') {
+            continue;
+        }
+        params.push(param.name);
+        if (param.required) {
+            required.push(param.name);
+        }
+    }
+    if (params.length === 0) {
+        return null;
+    }
+    return {
+        type: 'object',
+        properties: Object.fromEntries(params.map((p) => [p, { type: 'string' }])),
+        required,
+    };
+};
+class ExpressPathParser {
+    getPaths() {
+        return this._appPaths;
+    }
+    constructor(app) {
+        /**
+         * Recursive traversal method for the express router and middleware tree.
+         *
+         * @param path The current path segment that we have traversed so far
+         * @param layer The current 'layer' of the router tree
+         * @param keys The keys for the parameter's in the current path branch of the traversal
+         * @returns void - base case saves result to internal object
+         */
+        this.traverse = (path, layer, keys) => {
+            keys = [...keys, ...layer.keys];
+            if (layer.name === 'router' && layer.handle) {
+                layer.handle.stack.forEach((l) => {
+                    path = path || '';
+                    this.traverse(`${path}/${pathRegexParser(layer.regexp, layer.keys)}`, l, keys);
+                });
+            }
+            if (!layer.route || !layer.route.stack.length) {
+                return;
+            }
+            this._appPaths.push(this.parseRouteLayer(layer, keys, path));
+        };
+        /**
+         * Parses a route object. Route objects are the leafs of an express router tree
+         *
+         * @param layer The layer of this route object - represents the stack of middleware and other meta data
+         * @param keys The full set of keys for this particular route
+         * @param basePath The base path as it was initial declared for this route
+         * @returns A ExpressPath object holding the meta data for a given route
+         */
+        this.parseRouteLayer = (layer, keys, basePath) => {
+            const lastRequestHandler = layer.route.stack[layer.route.stack.length - 1];
+            const pathParams = keys.map((key) => {
+                return { name: key.name, in: 'path', required: !key.optional };
+            });
+            const filtered = layer.route.stack.filter((element) => element?.handle?.metadata);
+            const path = (basePath + layer.route.path).replace(/\/{2,}/gi, '/');
+            if (filtered.length === 0) {
+                return { path, pathParams, method: lastRequestHandler.method };
+            }
+            return {
+                path,
+                pathParams,
+                method: lastRequestHandler.method,
+                metadata: filtered.map((f) => f.handle.metadata),
+            };
+        };
+        this._appPaths = [];
+        const router = app._router;
+        if (router) {
+            for (const layer of router.stack) {
+                this.traverse('', layer, []);
+            }
+        }
+    }
+}
+/** Parses an express layer's regex and converts it to the original format seen in code.
+ *
+ * @param layerRegexPath The layer's regex pattern
+ * @param keys The keys that represent the layer's path parameters
+ * @returns The path string for that layer
+ * Code inspired and modify from:
+ * https://github.com/expressjs/express/issues/3308#issuecomment-300957572
+ */
+const pathRegexParser = (layerRegexPath, keys) => {
+    if (typeof layerRegexPath === 'string') {
+        return layerRegexPath;
+    }
+    if (layerRegexPath.fast_slash) {
+        return '';
+    }
+    if (layerRegexPath.fast_star) {
+        return '*';
+    }
+    let mappedPath = '';
+    if (keys && keys.length) {
+        mappedPath = mapKeysToPath(layerRegexPath, keys);
+    }
+    const match = layerRegexPath
+        .toString()
+        .replace('\\/?', '')
+        .replace('(?=\\/|$)', '$')
+        .match(/^\/\^((?:\\[.*+?^${}()|[\]\\/]|[^.*+?^${}()|[\]\\/])*)\$\//);
+    if (match) {
+        return match[1].replace(/\\(.)/g, '$1').slice(1);
+    }
+    if (mappedPath) {
+        return mappedPath.slice(1);
+    }
+    return layerRegexPath.toString();
+};
+/**
+ * Map's the keys/path variables to the regex inside a given path
+ *
+ * @param layerRegexPath The regex for a react router with path parameters
+ * @param keys The keys that represent the path parameters
+ * @returns The regex for a path variable converted to original string on the express route
+ */
+const mapKeysToPath = (layerRegexPath, keys) => {
+    if (!keys || keys.length === 0) {
+        throw Error('must include atleast one key to map');
+    }
+    let convertedSubPath = layerRegexPath.toString();
+    for (const key of keys) {
+        if (key.optional) {
+            convertedSubPath = convertedSubPath.replace('(?:\\/([^\\/]+?))?\\', `/:${key.name}?`);
+        }
+        else {
+            convertedSubPath = convertedSubPath.replace('(?:([^\\/]+?))', `:${key.name}`);
+        }
+    }
+    return convertedSubPath
+        .replace('/?(?=\\/|$)/i', '')
+        .replace('/^', '')
+        .replace(/\\/gi, '')
+        .replace(/\/{2,}/gi, '/');
+};

package/dist/setupTests.js

@@ -1,3 +1,5 @@
 import 'dotenv/config';
+import EventEmitter from 'node:events';
 import failOnConsole from 'vitest-fail-on-console';
+EventEmitter.setMaxListeners(20);
 failOnConsole();

package/dist/validate.js

@@ -4,33 +4,39 @@ import { BadRequest } from './errors.js';
 const Ajv = _Ajv;
 export function validateBody(schema) {
     const validate = compileValidateSchema(schema);
-    return (req, res, next) => {
+    const middleware = (req, res, next) => {
         const result = validate(req.body);
         if (!result.isValid) {
             return next(BadRequest({ body: result.errors }));
         }
         next();
     };
+    middleware.metadata = { bodySchema: schema };
+    return middleware;
 }
 export function validateQuery(schema) {
     const validate = compileValidateSchema(schema, { coerceTypes: true });
-    return (req, res, next) => {
+    const middleware = (req, res, next) => {
         const result = validate(req.query);
         if (!result.isValid) {
             return next(BadRequest({ query: result.errors }));
         }
         next();
     };
+    middleware.metadata = { querySchema: schema };
+    return middleware;
 }
 export function validateParams(schema) {
     const validate = compileValidateSchema(schema, { coerceTypes: true });
-    return (req, res, next) => {
+    const middleware = (req, res, next) => {
         const result = validate(req.params);
         if (!result.isValid) {
             return next(BadRequest({ params: result.errors }));
         }
         next();
     };
+    middleware.metadata = { paramsSchema: schema };
+    return middleware;
 }
 function createAjv(options) {
     const ajv = new Ajv({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devmoods/express-extras",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "description": "Kubernetes-ready utilities for rapid Node.js application development",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,11 +20,11 @@
   "devDependencies": {
     "@devmoods/eslint-config": "^1.14.0",
     "@types/koa-compose": "^3.2.8",
-    "@types/node": "22.7.5",
+    "@types/node": "22.8.1",
     "@types/supertest": "^6.0.2",
-    "@typescript-eslint/eslint-plugin": "^8.8.1",
-    "@typescript-eslint/parser": "^8.8.1",
-    "@vitest/coverage-v8": "^2.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.11.0",
+    "@typescript-eslint/parser": "^8.11.0",
+    "@vitest/coverage-v8": "^2.1.3",
     "chalk": "^5.3.0",
     "eslint": "^8.57.0",
     "eslint-plugin-import": "^2.31.0",
@@ -35,13 +35,13 @@
     "ts-node": "10.9.2",
     "tsx": "^4.19.1",
     "typescript": "5.6.3",
-    "vitest": "^2.1.2",
+    "vitest": "^2.1.3",
     "vitest-fail-on-console": "^0.7.1"
   },
   "dependencies": {
     "@devmoods/fetch": "^4.0.1",
-    "@sentry/node": "^8.34.0",
-    "@sentry/profiling-node": "^8.34.0",
+    "@sentry/node": "^8.35.0",
+    "@sentry/profiling-node": "^8.35.0",
     "@types/bcrypt": "^5.0.2",
     "@types/body-parser": "^1.19.5",
     "@types/cookie-parser": "^1.4.7",
@@ -59,11 +59,10 @@
     "cookie-parser": "^1.4.7",
     "dotenv": "^16.4.5",
     "express": "^4.21.1",
-    "express-route-parser": "^1.0.5",
     "helmet": "^8.0.0",
     "jsonwebtoken": "^9.0.2",
     "nodemailer": "^6.9.15",
-    "pg": "^8.13.0",
+    "pg": "^8.13.1",
     "redis": "^4.7.0",
     "sql-template-strings": "^2.2.2",
     "uuid": "^10.0.0"