@rx-ted/packages-core 1.0.1

package/README.md

@@ -0,0 +1,118 @@
+# @rx-ted/packages-core
+
+Unified runtime context, environment config, and logging for multi-platform TypeScript (Node, Bun, Deno, Cloudflare Workers, Vercel Edge).
+
+```
+packages/core/src/
+├── config/          — Runtime detection, env vars, dotenv loading
+│   ├── runtime.ts       Runtime detection (node/bun/deno/cf/edge)
+│   ├── env.ts           Env class (get / var / require / setLogger)
+│   ├── dotenv.ts        parseDotenv + async loadEnv with directory traversal
+│   ├── prefixes.ts      resolveKey / filterKeys for prefixed env vars
+│   ├── create-env.ts    Zod-schema-driven typed env validation
+│   └── runtime-helpers.ts  createNodeContext / createCloudflareContext
+├── logger/          — Console and Pino logging
+│   ├── types.ts         ILogger / NOOP_LOGGER / LoggerOptions
+│   ├── logger.ts        Logger class (Console fallback → Pino upgrade)
+│   └── console-logger.ts  Zero-dependency console implementation
+└── utils/
+    └── shared.ts        ConfigError / assertString / assertNumber / assertBoolean / assertUrl
+```
+
+All tests are co-located with their source files (`*.test.ts` next to each module).
+
+## Usage
+
+```ts
+import { env, Runtime, Logger } from '@rx-ted/packages-core';
+```
+
+### Runtime
+
+Detect platform and access per-request context (ALS-based):
+
+```ts
+Runtime.platform()           // 'node' | 'bun' | 'deno' | 'cloudflare' | 'vercel-edge'
+Runtime.env()                // platform-aware env source
+Runtime.request()            // current Request (inside run())
+Runtime.run({ platform, env, request }, () => { /* per-request scope */ })
+```
+
+### Env
+
+```ts
+env.get('PORT')              // string | undefined
+env.get('PORT', 'number')    // number | undefined
+env.var('DB_PATH', './db')   // string — falls back to './db' if unset
+env.require('JWT_SECRET')    // string — throws if missing
+env.has('SOME_KEY')          // boolean
+env.setLogger(logger)        // inject ILogger for debug traces
+```
+
+### Logger
+
+```ts
+const log = new Logger({ name: 'app', level: 'debug' });
+// or
+const log = createLogger({ name: 'app', level: 'info', destination: 'logs/app.log' });
+
+log.debug('connecting to %s', host);
+log.info({ userId }, 'user logged in');
+log.error(err, 'request failed');
+log.child({ module: 'auth' }).warn('rate limit hit');
+```
+
+- **Node/Bun**: upgrades from `ConsoleLogger` → `pino` (async, best-effort)
+- **Edge/CF**: uses `ConsoleLogger` directly (no dynamic imports)
+- **File output**: set `destination` — adds `pino/file` transport automatically
+- **NOOP_LOGGER**: import for tests or when logging should be silenced
+
+### Dotenv
+
+```ts
+await loadEnv();             // searches .env up to 3 parent dirs from CWD
+await loadEnv('/path');      // start search from /path
+```
+
+Strategy: `.env` (base) → merges `.env.dev` if `DEBUG=true` or `.env.prod` if not.
+Safe in Cloudflare Workers (returns `{}` when filesystem unavailable).
+
+### Zod-schema env validation
+
+```ts
+import { createEnv, z } from '@rx-ted/packages-core';
+
+const cfg = createEnv({
+  schema: { PORT: z.coerce.number().default(3000) },
+  prefixes: ['MY_APP'],
+});
+// reads MY_APP_PORT → falls back to PORT → defaults to 3000
+```
+
+### getSchema
+
+```ts
+import { getSchema, z } from '@rx-ted/packages-core';
+
+const db = getSchema('DB', {
+  host: z.string().default('127.0.0.1'),
+  port: z.coerce.number().default(3306),
+  user: z.string(),
+  password: z.string(),
+});
+// Reads DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
+```
+
+## Platform compatibility
+
+| Feature        | Node | Bun | Deno | Cloudflare | Vercel Edge |
+|----------------|------|-----|------|------------|-------------|
+| Runtime        | ✅   | ✅  | ✅   | ✅         | ✅          |
+| Env (get/var)  | ✅   | ✅  | ✅   | ✅         | ✅          |
+| Env (require)  | ✅   | ✅  | ✅   | ✅         | ✅          |
+| loadEnv        | ✅   | ✅  | ❌   | ❌ (safe)  | ❌ (safe)   |
+| Logger (console)| ✅   | ✅  | ✅   | ✅         | ✅          |
+| Logger (pino)  | ✅   | ✅  | ❌   | ❌         | ❌          |
+| Logger (file)  | ✅   | ✅  | ❌   | ❌         | ❌          |
+
+The package exports a single barrel (`index.ts`) — all platforms import from `@rx-ted/packages-core`.

package/dist/config/create-env.d.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+import { Platform } from './platform';
+type EnvSource = Record<string, string | undefined>;
+type ZodSchemaMap = Record<string, z.ZodTypeAny>;
+type InferEnv<T extends ZodSchemaMap> = {
+    [K in keyof T]: z.infer<T[K]>;
+} & {
+    toJSON(): Record<string, unknown>;
+};
+export interface CreateEnvOptions<T extends ZodSchemaMap> {
+    schema: T;
+    prefixes?: string[];
+    runtimeEnv?: EnvSource;
+    runtime?: Platform;
+    skipValidation?: boolean;
+}
+export declare function createEnv<T extends ZodSchemaMap>(options: CreateEnvOptions<T>): InferEnv<T>;
+export {};

package/dist/config/create-env.js

@@ -0,0 +1,43 @@
+import { Platform } from './platform';
+import { resolveKey } from './prefixes';
+import { ConfigError } from '../utils/shared';
+export function createEnv(options) {
+    const { schema, prefixes = [] } = options;
+    const source = options.runtimeEnv ?? Platform.env();
+    const validated = {};
+    for (const key of Object.keys(schema)) {
+        const raw = resolveKey(key, source, prefixes);
+        const zodSchema = schema[key];
+        const result = zodSchema.safeParse(raw);
+        if (result.success) {
+            validated[key] = result.data;
+        }
+        else if (raw === undefined) {
+            const defResult = zodSchema.safeParse(undefined);
+            if (defResult.success) {
+                validated[key] = defResult.data;
+            }
+            else if (!options.skipValidation) {
+                throw new ConfigError(`Validation failed for "${key}": ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+            }
+        }
+        else if (!options.skipValidation) {
+            throw new ConfigError(`Validation failed for "${key}": ${result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+        }
+    }
+    return new Proxy(validated, {
+        get(target, prop) {
+            if (prop === 'toJSON')
+                return () => ({ ...target });
+            if (typeof prop === 'string' && prop in target)
+                return target[prop];
+            return undefined;
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+}

package/dist/config/dotenv.d.ts

@@ -0,0 +1,20 @@
+export type DotenvOptions = never;
+declare function loadEnvImpl(cwd?: string): Promise<Record<string, string>>;
+/**
+ * Load .env file chain — safe for drizzle configs and other Node-only CLI tools.
+ * Returns {} when filesystem is unavailable.
+ */
+export declare const loadEnvSync: typeof loadEnvImpl;
+/**
+ * Load .env file chain by searching up to 3 parent directories from `cwd`.
+ *
+ * Strategy (from lowest to highest priority):
+ * 1. `.env` — always loaded as base
+ * 2. If `DEBUG=true` → `.env.dev` overrides base
+ * 3. If `DEBUG=false` → `.env.prod` overrides base
+ *
+ * Safe in Cloudflare Workers — returns `{}` when filesystem is unavailable.
+ */
+export declare const loadEnv: typeof loadEnvImpl;
+export declare function parseDotenv(content: string): Record<string, string>;
+export {};

package/dist/config/dotenv.js

@@ -0,0 +1,76 @@
+import { getNodeModules } from './node-modules';
+async function loadEnvImpl(cwd) {
+    const modules = await getNodeModules();
+    if (!modules)
+        return {};
+    const { readFileSync, existsSync, resolve } = modules;
+    const startDir = cwd ?? (typeof process !== 'undefined' ? process.cwd() : '');
+    if (!startDir)
+        return {};
+    function findUp(filename) {
+        let dir = startDir;
+        for (let i = 0; i < 4; i++) {
+            const filePath = resolve(dir, filename);
+            if (existsSync(filePath))
+                return filePath;
+            const parent = resolve(dir, '..');
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    }
+    const env = {};
+    const envPath = findUp('.env');
+    if (envPath) {
+        Object.assign(env, parseDotenv(readFileSync(envPath, 'utf-8')));
+    }
+    else {
+        return env;
+    }
+    const isDebug = process.env.DEBUG === 'true';
+    const overrideName = isDebug ? '.env.dev' : '.env.prod';
+    const overridePath = findUp(overrideName);
+    if (overridePath) {
+        Object.assign(env, parseDotenv(readFileSync(overridePath, 'utf-8')));
+    }
+    for (const [key, value] of Object.entries(env)) {
+        if (!(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Load .env file chain — safe for drizzle configs and other Node-only CLI tools.
+ * Returns {} when filesystem is unavailable.
+ */
+export const loadEnvSync = loadEnvImpl;
+/**
+ * Load .env file chain by searching up to 3 parent directories from `cwd`.
+ *
+ * Strategy (from lowest to highest priority):
+ * 1. `.env` — always loaded as base
+ * 2. If `DEBUG=true` → `.env.dev` overrides base
+ * 3. If `DEBUG=false` → `.env.prod` overrides base
+ *
+ * Safe in Cloudflare Workers — returns `{}` when filesystem is unavailable.
+ */
+export const loadEnv = loadEnvImpl;
+export function parseDotenv(content) {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('='))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        const key = trimmed.slice(0, eqIndex).trim();
+        let raw = trimmed.slice(eqIndex + 1).trim();
+        if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+            raw = raw.slice(1, -1);
+        }
+        if (key)
+            result[key] = raw;
+    }
+    return result;
+}

package/dist/config/env.d.ts

@@ -0,0 +1,39 @@
+import type { Platform as PlatformType } from './platform';
+import type { DotenvOptions } from './dotenv';
+import type { z } from 'zod';
+export type EnvMode = 'prod' | 'dev';
+export declare const ENV_SYMBOL: unique symbol;
+export declare class Env {
+    private _env;
+    private _ctx;
+    constructor(env?: Record<string, any>, ctx?: Record<string, any>);
+    get platform(): PlatformType;
+    get mode(): EnvMode;
+    get DEBUG(): boolean;
+    /** Read from merged source: ctx overrides env. Supports all value types. */
+    get(key: string): any;
+    get(key: string, type: 'string'): string;
+    get(key: string, type: 'number'): number;
+    get(key: string, type: 'boolean'): boolean;
+    get(key: string, type: 'url'): URL;
+    /** Read from pre-boot env only (process.env style). */
+    var(key: string): any;
+    var(key: string, defaultValue: string): string;
+    /** Read from runtime bindings only (CF D1/KV/R2 etc.). */
+    ctx(key: string): any;
+    /** Merged read, throws if missing. */
+    require(key: string): string;
+    has(key: string): boolean;
+    /** Write to pre-boot env source. Returns this for chaining. */
+    set(key: string, value: any): this;
+    toObject(): Record<string, any>;
+    /** Parse a group of env vars by Zod schema, with optional prefix fallback. */
+    schema<T extends Record<string, z.ZodTypeAny>>(schema: T, opts?: {
+        prefix?: string;
+        prefixes?: string[];
+    }): {
+        [K in keyof T]: z.output<T[K]>;
+    };
+    loadDotenv(_options?: DotenvOptions): Promise<this>;
+}
+export declare const env: Env;

package/dist/config/env.js

@@ -0,0 +1,99 @@
+import { detectPlatform } from './platform';
+import { assertString, assertNumber, assertBoolean, assertUrl } from '../utils/shared';
+import { resolveKey } from './prefixes';
+export const ENV_SYMBOL = Symbol('app:env');
+export class Env {
+    _env;
+    _ctx;
+    constructor(env, ctx) {
+        this._env = env ?? {};
+        this._ctx = ctx ?? {};
+    }
+    get platform() {
+        return detectPlatform();
+    }
+    get mode() {
+        const debugRaw = this._env.DEBUG ?? this._ctx.DEBUG;
+        const raw = this._env.NODE_ENV ?? this._env.APP_ENV ?? this._ctx.NODE_ENV ?? 'dev';
+        const intended = raw === 'production' || raw === 'prod' ? 'prod' : 'dev';
+        if (debugRaw === 'false') {
+            if (intended === 'dev') {
+                console.warn('[packages-core] DEBUG=false overrides mode="dev" → using mode="prod". ' +
+                    'Set NODE_ENV=production or APP_ENV=prod to suppress this warning.');
+            }
+            return 'prod';
+        }
+        if (debugRaw === 'true') {
+            if (intended === 'prod') {
+                console.warn('[packages-core] DEBUG=true overrides mode="prod" → using mode="dev". ' +
+                    'Set NODE_ENV=development or remove DEBUG=true to suppress this warning.');
+            }
+            return 'dev';
+        }
+        return intended;
+    }
+    get DEBUG() {
+        const explicit = this._env.DEBUG ?? this._ctx.DEBUG;
+        if (explicit === 'true')
+            return true;
+        if (explicit === 'false')
+            return false;
+        return this.mode !== 'prod';
+    }
+    get(key, type) {
+        const raw = key in this._ctx ? this._ctx[key] : this._env[key];
+        if (type === 'string')
+            return assertString(key, raw);
+        if (type === 'number')
+            return assertNumber(key, raw);
+        if (type === 'boolean')
+            return assertBoolean(key, raw);
+        if (type === 'url')
+            return assertUrl(key, raw);
+        return raw;
+    }
+    var(key, defaultValue) {
+        const raw = this._env[key];
+        return raw ?? defaultValue;
+    }
+    /** Read from runtime bindings only (CF D1/KV/R2 etc.). */
+    ctx(key) {
+        return this._ctx[key];
+    }
+    /** Merged read, throws if missing. */
+    require(key) {
+        const raw = key in this._ctx ? this._ctx[key] : this._env[key];
+        return assertString(key, raw);
+    }
+    has(key) {
+        return key in this._env || key in this._ctx;
+    }
+    /** Write to pre-boot env source. Returns this for chaining. */
+    set(key, value) {
+        this._env[key] = value;
+        return this;
+    }
+    toObject() {
+        return { ...this._env, ...this._ctx };
+    }
+    /** Parse a group of env vars by Zod schema, with optional prefix fallback. */
+    schema(schema, opts) {
+        const source = { ...this._env, ...this._ctx };
+        const allPrefixes = opts?.prefix
+            ? [opts.prefix, ...(opts.prefixes ?? [])]
+            : (opts?.prefixes ?? []);
+        const result = {};
+        for (const [key, zodType] of Object.entries(schema)) {
+            const upperKey = key.toUpperCase();
+            const prefixedKey = allPrefixes.length > 0
+                ? resolveKey(upperKey, source, allPrefixes.map((p) => `${p}_`))
+                : source[upperKey];
+            result[key] = zodType.parse(prefixedKey ?? undefined);
+        }
+        return result;
+    }
+    loadDotenv(_options) {
+        throw new Error('[packages-core] env.loadDotenv() is removed. Use Platform.setAppContext() to provide env data at startup.');
+    }
+}
+export const env = typeof process !== 'undefined' ? new Env(process.env, {}) : new Env({}, {});

package/dist/config/node-modules.d.ts

@@ -0,0 +1,6 @@
+export interface NodeModules {
+    readFileSync: (path: string, encoding: string) => string;
+    existsSync: (path: string) => boolean;
+    resolve: (...parts: string[]) => string;
+}
+export declare function getNodeModules(): Promise<NodeModules | null>;

package/dist/config/node-modules.js

@@ -0,0 +1,17 @@
+let cached = null;
+export async function getNodeModules() {
+    if (cached)
+        return cached;
+    try {
+        const [fs, path] = await Promise.all([import('node:fs'), import('node:path')]);
+        cached = {
+            readFileSync: fs.readFileSync,
+            existsSync: fs.existsSync,
+            resolve: path.resolve,
+        };
+        return cached;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/config/platform.d.ts

@@ -0,0 +1,20 @@
+export type Platform = 'node' | 'bun' | 'deno' | 'cloudflare' | 'vercel-edge';
+export interface RuntimeContext {
+    platform: Platform;
+    env: Record<string, any>;
+    request?: Request;
+    executionContext?: unknown;
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+declare function detectPlatform(): Platform;
+declare function resetDetection(): void;
+export { detectPlatform, resetDetection };
+export declare const Platform: {
+    run<T>(context: RuntimeContext, fn: () => T): T;
+    context(): RuntimeContext;
+    env(): Record<string, string | undefined>;
+    request(): Request | undefined;
+    platform(): Platform;
+    setAppContext(context: RuntimeContext): void;
+    clearAppContext(): void;
+};

package/dist/config/platform.js

@@ -0,0 +1,75 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const als = new AsyncLocalStorage();
+let appContext = null;
+let cached = null;
+function detectPlatform() {
+    if (cached)
+        return cached;
+    const g = globalThis;
+    if (typeof g.Deno !== 'undefined') {
+        cached = 'deno';
+        return cached;
+    }
+    if (typeof g.Bun !== 'undefined') {
+        cached = 'bun';
+        return cached;
+    }
+    if (typeof g.navigator !== 'undefined' && g.navigator?.userAgent === 'Cloudflare-Workers') {
+        cached = 'cloudflare';
+        return cached;
+    }
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        cached = 'node';
+        return cached;
+    }
+    if (typeof process !== 'undefined' && process.env) {
+        cached = 'vercel-edge';
+        return cached;
+    }
+    cached = 'node';
+    return cached;
+}
+function resetDetection() {
+    cached = null;
+}
+export { detectPlatform, resetDetection };
+function defaultEnv() {
+    if (typeof process !== 'undefined' && process.env)
+        return process.env;
+    return {};
+}
+function union(a, b) {
+    return { ...a, ...b };
+}
+export const Platform = {
+    run(context, fn) {
+        const hasEnv = Object.keys(context.env).length > 0;
+        if (!hasEnv) {
+            console.warn('[Platform.run] env is empty — D1 bindings and other platform resources will not be available. ' +
+                'Ensure Platform.setAppContext() is called before run(), or pass env in the context.');
+        }
+        return als.run(context, fn);
+    },
+    context() {
+        return als.getStore() ?? appContext ?? { platform: detectPlatform(), env: defaultEnv() };
+    },
+    env() {
+        const ctx = Platform.context();
+        if (als.getStore() && appContext) {
+            return union(appContext.env, ctx.env);
+        }
+        return ctx.env;
+    },
+    request() {
+        return Platform.context().request;
+    },
+    platform() {
+        return Platform.context().platform;
+    },
+    setAppContext(context) {
+        appContext = context;
+    },
+    clearAppContext() {
+        appContext = null;
+    },
+};

package/dist/config/prefixes.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveKey(key: string, source: Record<string, string | undefined>, prefixes?: string[]): string | undefined;
+export declare function filterKeys(source: Record<string, string | undefined>, prefixes: string[]): Record<string, string>;

package/dist/config/prefixes.js

@@ -0,0 +1,22 @@
+export function resolveKey(key, source, prefixes = []) {
+    if (key in source)
+        return source[key];
+    for (const prefix of prefixes) {
+        const prefixed = `${prefix}${key}`;
+        if (prefixed in source)
+            return source[prefixed];
+    }
+    return undefined;
+}
+export function filterKeys(source, prefixes) {
+    const result = {};
+    for (const key of Object.keys(source)) {
+        for (const prefix of prefixes) {
+            if (key.startsWith(prefix)) {
+                result[key] = source[key] ?? '';
+                break;
+            }
+        }
+    }
+    return result;
+}

package/dist/config/runtime-helpers.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeContext } from './platform';
+export declare function createNodeContext(env?: Record<string, string | undefined>, request?: Request): RuntimeContext;
+export declare function createCloudflareContext(env: Record<string, string | undefined>, request?: Request, executionContext?: unknown): RuntimeContext;

package/dist/config/runtime-helpers.js

@@ -0,0 +1,15 @@
+export function createNodeContext(env, request) {
+    return {
+        platform: 'node',
+        env: env ?? (typeof process !== 'undefined' ? process.env : {}),
+        request,
+    };
+}
+export function createCloudflareContext(env, request, executionContext) {
+    return {
+        platform: 'cloudflare',
+        env,
+        request,
+        executionContext,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { Platform, detectPlatform, resetDetection } from './config/platform';
+export type { RuntimeContext } from './config/platform';
+export { createNodeContext, createCloudflareContext } from './config/runtime-helpers';
+export { ConfigError, ConfigTypeError, resolveBinding } from './utils/shared';
+export { resolveKey, filterKeys } from './config/prefixes';
+export { parseDotenv, loadEnv, loadEnvSync } from './config/dotenv';
+export { Env, env, ENV_SYMBOL } from './config/env';
+export type { EnvMode } from './config/env';
+export { createEnv } from './config/create-env';
+export type { CreateEnvOptions } from './config/create-env';
+export { createLogger, Logger, createFileTransport } from './logger/logger';
+export { LOGGER_SYMBOL, NOOP_LOGGER } from './logger/types';
+export { ConsoleLogger } from './logger/console-logger';
+export type { ILogger, LoggerOptions, LogLevel, PinoTransportTarget, FileTransportOptions, } from './logger/types';

package/dist/index.js

@@ -0,0 +1,12 @@
+// ── Config (env, platform, dotenv) ──
+export { Platform, detectPlatform, resetDetection } from './config/platform';
+export { createNodeContext, createCloudflareContext } from './config/runtime-helpers';
+export { ConfigError, ConfigTypeError, resolveBinding } from './utils/shared';
+export { resolveKey, filterKeys } from './config/prefixes';
+export { parseDotenv, loadEnv, loadEnvSync } from './config/dotenv';
+export { Env, env, ENV_SYMBOL } from './config/env';
+export { createEnv } from './config/create-env';
+// ── Logger ──
+export { createLogger, Logger, createFileTransport } from './logger/logger';
+export { LOGGER_SYMBOL, NOOP_LOGGER } from './logger/types';
+export { ConsoleLogger } from './logger/console-logger';

package/dist/logger/console-logger.d.ts

@@ -0,0 +1,27 @@
+import type { ILogger, LogLevel } from './types';
+export declare class ConsoleLogger implements ILogger {
+    private name;
+    private level;
+    constructor(options?: {
+        name?: string;
+        level?: LogLevel;
+    });
+    private shouldLog;
+    private consoleMethod;
+    private formatMsg;
+    trace(msg: string, ...args: unknown[]): void;
+    trace(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    debug(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    info(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    warn(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    error(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    fatal(msg: string, ...args: unknown[]): void;
+    fatal(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    child(bindings: Record<string, unknown>): ILogger;
+    setLevel(level: LogLevel): void;
+    close(): Promise<void>;
+}

package/dist/logger/console-logger.js

@@ -0,0 +1,119 @@
+const LOG_LEVELS = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+    fatal: 5,
+};
+export class ConsoleLogger {
+    name;
+    level = 'info';
+    constructor(options = {}) {
+        this.name = options.name ?? 'app';
+        if (options.level && LOG_LEVELS[options.level] !== undefined) {
+            this.level = options.level;
+        }
+    }
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+    }
+    consoleMethod(level) {
+        if (level === 'fatal')
+            return 'error';
+        if (level === 'trace')
+            return 'debug';
+        return level;
+    }
+    formatMsg(level, msgOrObj, ...rest) {
+        const prefix = `[${this.name}] ${level}:`;
+        const method = this.consoleMethod(level);
+        const flatten = (v) => {
+            if (v instanceof Error)
+                return { message: v.message, stack: v.stack, cause: v.cause };
+            if (v && typeof v === 'object')
+                return v;
+            return v;
+        };
+        if (typeof msgOrObj === 'string') {
+            console[method](prefix, msgOrObj, ...rest.map(flatten));
+        }
+        else {
+            const [msg, ...args] = rest;
+            console[method](prefix, msg ?? '', flatten(msgOrObj), ...args.map(flatten));
+        }
+    }
+    trace(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('trace'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('trace', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('trace', msgOrObj, msg, ...args);
+        }
+    }
+    debug(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('debug'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('debug', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('debug', msgOrObj, msg, ...args);
+        }
+    }
+    info(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('info'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('info', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('info', msgOrObj, msg, ...args);
+        }
+    }
+    warn(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('warn'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('warn', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('warn', msgOrObj, msg, ...args);
+        }
+    }
+    error(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('error'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('error', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('error', msgOrObj, msg, ...args);
+        }
+    }
+    fatal(msgOrObj, msg, ...args) {
+        if (!this.shouldLog('fatal'))
+            return;
+        if (typeof msgOrObj === 'string') {
+            this.formatMsg('fatal', msgOrObj, ...args);
+        }
+        else {
+            this.formatMsg('fatal', msgOrObj, msg, ...args);
+        }
+    }
+    child(bindings) {
+        const module = bindings.module;
+        return new ConsoleLogger({
+            name: module ? `${this.name}:${module}` : this.name,
+            level: this.level,
+        });
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    close() {
+        return Promise.resolve();
+    }
+}

package/dist/logger/logger.d.ts

@@ -0,0 +1,22 @@
+import type { ILogger, LoggerOptions, LogLevel, FileTransportOptions, PinoTransportTarget } from './types';
+export declare class Logger implements ILogger {
+    private impl;
+    constructor(options?: LoggerOptions);
+    trace(msg: string, ...args: unknown[]): void;
+    trace(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    debug(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    info(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    warn(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    error(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    fatal(msg: string, ...args: unknown[]): void;
+    fatal(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    child(bindings: Record<string, unknown>): ILogger;
+    setLevel(level: LogLevel): void;
+    close(): Promise<void>;
+}
+export declare function createFileTransport(options: FileTransportOptions): PinoTransportTarget;
+export declare function createLogger(options?: LoggerOptions): Logger;

package/dist/logger/logger.js

@@ -0,0 +1,148 @@
+import { ConsoleLogger } from './console-logger';
+const isEdgeRuntime = typeof process === 'undefined' || typeof process.stdout === 'undefined';
+export class Logger {
+    impl;
+    constructor(options = {}) {
+        if (isEdgeRuntime) {
+            this.impl = new ConsoleLogger({ name: options.name, level: options.level });
+        }
+        else {
+            this.impl = new LazyPinoLogger(options);
+        }
+    }
+    trace(msgOrObj, msg, ...args) {
+        this.impl.trace(msgOrObj, msg, ...args);
+    }
+    debug(msgOrObj, msg, ...args) {
+        this.impl.debug(msgOrObj, msg, ...args);
+    }
+    info(msgOrObj, msg, ...args) {
+        this.impl.info(msgOrObj, msg, ...args);
+    }
+    warn(msgOrObj, msg, ...args) {
+        this.impl.warn(msgOrObj, msg, ...args);
+    }
+    error(msgOrObj, msg, ...args) {
+        this.impl.error(msgOrObj, msg, ...args);
+    }
+    fatal(msgOrObj, msg, ...args) {
+        this.impl.fatal(msgOrObj, msg, ...args);
+    }
+    child(bindings) {
+        return this.impl.child(bindings);
+    }
+    setLevel(level) {
+        this.impl.setLevel(level);
+    }
+    close() {
+        return this.impl.close();
+    }
+}
+class LazyPinoLogger {
+    impl;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        this.impl = new ConsoleLogger({ name: options.name, level: options.level });
+        this.tryUpgrade();
+    }
+    async tryUpgrade() {
+        try {
+            const name = 'pino';
+            const pino = await import(name);
+            const transportOpts = this.options.transport;
+            const targets = [];
+            if (transportOpts) {
+                const list = Array.isArray(transportOpts) ? transportOpts : [transportOpts];
+                targets.push(...list);
+            }
+            if (this.options.destination) {
+                targets.push({
+                    target: 'pino/file',
+                    options: { destination: this.options.destination },
+                });
+            }
+            let stream;
+            if (targets.length > 0) {
+                stream = pino.transport({ targets });
+            }
+            const instance = pino({
+                name: this.options.name ?? 'app',
+                level: this.options.level ?? 'info',
+                ...this.options.pino,
+            }, stream);
+            this.impl = pinoInstanceToLogger(instance);
+        }
+        catch {
+            // Keep ConsoleLogger as fallback
+        }
+    }
+    trace(msgOrObj, msg, ...args) {
+        this.impl.trace(msgOrObj, msg, ...args);
+    }
+    debug(msgOrObj, msg, ...args) {
+        this.impl.debug(msgOrObj, msg, ...args);
+    }
+    info(msgOrObj, msg, ...args) {
+        this.impl.info(msgOrObj, msg, ...args);
+    }
+    warn(msgOrObj, msg, ...args) {
+        this.impl.warn(msgOrObj, msg, ...args);
+    }
+    error(msgOrObj, msg, ...args) {
+        this.impl.error(msgOrObj, msg, ...args);
+    }
+    fatal(msgOrObj, msg, ...args) {
+        this.impl.fatal(msgOrObj, msg, ...args);
+    }
+    child(bindings) {
+        return this.impl.child(bindings);
+    }
+    setLevel(level) {
+        this.impl.setLevel(level);
+    }
+    close() {
+        return this.impl.close();
+    }
+}
+function pinoInstanceToLogger(instance) {
+    const wrap = (method) => {
+        return (msgOrObj, msg, ...args) => {
+            method.call(instance, msgOrObj, msg, ...args);
+        };
+    };
+    return {
+        trace: wrap(instance.trace),
+        debug: wrap(instance.debug),
+        info: wrap(instance.info),
+        warn: wrap(instance.warn),
+        error: wrap(instance.error),
+        fatal: wrap(instance.fatal),
+        child(bindings) {
+            return pinoInstanceToLogger(instance.child(bindings));
+        },
+        setLevel(level) {
+            instance.level = level;
+        },
+        async close() {
+            await instance.flush();
+        },
+    };
+}
+export function createFileTransport(options) {
+    return {
+        target: 'pino-roll',
+        options: {
+            file: options.file,
+            ...(options.size && { size: options.size }),
+            ...(options.frequency && { frequency: options.frequency }),
+            ...(options.limit && { limit: { count: options.limit } }),
+            ...(options.mkdir !== undefined && { mkdir: options.mkdir }),
+            ...(options.dateFormat && { dateFormat: options.dateFormat }),
+            ...(options.symlink !== undefined && { symlink: options.symlink }),
+        },
+    };
+}
+export function createLogger(options) {
+    return new Logger(options);
+}

package/dist/logger/types.d.ts

@@ -0,0 +1,49 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'trace';
+export interface ILogger {
+    trace(msg: string, ...args: any[]): void;
+    trace(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    debug(msg: string, ...args: any[]): void;
+    debug(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    info(msg: string, ...args: any[]): void;
+    info(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    warn(msg: string, ...args: any[]): void;
+    warn(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    error(msg: string, ...args: any[]): void;
+    error(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    fatal(msg: string, ...args: any[]): void;
+    fatal(obj: Record<string, unknown>, msg?: string, ...args: any[]): void;
+    child(bindings: Record<string, unknown>): ILogger;
+    setLevel(level: LogLevel): void;
+    close(): Promise<void>;
+}
+export interface PinoTransportTarget {
+    target: string;
+    options?: Record<string, unknown>;
+    level?: LogLevel;
+}
+export declare const LOGGER_SYMBOL: unique symbol;
+export declare const NOOP_LOGGER: ILogger;
+export interface LoggerOptions {
+    name?: string;
+    level?: LogLevel;
+    transport?: PinoTransportTarget | PinoTransportTarget[];
+    pino?: Record<string, unknown>;
+    /** File path to write logs. Only works on Node/Bun (uses pino/file transport). */
+    destination?: string;
+}
+export interface FileTransportOptions {
+    /** Base log file path (e.g. 'logs/app'). pino-roll appends rotation numbers. */
+    file: string;
+    /** Max file size before rotation. Accepts '10m', '1g', etc. */
+    size?: string;
+    /** Time-based rotation: 'daily', 'hourly', or ms number. */
+    frequency?: string | number;
+    /** Max rotated files to keep (in addition to active file). */
+    limit?: number;
+    /** Create parent directories if they don't exist. */
+    mkdir?: boolean;
+    /** Date format string for rotated filenames (date-fns format). */
+    dateFormat?: string;
+    /** Maintain a 'current.log' symlink. */
+    symlink?: boolean;
+}

package/dist/logger/types.js

@@ -0,0 +1,16 @@
+export const LOGGER_SYMBOL = Symbol('app:logger');
+export const NOOP_LOGGER = {
+    trace() { },
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+    fatal() { },
+    child() {
+        return NOOP_LOGGER;
+    },
+    setLevel() { },
+    close() {
+        return Promise.resolve();
+    },
+};

package/dist/utils/shared.d.ts

@@ -0,0 +1,12 @@
+import type { Env } from '../config/env';
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare class ConfigTypeError extends ConfigError {
+    constructor(key: string, expected: string, value: string);
+}
+export declare function assertString(key: string, value: string | undefined): string;
+export declare function assertNumber(key: string, value: string | undefined): number;
+export declare function assertBoolean(key: string, value: string | undefined): boolean;
+export declare function assertUrl(key: string, value: string | undefined): URL;
+export declare function resolveBinding(name: string, env?: Env): any;

package/dist/utils/shared.js

@@ -0,0 +1,52 @@
+import { Platform } from '../config/platform';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(`[packages-core] ${message}`);
+        this.name = 'ConfigError';
+    }
+}
+export class ConfigTypeError extends ConfigError {
+    constructor(key, expected, value) {
+        super(`Invalid type for "${key}": expected ${expected}, got "${value}"`);
+        this.name = 'ConfigTypeError';
+    }
+}
+export function assertString(key, value) {
+    if (value === undefined)
+        throw new ConfigError(`Missing required config: ${key}`);
+    return value;
+}
+export function assertNumber(key, value) {
+    if (value === undefined)
+        throw new ConfigError(`Missing required config: ${key}`);
+    const n = Number(value);
+    if (Number.isNaN(n))
+        throw new ConfigTypeError(key, 'number', value);
+    return n;
+}
+export function assertBoolean(key, value) {
+    if (value === undefined)
+        throw new ConfigError(`Missing required config: ${key}`);
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    throw new ConfigTypeError(key, 'boolean', value);
+}
+export function assertUrl(key, value) {
+    if (value === undefined)
+        throw new ConfigError(`Missing required config: ${key}`);
+    try {
+        return new URL(value);
+    }
+    catch {
+        throw new ConfigTypeError(key, 'URL', value);
+    }
+}
+export function resolveBinding(name, env) {
+    return (globalThis[name] ??
+        globalThis.env?.[name] ??
+        (typeof process !== 'undefined' ? process.env?.[name] : undefined) ??
+        Platform.env()?.[name] ??
+        env?.get(name));
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@rx-ted/packages-core",
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "description": "Unified runtime context, environment config, and logging for multi-platform TypeScript.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "types": "./dist/index.d.ts",
+    "default": "./dist/index.js"
+  },
+  "author": "rx-ted",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "demo": "tsx demo/demo.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "environment",
+    "runtime",
+    "als",
+    "bun",
+    "node",
+    "deno",
+    "cloudflare",
+    "vercel-edge",
+    "logging",
+    "typescript",
+    "zod"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/node": "^25.9.1",
+    "pino": "^9.6.0"
+  },
+  "optionalDependencies": {
+    "pino-pretty": "^13.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.7",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "zod": "^4.0.0"
+  }
+}