@ylsoo/core 1.1.0 → 2.0.1

package/README.md

@@ -1,17 +1,18 @@
 <div align="center">
-  <h1>@ylsoo/core</h1>
-  <p><b>The official, zero-dependency SDK powering all premium Ylsoo 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/)
+  [![Zero Defaults](https://img.shields.io/badge/Dependencies-0-brightgreen?style=flat-square)](#)
 </div>
 
 <hr>
 
 ## 🚀 Overview
 
-`@ylsoo/core` provides fundamental, blazing-fast utility functions designed specifically for integrating Ylsoo services. Built completely from the ground up without any third-party dependencies, it guarantees ultra-fast execution and zero bloat.
+`@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
 
@@ -19,88 +20,70 @@
 npm i @ylsoo/core
 ```
 
-*Note: Fully typed out-of-the-box for perfect IDE intellisense!*
+## 🛠️ V2.2 Enterprise Architecture Models
 
-## 🛠️ API Reference
+### 1. 🛣️ Professional DOM Router (`ylsoo.router`)
+An incredibly capable HTML5 Frontend matcher mimicking heavily advanced Vue/React dynamics.
 
-### 1. Ylsoo Console (`logger`)
-A beautifully formatted console utility utilizing native ANSI escape codes for local development.
+- **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!
 
 ```javascript
-const ylsoo = require('@ylsoo/core');
+// 1. Build an Authentication Middleware Guard
+ylsoo.router.beforeEach((to, from, next) => {
+  if (to.includes('admin') && !loggedIn) next(false); // Halt routing
+});
 
-ylsoo.logger.info('System initializing...');
-ylsoo.logger.success('Database connected successfully!');
-ylsoo.logger.warn('Rate limit approaching.');
-ylsoo.logger.error('Critical failure detected.');
-```
-
-### 2. Ylsoo Request Engine (`http`)
-A robust wrapper around the native `fetch` API. It automatically handles stringifying bodies, applying correct headers, parsing JSON, and safely throwing formatted errors.
-
-```javascript
-const ylsoo = require('@ylsoo/core');
-
-async function fetchUserData() {
-  try {
-    const data = await ylsoo.http.get('https://api.ylsoo.com/v1/user/me');
-    console.log(data);
-  } catch (error) {
-    ylsoo.logger.error('Failed to fetch user', error);
-  }
-}
-```
-
-### 3. Ylsoo Memory Cache (`cache`)
-A fast, volatile in-memory key/value store with Time-To-Live (TTL) functionality.
-
-```javascript
-const ylsoo = require('@ylsoo/core');
-
-// Cache a complex object for 5 seconds (5000 ms)
-ylsoo.cache.set('session_token', { id: 123 }, 5000);
+// 2. Configure Dynamic Deep Routes
+ylsoo.router.add('/users/:id/billing', (route) => {
+  console.log('Loading Billing For User:', route.params.id);
+});
 
-// Retrieve it instantly
-const session = ylsoo.cache.get('session_token');
-
-// Will return null after 5 seconds
-setTimeout(() => {
-  console.log(ylsoo.cache.get('session_token')); // null
-}, 5100);
+ylsoo.router.start();
 ```
 
-### 4. Advanced Core Utilities
+### 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.
 
-#### `sleep(ms)`
-Promise-based execution halter.
 ```javascript
-await ylsoo.sleep(2000); // Waits 2 seconds
+// 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');
+}
 ```
 
-#### `deepClone(obj)`
-Safely fully clones an object without retaining references, utilizing modern native standards where available.
-```javascript
-const copy = ylsoo.deepClone(complexObject);
-```
+### 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.
 
-#### `debounce(func, wait)`
-Throttles function execution to ensure high performance during spam events (like window resizing or typing).
+### 4. 🕐 Precise Time Formatter (`ylsoo.time`)
+Completely strips the need for massive `moment.js` dependency packets. Quickly parses standard intervals.
 ```javascript
-const search = ylsoo.debounce(() => console.log('Searching...'), 300);
+ylsoo.time.format(Date.now(), "YYYY-MM-DD HH:mm:ss"); 
+ylsoo.time.timeAgo(oldDate); // "5 minutes ago"
 ```
 
-#### `isEmpty(value)`
-Intelligently determines if strings, arrays, objects, maps, or sets are empty.
-```javascript
-ylsoo.isEmpty({}); // true
-ylsoo.isEmpty([]); // true
-ylsoo.isEmpty("hello"); // false
-```
+### 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`.
 
-#### `capitalize(str)`
-Easily standardize text formatting.
+### 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.capitalize('ylsoo'); // 'Ylsoo'
+const q = ylsoo.createQueue(5); // Throttle process to exactly 5 lanes
+q.add(() => fetchBigData1());
+q.add(() => fetchBigData2());
 ```
 
 ---

package/index.d.ts

@@ -1,89 +1,140 @@
 /**
- * @ylsoo/core Type Definitions
+ * @ylsoo/core v2.2.0 Type Definitions
+ * Enterprise Cross-Platform SDK
  */
 
 declare module '@ylsoo/core' {
 
+  // --- Base Systems ---
   export class YlsooLogger {
-      /** Logs an informational message */
       info(message: string | any): void;
-      /** Logs a success message */
       success(message: string | any): void;
-      /** Logs a warning message */
       warn(message: string | any): void;
-      /** Logs an error message */
       error(message: string | any): void;
   }
 
   export class YlsooCache {
-      /**
-       * Set a key-value pair in memory
-       * @param key String identifier
-       * @param value The raw value to store
-       * @param ttlMs Time to live in milliseconds (0 for infinite)
-       */
       set(key: string, value: any, ttlMs?: number): void;
-      
-      /**
-       * Retrieve a value from the cache. Returns null if expired or missing.
-       */
       get<T = any>(key: string): T | null;
-
-      /**
-       * Delete a specific key from the cache
-       */
       delete(key: string): boolean;
+      clear(): void;
+  }
+
+  export class YlsooHttp {
+      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>;
+  }
 
-      /**
-       * Clear all cached data
-       */
+  // --- Security & Process ---
+  export class YlsooCrypto {
+      encodeBase64(str: string): string;
+      decodeBase64(base64: string): string;
+      hash(str: string): Promise<string>;
+      uuid(): string;
+  }
+
+  export class YlsooEventBus {
+      on(event: string, callback: (data?: any) => void): () => void;
+      off(event: string, callback: (data?: any) => void): void;
+      emit(event: string, data?: any): void;
+      once(event: string, callback: (data?: any) => void): void;
       clear(): void;
   }
 
-  export interface YlsooHttpOptions {
-      method?: string;
-      headers?: Record<string, string>;
-      body?: any;
-      [key: string]: any;
+  // --- 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 YlsooHttp {
-      /** Makes a raw fetch request but automatically handles JSON mapping and errors */
-      request<T = any>(endpoint: string, options?: YlsooHttpOptions): Promise<T>;
-      
-      /** Performs a GET request */
-      get<T = any>(endpoint: string, headers?: Record<string, string>): Promise<T>;
-      
-      /** Performs a POST request with an automatic JSON-stringified body */
-      post<T = any>(endpoint: string, body: any, headers?: Record<string, string>): Promise<T>;
+  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;
       
-      /** The official Ylsoo logging console */
-      logger: YlsooLogger;
+      crypto: YlsooCrypto;
+      config: YlsooConfig;
+      router: YlsooRouter;
+      feature: YlsooFeatureFlags;
       
-      /** The official Ylsoo memory cache */
+      state: YlsooState;
       cache: YlsooCache;
+      storage: YlsooStorage;
       
-      /** The official Ylsoo request engine */
       http: YlsooHttp;
+      events: YlsooEventBus;
+      resilience: YlsooResilience;
+      analytics: YlsooAnalytics;
+      
+      logger: YlsooLogger;
+      time: YlsooTime;
+      i18n: Ylsoo18n;
 
-      /** Halt execution for a set duration */
       sleep(ms: number): Promise<void>;
-
-      /** Safely deep clone an object */
       deepClone<T>(obj: T): T;
-
-      /** Creates a debounced version of a function */
       debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
-
-      /** Check if an array, string, object, map, or set is semantically empty */
       isEmpty(value: any): boolean;
-
-      /** Capitalizes the first letter of a string */
       capitalize(str: string): string;
+      
+      validate(data: any, schema: Record<string, any>): boolean;
+      createQueue(limit?: number): YlsooTaskQueue;
   }
 
   const ylsoo: YlsooCore;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ylsoo/core",
-  "version": "1.1.0",
-  "description": "Core utility functions for Ylsoo projects",
-  "main": "index.js",
+  "version": "2.0.1",
+  "description": "Enterprise cross-platform SDK for Ylsoo projects",
+  "main": "src/index.js",
   "types": "index.d.ts",
   "files": [
-    "index.js",
+    "src/",
     "index.d.ts",
     "README.md"
   ],
@@ -15,11 +15,15 @@
   "keywords": [
     "ylsoo",
     "core",
-    "utilities",
+    "enterprise",
     "sdk",
-    "fetch",
-    "logger",
-    "cache"
+    "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/cache.js

@@ -0,0 +1,31 @@
+class YlsooCache {
+  constructor() {
+    this.store = new Map();
+  }
+
+  set(key, value, ttlMs = 0) {
+    const expiresAt = ttlMs > 0 ? Date.now() + ttlMs : null;
+    this.store.set(key, { value, expiresAt });
+  }
+
+  get(key) {
+    const item = this.store.get(key);
+    if (!item) return null;
+
+    if (item.expiresAt && Date.now() > item.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.value;
+  }
+
+  delete(key) {
+    return this.store.delete(key);
+  }
+
+  clear() {
+    this.store.clear();
+  }
+}
+
+module.exports = { YlsooCache };

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/logger.js

@@ -0,0 +1,39 @@
+class YlsooLogger {
+  constructor() {
+    this.colors = {
+      reset: "\x1b[0m",
+      info: "\x1b[36m",    // Cyan
+      success: "\x1b[32m", // Green
+      warn: "\x1b[33m",    // Yellow
+      error: "\x1b[31m",   // Red
+      ylsoo: "\x1b[35m"    // Magenta
+    };
+  }
+
+  _format(level, message, color) {
+    // Only use colors in Node.js, not browsers. Check process briefly.
+    const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+    if (isNode) {
+      return `${this.colors.ylsoo}[Ylsoo]${this.colors.reset} ${color}[${level.toUpperCase()}]${this.colors.reset} ${message}`;
+    }
+    return `[Ylsoo] [${level.toUpperCase()}] ${message}`;
+  }
+
+  info(message) {
+    console.log(this._format('info', message, this.colors.info));
+  }
+
+  success(message) {
+    console.log(this._format('success', message, this.colors.success));
+  }
+
+  warn(message) {
+    console.warn(this._format('warn', message, this.colors.warn));
+  }
+
+  error(message) {
+    console.error(this._format('error', message, this.colors.error));
+  }
+}
+
+module.exports = { YlsooLogger };

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 };