@ylsoo/core 1.0.0 → 1.1.0

package/README.md

@@ -1,19 +1,109 @@
-# @ylsoo/core
+<div align="center">
+  <h1>@ylsoo/core</h1>
+  <p><b>The official, zero-dependency SDK powering all premium Ylsoo products.</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/)
+</div>
 
-Core utility functions for Ylsoo projects.
+<hr>
 
-## Installation
+## 🚀 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.
+
+## 📦 Installation
 
 ```bash
 npm i @ylsoo/core
 ```
 
-## Usage
+*Note: Fully typed out-of-the-box for perfect IDE intellisense!*
+
+## 🛠️ API Reference
+
+### 1. Ylsoo Console (`logger`)
+A beautifully formatted console utility utilizing native ANSI escape codes for local development.
+
+```javascript
+const ylsoo = require('@ylsoo/core');
+
+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');
 
-ylsoo.log('Hello World');
-console.log(ylsoo.capitalize('hello'));
-console.log(ylsoo.isEmpty(''));
+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);
+
+// 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);
 ```
+
+### 4. Advanced Core Utilities
+
+#### `sleep(ms)`
+Promise-based execution halter.
+```javascript
+await ylsoo.sleep(2000); // Waits 2 seconds
+```
+
+#### `deepClone(obj)`
+Safely fully clones an object without retaining references, utilizing modern native standards where available.
+```javascript
+const copy = ylsoo.deepClone(complexObject);
+```
+
+#### `debounce(func, wait)`
+Throttles function execution to ensure high performance during spam events (like window resizing or typing).
+```javascript
+const search = ylsoo.debounce(() => console.log('Searching...'), 300);
+```
+
+#### `isEmpty(value)`
+Intelligently determines if strings, arrays, objects, maps, or sets are empty.
+```javascript
+ylsoo.isEmpty({}); // true
+ylsoo.isEmpty([]); // true
+ylsoo.isEmpty("hello"); // false
+```
+
+#### `capitalize(str)`
+Easily standardize text formatting.
+```javascript
+ylsoo.capitalize('ylsoo'); // 'Ylsoo'
+```
+
+---
+<div align="center">
+  <p>Built with ❤️ by <b>Ylsoo</b>.</p>
+</div>

package/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @ylsoo/core Type Definitions
+ */
+
+declare module '@ylsoo/core' {
+
+  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 all cached data
+       */
+      clear(): void;
+  }
+
+  export interface YlsooHttpOptions {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: any;
+      [key: string]: any;
+  }
+
+  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 YlsooCore {
+      version: string;
+      
+      /** The official Ylsoo logging console */
+      logger: YlsooLogger;
+      
+      /** The official Ylsoo memory cache */
+      cache: YlsooCache;
+      
+      /** The official Ylsoo request engine */
+      http: YlsooHttp;
+
+      /** 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;
+  }
+
+  const ylsoo: YlsooCore;
+  export default ylsoo;
+}

package/index.js

@@ -1,43 +1,202 @@
 /**
- * Ylsoo Core - Basic utility functions
+ * @ylsoo/core
+ * Premium utility functions for Ylsoo projects
+ * Zero dependency, extremely fast, robust.
  */
 
+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) {
+    const time = new Date().toISOString().split('T')[1].slice(0, -1);
+    return `${this.colors.ylsoo}[Ylsoo]${this.colors.reset} ${color}[${level.toUpperCase()}]${this.colors.reset} ${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));
+  }
+}
+
+class YlsooCache {
+  constructor() {
+    this.store = new Map();
+  }
+
+  /**
+   * Set a key-value pair with an optional Time-To-Live
+   * @param {string} key 
+   * @param {*} value 
+   * @param {number} ttlMs - Time to live in milliseconds
+   */
+  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();
+  }
+}
+
+class YlsooHttp {
+  /**
+   * Premium wrapper for fetch
+   * @param {string} endpoint 
+   * @param {object} options 
+   * @returns {Promise<any>}
+   */
+  async request(endpoint, options = {}) {
+    const defaultHeaders = {
+      'Content-Type': 'application/json',
+      'User-Agent': 'Ylsoo-Core/1.1'
+    };
+
+    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 });
+  }
+}
+
 class YlsooCore {
   constructor() {
-    this.version = '1.0.0';
+    this.version = '1.1.0';
+    this.logger = new YlsooLogger();
+    this.cache = new YlsooCache();
+    this.http = new YlsooHttp();
   }
 
   /**
-   * Logs a message with prefix
-   * @param {string} message - The message to log
+   * Sleep for a given amount of time (Promise based)
+   * @param {number} ms 
    */
-  log(message) {
-    console.log(`[Ylsoo Core] ${message}`);
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
   }
 
   /**
-   * Simple utility to capitalize a string
-   * @param {string} str - The string to capitalize
-   * @returns {string} Capitalized string
+   * Deep clone an object natively
+   * @param {object} obj 
    */
-  capitalize(str) {
-    if (typeof str !== 'string' || str.length === 0) {
-      return str;
+  deepClone(obj) {
+    if (typeof structuredClone === 'function') {
+      return structuredClone(obj);
     }
-    return str.charAt(0).toUpperCase() + str.slice(1);
+    return JSON.parse(JSON.stringify(obj));
+  }
+
+  /**
+   * Creates a debounced function that delays invoking func until after wait milliseconds have elapsed
+   * @param {Function} func 
+   * @param {number} wait 
+   */
+  debounce(func, wait) {
+    let timeout;
+    return function executedFunction(...args) {
+      const later = () => {
+        clearTimeout(timeout);
+        func(...args);
+      };
+      clearTimeout(timeout);
+      timeout = setTimeout(later, wait);
+    };
   }
 
   /**
-   * Simple utility to check if value is empty
-   * @param {*} value - The value to check
-   * @returns {boolean} True if empty
+   * Simple utility to verify if a value is semantically empty
+   * @param {*} value 
    */
   isEmpty(value) {
     if (value === null || value === undefined) return true;
     if (typeof value === 'string' || Array.isArray(value)) return value.length === 0;
-    if (typeof value === 'object') return Object.keys(value).length === 0;
+    if (typeof value === 'object') {
+      if (value instanceof Map || value instanceof Set) return value.size === 0;
+      return Object.keys(value).length === 0;
+    }
     return false;
   }
+  
+  /**
+   * Simple utility to capitalize a string
+   * @param {string} str - The string to capitalize
+   * @returns {string} Capitalized string
+   */
+  capitalize(str) {
+    if (typeof str !== 'string' || str.length === 0) {
+      return str;
+    }
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
 }
 
 module.exports = new YlsooCore();

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@ylsoo/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Core utility functions for Ylsoo projects",
   "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node test.js"
   },
   "keywords": [
     "ylsoo",
     "core",
-    "utilities"
+    "utilities",
+    "sdk",
+    "fetch",
+    "logger",
+    "cache"
   ],
-  "author": "",
-  "license": "ISC",
+  "author": "Ylsoo",
+  "license": "MIT",
   "type": "commonjs"
 }