@chittyos/env

Type-safe environment variable management for ChittyOS Framework.

Installation

npm install @chittyos/env

Usage

Load ChittyOS Environment

import { loadChittyOSEnv } from '@chittyos/env';

// Load with validation (requires CHITTY_ID_TOKEN)
const env = loadChittyOSEnv();

console.log(env.CHITTY_ID_TOKEN);      // Required
console.log(env.CHITTYID_SERVICE);     // Optional
console.log(env.DATABASE_URL);         // Optional

Custom Environment Configuration

import { loadEnv } from '@chittyos/env';

const env = loadEnv({
  required: ['API_KEY', 'DATABASE_URL'],
  optional: ['DEBUG', 'LOG_LEVEL'],
  defaults: {
    LOG_LEVEL: 'info',
  },
  validators: {
    DATABASE_URL: (v) => v.startsWith('postgresql://'),
    API_KEY: (v) => v.length > 20,
  },
  errorMessages: {
    API_KEY: 'API_KEY must be at least 20 characters',
    DATABASE_URL: 'DATABASE_URL must be a valid PostgreSQL URL',
  },
});

Individual Variable Access

import { requireEnv, getEnv, getBoolEnv, getNumberEnv, getArrayEnv } from '@chittyos/env';

// Require variable (throws if missing)
const token = requireEnv('CHITTY_ID_TOKEN');

// Get with optional default
const debug = getEnv('DEBUG', 'false');

// Get as boolean
const isDebug = getBoolEnv('DEBUG'); // true if "true" or "1"

// Get as number
const port = getNumberEnv('PORT', 3000);

// Get as array (comma-separated)
const scopes = getArrayEnv('SCOPES'); // "read,write" -> ["read", "write"]

Built-in Validators

import { validators, validateUrl, validateEmail, validateChittyIDToken } from '@chittyos/env';

// URL validation
const isValid = validateUrl('https://id.chitty.cc'); // true

// Email validation
validateEmail('[email protected]'); // true

// ChittyID token validation
validateChittyIDToken('valid-token-abc123'); // true

// Use with loadEnv
loadEnv({
  required: ['SERVICE_URL', 'EMAIL'],
  validators: {
    SERVICE_URL: validators.url,
    EMAIL: validators.email,
  },
});

// Custom validators
validators.notEmpty('value'); // true
validators.minLength(10)('short'); // false
validators.pattern(/^\d+$/)('123'); // true

Environment Presets

import { envPresets } from '@chittyos/env';

// Full ChittyOS integration
const chittyosEnv = envPresets.chittyos();

// ChittyID only
const chittyidEnv = envPresets.chittyid();

// ChittyAuth only
const chittyauthEnv = envPresets.chittyauth();

// Database only
const dbEnv = envPresets.database();

Environment Detection

import { getCurrentEnvironment, isProduction, isDevelopment } from '@chittyos/env';

const env = getCurrentEnvironment(); // 'development' | 'staging' | 'production'

if (isProduction()) {
  console.log('Running in production');
}

if (isDevelopment()) {
  console.log('Running in development');
}

ChittyOS Environment Variables

Required

• CHITTY_ID_TOKEN - ChittyOS authentication token

Optional

• CHITTYOS_ACCOUNT_ID - Cloudflare account ID
• CHITTYID_SERVICE - ChittyID service URL (default: https://id.chitty.cc)
• CHITTYAUTH_SERVICE - ChittyAuth service URL (default: https://auth.chitty.cc)
• CHITTYSCHEMA_SERVICE - ChittySchema service URL (default: https://schema.chitty.cc)
• CHITTYROUTER_SERVICE - ChittyRouter service URL (default: https://router.chitty.cc)
• CHITTYCHAT_SERVICE - ChittyChat service URL (default: https://gateway.chitty.cc)
• REGISTRY_SERVICE - Registry service URL (default: https://registry.chitty.cc)
• GATEWAY_SERVICE - Gateway service URL (default: https://gateway.chitty.cc)
• DATABASE_URL - Database connection string
• NEON_DATABASE_URL - Neon database connection string
• NODE_ENV - Node environment (development | staging | production)
• ENVIRONMENT - Application environment
• CLOUDFLARE_ACCOUNT_ID - Cloudflare account ID
• CLOUDFLARE_API_TOKEN - Cloudflare API token
• DEBUG - Debug flag
• LOG_LEVEL - Logging level (debug | info | warn | error)

Error Handling

import { ValidationError } from '@chittyos/types';
import { loadChittyOSEnv } from '@chittyos/env';

try {
  const env = loadChittyOSEnv();
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Environment validation failed:', error.message);
    console.error('Missing variables:', error.metadata?.missing);
    console.error('Invalid variables:', error.metadata?.invalid);
  }
}

Features

• ✅ Type-safe environment loading
• ✅ Required vs optional validation
• ✅ Custom validators
• ✅ Default values
• ✅ Type conversion (boolean, number, array)
• ✅ Built-in validators (URL, email, ChittyID token)
• ✅ Environment presets
• ✅ Clear error messages
• ✅ Zero runtime dependencies

Package Size

~15KB (gzipped)

License

MIT