@parsrun/core 0.1.14 → 0.1.16

package/dist/env.d.ts

@@ -1,7 +1,23 @@
 /**
- * @parsrun/core - Environment Variables
- * Runtime-agnostic environment variable access
- * Works in Node.js, Deno, Bun, and Cloudflare Workers
+ * @module
+ * Runtime-agnostic environment variable access.
+ * Works in Node.js, Deno, Bun, and Cloudflare Workers.
+ *
+ * @example
+ * ```typescript
+ * import { getEnv, requireEnv, getEnvNumber, isDevelopment } from '@parsrun/core';
+ *
+ * // Get optional env var with default
+ * const port = getEnvNumber('PORT', 3000);
+ *
+ * // Get required env var (throws if missing)
+ * const apiKey = requireEnv('API_KEY');
+ *
+ * // Check environment
+ * if (isDevelopment()) {
+ *   console.log('Running in development mode');
+ * }
+ * ```
  */
 /**
  * Set environment variables for edge runtimes (Cloudflare Workers, etc.)

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime.ts","../src/env.ts"],"sourcesContent":["/**\n * @parsrun/core - Runtime Detection\n * Edge-compatible runtime detection for Node.js, Deno, Bun, and Cloudflare Workers\n */\n\nexport type Runtime = \"node\" | \"deno\" | \"bun\" | \"cloudflare\" | \"edge\" | \"browser\" | \"unknown\";\n\n/**\n * Detect the current JavaScript runtime\n */\nexport function detectRuntime(): Runtime {\n  // Bun check (must be before Node since Bun also has process)\n  if (typeof globalThis !== \"undefined\" && \"Bun\" in globalThis) {\n    return \"bun\";\n  }\n\n  // Deno check\n  if (typeof globalThis !== \"undefined\" && \"Deno\" in globalThis) {\n    return \"deno\";\n  }\n\n  // Cloudflare Workers check (has caches but no process)\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).caches !== \"undefined\" &&\n    typeof (globalThis as any).process === \"undefined\"\n  ) {\n    return \"cloudflare\";\n  }\n\n  // Generic Edge runtime check (Vercel Edge, etc.)\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).EdgeRuntime !== \"undefined\"\n  ) {\n    return \"edge\";\n  }\n\n  // Browser check\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).window !== \"undefined\" &&\n    typeof (globalThis as any).document !== \"undefined\"\n  ) {\n    return \"browser\";\n  }\n\n  // Node.js check\n  if (\n    typeof process !== \"undefined\" &&\n    process.versions &&\n    process.versions.node\n  ) {\n    return \"node\";\n  }\n\n  return \"unknown\";\n}\n\n/**\n * Current runtime (cached)\n */\nexport const runtime = detectRuntime();\n\n/**\n * Runtime information helpers\n */\nexport const runtimeInfo = {\n  runtime,\n  isNode: runtime === \"node\",\n  isDeno: runtime === \"deno\",\n  isBun: runtime === \"bun\",\n  isCloudflare: runtime === \"cloudflare\",\n  isEdge: runtime === \"cloudflare\" || runtime === \"edge\" || runtime === \"deno\",\n  isBrowser: runtime === \"browser\",\n  isServer: runtime !== \"browser\",\n  supportsWebCrypto: typeof globalThis.crypto?.subtle !== \"undefined\",\n  supportsStreams: typeof globalThis.ReadableStream !== \"undefined\",\n} as const;\n\n/**\n * Check if running in Node.js\n */\nexport function isNode(): boolean {\n  return runtime === \"node\";\n}\n\n/**\n * Check if running in Deno\n */\nexport function isDeno(): boolean {\n  return runtime === \"deno\";\n}\n\n/**\n * Check if running in Bun\n */\nexport function isBun(): boolean {\n  return runtime === \"bun\";\n}\n\n/**\n * Check if running in Cloudflare Workers\n */\nexport function isCloudflare(): boolean {\n  return runtime === \"cloudflare\";\n}\n\n/**\n * Check if running in any edge environment\n */\nexport function isEdge(): boolean {\n  return runtimeInfo.isEdge;\n}\n\n/**\n * Check if running in browser\n */\nexport function isBrowser(): boolean {\n  return runtime === \"browser\";\n}\n\n/**\n * Check if running on server (not browser)\n */\nexport function isServer(): boolean {\n  return runtimeInfo.isServer;\n}\n\n/**\n * Get runtime version string\n */\nexport function getRuntimeVersion(): string {\n  switch (runtime) {\n    case \"node\":\n      return `Node.js ${process?.versions?.node ?? \"unknown\"}`;\n    case \"bun\":\n      return `Bun ${(globalThis as any).Bun.version}`;\n    case \"deno\":\n      return `Deno ${(globalThis as any).Deno.version.deno}`;\n    case \"cloudflare\":\n      return \"Cloudflare Workers\";\n    case \"edge\":\n      return \"Edge Runtime\";\n    case \"browser\":\n      return typeof navigator !== \"undefined\" ? navigator.userAgent : \"Browser\";\n    default:\n      return \"Unknown\";\n  }\n}\n","/**\n * @parsrun/core - Environment Variables\n * Runtime-agnostic environment variable access\n * Works in Node.js, Deno, Bun, and Cloudflare Workers\n */\n\nimport { runtime } from \"./runtime.js\";\n\n/**\n * Environment variable store for edge runtimes\n * Must be set from the request handler's env parameter\n */\nlet edgeEnvStore: Record<string, string | undefined> = {};\n\n/**\n * Set environment variables for edge runtimes (Cloudflare Workers, etc.)\n * Call this from your worker's fetch handler with the env parameter\n *\n * @example\n * ```typescript\n * export default {\n *   async fetch(request, env) {\n *     setEdgeEnv(env);\n *     // ... rest of handler\n *   }\n * }\n * ```\n */\nexport function setEdgeEnv(env: Record<string, string | undefined>): void {\n  edgeEnvStore = { ...edgeEnvStore, ...env };\n}\n\n/**\n * Clear edge environment store\n */\nexport function clearEdgeEnv(): void {\n  edgeEnvStore = {};\n}\n\n/**\n * Get an environment variable value\n * Works across all runtimes\n */\nexport function getEnv(key: string, defaultValue?: string): string | undefined {\n  // Edge runtimes (Cloudflare Workers, etc.)\n  if (runtime === \"cloudflare\" || runtime === \"edge\") {\n    return edgeEnvStore[key] ?? defaultValue;\n  }\n\n  // Deno\n  if (runtime === \"deno\") {\n    try {\n      return (globalThis as any).Deno.env.get(key) ?? defaultValue;\n    } catch {\n      return defaultValue;\n    }\n  }\n\n  // Node.js / Bun (both use process.env)\n  if (typeof process !== \"undefined\" && process.env) {\n    return process.env[key] ?? defaultValue;\n  }\n\n  // Browser - check for injected env\n  if (runtime === \"browser\" && typeof (globalThis as any).__ENV__ !== \"undefined\") {\n    return (globalThis as any).__ENV__[key] ?? defaultValue;\n  }\n\n  return defaultValue;\n}\n\n/**\n * Get an environment variable, throwing if not found\n */\nexport function requireEnv(key: string): string {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    throw new Error(`Required environment variable \"${key}\" is not set`);\n  }\n  return value;\n}\n\n/**\n * Get an environment variable as a number\n */\nexport function getEnvNumber(key: string, defaultValue?: number): number | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  const parsed = parseInt(value, 10);\n  return isNaN(parsed) ? defaultValue : parsed;\n}\n\n/**\n * Get an environment variable as a float\n */\nexport function getEnvFloat(key: string, defaultValue?: number): number | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  const parsed = parseFloat(value);\n  return isNaN(parsed) ? defaultValue : parsed;\n}\n\n/**\n * Get an environment variable as a boolean\n */\nexport function getEnvBoolean(key: string, defaultValue: boolean = false): boolean {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  return value === \"true\" || value === \"1\" || value === \"yes\";\n}\n\n/**\n * Get an environment variable as an array (comma-separated)\n */\nexport function getEnvArray(key: string, defaultValue: string[] = []): string[] {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  return value.split(\",\").map((s) => s.trim()).filter(Boolean);\n}\n\n/**\n * Get an environment variable as JSON\n */\nexport function getEnvJson<T>(key: string, defaultValue?: T): T | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  try {\n    return JSON.parse(value) as T;\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Check if running in development mode\n */\nexport function isDevelopment(): boolean {\n  const env = getEnv(\"NODE_ENV\");\n  return env === \"development\" || env === undefined;\n}\n\n/**\n * Check if running in production mode\n */\nexport function isProduction(): boolean {\n  return getEnv(\"NODE_ENV\") === \"production\";\n}\n\n/**\n * Check if running in test mode\n */\nexport function isTest(): boolean {\n  return getEnv(\"NODE_ENV\") === \"test\";\n}\n\n/**\n * Environment mode\n */\nexport type EnvMode = \"development\" | \"production\" | \"test\";\n\n/**\n * Get current environment mode\n */\nexport function getEnvMode(): EnvMode {\n  const env = getEnv(\"NODE_ENV\");\n  if (env === \"production\") return \"production\";\n  if (env === \"test\") return \"test\";\n  return \"development\";\n}\n\n/**\n * Create a typed environment configuration object\n *\n * @example\n * ```typescript\n * const env = createEnvConfig({\n *   DATABASE_URL: { required: true },\n *   PORT: { type: 'number', default: 3000 },\n *   DEBUG: { type: 'boolean', default: false },\n * });\n *\n * env.DATABASE_URL // string\n * env.PORT // number\n * env.DEBUG // boolean\n * ```\n */\nexport function createEnvConfig<T extends EnvSchema>(schema: T): EnvResult<T> {\n  const result: Record<string, unknown> = {};\n\n  for (const [key, config] of Object.entries(schema)) {\n    const envConfig = config as EnvConfigItem;\n    let value: unknown;\n\n    switch (envConfig.type) {\n      case \"number\":\n        value = getEnvNumber(key, envConfig.default as number | undefined);\n        break;\n      case \"boolean\":\n        value = getEnvBoolean(key, envConfig.default as boolean | undefined);\n        break;\n      case \"array\":\n        value = getEnvArray(key, envConfig.default as string[] | undefined);\n        break;\n      case \"json\":\n        value = getEnvJson(key, envConfig.default);\n        break;\n      default:\n        value = getEnv(key, envConfig.default as string | undefined);\n    }\n\n    if (envConfig.required && (value === undefined || value === \"\")) {\n      throw new Error(`Required environment variable \"${key}\" is not set`);\n    }\n\n    result[key] = value;\n  }\n\n  return result as EnvResult<T>;\n}\n\n// Type helpers for createEnvConfig\ntype EnvConfigItem = {\n  type?: \"string\" | \"number\" | \"boolean\" | \"array\" | \"json\";\n  required?: boolean;\n  default?: unknown;\n};\n\ntype EnvSchema = Record<string, EnvConfigItem>;\n\ntype EnvResult<T extends EnvSchema> = {\n  [K in keyof T]: T[K][\"type\"] extends \"number\"\n    ? number\n    : T[K][\"type\"] extends \"boolean\"\n      ? boolean\n      : T[K][\"type\"] extends \"array\"\n        ? string[]\n        : T[K][\"type\"] extends \"json\"\n          ? unknown\n          : string;\n};\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/runtime.ts","../src/env.ts"],"sourcesContent":["/**\n * @module\n * Runtime detection for Node.js, Deno, Bun, and Cloudflare Workers.\n * Detects the current JavaScript runtime and provides helper functions.\n *\n * @example\n * ```typescript\n * import { runtime, isNode, isDeno, isBun, isCloudflare, getRuntimeVersion } from '@parsrun/core';\n *\n * console.log(`Running on ${runtime}`); // \"node\", \"deno\", \"bun\", \"cloudflare\", etc.\n *\n * if (isNode()) {\n *   // Node.js specific code\n * } else if (isCloudflare()) {\n *   // Cloudflare Workers specific code\n * }\n *\n * console.log(getRuntimeVersion()); // \"Node.js 20.0.0\"\n * ```\n */\n\nexport type Runtime = \"node\" | \"deno\" | \"bun\" | \"cloudflare\" | \"edge\" | \"browser\" | \"unknown\";\n\n/**\n * Detect the current JavaScript runtime\n */\nexport function detectRuntime(): Runtime {\n  // Bun check (must be before Node since Bun also has process)\n  if (typeof globalThis !== \"undefined\" && \"Bun\" in globalThis) {\n    return \"bun\";\n  }\n\n  // Deno check\n  if (typeof globalThis !== \"undefined\" && \"Deno\" in globalThis) {\n    return \"deno\";\n  }\n\n  // Cloudflare Workers check (has caches but no process)\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).caches !== \"undefined\" &&\n    typeof (globalThis as any).process === \"undefined\"\n  ) {\n    return \"cloudflare\";\n  }\n\n  // Generic Edge runtime check (Vercel Edge, etc.)\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).EdgeRuntime !== \"undefined\"\n  ) {\n    return \"edge\";\n  }\n\n  // Browser check\n  if (\n    typeof globalThis !== \"undefined\" &&\n    typeof (globalThis as any).window !== \"undefined\" &&\n    typeof (globalThis as any).document !== \"undefined\"\n  ) {\n    return \"browser\";\n  }\n\n  // Node.js check\n  if (\n    typeof process !== \"undefined\" &&\n    process.versions &&\n    process.versions.node\n  ) {\n    return \"node\";\n  }\n\n  return \"unknown\";\n}\n\n/**\n * Current runtime (cached)\n */\nexport const runtime = detectRuntime();\n\n/**\n * Runtime information helpers\n */\nexport const runtimeInfo = {\n  runtime,\n  isNode: runtime === \"node\",\n  isDeno: runtime === \"deno\",\n  isBun: runtime === \"bun\",\n  isCloudflare: runtime === \"cloudflare\",\n  isEdge: runtime === \"cloudflare\" || runtime === \"edge\" || runtime === \"deno\",\n  isBrowser: runtime === \"browser\",\n  isServer: runtime !== \"browser\",\n  supportsWebCrypto: typeof globalThis.crypto?.subtle !== \"undefined\",\n  supportsStreams: typeof globalThis.ReadableStream !== \"undefined\",\n} as const;\n\n/**\n * Check if running in Node.js\n */\nexport function isNode(): boolean {\n  return runtime === \"node\";\n}\n\n/**\n * Check if running in Deno\n */\nexport function isDeno(): boolean {\n  return runtime === \"deno\";\n}\n\n/**\n * Check if running in Bun\n */\nexport function isBun(): boolean {\n  return runtime === \"bun\";\n}\n\n/**\n * Check if running in Cloudflare Workers\n */\nexport function isCloudflare(): boolean {\n  return runtime === \"cloudflare\";\n}\n\n/**\n * Check if running in any edge environment\n */\nexport function isEdge(): boolean {\n  return runtimeInfo.isEdge;\n}\n\n/**\n * Check if running in browser\n */\nexport function isBrowser(): boolean {\n  return runtime === \"browser\";\n}\n\n/**\n * Check if running on server (not browser)\n */\nexport function isServer(): boolean {\n  return runtimeInfo.isServer;\n}\n\n/**\n * Get runtime version string\n */\nexport function getRuntimeVersion(): string {\n  switch (runtime) {\n    case \"node\":\n      return `Node.js ${process?.versions?.node ?? \"unknown\"}`;\n    case \"bun\":\n      return `Bun ${(globalThis as any).Bun.version}`;\n    case \"deno\":\n      return `Deno ${(globalThis as any).Deno.version.deno}`;\n    case \"cloudflare\":\n      return \"Cloudflare Workers\";\n    case \"edge\":\n      return \"Edge Runtime\";\n    case \"browser\":\n      return typeof navigator !== \"undefined\" ? navigator.userAgent : \"Browser\";\n    default:\n      return \"Unknown\";\n  }\n}\n","/**\n * @module\n * Runtime-agnostic environment variable access.\n * Works in Node.js, Deno, Bun, and Cloudflare Workers.\n *\n * @example\n * ```typescript\n * import { getEnv, requireEnv, getEnvNumber, isDevelopment } from '@parsrun/core';\n *\n * // Get optional env var with default\n * const port = getEnvNumber('PORT', 3000);\n *\n * // Get required env var (throws if missing)\n * const apiKey = requireEnv('API_KEY');\n *\n * // Check environment\n * if (isDevelopment()) {\n *   console.log('Running in development mode');\n * }\n * ```\n */\n\nimport { runtime } from \"./runtime.js\";\n\n/**\n * Environment variable store for edge runtimes\n * Must be set from the request handler's env parameter\n */\nlet edgeEnvStore: Record<string, string | undefined> = {};\n\n/**\n * Set environment variables for edge runtimes (Cloudflare Workers, etc.)\n * Call this from your worker's fetch handler with the env parameter\n *\n * @example\n * ```typescript\n * export default {\n *   async fetch(request, env) {\n *     setEdgeEnv(env);\n *     // ... rest of handler\n *   }\n * }\n * ```\n */\nexport function setEdgeEnv(env: Record<string, string | undefined>): void {\n  edgeEnvStore = { ...edgeEnvStore, ...env };\n}\n\n/**\n * Clear edge environment store\n */\nexport function clearEdgeEnv(): void {\n  edgeEnvStore = {};\n}\n\n/**\n * Get an environment variable value\n * Works across all runtimes\n */\nexport function getEnv(key: string, defaultValue?: string): string | undefined {\n  // Edge runtimes (Cloudflare Workers, etc.)\n  if (runtime === \"cloudflare\" || runtime === \"edge\") {\n    return edgeEnvStore[key] ?? defaultValue;\n  }\n\n  // Deno\n  if (runtime === \"deno\") {\n    try {\n      return (globalThis as any).Deno.env.get(key) ?? defaultValue;\n    } catch {\n      return defaultValue;\n    }\n  }\n\n  // Node.js / Bun (both use process.env)\n  if (typeof process !== \"undefined\" && process.env) {\n    return process.env[key] ?? defaultValue;\n  }\n\n  // Browser - check for injected env\n  if (runtime === \"browser\" && typeof (globalThis as any).__ENV__ !== \"undefined\") {\n    return (globalThis as any).__ENV__[key] ?? defaultValue;\n  }\n\n  return defaultValue;\n}\n\n/**\n * Get an environment variable, throwing if not found\n */\nexport function requireEnv(key: string): string {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    throw new Error(`Required environment variable \"${key}\" is not set`);\n  }\n  return value;\n}\n\n/**\n * Get an environment variable as a number\n */\nexport function getEnvNumber(key: string, defaultValue?: number): number | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  const parsed = parseInt(value, 10);\n  return isNaN(parsed) ? defaultValue : parsed;\n}\n\n/**\n * Get an environment variable as a float\n */\nexport function getEnvFloat(key: string, defaultValue?: number): number | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  const parsed = parseFloat(value);\n  return isNaN(parsed) ? defaultValue : parsed;\n}\n\n/**\n * Get an environment variable as a boolean\n */\nexport function getEnvBoolean(key: string, defaultValue: boolean = false): boolean {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  return value === \"true\" || value === \"1\" || value === \"yes\";\n}\n\n/**\n * Get an environment variable as an array (comma-separated)\n */\nexport function getEnvArray(key: string, defaultValue: string[] = []): string[] {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  return value.split(\",\").map((s) => s.trim()).filter(Boolean);\n}\n\n/**\n * Get an environment variable as JSON\n */\nexport function getEnvJson<T>(key: string, defaultValue?: T): T | undefined {\n  const value = getEnv(key);\n  if (value === undefined || value === \"\") {\n    return defaultValue;\n  }\n  try {\n    return JSON.parse(value) as T;\n  } catch {\n    return defaultValue;\n  }\n}\n\n/**\n * Check if running in development mode\n */\nexport function isDevelopment(): boolean {\n  const env = getEnv(\"NODE_ENV\");\n  return env === \"development\" || env === undefined;\n}\n\n/**\n * Check if running in production mode\n */\nexport function isProduction(): boolean {\n  return getEnv(\"NODE_ENV\") === \"production\";\n}\n\n/**\n * Check if running in test mode\n */\nexport function isTest(): boolean {\n  return getEnv(\"NODE_ENV\") === \"test\";\n}\n\n/**\n * Environment mode\n */\nexport type EnvMode = \"development\" | \"production\" | \"test\";\n\n/**\n * Get current environment mode\n */\nexport function getEnvMode(): EnvMode {\n  const env = getEnv(\"NODE_ENV\");\n  if (env === \"production\") return \"production\";\n  if (env === \"test\") return \"test\";\n  return \"development\";\n}\n\n/**\n * Create a typed environment configuration object\n *\n * @example\n * ```typescript\n * const env = createEnvConfig({\n *   DATABASE_URL: { required: true },\n *   PORT: { type: 'number', default: 3000 },\n *   DEBUG: { type: 'boolean', default: false },\n * });\n *\n * env.DATABASE_URL // string\n * env.PORT // number\n * env.DEBUG // boolean\n * ```\n */\nexport function createEnvConfig<T extends EnvSchema>(schema: T): EnvResult<T> {\n  const result: Record<string, unknown> = {};\n\n  for (const [key, config] of Object.entries(schema)) {\n    const envConfig = config as EnvConfigItem;\n    let value: unknown;\n\n    switch (envConfig.type) {\n      case \"number\":\n        value = getEnvNumber(key, envConfig.default as number | undefined);\n        break;\n      case \"boolean\":\n        value = getEnvBoolean(key, envConfig.default as boolean | undefined);\n        break;\n      case \"array\":\n        value = getEnvArray(key, envConfig.default as string[] | undefined);\n        break;\n      case \"json\":\n        value = getEnvJson(key, envConfig.default);\n        break;\n      default:\n        value = getEnv(key, envConfig.default as string | undefined);\n    }\n\n    if (envConfig.required && (value === undefined || value === \"\")) {\n      throw new Error(`Required environment variable \"${key}\" is not set`);\n    }\n\n    result[key] = value;\n  }\n\n  return result as EnvResult<T>;\n}\n\n// Type helpers for createEnvConfig\ntype EnvConfigItem = {\n  type?: \"string\" | \"number\" | \"boolean\" | \"array\" | \"json\";\n  required?: boolean;\n  default?: unknown;\n};\n\ntype EnvSchema = Record<string, EnvConfigItem>;\n\ntype EnvResult<T extends EnvSchema> = {\n  [K in keyof T]: T[K][\"type\"] extends \"number\"\n    ? number\n    : T[K][\"type\"] extends \"boolean\"\n      ? boolean\n      : T[K][\"type\"] extends \"array\"\n        ? string[]\n        : T[K][\"type\"] extends \"json\"\n          ? unknown\n          : string;\n};\n"],"mappings":"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","names":[]}

package/dist/errors.d.ts

@@ -1,5 +1,26 @@
 /**
- * @parsrun/core - Error Classes
+ * @module
+ * Error classes for the Pars framework.
+ * Provides typed errors for auth, validation, rate limiting, and more.
+ *
+ * @example
+ * ```typescript
+ * import { NotFoundError, ValidationError, UnauthorizedError } from '@parsrun/core';
+ *
+ * // Throw typed errors
+ * throw new NotFoundError('User');
+ * throw new ValidationError('Invalid input', [{ field: 'email', message: 'Invalid format' }]);
+ * throw new UnauthorizedError('Token expired');
+ * ```
+ */
+/**
+ * Base error class for all Pars framework errors.
+ * Includes error code, HTTP status code, and optional details.
+ *
+ * @example
+ * ```typescript
+ * throw new ParsError('Something went wrong', 'CUSTOM_ERROR', 500, { extra: 'info' });
+ * ```
  */
 declare class ParsError extends Error {
     readonly code: string;
@@ -14,12 +35,15 @@ declare class ParsError extends Error {
         details: Record<string, unknown> | undefined;
     };
 }
+/** Base class for authentication-related errors (HTTP 401/403) */
 declare class AuthError extends ParsError {
     constructor(message: string, code?: string, statusCode?: number, details?: Record<string, unknown>);
 }
+/** User is not authenticated (HTTP 401) */
 declare class UnauthorizedError extends AuthError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
+/** User lacks permission for the requested action (HTTP 403) */
 declare class ForbiddenError extends AuthError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
@@ -55,22 +79,30 @@ declare class MembershipNotFoundError extends MembershipError {
 declare class MembershipExpiredError extends MembershipError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
+/** Request validation failed with one or more field errors (HTTP 400) */
 declare class ValidationError extends ParsError {
     readonly errors: ValidationErrorDetail[];
     constructor(message: string | undefined, errors: ValidationErrorDetail[], details?: Record<string, unknown>);
 }
+/** Details about a single validation error */
 interface ValidationErrorDetail {
+    /** Field path that failed validation */
     field: string;
+    /** Human-readable error message */
     message: string;
+    /** Optional error code for programmatic handling */
     code?: string;
 }
+/** Too many requests - rate limit exceeded (HTTP 429) */
 declare class RateLimitError extends ParsError {
     readonly retryAfter?: number | undefined;
     constructor(message?: string, retryAfter?: number | undefined, details?: Record<string, unknown>);
 }
+/** Requested resource was not found (HTTP 404) */
 declare class NotFoundError extends ParsError {
     constructor(resource?: string, message?: string, details?: Record<string, unknown>);
 }
+/** Resource conflict, such as duplicate entry (HTTP 409) */
 declare class ConflictError extends ParsError {
     constructor(message?: string, details?: Record<string, unknown>);
 }

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * @parsrun/core - Error Classes\n */\n\nexport class ParsError extends Error {\n  public readonly code: string;\n  public readonly statusCode: number;\n  public readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    message: string,\n    code: string,\n    statusCode: number = 500,\n    details?: Record<string, unknown>\n  ) {\n    super(message);\n    this.name = \"ParsError\";\n    this.code = code;\n    this.statusCode = statusCode;\n    this.details = details ?? undefined;\n    Error.captureStackTrace?.(this, this.constructor);\n  }\n\n  toJSON() {\n    return {\n      name: this.name,\n      message: this.message,\n      code: this.code,\n      statusCode: this.statusCode,\n      details: this.details,\n    };\n  }\n}\n\n// ============================================\n// AUTH ERRORS\n// ============================================\n\nexport class AuthError extends ParsError {\n  constructor(\n    message: string,\n    code: string = \"AUTH_ERROR\",\n    statusCode: number = 401,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"AuthError\";\n  }\n}\n\nexport class UnauthorizedError extends AuthError {\n  constructor(message: string = \"Unauthorized\", details?: Record<string, unknown>) {\n    super(message, \"UNAUTHORIZED\", 401, details);\n    this.name = \"UnauthorizedError\";\n  }\n}\n\nexport class ForbiddenError extends AuthError {\n  constructor(message: string = \"Forbidden\", details?: Record<string, unknown>) {\n    super(message, \"FORBIDDEN\", 403, details);\n    this.name = \"ForbiddenError\";\n  }\n}\n\nexport class InvalidCredentialsError extends AuthError {\n  constructor(message: string = \"Invalid credentials\", details?: Record<string, unknown>) {\n    super(message, \"INVALID_CREDENTIALS\", 401, details);\n    this.name = \"InvalidCredentialsError\";\n  }\n}\n\nexport class SessionExpiredError extends AuthError {\n  constructor(message: string = \"Session expired\", details?: Record<string, unknown>) {\n    super(message, \"SESSION_EXPIRED\", 401, details);\n    this.name = \"SessionExpiredError\";\n  }\n}\n\nexport class TwoFactorRequiredError extends AuthError {\n  constructor(\n    message: string = \"Two-factor authentication required\",\n    public readonly challengeId: string,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"TWO_FACTOR_REQUIRED\", 403, { ...details, challengeId });\n    this.name = \"TwoFactorRequiredError\";\n  }\n}\n\nexport class AccountLockedError extends AuthError {\n  constructor(\n    message: string = \"Account locked\",\n    public readonly lockedUntil?: Date,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"ACCOUNT_LOCKED\", 423, { ...details, lockedUntil });\n    this.name = \"AccountLockedError\";\n  }\n}\n\n// ============================================\n// TENANT ERRORS\n// ============================================\n\nexport class TenantError extends ParsError {\n  constructor(\n    message: string,\n    code: string = \"TENANT_ERROR\",\n    statusCode: number = 400,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"TenantError\";\n  }\n}\n\nexport class TenantNotFoundError extends TenantError {\n  constructor(message: string = \"Tenant not found\", details?: Record<string, unknown>) {\n    super(message, \"TENANT_NOT_FOUND\", 404, details);\n    this.name = \"TenantNotFoundError\";\n  }\n}\n\nexport class TenantSuspendedError extends TenantError {\n  constructor(message: string = \"Tenant suspended\", details?: Record<string, unknown>) {\n    super(message, \"TENANT_SUSPENDED\", 403, details);\n    this.name = \"TenantSuspendedError\";\n  }\n}\n\nexport class MembershipError extends TenantError {\n  constructor(\n    message: string = \"Membership error\",\n    code: string = \"MEMBERSHIP_ERROR\",\n    statusCode: number = 400,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"MembershipError\";\n  }\n}\n\nexport class MembershipNotFoundError extends MembershipError {\n  constructor(message: string = \"Membership not found\", details?: Record<string, unknown>) {\n    super(message, \"MEMBERSHIP_NOT_FOUND\", 404, details);\n    this.name = \"MembershipNotFoundError\";\n  }\n}\n\nexport class MembershipExpiredError extends MembershipError {\n  constructor(message: string = \"Membership expired\", details?: Record<string, unknown>) {\n    super(message, \"MEMBERSHIP_EXPIRED\", 403, details);\n    this.name = \"MembershipExpiredError\";\n  }\n}\n\n// ============================================\n// VALIDATION ERRORS\n// ============================================\n\nexport class ValidationError extends ParsError {\n  constructor(\n    message: string = \"Validation failed\",\n    public readonly errors: ValidationErrorDetail[],\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"VALIDATION_ERROR\", 400, { ...details, errors });\n    this.name = \"ValidationError\";\n  }\n}\n\nexport interface ValidationErrorDetail {\n  field: string;\n  message: string;\n  code?: string;\n}\n\n// ============================================\n// RATE LIMIT ERRORS\n// ============================================\n\nexport class RateLimitError extends ParsError {\n  constructor(\n    message: string = \"Rate limit exceeded\",\n    public readonly retryAfter?: number,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"RATE_LIMIT_EXCEEDED\", 429, { ...details, retryAfter });\n    this.name = \"RateLimitError\";\n  }\n}\n\n// ============================================\n// NOT FOUND ERRORS\n// ============================================\n\nexport class NotFoundError extends ParsError {\n  constructor(\n    resource: string = \"Resource\",\n    message?: string,\n    details?: Record<string, unknown>\n  ) {\n    super(message ?? `${resource} not found`, \"NOT_FOUND\", 404, { ...details, resource });\n    this.name = \"NotFoundError\";\n  }\n}\n\n// ============================================\n// CONFLICT ERRORS\n// ============================================\n\nexport class ConflictError extends ParsError {\n  constructor(message: string = \"Conflict\", details?: Record<string, unknown>) {\n    super(message, \"CONFLICT\", 409, details);\n    this.name = \"ConflictError\";\n  }\n}\n\nexport class DuplicateError extends ConflictError {\n  constructor(\n    resource: string = \"Resource\",\n    field?: string,\n    details?: Record<string, unknown>\n  ) {\n    super(`${resource} already exists${field ? ` with this ${field}` : \"\"}`, {\n      ...details,\n      resource,\n      field,\n    });\n    this.name = \"DuplicateError\";\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/**\n * @module\n * Error classes for the Pars framework.\n * Provides typed errors for auth, validation, rate limiting, and more.\n *\n * @example\n * ```typescript\n * import { NotFoundError, ValidationError, UnauthorizedError } from '@parsrun/core';\n *\n * // Throw typed errors\n * throw new NotFoundError('User');\n * throw new ValidationError('Invalid input', [{ field: 'email', message: 'Invalid format' }]);\n * throw new UnauthorizedError('Token expired');\n * ```\n */\n\n/**\n * Base error class for all Pars framework errors.\n * Includes error code, HTTP status code, and optional details.\n *\n * @example\n * ```typescript\n * throw new ParsError('Something went wrong', 'CUSTOM_ERROR', 500, { extra: 'info' });\n * ```\n */\nexport class ParsError extends Error {\n  public readonly code: string;\n  public readonly statusCode: number;\n  public readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    message: string,\n    code: string,\n    statusCode: number = 500,\n    details?: Record<string, unknown>\n  ) {\n    super(message);\n    this.name = \"ParsError\";\n    this.code = code;\n    this.statusCode = statusCode;\n    this.details = details ?? undefined;\n    Error.captureStackTrace?.(this, this.constructor);\n  }\n\n  toJSON() {\n    return {\n      name: this.name,\n      message: this.message,\n      code: this.code,\n      statusCode: this.statusCode,\n      details: this.details,\n    };\n  }\n}\n\n// ============================================\n// AUTH ERRORS\n// ============================================\n\n/** Base class for authentication-related errors (HTTP 401/403) */\nexport class AuthError extends ParsError {\n  constructor(\n    message: string,\n    code: string = \"AUTH_ERROR\",\n    statusCode: number = 401,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"AuthError\";\n  }\n}\n\n/** User is not authenticated (HTTP 401) */\nexport class UnauthorizedError extends AuthError {\n  constructor(message: string = \"Unauthorized\", details?: Record<string, unknown>) {\n    super(message, \"UNAUTHORIZED\", 401, details);\n    this.name = \"UnauthorizedError\";\n  }\n}\n\n/** User lacks permission for the requested action (HTTP 403) */\nexport class ForbiddenError extends AuthError {\n  constructor(message: string = \"Forbidden\", details?: Record<string, unknown>) {\n    super(message, \"FORBIDDEN\", 403, details);\n    this.name = \"ForbiddenError\";\n  }\n}\n\nexport class InvalidCredentialsError extends AuthError {\n  constructor(message: string = \"Invalid credentials\", details?: Record<string, unknown>) {\n    super(message, \"INVALID_CREDENTIALS\", 401, details);\n    this.name = \"InvalidCredentialsError\";\n  }\n}\n\nexport class SessionExpiredError extends AuthError {\n  constructor(message: string = \"Session expired\", details?: Record<string, unknown>) {\n    super(message, \"SESSION_EXPIRED\", 401, details);\n    this.name = \"SessionExpiredError\";\n  }\n}\n\nexport class TwoFactorRequiredError extends AuthError {\n  constructor(\n    message: string = \"Two-factor authentication required\",\n    public readonly challengeId: string,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"TWO_FACTOR_REQUIRED\", 403, { ...details, challengeId });\n    this.name = \"TwoFactorRequiredError\";\n  }\n}\n\nexport class AccountLockedError extends AuthError {\n  constructor(\n    message: string = \"Account locked\",\n    public readonly lockedUntil?: Date,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"ACCOUNT_LOCKED\", 423, { ...details, lockedUntil });\n    this.name = \"AccountLockedError\";\n  }\n}\n\n// ============================================\n// TENANT ERRORS\n// ============================================\n\nexport class TenantError extends ParsError {\n  constructor(\n    message: string,\n    code: string = \"TENANT_ERROR\",\n    statusCode: number = 400,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"TenantError\";\n  }\n}\n\nexport class TenantNotFoundError extends TenantError {\n  constructor(message: string = \"Tenant not found\", details?: Record<string, unknown>) {\n    super(message, \"TENANT_NOT_FOUND\", 404, details);\n    this.name = \"TenantNotFoundError\";\n  }\n}\n\nexport class TenantSuspendedError extends TenantError {\n  constructor(message: string = \"Tenant suspended\", details?: Record<string, unknown>) {\n    super(message, \"TENANT_SUSPENDED\", 403, details);\n    this.name = \"TenantSuspendedError\";\n  }\n}\n\nexport class MembershipError extends TenantError {\n  constructor(\n    message: string = \"Membership error\",\n    code: string = \"MEMBERSHIP_ERROR\",\n    statusCode: number = 400,\n    details?: Record<string, unknown>\n  ) {\n    super(message, code, statusCode, details);\n    this.name = \"MembershipError\";\n  }\n}\n\nexport class MembershipNotFoundError extends MembershipError {\n  constructor(message: string = \"Membership not found\", details?: Record<string, unknown>) {\n    super(message, \"MEMBERSHIP_NOT_FOUND\", 404, details);\n    this.name = \"MembershipNotFoundError\";\n  }\n}\n\nexport class MembershipExpiredError extends MembershipError {\n  constructor(message: string = \"Membership expired\", details?: Record<string, unknown>) {\n    super(message, \"MEMBERSHIP_EXPIRED\", 403, details);\n    this.name = \"MembershipExpiredError\";\n  }\n}\n\n// ============================================\n// VALIDATION ERRORS\n// ============================================\n\n/** Request validation failed with one or more field errors (HTTP 400) */\nexport class ValidationError extends ParsError {\n  constructor(\n    message: string = \"Validation failed\",\n    public readonly errors: ValidationErrorDetail[],\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"VALIDATION_ERROR\", 400, { ...details, errors });\n    this.name = \"ValidationError\";\n  }\n}\n\n/** Details about a single validation error */\nexport interface ValidationErrorDetail {\n  /** Field path that failed validation */\n  field: string;\n  /** Human-readable error message */\n  message: string;\n  /** Optional error code for programmatic handling */\n  code?: string;\n}\n\n// ============================================\n// RATE LIMIT ERRORS\n// ============================================\n\n/** Too many requests - rate limit exceeded (HTTP 429) */\nexport class RateLimitError extends ParsError {\n  constructor(\n    message: string = \"Rate limit exceeded\",\n    public readonly retryAfter?: number,\n    details?: Record<string, unknown>\n  ) {\n    super(message, \"RATE_LIMIT_EXCEEDED\", 429, { ...details, retryAfter });\n    this.name = \"RateLimitError\";\n  }\n}\n\n// ============================================\n// NOT FOUND ERRORS\n// ============================================\n\n/** Requested resource was not found (HTTP 404) */\nexport class NotFoundError extends ParsError {\n  constructor(\n    resource: string = \"Resource\",\n    message?: string,\n    details?: Record<string, unknown>\n  ) {\n    super(message ?? `${resource} not found`, \"NOT_FOUND\", 404, { ...details, resource });\n    this.name = \"NotFoundError\";\n  }\n}\n\n// ============================================\n// CONFLICT ERRORS\n// ============================================\n\n/** Resource conflict, such as duplicate entry (HTTP 409) */\nexport class ConflictError extends ParsError {\n  constructor(message: string = \"Conflict\", details?: Record<string, unknown>) {\n    super(message, \"CONFLICT\", 409, details);\n    this.name = \"ConflictError\";\n  }\n}\n\nexport class DuplicateError extends ConflictError {\n  constructor(\n    resource: string = \"Resource\",\n    field?: string,\n    details?: Record<string, unknown>\n  ) {\n    super(`${resource} already exists${field ? ` with this ${field}` : \"\"}`, {\n      ...details,\n      resource,\n      field,\n    });\n    this.name = \"DuplicateError\";\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Runtime, detectRuntime, getRuntimeVersion, isBrowser, isBun, isCloudflare, isDeno, isEdge, isNode, isServer, runtime, runtimeInfo } from './runtime.js';
 export { EnvMode, clearEdgeEnv, createEnvConfig, getEnv, getEnvArray, getEnvBoolean, getEnvFloat, getEnvJson, getEnvMode, getEnvNumber, isDevelopment, isProduction, isTest, requireEnv, setEdgeEnv } from './env.js';
-export { o as BaseTransportOptions, p as BatchTransportOptions, B as Breadcrumb, j as CombinedTransport, C as ConsoleTransport, k as ErrorContext, E as ErrorTransport, n as ErrorUser, g as LogEntry, a as LogLevel, e as LogLevelName, f as LogLevelValue, h as LogTransport, L as Logger, i as LoggerConfig, c as createLogger, d as createRequestLogger, b as logError, l as logger, m as measureTime } from './logger-aEibH9Mv.js';
+export { o as BaseTransportOptions, p as BatchTransportOptions, B as Breadcrumb, j as CombinedTransport, C as ConsoleTransport, k as ErrorContext, E as ErrorTransport, n as ErrorUser, g as LogEntry, a as LogLevel, e as LogLevelName, f as LogLevelValue, h as LogTransport, L as Logger, i as LoggerConfig, c as createLogger, d as createRequestLogger, b as logError, l as logger, m as measureTime } from './logger-3oVznpFY.js';
 export { Decimal, DecimalUtils, decimal } from './decimal.js';
 export { AccessLevel, AuthContext, DeepPartial, IpRestrictions, MembershipPermissions, MembershipStatus, PaginatedResult, PaginationParams, Prettify, RequireAtLeastOne, ResourceRestrictions, Result, Session, Tenant, TenantMembership, TenantStatus, TimeRestrictions, User, err, ok } from './types.js';
 export { AccountLockedError, AuthError, ConflictError, DuplicateError, ForbiddenError, InvalidCredentialsError, MembershipError, MembershipExpiredError, MembershipNotFoundError, NotFoundError, ParsError, RateLimitError, SessionExpiredError, TenantError, TenantNotFoundError, TenantSuspendedError, TwoFactorRequiredError, UnauthorizedError, ValidationError, ValidationErrorDetail } from './errors.js';
@@ -8,21 +8,69 @@ export { ErrorCategory, ErrorCode, ErrorCodeDefinition, ErrorCodes, getErrorCode
 export { AxiomTransport, AxiomTransportOptions, LogtapeLogger, LogtapeTransport, LogtapeTransportOptions, SentryClient, SentryEvent, SentryTransport, SentryTransportOptions, createAxiomTransport, createLogtapeTransport, createSentryTransport } from './transports/index.js';
 
 /**
- * @parsrun/core
- * Core utilities and types for Pars framework
- * Edge-compatible, zero dependencies
+ * @module
+ * Core utilities and types for the Pars framework.
+ * Edge-compatible with zero dependencies - works in Node.js, Deno, Bun, and Cloudflare Workers.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   // Runtime detection
+ *   runtime, isNode, isDeno, isBun, isCloudflare,
+ *   // Environment
+ *   getEnv, requireEnv, isDevelopment,
+ *   // Logging
+ *   createLogger, logger,
+ *   // Errors
+ *   ParsError, ValidationError, NotFoundError,
+ *   // Utilities
+ *   generateId, sha256, retry, sleep
+ * } from '@parsrun/core';
+ *
+ * // Create a logger
+ * const log = createLogger({ name: 'my-service' });
+ * log.info('Service started', { port: 3000 });
+ *
+ * // Use runtime detection
+ * if (isCloudflare()) {
+ *   // Cloudflare-specific code
+ * }
+ * ```
  */
 
 /**
- * Generate a cryptographically secure random string (hex)
+ * Generate a cryptographically secure random string (hex).
+ *
+ * @param length - Number of random bytes (output will be 2x this length in hex)
+ * @returns Promise resolving to a hex string
+ *
+ * @example
+ * ```typescript
+ * const token = await generateRandomString(32); // 64 character hex string
+ * ```
  */
 declare function generateRandomString(length: number): Promise<string>;
 /**
- * Generate a UUID v4
+ * Generate a UUID v4 using the Web Crypto API.
+ *
+ * @returns A new UUID v4 string
+ *
+ * @example
+ * ```typescript
+ * const id = generateId(); // "550e8400-e29b-41d4-a716-446655440000"
+ * ```
  */
 declare function generateId(): string;
 /**
- * Hash a string using SHA-256
+ * Hash a string using SHA-256 and return as hex string.
+ *
+ * @param input - The string to hash
+ * @returns Promise resolving to the hex-encoded hash
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha256('password123');
+ * ```
  */
 declare function sha256(input: string): Promise<string>;
 /**
@@ -30,15 +78,52 @@ declare function sha256(input: string): Promise<string>;
  */
 declare function sha256Bytes(input: string): Promise<ArrayBuffer>;
 /**
- * Constant-time string comparison (timing-safe)
+ * Constant-time string comparison (timing-safe).
+ * Use this for comparing secrets to prevent timing attacks.
+ *
+ * @param a - First string to compare
+ * @param b - Second string to compare
+ * @returns True if strings are equal
+ *
+ * @example
+ * ```typescript
+ * if (constantTimeEquals(providedToken, storedToken)) {
+ *   // Token is valid
+ * }
+ * ```
  */
 declare function constantTimeEquals(a: string, b: string): boolean;
 /**
- * Sleep for a given number of milliseconds
+ * Sleep for a given number of milliseconds.
+ *
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * ```typescript
+ * await sleep(1000); // Wait 1 second
+ * ```
  */
 declare function sleep(ms: number): Promise<void>;
 /**
- * Retry a function with exponential backoff
+ * Retry a function with exponential backoff.
+ *
+ * @param fn - The async function to retry
+ * @param options - Retry configuration options
+ * @returns Promise resolving to the function result
+ * @throws The last error if all retries fail
+ *
+ * @example
+ * ```typescript
+ * const data = await retry(
+ *   () => fetchFromAPI('/users'),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelayMs: 1000,
+ *     shouldRetry: (err) => err.status >= 500
+ *   }
+ * );
+ * ```
  */
 declare function retry<T>(fn: () => Promise<T>, options?: {
     maxRetries?: number;
@@ -57,7 +142,16 @@ declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): O
  */
 declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
 /**
- * Deep merge two objects
+ * Deep merge two objects recursively.
+ *
+ * @param target - The target object
+ * @param source - The source object to merge from
+ * @returns A new merged object
+ *
+ * @example
+ * ```typescript
+ * const config = deepMerge(defaults, userConfig);
+ * ```
  */
 declare function deepMerge<T extends object>(target: T, source: Partial<T>): T;
 /**
@@ -109,7 +203,19 @@ declare function createDeferred<T>(): {
     reject: (reason?: unknown) => void;
 };
 /**
- * Run promises with concurrency limit
+ * Run promises with concurrency limit.
+ *
+ * @param tasks - Array of async functions to execute
+ * @param concurrency - Maximum concurrent tasks
+ * @returns Promise resolving to array of results in order
+ *
+ * @example
+ * ```typescript
+ * const results = await pLimit(
+ *   urls.map(url => () => fetch(url)),
+ *   5 // Max 5 concurrent requests
+ * );
+ * ```
  */
 declare function pLimit<T>(tasks: (() => Promise<T>)[], concurrency: number): Promise<T[]>;