@bloomneo/appkit 1.2.9

package/dist/cache/strategies/redis.js

@@ -0,0 +1,318 @@
+/**
+ * Redis cache strategy with automatic connection management and retry logic
+ * @module @bloomneo/appkit/cache
+ * @file src/cache/strategies/redis.ts
+ *
+ * @llm-rule WHEN: App has REDIS_URL environment variable for distributed caching
+ * @llm-rule AVOID: Manual Redis setup - this handles connection, retry, and serialization automatically
+ * @llm-rule NOTE: Auto-reconnects on failure, handles JSON serialization, production-ready
+ */
+/**
+ * Redis cache strategy with enterprise-grade reliability
+ */
+export class RedisStrategy {
+    config;
+    client = null;
+    connected = false;
+    connectionPromise = null;
+    /**
+     * Creates Redis strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Cache initialization with Redis URL detected
+     * @llm-rule AVOID: Manual Redis configuration - environment detection handles this
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Connects to Redis with automatic retry and connection pooling
+     * @llm-rule WHEN: Cache initialization or reconnection after failure
+     * @llm-rule AVOID: Manual connection management - this handles all Redis complexity
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        // Prevent multiple connection attempts
+        if (this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        this.connectionPromise = this.establishConnection();
+        await this.connectionPromise;
+        this.connectionPromise = null;
+    }
+    /**
+     * Establishes Redis connection with retry logic
+     */
+    async establishConnection() {
+        try {
+            // Dynamic import for Redis client
+            const { createClient } = await import('redis');
+            const redisConfig = this.config.redis;
+            // Create Redis client with comprehensive configuration
+            this.client = createClient({
+                url: redisConfig.url,
+                password: redisConfig.password,
+                socket: {
+                    connectTimeout: redisConfig.connectTimeout,
+                    reconnectStrategy: (retries) => {
+                        if (retries >= redisConfig.maxRetries) {
+                            console.error(`[AppKit] Redis max retries (${redisConfig.maxRetries}) exceeded`);
+                            return new Error('Redis connection failed');
+                        }
+                        const delay = Math.min(redisConfig.retryDelay * Math.pow(2, retries), 10000);
+                        console.warn(`[AppKit] Redis reconnecting in ${delay}ms (attempt ${retries + 1})`);
+                        return delay;
+                    },
+                },
+                commandsQueueMaxLength: 1000,
+                // Set global command timeout via client options
+                isolationPoolOptions: {
+                    min: 1,
+                    max: 10,
+                },
+            });
+            // Set up event handlers
+            this.setupEventHandlers();
+            // Connect to Redis
+            await this.client.connect();
+            this.connected = true;
+            if (this.config.environment.isDevelopment) {
+                console.log(`✅ [AppKit] Redis connected to ${this.maskUrl(redisConfig.url)}`);
+            }
+        }
+        catch (error) {
+            this.connected = false;
+            this.client = null;
+            throw new Error(`Redis connection failed: ${error.message}`);
+        }
+    }
+    /**
+     * Sets up Redis event handlers for connection management
+     */
+    setupEventHandlers() {
+        if (!this.client)
+            return;
+        this.client.on('error', (error) => {
+            console.error('[AppKit] Redis error:', error.message);
+            this.connected = false;
+        });
+        this.client.on('connect', () => {
+            if (this.config.environment.isDevelopment) {
+                console.log('🔄 [AppKit] Redis connecting...');
+            }
+        });
+        this.client.on('ready', () => {
+            this.connected = true;
+            if (this.config.environment.isDevelopment) {
+                console.log('✅ [AppKit] Redis ready');
+            }
+        });
+        this.client.on('reconnecting', () => {
+            this.connected = false;
+            if (this.config.environment.isDevelopment) {
+                console.log('🔄 [AppKit] Redis reconnecting...');
+            }
+        });
+        this.client.on('end', () => {
+            this.connected = false;
+            if (this.config.environment.isDevelopment) {
+                console.log('👋 [AppKit] Redis connection ended');
+            }
+        });
+    }
+    /**
+     * Disconnects from Redis gracefully
+     * @llm-rule WHEN: App shutdown or cache cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents data loss
+     */
+    async disconnect() {
+        if (!this.client || !this.connected)
+            return;
+        try {
+            await this.client.quit();
+            this.connected = false;
+            this.client = null;
+        }
+        catch (error) {
+            console.error('[AppKit] Redis disconnect error:', error.message);
+            // Force close if graceful quit fails
+            if (this.client) {
+                this.client.disconnect();
+                this.client = null;
+            }
+        }
+    }
+    /**
+     * Gets value from Redis with automatic JSON deserialization
+     * @llm-rule WHEN: Retrieving cached data from distributed Redis cache
+     * @llm-rule AVOID: Manual Redis commands - this handles serialization automatically
+     */
+    async get(key) {
+        await this.ensureConnected();
+        try {
+            const value = await this.client.get(key);
+            if (value === null) {
+                return null; // Key not found or expired
+            }
+            // Deserialize JSON value
+            return this.deserialize(value);
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis get error for key "${key}":`, error.message);
+            return null; // Graceful degradation
+        }
+    }
+    /**
+     * Sets value in Redis with TTL and automatic JSON serialization
+     * @llm-rule WHEN: Storing data in distributed Redis cache with expiration
+     * @llm-rule AVOID: Manual Redis commands - this handles serialization and TTL automatically
+     */
+    async set(key, value, ttl) {
+        await this.ensureConnected();
+        try {
+            // Serialize value to JSON
+            const serialized = this.serialize(value);
+            // Set with TTL (Redis EX option expects seconds)
+            const result = await this.client.setEx(key, ttl, serialized);
+            return result === 'OK';
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis set error for key "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Deletes key from Redis
+     * @llm-rule WHEN: Cache invalidation or removing specific cached data
+     * @llm-rule AVOID: Manual key management - this handles Redis delete operations
+     */
+    async delete(key) {
+        await this.ensureConnected();
+        try {
+            const result = await this.client.del(key);
+            return result === 1; // Redis returns number of keys deleted
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis delete error for key "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Clears all keys matching pattern (usually namespace-based)
+     * @llm-rule WHEN: Namespace-based cache invalidation
+     * @llm-rule AVOID: Using FLUSHDB - this only clears specific namespace keys
+     */
+    async clear() {
+        // Note: This is handled by the main cache class using keys() + deleteMany()
+        // We don't implement it here to avoid accidental full cache clearing
+        throw new Error('Clear operation should be handled by cache class using keys() + deleteMany()');
+    }
+    /**
+     * Checks if key exists in Redis
+     * @llm-rule WHEN: Checking cache key existence without retrieving value
+     * @llm-rule AVOID: Using get() then checking null - this is more efficient
+     */
+    async has(key) {
+        await this.ensureConnected();
+        try {
+            const result = await this.client.exists(key);
+            return result === 1;
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis has error for key "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Gets all keys matching pattern (for namespace operations)
+     * @llm-rule WHEN: Finding all keys in namespace for bulk operations
+     * @llm-rule AVOID: Using KEYS in production with large datasets - use SCAN instead
+     */
+    async keys(pattern = '*') {
+        await this.ensureConnected();
+        try {
+            // Use SCAN instead of KEYS for production safety
+            const keys = [];
+            let cursor = 0;
+            do {
+                const result = await this.client.scan(cursor, {
+                    MATCH: pattern,
+                    COUNT: 1000, // Scan in batches of 1000
+                });
+                cursor = result.cursor;
+                keys.push(...result.keys);
+            } while (cursor !== 0);
+            return keys;
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis keys error for pattern "${pattern}":`, error.message);
+            return [];
+        }
+    }
+    /**
+     * Deletes multiple keys efficiently
+     * @llm-rule WHEN: Bulk deletion operations like namespace clearing
+     * @llm-rule AVOID: Individual delete calls - batch operations are much faster
+     */
+    async deleteMany(keys) {
+        if (keys.length === 0)
+            return 0;
+        await this.ensureConnected();
+        try {
+            // Redis DEL command accepts multiple keys
+            const result = await this.client.del(keys);
+            return result; // Returns number of keys deleted
+        }
+        catch (error) {
+            console.error(`[AppKit] Redis deleteMany error:`, error.message);
+            return 0;
+        }
+    }
+    // Private helper methods
+    /**
+     * Ensures Redis connection is established
+     */
+    async ensureConnected() {
+        if (!this.connected) {
+            await this.connect();
+        }
+    }
+    /**
+     * Serializes value to JSON string for Redis storage
+     */
+    serialize(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch (error) {
+            throw new Error(`Failed to serialize value: ${error.message}`);
+        }
+    }
+    /**
+     * Deserializes JSON string from Redis
+     */
+    deserialize(value) {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            // If it's not valid JSON, return as string (backward compatibility)
+            return value;
+        }
+    }
+    /**
+     * Masks sensitive parts of Redis URL for logging
+     */
+    maskUrl(url) {
+        try {
+            const parsed = new URL(url);
+            if (parsed.password) {
+                parsed.password = '***';
+            }
+            return parsed.toString();
+        }
+        catch {
+            return 'redis://***';
+        }
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/cache/strategies/redis.js.map

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

package/dist/config/config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Smart configuration management with automatic environment variable parsing
+ * @module @bloomneo/appkit/config
+ * @file src/config/config.ts
+ *
+ * @llm-rule WHEN: Building apps that need configuration from environment variables
+ * @llm-rule AVOID: Manual env parsing or complex config files - this handles it automatically
+ * @llm-rule NOTE: Uses UPPER_SNAKE_CASE convention (DATABASE_HOST → config.get('database.host'))
+ */
+export declare class ConfigClass {
+    private readonly _config;
+    /**
+     * Creates a new, immutable Config instance
+     * @llm-rule WHEN: App startup - need to parse environment variables into structured config
+     * @llm-rule AVOID: Calling directly - always use configClass.get() instead
+     * @llm-rule NOTE: Config is immutable and deeply frozen for safety
+     */
+    constructor(initialConfig?: Record<string, any>);
+    /**
+     * Gets a specific configuration value using dot notation
+     * @llm-rule WHEN: Accessing any config value from environment variables
+     * @llm-rule AVOID: Accessing process.env directly - use this for type safety and defaults
+     * @llm-rule NOTE: Returns typed values (strings, numbers, booleans) automatically
+     */
+    get<T = any>(path: string, defaultValue?: T): T | undefined;
+    /**
+     * Checks if a configuration path exists
+     * @llm-rule WHEN: Need to conditionally enable features based on config presence
+     * @llm-rule AVOID: Using get() !== undefined - this is more explicit and readable
+     */
+    has(path: string): boolean;
+    /**
+     * Returns the entire, immutable configuration object
+     * @llm-rule WHEN: Debugging config or passing entire config to other modules
+     * @llm-rule AVOID: Using in production loops - expensive operation, cache the result
+     */
+    getAll(): Record<string, any>;
+    /**
+     * Gets a required configuration value (throws if missing)
+     * @llm-rule WHEN: App startup validation for critical config values
+     * @llm-rule AVOID: Using in request handlers - expensive error creation
+     * @llm-rule NOTE: Use this for database URLs, API keys, and other critical settings
+     */
+    getRequired<T = any>(path: string): T;
+    /**
+     * Gets multiple configuration values at once
+     * @llm-rule WHEN: Need several related config values for a module
+     * @llm-rule AVOID: Multiple get() calls when you need many values - use this for performance
+     */
+    getMany<T extends Record<string, any>>(paths: {
+        [K in keyof T]: string;
+    }): T;
+    /**
+     * Deep freeze helper for immutability
+     */
+    private deepFreeze;
+    /**
+     * Converts dot notation path to environment variable name
+     */
+    private pathToEnvVar;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAE9C;;;;;OAKG;gBACS,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;IAKnD;;;;;OAKG;IACH,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAmB3D;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;OAIG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAI7B;;;;;OAKG;IACH,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAWrC;;;;OAIG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;KAAE,GAAG,CAAC;IAW5E;;OAEG;IACH,OAAO,CAAC,UAAU;IASlB;;OAEG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/dist/config/config.js

@@ -0,0 +1,107 @@
+/**
+ * Smart configuration management with automatic environment variable parsing
+ * @module @bloomneo/appkit/config
+ * @file src/config/config.ts
+ *
+ * @llm-rule WHEN: Building apps that need configuration from environment variables
+ * @llm-rule AVOID: Manual env parsing or complex config files - this handles it automatically
+ * @llm-rule NOTE: Uses UPPER_SNAKE_CASE convention (DATABASE_HOST → config.get('database.host'))
+ */
+export class ConfigClass {
+    _config;
+    /**
+     * Creates a new, immutable Config instance
+     * @llm-rule WHEN: App startup - need to parse environment variables into structured config
+     * @llm-rule AVOID: Calling directly - always use configClass.get() instead
+     * @llm-rule NOTE: Config is immutable and deeply frozen for safety
+     */
+    constructor(initialConfig = {}) {
+        // Make the config object deeply immutable for safety
+        this._config = Object.freeze(this.deepFreeze(structuredClone(initialConfig)));
+    }
+    /**
+     * Gets a specific configuration value using dot notation
+     * @llm-rule WHEN: Accessing any config value from environment variables
+     * @llm-rule AVOID: Accessing process.env directly - use this for type safety and defaults
+     * @llm-rule NOTE: Returns typed values (strings, numbers, booleans) automatically
+     */
+    get(path, defaultValue) {
+        if (typeof path !== 'string' || !path) {
+            return defaultValue;
+        }
+        const segments = path.split('.');
+        let current = this._config;
+        for (const segment of segments) {
+            if (current && typeof current === 'object' && segment in current) {
+                current = current[segment];
+            }
+            else {
+                return defaultValue;
+            }
+        }
+        return current;
+    }
+    /**
+     * Checks if a configuration path exists
+     * @llm-rule WHEN: Need to conditionally enable features based on config presence
+     * @llm-rule AVOID: Using get() !== undefined - this is more explicit and readable
+     */
+    has(path) {
+        return this.get(path) !== undefined;
+    }
+    /**
+     * Returns the entire, immutable configuration object
+     * @llm-rule WHEN: Debugging config or passing entire config to other modules
+     * @llm-rule AVOID: Using in production loops - expensive operation, cache the result
+     */
+    getAll() {
+        return this._config;
+    }
+    /**
+     * Gets a required configuration value (throws if missing)
+     * @llm-rule WHEN: App startup validation for critical config values
+     * @llm-rule AVOID: Using in request handlers - expensive error creation
+     * @llm-rule NOTE: Use this for database URLs, API keys, and other critical settings
+     */
+    getRequired(path) {
+        const value = this.get(path);
+        if (value === undefined) {
+            throw new Error(`Missing required configuration: "${path}". ` +
+                `Set environment variable: ${this.pathToEnvVar(path)}`);
+        }
+        return value;
+    }
+    /**
+     * Gets multiple configuration values at once
+     * @llm-rule WHEN: Need several related config values for a module
+     * @llm-rule AVOID: Multiple get() calls when you need many values - use this for performance
+     */
+    getMany(paths) {
+        const result = {};
+        for (const [key, path] of Object.entries(paths)) {
+            const value = this.get(path);
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Deep freeze helper for immutability
+     */
+    deepFreeze(obj) {
+        Object.getOwnPropertyNames(obj).forEach((prop) => {
+            if (obj[prop] !== null && (typeof obj[prop] === 'object' || typeof obj[prop] === 'function')) {
+                this.deepFreeze(obj[prop]);
+            }
+        });
+        return Object.freeze(obj);
+    }
+    /**
+     * Converts dot notation path to environment variable name
+     */
+    pathToEnvVar(path) {
+        return path.split('.').join('_').toUpperCase();
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,OAAO,WAAW;IACL,OAAO,CAAsB;IAE9C;;;;;OAKG;IACH,YAAY,gBAAqC,EAAE;QACjD,qDAAqD;QACrD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAU,IAAY,EAAE,YAAgB;QACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YACtC,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,OAAO,GAAQ,IAAI,CAAC,OAAO,CAAC;QAEhC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;gBACjE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QAED,OAAO,OAAY,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC;IACtC,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAU,IAAY;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAI,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,oCAAoC,IAAI,KAAK;gBAC7C,6BAA6B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CACvD,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAgC,KAAiC;QACtE,MAAM,MAAM,GAAG,EAAO,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAc,CAAC,GAAG,KAAK,CAAC;YACjC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,UAAU,CAAC,GAAQ;QACzB,MAAM,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;YAC/C,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC,EAAE,CAAC;gBAC7F,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,IAAY;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;CACF"}

package/dist/config/defaults.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Smart defaults and environment validation for configuration management
+ * @module @bloomneo/appkit/config
+ * @file src/config/defaults.ts
+ *
+ * @llm-rule WHEN: App startup - need to parse UPPER_SNAKE_CASE environment variables
+ * @llm-rule AVOID: Calling multiple times - expensive parsing, use lazy loading in get()
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ */
+export interface ConfigValue {
+    [key: string]: string | number | boolean | ConfigValue;
+}
+export interface AppConfig extends ConfigValue {
+    app: {
+        name: string;
+        environment: string;
+        port?: number;
+        host?: string;
+    };
+    [key: string]: any;
+}
+/**
+ * Builds the entire configuration object from process.env
+ * @llm-rule WHEN: App startup to get production-ready configuration from environment
+ * @llm-rule AVOID: Calling repeatedly - validates environment each time, expensive operation
+ * @llm-rule NOTE: Called once at startup, cached globally for performance
+ * @llm-rule CONVENTION: Only processes non-framework variables for user config
+ * @llm-rule CONVENTION: Variables with VOILA_* and FLUX_* are AppKit internal
+ */
+export declare function buildConfigFromEnv(): AppConfig;
+/**
+ * Validates critical configuration at startup
+ * @llm-rule WHEN: App startup to ensure required config is present
+ * @llm-rule AVOID: Skipping validation - missing config causes runtime errors
+ * @llm-rule NOTE: Add your app-specific required config here
+ */
+export declare function validateConfig(config: AppConfig): void;
+/**
+ * Gets smart defaults with validation
+ * @llm-rule WHEN: App startup to get production-ready configuration
+ * @llm-rule AVOID: Calling repeatedly - expensive validation, cache the result
+ */
+export declare function getSmartDefaults(): AppConfig;
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC;CACxD;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAwKD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,CA6B9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAmBtD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,SAAS,CAI5C"}