@pyreon/zero 0.24.4 → 0.24.6

package/src/env.ts

@@ -1,344 +0,0 @@
-/**
- * Environment variable validation.
- *
- * Infers types from default values — no verbose validator imports needed.
- * Explicit validators (`url()`, `oneOf()`) available for special cases.
- *
- * @example
- * ```ts
- * import { validateEnv, url, oneOf } from "@pyreon/zero/env"
- *
- * const env = validateEnv({
- *   PORT: 3000,                                // number, default 3000
- *   DEBUG: false,                              // boolean, default false
- *   HOST: "localhost",                         // string, default "localhost"
- *   DATABASE_URL: url(),                       // validated URL, required
- *   NODE_ENV: oneOf(["development", "production", "test"]),
- *   API_KEY: String,                           // required string, no default
- *   MAX_RETRIES: Number,                       // required number, no default
- * })
- * ```
- */
-
-export interface EnvValidatorOptions<T = string> {
-  /** Whether this variable is required. Default: true */
-  required?: boolean
-  /** Default value when not set. Makes the variable optional. */
-  default?: T
-  /** Human-readable description for error messages. */
-  description?: string
-}
-
-export interface EnvValidator<T> {
-  __type: 'env-validator'
-  parse: (raw: string | undefined, key: string) => T
-  required: boolean
-  defaultValue?: T | undefined
-}
-
-// ─── Explicit validators (for special cases) ────────────────────────────────
-
-/**
- * String validator — accepts any non-empty string.
- */
-export function str(options?: EnvValidatorOptions<string>): EnvValidator<string> {
-  const required = options?.default === undefined && options?.required !== false
-  return {
-    __type: 'env-validator',
-    required,
-    defaultValue: options?.default,
-    parse(raw, key) {
-      if (raw === undefined || raw === '') {
-        if (options?.default !== undefined) return options.default
-        throw new EnvError(key, 'is required but not set', options?.description)
-      }
-      return raw
-    },
-  }
-}
-
-/**
- * Number validator — parses to a number, rejects NaN.
- */
-export function num(options?: EnvValidatorOptions<number>): EnvValidator<number> {
-  const required = options?.default === undefined && options?.required !== false
-  return {
-    __type: 'env-validator',
-    required,
-    defaultValue: options?.default,
-    parse(raw, key) {
-      if (raw === undefined || raw === '') {
-        if (options?.default !== undefined) return options.default
-        throw new EnvError(key, 'is required but not set', options?.description)
-      }
-      const n = Number(raw)
-      if (Number.isNaN(n)) {
-        throw new EnvError(key, `must be a number, got "${raw}"`, options?.description)
-      }
-      return n
-    },
-  }
-}
-
-/**
- * Boolean validator — accepts "true"/"1" as true, "false"/"0" as false.
- */
-export function bool(options?: EnvValidatorOptions<boolean>): EnvValidator<boolean> {
-  const required = options?.default === undefined && options?.required !== false
-  return {
-    __type: 'env-validator',
-    required,
-    defaultValue: options?.default,
-    parse(raw, key) {
-      if (raw === undefined || raw === '') {
-        if (options?.default !== undefined) return options.default
-        throw new EnvError(key, 'is required but not set', options?.description)
-      }
-      const lower = raw.toLowerCase()
-      if (lower === 'true' || lower === '1') return true
-      if (lower === 'false' || lower === '0') return false
-      throw new EnvError(key, `must be "true" or "false", got "${raw}"`, options?.description)
-    },
-  }
-}
-
-/**
- * URL validator — validates that the value is a valid URL.
- */
-export function url(options?: EnvValidatorOptions<string>): EnvValidator<string> {
-  const required = options?.default === undefined && options?.required !== false
-  return {
-    __type: 'env-validator',
-    required,
-    defaultValue: options?.default,
-    parse(raw, key) {
-      if (raw === undefined || raw === '') {
-        if (options?.default !== undefined) return options.default
-        throw new EnvError(key, 'is required but not set', options?.description)
-      }
-      try {
-        new URL(raw)
-        return raw
-      } catch {
-        throw new EnvError(key, `must be a valid URL, got "${raw}"`, options?.description)
-      }
-    },
-  }
-}
-
-/**
- * Enum validator — value must be one of the allowed values.
- */
-export function oneOf<T extends string>(
-  values: readonly T[],
-  options?: EnvValidatorOptions<T>,
-): EnvValidator<T> {
-  const required = options?.default === undefined && options?.required !== false
-  return {
-    __type: 'env-validator',
-    required,
-    defaultValue: options?.default,
-    parse(raw, key) {
-      if (raw === undefined || raw === '') {
-        if (options?.default !== undefined) return options.default
-        throw new EnvError(key, 'is required but not set', options?.description)
-      }
-      if (!values.includes(raw as T)) {
-        throw new EnvError(
-          key,
-          `must be one of [${values.join(', ')}], got "${raw}"`,
-          options?.description,
-        )
-      }
-      return raw as T
-    },
-  }
-}
-
-// ─── Internal helpers ───────────────────────────────────────────────────────
-
-class EnvError extends Error {
-  constructor(key: string, message: string, description?: string) {
-    const desc = description ? ` (${description})` : ''
-    super(`[Pyreon] ${key}${desc}: ${message}`)
-    this.name = 'EnvError'
-  }
-}
-
-function isEnvValidator(v: unknown): v is EnvValidator<unknown> {
-  return typeof v === 'object' && v !== null && (v as any).__type === 'env-validator'
-}
-
-/**
- * Convert a plain schema value to an EnvValidator.
- *
- * - `3000` → num({ default: 3000 })
- * - `false` → bool({ default: false })
- * - `"localhost"` → str({ default: "localhost" })
- * - `String` → str() (required)
- * - `Number` → num() (required)
- * - `Boolean` → bool() (required)
- * - EnvValidator → pass through
- */
-function toValidator(value: unknown): EnvValidator<unknown> {
-  if (isEnvValidator(value)) return value
-
-  // Constructor markers → required, no default
-  if (value === String) return str()
-  if (value === Number) return num()
-  if (value === Boolean) return bool()
-
-  // Plain values → infer type + use as default
-  if (typeof value === 'number') return num({ default: value })
-  if (typeof value === 'boolean') return bool({ default: value })
-  if (typeof value === 'string') return str({ default: value })
-
-  throw new Error(`[Pyreon] Invalid schema value: ${String(value)}. Use a default value, String/Number/Boolean, or a validator like url().`)
-}
-
-// ─── Type inference ─────────────────────────────────────────────────────────
-
-/** Schema entry: plain value, constructor, or explicit validator. */
-type SchemaEntry =
-  | string | number | boolean
-  | StringConstructor | NumberConstructor | BooleanConstructor
-  | EnvValidator<any>
-
-/** Infer the output type from a schema entry. */
-type InferEntry<T> =
-  T extends EnvValidator<infer V> ? V :
-  T extends StringConstructor ? string :
-  T extends NumberConstructor ? number :
-  T extends BooleanConstructor ? boolean :
-  T extends string ? string :
-  T extends number ? number :
-  T extends boolean ? boolean :
-  never
-
-type InferEnvSchema<T> = {
-  [K in keyof T]: InferEntry<T[K]>
-}
-
-// ─── Main API ───────────────────────────────────────────────────────────────
-
-/**
- * Validate environment variables.
- *
- * Schema values can be:
- * - **Default values**: `3000`, `false`, `"localhost"` → type inferred, used as default
- * - **Constructors**: `String`, `Number`, `Boolean` → required, no default
- * - **Validators**: `url()`, `oneOf([...])`, `str()`, `num()`, `bool()` → explicit validation
- * - **Custom**: `schema(raw => z.coerce.number().parse(raw))` — bridge to any schema library
- *
- * @example
- * ```ts
- * import { validateEnv, url, oneOf } from "@pyreon/zero/env"
- *
- * const env = validateEnv({
- *   PORT: 3000,                                // optional, default 3000
- *   DATABASE_URL: url(),                       // required, validated URL
- *   NODE_ENV: oneOf(["dev", "prod", "test"]),  // required, must be one of
- *   API_KEY: String,                           // required string
- *   DEBUG: false,                              // optional, default false
- * })
- * ```
- */
-export function validateEnv<T extends Record<string, SchemaEntry>>(
-  envSchema: T,
-  source?: Record<string, string | undefined>,
-): InferEnvSchema<T> {
-  const env = source ?? (typeof process !== 'undefined' ? process.env : {})
-  const result: Record<string, unknown> = {}
-  const errors: string[] = []
-
-  for (const [key, entry] of Object.entries(envSchema)) {
-    const validator = toValidator(entry)
-    try {
-      result[key] = validator.parse(env[key], key)
-    } catch (e) {
-      errors.push((e as Error).message)
-    }
-  }
-
-  if (errors.length > 0) {
-    const header = `\n[Pyreon] Environment validation failed (${errors.length} error${errors.length > 1 ? 's' : ''}):\n`
-    const body = errors.map((e) => `  ✗ ${e.replace('[Pyreon] ', '')}`).join('\n')
-    throw new Error(header + body + '\n')
-  }
-
-  return result as InferEnvSchema<T>
-}
-
-// ─── Public env (client-safe) ────────────────────────────────────────────────
-
-/**
- * Extract public environment variables (prefixed with `ZERO_PUBLIC_`).
- *
- * @example
- * ```ts
- * const pub = publicEnv()
- * // → { API_URL: "https://...", APP_NAME: "MyApp" }
- *
- * const pub = publicEnv({ API_URL: url(), APP_NAME: "Default" })
- * // → validated against ZERO_PUBLIC_API_URL, ZERO_PUBLIC_APP_NAME
- * ```
- */
-export function publicEnv(): Record<string, string>
-export function publicEnv<T extends Record<string, SchemaEntry>>(envSchema: T): InferEnvSchema<T>
-export function publicEnv(envSchema?: Record<string, SchemaEntry>): Record<string, unknown> {
-  const prefix = 'ZERO_PUBLIC_'
-  const env = typeof process !== 'undefined' ? process.env : {}
-
-  if (!envSchema) {
-    const result: Record<string, string> = {}
-    for (const [key, value] of Object.entries(env)) {
-      if (key.startsWith(prefix) && value !== undefined) {
-        result[key.slice(prefix.length)] = value
-      }
-    }
-    return result
-  }
-
-  const prefixedSource: Record<string, string | undefined> = {}
-  for (const key of Object.keys(envSchema)) {
-    prefixedSource[key] = env[`${prefix}${key}`]
-  }
-  return validateEnv(envSchema, prefixedSource)
-}
-
-// ─── Custom validator escape hatch ──────────────────────────────────────────
-
-/**
- * Create an env validator from a custom parse function.
- * Use this to integrate any schema library (Zod, Valibot, ArkType, etc.).
- *
- * @example
- * ```ts
- * import { z } from "zod"
- * import { validateEnv, schema } from "@pyreon/zero/env"
- *
- * const env = validateEnv({
- *   PORT: schema(raw => z.coerce.number().parse(raw)),
- *   DATABASE_URL: schema(raw => z.string().url().parse(raw)),
- *   HOST: "localhost",  // plain defaults still work alongside
- * })
- * ```
- */
-export function schema<T>(parse: (raw: string) => T): EnvValidator<T> {
-  return {
-    __type: 'env-validator',
-    required: true,
-    defaultValue: undefined,
-    parse(raw: string | undefined, key: string) {
-      if (raw === undefined || raw === '') {
-        throw new Error(`[Pyreon] ${key}: is required but not set`)
-      }
-      try {
-        return parse(raw)
-      } catch (e) {
-        const msg = e instanceof Error ? e.message : String(e)
-        throw new Error(`[Pyreon] ${key}: ${msg}`)
-      }
-    },
-  }
-}

package/src/error-overlay.ts

@@ -1,118 +0,0 @@
-/**
- * Dev-only error overlay for SSR/loader errors.
- * Renders a styled HTML page with the error stack trace.
- */
-export function renderErrorOverlay(error: Error): string {
-  const title = escapeHtml(error.message || 'Unknown error')
-  const stack = escapeHtml(error.stack || '')
-
-  return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>SSR Error — Pyreon Zero</title>
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    body {
-      font-family: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas, monospace;
-      background: #1a1a2e;
-      color: #e0e0e0;
-      min-height: 100vh;
-      padding: 2rem;
-    }
-    .overlay {
-      max-width: 900px;
-      margin: 0 auto;
-    }
-    .header {
-      display: flex;
-      align-items: center;
-      gap: 0.75rem;
-      margin-bottom: 1.5rem;
-    }
-    .badge {
-      background: #e74c3c;
-      color: white;
-      padding: 0.25rem 0.75rem;
-      border-radius: 4px;
-      font-size: 0.75rem;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: 0.05em;
-    }
-    .label {
-      color: #888;
-      font-size: 0.85rem;
-    }
-    .message {
-      font-size: 1.25rem;
-      color: #ff6b6b;
-      margin-bottom: 1.5rem;
-      line-height: 1.5;
-      word-break: break-word;
-    }
-    .stack {
-      background: #16213e;
-      border: 1px solid #2a2a4a;
-      border-radius: 8px;
-      padding: 1.25rem;
-      overflow-x: auto;
-      font-size: 0.8rem;
-      line-height: 1.7;
-      white-space: pre-wrap;
-      word-break: break-all;
-    }
-    .stack .at { color: #888; }
-    .stack .file { color: #4ecdc4; }
-    .hint {
-      margin-top: 1.5rem;
-      padding: 1rem;
-      background: #1e2a45;
-      border-radius: 6px;
-      border-left: 3px solid #3498db;
-      font-size: 0.8rem;
-      color: #aaa;
-      line-height: 1.5;
-    }
-  </style>
-</head>
-<body>
-  <div class="overlay">
-    <div class="header">
-      <span class="badge">SSR Error</span>
-      <span class="label">Pyreon Zero — Dev Mode</span>
-    </div>
-    <div class="message">${title}</div>
-    <pre class="stack">${formatStack(stack)}</pre>
-    <div class="hint">
-      This error occurred during server-side rendering. Check the terminal for
-      the full stack trace. This overlay is only shown in development.
-    </div>
-  </div>
-</body>
-</html>`
-}
-
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}
-
-function formatStack(stack: string): string {
-  return stack
-    .split('\n')
-    .map((line) => {
-      if (line.includes('at ')) {
-        const fileMatch = line.match(/\(([^)]+)\)/)
-        if (fileMatch) {
-          return line.replace(fileMatch[0], `(<span class="file">${fileMatch[1]}</span>)`)
-        }
-      }
-      return line
-    })
-    .join('\n')
-}