@devmoods/express-extras 0.76.0 → 0.77.0

package/dist/redis-jobs.js

@@ -0,0 +1,185 @@
+import { config } from '@devmoods/config';
+import { startTimer } from '@devmoods/observability';
+import { JOB_ID_CONTEXT_KEY, requestContext, setRequestContext, } from './context.js';
+import {} from './jobs.js';
+import { getLogger } from './logger.js';
+import {} from './redis.js';
+const logger = getLogger('redis-jobs');
+const pollMs = 100;
+// One atomic claim moves due or abandoned jobs to the ready set, then reserves
+// the highest priority job. A worker renews its reservation while it runs.
+const claimScript = `
+for _, source in ipairs({KEYS[2], KEYS[3]}) do
+  local due = redis.call('ZRANGEBYSCORE', source, '-inf', ARGV[1], 'LIMIT', 0, 100)
+  for _, job in ipairs(due) do
+    if redis.call('ZREM', source, job) == 1 then
+      redis.call('ZADD', KEYS[1], cjson.decode(job).priority or 0, job)
+    end
+  end
+end
+local claimed = redis.call('ZPOPMAX', KEYS[1], 1)
+if #claimed == 0 then return nil end
+redis.call('ZADD', KEYS[3], ARGV[2], claimed[1])
+return claimed[1]
+`;
+const finishScript = `
+if redis.call('ZREM', KEYS[1], ARGV[1]) == 1 and ARGV[2] ~= '' then
+  redis.call('ZADD', KEYS[2], ARGV[3], ARGV[2])
+end
+`;
+/** Persistent, at least once job processing using Redis sorted sets. */
+export class RedisJobBackend {
+    redis;
+    options;
+    constructor(redis, options = {}) {
+        this.redis = redis;
+        this.options = options;
+    }
+    key(queue, state) {
+        return `${this.options.keyPrefix ?? `${config.REDIS_KEY_PREFIX}jobs:`}${queue}:${state}`;
+    }
+    get leaseMs() {
+        return this.options.leaseMs ?? 30_000;
+    }
+    async enqueue(job) {
+        const at = job.at == null ? Date.now() : new Date(job.at).getTime();
+        if (!Number.isFinite(at)) {
+            throw new RangeError('Invalid job schedule');
+        }
+        if (job.priority != null && !Number.isFinite(job.priority)) {
+            throw new RangeError('Invalid job priority');
+        }
+        if (job.retry != null && (!Number.isInteger(job.retry) || job.retry < 0)) {
+            throw new RangeError('Invalid job retry count');
+        }
+        const payload = JSON.stringify({ ...job, attempt: 0 });
+        const scheduled = at > Date.now();
+        await this.redis.zAdd(this.key(job.queue, scheduled ? 'scheduled' : 'ready'), {
+            score: scheduled ? at : (job.priority ?? 0),
+            value: payload,
+        });
+    }
+    async claim(queue) {
+        const now = Date.now();
+        const value = await this.redis.eval(claimScript, {
+            keys: [
+                this.key(queue, 'ready'),
+                this.key(queue, 'scheduled'),
+                this.key(queue, 'processing'),
+            ],
+            arguments: [String(now), String(now + this.leaseMs)],
+        });
+        return value == null ? null : JSON.parse(String(value));
+    }
+    async finish(job, next, failed = false) {
+        const nextValue = next ? JSON.stringify(next) : '';
+        const score = next
+            ? failed
+                ? Date.now()
+                : Date.now() + Math.min(60_000, 1000 * 2 ** (next.attempt - 1))
+            : 0;
+        await this.redis.eval(finishScript, {
+            keys: [
+                this.key(job.queue, 'processing'),
+                this.key(job.queue, failed ? 'failed' : 'scheduled'),
+            ],
+            arguments: [JSON.stringify(job), nextValue, String(score)],
+        });
+    }
+    createWorker({ jobs, queues, jobContext, }) {
+        const claim = (queue) => this.claim(queue);
+        const availableJobs = new Map(jobs
+            .filter((job) => !!job && Object.prototype.hasOwnProperty.call(job, '$job'))
+            .map((job) => [job.jobName, job]));
+        let running = false;
+        let loop;
+        let wake;
+        let queueIndex = 0;
+        const wait = () => new Promise((resolve) => {
+            const timer = setTimeout(resolve, pollMs);
+            wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+        const processJob = async (job) => {
+            const registered = availableJobs.get(job.jobName);
+            const timer = startTimer();
+            const heartbeat = setInterval(() => {
+                void this.redis
+                    .zAdd(this.key(job.queue, 'processing'), {
+                    score: Date.now() + this.leaseMs,
+                    value: JSON.stringify(job),
+                }, { XX: true })
+                    .catch((error) => logger.error(error));
+            }, this.leaseMs / 3);
+            try {
+                if (!registered) {
+                    throw new Error(`Unknown job: ${job.jobName}`);
+                }
+                logger.info('job started', { jobName: job.jobName, jobId: job.jid });
+                await requestContext.run(new Map(), async () => {
+                    setRequestContext(JOB_ID_CONTEXT_KEY, job.jid);
+                    await registered.execute(job.args, jobContext ?? {});
+                });
+                await this.finish(job);
+                logger.info('job succeeded', {
+                    jobName: job.jobName,
+                    jobId: job.jid,
+                    duration: timer.getDuration(),
+                });
+            }
+            catch (error) {
+                logger.error(error, 'job failed', {
+                    jobName: job.jobName,
+                    jobId: job.jid,
+                });
+                const next = { ...job, attempt: job.attempt + 1 };
+                const failed = next.attempt > (job.retry ?? 25) || !registered;
+                await this.finish(job, next, failed);
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+        };
+        return {
+            async start() {
+                if (running) {
+                    return;
+                }
+                running = true;
+                logger.info('redis job worker started', { queues });
+                loop = (async () => {
+                    while (running) {
+                        try {
+                            let found = false;
+                            for (let i = 0; i < queues.length && running; i++) {
+                                const queue = queues[queueIndex++ % queues.length];
+                                const job = await claim(queue);
+                                if (job) {
+                                    found = true;
+                                    await processJob(job);
+                                    break;
+                                }
+                            }
+                            if (!found && running) {
+                                await wait();
+                            }
+                        }
+                        catch (error) {
+                            logger.error(error, 'redis job worker error');
+                            if (running) {
+                                await wait();
+                            }
+                        }
+                    }
+                })();
+            },
+            async stop() {
+                running = false;
+                wake?.();
+                await loop;
+            },
+        };
+    }
+}

package/dist/routes.js

@@ -180,6 +180,41 @@ export function convertPathToOperationId(method, path) {
     const camelizedPath = segments.join('');
     return `${method.toLowerCase()}${camelizedPath}`;
 }
+const expressPathParameterPattern = /([/.])?:([A-Za-z0-9_]+)(?:\((?:\\.|[^)])*\))?(\?)?/g;
+const expandOpenAPIPaths = (path) => {
+    let variants = [
+        { path: '', parameterNames: new Set() },
+    ];
+    let previousIndex = 0;
+    for (const match of path.matchAll(expressPathParameterPattern)) {
+        const [token, prefix = '', name, optional] = match;
+        const literal = path.slice(previousIndex, match.index);
+        variants = variants.flatMap((variant) => {
+            const basePath = variant.path + literal;
+            if (optional) {
+                return [
+                    { path: basePath, parameterNames: new Set(variant.parameterNames) },
+                    {
+                        path: `${basePath}${prefix}{${name}}`,
+                        parameterNames: new Set([...variant.parameterNames, name]),
+                    },
+                ];
+            }
+            return [
+                {
+                    path: `${basePath}${prefix}{${name}}`,
+                    parameterNames: new Set([...variant.parameterNames, name]),
+                },
+            ];
+        });
+        previousIndex = match.index + token.length;
+    }
+    const suffix = path.slice(previousIndex);
+    return variants.map((variant) => ({
+        ...variant,
+        path: variant.path + suffix,
+    }));
+};
 export function toOpenAPISpec(app, info = {
     title: 'API Documentation',
     version: '1.0.0',
@@ -196,31 +231,15 @@ export function toOpenAPISpec(app, info = {
         for (const tag of tags) {
             allTags.add(tag);
         }
-        // Convert Express path params to OpenAPI path params
-        const openApiPath = path.replace(/:([^/]+)/g, '{$1}');
-        /* v8 ignore next -- @preserve */
-        if (!paths[openApiPath]) {
-            paths[openApiPath] = {};
-        }
-        const parameters = [];
-        // Add path parameters
-        if (params) {
-            parameters.push(...Object.keys(params.properties).map((name) => ({
-                name,
-                in: 'path',
-                /* v8 ignore start -- @preserve */
-                required: params.required?.includes(name) ?? true,
-                schema: params.properties[name],
-                /* v8 ignore end -- @preserve */
-            })));
-        }
+        const pathVariants = expandOpenAPIPaths(path);
+        const queryParameters = [];
         // Add query parameters
         if (query && typeof query === 'object' && 'properties' in query) {
             const querySchema = query;
             /* v8 ignore next -- @preserve */
             const properties = querySchema.properties || {};
             /* v8 ignore next -- @preserve */
-            parameters.push(...Object.keys(properties).map((name) => ({
+            queryParameters.push(...Object.keys(properties).map((name) => ({
                 name,
                 in: 'query',
                 required: Array.isArray(querySchema.required) &&
@@ -228,59 +247,75 @@ export function toOpenAPISpec(app, info = {
                 schema: properties[name],
             })));
         }
-        paths[openApiPath][method.toLowerCase()] = {
-            operationId: convertPathToOperationId(method, path), // Use original path, not openApiPath
-            tags,
-            parameters,
-            ...(body && {
-                requestBody: {
-                    content: {
-                        'application/json': {
-                            schema: body,
+        for (const pathVariant of pathVariants) {
+            /* v8 ignore next -- @preserve */
+            if (!paths[pathVariant.path]) {
+                paths[pathVariant.path] = {};
+            }
+            const pathParameters = params
+                ? Object.keys(params.properties)
+                    .filter((name) => pathVariant.parameterNames.has(name))
+                    .map((name) => ({
+                    name,
+                    in: 'path',
+                    required: true,
+                    schema: params.properties[name],
+                }))
+                : [];
+            paths[pathVariant.path][method.toLowerCase()] = {
+                operationId: convertPathToOperationId(method, pathVariant.path),
+                tags,
+                parameters: [...pathParameters, ...queryParameters],
+                ...(body && {
+                    requestBody: {
+                        content: {
+                            'application/json': {
+                                schema: body,
+                            },
                         },
                     },
-                },
-            }),
-            responses: {
-                ...(() => {
-                    const code = String(successStatus ?? 200);
-                    if (response) {
+                }),
+                responses: {
+                    ...(() => {
+                        const code = String(successStatus ?? 200);
+                        if (response) {
+                            return {
+                                [code]: {
+                                    description: 'Successful response',
+                                    content: {
+                                        'application/json': {
+                                            schema: response,
+                                        },
+                                    },
+                                },
+                            };
+                        }
                         return {
                             [code]: {
                                 description: 'Successful response',
-                                content: {
-                                    'application/json': {
-                                        schema: response,
-                                    },
-                                },
                             },
                         };
-                    }
-                    return {
-                        [code]: {
-                            description: 'Successful response',
-                        },
-                    };
-                })(),
-                '400': {
-                    description: 'Bad Request',
-                    content: {
-                        'application/json': {
-                            schema: {
-                                type: 'object',
-                                properties: {
-                                    type: { type: 'string' },
-                                    title: { type: 'string' },
-                                    detail: { type: 'string' },
-                                    status: { type: 'number' },
+                    })(),
+                    '400': {
+                        description: 'Bad Request',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        type: { type: 'string' },
+                                        title: { type: 'string' },
+                                        detail: { type: 'string' },
+                                        status: { type: 'number' },
+                                    },
+                                    required: ['type', 'title', 'status'],
                                 },
-                                required: ['type', 'title', 'status'],
                             },
                         },
                     },
                 },
-            },
-        };
+            };
+        }
     }
     return {
         openapi: '3.1.0',

package/dist/streams.js

@@ -3,7 +3,7 @@ export function writeChunk(writable, chunk, state) {
     // If we're already draining, just enqueue.
     if (state.draining) {
         if (state.queue.length >= state.maxQueue) {
-            // Drop the oldest chunk to keep memory bounded.
+            // Queue entries are atomic: callers should enqueue complete protocol units.
             state.queue.shift();
         }
         state.queue.push(chunk);

package/dist/validate.js

@@ -25,15 +25,15 @@ export async function validateSchema(data, schema) {
         await standardValidate(schema, data);
     }
     catch (error) {
+        if (!(error instanceof ValidationError)) {
+            throw error;
+        }
         return {
             isValid: false,
             /* v8 ignore start -- @preserve */
-            errors: (error instanceof ValidationError
-                ? error.issues.map((issue) => [
-                    String(issue.path ?? '/'),
-                    issue.message,
-                ])
-                : []).reduce((result, item) => {
+            errors: error.issues
+                .map((issue) => [String(issue.path ?? '/'), issue.message])
+                .reduce((result, item) => {
                 const [key, value] = item;
                 if (Array.isArray(result[key])) {
                     result[key].push(value);

package/dist/vite/defineViteConfig.d.ts

@@ -1,7 +1,6 @@
 import { type UserConfig } from 'vite';
 export declare function defineViteConfig({ base, ssr, analyze, }: {
     base?: string;
-    reactCompiler?: boolean;
     ssr?: boolean;
     analyze?: boolean;
 }): UserConfig;

package/dist/vite/ssr.d.ts

@@ -1,3 +1,4 @@
+import { type Server } from 'node:http';
 import { type RequestHandler } from 'express';
 export interface SsrMiddlewareOptions<InitialData = unknown> {
     /**
@@ -14,6 +15,21 @@ export interface SsrMiddlewareOptions<InitialData = unknown> {
      * Uses `config.VITE_USE_DEV_SERVER` if not provided.
      */
     useDevServer?: boolean;
+    /**
+     * The app's HTTP server. When given, the dev server runs HMR on it instead
+     * of on a separate port, so HMR works behind a proxy (e.g. over https) and
+     * several dev servers can run side by side.
+     */
+    server?: Server;
+    /**
+     * Whether the dev server should serve a browser: run HMR and pre-bundle
+     * client dependencies.
+     *
+     * Defaults to `false` under Vitest, where several test workers each start a
+     * dev server and would otherwise fight over the HMR port and race on the
+     * dependency cache.
+     */
+    hmr?: boolean;
 }
 export interface SsrMiddleware extends RequestHandler {
 }
@@ -22,5 +38,5 @@ export interface SsrMiddleware extends RequestHandler {
  *
  * See more: https://vite.dev/guide/ssr
  */
-export declare function createSsrMiddleware<InitialData = unknown>({ root, getInitialData, useDevServer, }?: SsrMiddlewareOptions<InitialData>): Promise<SsrMiddleware>;
+export declare function createSsrMiddleware<InitialData = unknown>({ root, getInitialData, useDevServer, server, hmr, }?: SsrMiddlewareOptions<InitialData>): Promise<SsrMiddleware>;
 export declare function replaceSsrPlaceholders(template: string, values: Record<string, unknown>): string;

package/dist/vite/ssr.js

@@ -7,6 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import * as fs from 'node:fs/promises';
+import {} from 'node:http';
 import * as path from 'node:path';
 import { config } from '@devmoods/config';
 import express, {} from 'express';
@@ -21,7 +22,7 @@ import { createFetchRequest } from '../webapi.js';
  *
  * See more: https://vite.dev/guide/ssr
  */
-export async function createSsrMiddleware({ root = process.cwd(), getInitialData, useDevServer = config.VITE_USE_DEV_SERVER, } = {}) {
+export async function createSsrMiddleware({ root = process.cwd(), getInitialData, useDevServer = config.VITE_USE_DEV_SERVER, server, hmr = !process.env.VITEST, } = {}) {
     const resolve = (p) => path.resolve(root, p);
     let vite;
     let assetLinks = { preload: '', css: '', js: '' };
@@ -29,7 +30,13 @@ export async function createSsrMiddleware({ root = process.cwd(), getInitialData
     if (useDevServer) {
         vite = await import('vite').then((mod) => mod.createServer({
             root,
-            server: { middlewareMode: true },
+            server: {
+                middlewareMode: true,
+                ...(hmr
+                    ? websocketServerOptions(mod.version, server)
+                    : { hmr: false, ws: false }),
+            },
+            ...(!hmr && { optimizeDeps: { noDiscovery: true } }),
             appType: 'custom',
         }));
         middlewares.push(vite.middlewares);
@@ -103,6 +110,18 @@ export async function createSsrMiddleware({ root = process.cwd(), getInitialData
     }));
     return composeMiddleware(middlewares);
 }
+/**
+ * Runs the HMR websocket on the given server. Vite 8 moved the option from
+ * `server.hmr.server` to `server.ws.server`.
+ */
+function websocketServerOptions(viteVersion, server) {
+    if (!server) {
+        return {};
+    }
+    return Number.parseInt(viteVersion, 10) >= 8
+        ? { ws: { server } }
+        : { hmr: { server } };
+}
 export function replaceSsrPlaceholders(template, values) {
     return template.replace(/\{\{\s*([\w-]+)\s*\}\}/g, (match, variableName) => {
         if (Object.prototype.hasOwnProperty.call(values, variableName)) {

package/dist/vitest/matchers.d.ts

@@ -1,15 +1,26 @@
 import { type ExpectStatic } from 'vitest';
-import failOnConsole from 'vitest-fail-on-console';
 interface CustomMatchers<R = unknown> {
     toMatchResponse: (statusCode: number, body?: unknown) => R;
 }
 declare module 'vitest' {
-    interface Matchers<T = any> extends CustomMatchers<T> {
-    }
-    interface Assertion<T = any> extends CustomMatchers<T> {
+    interface Matchers<R extends void | Promise<void> = void | Promise<void>, T = unknown> extends CustomMatchers<R> {
     }
     interface AsymmetricMatchersContaining extends CustomMatchers {
     }
 }
-export { failOnConsole };
+type ConsoleMethod = 'assert' | 'debug' | 'error' | 'info' | 'log' | 'warn';
+interface FailOnConsoleOptions {
+    shouldFailOnAssert?: boolean;
+    shouldFailOnDebug?: boolean;
+    shouldFailOnError?: boolean;
+    shouldFailOnInfo?: boolean;
+    shouldFailOnLog?: boolean;
+    shouldFailOnWarn?: boolean;
+    allowMessage?: (message: string, method: ConsoleMethod) => boolean;
+    silenceMessage?: (message: string, method: ConsoleMethod) => boolean;
+    shouldPrintMessage?: boolean;
+    afterEachDelay?: number;
+}
+export declare function failOnConsole(options?: FailOnConsoleOptions): void;
 export declare function extendMatchers(expect: ExpectStatic): void;
+export {};

package/dist/vitest/matchers.js

@@ -1,6 +1,69 @@
-import {} from 'vitest';
-import failOnConsole from 'vitest-fail-on-console';
-export { failOnConsole };
+import { format } from 'node:util';
+import { afterEach, beforeEach } from 'vitest';
+const defaultFailOnConsoleOptions = {
+    shouldFailOnAssert: false,
+    shouldFailOnDebug: false,
+    shouldFailOnError: true,
+    shouldFailOnInfo: false,
+    shouldFailOnLog: false,
+    shouldFailOnWarn: true,
+};
+const consoleMethodOptions = [
+    ['assert', 'shouldFailOnAssert'],
+    ['debug', 'shouldFailOnDebug'],
+    ['error', 'shouldFailOnError'],
+    ['info', 'shouldFailOnInfo'],
+    ['log', 'shouldFailOnLog'],
+    ['warn', 'shouldFailOnWarn'],
+];
+export function failOnConsole(options = {}) {
+    const resolvedOptions = { ...defaultFailOnConsoleOptions, ...options };
+    for (const [method, optionName] of consoleMethodOptions) {
+        if (!resolvedOptions[optionName]) {
+            continue;
+        }
+        const calls = [];
+        const consoleMethods = console;
+        const original = consoleMethods[method];
+        beforeEach(() => {
+            calls.length = 0;
+            consoleMethods[method] = (...args) => {
+                /* v8 ignore next 3 -- covered by console.assert itself */
+                if (method === 'assert' && args[0]) {
+                    return;
+                }
+                /* v8 ignore next -- covered by console.assert itself */
+                const messageArgs = method === 'assert' ? args.slice(1) : args;
+                /* v8 ignore next -- console.assert with no message */
+                const message = messageArgs.length > 0 ? format(...messageArgs) : 'Assertion failed';
+                /* v8 ignore next 3 -- optional diagnostic passthrough */
+                if (resolvedOptions.silenceMessage?.(message, method)) {
+                    return;
+                }
+                /* v8 ignore next 4 -- optional diagnostic passthrough */
+                if (resolvedOptions.allowMessage?.(message, method)) {
+                    original(...args);
+                    return;
+                }
+                /* v8 ignore next 3 -- optional diagnostic passthrough */
+                if (resolvedOptions.shouldPrintMessage) {
+                    original(...args);
+                }
+                calls.push(message);
+            };
+        });
+        afterEach(async () => {
+            /* v8 ignore next 5 -- optional async console flush delay */
+            if (resolvedOptions.afterEachDelay) {
+                await new Promise((resolve) => setTimeout(resolve, resolvedOptions.afterEachDelay));
+            }
+            consoleMethods[method] = original;
+            if (calls.length > 0) {
+                throw new Error(`Expected test not to call console.${method}().\n\n${calls.join('\n\n')}`);
+            }
+        });
+    }
+}
 /* v8 ignore next -- @preserve */
 export function extendMatchers(expect) {
     expect.extend({

package/dist/vitest/testClient.js

@@ -75,10 +75,22 @@ export async function createTestClient(server, options) {
         });
     };
     delete_.intercept = fetch.intercept;
-    const close = async () => {
-        if (started) {
-            server.close();
+    let closePromise;
+    const close = () => {
+        if (!started) {
+            return Promise.resolve();
         }
+        closePromise ??= new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+        return closePromise;
     };
     return {
         duplicate() {