xypriss 9.11.13 → 9.12.0

package/dist/src/types/mod/core.d.ts

@@ -0,0 +1,390 @@
+/**
+ * @fileoverview Core type definitions for XyPriss integration
+ *
+ * This module contains fundamental types and utilities used throughout
+ * the XyPriss integration system.
+ *
+ * @version 4.5.11
+ * @author XyPrissJS Team
+ * @since 2025-01-06
+ */
+import { Request, Response, NextFunction } from "../types";
+/**
+ * Deep partial utility type that makes all properties optional recursively.
+ *
+ * This utility type is used throughout the configuration system to allow
+ * partial configuration objects while maintaining type safety.
+ *
+ * @template T - The type to make deeply partial
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   server: {
+ *     port: number;
+ *     host: string;
+ *   };
+ * }
+ *
+ * type PartialConfig = DeepPartial<Config>;
+ * // Result: { server?: { port?: number; host?: string; } }
+ * ```
+ */
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends infer U ? U extends object ? U extends readonly any[] ? U extends readonly (infer V)[] ? readonly DeepPartial<V>[] : U : U extends Function ? U : DeepPartial<U> : U : never;
+};
+/**
+ * Validation result interface for request validation operations.
+ *
+ * Used by validation middleware and request handlers to provide
+ * structured validation feedback.
+ *
+ * @interface ValidationResult
+ *
+ * @example
+ * ```typescript
+ * const result: ValidationResult = {
+ *   valid: false,
+ *   errors: ['Email is required', 'Password too short'],
+ *   data: { email: '', password: '123' }
+ * };
+ * ```
+ */
+export interface ValidationResult {
+    /** Whether the validation passed */
+    valid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+    /** The validated/sanitized data */
+    data: any;
+}
+/**
+ * User context information for authenticated requests.
+ *
+ * Contains user identity, permissions, and metadata for
+ * authorization and audit purposes.
+ *
+ * @interface UserContext
+ *
+ * @example
+ * ```typescript
+ * const user: UserContext = {
+ *   id: 'user-123',
+ *   roles: ['admin', 'user'],
+ *   permissions: ['read:users', 'write:posts'],
+ *   metadata: { department: 'engineering', level: 'senior' }
+ * };
+ * ```
+ */
+export interface UserContext {
+    /** Unique user identifier */
+    id: string;
+    /** Array of user roles */
+    roles: string[];
+    /** Array of specific permissions */
+    permissions: string[];
+    /** Additional user metadata */
+    metadata: Record<string, any>;
+}
+/**
+ * Session data structure for user sessions.
+ *
+ * Contains session information including expiration and
+ * custom session data.
+ *
+ * @interface SessionData
+ *
+ * @example
+ * ```typescript
+ * const session: SessionData = {
+ *   id: 'session-abc123',
+ *   userId: 'user-123',
+ *   data: { theme: 'dark', language: 'en' },
+ *   expires: new Date(Date.now() + 3600000) // 1 hour
+ * };
+ * ```
+ */
+export interface SessionData {
+    /** Unique session identifier */
+    id: string;
+    /** Associated user ID (optional) */
+    userId?: string;
+    /** Custom session data */
+    data: Record<string, any>;
+    /** Session expiration date */
+    expires: Date;
+}
+/**
+ * Pagination information for paginated responses.
+ *
+ * Used by API endpoints that return paginated data to provide
+ * navigation information to clients.
+ *
+ * @interface PaginationInfo
+ *
+ * @example
+ * ```typescript
+ * const pagination: PaginationInfo = {
+ *   page: 2,
+ *   limit: 20,
+ *   total: 150,
+ *   pages: 8
+ * };
+ * ```
+ */
+export interface PaginationInfo {
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    limit: number;
+    /** Total number of items */
+    total: number;
+    /** Total number of pages */
+    pages: number;
+}
+/**
+ * Alert configuration for monitoring and notifications.
+ *
+ * Defines conditions and actions for system alerts based on
+ * performance metrics and thresholds.
+ *
+ * @interface AlertConfig
+ *
+ * @example
+ * ```typescript
+ * const alert: AlertConfig = {
+ *   metric: 'memory_usage',
+ *   threshold: 0.85,
+ *   action: 'webhook',
+ *   target: 'https://alerts.example.com/webhook',
+ *   cooldown: 300000 // 5 minutes
+ * };
+ * ```
+ */
+export interface AlertConfig {
+    /** The metric to monitor */
+    metric: string;
+    /** Threshold value that triggers the alert */
+    threshold: number;
+    /** Action to take when alert is triggered */
+    action: "log" | "email" | "webhook" | "custom";
+    /** Target for the action (email, webhook URL, etc.) */
+    target?: string;
+    /** Cooldown period in milliseconds before alert can trigger again */
+    cooldown?: number;
+}
+/**
+ * Configuration for internal response manipulation.
+ *
+/**
+ * Rules for masking or replacing fields in responses.
+ *
+ * @interface ResponseManipulationRule
+ */
+export interface ResponseManipulationRule {
+    /** Field name (dot notation) or RegExp pattern for matching keys */
+    field?: string | RegExp;
+    /** RegExp pattern for matching field values */
+    valuePattern?: RegExp;
+    /** Mask string (e.g., "****") or replacement value */
+    replacement?: any;
+    /** Number of characters to preserve (at the beginning) for string masking */
+    preserve?: number;
+}
+/**
+ * Configuration for internal response manipulation.
+ *
+ * Allows masking or replacing specific fields in JSON responses
+ * before they are sent to the client.
+ *
+ * @interface ResponseManipulationConfig
+ */
+export interface ResponseManipulationConfig {
+    /** Enable response manipulation */
+    enabled?: boolean;
+    /** Rules for masking or replacing fields */
+    rules?: ResponseManipulationRule[];
+    /** Maximum recursion depth for nested objects (default: 10) */
+    maxDepth?: number;
+}
+/**
+ * Enhanced XyPriss request interface with additional utilities.
+ *
+ * Extends the standard XyPriss Request with caching, security,
+ * performance, and validation utilities.
+ *
+ * @interface EnhancedRequest
+ * @extends Request
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
+ *   // Use enhanced features
+ *   const cached = await req.cache.get('users');
+ *   const encrypted = await req.security.encrypt(sensitiveData);
+ *   req.performance.start();
+ *
+ *   // Validation
+ *   const validation = req.validation.query(userQuerySchema);
+ *   if (!validation.valid) {
+ *     return res.error('Invalid query parameters');
+ *   }
+ * });
+ * ```
+ */
+export interface EnhancedRequest extends Request {
+    /** Cache utilities for request-level caching */
+    cache: {
+        /** Get cached value by key */
+        get: (key: string) => Promise<any>;
+        /** Set cached value with optional TTL */
+        set: (key: string, value: any, ttl?: number) => Promise<void>;
+        /** Delete cached value */
+        del: (key: string) => Promise<void>;
+        /** Tag cache entries for bulk invalidation */
+        tags: (tags: string[]) => Promise<void>;
+    };
+    /** Security utilities for encryption and authentication */
+    security: {
+        /** Encrypt data using configured algorithm */
+        encrypt: (data: any) => Promise<string>;
+        /** Decrypt data using configured algorithm */
+        decrypt: (data: string) => Promise<any>;
+        /** Hash data using secure algorithm */
+        hash: (data: string) => string;
+        /** Verify data against hash */
+        verify: (data: string, hash: string) => boolean;
+        /** Generate secure token */
+        generateToken: () => string;
+        /** Session encryption key */
+        sessionKey: string;
+    };
+    /** Performance monitoring utilities */
+    performance: {
+        /** Start performance timer */
+        start: () => void;
+        /** End performance timer and return duration */
+        end: () => number;
+        /** Mark a performance point */
+        mark: (name: string) => void;
+        /** Measure time between marks */
+        measure: (name: string, start: string, end: string) => number;
+    };
+    /** Request validation utilities */
+    validation: {
+        /** Validate request body against schema */
+        body: (schema: any) => ValidationResult;
+        /** Validate query parameters against schema */
+        query: (schema: any) => ValidationResult;
+        /** Validate route parameters against schema */
+        params: (schema: any) => ValidationResult;
+    };
+    /** User context (available after authentication) */
+    user?: UserContext;
+    /** Session data (available when sessions are enabled) */
+    session?: SessionData;
+}
+/**
+ * Enhanced XyPriss response interface with additional utilities.
+ *
+ * Extends the standard XyPriss Response with caching, security,
+ * performance, and convenience methods.
+ *
+ * @interface EnhancedResponse
+ * @extends Response
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/users', async (req: EnhancedRequest, res: EnhancedResponse) => {
+ *   const users = await getUsersFromDB();
+ *
+ *   // Use enhanced response methods
+ *   res.cache.set(3600, ['users']); // Cache for 1 hour with 'users' tag
+ *   res.performance.timing('db_query', 150);
+ *   res.success(users, 'Users retrieved successfully');
+ * });
+ * ```
+ */
+export interface EnhancedResponse extends Response {
+    /** Cache utilities for response caching */
+    cache: {
+        /** Set cache headers and TTL for response */
+        set: (ttl?: number, tags?: string[]) => void;
+        /** Invalidate cache entries by tags */
+        invalidate: (tags: string[]) => Promise<void>;
+    };
+    /** Security utilities for response encryption */
+    security: {
+        /** Encrypt response data */
+        encrypt: (data: any) => EnhancedResponse;
+        /** Sign response data */
+        sign: (data: any) => EnhancedResponse;
+    };
+    /** Performance utilities for response metrics */
+    performance: {
+        /** Record timing metric */
+        timing: (name: string, value: number) => void;
+        /** Record custom metric */
+        metric: (name: string, value: number) => void;
+    };
+    /** Send successful response with optional message */
+    success: (data?: any, message?: string) => void;
+    /** Send error response with message and status code */
+    error: (error: string | Error, code?: number) => void;
+    /** Send paginated response with pagination info */
+    paginated: (data: any[], pagination: PaginationInfo) => void;
+}
+/**
+ * Route handler function type with enhanced request/response.
+ *
+ * @template T - Return type of the handler
+ *
+ * @example
+ * ```typescript
+ * const getUserHandler: RouteHandler = async (req, res, next) => {
+ *   try {
+ *     const user = await getUserById(req.params.id);
+ *     res.success(user);
+ *   } catch (error) {
+ *     next(error);
+ *   }
+ * };
+ * ```
+ */
+export type RouteHandler = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction) => Promise<any> | any;
+/**
+ * Middleware function type with enhanced request/response.
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware: MiddlewareFunction = async (req, res, next) => {
+ *   const token = req.headers.authorization;
+ *   if (!token) {
+ *     return res.error('Authorization required', 401);
+ *   }
+ *
+ *   try {
+ *     req.user = await verifyToken(token);
+ *     next();
+ *   } catch (error) {
+ *     res.error('Invalid token', 401);
+ *   }
+ * };
+ * ```
+ */
+export type MiddlewareFunction = (req: EnhancedRequest, res: EnhancedResponse, next: NextFunction) => Promise<void> | void;
+/**
+ * Strict type utility to enforce exact types and prevent excess properties.
+ *
+ * @template T - The base type to enforce
+ * @template U - The actual type provided
+ *
+ * @example
+ * ```typescript
+ * function create<T extends Base>(obj: Strict<Base, T>) { ... }
+ * ```
+ */
+export type Strict<T, U> = T & {
+    [K in keyof U]: K extends keyof T ? U[K] : never;
+};
+//# sourceMappingURL=core.d.ts.map

package/dist/src/types/mod/core.d.ts.map

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

package/dist/src/types/mod/core.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=core.js.map

package/dist/src/types/mod/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../src/types/mod/core.ts"],"names":[],"mappings":""}