titanpl 7.0.0 → 7.0.1

package/packages/core-source/index.d.ts

@@ -1,515 +0,0 @@
-// =============================================================================
-//  @titanpl/core — Module Type Definitions
-//  The official Core Standard Library for Titan Planet
-//  Version: 2.x
-//  Repository: https://github.com/ezet-galaxy/-titanpl-core
-// =============================================================================
-
-/// <reference path="./globals.d.ts" />
-
-// =============================================================================
-//  ESM Named Exports
-//  Usage: import { fs, crypto, response } from '@titanpl/core';
-// =============================================================================
-
-/**
- * # File System Module
- *
- * Native file operations backed by Rust. All methods are **synchronous**.
- *
- * **Methods:**
- * - `readFile(path)` — Read file as UTF-8 string
- * - `writeFile(path, content)` — Write string to file
- * - `readdir(path)` — List directory contents
- * - `mkdir(path)` — Create directory (recursive)
- * - `exists(path)` — Check if path exists
- * - `stat(path)` — Get file metadata
- * - `remove(path)` — Delete file or directory
- *
- * @example
- * ```js
- * import { fs } from '@titanpl/core';
- *
- * // Read and parse JSON
- * const config = JSON.parse(fs.readFile("./config.json"));
- *
- * // Write data
- * fs.writeFile("./output.json", JSON.stringify(data, null, 2));
- *
- * // Check existence
- * if (fs.exists("./cache")) {
- *     const files = fs.readdir("./cache");
- * }
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#fs-file-system
- */
-export declare const fs: TitanCore.FileSystem;
-
-/**
- * # Path Module
- *
- * Cross-platform path manipulation utilities. All methods are **synchronous**.
- *
- * **Methods:**
- * - `join(...parts)` — Join path segments
- * - `resolve(...parts)` — Resolve to absolute path
- * - `dirname(path)` — Get directory name
- * - `basename(path)` — Get file name
- * - `extname(path)` — Get file extension
- *
- * @example
- * ```js
- * import { path } from '@titanpl/core';
- *
- * const configPath = path.join("app", "config", "settings.json");
- * const absolute = path.resolve("./data", "users.db");
- *
- * path.dirname("/var/log/app.log");  // → "/var/log"
- * path.basename("/var/log/app.log"); // → "app.log"
- * path.extname("photo.png");         // → ".png"
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#path-path-manipulation
- */
-export declare const path: TitanCore.Path;
-
-/**
- * # Cryptography Module
- *
- * Cryptographic utilities powered by native Rust. All methods are **synchronous**.
- *
- * **Methods:**
- * - `hash(algo, data)` — Hash data (sha256, sha512, md5)
- * - `randomBytes(size)` — Generate random bytes (hex)
- * - `uuid()` — Generate UUID v4
- * - `compare(a, b)` — Constant-time comparison
- * - `base64.encode(str)` / `base64.decode(str)` — Base64 utilities
- * - `encrypt(algo, key, plaintext)` — AES-256-GCM encrypt
- * - `decrypt(algo, key, ciphertext)` — AES-256-GCM decrypt
- * - `hashKeyed(algo, key, message)` — HMAC signing
- *
- * @example
- * ```js
- * import { crypto } from '@titanpl/core';
- *
- * // Generate identifiers
- * const id = crypto.uuid();
- * const token = crypto.randomBytes(32);
- *
- * // Hash and verify
- * const hash = crypto.hash("sha256", password + salt);
- * const isValid = crypto.compare(storedHash, hash);
- *
- * // Base64 encoding
- * const encoded = crypto.base64.encode("Hello World");
- * const decoded = crypto.base64.decode(encoded);
- *
- * // HMAC for webhooks
- * const signature = crypto.hashKeyed("hmac-sha256", secret, payload);
- *
- * // Encryption
- * const encrypted = crypto.encrypt("aes-256-gcm", key, "secret");
- * const decrypted = crypto.decrypt("aes-256-gcm", key, encrypted);
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#crypto-cryptography
- */
-export declare const crypto: TitanCore.Crypto;
-
-/**
- * # Operating System Module
- *
- * System information about the host machine. All methods are **synchronous**.
- *
- * **Methods:**
- * - `platform()` — OS identifier ("linux", "darwin", "windows")
- * - `cpus()` — Number of CPU cores
- * - `totalMemory()` — Total RAM in bytes
- * - `freeMemory()` — Available RAM in bytes
- * - `tmpdir()` — Temporary directory path
- *
- * @example
- * ```js
- * import { os } from '@titanpl/core';
- *
- * console.log({
- *     platform: os.platform(),
- *     cpus: os.cpus(),
- *     totalMemory: os.totalMemory() / (1024 ** 3) + " GB",
- *     freeMemory: os.freeMemory() / (1024 ** 3) + " GB",
- *     tmpdir: os.tmpdir()
- * });
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#os-operating-system
- */
-export declare const os: TitanCore.OS;
-
-/**
- * # Network Module
- *
- * Network utilities for DNS and IP operations. All methods are **synchronous**.
- *
- * **Methods:**
- * - `resolveDNS(hostname)` — Resolve hostname to IPs
- * - `ip()` — Get local IP address
- * - `ping(host)` — Check if host is reachable
- *
- * @example
- * ```js
- * import { net } from '@titanpl/core';
- *
- * const ips = net.resolveDNS("github.com");
- * const localIp = net.ip();
- * const reachable = net.ping("8.8.8.8");
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#net-network
- */
-export declare const net: TitanCore.Net;
-
-/**
- * # Process Module
- *
- * Runtime process information and subprocess management.
- * All methods are **synchronous**.
- *
- * **Methods:**
- * - `pid()` — Process ID
- * - `uptime()` — Uptime in seconds
- * - `memory()` — Memory usage stats
- * - `run(cmd, args, cwd)` — Spawn subprocess
- * - `kill(pid)` — Terminate process
- * - `list()` — List running processes
- *
- * @example
- * ```js
- * import { proc } from '@titanpl/core';
- *
- * console.log({
- *     pid: proc.pid(),
- *     uptime: proc.uptime() + " seconds",
- *     memory: proc.memory()
- * });
- *
- * // Spawn subprocess
- * const result = proc.run("node", ["script.js"], "./scripts");
- * if (result.ok) {
- *     console.log("Spawned PID:", result.pid);
- * }
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#proc-process
- */
-export declare const proc: TitanCore.Process;
-
-/**
- * # Time Module
- *
- * Time utilities including sleep, timestamps, and timing.
- * All methods are **synchronous**.
- *
- * **Methods:**
- * - `now()` — Current timestamp in milliseconds
- * - `timestamp()` — ISO 8601 timestamp string
- * - `sleep(ms)` — Blocking sleep
- *
- * @example
- * ```js
- * import { time } from '@titanpl/core';
- *
- * // Measure execution time
- * const start = time.now();
- * performOperation();
- * console.log(`Took ${time.now() - start}ms`);
- *
- * // Get ISO timestamp
- * const ts = time.timestamp();
- * // → "2026-01-15T12:30:45.123Z"
- *
- * // Rate limiting
- * time.sleep(100); // Wait 100ms
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#time-time
- */
-export declare const time: TitanCore.Time;
-
-/**
- * # URL Module
- *
- * URL parsing, formatting, and query string manipulation.
- * All methods are **synchronous**.
- *
- * **Methods:**
- * - `parse(url)` — Parse URL to components
- * - `format(urlObj)` — Build URL from components
- * - `SearchParams` — Query string class
- *
- * @example
- * ```js
- * import { url } from '@titanpl/core';
- *
- * // Parse URL
- * const parsed = url.parse("https://api.example.com:8080/users?page=2");
- * // → { protocol: "https:", hostname: "api.example.com", ... }
- *
- * // Build URL
- * const built = url.format({
- *     protocol: "https:",
- *     hostname: "api.example.com",
- *     pathname: "/v2/users"
- * });
- *
- * // Query strings
- * const params = new url.SearchParams({ page: "1", limit: "20" });
- * params.set("sort", "name");
- * console.log(params.toString()); // → "page=1&limit=20&sort=name"
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#url-url
- */
-export declare const url: TitanCore.URLModule;
-
-/**
- * # Buffer Module
- *
- * Binary data encoding and decoding utilities. All methods are **synchronous**.
- *
- * **Methods:**
- * - `toBase64(data)` / `fromBase64(str)` — Base64 encoding
- * - `toHex(data)` / `fromHex(str)` — Hex encoding
- * - `toUtf8(bytes)` / `fromUtf8(str)` — UTF-8 encoding
- *
- * @example
- * ```js
- * import { buffer } from '@titanpl/core';
- *
- * // Base64
- * const b64 = buffer.toBase64("Hello, World!");
- * const decoded = buffer.toUtf8(buffer.fromBase64(b64));
- *
- * // Hex
- * const hex = buffer.toHex("Hello");
- * // → "48656c6c6f"
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#buffer-buffer-utilities
- */
-export declare const buffer: TitanCore.BufferModule;
-
-/**
- * # Local Storage Module
- *
- * High-performance in-memory key-value store. All methods are **synchronous**.
- *
- * **Performance:** ~150,000+ ops/sec (native Rust RwLock<HashMap>)
- *
- * **Methods:**
- * - `get(key)` / `set(key, value)` — String storage
- * - `getObject(key)` / `setObject(key, value)` — Complex object storage
- * - `remove(key)` / `clear()` — Deletion
- * - `keys()` — List all keys
- * - `serialize(value)` / `deserialize(bytes)` — V8 serialization
- *
- * @example
- * ```js
- * import { ls } from '@titanpl/core';
- *
- * // String storage
- * ls.set("user:123", JSON.stringify({ name: "Alice" }));
- * const user = JSON.parse(ls.get("user:123") || "{}");
- *
- * // Complex objects (preserves Map, Set, Date)
- * const data = {
- *     users: new Map([["alice", { role: "admin" }]]),
- *     tags: new Set(["active"]),
- *     created: new Date()
- * };
- * ls.setObject("session", data);
- * const restored = ls.getObject("session");
- * // restored.users instanceof Map → true
- *
- * // Cleanup
- * ls.remove("user:123");
- * ls.clear();
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#ls--localstorage-persistent-storage
- */
-export declare const ls: TitanCore.LocalStorage;
-
-/**
- * # Local Storage Module (Alias)
- *
- * Alias for `ls` — same high-performance key-value store.
- *
- * @see {@link ls}
- * @see https://github.com/ezet-galaxy/-titanpl-core#ls--localstorage-persistent-storage
- */
-export declare const localStorage: TitanCore.LocalStorage;
-
-/**
- * # Session Module
- *
- * Server-side session state management. All methods are **synchronous**.
- *
- * Uses composite keys (`{sessionId}:{key}`) for session isolation.
- *
- * **Methods:**
- * - `get(sessionId, key)` — Get session value
- * - `set(sessionId, key, value)` — Set session value
- * - `delete(sessionId, key)` — Delete session key
- * - `clear(sessionId)` — Clear entire session
- *
- * @example
- * ```js
- * import { session, crypto, cookies } from '@titanpl/core';
- *
- * export function handleRequest(req) {
- *     // Get or create session ID
- *     let sessionId = cookies.get(req, "sid");
- *     if (!sessionId) {
- *         sessionId = crypto.uuid();
- *         cookies.set(req, "sid", sessionId, { httpOnly: true });
- *     }
- *
- *     // Store user data
- *     session.set(sessionId, "userId", "123");
- *     session.set(sessionId, "cart", JSON.stringify([1, 2, 3]));
- *
- *     // Retrieve data
- *     const cart = JSON.parse(session.get(sessionId, "cart") || "[]");
- *
- *     // Logout
- *     session.clear(sessionId);
- * }
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#session-server-side-sessions
- */
-export declare const session: TitanCore.Session;
-
-/**
- * # Cookies Module
- *
- * HTTP cookie parsing and setting utilities.
- *
- * **Methods:**
- * - `get(req, name)` — Read cookie from request
- * - `set(res, name, value, options)` — Set cookie on response
- * - `delete(res, name)` — Delete cookie
- *
- * **Options:** `httpOnly`, `secure`, `sameSite`, `maxAge`, `path`
- *
- * @example
- * ```js
- * import { cookies, crypto } from '@titanpl/core';
- *
- * export function auth(req) {
- *     // Read cookie
- *     const token = cookies.get(req, "auth_token");
- *
- *     if (!token) {
- *         // Set secure cookie
- *         cookies.set(req, "auth_token", crypto.uuid(), {
- *             httpOnly: true,
- *             secure: true,
- *             sameSite: "Strict",
- *             maxAge: 86400 * 7, // 7 days
- *             path: "/"
- *         });
- *     }
- *
- *     // Delete cookie (logout)
- *     cookies.delete(req, "auth_token");
- * }
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core#cookies-http-cookies
- */
-export declare const cookies: TitanCore.Cookies;
-
-/**
- * # Response Module
- *
- * HTTP response builder for controlled response formatting.
- *
- * **Methods:**
- * - `response(options)` — Custom response
- * - `response.json(data, options?)` — JSON response
- * - `response.html(content, options?)` — HTML response
- * - `response.text(content, options?)` — Plain text response
- * - `response.redirect(url, status?)` — Redirect response
- * - `response.empty(status?)` — Empty response (204)
- *
- * @example
- * ```js
- * import { response, fs } from '@titanpl/core';
- *
- * // JSON response
- * export function getUsers(req) {
- *     return response.json({ users: [], total: 0 });
- * }
- *
- * // Error response
- * export function notFound(req) {
- *     return response.json({ error: "Not found" }, { status: 404 });
- * }
- *
- * // HTML response
- * export function home(req) {
- *     const html = fs.readFile("./views/index.html");
- *     return response.html(html);
- * }
- *
- * // Redirect
- * export function legacy(req) {
- *     return response.redirect("/api/v2/users", 301);
- * }
- *
- * // Custom response with headers
- * export function download(req) {
- *     return response({
- *         status: 200,
- *         headers: {
- *             "Content-Type": "text/csv",
- *             "Content-Disposition": "attachment; filename=\"data.csv\""
- *         },
- *         body: fs.readFile("./export.csv")
- *     });
- * }
- *
- * // Empty response (after DELETE)
- * export function deleteUser(req) {
- *     removeUser(req.params.id);
- *     return response.empty();
- * }
- * ```
- *
- * @see https://titan-docs-ez.vercel.app/docs/04-runtime-apis
- */
-export declare const response: TitanCore.ResponseModule;
-
-/**
- * # Core Module
- *
- * Unified namespace providing access to all @titanpl/core APIs.
- * Useful for destructuring multiple modules at once.
- *
- * @example
- * ```js
- * import { core } from '@titanpl/core';
- *
- * // Destructure what you need
- * const { fs, crypto, os, response } = core;
- *
- * // Or access directly
- * const config = JSON.parse(core.fs.readFile("./config.json"));
- * const id = core.crypto.uuid();
- * ```
- *
- * @see https://github.com/ezet-galaxy/-titanpl-core
- */
-export declare const core: TitanCore.Core;