@ckirg/corelib 0.1.22

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Costas Kirgoussios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @ckirg/corelib
+
+The foundational package of the Corelib monorepo, providing essential utilities, resilient HTTP, structured logging, and database abstractions.
+
+> [!IMPORTANT]
+> Not on the public npm registry — install from GitHub Releases. See the [root install guide](../README.md#-installation-for-external-projects).
+
+## Features
+
+- **Multi-Runtime Support**: Compatible with Node.js, Bun, and Deno.
+- **Resilient HTTP**: `RequestUnlimited` (based on `ky`) with automatic retries and consistent error serialization.
+- **Structured Logging**: Strict Logger API with telemetry and structured data support.
+- **Database Abstraction**: Unified interface for SQLite (via LibSQL) and PostgreSQL.
+- **Configuration Management**: `ConfigManager` with support for CLI, Environment Variables, and Local/Remote encrypted files.
+- **Native Core (FFI)**: High-performance logic implemented in Rust and exposed via N-API.
+- **Runtime Utilities**: Platform-agnostic helpers for environment, file system, and telemetry.
+
+## Installation
+
+Install from the GitHub Release — see the [root install guide](../README.md#-installation-for-external-projects) for package manager overrides.
+
+```bash
+# pnpm
+pnpm add https://github.com/ckir/corelib/releases/download/v0.1.17/ckirg-corelib-0.1.17.tgz
+```
+
+## Usage Examples
+
+### 1. Resilient HTTP Requests
+Use `endPoint` for single requests or `endPoints` for parallel requests.
+
+```typescript
+import { endPoint } from '@ckirg/corelib';
+
+const result = await endPoint('https://api.github.com/repos/ckir/corelib');
+
+if (result.status === 'success') {
+  // result.value is a SerializedResponse object
+  console.log('Body:', result.value.body);
+}
+```
+
+### 2. Proxied HTTP Requests (Self-Healing, Rotating Pool)
+`RequestProxied` provides an identical API to `RequestUnlimited` but adds automatic rotation, full fallback, and automatic removal of dead proxies. The pool is self-healing — unhealthy endpoints are pruned on first failure and do not re-enter rotation.
+
+```typescript
+import { RequestProxied } from '@ckirg/corelib';
+
+const proxies = [
+  "https://proxy-us.example.com",
+  "https://proxy-eu.example.com",
+  "https://proxy-as.example.com"
+];
+
+const client = new RequestProxied(proxies);
+
+// Single request with automatic rotation and fallback
+const result = await client.endPoint("https://api.nasdaq.com/api/market-info");
+
+// Parallel requests with round-robin load balancing
+const results = await client.endPoints([
+  "https://api.nasdaq.com/api/quote/AAPL/info",
+  "https://api.nasdaq.com/api/quote/TSLA/info"
+]);
+```
+
+### 3. Structured Logging
+The logger follows a strict `(msg: string, extras?: object)` signature and handles runtime differences automatically.
+
+```typescript
+import { logger } from '@ckirg/corelib';
+
+// Basic logging
+logger.info("Application started");
+
+// Logging with structured metadata
+logger.error("Database connection failed", { 
+  host: "localhost", 
+  port: 5432,
+  error: "Connection timeout" 
+});
+
+// Telemetry support (if configured)
+logger.setTelemetry('on');
+logger.info("Critical event", { telemetry: true });
+```
+
+### 4. Unified Database API
+Switch between SQLite and PostgreSQL with minimal configuration changes.
+
+```typescript
+import { createDatabase } from '@ckirg/corelib';
+
+// SQLite
+const db = await createDatabase({
+  dialect: 'sqlite',
+  url: 'file:./app.db'
+});
+
+// PostgreSQL
+// const db = await createDatabase({
+//   dialect: 'postgres',
+//   url: 'postgres://user:pass@localhost:5432/dbname'
+// });
+
+// Querying (Returns a DatabaseResult discriminated union)
+const result = await db.query('SELECT * FROM users WHERE active = ?', [true]);
+
+if (result.status === 'success') {
+  // result.value is a QueryResponse object containing .rows
+  const users = result.value.rows;
+  console.log(`Found ${users.length} users`);
+} else {
+  console.error('Query failed:', result.reason.message);
+}
+
+// Transactions
+await db.transaction(async () => {
+  await db.query('INSERT INTO logs (msg) VALUES (?)', ['Transaction step 1']);
+  await db.query('UPDATE status SET value = ?', ['processed']);
+  // Return success from the callback to commit the transaction
+  return { status: 'success', value: true };
+});
+```
+
+
+### 5. Configuration Management
+Manage complex configuration hierarchies with ease.
+
+Both the **static** and **instance** forms of `get()` are supported by design — use whichever fits your call site. They read from the same singleton store.
+
+```typescript
+import { ConfigManager } from '@ckirg/corelib';
+
+// ── Instance form (explicit singleton) ────────────────────────────────────
+const config = ConfigManager.getInstance();
+
+// Initialize (parses CLI, Env, and local defaults). Idempotent under
+// concurrency: simultaneous calls share one in-flight run.
+await config.initialize();
+
+// Instance get — nested value with dot-notation
+const dbPort = config.get('database.port');
+
+// ── Static form (convenience shorthand — same singleton, same data) ────────
+// Both of these are equivalent after the first initialize() settles:
+const port = ConfigManager.get('database.port');
+
+// Load external encrypted configuration
+await config.loadExternalConfig('https://remote-server.com/prod.json.enc');
+
+// Reactive updates
+config.on('change:database.port', (newPort) => {
+  console.log(`Port changed to ${newPort}`);
+});
+```
+
+#### Readiness
+
+`get()` is synchronous and never throws — bundled defaults are seeded in the
+constructor, so reads are safe even before `initialize()` resolves (a one-time
+dev warning fires if you read pre-init, suppressed in production). Long-lived
+orchestrators (DB connections, stream wrappers) that need *resolved* config
+should gate on readiness:
+
+```typescript
+if (!config.isInitialized) {
+  await config.whenReady(); // resolves when the first initialize() settles
+}
+```
+
+> **Anti-pattern — don't cache a sub-section at module scope.** Read at the hot
+> point instead. `this._config`'s object identity is stable (mutation is in
+> place), but caching a nested slice can still mask a later override:
+>
+> ```typescript
+> // ❌ captured once at import; may miss overrides applied during initialize()
+> const db = ConfigManager.getInstance().get('database');
+>
+> // ✅ read at the use site (static or instance — both work)
+> const port = ConfigManager.get('database.port');
+> ```
+
+### 6. Native Core FFI
+Access high-performance Rust logic directly from TypeScript. The implementation is resilient and will disable FFI features if the native binary is missing rather than crashing the module.
+
+```typescript
+import { Core } from '@ckirg/corelib';
+
+// Check if FFI is available in current runtime
+if (Core.isFfiAvailable()) {
+  console.log('Rust Version:', Core.getVersion());
+  const doubled = Core.logAndDouble("Double me", 21);
+  console.log('Result:', doubled); // 42
+}
+
+// Safe run method that includes runtime info
+Core.run("maintenance-task", { verbose: true });
+```
+
+### 7. Runtime Utilities
+Platform-agnostic helpers for common tasks.
+
+**Key Helpers**:
+- `detectRuntime()` — returns current runtime (`"node" | "bun" | "deno" | ...`)
+- `sleep(ms)` — cross-runtime delay
+- `getEnv(key)`, `getAllEnv()` — safe environment access
+- `getSysInfo()` — detailed system info with automatic secret redaction
+- `includeExcludeCron` — helpers for complex cron include/exclude patterns
+- File system helpers with graceful fallbacks across runtimes
+
+```typescript
+import { detectRuntime, sleep, getEnv, getSysInfo } from '@ckirg/corelib';
+
+// Detect where we are (node, bun, deno, cloudflare, aws-lambda, etc.)
+const runtime = detectRuntime();
+
+// Resilient sleep
+await sleep(1000);
+
+// Platform-agnostic env access
+const apiKey = getEnv('API_KEY');
+
+// Detailed system and process telemetry (auto-redacts secrets)
+const sysInfo = getSysInfo();
+console.log('Memory Usage:', sysInfo.memory.rss);
+```
+

package/dist/RequestUnlimited-CLB36IJX.js

@@ -0,0 +1,27 @@
+import {
+  DEFAULT_REQUEST_OPTIONS,
+  MAX_BACKOFF_LIMIT_MS,
+  MAX_RETRY_LIMIT,
+  MAX_TIMEOUT_MS,
+  MIN_TIMEOUT_MS,
+  RequestUnlimited,
+  clampNumber,
+  endPoint,
+  endPoints,
+  fullJitterDelay
+} from "./chunk-PESRDNPD.js";
+import "./chunk-BAVE2JXI.js";
+import "./chunk-2DF4ADYX.js";
+import "./chunk-HPE2XSTW.js";
+export {
+  DEFAULT_REQUEST_OPTIONS,
+  MAX_BACKOFF_LIMIT_MS,
+  MAX_RETRY_LIMIT,
+  MAX_TIMEOUT_MS,
+  MIN_TIMEOUT_MS,
+  RequestUnlimited,
+  clampNumber,
+  endPoint,
+  endPoints,
+  fullJitterDelay
+};

package/dist/browser.d.ts

@@ -0,0 +1,6 @@
+import { S as StrictLogger } from './flight-recorder-BCSVZvWQ.js';
+export { F as FlightRecorderExtras, L as LogMethod, n as nextCid } from './flight-recorder-BCSVZvWQ.js';
+
+declare const logger: StrictLogger;
+
+export { StrictLogger, logger };

package/dist/browser.js

@@ -0,0 +1,75 @@
+import {
+  nextCid
+} from "./chunk-2DF4ADYX.js";
+
+// src/loggers/implementations/browser.ts
+var LEVEL_MAP = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+  silent: Infinity
+};
+var envLevel = (typeof process !== "undefined" ? process.env?.LOG_LEVEL : void 0) || "info";
+var BrowserLogger = class _BrowserLogger {
+  ctx;
+  // Shared state object so children reflect parent level changes (non-independent).
+  state;
+  constructor(ctx = {}, state = { level: envLevel }) {
+    this.ctx = ctx;
+    this.state = state;
+  }
+  get level() {
+    return this.state.level;
+  }
+  set level(val) {
+    this.state.level = val;
+  }
+  get levelVal() {
+    return LEVEL_MAP[this.state.level] ?? 30;
+  }
+  emit(lvl, consoleFn, msg, extras) {
+    if ((LEVEL_MAP[lvl] ?? 30) < this.levelVal) return;
+    consoleFn(`[${lvl.toUpperCase()}]`, msg, { ...this.ctx, ...extras });
+  }
+  trace(msg, extras) {
+    this.emit("trace", console.debug.bind(console), msg, extras);
+  }
+  debug(msg, extras) {
+    this.emit("debug", console.debug.bind(console), msg, extras);
+  }
+  info(msg, extras) {
+    this.emit("info", console.info.bind(console), msg, extras);
+  }
+  warn(msg, extras) {
+    this.emit("warn", console.warn.bind(console), msg, extras);
+  }
+  error(msg, extras) {
+    this.emit("error", console.error.bind(console), msg, extras);
+  }
+  fatal(msg, extras) {
+    this.emit("fatal", console.error.bind(console), msg, extras);
+  }
+  child(bindings) {
+    return new _BrowserLogger({ ...this.ctx, ...bindings }, this.state);
+  }
+  setTelemetry(_mode) {
+  }
+  bindings() {
+    return { ...this.ctx };
+  }
+  silent() {
+    this.state.level = "silent";
+  }
+  flush(cb) {
+    cb?.();
+  }
+};
+var logger = new BrowserLogger();
+var browser_default = logger;
+export {
+  browser_default as logger,
+  nextCid
+};

package/dist/bun-LDGTNQBK.js

@@ -0,0 +1,41 @@
+import {
+  StrictLoggerWrapper
+} from "./chunk-HOOAMOFY.js";
+import "./chunk-HPE2XSTW.js";
+
+// src/loggers/implementations/bun.ts
+import { Writable } from "stream";
+import pino from "pino";
+import pretty from "pino-pretty";
+var isPretty = process.env.LOG_PRETTY === "true" || process.env.NODE_ENV !== "production" && process.env.LOG_PRETTY !== "false";
+var level = process.env.LOG_LEVEL || "info";
+var wsProxy = new Writable({
+  write(chunk, _encoding, cb) {
+    const fn = globalThis.__wsLogWrite;
+    if (fn) fn(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+    cb();
+  }
+});
+var dest = pino.multistream([
+  {
+    level,
+    stream: isPretty ? pretty({
+      colorize: true,
+      translateTime: "SYS:standard",
+      ignore: "pid,hostname"
+    }) : process.stdout
+  },
+  { level, stream: wsProxy }
+]);
+var pinoInstance = pino(
+  {
+    level,
+    redact: ["password", "secret", "token", "authorization", "apiKey"]
+  },
+  dest
+);
+var logger = new StrictLoggerWrapper(pinoInstance);
+var bun_default = logger;
+export {
+  bun_default as default
+};

package/dist/chunk-2DF4ADYX.js

@@ -0,0 +1,9 @@
+// src/utils/flight-recorder.ts
+var _cid = 0;
+function nextCid() {
+  return ++_cid;
+}
+
+export {
+  nextCid
+};

package/dist/chunk-BAVE2JXI.js

@@ -0,0 +1,207 @@
+import {
+  detectRuntime
+} from "./chunk-HPE2XSTW.js";
+
+// src/loggers/index.ts
+var runtime = detectRuntime();
+async function loadLogger() {
+  let impl;
+  switch (runtime) {
+    case "cloudflare":
+      impl = await import("./cloudflare-IOVZ3QEK.js");
+      break;
+    case "aws-lambda":
+      impl = await import("./lambda-CQXJKGN5.js");
+      break;
+    case "gcp-cloudrun":
+      impl = await import("./gcp-TRX5BADQ.js");
+      break;
+    case "bun":
+      impl = await import("./bun-LDGTNQBK.js");
+      break;
+    case "deno":
+      impl = await import("./deno-MVIUW5GX.js");
+      break;
+    default:
+      impl = await import("./node-6V4FDE5Z.js");
+      break;
+  }
+  const loggerRaw = impl.default;
+  const logger = typeof loggerRaw === "function" ? loggerRaw() : loggerRaw;
+  globalThis.logger = logger;
+  return logger;
+}
+var loggers_default = await loadLogger();
+
+// src/utils/cron.ts
+import { Cron } from "croner";
+function includeExcludeCron(includeExprs, excludeExprs, handler, timezone) {
+  const opts = timezone ? { timezone } : {};
+  const job = new Cron("* * * * * *", () => {
+    const now = /* @__PURE__ */ new Date();
+    const included = includeExprs.some((expr) => {
+      const c = new Cron(expr, opts);
+      return c.nextRun(now) === null;
+    });
+    if (!included) return;
+    const excluded = excludeExprs.some((expr) => {
+      const c = new Cron(expr, opts);
+      return c.nextRun(now) === null;
+    });
+    if (!excluded) {
+      handler();
+    }
+  });
+  return job;
+}
+
+// src/utils/index.ts
+var _createRequire;
+if (typeof __EDGE_RUNTIME__ === "undefined" || !__EDGE_RUNTIME__) {
+  _createRequire = (await import("module")).createRequire;
+}
+var utilsLogger = loggers_default.child({ section: "Utils" });
+var _require;
+var getRequire = () => {
+  if (!_require) {
+    const runtime2 = detectRuntime();
+    if (_createRequire && typeof import.meta !== "undefined" && import.meta.url) {
+      try {
+        _require = _createRequire(import.meta.url);
+      } catch (_e) {
+      }
+    }
+    if (!_require && typeof globalThis.require === "function") {
+      _require = globalThis.require;
+    }
+    if (!_require) {
+      _require = (path) => {
+        throw new Error(
+          `require("${path}") is not available in this runtime (${runtime2}).`
+        );
+      };
+    }
+  }
+  return _require;
+};
+var Utils = {
+  /**
+   * Logs the current runtime information.
+   */
+  run: () => utilsLogger.info(`Running on ${detectRuntime()}`)
+};
+var getEnv = (key) => {
+  try {
+    if (typeof Deno !== "undefined" && Deno.env) {
+      return Deno.env.get(key);
+    }
+  } catch {
+  }
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return process.env[key];
+    }
+  } catch {
+  }
+  return void 0;
+};
+var getAllEnv = () => {
+  try {
+    if (typeof Deno !== "undefined" && Deno.env) {
+      return Deno.env.toObject();
+    }
+  } catch {
+  }
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return { ...process.env };
+    }
+  } catch {
+  }
+  return {};
+};
+var readTextFileSync = (file) => {
+  if (typeof Deno !== "undefined" && Deno.readTextFileSync) {
+    return Deno.readTextFileSync(file);
+  }
+  const { readFileSync } = getRequire()("node:fs");
+  return readFileSync(file, "utf8");
+};
+var existsSync = (file) => {
+  if (typeof Deno !== "undefined" && Deno.statSync) {
+    try {
+      Deno.statSync(file);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const { existsSync: existsSync2 } = getRequire()("node:fs");
+  return existsSync2(file);
+};
+var getCwd = () => {
+  if (typeof Deno !== "undefined" && Deno.cwd) {
+    return Deno.cwd();
+  }
+  if (typeof process !== "undefined" && process.cwd) {
+    return process.cwd();
+  }
+  return "/";
+};
+var getDirname = () => {
+  const runtime2 = detectRuntime();
+  if (runtime2 === "deno") {
+    return new URL(".", import.meta.url).pathname;
+  }
+  if (typeof import.meta !== "undefined" && import.meta.url) {
+    const url = new URL(import.meta.url);
+    if (url.protocol === "file:") {
+      const { dirname } = getRequire()("node:path");
+      const { fileURLToPath } = getRequire()("node:url");
+      return dirname(fileURLToPath(import.meta.url));
+    }
+    const path = url.pathname;
+    return path.substring(0, path.lastIndexOf("/"));
+  }
+  return "";
+};
+var getPlatform = () => {
+  const runtime2 = detectRuntime();
+  let plat;
+  if (runtime2 === "deno") {
+    plat = Deno.build.os;
+  } else {
+    plat = process.platform;
+  }
+  return plat === "win32" || plat === "windows" ? "windows" : "linux";
+};
+var getMode = () => {
+  const env = getEnv("NODE_ENV")?.toLowerCase();
+  return env === "production" ? "production" : "development";
+};
+var getTempDir = () => {
+  if (detectRuntime() === "deno") {
+    return Deno.env.get("TMPDIR") || Deno.env.get("TEMP") || "/tmp";
+  } else {
+    const os = getRequire()("node:os");
+    return os.tmpdir();
+  }
+};
+var sleep = (ms) => new Promise((res) => setTimeout(res, ms));
+
+export {
+  loggers_default,
+  includeExcludeCron,
+  getRequire,
+  Utils,
+  getEnv,
+  getAllEnv,
+  readTextFileSync,
+  existsSync,
+  getCwd,
+  getDirname,
+  getPlatform,
+  getMode,
+  getTempDir,
+  sleep
+};