@plyaz/core 1.16.0 → 1.17.0

package/dist/utils/index.js

@@ -0,0 +1,1143 @@
+'use strict';
+
+var config = require('@plyaz/config');
+var types = require('@plyaz/types');
+var errors = require('@plyaz/errors');
+var logger$1 = require('@plyaz/logger');
+var core = require('@plyaz/types/core');
+
+// @plyaz package - Built with tsup
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function hashString(str) {
+  if (str.length === 0) return 0;
+  let hash = config.FNV_CONSTANTS.FNV_32_OFFSET;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, config.FNV_CONSTANTS.FNV_32_PRIME) >>> 0;
+  }
+  return hash >>> 0;
+}
+__name(hashString, "hashString");
+function isInRollout(identifier, percentage) {
+  if (percentage >= config.MATH_CONSTANTS.PERCENTAGE_MAX) return true;
+  if (percentage <= 0) return false;
+  const hash = hashString(identifier);
+  return hash % config.MATH_CONSTANTS.PERCENTAGE_MAX < percentage;
+}
+__name(isInRollout, "isInRollout");
+function createRolloutIdentifier(featureKey, userId) {
+  const trimmedUserId = userId?.trim();
+  const effectiveUserId = trimmedUserId && trimmedUserId.length > 0 ? trimmedUserId : "anonymous";
+  return `${featureKey}:${effectiveUserId}`;
+}
+__name(createRolloutIdentifier, "createRolloutIdentifier");
+var HashUtils = {
+  /**
+   * Generates a hash-based bucket for load balancing or distribution.
+   *
+   * @param identifier - Unique identifier
+   * @param bucketCount - Number of buckets (default: 10)
+   * @returns Bucket number (0 to bucketCount-1)
+   */
+  getBucket: /* @__PURE__ */ __name((identifier, bucketCount = 10) => {
+    return hashString(identifier) % bucketCount;
+  }, "getBucket"),
+  /**
+   * Checks if an identifier falls within a specific bucket range.
+   *
+   * @param identifier - Unique identifier
+   * @param startBucket - Starting bucket (inclusive)
+   * @param endBucket - Ending bucket (inclusive)
+   * @param totalBuckets - Total number of buckets (default: 100)
+   * @returns true if identifier is in the bucket range
+   */
+  isInBucketRange: /* @__PURE__ */ __name((identifier, startBucket, endBucket, totalBuckets = config.MATH_CONSTANTS.PERCENTAGE_MAX) => {
+    const bucket = hashString(identifier) % totalBuckets;
+    return bucket >= startBucket && bucket <= endBucket;
+  }, "isInBucketRange"),
+  /**
+   * Creates a deterministic random seed from a string.
+   * Uses the improved hash function and ensures the seed is within
+   * the safe range for JavaScript's Math.random seeding.
+   *
+   * @param str - String to convert to seed
+   * @returns Deterministic seed value (0 to 2^31-1)
+   */
+  createSeed: /* @__PURE__ */ __name((str) => {
+    return hashString(str) % config.HASH_SEED_CONSTANTS.MAX_SAFE_SEED;
+  }, "createSeed")
+};
+
+// src/utils/common/id.ts
+var RANDOM_ID_RADIX = 36;
+var RANDOM_ID_SLICE_START = 2;
+var SHORT_ID_LENGTH = 8;
+var HEX_RADIX = 16;
+var HEX_SLICE_START = 2;
+var HEX_SLICE_END = 18;
+var SPAN_ID_LENGTH = 16;
+function generateId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START)}`;
+}
+__name(generateId, "generateId");
+function generateShortId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID().replace(/-/g, "").slice(0, SHORT_ID_LENGTH);
+  }
+  return Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START, RANDOM_ID_SLICE_START + SHORT_ID_LENGTH);
+}
+__name(generateShortId, "generateShortId");
+function generateCorrelationId() {
+  return `${Date.now()}-${generateShortId()}`;
+}
+__name(generateCorrelationId, "generateCorrelationId");
+function generateTraceId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID().replace(/-/g, "");
+  }
+  return Math.random().toString(HEX_RADIX).substring(HEX_SLICE_START, HEX_SLICE_END) + Math.random().toString(HEX_RADIX).substring(HEX_SLICE_START, HEX_SLICE_END);
+}
+__name(generateTraceId, "generateTraceId");
+function generateSpanId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID().replace(/-/g, "").substring(0, SPAN_ID_LENGTH);
+  }
+  return Math.random().toString(HEX_RADIX).substring(HEX_SLICE_START, HEX_SLICE_END);
+}
+__name(generateSpanId, "generateSpanId");
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isValidUUID(value) {
+  if (!value) return false;
+  return UUID_REGEX.test(value);
+}
+__name(isValidUUID, "isValidUUID");
+var IdUtils = {
+  generate: generateId,
+  generateShort: generateShortId,
+  generateCorrelation: generateCorrelationId,
+  generateTraceId,
+  generateSpanId,
+  isValidUUID
+};
+function isStringFalsy(value) {
+  if (value === "") return true;
+  const lower = value.toLowerCase().trim();
+  return ["false", "no", "0", "off", "disabled"].includes(lower);
+}
+__name(isStringFalsy, "isStringFalsy");
+function isObjectTruthy(value) {
+  if (Array.isArray(value)) return value.length > 0;
+  if (value instanceof Map || value instanceof Set) return value.size > 0;
+  if (value.constructor === Object) return Object.keys(value).length > 0;
+  return true;
+}
+__name(isObjectTruthy, "isObjectTruthy");
+function isTruthy(value) {
+  if (value === null || value === void 0) return false;
+  switch (typeof value) {
+    case "boolean":
+      return value;
+    case "string":
+      return !isStringFalsy(value);
+    case "number":
+      return value !== 0 && !isNaN(value);
+    case "function":
+    case "symbol":
+      return true;
+    case "object":
+      return isObjectTruthy(value);
+    default:
+      return false;
+  }
+}
+__name(isTruthy, "isTruthy");
+function parseStringToBoolean(value, defaultValue) {
+  const lower = value.toLowerCase();
+  if (["true", "yes", "1", "on", "enabled"].includes(lower)) return true;
+  if (["false", "no", "0", "off", "disabled"].includes(lower)) return false;
+  return defaultValue;
+}
+__name(parseStringToBoolean, "parseStringToBoolean");
+function toBoolean(value, defaultValue = false) {
+  if (value === null || value === void 0) return false;
+  switch (typeof value) {
+    case "boolean":
+      return value;
+    case "string":
+      return parseStringToBoolean(value, defaultValue);
+    case "number":
+      return value !== 0 && !isNaN(value);
+    case "object":
+    case "function":
+      return true;
+    default:
+      return defaultValue;
+  }
+}
+__name(toBoolean, "toBoolean");
+function toNumber(value, defaultValue = 0) {
+  if (value === null || value === void 0) return defaultValue;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "number") return isNaN(value) ? defaultValue : value;
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    return isNaN(parsed) ? defaultValue : parsed;
+  }
+  return defaultValue;
+}
+__name(toNumber, "toNumber");
+var ValueUtils = {
+  /**
+   * Checks if a value is a valid percentage (0-100).
+   *
+   * @param value - Value to check
+   * @returns true if valid percentage
+   */
+  isValidPercentage: /* @__PURE__ */ __name((value) => {
+    if (typeof value !== "number") return false;
+    return !isNaN(value) && isFinite(value) && value >= 0 && value <= config.MATH_CONSTANTS.PERCENTAGE_MAX;
+  }, "isValidPercentage"),
+  /**
+   * Clamps a number to a specific range.
+   *
+   * @param value - Value to clamp
+   * @param min - Minimum value
+   * @param max - Maximum value
+   * @returns Clamped value
+   */
+  clamp: /* @__PURE__ */ __name((value, min, max) => {
+    return Math.min(Math.max(value, min), max);
+  }, "clamp"),
+  /**
+   * Checks if a value is empty (null, undefined, empty string, empty array).
+   *
+   * @param value - Value to check
+   * @returns true if empty
+   */
+  isEmpty: /* @__PURE__ */ __name((value) => {
+    if (value === null || value === void 0) return true;
+    if (typeof value === "string") return value.trim() === "";
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === "object") return Object.keys(value).length === 0;
+    return false;
+  }, "isEmpty"),
+  /**
+   * Safely gets a nested property from an object.
+   *
+   * @param obj - Object to query
+   * @param path - Dot-separated path (e.g., 'user.profile.name')
+   * @param defaultValue - Default if path doesn't exist
+   * @returns Property value or default
+   */
+  getNestedProperty: /* @__PURE__ */ __name((obj, path, defaultValue) => {
+    if (!obj || typeof obj !== "object") return defaultValue;
+    const keys = path.split(".");
+    let current = obj;
+    for (const key of keys) {
+      if (current == null || typeof current !== "object") return defaultValue;
+      current = current[key];
+      if (current === void 0) return defaultValue;
+    }
+    return current;
+  }, "getNestedProperty")
+};
+
+// src/utils/common/object.ts
+function setNestedProperty(obj, path, value) {
+  const keys = path.split(".");
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!(key in current) || typeof current[key] !== "object" || current[key] === null) {
+      current[key] = {};
+    }
+    current = current[key];
+  }
+  const finalKey = keys[keys.length - 1];
+  current[finalKey] = value;
+}
+__name(setNestedProperty, "setNestedProperty");
+function getNestedProperty(obj, path, defaultValue) {
+  const keys = path.split(".");
+  let current = obj;
+  for (const key of keys) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return defaultValue;
+    }
+    current = current[key];
+  }
+  return current !== void 0 ? current : defaultValue;
+}
+__name(getNestedProperty, "getNestedProperty");
+function hasNestedProperty(obj, path) {
+  const keys = path.split(".");
+  let current = obj;
+  for (const key of keys) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return false;
+    }
+    if (!(key in current)) {
+      return false;
+    }
+    current = current[key];
+  }
+  return current !== void 0;
+}
+__name(hasNestedProperty, "hasNestedProperty");
+var ObjectUtils = {
+  setNestedProperty,
+  getNestedProperty,
+  hasNestedProperty
+};
+
+// src/utils/common/typeGuards.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+__name(isObject, "isObject");
+function hasProperty(obj, key) {
+  return isObject(obj) && key in obj;
+}
+__name(hasProperty, "hasProperty");
+var TypeGuardUtils = {
+  isObject,
+  hasProperty
+};
+var isString = /* @__PURE__ */ __name((value) => typeof value === "string", "isString");
+var isDefined = /* @__PURE__ */ __name((value) => value !== void 0, "isDefined");
+var isNumber = /* @__PURE__ */ __name((value) => typeof value === "number", "isNumber");
+var getValidProviders = /* @__PURE__ */ __name(() => Object.values(types.FEATURE_FLAG_PROVIDERS), "getValidProviders");
+var FeatureFlagContextBuilder = class _FeatureFlagContextBuilder {
+  constructor() {
+    this.context = {};
+  }
+  static {
+    __name(this, "FeatureFlagContextBuilder");
+  }
+  /**
+   * Sets the user ID in the context.
+   *
+   * @param userId - User identifier
+   * @returns Builder instance for chaining
+   */
+  setUserId(userId) {
+    this.context.userId = userId;
+    return this;
+  }
+  /**
+   * Sets the user email in the context.
+   *
+   * @param userEmail - User email address
+   * @returns Builder instance for chaining
+   */
+  setUserEmail(userEmail) {
+    this.context.userEmail = userEmail;
+    return this;
+  }
+  /**
+   * Sets the user role in the context.
+   *
+   * @param userRole - User role or permission level
+   * @returns Builder instance for chaining
+   */
+  setUserRole(userRole) {
+    this.context.userRole = userRole;
+    return this;
+  }
+  /**
+   * Sets the country in the context.
+   *
+   * @param country - Country code (ISO 3166-1 alpha-2)
+   * @returns Builder instance for chaining
+   */
+  setCountry(country) {
+    this.context.country = country;
+    return this;
+  }
+  /**
+   * Sets the platform in the context.
+   *
+   * @param platform - Platform type
+   * @returns Builder instance for chaining
+   */
+  setPlatform(platform) {
+    this.context.platform = platform;
+    return this;
+  }
+  /**
+   * Sets the version in the context.
+   *
+   * @param version - Application version
+   * @returns Builder instance for chaining
+   */
+  setVersion(version) {
+    this.context.version = version;
+    return this;
+  }
+  /**
+   * Sets the environment in the context.
+   *
+   * @param environment - Current environment
+   * @returns Builder instance for chaining
+   */
+  setEnvironment(environment) {
+    this.context.environment = environment;
+    return this;
+  }
+  /**
+   * Sets custom context data.
+   *
+   * @param custom - Custom context properties
+   * @returns Builder instance for chaining
+   */
+  setCustom(custom) {
+    this.context.custom = { ...this.context.custom, ...custom };
+    return this;
+  }
+  /**
+   * Adds a single custom property to the context.
+   *
+   * @param key - Custom property key
+   * @param value - Custom property value
+   * @returns Builder instance for chaining
+   */
+  addCustomProperty(key, value) {
+    this.context.custom ??= {};
+    this.context.custom[key] = value;
+    return this;
+  }
+  /**
+   * Builds the final context object.
+   * Validates required fields and returns the context.
+   *
+   * @returns Complete feature flag context
+   * @throws Error if required environment is not set
+   */
+  build() {
+    return {
+      environment: this.context.environment ?? "development",
+      userId: this.context.userId,
+      userEmail: this.context.userEmail,
+      userRole: this.context.userRole,
+      country: this.context.country,
+      platform: this.context.platform,
+      version: this.context.version,
+      custom: this.context.custom
+    };
+  }
+  /**
+   * Clears all context data and resets the builder.
+   *
+   * @returns Builder instance for chaining
+   */
+  clear() {
+    this.context = {};
+    return this;
+  }
+  /**
+   * Creates a copy of the current builder state.
+   *
+   * @returns New builder instance with copied context
+   */
+  clone() {
+    const cloned = new _FeatureFlagContextBuilder();
+    cloned.context = { ...this.context };
+    if (this.context.custom) {
+      cloned.context.custom = { ...this.context.custom };
+    }
+    return cloned;
+  }
+};
+var ContextUtils = {
+  /**
+   * Creates a basic context for anonymous users using the builder.
+   *
+   * @param environment - Target environment
+   * @param platform - User platform
+   * @returns Basic anonymous context
+   */
+  createAnonymousContext(environment, platform = "web") {
+    return new FeatureFlagContextBuilder().setEnvironment(environment).setPlatform(platform).build();
+  },
+  /**
+   * Creates a context for authenticated users using the builder.
+   *
+   * @param params - User context parameters
+   * @returns User context
+   */
+  createUserContext(params) {
+    const builder = new FeatureFlagContextBuilder().setUserId(params.userId).setEnvironment(params.environment);
+    if (params.userEmail) builder.setUserEmail(params.userEmail);
+    if (params.userRole) builder.setUserRole(params.userRole);
+    if (params.platform) builder.setPlatform(params.platform);
+    if (params.country) builder.setCountry(params.country);
+    if (params.version) builder.setVersion(params.version);
+    if (params.custom) builder.setCustom(params.custom);
+    return builder.build();
+  },
+  /**
+   * Creates a testing context with minimal required fields.
+   *
+   * @param overrides - Optional context overrides
+   * @returns Testing context
+   */
+  createTestingContext(overrides = {}) {
+    return {
+      environment: "development",
+      platform: "web",
+      ...overrides
+    };
+  },
+  /**
+   * Validates if a context object is complete and valid.
+   *
+   * @param context - Context to validate
+   * @returns Validation result
+   */
+  validateContext(context) {
+    const errors = [];
+    if (!context.environment) {
+      errors.push("Environment is required");
+    } else if (!["development", "staging", "production"].includes(context.environment)) {
+      errors.push("Environment must be development, staging, or production");
+    }
+    if (context.platform && !["web", "mobile", "desktop"].includes(context.platform)) {
+      errors.push("Platform must be web, mobile, or desktop");
+    }
+    if (context.country && context.country.length !== config.ISO_STANDARDS.ISO_COUNTRY_CODE_LENGTH) {
+      errors.push("Country must be a 2-letter ISO country code");
+    }
+    return {
+      isValid: errors.length === 0,
+      errors
+    };
+  },
+  /**
+   * Merges multiple context objects, with later contexts taking precedence.
+   *
+   * @param contexts - Array of contexts to merge
+   * @returns Merged context
+   */
+  mergeContexts(...contexts) {
+    const merged = contexts.reduce((acc, context) => {
+      const result = {
+        ...acc,
+        ...context
+      };
+      if (acc.custom || context.custom) {
+        result.custom = {
+          ...acc.custom,
+          ...context.custom
+        };
+      }
+      return result;
+    }, {});
+    merged.environment ??= "development";
+    return merged;
+  },
+  /**
+   * Extracts a specific field value from a context.
+   *
+   * @param field - Field name to extract
+   * @param context - Context object
+   * @returns Field value or undefined
+   */
+  getContextValue(field, context) {
+    const standardFields = {
+      userId: /* @__PURE__ */ __name((ctx) => ctx.userId, "userId"),
+      userEmail: /* @__PURE__ */ __name((ctx) => ctx.userEmail, "userEmail"),
+      userRole: /* @__PURE__ */ __name((ctx) => ctx.userRole, "userRole"),
+      country: /* @__PURE__ */ __name((ctx) => ctx.country, "country"),
+      platform: /* @__PURE__ */ __name((ctx) => ctx.platform, "platform"),
+      version: /* @__PURE__ */ __name((ctx) => ctx.version, "version"),
+      environment: /* @__PURE__ */ __name((ctx) => ctx.environment, "environment"),
+      custom: /* @__PURE__ */ __name((ctx) => ctx.custom, "custom")
+    };
+    if (field in standardFields) {
+      return standardFields[field](context);
+    }
+    return context.custom?.[field];
+  },
+  /**
+   * Creates a context fingerprint for caching and consistency.
+   *
+   * @param context - Context to fingerprint
+   * @returns String fingerprint
+   */
+  createFingerprint(context) {
+    const relevant = {
+      userId: context.userId,
+      userRole: context.userRole,
+      environment: context.environment,
+      platform: context.platform,
+      country: context.country,
+      version: context.version,
+      custom: context.custom
+    };
+    const filtered = Object.entries(relevant).filter(([, value]) => value !== void 0).sort(([a], [b]) => a.localeCompare(b)).reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {});
+    return JSON.stringify(filtered);
+  },
+  /**
+   * Sanitizes a context by removing sensitive information.
+   *
+   * @param context - Context to sanitize
+   * @param sensitiveFields - Fields to remove (default: ['userEmail'])
+   * @returns Sanitized context
+   */
+  sanitizeContext(context, sensitiveFields = ["userEmail"]) {
+    const sanitized = { ...context };
+    if (context.custom) {
+      sanitized.custom = { ...context.custom };
+    }
+    for (const field of sensitiveFields) {
+      if (field in sanitized) {
+        delete sanitized[field];
+      }
+      if (sanitized.custom && field in sanitized.custom) {
+        delete sanitized.custom[field];
+      }
+    }
+    return sanitized;
+  }
+};
+function createBackendContext(params) {
+  return {
+    environment: params.environment,
+    userId: params.userId,
+    userEmail: params.userEmail,
+    userRole: params.userRole,
+    platform: params.platform ?? "api",
+    country: params.country,
+    version: params.version,
+    custom: params.custom
+  };
+}
+__name(createBackendContext, "createBackendContext");
+function createFrontendContext(params) {
+  return {
+    environment: params.environment,
+    userId: params.userId,
+    userEmail: params.userEmail,
+    userRole: params.userRole,
+    platform: params.platform ?? "web",
+    country: params.country,
+    version: params.version,
+    custom: params.custom
+  };
+}
+__name(createFrontendContext, "createFrontendContext");
+function evaluateConditionOperator(condition, contextValue) {
+  const { operator } = condition;
+  if (isEqualityOperator(operator)) {
+    return evaluateEqualityOperator(operator, contextValue, condition.value);
+  }
+  if (isStringOperator(operator)) {
+    return evaluateStringOperator(operator, contextValue, condition.value);
+  }
+  if (isArrayOperator(operator)) {
+    return evaluateArrayOperator(operator, condition.value, contextValue);
+  }
+  if (isNumericOperator(operator)) {
+    return evaluateNumericOperator(operator, contextValue, condition.value);
+  }
+  return false;
+}
+__name(evaluateConditionOperator, "evaluateConditionOperator");
+function isEqualityOperator(operator) {
+  return operator === "equals" || operator === "not_equals";
+}
+__name(isEqualityOperator, "isEqualityOperator");
+function isStringOperator(operator) {
+  return operator === "contains" || operator === "not_contains";
+}
+__name(isStringOperator, "isStringOperator");
+function isArrayOperator(operator) {
+  return operator === "in" || operator === "not_in";
+}
+__name(isArrayOperator, "isArrayOperator");
+function isNumericOperator(operator) {
+  return operator === "greater_than" || operator === "less_than";
+}
+__name(isNumericOperator, "isNumericOperator");
+function evaluateEqualityOperator(operator, contextValue, conditionValue) {
+  const isEqual = contextValue === conditionValue;
+  return operator === "equals" ? isEqual : !isEqual;
+}
+__name(evaluateEqualityOperator, "evaluateEqualityOperator");
+function evaluateStringOperator(operator, contextValue, conditionValue) {
+  if (typeof contextValue === "string" && typeof conditionValue === "string") {
+    const contains = contextValue.includes(conditionValue);
+    return operator === "contains" ? contains : !contains;
+  }
+  if (Array.isArray(contextValue) && typeof conditionValue === "string") {
+    const contains = contextValue.includes(conditionValue);
+    return operator === "contains" ? contains : !contains;
+  }
+  return operator === "not_contains";
+}
+__name(evaluateStringOperator, "evaluateStringOperator");
+function evaluateArrayOperator(operator, conditionValue, contextValue) {
+  if (!Array.isArray(conditionValue)) {
+    return operator === "not_in";
+  }
+  const isIncluded = conditionValue.includes(contextValue);
+  return operator === "in" ? isIncluded : !isIncluded;
+}
+__name(evaluateArrayOperator, "evaluateArrayOperator");
+function compareValues(operator, left, right) {
+  switch (operator) {
+    case "greater_than":
+      return left > right;
+    case "less_than":
+      return left < right;
+    default:
+      return false;
+  }
+}
+__name(compareValues, "compareValues");
+function evaluateNumericOperator(operator, contextValue, conditionValue) {
+  const contextNum = Number(contextValue);
+  const conditionNum = Number(conditionValue);
+  if (!isNaN(contextNum) && !isNaN(conditionNum)) {
+    return compareValues(operator, contextNum, conditionNum);
+  }
+  if (typeof contextValue === "string" && typeof conditionValue === "string") {
+    return compareValues(operator, contextValue, conditionValue);
+  }
+  return false;
+}
+__name(evaluateNumericOperator, "evaluateNumericOperator");
+var ConditionUtils = {
+  /**
+   * Evaluates multiple conditions with AND logic.
+   *
+   * @param conditions - Array of conditions
+   * @param contextValue - Context value getter function
+   * @returns true if all conditions match
+   */
+  evaluateConditionsAnd: /* @__PURE__ */ __name((conditions, contextValue) => {
+    if (conditions.length === 0) return true;
+    return conditions.every((condition) => {
+      const value = contextValue(condition.field);
+      if (value === void 0) return false;
+      return evaluateConditionOperator(condition, value);
+    });
+  }, "evaluateConditionsAnd"),
+  /**
+   * Evaluates multiple conditions with OR logic.
+   *
+   * @param conditions - Array of conditions
+   * @param contextValue - Context value getter function
+   * @returns true if any condition matches
+   */
+  evaluateConditionsOr: /* @__PURE__ */ __name((conditions, contextValue) => {
+    if (conditions.length === 0) return true;
+    return conditions.some((condition) => {
+      const value = contextValue(condition.field);
+      if (value === void 0) return false;
+      return evaluateConditionOperator(condition, value);
+    });
+  }, "evaluateConditionsOr"),
+  /**
+   * Validates a condition structure.
+   *
+   * @param condition - Condition to validate
+   * @returns Validation result
+   */
+  validateCondition: /* @__PURE__ */ __name((condition) => {
+    const errors = [];
+    if (!condition.field) {
+      errors.push("Field is required");
+    }
+    if (!condition.operator) {
+      errors.push("Operator is required");
+    } else {
+      const validOperators = [
+        "equals",
+        "not_equals",
+        "contains",
+        "not_contains",
+        "in",
+        "not_in",
+        "greater_than",
+        "less_than"
+      ];
+      if (!validOperators.includes(condition.operator)) {
+        errors.push(`Invalid operator: ${condition.operator}`);
+      }
+    }
+    if (condition.value === void 0) {
+      errors.push("Value is required");
+    }
+    return {
+      isValid: errors.length === 0,
+      errors
+    };
+  }, "validateCondition"),
+  /**
+   * Creates a condition object with validation.
+   *
+   * @param field - Context field to evaluate
+   * @param operator - Comparison operator
+   * @param value - Value to compare against
+   * @returns Valid condition object
+   */
+  createCondition: /* @__PURE__ */ __name((field, operator, value) => {
+    const condition = { field, operator, value };
+    const validation = ConditionUtils.validateCondition(condition);
+    if (!validation.isValid) {
+      throw new errors.CorePackageError(
+        `Invalid condition: ${validation.errors.join(", ")}`,
+        types.ERROR_CODES.VALIDATION_ERROR
+      );
+    }
+    return condition;
+  }, "createCondition")
+};
+var getGlobalProperty = /* @__PURE__ */ __name((key) => {
+  return globalThis[key];
+}, "getGlobalProperty");
+var logger = new logger$1.PackageLogger({ packageName: "core", service: "Runtime" });
+function isModuleAvailable(moduleName) {
+  const nodeRequire = globalThis.require;
+  if (!nodeRequire) return false;
+  const resolveModule = nodeRequire.resolve;
+  if (!resolveModule) return false;
+  try {
+    resolveModule(moduleName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+__name(isModuleAvailable, "isModuleAvailable");
+function detectAltRuntime() {
+  if (typeof getGlobalProperty("Deno") !== "undefined") return "deno";
+  if (typeof getGlobalProperty("Bun") !== "undefined") return "bun";
+  return null;
+}
+__name(detectAltRuntime, "detectAltRuntime");
+function detectEdgeRuntime() {
+  if (typeof getGlobalProperty("EdgeRuntime") !== "undefined") return "edge";
+  const isEdgeLike = typeof globalThis.caches !== "undefined" && typeof globalThis.Request !== "undefined" && typeof process === "undefined";
+  return isEdgeLike ? "edge" : null;
+}
+__name(detectEdgeRuntime, "detectEdgeRuntime");
+function detectBrowser() {
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  return null;
+}
+__name(detectBrowser, "detectBrowser");
+function detectNodeFramework() {
+  if (process.env.__NUXT__ || process.env.NUXT_APP) return "nuxt";
+  if (process.env.__NEXT_PRIVATE_ORIGIN || process.env.NEXT_RUNTIME) return "nextjs";
+  if (isModuleAvailable("@nestjs/core")) return "nestjs";
+  if (isModuleAvailable("express")) return "express";
+  return "node";
+}
+__name(detectNodeFramework, "detectNodeFramework");
+function detectRuntime() {
+  const altRuntime = detectAltRuntime();
+  if (altRuntime) return altRuntime;
+  const edgeRuntime = detectEdgeRuntime();
+  if (edgeRuntime) return edgeRuntime;
+  const browser = detectBrowser();
+  if (browser) return browser;
+  if (typeof process !== "undefined" && process.versions?.node) {
+    return detectNodeFramework();
+  }
+  return "unknown";
+}
+__name(detectRuntime, "detectRuntime");
+async function loadEnvFile(envPath, verbose) {
+  try {
+    const dotenv = await import('dotenv');
+    const result = dotenv.config({ path: envPath });
+    if (result.error) {
+      logger.warn(`Failed to load env file: ${result.error.message}`);
+    } else if (verbose) {
+      logger.info(`Loaded env from: ${envPath}`);
+    }
+  } catch {
+    logger.warn("dotenv not available, skipping .env file loading");
+  }
+}
+__name(loadEnvFile, "loadEnvFile");
+var FILE_KEY_FULL_PATH_SEGMENTS = 4;
+var FILE_KEY_THREE_SEGMENTS = 3;
+var FILE_KEY_TWO_SEGMENTS = 2;
+var MIME_TYPE_PARTS = 2;
+function fileToBase64(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      const result = reader.result;
+      const base64 = result.split(",")[1] || result;
+      resolve(base64);
+    };
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+}
+__name(fileToBase64, "fileToBase64");
+function base64ToBlob(base64, mimeType = "application/octet-stream") {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new Blob([bytes], { type: mimeType });
+}
+__name(base64ToBlob, "base64ToBlob");
+function base64ToBuffer(base64) {
+  return Buffer.from(base64, "base64");
+}
+__name(base64ToBuffer, "base64ToBuffer");
+function bufferToBase64(data) {
+  if (Buffer.isBuffer(data)) {
+    return data.toString("base64");
+  }
+  return Buffer.from(data).toString("base64");
+}
+__name(bufferToBase64, "bufferToBase64");
+function downloadBlob(blob, filename) {
+  const win = globalThis;
+  if (!win.document) return;
+  const url = URL.createObjectURL(blob);
+  const a = win.document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  win.document.body.appendChild(a);
+  a.click();
+  win.document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+__name(downloadBlob, "downloadBlob");
+function downloadBase64(base64, filename, mimeType = "application/octet-stream") {
+  const blob = base64ToBlob(base64, mimeType);
+  downloadBlob(blob, filename);
+}
+__name(downloadBase64, "downloadBase64");
+function parseFileKey(key) {
+  const parts = key.split("/");
+  const result = { raw: key };
+  if (parts.length >= FILE_KEY_FULL_PATH_SEGMENTS) {
+    result.entityType = parts[0];
+    result.entityId = parts[1];
+    result.category = parts[2];
+    result.filename = parts.slice(FILE_KEY_THREE_SEGMENTS).join("/");
+  } else if (parts.length === FILE_KEY_THREE_SEGMENTS) {
+    result.entityType = parts[0];
+    result.entityId = parts[1];
+    result.filename = parts[FILE_KEY_TWO_SEGMENTS];
+  } else if (parts.length === FILE_KEY_TWO_SEGMENTS) {
+    result.category = parts[0];
+    result.filename = parts[1];
+  } else {
+    result.filename = parts[0];
+  }
+  return result;
+}
+__name(parseFileKey, "parseFileKey");
+function getFilenameFromKey(key) {
+  return key.split("/").pop() ?? key;
+}
+__name(getFilenameFromKey, "getFilenameFromKey");
+function generateFilename(templateId, outputFormat) {
+  const baseName = templateId.split("/").pop() ?? "document";
+  return `${baseName}.${outputFormat}`;
+}
+__name(generateFilename, "generateFilename");
+function generateUniqueFilename(prefix = "file", extension = "bin") {
+  return `${prefix}-${Date.now()}.${extension}`;
+}
+__name(generateUniqueFilename, "generateUniqueFilename");
+function inferExtensionFromMimeType(mimeType) {
+  if (core.MIME_TYPE_EXTENSIONS[mimeType]) {
+    return core.MIME_TYPE_EXTENSIONS[mimeType];
+  }
+  const parts = mimeType.split("/");
+  if (parts.length === MIME_TYPE_PARTS) {
+    return parts[1].split(";")[0].trim();
+  }
+  return "bin";
+}
+__name(inferExtensionFromMimeType, "inferExtensionFromMimeType");
+function formatFileSize(bytes, decimals = 2) {
+  if (bytes === 0) return "0 Bytes";
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  const size = Number.parseFloat((bytes / Math.pow(k, i)).toFixed(dm));
+  return `${size} ${core.FILE_SIZE_UNITS[i]}`;
+}
+__name(formatFileSize, "formatFileSize");
+function parseFileSize(sizeString) {
+  const match = sizeString.trim().match(/^([\d.]+)\s*([A-Z]+)$/i);
+  if (!match) {
+    return Number.parseInt(sizeString, 10) || 0;
+  }
+  const value = Number.parseFloat(match[1]);
+  const unit = match[2].toUpperCase();
+  return Math.round(value * (core.FILE_SIZE_MULTIPLIERS[unit] ?? 1));
+}
+__name(parseFileSize, "parseFileSize");
+
+// src/utils/hmr-singleton.ts
+var GLOBAL_PREFIX = "__plyaz_hmr_singleton__";
+function hasResetMethod(obj) {
+  return typeof obj === "object" && obj !== null && "reset" in obj && typeof obj.reset === "function";
+}
+__name(hasResetMethod, "hasResetMethod");
+function createHmrSafeSingleton(key, initializer, options = {}) {
+  const { onInitialized, onError, onReset } = options;
+  const instanceKey = `${GLOBAL_PREFIX}${key}_instance`;
+  const promiseKey = `${GLOBAL_PREFIX}${key}_promise`;
+  const initializedKey = `${GLOBAL_PREFIX}${key}_initialized`;
+  const g = globalThis;
+  function getInstance() {
+    return g[instanceKey];
+  }
+  __name(getInstance, "getInstance");
+  function setInstance(instance) {
+    g[instanceKey] = instance;
+  }
+  __name(setInstance, "setInstance");
+  function clearInstance() {
+    delete g[instanceKey];
+  }
+  __name(clearInstance, "clearInstance");
+  function getPromise() {
+    return g[promiseKey];
+  }
+  __name(getPromise, "getPromise");
+  function setPromise(promise) {
+    if (promise === null) {
+      delete g[promiseKey];
+    } else {
+      g[promiseKey] = promise;
+    }
+  }
+  __name(setPromise, "setPromise");
+  function isInit() {
+    return g[initializedKey] === true;
+  }
+  __name(isInit, "isInit");
+  function setInit(value) {
+    g[initializedKey] = value;
+  }
+  __name(setInit, "setInit");
+  async function accessor() {
+    if (isInit()) {
+      const instance = getInstance();
+      if (instance !== void 0) {
+        return instance;
+      }
+    }
+    const existingPromise = getPromise();
+    if (existingPromise) {
+      return existingPromise;
+    }
+    const initPromise = (async () => {
+      try {
+        const instance = await initializer();
+        setInstance(instance);
+        setInit(true);
+        onInitialized?.();
+        return instance;
+      } catch (err) {
+        setPromise(null);
+        const error = err instanceof Error ? err : new Error(String(err));
+        onError?.(error);
+        throw error;
+      }
+    })();
+    setPromise(initPromise);
+    return initPromise;
+  }
+  __name(accessor, "accessor");
+  accessor.isInitialized = () => isInit();
+  accessor.reset = async () => {
+    if (isInit()) {
+      const instance = getInstance();
+      if (hasResetMethod(instance)) {
+        await instance.reset();
+      }
+      clearInstance();
+      setInit(false);
+      setPromise(null);
+      onReset?.();
+    }
+  };
+  return accessor;
+}
+__name(createHmrSafeSingleton, "createHmrSafeSingleton");
+
+exports.ConditionUtils = ConditionUtils;
+exports.ContextUtils = ContextUtils;
+exports.FeatureFlagContextBuilder = FeatureFlagContextBuilder;
+exports.HashUtils = HashUtils;
+exports.IdUtils = IdUtils;
+exports.ObjectUtils = ObjectUtils;
+exports.TypeGuardUtils = TypeGuardUtils;
+exports.ValueUtils = ValueUtils;
+exports.base64ToBlob = base64ToBlob;
+exports.base64ToBuffer = base64ToBuffer;
+exports.bufferToBase64 = bufferToBase64;
+exports.createBackendContext = createBackendContext;
+exports.createFrontendContext = createFrontendContext;
+exports.createHmrSafeSingleton = createHmrSafeSingleton;
+exports.createRolloutIdentifier = createRolloutIdentifier;
+exports.detectRuntime = detectRuntime;
+exports.downloadBase64 = downloadBase64;
+exports.downloadBlob = downloadBlob;
+exports.evaluateArrayOperator = evaluateArrayOperator;
+exports.evaluateConditionOperator = evaluateConditionOperator;
+exports.evaluateEqualityOperator = evaluateEqualityOperator;
+exports.evaluateNumericOperator = evaluateNumericOperator;
+exports.evaluateStringOperator = evaluateStringOperator;
+exports.fileToBase64 = fileToBase64;
+exports.formatFileSize = formatFileSize;
+exports.generateCorrelationId = generateCorrelationId;
+exports.generateFilename = generateFilename;
+exports.generateId = generateId;
+exports.generateShortId = generateShortId;
+exports.generateSpanId = generateSpanId;
+exports.generateTraceId = generateTraceId;
+exports.generateUniqueFilename = generateUniqueFilename;
+exports.getFilenameFromKey = getFilenameFromKey;
+exports.getNestedProperty = getNestedProperty;
+exports.getValidProviders = getValidProviders;
+exports.hasNestedProperty = hasNestedProperty;
+exports.hasProperty = hasProperty;
+exports.hashString = hashString;
+exports.inferExtensionFromMimeType = inferExtensionFromMimeType;
+exports.isArrayOperator = isArrayOperator;
+exports.isDefined = isDefined;
+exports.isEqualityOperator = isEqualityOperator;
+exports.isInRollout = isInRollout;
+exports.isNumber = isNumber;
+exports.isNumericOperator = isNumericOperator;
+exports.isObject = isObject;
+exports.isString = isString;
+exports.isStringOperator = isStringOperator;
+exports.isTruthy = isTruthy;
+exports.isValidUUID = isValidUUID;
+exports.loadEnvFile = loadEnvFile;
+exports.parseFileKey = parseFileKey;
+exports.parseFileSize = parseFileSize;
+exports.setNestedProperty = setNestedProperty;
+exports.toBoolean = toBoolean;
+exports.toNumber = toNumber;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map