@ylsoo/core 2.0.0 → 2.0.1

package/README.md

@@ -1,18 +1,18 @@
 <div align="center">
-  <h1>@ylsoo/core (v2.0 Enterprise)</h1>
-  <p><b>The official, enterprise-grade SDK powering advanced Ylsoo web and server products.</b></p>
+  <h1>@ylsoo/core (v2.2 Enterprise)</h1>
+  <p><b>The absolute standard in enterprise SDK architecture.</b></p>
   
   [![npm version](https://img.shields.io/npm/v/@ylsoo/core.svg?style=flat-square)](https://www.npmjs.com/package/@ylsoo/core)
   [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
   [![TypeScript Ready](https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
-  [![Cross-Platform](https://img.shields.io/badge/Cross--Platform-Node.js%20%7C%20Browser-brightgreen?style=flat-square)](#)
+  [![Zero Defaults](https://img.shields.io/badge/Dependencies-0-brightgreen?style=flat-square)](#)
 </div>
 
 <hr>
 
 ## 🚀 Overview
 
-`@ylsoo/core` v2 has been completely rewritten into a powerful, modular architecture. It provides blazing-fast utility functions designed specifically for Ylsoo services. It runs identically on **modern browsers** and **Node.js** servers thanks to custom polyfills acting entirely natively, without a single external dependency!
+`@ylsoo/core` v2.2 introduces tier-1 routing capabilities and highly rigorous A/B target evaluation. Everything operates entirely on native standard technologies, avoiding the devastating payload bloat of common frameworks.
 
 ## 📦 Installation
 
@@ -20,74 +20,72 @@
 npm i @ylsoo/core
 ```
 
-## 🛠️ API Reference
+## 🛠️ V2.2 Enterprise Architecture Models
 
-### 1. 🔐 Distributed Security (`ylsoo.crypto`)
-Leverages Web Crypto API natively to perform secure operations identically across browsers and servers.
-```javascript
-const ylsoo = require('@ylsoo/core');
-
-// 1. Generate Secure V4 UUIDs
-const sessionID = ylsoo.crypto.uuid();
-
-// 2. Hash strings natively
-const secretHash = await ylsoo.crypto.hash('my_super_secret');
+### 1. 🛣️ Professional DOM Router (`ylsoo.router`)
+An incredibly capable HTML5 Frontend matcher mimicking heavily advanced Vue/React dynamics.
 
-// 3. Encode/Decode Base64
-const encoded = ylsoo.crypto.encodeBase64('user:pass');
-```
+- **Dynamic Constraints**: Extracts `/:id/` params cleanly into variables.
+- **Middleware Control**: Provides `beforeEach()` to easily intercept and blockade navigations dynamically.
+- **Click Hijacking**: Automatically binds to HTML5 PushState and catches `data-route` click events!
 
-### 2. ⚡ Event Bus (`ylsoo.events`)
-An enterprise Publisher/Subscriber mechanism to handle inter-component state within Ylsoo frontends or microservices.
 ```javascript
-// Component A (Subscribes)
-const unsubscribe = ylsoo.events.on('user:login', (user) => {
-  console.log('Welcome back,', user.name);
+// 1. Build an Authentication Middleware Guard
+ylsoo.router.beforeEach((to, from, next) => {
+  if (to.includes('admin') && !loggedIn) next(false); // Halt routing
 });
 
-// Component B (Publishes)
-ylsoo.events.emit('user:login', { name: 'Admin' });
+// 2. Configure Dynamic Deep Routes
+ylsoo.router.add('/users/:id/billing', (route) => {
+  console.log('Loading Billing For User:', route.params.id);
+});
 
-// Listen exactly once
-ylsoo.events.once('system:boot', bootFunction);
+ylsoo.router.start();
 ```
 
-### 3. 🌐 Ylsoo Request Engine (`ylsoo.http`)
-A robust wrapper around the versatile `fetch` API. It handles JSON stringification, applies custom headers, parses JSON, and safely formats errors automatically.
+### 2. 🎛️ Deterministic A/B Flags (`ylsoo.feature`)
+Not just a switch. A true matrix evaluation engine utilizing cryptographic hashing to guarantee specific users continuously load the exact same "random" feature buckets.
+
 ```javascript
-async function fetchUserData() {
-  try {
-    const data = await ylsoo.http.get('https://api.ylsoo.com/v1/user/me');
-  } catch (error) {
-    ylsoo.logger.error('Failed to fetch user', error);
-  }
+// Force the dashboard to turn on ONLY for:
+// 1) Exactly 25% of traffic
+// 2) Users whose attributes dictate they live in the UK
+ylsoo.feature.setFlag('beta_dashboard', {
+  enabled: true,
+  rolloutPercentage: 25,
+  conditions: { country: 'UK' }
+});
+
+// Execution check during login
+const userContext = { userId: "uuid-123", attributes: { country: 'UK' }};
+
+if (await ylsoo.feature.evaluate('beta_dashboard', userContext)) {
+  console.log('User Granted Beta Access');
 }
 ```
 
-### 4. 🧠 Ylsoo Memory Cache (`ylsoo.cache`)
-A volatile in-memory Map structure featuring native Time-To-Live (TTL) functionality.
+### 3. 🛡️ Resilience Core (`ylsoo.resilience`)
+- **`withRetry(fn)`**: Wraps flaky API calls and repeats them on an exponential delay loop (e.g. 1s... 2s... 4s...) rather than immediately panicking.
+- **`createBreaker(fn)`**: Operates a Circuit Breaker algorithm to instantly cut network traffic down if an upstream service goes offline, protecting your node instances from dead-locking.
+
+### 4. 🕐 Precise Time Formatter (`ylsoo.time`)
+Completely strips the need for massive `moment.js` dependency packets. Quickly parses standard intervals.
 ```javascript
-// Cache an object for 5000 ms (5 seconds)
-ylsoo.cache.set('session', { id: 123 }, 5000);
-const session = ylsoo.cache.get('session');
+ylsoo.time.format(Date.now(), "YYYY-MM-DD HH:mm:ss"); 
+ylsoo.time.timeAgo(oldDate); // "5 minutes ago"
 ```
 
-### 5. 🖥️ Ylsoo Console (`ylsoo.logger`)
-Formatted console utility employing native ANSI escape codes specifically designed for local backends.
+### 5. 🗄️ Strict Config Matrix (`ylsoo.config`)
+A deep-merging configurations orchestrator. Implements `.freeze()` architecture to physically lock constants into memory, violently blocking any injected bad code downstream from maliciously altering your `API_KEYS`.
+
+### 6. 🗃️ Concurrency Queue (`ylsoo.createQueue`)
+Need thousands of promises to compute, but executing them simultaneously throttles your CPU? Assign them to a limit.
 ```javascript
-ylsoo.logger.info('System initializing...');
-ylsoo.logger.success('Database connected successfully!');
-ylsoo.logger.warn('Rate limit approaching.');
-ylsoo.logger.error('Critical failure detected.');
+const q = ylsoo.createQueue(5); // Throttle process to exactly 5 lanes
+q.add(() => fetchBigData1());
+q.add(() => fetchBigData2());
 ```
 
-### 6. 🧰 Native Enterprise Utilies 
-- **`ylsoo.sleep(ms)`**: Promise-based execution halter.
-- **`ylsoo.deepClone(obj)`**: Safely deep clones utilizing native modern standards like `structuredClone` when available.
-- **`ylsoo.debounce(func, wait)`**: High performance throttling mechanics.
-- **`ylsoo.isEmpty(val)`**: Semantic entity verification (detects empty Sets, Maps, Objects, Strings, Arrays).
-- **`ylsoo.capitalize(str)`**: Automatic string standardizer.
-
 ---
 <div align="center">
   <p>Built with ❤️ by <b>Ylsoo</b>.</p>

package/index.d.ts

@@ -1,12 +1,11 @@
 /**
- * @ylsoo/core v2.0.0 Type Definitions
- * Cross-platform Enterprise SDK
+ * @ylsoo/core v2.2.0 Type Definitions
+ * Enterprise Cross-Platform SDK
  */
 
 declare module '@ylsoo/core' {
 
-  // --- Core Modules ---
-
+  // --- Base Systems ---
   export class YlsooLogger {
       info(message: string | any): void;
       success(message: string | any): void;
@@ -21,72 +20,121 @@ declare module '@ylsoo/core' {
       clear(): void;
   }
 
-  export interface YlsooHttpOptions {
-      method?: string;
-      headers?: Record<string, string>;
-      body?: any;
-      [key: string]: any;
-  }
-
   export class YlsooHttp {
-      request<T = any>(endpoint: string, options?: YlsooHttpOptions): Promise<T>;
-      get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<T>;
-      post<T = any>(endpoint: string, body: any, headers?: Record<string, string>): Promise<T>;
+      request<T = any>(endpoint: string, options?: any): Promise<T>;
+      get<T = any>(endpoint: string, headers?: any): Promise<T>;
+      post<T = any>(endpoint: string, body: any, headers?: any): Promise<T>;
   }
 
-  // --- Security Modules ---
-
+  // --- Security & Process ---
   export class YlsooCrypto {
-      /** Base64 encodes a utf-8 string securely */
       encodeBase64(str: string): string;
-      
-      /** Base64 decodes a string */
       decodeBase64(base64: string): string;
-      
-      /** Natively generates a secure SHA-256 hash */
       hash(str: string): Promise<string>;
-
-      /** Generates a cryptographically strong v4 UUID */
       uuid(): string;
   }
 
-  // --- Event Modules ---
-
   export class YlsooEventBus {
-      /** Subscribe to an event. Returns an unsubscribe function. */
       on(event: string, callback: (data?: any) => void): () => void;
-      
-      /** Unsubscribe from an event. */
       off(event: string, callback: (data?: any) => void): void;
-      
-      /** Publish an event to all subscribers. */
       emit(event: string, data?: any): void;
-
-      /** Subscribe to an event, un-subscribing immediately after first emission. */
       once(event: string, callback: (data?: any) => void): void;
-
-      /** clear all event listeners */
       clear(): void;
   }
 
-  // --- Main Export ---
+  // --- State & Config ---
+  export class YlsooState {
+      setup(key: string, initialValue?: any): void;
+      get<T = any>(key: string): T;
+      set(key: string, value: any): void;
+      subscribe<T = any>(key: string, callback: (val: T) => void): () => void;
+  }
+
+  export class YlsooStorage {
+      set(key: string, value: any): void;
+      get<T = any>(key: string): T | null;
+      remove(key: string): void;
+  }
+
+  export class YlsooConfig {
+      setDefault(defaults: Record<string, any>): void;
+      applyEnvironment(envOverrides: Record<string, any>): void;
+      freeze(): void;
+      get<T = any>(key?: string | null): T;
+  }
+
+  export class YlsooFeatureFlags {
+      setFlag(flagName: string, rules: { enabled?: boolean, rolloutPercentage?: number, conditions?: Record<string, any> }): void;
+      evaluate(flagName: string, context?: { userId?: string, attributes?: Record<string, any> }): Promise<boolean>;
+  }
 
+  // --- Flow & Routers ---
+  export class YlsooRouter {
+      beforeEach(hook: (to: string, from: string, next: (confirm?: boolean) => void) => void): void;
+      add(path: string, handler: (route: { params: any, query: any, path: string }) => void): void;
+      setFallback(handler: (route: { path: string, query: any }) => void): void;
+      start(): void;
+      push(path: string): void;
+  }
+
+  export class YlsooResilience {
+      withRetry<T>(asyncFunction: () => Promise<T>, maxRetries?: number, baseDelayMs?: number): Promise<T>;
+      createBreaker<T>(asyncFunction: (...args: any[]) => Promise<T>, options?: any): (...args: any[]) => Promise<T>;
+  }
+
+  export class YlsooTaskQueue {
+      constructor(concurrencyLimit?: number);
+      add<T>(asyncTask: () => Promise<T>): Promise<T>;
+      get remaining(): number;
+  }
+
+  // --- Micro Utils ---
+  export class YlsooAnalytics {
+      configure(options: any): void;
+      track(eventName: string, metadata?: any): void;
+  }
+
+  export class Ylsoo18n {
+      load(locale: string, dict: Record<string, string>): void;
+      setLocale(locale: string): void;
+      t(key: string, variables?: Record<string, string>): string;
+  }
+
+  export class YlsooTime {
+      format(date: Date | number | string, formatStr?: string): string | null;
+      timeAgo(date: Date | number | string): string;
+  }
+
+  // --- Main Export ---
   export class YlsooCore {
       version: string;
       
-      // Systems
-      logger: YlsooLogger;
+      crypto: YlsooCrypto;
+      config: YlsooConfig;
+      router: YlsooRouter;
+      feature: YlsooFeatureFlags;
+      
+      state: YlsooState;
       cache: YlsooCache;
+      storage: YlsooStorage;
+      
       http: YlsooHttp;
-      crypto: YlsooCrypto;
       events: YlsooEventBus;
+      resilience: YlsooResilience;
+      analytics: YlsooAnalytics;
+      
+      logger: YlsooLogger;
+      time: YlsooTime;
+      i18n: Ylsoo18n;
 
-      // Utilities
       sleep(ms: number): Promise<void>;
       deepClone<T>(obj: T): T;
       debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
       isEmpty(value: any): boolean;
       capitalize(str: string): string;
+      
+      validate(data: any, schema: Record<string, any>): boolean;
+      createQueue(limit?: number): YlsooTaskQueue;
   }
 
   const ylsoo: YlsooCore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ylsoo/core",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Enterprise cross-platform SDK for Ylsoo projects",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -17,12 +17,13 @@
     "core",
     "enterprise",
     "sdk",
-    "fetch",
-    "logger",
-    "cache",
-    "crypto",
-    "uuid",
-    "events"
+    "router",
+    "feature-flags",
+    "ab-testing",
+    "circuit-breaker",
+    "retry",
+    "queue",
+    "time"
   ],
   "author": "Ylsoo",
   "license": "MIT",

package/src/core/analytics.js

@@ -0,0 +1,66 @@
+class YlsooAnalytics {
+  constructor(httpEngine) {
+    this.http = httpEngine;
+    this.queue = [];
+    this.config = {
+      endpoint: null,    // User must set this via configure()
+      batchSize: 10,     // Flush after 10 events
+      flushInterval: 5000 // Or flush every 5 seconds
+    };
+    
+    this.timer = null;
+  }
+
+  configure(options) {
+    this.config = { ...this.config, ...options };
+    this._startTimer();
+  }
+
+  /**
+   * Silently track an event
+   * @param {string} eventName 
+   * @param {object} metadata 
+   */
+  track(eventName, metadata = {}) {
+    this.queue.push({
+      event: eventName,
+      data: metadata,
+      timestamp: new Date().toISOString()
+    });
+
+    if (this.queue.length >= this.config.batchSize) {
+      this.flush();
+    }
+  }
+
+  async flush() {
+    if (this.queue.length === 0 || !this.config.endpoint) return;
+
+    const payload = [...this.queue];
+    this.queue = []; // clear early to prevent race conditions
+
+    try {
+      // Intentionally suppress errors to stay silent
+      await this.http.post(this.config.endpoint, { events: payload });
+    } catch(err) {
+      // Re-queue on fail
+      this.queue = [...payload, ...this.queue];
+    }
+  }
+
+  _startTimer() {
+    if (this.timer) clearInterval(this.timer);
+    
+    // In Node or Browser, setInterval is standard
+    this.timer = setInterval(() => {
+      this.flush();
+    }, this.config.flushInterval);
+    
+    // In node, unref the timer to prevent keeping the process alive
+    if (typeof this.timer.unref === 'function') {
+      this.timer.unref();
+    }
+  }
+}
+
+module.exports = { YlsooAnalytics };

package/src/core/i18n.js

@@ -0,0 +1,42 @@
+class Ylsoo18n {
+  constructor() {
+    this.dictionary = {};
+    this.locale = 'en';
+  }
+
+  /**
+   * Load a language dictionary into memory
+   * @param {string} locale
+   * @param {object} dict 
+   */
+  load(locale, dict) {
+    this.dictionary[locale] = dict;
+  }
+
+  setLocale(locale) {
+    this.locale = locale;
+  }
+
+  /**
+   * Translate a key and interpolate variables
+   * @param {string} key 
+   * @param {object} variables 
+   * @returns {string}
+   */
+  t(key, variables = {}) {
+    const dict = this.dictionary[this.locale];
+    if (!dict || !dict[key]) return key; // Fallback to raw key
+
+    let translation = dict[key];
+    
+    // Interpolate: "Welcome {name}" -> "Welcome Admin"
+    Object.keys(variables).forEach(varKey => {
+      const regex = new RegExp(`{${varKey}}`, 'g');
+      translation = translation.replace(regex, variables[varKey]);
+    });
+
+    return translation;
+  }
+}
+
+module.exports = { Ylsoo18n };

package/src/core/state.js

@@ -0,0 +1,67 @@
+class YlsooState {
+  constructor() {
+    this.state = {};
+    this.listeners = new Map();
+  }
+
+  /**
+   * Initializes or updates a specific state key
+   * @param {string} key 
+   * @param {*} initialValue 
+   */
+  setup(key, initialValue = null) {
+    if (!(key in this.state)) {
+      this.state[key] = initialValue;
+      this.listeners.set(key, new Set());
+    }
+  }
+
+  /**
+   * Retrieves the current value of a state key
+   * @param {string} key 
+   */
+  get(key) {
+    return this.state[key];
+  }
+
+  /**
+   * Set a new value and trigger all subscribers
+   * @param {string} key 
+   * @param {*} value 
+   */
+  set(key, value) {
+    this.setup(key); // Ensure setup
+    
+    // Only trigger if actually changed to prevent render loops
+    if (this.state[key] !== value) {
+      this.state[key] = value;
+      this.listeners.get(key).forEach(callback => {
+        try {
+          callback(value);
+        } catch (e) {
+          console.error(`[Ylsoo State] Error in listener for ${key}`, e);
+        }
+      });
+    }
+  }
+
+  /**
+   * Subscribe to changes on a specific key
+   * @param {string} key 
+   * @param {Function} callback 
+   * @returns {Function} Unsubscribe method
+   */
+  subscribe(key, callback) {
+    this.setup(key);
+    this.listeners.get(key).add(callback);
+
+    // Provide initial state immediately upon subscription
+    callback(this.state[key]);
+
+    return () => {
+      this.listeners.get(key).delete(callback);
+    };
+  }
+}
+
+module.exports = { YlsooState };

package/src/core/storage.js

@@ -0,0 +1,99 @@
+class YlsooStorage {
+  constructor(cryptoEngine) {
+    this.crypto = cryptoEngine; // Instance of YlsooCrypto
+    this.vaultPath = '.ylsoo-vault.json';
+    
+    // Check environment (distinguish Node from Browser safely)
+    this.isBrowser = typeof window !== 'undefined' && typeof window.localStorage !== 'undefined';
+  }
+
+  // Very rudimentary AES-like masking to keep it zero-dependency and cross-platform
+  // without heavily relying on async SubtleCrypto which makes synchronous read/writes impossible here.
+  // We use Base64 padding for simplistic obfuscation here to keep the API synchronous. 
+  // For true AES, it would require async/await API changes. 
+  _obfuscate(str) {
+    return this.crypto.encodeBase64(str).split('').reverse().join('');
+  }
+
+  _deobfuscate(obf) {
+    const b64 = obf.split('').reverse().join('');
+    return this.crypto.decodeBase64(b64);
+  }
+
+  /**
+   * Sets a value securely
+   */
+  set(key, value) {
+    const raw = JSON.stringify(value);
+    const secureString = this._obfuscate(raw);
+    const secureKey = this._obfuscate(key);
+
+    if (this.isBrowser) {
+      globalThis.localStorage.setItem(secureKey, secureString);
+    } else {
+      this._writeNodeFile(secureKey, secureString);
+    }
+  }
+
+  /**
+   * Retrieves a secure value
+   */
+  get(key) {
+    const secureKey = this._obfuscate(key);
+    let secureString = null;
+
+    if (this.isBrowser) {
+      secureString = globalThis.localStorage.getItem(secureKey);
+    } else {
+      secureString = this._readNodeFile(secureKey);
+    }
+
+    if (!secureString) return null;
+
+    try {
+      const raw = this._deobfuscate(secureString);
+      return JSON.parse(raw);
+    } catch(e) {
+      return null;
+    }
+  }
+
+  /**
+   * Removes a secure key
+   */
+  remove(key) {
+    const secureKey = this._obfuscate(key);
+    if (this.isBrowser) {
+      globalThis.localStorage.removeItem(secureKey);
+    } else {
+      const map = this._getNodeMap();
+      delete map[secureKey];
+      require('fs').writeFileSync(this.vaultPath, JSON.stringify(map), 'utf8');
+    }
+  }
+
+  // -- Node.js Fallbacks --
+  _getNodeMap() {
+    try {
+      const fs = require('fs');
+      if (!fs.existsSync(this.vaultPath)) return {};
+      const raw = fs.readFileSync(this.vaultPath, 'utf8');
+      return JSON.parse(raw);
+    } catch (e) {
+      return {};
+    }
+  }
+
+  _writeNodeFile(key, val) {
+    const map = this._getNodeMap();
+    map[key] = val;
+    require('fs').writeFileSync(this.vaultPath, JSON.stringify(map), 'utf8');
+  }
+
+  _readNodeFile(key) {
+    const map = this._getNodeMap();
+    return map[key] || null;
+  }
+}
+
+module.exports = { YlsooStorage };

package/src/engine/config.js

@@ -0,0 +1,54 @@
+class YlsooConfig {
+  constructor() {
+    this.store = {};
+    this.isFrozen = false;
+  }
+
+  /**
+   * Defines a base configuration
+   * @param {object} defaults 
+   */
+  setDefault(defaults) {
+    if (this.isFrozen) throw new Error('[Ylsoo Config] Cannot mutate after freezing.');
+    this.store = { ...defaults };
+  }
+
+  /**
+   * Deep merges environment overrides over defaults
+   * @param {object} envOverrides 
+   */
+  applyEnvironment(envOverrides) {
+    if (this.isFrozen) throw new Error('[Ylsoo Config] Cannot mutate after freezing.');
+    this.store = this._deepMerge(this.store, envOverrides);
+  }
+
+  /**
+   * Locks the config so it cannot be altered during application runtime securely.
+   */
+  freeze() {
+    this.isFrozen = true;
+    Object.freeze(this.store);
+  }
+
+  /**
+   * Fetches the entire config or a specific key
+   * @param {string} key Optional
+   */
+  get(key = null) {
+    if (key) return this.store[key];
+    return this.store;
+  }
+
+  // Purely native deep merge logic
+  _deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+      if (source[key] instanceof Object && key in target) {
+        Object.assign(source[key], this._deepMerge(target[key], source[key]));
+      }
+    }
+    Object.assign(target || {}, source);
+    return target;
+  }
+}
+
+module.exports = { YlsooConfig };

package/src/engine/features.js

@@ -0,0 +1,59 @@
+class YlsooFeatureFlags {
+  constructor(cryptoEngine) {
+    this.crypto = cryptoEngine; // Need crypto to hash unique IDs for deterministic A/B testing
+    this.flags = {};
+  }
+
+  /**
+   * Register a feature flag ruleset
+   * @param {string} flagName 
+   * @param {object} rules { enabled: boolean, rolloutPercentage: number, conditions: object }
+   */
+  setFlag(flagName, rules) {
+    this.flags[flagName] = {
+      enabled: false,
+      rolloutPercentage: 100, // 0 to 100
+      conditions: {}, // e.g. { country: 'US', tier: 'pro' }
+      ...rules
+    };
+  }
+
+  /**
+   * Evaluate if a feature is enabled for a specific context natively
+   * @param {string} flagName 
+   * @param {object} context { userId: string, attributes: { country: 'US', tier: 'pro' }}
+   */
+  async evaluate(flagName, context = {}) {
+    const flag = this.flags[flagName];
+    if (!flag) return false;
+    
+    // 1. Master Kill Switch check
+    if (flag.enabled === false) return false;
+
+    // 2. Fractional Rollout Evaluation
+    if (flag.rolloutPercentage < 100) {
+      if (!context.userId) return false; // Needs persistent ID for A/B rollout tracking
+      
+      // We hash the flagName + userId so the same user ALWAYS gets the same result for a specific flag consistently.
+      const hashStr = await this.crypto.hash(`${flagName}-${context.userId}`);
+      // Natively convert first 8 chars of hex hash into an integer, modulus 100 to get a 0-99 distribution
+      const bucket = parseInt(hashStr.substring(0, 8), 16) % 100; 
+      
+      if (bucket >= flag.rolloutPercentage) {
+        return false;
+      }
+    }
+
+    // 3. Context Targeting Rules
+    for (const [key, expectedValue] of Object.entries(flag.conditions)) {
+      const userValue = (context.attributes || {})[key];
+      if (userValue !== expectedValue) {
+        return false; // Missed targeting matrix
+      }
+    }
+
+    return true;
+  }
+}
+
+module.exports = { YlsooFeatureFlags };

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * @ylsoo/core v2.0.0
+ * @ylsoo/core v2.2.0
  * Enterprise utilities for both Node.js and the Web.
  */
 
@@ -9,28 +9,60 @@ const { YlsooCache } = require('./core/cache');
 const { YlsooCrypto } = require('./security/crypto');
 const { YlsooEventBus } = require('./events/bus');
 const { YlsooHelpers } = require('./utils/helpers');
+const { YlsooState } = require('./core/state');
+const { YlsooAnalytics } = require('./core/analytics');
+const { Ylsoo18n } = require('./core/i18n');
+const { YlsooStorage } = require('./core/storage');
+const { YlsooValidator } = require('./validation/schema');
+
+// V2.2.0 Ultra-Advanced Modules
+const { YlsooRouter } = require('./router/domRouter');
+const { YlsooFeatureFlags } = require('./engine/features');
+const { YlsooResilience } = require('./resilience/breaker');
+const { YlsooTaskQueue } = require('./utils/queue');
+const { YlsooTime } = require('./utils/time');
+const { YlsooConfig } = require('./engine/config');
 
 class YlsooCore {
   constructor() {
-    this.version = '2.0.0';
+    this.version = '2.2.0';
     
-    // Core Modules
-    this.http = new YlsooHttp();
-    this.logger = new YlsooLogger();
+    // Engine & Structure
+    this.crypto = new YlsooCrypto();
+    this.config = new YlsooConfig();
+    this.router = new YlsooRouter();
+    this.feature = new YlsooFeatureFlags(this.crypto);
+    
+    // Memory & Data
+    this.state = new YlsooState();
     this.cache = new YlsooCache();
+    this.storage = new YlsooStorage(this.crypto);
+    this.validator = new YlsooValidator();
     
-    // Advanced Modules
-    this.crypto = new YlsooCrypto();
+    // Networking & Flow
+    this.http = new YlsooHttp();
     this.events = new YlsooEventBus();
+    this.resilience = new YlsooResilience();
+    this.analytics = new YlsooAnalytics(this.http);
+    
+    // Helpers
+    this.logger = new YlsooLogger();
+    this.time = new YlsooTime();
+    this.i18n = new Ylsoo18n();
     this.helpers = new YlsooHelpers();
   }
 
-  // --- Helper Proxies to keep backwards compatibility with v1.1.0 ---
+  // --- Helper Proxies to keep backwards compatibility ---
   sleep(ms) { return this.helpers.sleep(ms); }
   deepClone(obj) { return this.helpers.deepClone(obj); }
   debounce(func, wait) { return this.helpers.debounce(func, wait); }
   isEmpty(val) { return this.helpers.isEmpty(val); }
   capitalize(str) { return this.helpers.capitalize(str); }
+
+  validate(data, schema) { return this.validator.validate(data, schema); }
+
+  // Expose the raw Queue Class so developers can instantiate multiple queues if needed
+  createQueue(limit = 5) { return new YlsooTaskQueue(limit); }
 }
 
 module.exports = new YlsooCore();

package/src/resilience/breaker.js

@@ -0,0 +1,73 @@
+class YlsooResilience {
+  /**
+   * Exponential backoff retry wrapper
+   * @param {Function} asyncFunction 
+   * @param {number} maxRetries 
+   * @param {number} baseDelayMs 
+   */
+  async withRetry(asyncFunction, maxRetries = 3, baseDelayMs = 1000) {
+    let attempt = 0;
+    while (attempt <= maxRetries) {
+      try {
+        return await asyncFunction();
+      } catch (err) {
+        attempt++;
+        if (attempt > maxRetries) {
+          throw new Error(`[Ylsoo Resilience] Failed after ${maxRetries} retries. Final Error: ${err.message}`);
+        }
+        
+        // Exponential backoff logic: 1s, 2s, 4s...
+        const delay = baseDelayMs * Math.pow(2, attempt - 1);
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  /**
+   * Creates a Circuit Breaker wrapper to prevent blasting dead APIs
+   * @param {Function} asyncFunction 
+   * @param {object} options 
+   */
+  createBreaker(asyncFunction, options = {}) {
+    const config = {
+      failureThreshold: 5,        // Fail 5 times before breaking
+      resetTimeoutMs: 30000,      // Keep broken for 30s before testing again
+      ...options
+    };
+
+    let failures = 0;
+    let state = 'CLOSED'; // CLOSED (working), OPEN (broken API), HALF_OPEN (testing)
+    let nextAttemptTimestamp = 0;
+
+    return async (...args) => {
+      if (state === 'OPEN') {
+        if (Date.now() >= nextAttemptTimestamp) {
+          state = 'HALF_OPEN';
+        } else {
+          throw new Error('[Ylsoo Circuit Breaker] Circuit is OPEN. Request dropped to protect upstream service.');
+        }
+      }
+
+      try {
+        const result = await asyncFunction(...args);
+        
+        // Reset breaker on success
+        if (state === 'HALF_OPEN') {
+          state = 'CLOSED';
+          failures = 0;
+        }
+
+        return result;
+      } catch (err) {
+        failures++;
+        if (failures >= config.failureThreshold || state === 'HALF_OPEN') {
+          state = 'OPEN';
+          nextAttemptTimestamp = Date.now() + config.resetTimeoutMs;
+        }
+        throw err;
+      }
+    };
+  }
+}
+
+module.exports = { YlsooResilience };

package/src/router/domRouter.js

@@ -0,0 +1,131 @@
+class YlsooRouter {
+  constructor() {
+    this.routes = [];
+    this.middlewares = [];
+    this.currentRoute = null;
+    this.fallback = null;
+    this.isBrowser = typeof window !== 'undefined' && typeof window.history !== 'undefined';
+  }
+
+  /**
+   * Adds a global middleware hook
+   * @param {Function} hook (to, from, next)
+   */
+  beforeEach(hook) {
+    this.middlewares.push(hook);
+  }
+
+  /**
+   * Register a route mapping
+   * @param {string} path  (e.g. "/users/:id")
+   * @param {Function} handler 
+   */
+  add(path, handler) {
+    // Generate Regex for path parsing
+    const paramNames = [];
+    let regexPath = path.replace(/([:*])(\w+)/g, (full, colon, name) => {
+      paramNames.push(name);
+      return '([^/]+)';
+    });
+    
+    // Allow wildcards
+    regexPath = regexPath.replace(/\*/g, '.*');
+
+    this.routes.push({
+      path,
+      regex: new RegExp(`^${regexPath}/?$`, 'i'),
+      paramNames,
+      handler
+    });
+  }
+
+  /**
+   * Set a 404 Not Found fallback route
+   * @param {Function} handler 
+   */
+  setFallback(handler) {
+    this.fallback = handler;
+  }
+
+  /**
+   * Start the router engine, bind to HTML5 History and PopState
+   */
+  start() {
+    if (!this.isBrowser) return; // Silent fail in Node environments
+    
+    // Bind back/forward buttons
+    window.addEventListener('popstate', () => {
+      this._navigate(window.location.pathname, false);
+    });
+    
+    // Intercept clicks
+    document.body.addEventListener('click', (e) => {
+      const target = e.target.closest('a');
+      if (target && target.hasAttribute('data-route')) {
+        e.preventDefault();
+        this._navigate(target.getAttribute('href'));
+      }
+    });
+
+    // Run initial parse
+    this._navigate(window.location.pathname, false);
+  }
+
+  /**
+   * Navigate to a route manually
+   * @param {string} path 
+   */
+  push(path) {
+    if (!this.isBrowser) return;
+    this._navigate(path, true);
+  }
+
+  async _navigate(urlPath, pushToHistory = true) {
+    const fromPath = this.currentRoute;
+    
+    // Run middlewares
+    let halt = false;
+    const next = (confirm = true) => { if (confirm === false) halt = true; };
+    
+    for (let mw of this.middlewares) {
+      await mw(urlPath, fromPath, next);
+      if (halt) return; // Middleware blocked navigation
+    }
+
+    // Match route
+    let matchedRoute = null;
+    let params = {};
+
+    for (let route of this.routes) {
+      const match = urlPath.match(route.regex);
+      if (match) {
+        matchedRoute = route;
+        route.paramNames.forEach((name, idx) => {
+          params[name] = match[idx + 1];
+        });
+        break;
+      }
+    }
+
+    if (pushToHistory && urlPath !== window.location.pathname) {
+      window.history.pushState(null, '', urlPath);
+    }
+    
+    this.currentRoute = urlPath;
+
+    // Parse Query Params (Only in browser)
+    let query = {};
+    if (this.isBrowser && typeof window !== 'undefined') {
+      const url = new URL(window.location.href);
+      query = Object.fromEntries(url.searchParams.entries());
+    }
+
+    if (matchedRoute) {
+      matchedRoute.handler({ params, query, path: urlPath });
+    } else if (this.fallback) {
+      this.fallback({ path: urlPath, query });
+    }
+  }
+}
+
+module.exports = { YlsooRouter };

package/src/utils/queue.js

@@ -0,0 +1,50 @@
+class YlsooTaskQueue {
+  /**
+   * Limit concurrency of massive promises automatically
+   * @param {number} concurrencyLimit 
+   */
+  constructor(concurrencyLimit = 5) {
+    this.concurrencyLimit = concurrencyLimit;
+    this.activeCount = 0;
+    this.queue = [];
+  }
+
+  /**
+   * Add a function that returns a Promise to the queue
+   * @param {Function} asyncTask 
+   * @returns {Promise<*>}
+   */
+  add(asyncTask) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({
+        task: asyncTask,
+        resolve,
+        reject
+      });
+      this._next();
+    });
+  }
+
+  get remaining() {
+    return this.queue.length;
+  }
+
+  _next() {
+    if (this.activeCount >= this.concurrencyLimit || this.queue.length === 0) {
+      return;
+    }
+
+    this.activeCount++;
+    const { task, resolve, reject } = this.queue.shift();
+
+    task()
+      .then(resolve)
+      .catch(reject)
+      .finally(() => {
+        this.activeCount--;
+        this._next();
+      });
+  }
+}
+
+module.exports = { YlsooTaskQueue };

package/src/utils/time.js

@@ -0,0 +1,46 @@
+class YlsooTime {
+  /**
+   * Extremely lightweight date formatter (replaces heavy Moment.js)
+   * @param {Date|number|string} date 
+   * @param {string} formatStr (e.g. "YYYY-MM-DD HH:mm:ss")
+   */
+  format(date, formatStr = "YYYY-MM-DD") {
+    const d = new Date(date);
+    if (isNaN(d.getTime())) return null;
+
+    const pad = (n) => String(n).padStart(2, '0');
+    
+    return formatStr
+      .replace('YYYY', d.getFullYear())
+      .replace('YY', String(d.getFullYear()).slice(-2))
+      .replace('MM', pad(d.getMonth() + 1))
+      .replace('DD', pad(d.getDate()))
+      .replace('HH', pad(d.getHours()))
+      .replace('mm', pad(d.getMinutes()))
+      .replace('ss', pad(d.getSeconds()));
+  }
+
+  /**
+   * Fast "time ago" algorithm
+   * @param {Date|number|string} date 
+   */
+  timeAgo(date) {
+    const d = new Date(date);
+    const seconds = Math.floor((new Date() - d) / 1000);
+    
+    let interval = Math.floor(seconds / 31536000);
+    if (interval >= 1) return interval + " year" + (interval > 1 ? "s" : "") + " ago";
+    interval = Math.floor(seconds / 2592000);
+    if (interval >= 1) return interval + " month" + (interval > 1 ? "s" : "") + " ago";
+    interval = Math.floor(seconds / 86400);
+    if (interval >= 1) return interval + " day" + (interval > 1 ? "s" : "") + " ago";
+    interval = Math.floor(seconds / 3600);
+    if (interval >= 1) return interval + " hour" + (interval > 1 ? "s" : "") + " ago";
+    interval = Math.floor(seconds / 60);
+    if (interval >= 1) return interval + " minute" + (interval > 1 ? "s" : "") + " ago";
+    
+    return Math.floor(seconds) + " seconds ago";
+  }
+}
+
+module.exports = { YlsooTime };

package/src/validation/schema.js

@@ -0,0 +1,53 @@
+class YlsooValidator {
+  /**
+   * Validate an object against a strict schema mapping
+   * @param {*} data 
+   * @param {object} schema 
+   * @throws Error on validation failure
+   * @returns {boolean} true if valid
+   */
+  validate(data, schema) {
+    if (typeof data !== 'object' || data === null) {
+      throw new Error('[Ylsoo Validation] Target is not an object.');
+    }
+
+    for (const [key, rules] of Object.entries(schema)) {
+      const value = data[key];
+
+      // Handle raw type strings (e.g. { age: 'number' })
+      const type = typeof rules === 'string' ? rules : rules.type;
+      
+      // Check required
+      const isRequired = typeof rules === 'object' ? rules.required !== false : true;
+      if (value === undefined || value === null) {
+        if (isRequired) throw new Error(`[Ylsoo Validation] Missing required key: ${key}`);
+        continue;
+      }
+
+      // Check Types
+      if (type === 'array') {
+        if (!Array.isArray(value)) throw new Error(`[Ylsoo Validation] Type mismatch. ${key} must be an array.`);
+      } else if (type === 'email') {
+        if (typeof value !== 'string' || !/^\S+@\S+\.\S+$/.test(value)) {
+          throw new Error(`[Ylsoo Validation] Type mismatch. ${key} must be a valid email.`);
+        }
+      } else if (type === 'object') {
+        if (typeof value !== 'object' || Array.isArray(value)) {
+          throw new Error(`[Ylsoo Validation] Type mismatch. ${key} must be an object.`);
+        }
+        // Recursive dive
+        if (rules.schema) {
+          this.validate(value, rules.schema);
+        }
+      } else {
+        if (typeof value !== type) {
+          throw new Error(`[Ylsoo Validation] Type mismatch. ${key} must be a ${type}.`);
+        }
+      }
+    }
+    
+    return true;
+  }
+}
+
+module.exports = { YlsooValidator };