@ckir/corelib

The foundational package of the Corelib monorepo, providing essential utilities, resilient HTTP, structured logging, and database abstractions.

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.

Installation

pnpm add @ckir/corelib
Copy

Usage Examples

1. Resilient HTTP Requests

Use endPoint for single requests or endPoints for parallel requests.

import { endPoint } from '@ckir/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);
}
Copy

2. Proxied HTTP Requests (Rotation & Fallback)

RequestProxied provides an identical API to RequestUnlimited but adds automatic rotation, full fallback, and automatic removal of dead proxies.

import { RequestProxied } from '@ckir/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
// If proxy1 fails, it tries proxy2, then proxy3 before returning error.
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",
  "https://api.nasdaq.com/api/quote/NVDA/info"
]);
Copy

3. Structured Logging

The logger follows a strict (msg: string, extras?: object) signature.

import { logger } from '@ckir/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 });
Copy

3. Unified Database API

Switch between SQLite and PostgreSQL with minimal configuration changes.

import { createDatabase } from '@ckir/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
const users = await db.query('SELECT * FROM users WHERE active = ?', [true]);

// 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 { status: 'success', value: true };
});
Copy

4. Configuration Management

Manage complex configuration hierarchies with ease.

import { ConfigManager } from '@ckir/corelib';

const config = ConfigManager.getInstance();

// Initialize (parses CLI, Env, and local defaults)
await config.initialize();

// Get nested value with dot-notation
const dbPort = config.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}`);
});
Copy

5. Native Core FFI

Access high-performance Rust logic directly from TypeScript.

import { Core } from '@ckir/corelib';

// Check if FFI is available in current runtime
if (Core.isFfiAvailable()) {
  const result = Core.run("some-task", { param: 123 });
  console.log("FFI Result:", result);
}
Copy