@tamyla/clodo-framework 4.4.1 → 4.5.0

package/dist/routing/EnhancedRouter.js

@@ -1,37 +1,61 @@
 import { createRouteHandlers } from '../handlers/GenericRouteHandler.js';
 import { schemaManager } from '../schema/SchemaManager.js';
+import { MiddlewareComposer } from '../middleware/Composer.js';
+import { RequestContext, createRequestContext } from './RequestContext.js';
 
 /**
  * Enhanced Router
- * Supports both domain-specific routes and generic CRUD routes
- *
- * Framework-ready version: All data-service specific imports and routes removed.
- * Domain-specific routes should be registered by the consuming application.
+ * Supports Express/Hono-style routing with middleware composition,
+ * parameterized routes, and optional auto-CRUD for schema models.
+ * 
+ * Now works without a D1 client — pass null for pure API routing.
+ * 
+ * @example
+ * import { EnhancedRouter, createEnhancedRouter } from '@tamyla/clodo-framework';
+ * 
+ * // Minimal router (no D1)
+ * const router = new EnhancedRouter();
+ * 
+ * // With Hono-style RequestContext:
+ * router.get('/users/:id', async (c) => {
+ *   return c.json({ user: c.req.param('id') });
+ * });
+ * 
+ * // With classic (request, env, ctx) pattern:
+ * router.get('/legacy', async (request, env, ctx) => {
+ *   return new Response('ok');
+ * });
  */
 
 export class EnhancedRouter {
   /**
    * Create a new EnhancedRouter instance
-   * @param {Object} d1Client - D1 database client
-   * @param {Object} options - Router options
+   * @param {Object} [d1Client=null] - Optional D1 database client (null for pure routing)
+   * @param {Object} [options={}] - Router options
+   * @param {boolean} [options.autoRegisterGenericRoutes=true] - Auto-register CRUD routes for schema models
+   * @param {boolean} [options.useRequestContext=true] - Pass RequestContext to handlers instead of raw request
    */
-  constructor(d1Client, options = {}) {
+  constructor(d1Client = null, options = {}) {
     this.d1Client = d1Client;
     this.options = options;
     this.routes = new Map();
-    this.genericHandlers = createRouteHandlers(d1Client, options);
+    this.middleware = [];
+    this.scopedMiddleware = new Map(); // path prefix → middleware[]
+    this.middlewareExecutor = null;
 
-    // Register generic routes for all models
-    this._registerGenericRoutes();
-
-    // Note: Domain-specific routes should be registered by the consuming application
+    // Only auto-register CRUD routes if D1 client is provided and option is enabled
+    const autoRegister = options.autoRegisterGenericRoutes !== false && d1Client;
+    if (autoRegister) {
+      this.genericHandlers = createRouteHandlers(d1Client, options);
+      this._registerGenericRoutes();
+    }
   }
 
   /**
    * Register a custom route
    * @param {string} method - HTTP method
-   * @param {string} path - Route path
-   * @param {Function} handler - Route handler
+   * @param {string} path - Route path (supports :params and * wildcards)
+   * @param {Function} handler - Route handler: (c: RequestContext) => Response or (request, env, ctx) => Response
    */
   registerRoute(method, path, handler) {
     const key = `${method.toUpperCase()} ${path}`;
@@ -101,39 +125,89 @@ export class EnhancedRouter {
     return this.registerRoute('HEAD', path, handler);
   }
 
+  /**
+   * Register a route handler for ALL HTTP methods
+   * @param {string} path - Route path
+   * @param {Function} handler - Route handler
+   */
+  all(path, handler) {
+    for (const method of ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']) {
+      this.registerRoute(method, path, handler);
+    }
+  }
+
   /**
    * Find and execute a route handler
+   * 
+   * Supports two call signatures:
+   * - handleRequest(method, path, request) — legacy
+   * - handleRequest(method, path, request, env, ctx) — full Workers signature
+   * 
    * @param {string} method - HTTP method
    * @param {string} path - Request path
    * @param {Request} request - HTTP request
+   * @param {Object} [env] - Worker environment bindings
+   * @param {Object} [ctx] - Worker execution context
    * @returns {Promise<Response>} HTTP response
    */
-  async handleRequest(method, path, request) {
-    const key = `${method.toUpperCase()} ${path}`;
+  async handleRequest(method, path, request, env = {}, ctx = {}) {
+    // Create a handler function that will be executed with middleware
+    let handler = null;
+    let params = {};
 
     // Check for exact match first
+    const key = `${method.toUpperCase()} ${path}`;
     if (this.routes.has(key)) {
-      const handler = this.routes.get(key);
-      return await handler(request);
+      handler = this.routes.get(key);
+    } else {
+      // Check for parameterized routes
+      for (const [routeKey, routeHandler] of this.routes.entries()) {
+        const [routeMethod, routePath] = routeKey.split(' ');
+        if (routeMethod !== method.toUpperCase()) continue;
+        const match = this._matchRoute(routePath, path);
+        if (match) {
+          params = match.params;
+          handler = routeHandler;
+          break;
+        }
+      }
     }
 
-    // Check for parameterized routes
-    for (const [routeKey, handler] of this.routes.entries()) {
-      const [routeMethod, routePath] = routeKey.split(' ');
-      if (routeMethod !== method.toUpperCase()) continue;
-      const match = this._matchRoute(routePath, path);
-      if (match) {
-        // Add route parameters to request
-        // @ts-ignore - Extending Request object with params
-        request.params = match.params;
-        return await handler(request, ...match.args);
-      }
+    // If no handler found, return 404
+    if (!handler) {
+      return new Response(JSON.stringify({
+        error: 'Not Found',
+        path
+      }), {
+        status: 404,
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
     }
 
-    // No route found
-    return new Response('Not Found', {
-      status: 404
-    });
+    // Detect handler arity to decide: RequestContext vs raw (request, env, ctx)
+    const useContext = this.options.useRequestContext !== false;
+
+    // Build the actual handler execution function
+    const executeHandler = async req => {
+      if (useContext && handler.length <= 1) {
+        // Hono-style: single argument = RequestContext
+        const c = new RequestContext(req, env, ctx, params);
+        return await handler(c);
+      } else {
+        // Classic style: (request, env, ctx) — attach params to request
+        req.params = params;
+        return await handler(req, env, ctx);
+      }
+    };
+
+    // Execute with middleware if available, otherwise execute directly
+    if (this.middlewareExecutor) {
+      return await this.middlewareExecutor.execute(request, executeHandler);
+    } else {
+      return await executeHandler(request);
+    }
   }
 
   /**
@@ -141,8 +215,10 @@ export class EnhancedRouter {
    * @private
    */
   _registerGenericRoutes() {
+    if (!this.genericHandlers) return;
     for (const [modelName] of schemaManager.getAllModels()) {
       const handler = this.genericHandlers[modelName];
+      if (!handler) continue;
       const basePath = `/api/${modelName}`;
 
       // CRUD routes
@@ -151,7 +227,9 @@ export class EnhancedRouter {
       this.registerRoute('GET', `${basePath}/:id`, (req, id) => handler.handleGet(req, id));
       this.registerRoute('PATCH', `${basePath}/:id`, (req, id) => handler.handleUpdate(req, id));
       this.registerRoute('DELETE', `${basePath}/:id`, (req, id) => handler.handleDelete(req, id));
-      console.log(`✅ Registered generic routes for: ${modelName}`);
+      if (this.options.verbose || typeof process !== 'undefined' && process.env?.DEBUG) {
+        console.log(`✅ Registered generic routes for: ${modelName}`);
+      }
     }
   }
 
@@ -178,6 +256,11 @@ export class EnhancedRouter {
         const paramName = patternPart.slice(1);
         params[paramName] = pathPart;
         args.push(pathPart);
+      } else if (patternPart === '*') {
+        // Wildcard — matches anything
+        params['*'] = pathParts.slice(i).join('/');
+        args.push(params['*']);
+        break;
       } else if (patternPart !== pathPart) {
         // No match
         return null;
@@ -199,23 +282,81 @@ export class EnhancedRouter {
 
   /**
    * Add middleware to the router
-   * @param {Function} middleware - Middleware function
+   * 
+   * Supports two signatures:
+   * - use(middleware)         — global middleware
+   * - use('/path', middleware) — scoped to a path prefix
+   * 
+   * @param {string|Function|Object} pathOrMiddleware - Path prefix or middleware
+   * @param {Function|Object} [middleware] - Middleware (when first arg is a path)
+   */
+  use(pathOrMiddleware, middleware) {
+    if (typeof pathOrMiddleware === 'string' && middleware) {
+      // Scoped middleware: use('/api', corsMiddleware)
+      const prefix = pathOrMiddleware;
+      if (!this.scopedMiddleware.has(prefix)) {
+        this.scopedMiddleware.set(prefix, []);
+      }
+      this.scopedMiddleware.get(prefix).push(middleware);
+    } else {
+      // Global middleware
+      this.middleware.push(pathOrMiddleware);
+    }
+
+    // Rebuild the middleware executor
+    this._rebuildMiddlewareExecutor();
+  }
+
+  /**
+   * Rebuild the middleware executor when middleware changes
+   * @private
    */
-  use(middleware) {
-    // Store middleware for later use
-    if (!this.middleware) {
-      this.middleware = [];
+  _rebuildMiddlewareExecutor() {
+    if (this.middleware.length > 0) {
+      this.middlewareExecutor = MiddlewareComposer.compose(...this.middleware);
+    } else {
+      this.middlewareExecutor = null;
     }
-    this.middleware.push(middleware);
+  }
+
+  /**
+   * Create a route group with a shared prefix
+   * @param {string} prefix - Path prefix for all routes in the group
+   * @param {Function} callback - (group: EnhancedRouter) => void
+   * @returns {EnhancedRouter} this — for chaining
+   * 
+   * @example
+   * router.group('/api/v1', (api) => {
+   *   api.get('/users', listUsers);
+   *   api.post('/users', createUser);
+   *   api.get('/users/:id', getUser);
+   * });
+   */
+  group(prefix, callback) {
+    const groupRouter = {
+      get: (path, handler) => this.get(prefix + path, handler),
+      post: (path, handler) => this.post(prefix + path, handler),
+      put: (path, handler) => this.put(prefix + path, handler),
+      patch: (path, handler) => this.patch(prefix + path, handler),
+      delete: (path, handler) => this.delete(prefix + path, handler),
+      options: (path, handler) => this.options(prefix + path, handler),
+      head: (path, handler) => this.head(prefix + path, handler),
+      all: (path, handler) => this.all(prefix + path, handler)
+    };
+    callback(groupRouter);
+    return this;
   }
 }
 
 /**
  * Create an enhanced router instance
- * @param {Object} d1Client - D1 database client
- * @param {Object} options - Router options
+ * @param {Object} [d1Client=null] - Optional D1 database client
+ * @param {Object} [options={}] - Router options
  * @returns {EnhancedRouter} Router instance
  */
-export function createEnhancedRouter(d1Client, options = {}) {
+export function createEnhancedRouter(d1Client = null, options = {}) {
   return new EnhancedRouter(d1Client, options);
-}
+}
+
+// Re-export RequestContext for direct usage
+export { RequestContext, createRequestContext } from './RequestContext.js';

package/dist/routing/RequestContext.js

@@ -0,0 +1,393 @@
+/**
+ * RequestContext — Hono-style request/response context for Cloudflare Workers
+ * 
+ * Wraps the standard (request, env, ctx) triplet into a single ergonomic object.
+ * 
+ * @example
+ * import { RequestContext } from '@tamyla/clodo-framework/routing';
+ * 
+ * router.get('/users/:id', async (c) => {
+ *   const id = c.req.param('id');
+ *   const data = await c.env.KV_DATA.get(id);
+ *   return c.json({ id, data });
+ * });
+ * 
+ * @module @tamyla/clodo-framework/routing/RequestContext
+ */
+
+export class RequestContext {
+  /**
+   * @param {Request} request - The incoming request
+   * @param {Object} env - Cloudflare Worker environment bindings
+   * @param {ExecutionContext} executionCtx - Worker execution context
+   * @param {Object} [params={}] - Route parameters extracted by the router
+   */
+  constructor(request, env, executionCtx, params = {}) {
+    this._request = request;
+    this._env = env;
+    this._executionCtx = executionCtx;
+    this._params = params;
+    this._url = null; // lazy-parsed
+    this._headers = new Headers();
+    this._status = 200;
+    this._store = new Map(); // per-request storage for middleware data sharing
+  }
+
+  // ─── Request Accessors ──────────────────────────────────────────────
+
+  /** The raw Request object */
+  get request() {
+    return this._request;
+  }
+
+  /** Alias — matches Hono's `c.req` */
+  get req() {
+    return this._reqProxy || (this._reqProxy = this._buildReqProxy());
+  }
+
+  /** Worker environment bindings */
+  get env() {
+    return this._env;
+  }
+
+  /** Worker execution context (for waitUntil, passThroughOnException, etc.) */
+  get executionCtx() {
+    return this._executionCtx;
+  }
+
+  /** Parsed URL (lazy) */
+  get url() {
+    return this._url || (this._url = new URL(this._request.url));
+  }
+
+  // ─── Per-request store (for middleware data sharing) ─────────────────
+
+  /**
+   * Set a value in the per-request store
+   * @param {string} key
+   * @param {*} value
+   */
+  set(key, value) {
+    this._store.set(key, value);
+  }
+
+  /**
+   * Get a value from the per-request store
+   * @param {string} key
+   * @returns {*}
+   */
+  get(key) {
+    return this._store.get(key);
+  }
+
+  // ─── Response Helpers ───────────────────────────────────────────────
+
+  /**
+   * Return a JSON response
+   * @param {*} data - Data to serialize
+   * @param {number} [status=200] - HTTP status code
+   * @param {Object} [headers={}] - Additional response headers
+   * @returns {Response}
+   */
+  json(data, status = 200, headers = {}) {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: {
+        'Content-Type': 'application/json; charset=utf-8',
+        ...Object.fromEntries(this._headers),
+        ...headers
+      }
+    });
+  }
+
+  /**
+   * Return a plain text response
+   * @param {string} text
+   * @param {number} [status=200]
+   * @param {Object} [headers={}]
+   * @returns {Response}
+   */
+  text(text, status = 200, headers = {}) {
+    return new Response(String(text), {
+      status,
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        ...Object.fromEntries(this._headers),
+        ...headers
+      }
+    });
+  }
+
+  /**
+   * Return an HTML response
+   * @param {string} html
+   * @param {number} [status=200]
+   * @param {Object} [headers={}]
+   * @returns {Response}
+   */
+  html(html, status = 200, headers = {}) {
+    return new Response(String(html), {
+      status,
+      headers: {
+        'Content-Type': 'text/html; charset=utf-8',
+        ...Object.fromEntries(this._headers),
+        ...headers
+      }
+    });
+  }
+
+  /**
+   * Return a redirect response
+   * @param {string} url - Target URL
+   * @param {number} [status=302] - 301 or 302
+   * @returns {Response}
+   */
+  redirect(url, status = 302) {
+    return Response.redirect(url, status);
+  }
+
+  /**
+   * Return a streaming response — ideal for Workers AI streaming
+   * @param {Function} callback - async (stream: WritableStreamDefaultWriter) => void
+   * @param {Object} [headers={}] - Additional response headers
+   * @returns {Response}
+   * 
+   * @example
+   * return c.stream(async (stream) => {
+   *   const aiStream = await env.AI.run(model, { stream: true, messages });
+   *   for await (const chunk of aiStream) {
+   *     await stream.write(new TextEncoder().encode(chunk.response));
+   *   }
+   * });
+   */
+  stream(callback, headers = {}) {
+    const {
+      readable,
+      writable
+    } = new TransformStream();
+    const writer = writable.getWriter();
+
+    // Wrap writer with convenience methods
+    const stream = {
+      write: async data => {
+        const chunk = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        await writer.write(chunk);
+      },
+      writeLine: async data => {
+        await stream.write(data + '\n');
+      },
+      close: async () => {
+        await writer.close();
+      },
+      abort: async reason => {
+        await writer.abort(reason);
+      }
+    };
+
+    // Run the callback in the background via waitUntil if available
+    const promise = (async () => {
+      try {
+        await callback(stream);
+      } catch (err) {
+        await stream.write(`Error: ${err.message}`);
+      } finally {
+        try {
+          await stream.close();
+        } catch {/* already closed */}
+      }
+    })();
+    if (this._executionCtx?.waitUntil) {
+      this._executionCtx.waitUntil(promise);
+    }
+    return new Response(readable, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        ...Object.fromEntries(this._headers),
+        ...headers
+      }
+    });
+  }
+
+  /**
+   * Return a Server-Sent Events (SSE) streaming response
+   * @param {Function} callback - async (sse: { send, close }) => void
+   * @param {Object} [headers={}]
+   * @returns {Response}
+   * 
+   * @example
+   * return c.sse(async (sse) => {
+   *   for (let i = 0; i < 10; i++) {
+   *     await sse.send({ data: `chunk ${i}`, event: 'progress' });
+   *   }
+   * });
+   */
+  sse(callback, headers = {}) {
+    return this.stream(async stream => {
+      const sse = {
+        send: async ({
+          data,
+          event,
+          id,
+          retry
+        }) => {
+          let message = '';
+          if (id) message += `id: ${id}\n`;
+          if (event) message += `event: ${event}\n`;
+          if (retry) message += `retry: ${retry}\n`;
+          message += `data: ${typeof data === 'object' ? JSON.stringify(data) : data}\n\n`;
+          await stream.write(message);
+        },
+        close: async () => {
+          await stream.close();
+        }
+      };
+      await callback(sse);
+    }, {
+      'Content-Type': 'text/event-stream',
+      ...headers
+    });
+  }
+
+  /**
+   * Return a 404 Not Found response
+   * @param {string} [message='Not Found']
+   * @returns {Response}
+   */
+  notFound(message = 'Not Found') {
+    return this.json({
+      error: message
+    }, 404);
+  }
+
+  /**
+   * Set a response header (applied to all subsequent response helpers)
+   * @param {string} key
+   * @param {string} value
+   * @returns {RequestContext} this — for chaining
+   */
+  header(key, value) {
+    this._headers.set(key, value);
+    return this;
+  }
+
+  /**
+   * Schedule work after the response is sent via ctx.waitUntil
+   * @param {Promise} promise
+   */
+  waitUntil(promise) {
+    if (this._executionCtx?.waitUntil) {
+      this._executionCtx.waitUntil(promise);
+    }
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────
+
+  /** Build a proxy object for c.req that provides Hono-style accessors */
+  _buildReqProxy() {
+    const ctx = this;
+    return {
+      /** The raw Request object */
+      get raw() {
+        return ctx._request;
+      },
+      /** HTTP method */
+      get method() {
+        return ctx._request.method;
+      },
+      /** Full URL string */
+      get url() {
+        return ctx._request.url;
+      },
+      /** Request headers */
+      get headers() {
+        return ctx._request.headers;
+      },
+      /**
+       * Get a route parameter
+       * @param {string} name
+       * @returns {string|undefined}
+       */
+      param(name) {
+        return name ? ctx._params[name] : {
+          ...ctx._params
+        };
+      },
+      /**
+       * Get a query string parameter
+       * @param {string} name
+       * @returns {string|null}
+       */
+      query(name) {
+        if (!name) {
+          return Object.fromEntries(ctx.url.searchParams.entries());
+        }
+        return ctx.url.searchParams.get(name);
+      },
+      /**
+       * Get a request header
+       * @param {string} name
+       * @returns {string|null}
+       */
+      header(name) {
+        return ctx._request.headers.get(name);
+      },
+      /**
+       * Parse body as JSON
+       * @returns {Promise<*>}
+       */
+      async json() {
+        return ctx._request.json();
+      },
+      /**
+       * Parse body as text
+       * @returns {Promise<string>}
+       */
+      async text() {
+        return ctx._request.text();
+      },
+      /**
+       * Parse body as FormData
+       * @returns {Promise<FormData>}
+       */
+      async formData() {
+        return ctx._request.formData();
+      },
+      /**
+       * Parse body as ArrayBuffer
+       * @returns {Promise<ArrayBuffer>}
+       */
+      async arrayBuffer() {
+        return ctx._request.arrayBuffer();
+      },
+      /**
+       * Get the body as a ReadableStream
+       * @returns {ReadableStream|null}
+       */
+      get body() {
+        return ctx._request.body;
+      },
+      /**
+       * Get the pathname
+       * @returns {string}
+       */
+      get path() {
+        return ctx.url.pathname;
+      }
+    };
+  }
+}
+
+/**
+ * Create a RequestContext instance — factory function alternative
+ * @param {Request} request
+ * @param {Object} env
+ * @param {ExecutionContext} ctx
+ * @param {Object} [params={}]
+ * @returns {RequestContext}
+ */
+export function createRequestContext(request, env, ctx, params = {}) {
+  return new RequestContext(request, env, ctx, params);
+}