@ylsoo/core 1.1.0 → 2.0.1

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/events/bus.js

@@ -0,0 +1,69 @@
+class YlsooEventBus {
+  constructor() {
+    this.events = {};
+  }
+
+  /**
+   * Subscribe to an event
+   * @param {string} event 
+   * @param {Function} callback 
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, callback) {
+    if (!this.events[event]) {
+      this.events[event] = [];
+    }
+    this.events[event].push(callback);
+
+    // Return an un-subscriber
+    return () => this.off(event, callback);
+  }
+
+  /**
+   * Unsubscribe from an event
+   * @param {string} event 
+   * @param {Function} callback 
+   */
+  off(event, callback) {
+    if (!this.events[event]) return;
+    this.events[event] = this.events[event].filter(cb => cb !== callback);
+  }
+
+  /**
+   * Publish an event with optional payload
+   * @param {string} event 
+   * @param {*} data 
+   */
+  emit(event, data) {
+    if (!this.events[event]) return;
+    this.events[event].forEach(callback => {
+      try {
+        callback(data);
+      } catch (err) {
+        console.error(`[Ylsoo Event Bus] Error in callback for event "${event}":`, err);
+      }
+    });
+  }
+
+  /**
+   * Listen for an event exactly once
+   * @param {string} event 
+   * @param {Function} callback 
+   */
+  once(event, callback) {
+    const wrapper = (data) => {
+      this.off(event, wrapper);
+      callback(data);
+    };
+    this.on(event, wrapper);
+  }
+
+  /**
+   * Clear all events
+   */
+  clear() {
+    this.events = {};
+  }
+}
+
+module.exports = { YlsooEventBus };

package/src/http/client.js

@@ -0,0 +1,49 @@
+class YlsooHttp {
+  async request(endpoint, options = {}) {
+    const defaultHeaders = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'Ylsoo-Core/2.0'
+    };
+
+    const config = {
+      ...options,
+      headers: {
+        ...defaultHeaders,
+        ...options.headers
+      }
+    };
+
+    if (config.body && typeof config.body === 'object') {
+      config.body = JSON.stringify(config.body);
+    }
+
+    try {
+      const response = await fetch(endpoint, config);
+      const isJson = response.headers.get('content-type')?.includes('application/json');
+      
+      const data = isJson ? await response.json() : await response.text();
+
+      if (!response.ok) {
+        throw {
+          status: response.status,
+          message: response.statusText,
+          data
+        };
+      }
+
+      return data;
+    } catch (error) {
+      throw new Error(`[Ylsoo HTTP Error]: ${error.message || JSON.stringify(error)}`);
+    }
+  }
+
+  get(endpoint, headers = {}) {
+    return this.request(endpoint, { method: 'GET', headers });
+  }
+
+  post(endpoint, body, headers = {}) {
+    return this.request(endpoint, { method: 'POST', body, headers });
+  }
+}
+
+module.exports = { YlsooHttp };

package/src/index.js

@@ -0,0 +1,68 @@
+/**
+ * @ylsoo/core v2.2.0
+ * Enterprise utilities for both Node.js and the Web.
+ */
+
+const { YlsooHttp } = require('./http/client');
+const { YlsooLogger } = require('./core/logger');
+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.2.0';
+    
+    // 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();
+    
+    // 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 ---
+  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/security/crypto.js

@@ -0,0 +1,67 @@
+class YlsooCrypto {
+  /**
+   * Base64 encode a string
+   * @param {string} str 
+   * @returns {string}
+   */
+  encodeBase64(str) {
+    if (typeof globalThis.btoa === 'function') {
+      return globalThis.btoa(str);
+    }
+    return Buffer.from(str).toString('base64');
+  }
+
+  /**
+   * Base64 decode a string
+   * @param {string} base64 
+   * @returns {string}
+   */
+  decodeBase64(base64) {
+    if (typeof globalThis.atob === 'function') {
+      return globalThis.atob(base64);
+    }
+    return Buffer.from(base64, 'base64').toString('utf-8');
+  }
+
+  /**
+   * Creates a SHA-256 hash of a string natively
+   * @param {string} str 
+   * @returns {Promise<string>}
+   */
+  async hash(str) {
+    // Attempt standard Web Crypto API (Browser + Modern Node)
+    if (globalThis.crypto && globalThis.crypto.subtle) {
+      const msgBuffer = new TextEncoder().encode(str);
+      const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', msgBuffer);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    
+    // Fallback for older Node.js contexts
+    try {
+      const crypto = require('crypto');
+      return crypto.createHash('sha256').update(str).digest('hex');
+    } catch(err) {
+      throw new Error('[Ylsoo Crypto Error] No secure hashing engine available on this platform.');
+    }
+  }
+
+  /**
+   * Generate a secure random v4 UUID
+   * @returns {string}
+   */
+  uuid() {
+    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
+      return globalThis.crypto.randomUUID();
+    }
+    
+    // Fallback UUID v4 generator
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+      const r = Math.random() * 16 | 0;
+      const v = c === 'x' ? r : (r & 0x3 | 0x8);
+      return v.toString(16);
+    });
+  }
+}
+
+module.exports = { YlsooCrypto };