hazo_config 1.3.0 → 1.4.0

package/.cursor/rules/general.mdc

@@ -48,4 +48,29 @@ alwaysApply: true
 - When error messages are shown to the user, they should always be logged verbatem in the serverside log file as well
 - pretty print the json output
 - don't import the logger in the client side code
-- whenever there's any actions on the database, or any API calls, please add details of the payload and update as well as the resulsts in the log file to help debug issues.  For API calls, don't save any base64 data as it is too large.
+- whenever there's any actions on the database, or any API calls, please add details of the payload and update as well as the resulsts in the log file to help debug issues.  For API calls, don't save any base64 data as it is too large.
+
+[For Packages ES Module Exports]
+- When creating npm packages that will be consumed by ES module bundlers (Next.js, Vite, etc.), ALL export statements MUST use explicit file paths with .js extensions
+- Directory imports like `export * from './components'` are INVALID in ES modules and will fail at runtime
+- ALWAYS use explicit paths: `export * from './components/index.js'` instead of `export * from './components'`
+- Even though source files are .ts, TypeScript requires .js extensions in import/export paths for ES module output
+- This applies to all export statements in index.ts files and any barrel export files
+
+[For packages: TypeScript Configuration]
+- For package builds (tsconfig.build.json), set moduleResolution to "node16" or "node" (not "bundler") when shipping compiled output
+- Ensure module is set to "ESNext" or "ES2020" for modern ES module output
+- Add "type": "module" to package.json if shipping pure ESM packages
+
+[For Packages: Export Path Rules]
+- ✅ CORRECT: `export * from './lib/index.js'`
+- ✅ CORRECT: `export * from './components/index.js'`
+- ✅ CORRECT: `export { Something } from './utils.js'`
+- ❌ WRONG: `export * from './lib'`
+- ❌ WRONG: `export * from './components'`
+- ❌ WRONG: `export { Something } from './utils'` (without extension)
+
+[Verification]
+- After building, check dist/index.js and ensure all export paths have .js extensions
+- Test the built package in a consuming Next.js or ES module project to verify imports work
+- If using TypeScript path aliases (@/...), ensure they are resolved to relative paths in the compiled output (not left as aliases)

package/.cursor/rules/package_development.mdc

@@ -0,0 +1,34 @@
+---
+description: Rules for package/library development to ensure ES module compatibility
+globs: 
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+  - "tsconfig*.json"
+  - "package.json"
+alwaysApply: true
+---
+
+[Package Development - ES Module Exports]
+- When creating npm packages that will be consumed by ES module bundlers (Next.js, Vite, etc.), ALL export statements MUST use explicit file paths with .js extensions
+- Directory imports like `export * from './components'` are INVALID in ES modules and will fail at runtime
+- ALWAYS use explicit paths: `export * from './components/index.js'` instead of `export * from './components'`
+- Even though source files are .ts, TypeScript requires .js extensions in import/export paths for ES module output
+- This applies to all export statements in index.ts files and any barrel export files
+
+[TypeScript Configuration for Packages]
+- For package builds (tsconfig.build.json), set moduleResolution to "node16" or "node" (not "bundler") when shipping compiled output
+- Ensure module is set to "ESNext" or "ES2020" for modern ES module output
+- Add "type": "module" to package.json if shipping pure ESM packages
+
+[Export Path Rules]
+- ✅ CORRECT: `export * from './lib/index.js'`
+- ✅ CORRECT: `export * from './components/index.js'`
+- ✅ CORRECT: `export { Something } from './utils.js'`
+- ❌ WRONG: `export * from './lib'`
+- ❌ WRONG: `export * from './components'`
+- ❌ WRONG: `export { Something } from './utils'` (without extension)
+
+[Verification]
+- After building, check dist/index.js and ensure all export paths have .js extensions
+- Test the built package in a consuming Next.js or ES module project to verify imports work
+- If using TypeScript path aliases (@/...), ensure they are resolved to relative paths in the compiled output (not left as aliases)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pub12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/components/index.d.ts

@@ -1,6 +1,6 @@
-export { ExampleComponent } from './example_component';
-export { ConfigViewer } from './config_viewer';
-export { ConfigEditor } from './config_editor';
-export type { ConfigViewerProps } from './config_viewer';
-export type { ConfigEditorProps } from './config_editor';
+export { ExampleComponent } from './example_component.js';
+export { ConfigViewer } from './config_viewer.js';
+export { ConfigEditor } from './config_editor.js';
+export type { ConfigViewerProps } from './config_viewer.js';
+export type { ConfigEditorProps } from './config_editor.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/components/index.js

@@ -1,5 +1,5 @@
 // Component exports
 // Export all components from this file for easy importing
-export { ExampleComponent } from './example_component';
-export { ConfigViewer } from './config_viewer';
-export { ConfigEditor } from './config_editor';
+export { ExampleComponent } from './example_component.js';
+export { ConfigViewer } from './config_viewer.js';
+export { ConfigEditor } from './config_editor.js';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from './components';
-export * from './lib/utils';
-export * from './lib';
+export * from './components/index.js';
+export * from './lib/utils.js';
+export * from './lib/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,OAAO,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -1,5 +1,5 @@
 // Main entry point for the component library
 // Export all components and utilities from this file
-export * from './components';
-export * from './lib/utils';
-export * from './lib';
+export * from './components/index.js';
+export * from './lib/utils.js';
+export * from './lib/index.js';

package/dist/lib/config-loader.d.ts

@@ -11,18 +11,26 @@ import type { ConfigProvider, HazoConfigOptions } from './types';
  * HazoConfig class
  *
  * Implements ConfigProvider interface for managing INI configuration files.
- * Provides sync read/write operations with in-memory caching.
+ * Provides sync read/write operations with in-memory caching and automatic cache refresh.
  */
 export declare class HazoConfig implements ConfigProvider {
     private filePath;
     private logger;
     private config;
+    private cache_ttl_ms;
+    private disable_cache;
+    private last_cache_refresh;
     /**
      * Constructor
-     * @param options - Configuration options including filePath and optional logger
+     * @param options - Configuration options including filePath, optional logger, cache settings
      * @throws Error if file doesn't exist
      */
     constructor(options: HazoConfigOptions);
+    /**
+     * Check if cache needs to be refreshed and refresh if needed
+     * This method is called before read operations to ensure cache is up to date
+     */
+    private ensure_cache_fresh;
     /**
      * Get a configuration value by section and key
      * @param section - The configuration section name

package/dist/lib/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/lib/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAU,MAAM,SAAS,CAAA;AAaxE;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAA6C;IAE3D;;;;OAIG;gBACS,OAAO,EAAE,iBAAiB;IAgBtC;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrD;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAI/D;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQtD;;;OAGG;IACH,IAAI,IAAI,IAAI;IAqBZ;;;OAGG;IACH,OAAO,IAAI,IAAI;IAuCf;;;OAGG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAQzD"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/lib/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAU,MAAM,SAAS,CAAA;AAaxE;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,MAAM,CAA6C;IAC3D,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAY;IAEtC;;;;OAIG;gBACS,OAAO,EAAE,iBAAiB;IAkBtC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKrD;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS;IAK/D;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQtD;;;OAGG;IACH,IAAI,IAAI,IAAI;IAqBZ;;;OAGG;IACH,OAAO,IAAI,IAAI;IA0Cf;;;OAGG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CASzD"}

package/dist/lib/config-loader.js

@@ -23,12 +23,12 @@ const no_op_logger = {
  * HazoConfig class
  *
  * Implements ConfigProvider interface for managing INI configuration files.
- * Provides sync read/write operations with in-memory caching.
+ * Provides sync read/write operations with in-memory caching and automatic cache refresh.
  */
 export class HazoConfig {
     /**
      * Constructor
-     * @param options - Configuration options including filePath and optional logger
+     * @param options - Configuration options including filePath, optional logger, cache settings
      * @throws Error if file doesn't exist
      */
     constructor(options) {
@@ -50,8 +50,28 @@ export class HazoConfig {
             writable: true,
             value: {}
         });
+        Object.defineProperty(this, "cache_ttl_ms", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "disable_cache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "last_cache_refresh", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         this.filePath = path.resolve(options.filePath);
         this.logger = options.logger || no_op_logger;
+        this.cache_ttl_ms = options.cache_ttl_ms ?? 5000; // Default 5 seconds
+        this.disable_cache = options.disable_cache ?? false; // Default: caching enabled
         // Validate file exists
         if (!fs.existsSync(this.filePath)) {
             const error = new Error(`Configuration file not found: ${this.filePath}`);
@@ -62,6 +82,28 @@ export class HazoConfig {
         // Load initial configuration
         this.refresh();
     }
+    /**
+     * Check if cache needs to be refreshed and refresh if needed
+     * This method is called before read operations to ensure cache is up to date
+     */
+    ensure_cache_fresh() {
+        if (this.disable_cache) {
+            // If caching is disabled, always refresh from disk
+            this.refresh();
+            return;
+        }
+        if (this.cache_ttl_ms === 0) {
+            // If TTL is 0, cache never expires (only manual refresh)
+            return;
+        }
+        const now = Date.now();
+        const cache_age = now - this.last_cache_refresh;
+        if (cache_age >= this.cache_ttl_ms) {
+            // Cache has expired, refresh from disk
+            this.logger.debug(`[HazoConfig] Cache expired (age: ${cache_age}ms, ttl: ${this.cache_ttl_ms}ms), refreshing from disk`);
+            this.refresh();
+        }
+    }
     /**
      * Get a configuration value by section and key
      * @param section - The configuration section name
@@ -69,6 +111,7 @@ export class HazoConfig {
      * @returns The configuration value, or undefined if not found
      */
     get(section, key) {
+        this.ensure_cache_fresh();
         return this.config[section]?.[key];
     }
     /**
@@ -77,6 +120,7 @@ export class HazoConfig {
      * @returns A record of key-value pairs for the section, or undefined if section doesn't exist
      */
     getSection(section) {
+        this.ensure_cache_fresh();
         return this.config[section] ? { ...this.config[section] } : undefined;
     }
     /**
@@ -135,6 +179,8 @@ export class HazoConfig {
                     }
                 }
             }
+            // Update cache timestamp
+            this.last_cache_refresh = Date.now();
             this.logger.info(`[HazoConfig] Configuration refreshed from: ${this.filePath}`, {
                 sections: Object.keys(this.config)
             });
@@ -167,6 +213,7 @@ export class HazoConfig {
      * @returns A record of all sections and their key-value pairs
      */
     getAllSections() {
+        this.ensure_cache_fresh();
         // Return a deep copy to prevent external modification
         const result = {};
         for (const [section, values] of Object.entries(this.config)) {

package/dist/lib/index.d.ts

@@ -5,8 +5,8 @@
  * configuration management utility. It serves as the primary entry point
  * for consumers of the library.
  */
-export { HazoConfig } from './config-loader';
-export { MockConfigProvider } from './mock_config_provider';
-export { ConfigErrorCode } from './types';
-export type { ConfigProvider, HazoConfigOptions, Logger, HazoConfigError } from './types';
+export { HazoConfig } from './config-loader.js';
+export { MockConfigProvider } from './mock_config_provider.js';
+export { ConfigErrorCode } from './types.js';
+export type { ConfigProvider, HazoConfigOptions, Logger, HazoConfigError } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AACzC,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,MAAM,EACN,eAAe,EAChB,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,MAAM,EACN,eAAe,EAChB,MAAM,YAAY,CAAA"}

package/dist/lib/index.js

@@ -5,6 +5,6 @@
  * configuration management utility. It serves as the primary entry point
  * for consumers of the library.
  */
-export { HazoConfig } from './config-loader';
-export { MockConfigProvider } from './mock_config_provider';
-export { ConfigErrorCode } from './types';
+export { HazoConfig } from './config-loader.js';
+export { MockConfigProvider } from './mock_config_provider.js';
+export { ConfigErrorCode } from './types.js';

package/dist/lib/types.d.ts

@@ -68,6 +68,18 @@ export interface HazoConfigOptions {
      * Optional logger instance for logging operations
      */
     logger?: Logger;
+    /**
+     * Cache time-to-live in milliseconds (default: 5000ms)
+     * When cache expires, configuration will be automatically refreshed from disk
+     * Set to 0 to disable automatic cache expiration (cache will only refresh on manual refresh() call)
+     */
+    cache_ttl_ms?: number;
+    /**
+     * Disable caching entirely (default: false)
+     * When true, every get() and getSection() call will read from disk
+     * When false, values are cached in memory and refreshed based on cache_ttl_ms
+     */
+    disable_cache?: boolean;
 }
 /**
  * Error codes for configuration operations

package/dist/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACxC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACvC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACvC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CACzC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAErD;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IAE/D;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtD;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,cAAc,+BAA+B;IAC7C,UAAU,2BAA2B;IACrC,WAAW,4BAA4B;IACvC,WAAW,4BAA4B;IACvC,gBAAgB,iCAAiC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,GAAG,CAAA;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACxC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACvC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;IACvC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CACzC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IAErD;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IAE/D;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtD;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,cAAc,+BAA+B;IAC7C,UAAU,2BAA2B;IACrC,WAAW,4BAA4B;IACvC,WAAW,4BAA4B;IACvC,gBAAgB,iCAAiC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,GAAG,CAAA;CACpB"}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "hazo_config",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Config wrapper with error handling",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/components/index.ts

@@ -1,9 +1,9 @@
 // Component exports
 // Export all components from this file for easy importing
 
-export { ExampleComponent } from './example_component'
-export { ConfigViewer } from './config_viewer'
-export { ConfigEditor } from './config_editor'
-export type { ConfigViewerProps } from './config_viewer'
-export type { ConfigEditorProps } from './config_editor'
+export { ExampleComponent } from './example_component.js'
+export { ConfigViewer } from './config_viewer.js'
+export { ConfigEditor } from './config_editor.js'
+export type { ConfigViewerProps } from './config_viewer.js'
+export type { ConfigEditorProps } from './config_editor.js'
 

package/src/index.ts

@@ -1,7 +1,7 @@
 // Main entry point for the component library
 // Export all components and utilities from this file
 
-export * from './components'
-export * from './lib/utils'
-export * from './lib'
+export * from './components/index.js'
+export * from './lib/utils.js'
+export * from './lib/index.js'
 

package/src/lib/config-loader.ts

@@ -27,21 +27,26 @@ const no_op_logger: Logger = {
  * HazoConfig class
  * 
  * Implements ConfigProvider interface for managing INI configuration files.
- * Provides sync read/write operations with in-memory caching.
+ * Provides sync read/write operations with in-memory caching and automatic cache refresh.
  */
 export class HazoConfig implements ConfigProvider {
   private filePath: string
   private logger: Logger
   private config: Record<string, Record<string, string>> = {}
+  private cache_ttl_ms: number
+  private disable_cache: boolean
+  private last_cache_refresh: number = 0
 
   /**
    * Constructor
-   * @param options - Configuration options including filePath and optional logger
+   * @param options - Configuration options including filePath, optional logger, cache settings
    * @throws Error if file doesn't exist
    */
   constructor(options: HazoConfigOptions) {
     this.filePath = path.resolve(options.filePath)
     this.logger = options.logger || no_op_logger
+    this.cache_ttl_ms = options.cache_ttl_ms ?? 5000 // Default 5 seconds
+    this.disable_cache = options.disable_cache ?? false // Default: caching enabled
 
     // Validate file exists
     if (!fs.existsSync(this.filePath)) {
@@ -55,6 +60,32 @@ export class HazoConfig implements ConfigProvider {
     this.refresh()
   }
 
+  /**
+   * Check if cache needs to be refreshed and refresh if needed
+   * This method is called before read operations to ensure cache is up to date
+   */
+  private ensure_cache_fresh(): void {
+    if (this.disable_cache) {
+      // If caching is disabled, always refresh from disk
+      this.refresh()
+      return
+    }
+
+    if (this.cache_ttl_ms === 0) {
+      // If TTL is 0, cache never expires (only manual refresh)
+      return
+    }
+
+    const now = Date.now()
+    const cache_age = now - this.last_cache_refresh
+
+    if (cache_age >= this.cache_ttl_ms) {
+      // Cache has expired, refresh from disk
+      this.logger.debug(`[HazoConfig] Cache expired (age: ${cache_age}ms, ttl: ${this.cache_ttl_ms}ms), refreshing from disk`)
+      this.refresh()
+    }
+  }
+
   /**
    * Get a configuration value by section and key
    * @param section - The configuration section name
@@ -62,6 +93,7 @@ export class HazoConfig implements ConfigProvider {
    * @returns The configuration value, or undefined if not found
    */
   get(section: string, key: string): string | undefined {
+    this.ensure_cache_fresh()
     return this.config[section]?.[key]
   }
 
@@ -71,6 +103,7 @@ export class HazoConfig implements ConfigProvider {
    * @returns A record of key-value pairs for the section, or undefined if section doesn't exist
    */
   getSection(section: string): Record<string, string> | undefined {
+    this.ensure_cache_fresh()
     return this.config[section] ? { ...this.config[section] } : undefined
   }
 
@@ -135,6 +168,9 @@ export class HazoConfig implements ConfigProvider {
         }
       }
 
+      // Update cache timestamp
+      this.last_cache_refresh = Date.now()
+
       this.logger.info(`[HazoConfig] Configuration refreshed from: ${this.filePath}`, {
         sections: Object.keys(this.config)
       })
@@ -169,6 +205,7 @@ export class HazoConfig implements ConfigProvider {
    * @returns A record of all sections and their key-value pairs
    */
   getAllSections(): Record<string, Record<string, string>> {
+    this.ensure_cache_fresh()
     // Return a deep copy to prevent external modification
     const result: Record<string, Record<string, string>> = {}
     for (const [section, values] of Object.entries(this.config)) {

package/src/lib/index.ts

@@ -6,13 +6,13 @@
  * for consumers of the library.
  */
 
-export { HazoConfig } from './config-loader'
-export { MockConfigProvider } from './mock_config_provider'
-export { ConfigErrorCode } from './types'
+export { HazoConfig } from './config-loader.js'
+export { MockConfigProvider } from './mock_config_provider.js'
+export { ConfigErrorCode } from './types.js'
 export type {
   ConfigProvider,
   HazoConfigOptions,
   Logger,
   HazoConfigError
-} from './types'
+} from './types.js'
 

package/src/lib/types.ts

@@ -76,6 +76,20 @@ export interface HazoConfigOptions {
    * Optional logger instance for logging operations
    */
   logger?: Logger
+
+  /**
+   * Cache time-to-live in milliseconds (default: 5000ms)
+   * When cache expires, configuration will be automatically refreshed from disk
+   * Set to 0 to disable automatic cache expiration (cache will only refresh on manual refresh() call)
+   */
+  cache_ttl_ms?: number
+
+  /**
+   * Disable caching entirely (default: false)
+   * When true, every get() and getSection() call will read from disk
+   * When false, values are cached in memory and refreshed based on cache_ttl_ms
+   */
+  disable_cache?: boolean
 }
 
 /**

package/tsconfig.build.json

@@ -2,11 +2,15 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "noEmit": false,
+    "module": "ESNext",
     "declaration": true,
     "declarationMap": true,
     "outDir": "./dist",
     "rootDir": "./src",
-    "allowImportingTsExtensions": false
+    "allowImportingTsExtensions": false,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true
   },
   "include": ["src"],
   "exclude": ["**/*.stories.tsx", "**/*.test.tsx", "**/*.test.ts"]