@bloomneo/appkit 1.2.9

package/dist/error/error.js

@@ -0,0 +1,200 @@
+/**
+ * Core error class with semantic HTTP status codes and middleware
+ * @module @bloomneo/appkit/error
+ * @file src/error/error.ts
+ *
+ * @llm-rule WHEN: Building apps that need semantic HTTP error handling
+ * @llm-rule AVOID: Using directly - always get instance via errorClass.get()
+ * @llm-rule NOTE: Provides semantic error creation (badRequest, unauthorized) and Express middleware
+ */
+/**
+ * Error class with semantic HTTP status codes and middleware functionality
+ */
+export class ErrorClass {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Creates a 400 Bad Request error
+     * @llm-rule WHEN: Client sends invalid input data (missing fields, wrong format)
+     * @llm-rule AVOID: Using for server-side validation errors - use conflict() instead
+     * @llm-rule NOTE: EXAMPLES: missing email, invalid JSON, malformed request body
+     * @llm-rule NOTE: PATTERN: if (!req.body.email) throw error.badRequest('Email required');
+     */
+    badRequest(message) {
+        const error = new Error(message || this.config.messages.badRequest);
+        error.statusCode = 400;
+        error.type = 'BAD_REQUEST';
+        return error;
+    }
+    /**
+     * Creates a 401 Unauthorized error
+     * @llm-rule WHEN: Authentication is required but missing or invalid
+     * @llm-rule AVOID: Using for permission issues - use forbidden() for access control
+     * @llm-rule NOTE: EXAMPLES: missing token, invalid token, expired session
+     * @llm-rule NOTE: PATTERN: if (!token) throw error.unauthorized('Token required');
+     */
+    unauthorized(message) {
+        const error = new Error(message || this.config.messages.unauthorized);
+        error.statusCode = 401;
+        error.type = 'UNAUTHORIZED';
+        return error;
+    }
+    /**
+     * Creates a 403 Forbidden error
+     * @llm-rule WHEN: User is authenticated but lacks permission for the action
+     * @llm-rule AVOID: Using for authentication issues - use unauthorized() instead
+     * @llm-rule NOTE: EXAMPLES: insufficient role, blocked user, admin-only endpoint
+     * @llm-rule NOTE: PATTERN: if (!user.isAdmin) throw error.forbidden('Admin access required');
+     */
+    forbidden(message) {
+        const error = new Error(message || this.config.messages.forbidden);
+        error.statusCode = 403;
+        error.type = 'FORBIDDEN';
+        return error;
+    }
+    /**
+     * Creates a 404 Not Found error
+     * @llm-rule WHEN: Requested resource does not exist
+     * @llm-rule AVOID: Using for business logic failures - use conflict() instead
+     * @llm-rule NOTE: EXAMPLES: user not found, post not found, missing file
+     * @llm-rule NOTE: PATTERN: if (!user) throw error.notFound('User not found');
+     */
+    notFound(message) {
+        const error = new Error(message || this.config.messages.notFound);
+        error.statusCode = 404;
+        error.type = 'NOT_FOUND';
+        return error;
+    }
+    /**
+     * Creates a 409 Conflict error
+     * @llm-rule WHEN: Business logic conflicts or resource already exists
+     * @llm-rule AVOID: Using for validation errors - use badRequest() for input validation
+     * @llm-rule NOTE: EXAMPLES: email already exists, duplicate username, state conflicts
+     * @llm-rule NOTE: PATTERN: if (existingUser) throw error.conflict('Email already registered');
+     */
+    conflict(message) {
+        const error = new Error(message || this.config.messages.conflict);
+        error.statusCode = 409;
+        error.type = 'CONFLICT';
+        return error;
+    }
+    /**
+     * Creates a 500 Server Error
+     * @llm-rule WHEN: Internal server failures like database errors, external API failures
+     * @llm-rule AVOID: Using for business logic issues - use appropriate 4xx errors instead
+     * @llm-rule NOTE: EXAMPLES: database connection failure, external API timeout, file system errors
+     * @llm-rule NOTE: PATTERN: catch (dbError) { throw error.serverError('Database unavailable'); }
+     */
+    serverError(message) {
+        const error = new Error(message || this.config.messages.serverError);
+        error.statusCode = 500;
+        error.type = 'SERVER_ERROR';
+        return error;
+    }
+    /**
+     * Creates a custom error with any status code
+     * @llm-rule WHEN: Need custom HTTP status codes not covered by semantic methods
+     * @llm-rule AVOID: Using for standard HTTP codes - use semantic methods instead
+     * @llm-rule NOTE: EXAMPLES: 429 rate limit, 503 service unavailable, 418 teapot
+     * @llm-rule NOTE: PATTERN: error.createError(429, 'Rate limit exceeded', 'RATE_LIMIT');
+     */
+    createError(statusCode, message, type) {
+        const error = new Error(message);
+        error.statusCode = statusCode;
+        error.type = type || `HTTP_${statusCode}`;
+        return error;
+    }
+    /**
+     * Creates production-ready Express error handling middleware
+     * @llm-rule WHEN: Setting up Express app error handling - use as last middleware
+     * @llm-rule AVOID: Using multiple error handlers - this should be the final middleware
+     * @llm-rule NOTE: MIDDLEWARE SETUP: app.use(error.handleErrors()); // Must be LAST
+     * @llm-rule NOTE: AUTO-FEATURES: dev vs prod responses, stack trace hiding, error logging
+     */
+    handleErrors(options = {}) {
+        // Use instance config as defaults, allow options to override
+        const showStack = options.showStack !== undefined
+            ? options.showStack
+            : this.config.middleware.showStack;
+        const logErrors = options.logErrors !== undefined
+            ? options.logErrors
+            : this.config.middleware.logErrors;
+        return (error, req, res, next) => {
+            // Log errors if enabled
+            if (logErrors) {
+                console.error('Error:', error.message);
+                if (showStack && error.stack) {
+                    console.error('Stack:', error.stack);
+                }
+            }
+            // Determine status code
+            const statusCode = error.statusCode || 500;
+            // Determine error type
+            const errorType = error.type || (statusCode >= 500 ? 'SERVER_ERROR' : 'CLIENT_ERROR');
+            // Build response object
+            const response = {
+                error: errorType,
+                message: error.message || 'An error occurred',
+            };
+            // Include stack trace in development
+            if (showStack && error.stack) {
+                response.stack = error.stack;
+            }
+            // Send error response
+            res.status(statusCode).json(response);
+        };
+    }
+    /**
+     * Wraps async route handlers to catch errors automatically
+     * @llm-rule WHEN: Creating async Express route handlers that might throw errors
+     * @llm-rule AVOID: Manual try/catch in every route - this handles it automatically
+     * @llm-rule NOTE: ASYNC PATTERN: app.post('/route', error.asyncRoute(async (req, res) => {...}));
+     * @llm-rule NOTE: ERROR FLOW: thrown errors → automatically caught → sent to handleErrors middleware
+     */
+    asyncRoute(fn) {
+        return (req, res, next) => {
+            Promise.resolve(fn(req, res, next)).catch(next);
+        };
+    }
+    /**
+     * Checks if error is a 4xx client error
+     * @llm-rule WHEN: Need to categorize errors for logging or metrics
+     * @llm-rule AVOID: Manual status code checking - this handles the logic
+     * @llm-rule NOTE: CLIENT ERRORS: 400-499 status codes (user's fault)
+     */
+    isClientError(error) {
+        return error.statusCode >= 400 && error.statusCode < 500;
+    }
+    /**
+     * Checks if error is a 5xx server error
+     * @llm-rule WHEN: Need to categorize errors for monitoring or alerting
+     * @llm-rule AVOID: Manual status code checking - this handles the logic
+     * @llm-rule NOTE: SERVER ERRORS: 500-599 status codes (server's fault)
+     */
+    isServerError(error) {
+        return error.statusCode >= 500;
+    }
+    /**
+     * Gets current environment detection info
+     * @llm-rule WHEN: Need to check current environment configuration
+     * @llm-rule AVOID: Direct process.env access - this provides parsed config
+     */
+    getEnvironmentInfo() {
+        return {
+            isDevelopment: this.config.environment.isDevelopment,
+            isProduction: this.config.environment.isProduction,
+            nodeEnv: this.config.environment.nodeEnv,
+        };
+    }
+    /**
+     * Gets current error configuration
+     * @llm-rule WHEN: Debugging error setup or inspecting current settings
+     * @llm-rule AVOID: Accessing config directly - this provides clean interface
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+//# sourceMappingURL=error.js.map

package/dist/error/error.js.map

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

package/dist/error/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Ultra-simple semantic error handling that just works
+ * @module @bloomneo/appkit/error
+ * @file src/error/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need semantic HTTP error handling
+ * @llm-rule AVOID: Complex error setups with multiple libraries - this handles everything in one API
+ * @llm-rule NOTE: Provides semantic error creation (badRequest, unauthorized) and Express middleware
+ * @llm-rule NOTE: Common pattern - errorClass.get() → throw error.badRequest() → app.use(error.handleErrors())
+ * @llm-rule NOTE: COMPLETE SETUP: const error = errorClass.get(); app.use(error.handleErrors()); // Done!
+ */
+import { ErrorClass } from './error.js';
+import { type ErrorConfig } from './defaults.js';
+export interface AppError extends Error {
+    statusCode: number;
+    type: string;
+}
+export interface ExpressRequest {
+    [key: string]: any;
+}
+export interface ExpressResponse {
+    status: (code: number) => ExpressResponse;
+    json: (data: any) => void;
+}
+export interface ExpressNextFunction {
+    (error?: any): void;
+}
+export type ExpressErrorHandler = (error: AppError, req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+export type AsyncRouteHandler = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => Promise<any>;
+export interface ErrorHandlerOptions {
+    showStack?: boolean;
+    logErrors?: boolean;
+}
+/**
+ * Get error instance - the only function you need to learn
+ * Environment variables parsed once for performance
+ * @llm-rule WHEN: Starting any error operation - this is your main entry point
+ * @llm-rule AVOID: Calling new ErrorClass() directly - always use this function
+ * @llm-rule NOTE: USAGE FLOW: get() → create errors → setup middleware → done
+ * @llm-rule NOTE: TYPICAL SETUP: const error = errorClass.get(); app.use(error.handleErrors());
+ */
+declare function get(overrides?: Partial<ErrorConfig>): ErrorClass;
+/**
+ * Reset global instance (useful for testing or config changes)
+ * @llm-rule WHEN: Testing error logic with different configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ * @llm-rule NOTE: TEST PATTERN: const error = errorClass.reset({showStack: false}); // Clean slate
+ */
+declare function reset(newConfig?: Partial<ErrorConfig>): ErrorClass;
+/**
+ * Clear global instance cache (for testing)
+ * @llm-rule WHEN: Testing error configurations or between test suites
+ * @llm-rule AVOID: Using in production - only for tests
+ */
+declare function clearCache(): void;
+/**
+ * Single error export with semantic methods and Express integration
+ * @llm-rule NOTE: TWO USAGE PATTERNS: errorClass.get().badRequest() OR errorClass.badRequest() (shortcuts)
+ * @llm-rule NOTE: MIDDLEWARE PATTERN: app.use(error.handleErrors()); // Global error handling
+ */
+export declare const errorClass: {
+    readonly get: typeof get;
+    readonly reset: typeof reset;
+    readonly clearCache: typeof clearCache;
+    /**
+     * Creates 400 Bad Request error
+     * @llm-rule WHEN: Client input validation failures (missing/invalid data)
+     * @llm-rule NOTE: EXAMPLES: missing email, invalid JSON, malformed request
+     * @llm-rule NOTE: PATTERN: if (!email) throw error.badRequest('Email required');
+     */
+    readonly badRequest: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates 401 Unauthorized error
+     * @llm-rule WHEN: Authentication required but missing or invalid
+     * @llm-rule NOTE: EXAMPLES: missing token, expired session, invalid credentials
+     * @llm-rule NOTE: PATTERN: if (!token) throw error.unauthorized('Login required');
+     */
+    readonly unauthorized: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates 403 Forbidden error
+     * @llm-rule WHEN: User authenticated but lacks permission for action
+     * @llm-rule NOTE: EXAMPLES: insufficient role, admin-only endpoint, blocked user
+     * @llm-rule NOTE: PATTERN: if (!user.isAdmin) throw error.forbidden('Admin only');
+     */
+    readonly forbidden: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates 404 Not Found error
+     * @llm-rule WHEN: Requested resource does not exist in database/system
+     * @llm-rule NOTE: EXAMPLES: user not found, post not found, file missing
+     * @llm-rule NOTE: PATTERN: if (!user) throw error.notFound('User not found');
+     */
+    readonly notFound: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates 409 Conflict error
+     * @llm-rule WHEN: Business logic conflicts or duplicate resources
+     * @llm-rule NOTE: EXAMPLES: email already exists, username taken, state conflicts
+     * @llm-rule NOTE: PATTERN: if (existingUser) throw error.conflict('Email exists');
+     */
+    readonly conflict: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates 500 Server Error
+     * @llm-rule WHEN: Internal failures like database/API errors
+     * @llm-rule NOTE: EXAMPLES: database down, external API timeout, file system errors
+     * @llm-rule NOTE: PATTERN: catch (dbError) { throw error.serverError('DB unavailable'); }
+     */
+    readonly serverError: (message?: string) => import("./error.js").AppError;
+    /**
+     * Creates custom error with any status code
+     * @llm-rule WHEN: Need non-standard HTTP status codes
+     * @llm-rule NOTE: EXAMPLES: 429 rate limit, 503 maintenance, 418 teapot
+     * @llm-rule NOTE: PATTERN: error.createError(429, 'Rate limited', 'RATE_LIMIT');
+     */
+    readonly createError: (statusCode: number, message: string, type?: string) => import("./error.js").AppError;
+    /**
+     * Express error handling middleware - handles all thrown errors
+     * @llm-rule WHEN: Setting up Express app - use as LAST middleware
+     * @llm-rule AVOID: Multiple error handlers - this should be the final one
+     * @llm-rule NOTE: EXPRESS SETUP: app.use(error.handleErrors()); // Must be last!
+     * @llm-rule NOTE: AUTO-FEATURES: dev vs prod responses, stack hiding, error logging
+     */
+    readonly handleErrors: (options?: ErrorHandlerOptions) => import("./error.js").ExpressErrorHandler;
+    /**
+     * Async route wrapper - automatically catches thrown errors
+     * @llm-rule WHEN: Creating async Express routes that might throw errors
+     * @llm-rule AVOID: Manual try/catch in routes - this handles it automatically
+     * @llm-rule NOTE: ASYNC PATTERN: app.post('/api', error.asyncRoute(async (req, res) => {...}));
+     * @llm-rule NOTE: ERROR FLOW: throw error → asyncRoute catches → handleErrors processes
+     */
+    readonly asyncRoute: (fn: AsyncRouteHandler) => (req: import("./error.js").ExpressRequest, res: import("./error.js").ExpressResponse, next: import("./error.js").ExpressNextFunction) => void;
+    /**
+     * Checks if error is 4xx client error
+     * @llm-rule WHEN: Categorizing errors for logging/metrics
+     * @llm-rule NOTE: CLIENT ERRORS: 400-499 (user's fault)
+     */
+    readonly isClientError: (err: AppError) => boolean;
+    /**
+     * Checks if error is 5xx server error
+     * @llm-rule WHEN: Categorizing errors for monitoring/alerting
+     * @llm-rule NOTE: SERVER ERRORS: 500-599 (server's fault)
+     */
+    readonly isServerError: (err: AppError) => boolean;
+};
+export type { ErrorConfig } from './defaults.js';
+export { ErrorClass } from './error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/error/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEnE,MAAM,WAAW,QAAS,SAAQ,KAAK;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAC;IAC1C,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,mBAAmB,GAAG,CAChC,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,mBAAmB,KACtB,IAAI,CAAC;AAEV,MAAM,MAAM,iBAAiB,GAAG,CAC9B,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC,GAAG,CAAC,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD;;;;;;;GAOG;AACH,iBAAS,GAAG,CAAC,SAAS,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,UAAU,CAS7D;AAED;;;;;GAKG;AACH,iBAAS,KAAK,CAAC,SAAS,GAAE,OAAO,CAAC,WAAW,CAAM,GAAG,UAAU,CAK/D;AAED;;;;GAIG;AACH,iBAAS,UAAU,IAAI,IAAI,CAE1B;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;IASrB;;;;;OAKG;oCACoB,MAAM;IAE7B;;;;;OAKG;sCACsB,MAAM;IAE/B;;;;;OAKG;mCACmB,MAAM;IAE5B;;;;;OAKG;kCACkB,MAAM;IAE3B;;;;;OAKG;kCACkB,MAAM;IAE3B;;;;;OAKG;qCACqB,MAAM;IAE9B;;;;;OAKG;uCACuB,MAAM,WAAW,MAAM,SAAS,MAAM;IAGhE;;;;;;OAMG;sCACsB,mBAAmB;IAE5C;;;;;;OAMG;8BACc,iBAAiB;IAElC;;;;OAIG;kCACkB,QAAQ;IAE7B;;;;OAIG;kCACkB,QAAQ;CACrB,CAAC;AAGX,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/error/index.js

@@ -0,0 +1,145 @@
+/**
+ * Ultra-simple semantic error handling that just works
+ * @module @bloomneo/appkit/error
+ * @file src/error/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need semantic HTTP error handling
+ * @llm-rule AVOID: Complex error setups with multiple libraries - this handles everything in one API
+ * @llm-rule NOTE: Provides semantic error creation (badRequest, unauthorized) and Express middleware
+ * @llm-rule NOTE: Common pattern - errorClass.get() → throw error.badRequest() → app.use(error.handleErrors())
+ * @llm-rule NOTE: COMPLETE SETUP: const error = errorClass.get(); app.use(error.handleErrors()); // Done!
+ */
+import { ErrorClass } from './error.js';
+import { getSmartDefaults } from './defaults.js';
+// Global error instance for performance
+let globalError = null;
+/**
+ * Get error instance - the only function you need to learn
+ * Environment variables parsed once for performance
+ * @llm-rule WHEN: Starting any error operation - this is your main entry point
+ * @llm-rule AVOID: Calling new ErrorClass() directly - always use this function
+ * @llm-rule NOTE: USAGE FLOW: get() → create errors → setup middleware → done
+ * @llm-rule NOTE: TYPICAL SETUP: const error = errorClass.get(); app.use(error.handleErrors());
+ */
+function get(overrides = {}) {
+    // Lazy initialization - parse environment once
+    if (!globalError) {
+        const defaults = getSmartDefaults();
+        const config = { ...defaults, ...overrides };
+        globalError = new ErrorClass(config);
+    }
+    return globalError;
+}
+/**
+ * Reset global instance (useful for testing or config changes)
+ * @llm-rule WHEN: Testing error logic with different configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ * @llm-rule NOTE: TEST PATTERN: const error = errorClass.reset({showStack: false}); // Clean slate
+ */
+function reset(newConfig = {}) {
+    const defaults = getSmartDefaults();
+    const config = { ...defaults, ...newConfig };
+    globalError = new ErrorClass(config);
+    return globalError;
+}
+/**
+ * Clear global instance cache (for testing)
+ * @llm-rule WHEN: Testing error configurations or between test suites
+ * @llm-rule AVOID: Using in production - only for tests
+ */
+function clearCache() {
+    globalError = null;
+}
+/**
+ * Single error export with semantic methods and Express integration
+ * @llm-rule NOTE: TWO USAGE PATTERNS: errorClass.get().badRequest() OR errorClass.badRequest() (shortcuts)
+ * @llm-rule NOTE: MIDDLEWARE PATTERN: app.use(error.handleErrors()); // Global error handling
+ */
+export const errorClass = {
+    // Core method
+    get,
+    // Utility methods
+    reset,
+    clearCache,
+    // Error creation shortcuts - automatically call get()
+    /**
+     * Creates 400 Bad Request error
+     * @llm-rule WHEN: Client input validation failures (missing/invalid data)
+     * @llm-rule NOTE: EXAMPLES: missing email, invalid JSON, malformed request
+     * @llm-rule NOTE: PATTERN: if (!email) throw error.badRequest('Email required');
+     */
+    badRequest: (message) => get().badRequest(message),
+    /**
+     * Creates 401 Unauthorized error
+     * @llm-rule WHEN: Authentication required but missing or invalid
+     * @llm-rule NOTE: EXAMPLES: missing token, expired session, invalid credentials
+     * @llm-rule NOTE: PATTERN: if (!token) throw error.unauthorized('Login required');
+     */
+    unauthorized: (message) => get().unauthorized(message),
+    /**
+     * Creates 403 Forbidden error
+     * @llm-rule WHEN: User authenticated but lacks permission for action
+     * @llm-rule NOTE: EXAMPLES: insufficient role, admin-only endpoint, blocked user
+     * @llm-rule NOTE: PATTERN: if (!user.isAdmin) throw error.forbidden('Admin only');
+     */
+    forbidden: (message) => get().forbidden(message),
+    /**
+     * Creates 404 Not Found error
+     * @llm-rule WHEN: Requested resource does not exist in database/system
+     * @llm-rule NOTE: EXAMPLES: user not found, post not found, file missing
+     * @llm-rule NOTE: PATTERN: if (!user) throw error.notFound('User not found');
+     */
+    notFound: (message) => get().notFound(message),
+    /**
+     * Creates 409 Conflict error
+     * @llm-rule WHEN: Business logic conflicts or duplicate resources
+     * @llm-rule NOTE: EXAMPLES: email already exists, username taken, state conflicts
+     * @llm-rule NOTE: PATTERN: if (existingUser) throw error.conflict('Email exists');
+     */
+    conflict: (message) => get().conflict(message),
+    /**
+     * Creates 500 Server Error
+     * @llm-rule WHEN: Internal failures like database/API errors
+     * @llm-rule NOTE: EXAMPLES: database down, external API timeout, file system errors
+     * @llm-rule NOTE: PATTERN: catch (dbError) { throw error.serverError('DB unavailable'); }
+     */
+    serverError: (message) => get().serverError(message),
+    /**
+     * Creates custom error with any status code
+     * @llm-rule WHEN: Need non-standard HTTP status codes
+     * @llm-rule NOTE: EXAMPLES: 429 rate limit, 503 maintenance, 418 teapot
+     * @llm-rule NOTE: PATTERN: error.createError(429, 'Rate limited', 'RATE_LIMIT');
+     */
+    createError: (statusCode, message, type) => get().createError(statusCode, message, type),
+    // Middleware and utility shortcuts
+    /**
+     * Express error handling middleware - handles all thrown errors
+     * @llm-rule WHEN: Setting up Express app - use as LAST middleware
+     * @llm-rule AVOID: Multiple error handlers - this should be the final one
+     * @llm-rule NOTE: EXPRESS SETUP: app.use(error.handleErrors()); // Must be last!
+     * @llm-rule NOTE: AUTO-FEATURES: dev vs prod responses, stack hiding, error logging
+     */
+    handleErrors: (options) => get().handleErrors(options),
+    /**
+     * Async route wrapper - automatically catches thrown errors
+     * @llm-rule WHEN: Creating async Express routes that might throw errors
+     * @llm-rule AVOID: Manual try/catch in routes - this handles it automatically
+     * @llm-rule NOTE: ASYNC PATTERN: app.post('/api', error.asyncRoute(async (req, res) => {...}));
+     * @llm-rule NOTE: ERROR FLOW: throw error → asyncRoute catches → handleErrors processes
+     */
+    asyncRoute: (fn) => get().asyncRoute(fn),
+    /**
+     * Checks if error is 4xx client error
+     * @llm-rule WHEN: Categorizing errors for logging/metrics
+     * @llm-rule NOTE: CLIENT ERRORS: 400-499 (user's fault)
+     */
+    isClientError: (err) => get().isClientError(err),
+    /**
+     * Checks if error is 5xx server error
+     * @llm-rule WHEN: Categorizing errors for monitoring/alerting
+     * @llm-rule NOTE: SERVER ERRORS: 500-599 (server's fault)
+     */
+    isServerError: (err) => get().isServerError(err),
+};
+export { ErrorClass } from './error.js';
+//# sourceMappingURL=index.js.map

package/dist/error/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/error/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAoB,MAAM,eAAe,CAAC;AAsCnE,wCAAwC;AACxC,IAAI,WAAW,GAAsB,IAAI,CAAC;AAE1C;;;;;;;GAOG;AACH,SAAS,GAAG,CAAC,YAAkC,EAAE;IAC/C,+CAA+C;IAC/C,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;QACpC,MAAM,MAAM,GAAgB,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC;QAC1D,WAAW,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,SAAS,KAAK,CAAC,YAAkC,EAAE;IACjD,MAAM,QAAQ,GAAG,gBAAgB,EAAE,CAAC;IACpC,MAAM,MAAM,GAAgB,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC;IAC1D,WAAW,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU;IACjB,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,cAAc;IACd,GAAG;IAEH,kBAAkB;IAClB,KAAK;IACL,UAAU;IAEV,sDAAsD;IACtD;;;;;OAKG;IACH,UAAU,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;IAE3D;;;;;OAKG;IACH,YAAY,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;IAE/D;;;;;OAKG;IACH,SAAS,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC;IAEzD;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;IAEvD;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;IAEvD;;;;;OAKG;IACH,WAAW,EAAE,CAAC,OAAgB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC;IAE7D;;;;;OAKG;IACH,WAAW,EAAE,CAAC,UAAkB,EAAE,OAAe,EAAE,IAAa,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC;IAEjH,mCAAmC;IACnC;;;;;;OAMG;IACH,YAAY,EAAE,CAAC,OAA6B,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC;IAE5E;;;;;;OAMG;IACH,UAAU,EAAE,CAAC,EAAqB,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;IAE3D;;;;OAIG;IACH,aAAa,EAAE,CAAC,GAAa,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC;IAE1D;;;;OAIG;IACH,aAAa,EAAE,CAAC,GAAa,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC;CAClD,CAAC;AAIX,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/event/defaults.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Smart defaults and environment validation for event system with auto-strategy detection
+ * @module @bloomneo/appkit/event
+ * @file src/event/defaults.ts
+ *
+ * @llm-rule WHEN: App startup - need to configure event system and connection strategy
+ * @llm-rule AVOID: Calling multiple times - expensive environment parsing, use lazy loading in get()
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ * @llm-rule NOTE: Auto-detects Redis vs Memory based on REDIS_URL environment variable
+ */
+export interface RedisConfig {
+    url: string;
+    password?: string;
+    maxRetries: number;
+    retryDelay: number;
+    connectTimeout: number;
+    commandTimeout: number;
+    keyPrefix: string;
+}
+export interface MemoryConfig {
+    maxListeners: number;
+    maxHistory: number;
+    checkInterval: number;
+    enableGC: boolean;
+}
+export interface EventConfig {
+    strategy: 'redis' | 'memory';
+    namespace: string;
+    redis?: RedisConfig;
+    memory?: MemoryConfig;
+    history: {
+        enabled: boolean;
+        maxSize: number;
+    };
+    environment: {
+        isDevelopment: boolean;
+        isProduction: boolean;
+        isTest: boolean;
+        nodeEnv: string;
+    };
+}
+/**
+ * Gets smart defaults using environment variables with auto-strategy detection
+ * @llm-rule WHEN: App startup to get production-ready event configuration
+ * @llm-rule AVOID: Calling repeatedly - expensive validation, cache the result
+ * @llm-rule NOTE: Auto-detects strategy: REDIS_URL → Redis, no REDIS_URL → Memory
+ */
+export declare function getSmartDefaults(): EventConfig;
+/**
+ * Gets event configuration summary for debugging and health checks
+ * @llm-rule WHEN: Debugging event configuration or building health check endpoints
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+export declare function getConfigSummary(): {
+    strategy: string;
+    namespace: string;
+    historyEnabled: boolean;
+    redisConnected: boolean;
+    environment: string;
+};
+/**
+ * Validates that required event configuration is present for production
+ * @llm-rule WHEN: App startup validation for production deployments
+ * @llm-rule AVOID: Skipping validation - missing event config causes runtime issues
+ */
+export declare function validateProductionRequirements(): void;
+/**
+ * Validates startup configuration and throws detailed errors
+ * @llm-rule WHEN: App startup to ensure event configuration is valid before starting
+ * @llm-rule AVOID: Skipping validation - catches config issues early
+ * @llm-rule NOTE: Comprehensive validation for production readiness
+ */
+export declare function validateStartupConfiguration(): {
+    strategy: string;
+    warnings: string[];
+    errors: string[];
+    ready: boolean;
+};
+/**
+ * Performs comprehensive event system health check
+ * @llm-rule WHEN: Health check endpoints or monitoring systems
+ * @llm-rule AVOID: Running in critical path - this is for monitoring only
+ * @llm-rule NOTE: Returns detailed health status without exposing sensitive data
+ */
+export declare function performHealthCheck(): {
+    status: 'healthy' | 'warning' | 'error';
+    strategy: string;
+    configured: boolean;
+    issues: string[];
+    ready: boolean;
+    timestamp: string;
+};
+/**
+ * Gets optimal event configuration for different environments
+ * @llm-rule WHEN: Setting up environment-specific event behavior
+ * @llm-rule AVOID: Manual environment handling - this provides optimal defaults
+ */
+export declare function getEnvironmentOptimizedConfig(): EventConfig;
+/**
+ * Checks if Redis is available and properly configured
+ * @llm-rule WHEN: Conditional logic based on event capabilities
+ * @llm-rule AVOID: Complex event detection - just use events normally, strategy handles it
+ */
+export declare function hasRedis(): boolean;
+/**
+ * Gets recommended configuration for microservices
+ * @llm-rule WHEN: Setting up events for microservices architecture
+ * @llm-rule AVOID: Default config for microservices - needs specific tuning
+ */
+export declare function getMicroservicesConfig(): Partial<EventConfig>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/event/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/event/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,WAAW,EAAE;QACX,aAAa,EAAE,OAAO,CAAC;QACvB,YAAY,EAAE,OAAO,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAmD9C;AAuJD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAUA;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAmBrD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,IAAI;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB,CA0DA;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAsCA;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,IAAI,WAAW,CA4B3D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAGlC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAAC,WAAW,CAAC,CAgB7D"}