@plyaz/core 1.0.2 → 1.0.4

package/dist/index.mjs

@@ -1,4 +1,9 @@
-import { FEATURES } from '@plyaz/config';
+import { CACHE_MAX_SIZE_DEFAULT, CACHE_CLEANUP_INTERVAL_DEFAULT, TIME_CONSTANTS, FORMAT_CONSTANTS, FILE_CHECK_INTERVAL_DEFAULT, FEATURE_FLAG_FILE_PATHS, FEATURE_FLAG_CACHE_TTL_DEFAULT, MATH_CONSTANTS, ISO_STANDARDS, FEATURES } from '@plyaz/config';
+import * as fs from 'fs';
+import * as path from 'path';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import * as yaml from 'yaml';
 import { Post, Param, Body, Put, Delete, Get, Query, Controller, Injectable, Global, Module, HttpException, HttpStatus, Logger } from '@nestjs/common';
 import React, { createContext, useState, useRef, useCallback, useEffect, useContext, useMemo } from 'react';
 import { jsx } from 'react/jsx-runtime';
@@ -18,8 +23,6 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 var __publicField = (obj, key, value) => __defNormalProp(obj, key + "" , value);
-
-// src/utils/common/hash.ts
 function hashString(str) {
   const HASH_SHIFT = 5;
   let hash = 0;
@@ -32,10 +35,10 @@ function hashString(str) {
 }
 __name(hashString, "hashString");
 function isInRollout(identifier, percentage) {
-  if (percentage >= 100) return true;
+  if (percentage >= MATH_CONSTANTS.PERCENTAGE_MAX) return true;
   if (percentage <= 0) return false;
   const hash = hashString(identifier);
-  return hash % 100 < percentage;
+  return hash % MATH_CONSTANTS.PERCENTAGE_MAX < percentage;
 }
 __name(isInRollout, "isInRollout");
 function createRolloutIdentifier(featureKey, userId) {
@@ -64,7 +67,7 @@ var HashUtils = {
    * @param totalBuckets - Total number of buckets (default: 100)
    * @returns true if identifier is in the bucket range
    */
-  isInBucketRange: /* @__PURE__ */ __name((identifier, startBucket, endBucket, totalBuckets = 100) => {
+  isInBucketRange: /* @__PURE__ */ __name((identifier, startBucket, endBucket, totalBuckets = MATH_CONSTANTS.PERCENTAGE_MAX) => {
     const bucket = hashString(identifier) % totalBuckets;
     return bucket >= startBucket && bucket <= endBucket;
   }, "isInBucketRange"),
@@ -79,8 +82,6 @@ var HashUtils = {
     return hashString(str) % SAFE_INT;
   }, "createSeed")
 };
-
-// src/utils/common/values.ts
 function isStringFalsy(value) {
   if (value === "") return true;
   const lower = value.toLowerCase().trim();
@@ -146,7 +147,7 @@ var ValueUtils = {
    */
   isValidPercentage: /* @__PURE__ */ __name((value) => {
     if (typeof value !== "number") return false;
-    return !isNaN(value) && isFinite(value) && value >= 0 && value <= 100;
+    return !isNaN(value) && isFinite(value) && value >= 0 && value <= MATH_CONSTANTS.PERCENTAGE_MAX;
   }, "isValidPercentage"),
   /**
    * Clamps a number to a specific range.
@@ -180,9 +181,9 @@ var ValueUtils = {
    * @param defaultValue - Default if path doesn't exist
    * @returns Property value or default
    */
-  getNestedProperty: /* @__PURE__ */ __name((obj, path, defaultValue) => {
+  getNestedProperty: /* @__PURE__ */ __name((obj, path2, defaultValue) => {
     if (!obj || typeof obj !== "object") return defaultValue;
-    const keys = path.split(".");
+    const keys = path2.split(".");
     let current = obj;
     for (const key of keys) {
       if (current == null || typeof current !== "object") return defaultValue;
@@ -192,8 +193,6 @@ var ValueUtils = {
     return current;
   }, "getNestedProperty")
 };
-
-// src/utils/featureFlags/context.ts
 var FeatureFlagContextBuilder = class _FeatureFlagContextBuilder {
   static {
     __name(this, "FeatureFlagContextBuilder");
@@ -389,7 +388,7 @@ var ContextUtils = {
     if (context.platform && !["web", "mobile", "desktop"].includes(context.platform)) {
       errors.push("Platform must be web, mobile, or desktop");
     }
-    if (context.country && context.country.length !== 2) {
+    if (context.country && context.country.length !== ISO_STANDARDS.ISO_COUNTRY_CODE_LENGTH) {
       errors.push("Country must be a 2-letter ISO country code");
     }
     return {
@@ -750,6 +749,16 @@ var FeatureFlagEngine = class {
     this.overrides.delete(key);
     this.log("Override removed:", key);
   }
+  /**
+   * Updates the default values for feature flags.
+   * This is useful when the FEATURES constant is updated at runtime.
+   *
+   * @param newDefaults - New default values
+   */
+  updateDefaults(newDefaults) {
+    this.defaults = newDefaults;
+    this.log("Updated default feature values");
+  }
   /**
    * Clears all manual overrides.
    */
@@ -927,7 +936,7 @@ var FeatureFlagEngine = class {
       value: rule.value,
       isEnabled: isTruthy(rule.value),
       reason: "rule_match",
-      ruleId: rule.id,
+      matchedRuleId: rule.id,
       evaluatedAt: evaluatedAt ?? /* @__PURE__ */ new Date()
     };
   }
@@ -970,8 +979,6 @@ var FeatureFlagEngine = class {
     }
   }
 };
-
-// src/base/cache/strategies/memory.ts
 var MemoryCacheStrategy = class {
   static {
     __name(this, "MemoryCacheStrategy");
@@ -994,11 +1001,9 @@ var MemoryCacheStrategy = class {
    * @param config - Memory cache configuration
    */
   constructor(config = {}) {
-    const DEFAULT_MAX_ENTRIES = 1e3;
-    const DEFAULT_CLEANUP_INTERVAL = 6e4;
     const defaultConfig = {
-      maxEntries: DEFAULT_MAX_ENTRIES,
-      cleanupInterval: DEFAULT_CLEANUP_INTERVAL
+      maxEntries: CACHE_MAX_SIZE_DEFAULT,
+      cleanupInterval: CACHE_CLEANUP_INTERVAL_DEFAULT
     };
     this.maxSize = config.maxSize ?? config.maxEntries ?? defaultConfig.maxEntries;
     this.cleanupInterval = config.cleanupInterval ?? defaultConfig.cleanupInterval;
@@ -1150,8 +1155,6 @@ var MemoryCacheStrategy = class {
     }
   }
 };
-
-// src/base/cache/strategies/redis.ts
 var RedisCacheStrategy = class {
   /**
    * Creates a new Redis cache strategy.
@@ -1189,7 +1192,7 @@ var RedisCacheStrategy = class {
     const redisKey = this.buildRedisKey(key);
     const serializedEntry = JSON.stringify(entry);
     const ttlMs = entry.expiresAt - Date.now();
-    const ttlSeconds = Math.max(1, Math.ceil(ttlMs / 1e3));
+    const ttlSeconds = Math.max(1, Math.ceil(ttlMs / TIME_CONSTANTS.MILLISECONDS_PER_SECOND));
     await this.client.set(redisKey, serializedEntry, "EX", ttlSeconds);
     this.stats.setCount++;
   }
@@ -1313,8 +1316,8 @@ var RedisCacheStrategy = class {
       commandTimeout: this.config.commandTimeout ?? defaultOptions.commandTimeout,
       enableOfflineQueue: defaultOptions.enableOfflineQueue
     });
-    await new Promise((resolve, reject) => {
-      client.on("ready", resolve);
+    await new Promise((resolve2, reject) => {
+      client.on("ready", resolve2);
       client.on("error", reject);
     });
     return client;
@@ -1360,7 +1363,7 @@ var CacheManager = class {
     const finalTtl = ttl ?? this.config.ttl;
     const entry = {
       data: value,
-      expiresAt: Date.now() + finalTtl * 1e3,
+      expiresAt: Date.now() + finalTtl * TIME_CONSTANTS.MILLISECONDS_PER_SECOND,
       createdAt: Date.now()
     };
     await this.strategy.set(key, entry);
@@ -1453,8 +1456,6 @@ var CacheManager = class {
     await this.strategy.dispose?.();
   }
 };
-
-// src/domain/featureFlags/provider.ts
 var FeatureFlagProvider = class {
   /**
    * Creates a new feature flag provider.
@@ -1689,7 +1690,7 @@ var FeatureFlagProvider = class {
         void this.refresh().catch((error) => {
           this.log("Auto-refresh failed:", error);
         });
-      }, this.config.refreshInterval * 1e3);
+      }, this.config.refreshInterval * TIME_CONSTANTS.MILLISECONDS_PER_SECOND);
     }
   }
   /**
@@ -1860,31 +1861,53 @@ var MemoryFeatureFlagProvider = class extends FeatureFlagProvider {
     }
   }
   /**
-   * Updates a flag value in memory.
+   * Updates a flag in memory.
    *
-   * @param key - The flag key to update
-   * @param value - The new value
-   * @param updateProps - Optional properties to update
+   * @param flagOrKey - Either a complete flag object or a flag key
+   * @param value - The new value (only used when first param is a key)
+   * @param updateProps - Optional properties to update (only used when first param is a key)
    */
-  updateFlag(key, value, updateProps) {
-    const flagIndex = this.flags.findIndex((flag) => flag.key === key);
+  async updateFlag(flagOrKey, value, updateProps) {
+    let key;
+    let updatedFlag;
+    if (typeof flagOrKey === "string") {
+      key = flagOrKey;
+      const existingFlag = this.flags.find((f) => f.key === key);
+      if (!existingFlag) {
+        this.log(`Flag with key ${key} not found in memory`);
+        return;
+      }
+      if (value === void 0) {
+        this.log(`Value is required when updating flag by key`);
+        return;
+      }
+      updatedFlag = {
+        ...existingFlag,
+        value,
+        type: this.inferFlagType(value),
+        updatedAt: /* @__PURE__ */ new Date(),
+        updatedBy: "memory-runtime",
+        ...updateProps
+      };
+    } else {
+      const flag = flagOrKey;
+      key = flag.key;
+      updatedFlag = {
+        ...flag,
+        updatedAt: /* @__PURE__ */ new Date(),
+        updatedBy: flag.updatedBy || "memory-runtime"
+      };
+    }
+    const flagIndex = this.flags.findIndex((f) => f.key === key);
     if (flagIndex === -1) {
       this.log(`Flag with key ${key} not found in memory`);
       return;
     }
-    const updatedFlag = {
-      ...this.flags[flagIndex],
-      value,
-      type: this.inferFlagType(value),
-      updatedAt: /* @__PURE__ */ new Date(),
-      updatedBy: "memory-runtime",
-      ...updateProps
-    };
     this.flags[flagIndex] = updatedFlag;
     this.engine.setFlags(this.flags);
     void this.cacheManager.clear();
     this.notifySubscribers();
-    this.log(`Updated flag: ${key} with new value:`, value);
+    this.log(`Updated flag: ${key}`);
   }
   /**
    * Adds a new flag to memory at runtime.
@@ -1994,6 +2017,18 @@ var MemoryFeatureFlagProvider = class extends FeatureFlagProvider {
   getCurrentRules() {
     return [...this.rules];
   }
+  /**
+   * Updates the features object and syncs all flags.
+   * This allows updating the FEATURES constant at runtime.
+   *
+   * @param newFeatures - New features object to sync with
+   */
+  async syncFeatures(newFeatures) {
+    this.log("Syncing with new FEATURES values");
+    this.features = newFeatures;
+    await this.refresh();
+    this.log(`Synced ${Object.keys(newFeatures).length} features`);
+  }
   /**
    * Resets the memory provider to its initial state.
    */
@@ -2027,13 +2062,18 @@ var MemoryFeatureFlagProvider = class extends FeatureFlagProvider {
     }
   }
 };
-
-// src/domain/featureFlags/providers/file.ts
+var readFile2 = promisify(fs.readFile);
+var writeFile2 = promisify(fs.writeFile);
+var access2 = promisify(fs.access);
+var mkdir2 = promisify(fs.mkdir);
 var FileFeatureFlagProvider = class extends FeatureFlagProvider {
   static {
     __name(this, "FileFeatureFlagProvider");
   }
   fileWatcher;
+  lastFileContent;
+  fileCheckInterval;
+  rules = [];
   /**
    * Creates a new file feature flag provider.
    *
@@ -2043,8 +2083,15 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
   constructor(config, features) {
     super(config, features);
     this.validateConfig();
-    this.setupFileWatcher();
-    throw new Error("File provider implementation coming soon");
+  }
+  /**
+   * Initializes the provider and sets up file watching if enabled.
+   */
+  async initialize() {
+    await super.initialize();
+    if (this.config.fileConfig?.shouldWatchForChanges) {
+      this.setupFileWatcher();
+    }
   }
   /**
    * Fetches flags and rules from the configuration file.
@@ -2053,9 +2100,89 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
    * @returns Promise resolving to flags and rules from file
    */
   async fetchData() {
-    throw new Error(
-      'File Provider is not yet fully implemented. This requires dedicated file paths to be configured in @plyaz/core.\n\nRequired Implementation:\n1. Define standard file paths for feature flags\n2. Implement file reading and parsing logic\n3. Add YAML and JSON format support\n4. Set up file watching for hot reload\n5. Add file validation and error handling\n\nRecommended File Structure:\n@plyaz/core/config/\n├── feature-flags.json\n├── feature-flags.yaml\n├── rules/\n│   ├── targeting-rules.json\n│   └── rollout-rules.json\n└── environments/\n    ├── development.json\n    ├── staging.json\n    └── production.json\n\nExample Configuration:\n{\n  provider: "file",\n  fileConfig: {\n    filePath: "@plyaz/core/config/feature-flags.json",\n    format: "json",\n    shouldWatchForChanges: true\n  },\n  isCacheEnabled: true,\n  cacheTtl: 60\n}\n\nNote: Default provider should be memory for testing environments.\nFile provider is intended for configuration-driven deployments.\n\nMigration Note: This provider will be moved to @plyaz/core/src/domain/featureFlags/providers/'
-    );
+    const { filePath, format } = this.config.fileConfig;
+    const resolvedPath = this.resolveFilePath(filePath);
+    try {
+      await access2(resolvedPath, fs.constants.R_OK);
+      const content = await readFile2(resolvedPath, "utf-8");
+      this.lastFileContent = content;
+      const data = await this.parseFileContent(content, format);
+      this.validateFileData(data);
+      this.rules = data.rules || [];
+      return {
+        flags: data.flags || [],
+        rules: data.rules || []
+      };
+    } catch (error) {
+      return this.handleFetchDataError(error, resolvedPath, format);
+    }
+  }
+  /**
+   * Parses file content based on format.
+   *
+   * @private
+   */
+  async parseFileContent(content, format) {
+    if (format === "json") {
+      return this.parseJSON(content);
+    } else if (format === "yaml") {
+      return await this.parseYAML(content);
+    }
+    throw new Error(`Unsupported file format: ${format}`);
+  }
+  /**
+   * Handles errors for fetchData, including file creation and fallback.
+   *
+   * @private
+   */
+  async handleFetchDataError(error, resolvedPath, format) {
+    const isFileNotFound = this.isFileNotFoundError(error);
+    if (isFileNotFound && this.config.shouldFallbackToDefaults) {
+      return await this.handleFileNotFound(resolvedPath, format);
+    }
+    this.log(`Error reading file ${resolvedPath}:`, error);
+    if (this.config.shouldFallbackToDefaults) {
+      return this.handleFallbackToDefaults();
+    }
+    throw error;
+  }
+  /**
+   * Type guard for NodeJS.ErrnoException.
+   */
+  isFileNotFoundError(error) {
+    return error instanceof Error && typeof error.code === "string" && error.code === "ENOENT";
+  }
+  /**
+   * Handles the case when the file is not found and fallback is enabled.
+   */
+  async handleFileNotFound(resolvedPath, format) {
+    this.log(`File not found at ${resolvedPath}, creating with default values`);
+    try {
+      await this.createDefaultFile(resolvedPath, format);
+      const content = await readFile2(resolvedPath, "utf-8");
+      this.lastFileContent = content;
+      const data = await this.parseFileContent(content, format);
+      return {
+        flags: data.flags || [],
+        rules: data.rules || []
+      };
+    } catch (createError) {
+      this.log("Error creating default file:", createError);
+      return {
+        flags: this.createDefaultFlags(),
+        rules: []
+      };
+    }
+  }
+  /**
+   * Handles fallback to default flags and rules.
+   */
+  handleFallbackToDefaults() {
+    this.log("Falling back to default values");
+    return {
+      flags: this.createDefaultFlags(),
+      rules: []
+    };
   }
   /**
    * Validates the file provider configuration.
@@ -2078,6 +2205,165 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
       throw new Error('File format must be either "json" or "yaml"');
     }
   }
+  /**
+   * Resolves the file path, supporting relative and absolute paths.
+   *
+   * @private
+   * @param filePath - The file path from configuration
+   * @returns Resolved absolute file path
+   */
+  resolveFilePath(filePath) {
+    let pathToResolve = filePath;
+    if (!pathToResolve) {
+      const __filename = fileURLToPath(import.meta.url);
+      const __dirname = path.dirname(__filename);
+      pathToResolve = path.join(__dirname, "../../../config/feature-provider.json");
+    }
+    if (path.isAbsolute(pathToResolve)) {
+      return pathToResolve;
+    }
+    return path.resolve(process.cwd(), pathToResolve);
+  }
+  /**
+   * Parses JSON content.
+   *
+   * @private
+   * @param content - File content
+   * @returns Parsed data
+   */
+  parseJSON(content) {
+    try {
+      return JSON.parse(content);
+    } catch (error) {
+      throw new Error(
+        `Invalid JSON format: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Parses YAML content.
+   *
+   * @private
+   * @param content - File content
+   * @returns Parsed data
+   */
+  async parseYAML(content) {
+    try {
+      const data = yaml.parse(content);
+      return data;
+    } catch (error) {
+      throw new Error(
+        `Invalid YAML format: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Validates the structure of file data.
+   *
+   * @private
+   * @param data - Parsed file data
+   */
+  validateFileData(data) {
+    if (!data || typeof data !== "object") {
+      throw new Error("File must contain a valid object");
+    }
+    const fileData = data;
+    this.checkFlagsArray(fileData.flags);
+    this.checkRulesArray(fileData.rules);
+  }
+  checkFlagsArray(flags) {
+    if (flags && !Array.isArray(flags)) {
+      throw new Error('"flags" must be an array');
+    }
+    if (Array.isArray(flags)) {
+      this.validateFlags(flags);
+    }
+  }
+  checkRulesArray(rules) {
+    if (rules && !Array.isArray(rules)) {
+      throw new Error('"rules" must be an array');
+    }
+    if (Array.isArray(rules)) {
+      this.validateRules(rules);
+    }
+  }
+  validateFlags(flags) {
+    flags.forEach((flag, index) => {
+      if (!flag || typeof flag !== "object") {
+        throw new Error(`Flag at index ${index} must be an object`);
+      }
+      const flagObj = flag;
+      if (!flagObj.key || typeof flagObj.key !== "string") {
+        throw new Error(`Flag at index ${index} must have a "key" property`);
+      }
+      if (flagObj.value === void 0) {
+        throw new Error(`Flag "${flagObj.key}" must have a "value" property`);
+      }
+    });
+  }
+  validateRules(rules) {
+    rules.forEach((rule, index) => {
+      if (!rule || typeof rule !== "object") {
+        throw new Error(`Rule at index ${index} must be an object`);
+      }
+      const ruleObj = rule;
+      if (!ruleObj.id || typeof ruleObj.id !== "string") {
+        throw new Error(`Rule at index ${index} must have an "id" property`);
+      }
+      if (!ruleObj.flagKey || typeof ruleObj.flagKey !== "string") {
+        throw new Error(`Rule "${ruleObj.id}" must have a "flagKey" property`);
+      }
+      if (!Array.isArray(ruleObj.conditions)) {
+        throw new Error(`Rule "${ruleObj.id}" must have a "conditions" array`);
+      }
+    });
+  }
+  /**
+   * Creates a default configuration file with values from features.
+   *
+   * @private
+   * @param filePath - Path where to create the file
+   * @param format - File format (json or yaml)
+   */
+  async createDefaultFile(filePath, format) {
+    const dir = path.dirname(filePath);
+    await mkdir2(dir, { recursive: true });
+    const defaultData = {
+      flags: this.createDefaultFlags(),
+      rules: []
+    };
+    let content;
+    if (format === "json") {
+      content = JSON.stringify(defaultData, null, FORMAT_CONSTANTS.JSON_INDENT_SPACES);
+    } else {
+      content = yaml.stringify(defaultData);
+    }
+    await writeFile2(filePath, content, "utf-8");
+    this.log(`Created default feature flag file at: ${filePath}`);
+  }
+  /**
+   * Creates default flags from the features configuration.
+   *
+   * @private
+   * @returns Array of default flags
+   */
+  createDefaultFlags() {
+    return Object.entries(this.features).map(([key, value]) => ({
+      key,
+      value,
+      isEnabled: true,
+      name: key,
+      description: `Default flag for ${key}`,
+      type: typeof value === "boolean" ? "boolean" : typeof value === "number" ? "number" : typeof value === "string" ? "string" : "json",
+      environment: "development",
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date(),
+      createdBy: "system",
+      updatedBy: "system",
+      metadata: {},
+      tags: []
+    }));
+  }
   /**
    * Sets up file watching for hot reload if enabled.
    *
@@ -2087,8 +2373,32 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
     if (!this.config.fileConfig?.shouldWatchForChanges) {
       return;
     }
-    this.log("File watching would be enabled for hot reload");
-    this.log("File path:", this.config.fileConfig.filePath);
+    const { filePath } = this.config.fileConfig;
+    const resolvedPath = this.resolveFilePath(filePath);
+    try {
+      this.fileWatcher = fs.watch(resolvedPath, async (eventType) => {
+        if (eventType === "change") {
+          this.log(`File changed: ${resolvedPath}`);
+          if (this.fileCheckInterval) {
+            clearTimeout(this.fileCheckInterval);
+          }
+          this.fileCheckInterval = setTimeout(async () => {
+            try {
+              const content = await readFile2(resolvedPath, "utf-8");
+              if (content !== this.lastFileContent) {
+                this.log("File content changed, refreshing...");
+                await this.refresh();
+              }
+            } catch (error) {
+              this.log("Error reading changed file:", error);
+            }
+          }, this.config.fileConfig?.fileCheckInterval ?? FILE_CHECK_INTERVAL_DEFAULT);
+        }
+      });
+      this.log(`File watching enabled for: ${resolvedPath}`);
+    } catch (error) {
+      this.log(`Failed to set up file watching: ${error}`);
+    }
   }
   /**
    * Disposes of the file provider and stops file watching.
@@ -2096,10 +2406,57 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
   dispose() {
     super.dispose();
     if (this.fileWatcher) {
-      clearInterval(this.fileWatcher);
+      this.fileWatcher.close();
       this.fileWatcher = void 0;
       this.log("File watching stopped");
     }
+    if (this.fileCheckInterval) {
+      clearTimeout(this.fileCheckInterval);
+      this.fileCheckInterval = void 0;
+    }
+  }
+  /**
+   * Refreshes the provider by fetching latest data from the file.
+   * Overrides base class to store rules.
+   *
+   * @returns Promise that resolves when refresh is complete
+   */
+  async refresh() {
+    await super.refresh();
+  }
+  /**
+   * Updates the features object and writes to file.
+   * This allows updating the FEATURES at runtime and persisting to file.
+   *
+   * @param newFeatures - New features object to sync with
+   */
+  async syncFeatures(newFeatures) {
+    this.log("Syncing with new FEATURES values and updating file");
+    this.features = newFeatures;
+    const fileData = {
+      flags: this.createDefaultFlags(),
+      rules: this.rules || []
+    };
+    const { filePath, format } = this.config.fileConfig;
+    const resolvedPath = this.resolveFilePath(filePath);
+    try {
+      let content;
+      if (format === "json") {
+        content = JSON.stringify(fileData, null, FORMAT_CONSTANTS.JSON_INDENT_SPACES);
+      } else {
+        content = yaml.stringify(fileData);
+      }
+      await writeFile2(resolvedPath, content, "utf-8");
+      this.lastFileContent = content;
+      this.engine.updateDefaults(newFeatures);
+      await this.refresh();
+      this.log(`Synced ${Object.keys(newFeatures).length} features to file: ${resolvedPath}`);
+    } catch (error) {
+      this.log("Error syncing features to file:", error);
+      throw new Error(
+        `Failed to sync features to file: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
   }
   /**
    * Gets information about the file provider.
@@ -2107,18 +2464,23 @@ var FileFeatureFlagProvider = class extends FeatureFlagProvider {
    * @returns File provider information
    */
   getFileInfo() {
+    const filePath = this.config.fileConfig?.filePath;
+    const resolvedPath = filePath ? this.resolveFilePath(filePath) : void 0;
+    let lastModified;
+    if (resolvedPath) {
+      try {
+        const stats = fs.statSync(resolvedPath);
+        lastModified = stats.mtime;
+      } catch {
+      }
+    }
     return {
-      filePath: this.config.fileConfig?.filePath,
+      filePath,
+      resolvedPath,
       format: this.config.fileConfig?.format,
       isWatchEnabled: Boolean(this.config.fileConfig?.shouldWatchForChanges),
-      isImplemented: false,
-      requiredImplementation: [
-        "File reading and parsing logic",
-        "YAML and JSON format support",
-        "File watching for hot reload",
-        "Standard file path configuration",
-        "File validation and error handling"
-      ]
+      isImplemented: true,
+      lastModified
     };
   }
 };
@@ -2431,8 +2793,6 @@ Examples:
     };
   }
 };
-
-// src/domain/featureFlags/providers/factory.ts
 var PROVIDER_REGISTRY = {
   memory: MemoryFeatureFlagProvider,
   file: FileFeatureFlagProvider,
@@ -2535,25 +2895,69 @@ var FeatureFlagProviderFactory = class {
     };
   }
   /**
-   * Creates a default memory provider for testing environments.
+   * Creates a default provider.
+   * Uses file provider if features are not provided, memory provider otherwise.
    *
-   * @param features - Record of feature flag keys to their default values
+   * @param features - Record of feature flag keys to their default values (optional)
    * @param overrides - Optional configuration overrides
-   * @returns Memory provider instance
+   * @returns Provider instance
    */
   static createDefault(features, overrides) {
+    const provider = features ? "memory" : "file";
     const defaultConfig = {
-      provider: "memory",
+      provider,
       isCacheEnabled: true,
-      cacheTtl: 300,
-      // 5 minutes
+      cacheTtl: FEATURE_FLAG_CACHE_TTL_DEFAULT,
       refreshInterval: 0,
       // No auto-refresh
       isLoggingEnabled: false,
       shouldFallbackToDefaults: true,
       ...overrides
     };
-    return this.create(defaultConfig, features);
+    if (defaultConfig.provider === "file" && !defaultConfig.fileConfig) {
+      defaultConfig.fileConfig = {
+        filePath: FEATURE_FLAG_FILE_PATHS.DEFAULT,
+        format: "json",
+        shouldWatchForChanges: false
+      };
+    }
+    return this.create(defaultConfig, features ?? {});
+  }
+  /**
+   * Type guard to check if a provider supports feature syncing.
+   *
+   * @param provider - The provider instance to check
+   * @returns True if provider has syncFeatures method
+   */
+  static isSyncableProvider(provider) {
+    return "syncFeatures" in provider && typeof provider.syncFeatures === "function";
+  }
+  /**
+   * Updates features on a provider if it supports the syncFeatures method.
+   * This is useful for providers like MemoryProvider that can update their features at runtime.
+   *
+   * @param provider - The provider instance
+   * @param newFeatures - New features to sync
+   * @returns Promise that resolves when sync is complete
+   * @throws Error if provider doesn't support feature syncing
+   */
+  static async syncFeatures(provider, newFeatures) {
+    if (this.isSyncableProvider(provider)) {
+      await provider.syncFeatures(newFeatures);
+    } else {
+      throw new Error(
+        `Provider type does not support feature syncing. Only providers with syncFeatures method (like MemoryProvider and FileProvider) support this operation.`
+      );
+    }
+  }
+  /**
+   * Checks if a provider supports feature syncing.
+   *
+   * @param provider - The provider instance to check
+   * @returns True if provider supports syncFeatures method
+   */
+  static supportsFeaturesSync(provider) {
+    return this.isSyncableProvider(provider);
   }
   /**
    * Validates provider configuration before instantiation.
@@ -2606,8 +3010,11 @@ var FeatureFlagProviderFactory = class {
     validator();
   }
   static validateFileConfig(config) {
-    if (!config.fileConfig) {
-      throw new Error("File configuration is required for file provider");
+    if (config.fileConfig) {
+      const { format } = config.fileConfig;
+      if (format && !["json", "yaml"].includes(format)) {
+        throw new Error('File format must be either "json" or "yaml"');
+      }
     }
   }
   static validateRedisConfig(config) {