@designofadecade/server 4.0.0

package/dist/client/ApiClient.js

@@ -0,0 +1,289 @@
+/**
+ * API Client for making HTTP requests
+ * @class ApiClient
+ * @example
+ * const client = new ApiClient('https://api.example.com');
+ * client.setAuthToken('your-token');
+ * const result = await client.get('/users', { page: 1, limit: 10 });
+ */
+export default class ApiClient {
+    #baseUrl = '';
+    #authToken = null;
+    #authType = 'Bearer';
+    #defaultHeaders = {};
+    #timeout = 30000; // 30 seconds default
+    #requestInterceptors = [];
+    #responseInterceptors = [];
+    #retryAttempts = 0;
+    #retryDelay = 1000;
+    /**
+     * Create an API Client
+     * @param {string} baseUrl - Base URL for all requests
+     * @param {Object} options - Configuration options
+     * @param {number} options.timeout - Request timeout in milliseconds (default: 30000)
+     * @param {number} options.retryAttempts - Number of retry attempts for failed requests (default: 0)
+     * @param {number} options.retryDelay - Delay between retries in milliseconds (default: 1000)
+     */
+    constructor(baseUrl, options = {}) {
+        this.#baseUrl = baseUrl;
+        this.#timeout = options.timeout || 30000;
+        this.#retryAttempts = options.retryAttempts || 0;
+        this.#retryDelay = options.retryDelay || 1000;
+    }
+    /**
+     * Set authentication token
+     * @param {string} token - Authentication token
+     * @param {string} type - Token type (default: 'Bearer')
+     */
+    setAuthToken(token, type = 'Bearer') {
+        this.#authToken = token;
+        this.#authType = type;
+    }
+    /**
+     * Clear authentication token
+     */
+    clearAuthToken() {
+        this.#authToken = null;
+    }
+    /**
+     * Set default headers for all requests
+     * @param {Object} headers - Headers object
+     */
+    setDefaultHeaders(headers) {
+        this.#defaultHeaders = { ...headers };
+    }
+    /**
+     * Add a request interceptor
+     * @param {Function} interceptor - Function that receives and modifies request config
+     */
+    addRequestInterceptor(interceptor) {
+        this.#requestInterceptors.push(interceptor);
+    }
+    /**
+     * Add a response interceptor
+     * @param {Function} interceptor - Function that receives and modifies response
+     */
+    addResponseInterceptor(interceptor) {
+        this.#responseInterceptors.push(interceptor);
+    }
+    /**
+     * Build query string from params object
+     * @param {Object} params - Query parameters
+     * @returns {string} Query string
+     */
+    #buildQueryString(params) {
+        if (!params || Object.keys(params).length === 0)
+            return '';
+        const queryString = new URLSearchParams(params).toString();
+        return `?${queryString}`;
+    }
+    /**
+     * Get headers for request
+     * @param {Object} customHeaders - Custom headers for this request
+     * @returns {Object} Combined headers
+     */
+    #getHeaders(customHeaders = {}) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            ...this.#defaultHeaders,
+            ...customHeaders
+        };
+        if (this.#authToken) {
+            headers['Authorization'] = `${this.#authType} ${this.#authToken}`;
+        }
+        return headers;
+    }
+    /**
+     * Execute request with timeout and retry logic
+     * @param {Function} fetchFn - Function that performs the fetch
+     * @param {AbortController} controller - Abort controller for timeout
+     * @param {number} attempt - Current attempt number
+     * @returns {Promise<Response>}
+     */
+    async #executeWithRetry(fetchFn, controller, attempt = 0) {
+        let timeoutId;
+        try {
+            timeoutId = setTimeout(() => controller.abort(), this.#timeout);
+            const response = await fetchFn();
+            return response;
+        }
+        catch (error) {
+            if (attempt < this.#retryAttempts && error.name !== 'AbortError') {
+                await new Promise(resolve => setTimeout(resolve, this.#retryDelay));
+                return this.#executeWithRetry(fetchFn, controller, attempt + 1);
+            }
+            throw error;
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    /**
+     * Process response through interceptors
+     * @param {Object} response - Response object
+     * @returns {Promise<Object>} Processed response
+     */
+    async #processResponse(response) {
+        let processedResponse = response;
+        for (const interceptor of this.#responseInterceptors) {
+            processedResponse = await interceptor(processedResponse);
+        }
+        return processedResponse;
+    }
+    /**
+     * Make HTTP request
+     * @param {string} url - Request URL
+     * @param {Object} config - Request configuration
+     * @returns {Promise<Object>} Response object
+     */
+    async #request(url, config) {
+        const controller = new AbortController();
+        try {
+            // Apply request interceptors
+            let requestConfig = { ...config, signal: controller.signal };
+            for (const interceptor of this.#requestInterceptors) {
+                requestConfig = await interceptor(requestConfig);
+            }
+            const fetchFn = () => fetch(`${this.#baseUrl}${url}`, requestConfig);
+            const response = await this.#executeWithRetry(fetchFn, controller);
+            let responseData = null;
+            const contentType = response.headers.get('content-type');
+            if (contentType && contentType.includes('application/json')) {
+                try {
+                    responseData = await response.json();
+                }
+                catch (e) {
+                    // Failed to parse JSON
+                }
+            }
+            else if (contentType && contentType.includes('text/')) {
+                try {
+                    responseData = await response.text();
+                }
+                catch (e) {
+                    // Failed to parse text
+                }
+            }
+            const result = {
+                ok: response.ok,
+                status: response.status,
+                statusText: response.statusText,
+                data: responseData,
+                error: !response.ok ? response.statusText : null,
+                headers: Object.fromEntries(response.headers.entries())
+            };
+            return await this.#processResponse(result);
+        }
+        catch (error) {
+            const errorResponse = {
+                ok: false,
+                status: null,
+                statusText: error.name === 'AbortError' ? 'Request Timeout' : 'Network Error',
+                data: null,
+                error: error.name === 'AbortError' ? 'Request timed out' : error.message,
+                headers: {}
+            };
+            return await this.#processResponse(errorResponse);
+        }
+    }
+    /**
+     * Make GET request
+     * @param {string} url - Request URL
+     * @param {Object} params - Query parameters (optional)
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    async get(url, params = null, options = {}) {
+        const queryString = params ? this.#buildQueryString(params) : '';
+        return this.#request(`${url}${queryString}`, {
+            method: 'GET',
+            headers: this.#getHeaders(options.headers),
+            signal: options.signal
+        });
+    }
+    /**
+     * Make POST request
+     * @param {string} url - Request URL
+     * @param {Object|FormData} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    async post(url, data, options = {}) {
+        const isFormData = data instanceof FormData;
+        const headers = this.#getHeaders(options.headers);
+        // Remove Content-Type for FormData (browser sets it with boundary)
+        if (isFormData) {
+            delete headers['Content-Type'];
+        }
+        return this.#request(url, {
+            method: 'POST',
+            headers: headers,
+            body: isFormData ? data : JSON.stringify(data),
+            signal: options.signal
+        });
+    }
+    /**
+     * Make PUT request
+     * @param {string} url - Request URL
+     * @param {Object|FormData} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    async put(url, data, options = {}) {
+        const isFormData = data instanceof FormData;
+        const headers = this.#getHeaders(options.headers);
+        // Remove Content-Type for FormData (browser sets it with boundary)
+        if (isFormData) {
+            delete headers['Content-Type'];
+        }
+        return this.#request(url, {
+            method: 'PUT',
+            headers: headers,
+            body: isFormData ? data : JSON.stringify(data),
+            signal: options.signal
+        });
+    }
+    /**
+     * Make DELETE request
+     * @param {string} url - Request URL
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    async delete(url, options = {}) {
+        const config = {
+            method: 'DELETE',
+            headers: this.#getHeaders(options.headers),
+            signal: options.signal
+        };
+        return this.#request(url, config);
+    }
+    /**
+     * Make PATCH request
+     * @param {string} url - Request URL
+     * @param {Object} data - Request body
+     * @param {Object} options - Request options
+     * @param {Object} options.headers - Custom headers for this request
+     * @param {AbortSignal} options.signal - Abort signal for cancellation
+     * @returns {Promise<Object>} Response object
+     */
+    async patch(url, data, options = {}) {
+        return this.#request(url, {
+            method: 'PATCH',
+            headers: this.#getHeaders(options.headers),
+            body: JSON.stringify(data),
+            signal: options.signal
+        });
+    }
+}
+//# sourceMappingURL=ApiClient.js.map

package/dist/client/ApiClient.js.map

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

package/dist/context/Context.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Abstract Context class for application context management
+ *
+ * This abstract class must be extended to provide type-safe context
+ * throughout the application. It enforces a pattern where context
+ * structure is explicitly defined through extension.
+ *
+ * @abstract
+ * @class Context
+ *
+ * @example
+ * // Define your application context
+ * class AppContext extends Context {
+ *     constructor(
+ *         public database: DatabaseConnection,
+ *         public config: AppConfig,
+ *         public services: Services
+ *     ) {
+ *         super();
+ *     }
+ * }
+ *
+ * // Use in router initialization
+ * const context = new AppContext(db, config, services);
+ * const router = new Router({
+ *     context,
+ *     initRoutes: [UserRoutes, PostRoutes]
+ * });
+ *
+ * @example
+ * // Access context in route handlers
+ * class UserRoutes extends Routes {
+ *     constructor(router: Router, context?: AppContext) {
+ *         super(router, context);
+ *
+ *         this.addRoute('/users', 'GET', async () => {
+ *             const users = await (this.context as AppContext).database.getUsers();
+ *             return { status: 200, body: users };
+ *         });
+ *     }
+ * }
+ */
+export default abstract class Context {
+    /**
+     * Protected constructor ensures this class cannot be instantiated directly
+     * and must be extended by a concrete implementation
+     */
+    protected constructor();
+    /**
+     * Optional method to validate context state
+     * Override in derived classes to implement custom validation
+     *
+     * @returns {boolean} True if context is valid
+     */
+    protected validate(): boolean;
+    /**
+     * Optional method to initialize context
+     * Override in derived classes to implement custom initialization logic
+     *
+     * @returns {Promise<void>}
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * Optional method to cleanup context resources
+     * Override in derived classes to implement custom cleanup logic
+     *
+     * @returns {Promise<void>}
+     */
+    protected dispose(): Promise<void>;
+}
+//# sourceMappingURL=Context.d.ts.map

package/dist/context/Context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.d.ts","sourceRoot":"","sources":["../../src/context/Context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,OAAO;IACnC;;;OAGG;IACH,SAAS;IAMT;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,IAAI,OAAO;IAI7B;;;;;OAKG;cACa,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3C;;;;;OAKG;cACa,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGzC"}

package/dist/context/Context.js

@@ -0,0 +1,81 @@
+/**
+ * Abstract Context class for application context management
+ *
+ * This abstract class must be extended to provide type-safe context
+ * throughout the application. It enforces a pattern where context
+ * structure is explicitly defined through extension.
+ *
+ * @abstract
+ * @class Context
+ *
+ * @example
+ * // Define your application context
+ * class AppContext extends Context {
+ *     constructor(
+ *         public database: DatabaseConnection,
+ *         public config: AppConfig,
+ *         public services: Services
+ *     ) {
+ *         super();
+ *     }
+ * }
+ *
+ * // Use in router initialization
+ * const context = new AppContext(db, config, services);
+ * const router = new Router({
+ *     context,
+ *     initRoutes: [UserRoutes, PostRoutes]
+ * });
+ *
+ * @example
+ * // Access context in route handlers
+ * class UserRoutes extends Routes {
+ *     constructor(router: Router, context?: AppContext) {
+ *         super(router, context);
+ *
+ *         this.addRoute('/users', 'GET', async () => {
+ *             const users = await (this.context as AppContext).database.getUsers();
+ *             return { status: 200, body: users };
+ *         });
+ *     }
+ * }
+ */
+export default class Context {
+    /**
+     * Protected constructor ensures this class cannot be instantiated directly
+     * and must be extended by a concrete implementation
+     */
+    constructor() {
+        if (new.target === Context) {
+            throw new TypeError('Cannot construct Context instances directly. Context must be extended.');
+        }
+    }
+    /**
+     * Optional method to validate context state
+     * Override in derived classes to implement custom validation
+     *
+     * @returns {boolean} True if context is valid
+     */
+    validate() {
+        return true;
+    }
+    /**
+     * Optional method to initialize context
+     * Override in derived classes to implement custom initialization logic
+     *
+     * @returns {Promise<void>}
+     */
+    async initialize() {
+        // Override in derived classes
+    }
+    /**
+     * Optional method to cleanup context resources
+     * Override in derived classes to implement custom cleanup logic
+     *
+     * @returns {Promise<void>}
+     */
+    async dispose() {
+        // Override in derived classes
+    }
+}
+//# sourceMappingURL=Context.js.map

package/dist/context/Context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Context.js","sourceRoot":"","sources":["../../src/context/Context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,OAAO,OAAgB,OAAO;IACnC;;;OAGG;IACH;QACE,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;YAC3B,MAAM,IAAI,SAAS,CAAC,wEAAwE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACO,QAAQ;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,UAAU;QACxB,8BAA8B;IAChC,CAAC;IAED;;;;;OAKG;IACO,KAAK,CAAC,OAAO;QACrB,8BAA8B;IAChC,CAAC;CACF"}

package/dist/docs/OpenApiGenerator.d.ts

@@ -0,0 +1,135 @@
+/**
+ * OpenAPI/Swagger Documentation Generator
+ *
+ * This utility helps generate OpenAPI 3.0 documentation for your API routes.
+ *
+ * Installation:
+ * ```bash
+ * npm install --save-dev swagger-jsdoc swagger-ui-dist
+ * ```
+ *
+ * Usage:
+ * ```typescript
+ * import { OpenApiGenerator } from '@designofadecade/server';
+ *
+ * const generator = new OpenApiGenerator({
+ *   title: 'My API',
+ *   version: '1.0.0',
+ *   description: 'My API description'
+ * });
+ *
+ * // Add route documentation
+ * generator.addRoute({
+ *   path: '/api/users',
+ *   method: 'GET',
+ *   summary: 'Get all users',
+ *   responses: {
+ *     200: { description: 'Success', schema: { type: 'array' } }
+ *   }
+ * });
+ *
+ * // Generate OpenAPI spec
+ * const spec = generator.generate();
+ * ```
+ */
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        email?: string;
+        url?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+export interface OpenApiServer {
+    url: string;
+    description?: string;
+}
+export interface OpenApiParameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    description?: string;
+    required?: boolean;
+    schema: {
+        type: string;
+        [key: string]: unknown;
+    };
+}
+export interface OpenApiResponse {
+    description: string;
+    content?: {
+        [mediaType: string]: {
+            schema: unknown;
+        };
+    };
+}
+export interface OpenApiRouteConfig {
+    path: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        description?: string;
+        required?: boolean;
+        content: {
+            [mediaType: string]: {
+                schema: unknown;
+            };
+        };
+    };
+    responses: {
+        [statusCode: string]: OpenApiResponse;
+    };
+    security?: Array<Record<string, string[]>>;
+}
+export interface OpenApiConfig {
+    info: OpenApiInfo;
+    servers?: OpenApiServer[];
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+    };
+}
+export declare class OpenApiGenerator {
+    private config;
+    private routes;
+    constructor(config: OpenApiConfig);
+    /**
+     * Add a route to the OpenAPI documentation
+     */
+    addRoute(route: OpenApiRouteConfig): void;
+    /**
+     * Add multiple routes at once
+     */
+    addRoutes(routes: OpenApiRouteConfig[]): void;
+    /**
+     * Generate the complete OpenAPI specification
+     */
+    generate(): object;
+    /**
+     * Generate OpenAPI spec as JSON string
+     */
+    toJSON(): string;
+    /**
+     * Generate OpenAPI spec as YAML string (basic implementation)
+     */
+    toYAML(): string;
+    private objectToYaml;
+}
+/**
+ * Helper function to create Swagger UI HTML page
+ */
+export declare function generateSwaggerUI(specUrl: string | object): string;
+//# sourceMappingURL=OpenApiGenerator.d.ts.map

package/dist/docs/OpenApiGenerator.d.ts.map

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