@veloxts/router 0.6.87 → 0.6.88

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/router
 
+## 0.6.88
+
+### Patch Changes
+
+- add ecosystem presets for environment-aware configuration
+- Updated dependencies
+  - @veloxts/core@0.6.88
+  - @veloxts/validation@0.6.88
+
 ## 0.6.87
 
 ### Patch Changes

package/dist/middleware/chain.d.ts

@@ -20,9 +20,33 @@ export interface MiddlewareResult<TOutput> {
  * Builds the chain from end to start and executes it, allowing each
  * middleware to extend the context before calling the next middleware.
  *
+ * ## Implementation Notes: Closure Capture Pattern
+ *
+ * This function uses a deliberate closure capture pattern in the loop:
+ *
+ * ```typescript
+ * for (let i = middlewares.length - 1; i >= 0; i--) {
+ *   const middleware = middlewares[i];  // Captured in closure
+ *   const currentNext = next;           // Captured in closure
+ *   next = async () => { ... };         // Creates new closure
+ * }
+ * ```
+ *
+ * **Why closures in a loop?**
+ * Each iteration creates a new closure that captures:
+ * 1. `middleware` - The specific middleware function for that position
+ * 2. `currentNext` - The accumulated chain from previous iterations
+ *
+ * This builds the chain backwards (handler → last middleware → ... → first middleware)
+ * so that when executed, it runs forwards (first middleware → ... → handler).
+ *
+ * **Why not use Array.reduceRight?**
+ * The closure pattern is more explicit and easier to debug. Each closure
+ * captures exactly what it needs, and the chain structure is visible.
+ *
  * @param middlewares - Array of middleware functions to execute
  * @param input - The input to pass to each middleware
- * @param ctx - The context object (will be mutated by middleware)
+ * @param ctx - The context object (will be mutated by middleware via Object.assign)
  * @param handler - The final handler to execute after all middleware
  * @returns The output from the handler
  *

package/dist/middleware/chain.js

@@ -12,9 +12,33 @@
  * Builds the chain from end to start and executes it, allowing each
  * middleware to extend the context before calling the next middleware.
  *
+ * ## Implementation Notes: Closure Capture Pattern
+ *
+ * This function uses a deliberate closure capture pattern in the loop:
+ *
+ * ```typescript
+ * for (let i = middlewares.length - 1; i >= 0; i--) {
+ *   const middleware = middlewares[i];  // Captured in closure
+ *   const currentNext = next;           // Captured in closure
+ *   next = async () => { ... };         // Creates new closure
+ * }
+ * ```
+ *
+ * **Why closures in a loop?**
+ * Each iteration creates a new closure that captures:
+ * 1. `middleware` - The specific middleware function for that position
+ * 2. `currentNext` - The accumulated chain from previous iterations
+ *
+ * This builds the chain backwards (handler → last middleware → ... → first middleware)
+ * so that when executed, it runs forwards (first middleware → ... → handler).
+ *
+ * **Why not use Array.reduceRight?**
+ * The closure pattern is more explicit and easier to debug. Each closure
+ * captures exactly what it needs, and the chain structure is visible.
+ *
  * @param middlewares - Array of middleware functions to execute
  * @param input - The input to pass to each middleware
- * @param ctx - The context object (will be mutated by middleware)
+ * @param ctx - The context object (will be mutated by middleware via Object.assign)
  * @param handler - The final handler to execute after all middleware
  * @returns The output from the handler
  *
@@ -30,20 +54,26 @@
  */
 export async function executeMiddlewareChain(middlewares, input, ctx, handler) {
     // Build the chain from the end (handler) back to the start
+    // Start with the handler wrapped in a MiddlewareResult
     let next = async () => {
         const output = await handler();
         return { output };
     };
     // Wrap each middleware from last to first
+    // Each iteration captures `middleware` and `currentNext` in a new closure
+    // This builds: handler <- MW[n] <- MW[n-1] <- ... <- MW[0]
+    // So execution flows: MW[0] -> MW[1] -> ... -> MW[n] -> handler
     for (let i = middlewares.length - 1; i >= 0; i--) {
         const middleware = middlewares[i];
-        const currentNext = next;
+        const currentNext = next; // Capture the accumulated chain so far
+        // Create a new closure that wraps the middleware with the chain
         next = async () => {
             return middleware({
                 input,
                 ctx,
                 next: async (opts) => {
-                    // Allow middleware to extend context
+                    // Allow middleware to extend context via Object.assign
+                    // This mutates ctx in place, which is intentional
                     if (opts?.ctx) {
                         Object.assign(ctx, opts.ctx);
                     }

package/dist/procedure/builder.js

@@ -10,72 +10,9 @@
 import { ConfigurationError, logWarning } from '@veloxts/core';
 import { GuardError } from '../errors.js';
 import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
+import { deriveParentParamName } from '../utils/pluralization.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
 // ============================================================================
-// Utility Functions
-// ============================================================================
-/**
- * Derives the default parent parameter name from a namespace
- *
- * Converts a plural namespace to a singular form and appends 'Id'.
- * Uses simple heuristics for common English pluralization patterns.
- *
- * @param namespace - The parent resource namespace (e.g., 'posts', 'users')
- * @returns The parameter name (e.g., 'postId', 'userId')
- *
- * @example
- * ```typescript
- * deriveParentParamName('posts')      // 'postId'
- * deriveParentParamName('users')      // 'userId'
- * deriveParentParamName('categories') // 'categoryId'
- * deriveParentParamName('data')       // 'dataId' (no change for non-plural)
- * ```
- *
- * @internal
- */
-function deriveParentParamName(namespace) {
-    // Handle common irregular plurals
-    const irregulars = {
-        people: 'person',
-        children: 'child',
-        men: 'man',
-        women: 'woman',
-        mice: 'mouse',
-        geese: 'goose',
-        teeth: 'tooth',
-        feet: 'foot',
-        data: 'datum',
-        criteria: 'criterion',
-        phenomena: 'phenomenon',
-    };
-    const lower = namespace.toLowerCase();
-    if (irregulars[lower]) {
-        return `${irregulars[lower]}Id`;
-    }
-    // Handle common English pluralization patterns
-    let singular = namespace;
-    if (namespace.endsWith('ies') && namespace.length > 3) {
-        // categories -> category
-        singular = `${namespace.slice(0, -3)}y`;
-    }
-    else if (namespace.endsWith('es') && namespace.length > 2) {
-        // Check for -shes, -ches, -xes, -zes, -sses patterns
-        const beforeEs = namespace.slice(-4, -2);
-        if (['sh', 'ch'].includes(beforeEs) || ['x', 'z', 's'].includes(namespace.slice(-3, -2))) {
-            singular = namespace.slice(0, -2);
-        }
-        else {
-            // classes -> class (double s + es)
-            singular = namespace.slice(0, -1);
-        }
-    }
-    else if (namespace.endsWith('s') && namespace.length > 1 && !namespace.endsWith('ss')) {
-        // Simple plural: users -> user, posts -> post
-        singular = namespace.slice(0, -1);
-    }
-    return `${singular}Id`;
-}
-// ============================================================================
 // Builder Factory
 // ============================================================================
 /**

package/dist/types.d.ts

@@ -7,6 +7,7 @@
  * @module types
  */
 import type { BaseContext } from '@veloxts/core';
+import type { HttpMethod } from '@veloxts/validation';
 /**
  * Procedure operation types
  *
@@ -18,11 +19,17 @@ export type ProcedureType = 'query' | 'mutation';
  * HTTP methods supported by the REST adapter
  *
  * Full REST support: GET, POST, PUT, PATCH, DELETE
+ *
+ * @see {@link PROCEDURE_METHOD_MAP} for naming convention mapping
  */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type { HttpMethod };
 /**
  * Maps procedure naming conventions to HTTP methods
  *
+ * Re-exported from @veloxts/validation for consistency across router and client.
+ *
+ * @see {@link @veloxts/validation!PROCEDURE_METHOD_MAP} for the canonical definition
+ *
  * @example
  * - getUser -> GET
  * - listUsers -> GET
@@ -31,7 +38,7 @@ export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  * - patchUser -> PATCH
  * - deleteUser -> DELETE
  */
-export declare const PROCEDURE_METHOD_MAP: Record<string, HttpMethod>;
+export { PROCEDURE_METHOD_MAP } from '@veloxts/validation';
 /**
  * Extended context type that can be augmented by middleware
  *

package/dist/types.js

@@ -9,6 +9,10 @@
 /**
  * Maps procedure naming conventions to HTTP methods
  *
+ * Re-exported from @veloxts/validation for consistency across router and client.
+ *
+ * @see {@link @veloxts/validation!PROCEDURE_METHOD_MAP} for the canonical definition
+ *
  * @example
  * - getUser -> GET
  * - listUsers -> GET
@@ -17,15 +21,4 @@
  * - patchUser -> PATCH
  * - deleteUser -> DELETE
  */
-export const PROCEDURE_METHOD_MAP = {
-    get: 'GET',
-    list: 'GET',
-    find: 'GET',
-    create: 'POST',
-    add: 'POST',
-    update: 'PUT',
-    edit: 'PUT',
-    patch: 'PATCH',
-    delete: 'DELETE',
-    remove: 'DELETE',
-};
+export { PROCEDURE_METHOD_MAP } from '@veloxts/validation';

package/dist/utils/pluralization.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pluralization utilities for REST naming conventions
+ *
+ * Provides functions to convert between singular and plural forms
+ * for resource names. Used primarily by the procedure builder to
+ * derive parent parameter names from namespaces.
+ *
+ * @module utils/pluralization
+ */
+/**
+ * Converts a plural word to its singular form
+ *
+ * Uses heuristics for common English pluralization patterns:
+ * - Irregular plurals (people -> person, children -> child)
+ * - -ies endings (categories -> category)
+ * - -es endings (boxes -> box, classes -> class)
+ * - Simple -s endings (users -> user)
+ *
+ * @param word - The plural word to singularize
+ * @returns The singular form of the word
+ *
+ * @example
+ * ```typescript
+ * singularize('users')      // 'user'
+ * singularize('categories') // 'category'
+ * singularize('boxes')      // 'box'
+ * singularize('people')     // 'person'
+ * singularize('data')       // 'datum'
+ * ```
+ */
+export declare function singularize(word: string): string;
+/**
+ * Derives a parameter name from a resource namespace
+ *
+ * Converts a plural namespace to a singular form and appends 'Id'.
+ * This is used to derive parent parameter names for nested routes.
+ *
+ * @param namespace - The parent resource namespace (e.g., 'posts', 'users')
+ * @returns The parameter name (e.g., 'postId', 'userId')
+ *
+ * @example
+ * ```typescript
+ * deriveParentParamName('posts')      // 'postId'
+ * deriveParentParamName('users')      // 'userId'
+ * deriveParentParamName('categories') // 'categoryId'
+ * deriveParentParamName('people')     // 'personId'
+ * deriveParentParamName('data')       // 'datumId'
+ * ```
+ */
+export declare function deriveParentParamName(namespace: string): string;

package/dist/utils/pluralization.js

@@ -0,0 +1,111 @@
+/**
+ * Pluralization utilities for REST naming conventions
+ *
+ * Provides functions to convert between singular and plural forms
+ * for resource names. Used primarily by the procedure builder to
+ * derive parent parameter names from namespaces.
+ *
+ * @module utils/pluralization
+ */
+// ============================================================================
+// Irregular Plurals
+// ============================================================================
+/**
+ * Common irregular English plurals
+ *
+ * Maps plural forms to their singular equivalents.
+ * Used for accurate parameter name derivation.
+ */
+const IRREGULAR_PLURALS = {
+    people: 'person',
+    children: 'child',
+    men: 'man',
+    women: 'woman',
+    mice: 'mouse',
+    geese: 'goose',
+    teeth: 'tooth',
+    feet: 'foot',
+    data: 'datum',
+    criteria: 'criterion',
+    phenomena: 'phenomenon',
+};
+// ============================================================================
+// Singularization
+// ============================================================================
+/**
+ * Converts a plural word to its singular form
+ *
+ * Uses heuristics for common English pluralization patterns:
+ * - Irregular plurals (people -> person, children -> child)
+ * - -ies endings (categories -> category)
+ * - -es endings (boxes -> box, classes -> class)
+ * - Simple -s endings (users -> user)
+ *
+ * @param word - The plural word to singularize
+ * @returns The singular form of the word
+ *
+ * @example
+ * ```typescript
+ * singularize('users')      // 'user'
+ * singularize('categories') // 'category'
+ * singularize('boxes')      // 'box'
+ * singularize('people')     // 'person'
+ * singularize('data')       // 'datum'
+ * ```
+ */
+export function singularize(word) {
+    // Check irregular plurals first
+    const lower = word.toLowerCase();
+    if (IRREGULAR_PLURALS[lower]) {
+        // Preserve original casing for first letter
+        const singular = IRREGULAR_PLURALS[lower];
+        if (word[0] === word[0].toUpperCase()) {
+            return singular.charAt(0).toUpperCase() + singular.slice(1);
+        }
+        return singular;
+    }
+    // Handle common English pluralization patterns
+    if (word.endsWith('ies') && word.length > 3) {
+        // categories -> category
+        return `${word.slice(0, -3)}y`;
+    }
+    if (word.endsWith('es') && word.length > 2) {
+        // Check for -shes, -ches, -xes, -zes, -sses patterns
+        const beforeEs = word.slice(-4, -2);
+        if (['sh', 'ch'].includes(beforeEs) || ['x', 'z', 's'].includes(word.slice(-3, -2))) {
+            return word.slice(0, -2);
+        }
+        // Default: remove just the 's' (e.g., "types" -> "type")
+        return word.slice(0, -1);
+    }
+    if (word.endsWith('s') && word.length > 1 && !word.endsWith('ss')) {
+        // Simple plural: users -> user, posts -> post
+        return word.slice(0, -1);
+    }
+    // Word doesn't appear to be plural, return as-is
+    return word;
+}
+// ============================================================================
+// Parameter Name Derivation
+// ============================================================================
+/**
+ * Derives a parameter name from a resource namespace
+ *
+ * Converts a plural namespace to a singular form and appends 'Id'.
+ * This is used to derive parent parameter names for nested routes.
+ *
+ * @param namespace - The parent resource namespace (e.g., 'posts', 'users')
+ * @returns The parameter name (e.g., 'postId', 'userId')
+ *
+ * @example
+ * ```typescript
+ * deriveParentParamName('posts')      // 'postId'
+ * deriveParentParamName('users')      // 'userId'
+ * deriveParentParamName('categories') // 'categoryId'
+ * deriveParentParamName('people')     // 'personId'
+ * deriveParentParamName('data')       // 'datumId'
+ * ```
+ */
+export function deriveParentParamName(namespace) {
+    return `${singularize(namespace)}Id`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.6.87",
+  "version": "0.6.88",
   "description": "Procedure definitions with tRPC and REST routing for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -40,8 +40,8 @@
     "@trpc/server": "11.8.0",
     "fastify": "5.6.2",
     "zod-to-json-schema": "3.24.5",
-    "@veloxts/validation": "0.6.87",
-    "@veloxts/core": "0.6.87"
+    "@veloxts/validation": "0.6.88",
+    "@veloxts/core": "0.6.88"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.16",