blendsdk 5.33.0

package/dist/webafx/application/request-context.d.ts

@@ -0,0 +1,62 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Request context data propagated through async operations.
+ * Contains request-scoped information accessible anywhere in the request lifecycle.
+ */
+export interface RequestContext {
+    /** Unique request ID for tracing */
+    requestId: string;
+    /** Request start time (milliseconds since epoch) */
+    startTime: number;
+    /** Additional context properties can be added dynamically */
+    [key: string]: unknown;
+}
+/**
+ * Shared AsyncLocalStorage instance for request context propagation.
+ * This enables accessing request-scoped data anywhere in the async call chain
+ * without explicitly passing it through function parameters.
+ *
+ * @remarks
+ * AsyncLocalStorage is a Node.js feature that maintains context across async operations.
+ * Each request runs in its own context, preventing cross-request contamination.
+ *
+ * @example
+ * ```typescript
+ * // In middleware:
+ * requestContextStorage.run(context, () => {
+ *   next(); // All async operations from here have access to context
+ * });
+ *
+ * // Anywhere in the request lifecycle:
+ * const context = getRequestContext();
+ * console.log(context?.requestId);
+ * ```
+ */
+export declare const requestContextStorage: AsyncLocalStorage<RequestContext>;
+/**
+ * Gets the current request context if inside a request scope.
+ *
+ * @returns Request context object, or undefined if called outside request scope
+ *
+ * @example
+ * ```typescript
+ * const context = getRequestContext();
+ * if (context) {
+ *   logger.info('Processing request', { requestId: context.requestId });
+ * }
+ * ```
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Gets the current request ID if inside a request scope.
+ *
+ * @returns Request ID string, or undefined if called outside request scope
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestId();
+ * await database.query('SELECT * FROM users WHERE id = ?', [userId], { requestId });
+ * ```
+ */
+export declare function getRequestId(): string | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/webafx/application/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/application/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,qBAAqB,mCAA0C,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAEjD"}

package/dist/webafx/application/request-context.js

@@ -0,0 +1,54 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Shared AsyncLocalStorage instance for request context propagation.
+ * This enables accessing request-scoped data anywhere in the async call chain
+ * without explicitly passing it through function parameters.
+ *
+ * @remarks
+ * AsyncLocalStorage is a Node.js feature that maintains context across async operations.
+ * Each request runs in its own context, preventing cross-request contamination.
+ *
+ * @example
+ * ```typescript
+ * // In middleware:
+ * requestContextStorage.run(context, () => {
+ *   next(); // All async operations from here have access to context
+ * });
+ *
+ * // Anywhere in the request lifecycle:
+ * const context = getRequestContext();
+ * console.log(context?.requestId);
+ * ```
+ */
+export const requestContextStorage = new AsyncLocalStorage();
+/**
+ * Gets the current request context if inside a request scope.
+ *
+ * @returns Request context object, or undefined if called outside request scope
+ *
+ * @example
+ * ```typescript
+ * const context = getRequestContext();
+ * if (context) {
+ *   logger.info('Processing request', { requestId: context.requestId });
+ * }
+ * ```
+ */
+export function getRequestContext() {
+    return requestContextStorage.getStore();
+}
+/**
+ * Gets the current request ID if inside a request scope.
+ *
+ * @returns Request ID string, or undefined if called outside request scope
+ *
+ * @example
+ * ```typescript
+ * const requestId = getRequestId();
+ * await database.query('SELECT * FROM users WHERE id = ?', [userId], { requestId });
+ * ```
+ */
+export function getRequestId() {
+    return requestContextStorage.getStore()?.requestId;
+}
+//# sourceMappingURL=request-context.js.map

package/dist/webafx/application/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/application/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAerD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,qBAAqB,CAAC,QAAQ,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,qBAAqB,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC;AACrD,CAAC"}

package/dist/webafx/application/request-id-middleware.d.ts

@@ -0,0 +1,30 @@
+import { NextFunction, Request, Response } from 'express';
+/**
+ * Validates whether a string is a valid UUID v4 format.
+ *
+ * @param id - The string to validate
+ * @returns True if the string matches UUID v4 format
+ */
+export declare function isValidUUID(id: string): boolean;
+/**
+ * Request ID middleware.
+ * Generates a unique correlation ID for each request and propagates it through
+ * AsyncLocalStorage for access anywhere in the request lifecycle.
+ * Attaches it to req.id and X-Request-ID response header.
+ *
+ * If the incoming request has an X-Request-ID header with a valid UUID format,
+ * it is reused. Otherwise, a new UUID is generated. This prevents malformed
+ * or malicious request IDs from propagating through the system.
+ *
+ * @remarks
+ * The request context is stored in AsyncLocalStorage, making the request ID
+ * accessible via `getRequestId()` or `getRequestContext()` anywhere in the
+ * async call chain without explicitly passing it through parameters.
+ *
+ * @example
+ * ```typescript
+ * app.use(requestIdMiddleware());
+ * ```
+ */
+export declare function requestIdMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=request-id-middleware.d.ts.map

package/dist/webafx/application/request-id-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id-middleware.d.ts","sourceRoot":"","sources":["../../src/application/request-id-middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAS1D;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,KACzB,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAuBxD"}

package/dist/webafx/application/request-id-middleware.js

@@ -0,0 +1,57 @@
+import { randomUUID } from 'crypto';
+import { requestContextStorage } from './request-context.js';
+/**
+ * UUID v4 format regex pattern.
+ * Validates standard UUID format: 8-4-4-4-12 hex characters.
+ */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Validates whether a string is a valid UUID v4 format.
+ *
+ * @param id - The string to validate
+ * @returns True if the string matches UUID v4 format
+ */
+export function isValidUUID(id) {
+    return UUID_REGEX.test(id);
+}
+/**
+ * Request ID middleware.
+ * Generates a unique correlation ID for each request and propagates it through
+ * AsyncLocalStorage for access anywhere in the request lifecycle.
+ * Attaches it to req.id and X-Request-ID response header.
+ *
+ * If the incoming request has an X-Request-ID header with a valid UUID format,
+ * it is reused. Otherwise, a new UUID is generated. This prevents malformed
+ * or malicious request IDs from propagating through the system.
+ *
+ * @remarks
+ * The request context is stored in AsyncLocalStorage, making the request ID
+ * accessible via `getRequestId()` or `getRequestContext()` anywhere in the
+ * async call chain without explicitly passing it through parameters.
+ *
+ * @example
+ * ```typescript
+ * app.use(requestIdMiddleware());
+ * ```
+ */
+export function requestIdMiddleware() {
+    return (req, res, next) => {
+        // Check if request already has a valid UUID from upstream proxy
+        const existingId = req.headers['x-request-id'];
+        // Only reuse existing ID if it's a valid UUID format;
+        // reject malformed IDs to prevent injection or log corruption
+        const requestId = existingId && isValidUUID(existingId) ? existingId : randomUUID();
+        // Attach to request
+        req.id = requestId;
+        // Add to response headers
+        res.setHeader('X-Request-ID', requestId);
+        // Create request context and run the rest of the request in AsyncLocalStorage
+        const context = {
+            requestId,
+            startTime: Date.now(),
+        };
+        // All async operations from this point have access to the context
+        requestContextStorage.run(context, () => next());
+    };
+}
+//# sourceMappingURL=request-id-middleware.js.map

package/dist/webafx/application/request-id-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id-middleware.js","sourceRoot":"","sources":["../../src/application/request-id-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,EAAkB,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7E;;;GAGG;AACH,MAAM,UAAU,GAAG,iEAAiE,CAAC;AAErF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;QACzD,gEAAgE;QAChE,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,CAAW,CAAC;QAEzD,sDAAsD;QACtD,8DAA8D;QAC9D,MAAM,SAAS,GAAG,UAAU,IAAI,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QAEpF,oBAAoB;QACpB,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC;QAEnB,0BAA0B;QAC1B,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;QAEzC,8EAA8E;QAC9E,MAAM,OAAO,GAAmB;YAC9B,SAAS;YACT,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;QAEF,kEAAkE;QAClE,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC,CAAC;AACJ,CAAC"}

package/dist/webafx/application/route-builder.d.ts

@@ -0,0 +1,231 @@
+import { NextFunction, Request, RequestHandler, Response } from 'express';
+import { ZodType } from 'zod';
+/**
+ * Supported HTTP methods for routes.
+ */
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/**
+ * Response definition for OpenAPI documentation.
+ * Describes a possible response from an API endpoint.
+ *
+ * @remarks
+ * This is pure metadata — no generation logic lives in webafx.
+ * The actual OpenAPI spec generation happens in `@blendsdk/codegen`.
+ */
+export interface OpenAPIResponseDefinition {
+    /** HTTP status code (e.g., 200, 201, 400, 404) */
+    statusCode: number;
+    /** Human-readable description of this response */
+    description: string;
+    /** Optional Zod schema describing the response body structure */
+    schema?: ZodType;
+}
+/**
+ * Optional OpenAPI metadata for route documentation.
+ *
+ * Only routes with this metadata will be included in generated OpenAPI specs.
+ * This serves as the opt-in mechanism: routes without `.openapi()` are excluded
+ * from the generated specification, keeping internal routes hidden.
+ *
+ * @remarks
+ * This is pure data — no generation logic lives in webafx.
+ * The actual OpenAPI spec generation happens in `@blendsdk/codegen`.
+ *
+ * @example
+ * ```typescript
+ * this.route()
+ *   .get('/')
+ *   .openapi({
+ *     summary: 'List products',
+ *     tags: ['products'],
+ *     responses: [
+ *       { statusCode: 200, description: 'Paginated product list' }
+ *     ]
+ *   })
+ *   .validate(productQuerySchema)
+ *   .handle(this.listProducts);
+ * ```
+ */
+export interface OpenAPIRouteMetadata {
+    /** Short summary of the route (appears in path listing) */
+    summary?: string;
+    /** Detailed description of the route (supports markdown) */
+    description?: string;
+    /** Tags for grouping routes in the spec (e.g., 'products', 'auth') */
+    tags?: string[];
+    /** Unique operation identifier for the route */
+    operationId?: string;
+    /** Mark route as deprecated in the spec */
+    deprecated?: boolean;
+    /**
+     * Path parameter schemas for parameters not covered by the validation schema.
+     * Each key is the parameter name (matching the Express `:param` in the path).
+     */
+    pathParams?: Record<string, {
+        schema: ZodType;
+        description?: string;
+    }>;
+    /** Response definitions describing possible responses from this endpoint */
+    responses?: OpenAPIResponseDefinition[];
+}
+/**
+ * Route handler function signature.
+ * Handles HTTP requests and can be async or sync.
+ */
+export type RouteHandler = (req: Request, res: Response, next: NextFunction) => Promise<void> | void;
+/**
+ * Authorization function that determines if a user can access a route.
+ *
+ * @template T - User type
+ * @param req - Express request object
+ * @param user - Authenticated user object
+ * @returns True if authorized, false otherwise
+ */
+export type AuthorizeFunction<T = any> = (req: Request, user: T) => boolean | Promise<boolean>;
+/**
+ * Complete route definition with all configuration.
+ */
+export interface RouteDefinition {
+    method: HttpMethod;
+    path: string;
+    handler: RouteHandler;
+    validation?: ZodType;
+    secure?: boolean;
+    authorize?: AuthorizeFunction;
+    middleware?: RequestHandler[];
+    /**
+     * Optional OpenAPI metadata for this route.
+     * Routes without this field are excluded from generated OpenAPI specs.
+     * This is the opt-in mechanism for API documentation.
+     */
+    openapi?: OpenAPIRouteMetadata;
+}
+/**
+ * Fluent API builder for defining HTTP routes.
+ * Provides a chainable interface for configuring route properties.
+ *
+ * @remarks
+ * Use this class to build route definitions with method chaining:
+ * - HTTP method (get, post, put, patch, delete)
+ * - Path
+ * - Authentication (secure)
+ * - Authorization (authorize)
+ * - Validation (validate)
+ * - Handler function (handle)
+ */
+export declare class RouteBuilder {
+    private definition;
+    /**
+     * Defines a GET route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    get(path: string): this;
+    /**
+     * Defines a POST route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    post(path: string): this;
+    /**
+     * Defines a PUT route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    put(path: string): this;
+    /**
+     * Defines a PATCH route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    patch(path: string): this;
+    /**
+     * Defines a DELETE route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    delete(path: string): this;
+    /**
+     * Marks the route as requiring authentication.
+     * Authenticated user must be present in request.services.
+     *
+     * @returns This builder instance for method chaining
+     */
+    secure(): this;
+    /**
+     * Adds authorization check to the route.
+     * Called after authentication if route is secure.
+     *
+     * @param authorizeFn - Function that determines if user is authorized
+     * @returns This builder instance for method chaining
+     */
+    authorize(authorizeFn: AuthorizeFunction): this;
+    /**
+     * Adds middleware to this route. Can be called multiple times.
+     * Middleware runs in order before the route handler.
+     *
+     * @param fn - Middleware function to add
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * this.route()
+     *   .get('/admin')
+     *   .middleware(authMiddleware)
+     *   .middleware(rateLimitMiddleware)
+     *   .handle(fn);
+     * ```
+     */
+    middleware(fn: RequestHandler): this;
+    /**
+     * Attaches OpenAPI metadata to this route.
+     *
+     * Only routes with this metadata will appear in generated OpenAPI specs.
+     * Routes without `.openapi()` are excluded, keeping internal routes hidden.
+     *
+     * @param meta - OpenAPI metadata for this route
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * this.route()
+     *   .get('/:id')
+     *   .openapi({
+     *     summary: 'Get product by ID',
+     *     tags: ['products'],
+     *     pathParams: { id: { schema: z.coerce.number(), description: 'Product ID' } },
+     *     responses: [
+     *       { statusCode: 200, description: 'Product details' },
+     *       { statusCode: 404, description: 'Product not found' }
+     *     ]
+     *   })
+     *   .handle(this.getProduct);
+     * ```
+     */
+    openapi(meta: OpenAPIRouteMetadata): this;
+    /**
+     * Adds request validation using a Zod schema.
+     * Validates merged params, query, and body data.
+     *
+     * @param schema - Zod validation schema
+     * @returns This builder instance for method chaining
+     * @template TSchema - Zod schema type
+     */
+    validate<TSchema extends ZodType>(schema: TSchema): RouteBuilder;
+    /**
+     * Sets the route handler function and finalizes the route definition.
+     * This must be the last method called in the chain.
+     *
+     * @param handler - Route handler function
+     * @returns Complete route definition
+     * @throws {Error} If handler is not a function
+     * @throws {Error} If method or path not set
+     */
+    handle(handler: RouteHandler): RouteDefinition;
+}
+//# sourceMappingURL=route-builder.d.ts.map

package/dist/webafx/application/route-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-builder.d.ts","sourceRoot":"","sources":["../../src/application/route-builder.ts"],"names":[],"mappings":"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"}

package/dist/webafx/application/route-builder.js

@@ -0,0 +1,182 @@
+/**
+ * Fluent API builder for defining HTTP routes.
+ * Provides a chainable interface for configuring route properties.
+ *
+ * @remarks
+ * Use this class to build route definitions with method chaining:
+ * - HTTP method (get, post, put, patch, delete)
+ * - Path
+ * - Authentication (secure)
+ * - Authorization (authorize)
+ * - Validation (validate)
+ * - Handler function (handle)
+ */
+export class RouteBuilder {
+    definition = {};
+    /**
+     * Defines a GET route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    get(path) {
+        this.definition.method = 'get';
+        this.definition.path = path;
+        return this;
+    }
+    /**
+     * Defines a POST route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    post(path) {
+        this.definition.method = 'post';
+        this.definition.path = path;
+        return this;
+    }
+    /**
+     * Defines a PUT route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    put(path) {
+        this.definition.method = 'put';
+        this.definition.path = path;
+        return this;
+    }
+    /**
+     * Defines a PATCH route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    patch(path) {
+        this.definition.method = 'patch';
+        this.definition.path = path;
+        return this;
+    }
+    /**
+     * Defines a DELETE route.
+     *
+     * @param path - URL path for the route
+     * @returns This builder instance for method chaining
+     */
+    delete(path) {
+        this.definition.method = 'delete';
+        this.definition.path = path;
+        return this;
+    }
+    /**
+     * Marks the route as requiring authentication.
+     * Authenticated user must be present in request.services.
+     *
+     * @returns This builder instance for method chaining
+     */
+    secure() {
+        this.definition.secure = true;
+        return this;
+    }
+    /**
+     * Adds authorization check to the route.
+     * Called after authentication if route is secure.
+     *
+     * @param authorizeFn - Function that determines if user is authorized
+     * @returns This builder instance for method chaining
+     */
+    authorize(authorizeFn) {
+        this.definition.authorize = authorizeFn;
+        return this;
+    }
+    /**
+     * Adds middleware to this route. Can be called multiple times.
+     * Middleware runs in order before the route handler.
+     *
+     * @param fn - Middleware function to add
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * this.route()
+     *   .get('/admin')
+     *   .middleware(authMiddleware)
+     *   .middleware(rateLimitMiddleware)
+     *   .handle(fn);
+     * ```
+     */
+    middleware(fn) {
+        if (!this.definition.middleware) {
+            this.definition.middleware = [];
+        }
+        this.definition.middleware.push(fn);
+        return this;
+    }
+    /**
+     * Attaches OpenAPI metadata to this route.
+     *
+     * Only routes with this metadata will appear in generated OpenAPI specs.
+     * Routes without `.openapi()` are excluded, keeping internal routes hidden.
+     *
+     * @param meta - OpenAPI metadata for this route
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * this.route()
+     *   .get('/:id')
+     *   .openapi({
+     *     summary: 'Get product by ID',
+     *     tags: ['products'],
+     *     pathParams: { id: { schema: z.coerce.number(), description: 'Product ID' } },
+     *     responses: [
+     *       { statusCode: 200, description: 'Product details' },
+     *       { statusCode: 404, description: 'Product not found' }
+     *     ]
+     *   })
+     *   .handle(this.getProduct);
+     * ```
+     */
+    openapi(meta) {
+        this.definition.openapi = meta;
+        return this;
+    }
+    /**
+     * Adds request validation using a Zod schema.
+     * Validates merged params, query, and body data.
+     *
+     * @param schema - Zod validation schema
+     * @returns This builder instance for method chaining
+     * @template TSchema - Zod schema type
+     */
+    validate(schema) {
+        this.definition.validation = schema;
+        return this;
+    }
+    /**
+     * Sets the route handler function and finalizes the route definition.
+     * This must be the last method called in the chain.
+     *
+     * @param handler - Route handler function
+     * @returns Complete route definition
+     * @throws {Error} If handler is not a function
+     * @throws {Error} If method or path not set
+     */
+    handle(handler) {
+        // Validate that handler is a function
+        if (typeof handler !== 'function') {
+            throw new Error(`Route handler must be a function, received: ${typeof handler}. ` +
+                `Path: ${this.definition.path || 'unknown'}, Method: ${this.definition.method || 'unknown'}`);
+        }
+        // Validate that required route properties are set
+        if (!this.definition.method) {
+            throw new Error('Route method must be set before calling handle()');
+        }
+        if (!this.definition.path) {
+            throw new Error('Route path must be set before calling handle()');
+        }
+        this.definition.handler = handler;
+        return this.definition;
+    }
+}
+//# sourceMappingURL=route-builder.js.map

package/dist/webafx/application/route-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-builder.js","sourceRoot":"","sources":["../../src/application/route-builder.ts"],"names":[],"mappings":"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"}