@verydia/tooling-core

Low-level utility and tooling foundation for Verydia

Part of the Verydia framework — a modern, modular TypeScript framework for building real production agentic systems.

📦 What is tooling-core?

@verydia/tooling-core provides foundational utilities and common patterns that other Verydia packages can depend on. It's designed to be lightweight, runtime-agnostic, and contain zero cloud/enterprise-specific behavior.

Features

• Environment Variable Utilities — Type-safe env var resolution with defaults
• Configuration Loading — Zod-based typed configuration with validation
• HTTP Client — Lightweight fetch wrapper with Result types
• Result Type — Rust-inspired Result<T, E> for type-safe error handling
• Shared Constants — Common header names, env var names, and types

📦 Installation

npm install @verydia/tooling-core

🎯 Usage

Result Type

Type-safe error handling without exceptions:

import { ok, err, isOk, type Result } from '@verydia/tooling-core';

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) {
    return err("Division by zero");
  }
  return ok(a / b);
}

const result = divide(10, 2);

if (isOk(result)) {
  console.log("Result:", result.value); // 5
} else {
  console.error("Error:", result.error);
}

Environment Variables

import { requireEnv, getEnv, booleanEnv } from '@verydia/tooling-core';

// Require an env var (throws if missing)
const apiKey = requireEnv('VERYDIA_API_KEY');

// Get with default
const logLevel = getEnv('LOG_LEVEL', 'info');

// Boolean env var
const debugMode = booleanEnv('DEBUG', false);

Configuration

import { z } from 'zod';
import { buildConfig, loadCommonConfig } from '@verydia/tooling-core';

// Define your config schema
const MyConfigSchema = z.object({
  apiUrl: z.string().url(),
  timeout: z.number().default(5000),
  retries: z.number().default(3),
});

// Build and validate config
const config = buildConfig(MyConfigSchema, {
  apiUrl: 'https://api.example.com',
  timeout: 10000,
});

// Or load common Verydia config
const commonConfig = loadCommonConfig();
console.log(commonConfig.env); // "development" | "staging" | "production"
console.log(commonConfig.logLevel); // "debug" | "info" | "warn" | "error"

HTTP Client

import { createHttpClient, isOk } from '@verydia/tooling-core';

const client = createHttpClient({
  baseUrl: 'https://api.example.com',
  headers: {
    'x-api-key': 'your-api-key',
  },
  timeout: 5000,
});

// Make a GET request
const result = await client.get('/users/123');

if (isOk(result)) {
  console.log('User:', result.value.data);
  console.log('Status:', result.value.status);
} else {
  console.error('Error:', result.error.message);
}

// POST request
const createResult = await client.post('/users', {
  name: 'John Doe',
  email: '[email protected]',
});

Constants

import {
  VERYDIA_API_KEY_HEADER,
  VERYDIA_PROJECT_ID_HEADER,
  VERYDIA_API_KEY_ENV,
  DEFAULT_LOG_LEVEL,
} from '@verydia/tooling-core';

// Use in HTTP requests
const headers = {
  [VERYDIA_API_KEY_HEADER]: apiKey,
  [VERYDIA_PROJECT_ID_HEADER]: projectId,
};

// Use for env var names
const apiKey = process.env[VERYDIA_API_KEY_ENV];

🏗 API Reference

Result Type

• ok<T>(value: T): Ok<T> — Create a successful Result
• err<E>(error: E): Err<E> — Create a failed Result
• isOk<T, E>(result: Result<T, E>): boolean — Check if Result is Ok
• isErr<T, E>(result: Result<T, E>): boolean — Check if Result is Err
• unwrap<T, E>(result: Result<T, E>): T — Unwrap or throw
• unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T — Unwrap with default
• map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> — Map value
• mapErr<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F> — Map error

Environment Utilities

• requireEnv(name: string): string — Get required env var (throws if missing)
• getEnv(name: string, defaultValue?: string): string | undefined — Get env var with default
• booleanEnv(name: string, defaultValue?: boolean): boolean — Get boolean env var
• numberEnv(name: string, defaultValue?: number): number | undefined — Get number env var
• enumEnv<T>(name: string, allowedValues: T[], defaultValue?: T): T | undefined — Get enum env var

Configuration Utilities

• buildConfig<T>(schema: ZodSchema<T>, source: Record<string, unknown>): T — Build and validate config
• buildConfigSafe<T>(schema: ZodSchema<T>, source: Record<string, unknown>): SafeParseResult<T> — Safe config building
• loadCommonConfig(): VerydiaCommonConfig — Load common Verydia configuration
• createConfigLoader<T>(loader: () => T): ConfigLoader<T> — Create memoized config loader
• mergeConfig<T>(...configs: Partial<T>[]): T — Merge multiple configs

HTTP Client

• createHttpClient(config?: HttpClientConfig): HttpClient — Create HTTP client
• client.get<T>(path: string, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>
• client.post<T>(path: string, body?: unknown, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>
• client.put<T>(path: string, body?: unknown, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>
• client.delete<T>(path: string, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>
• client.patch<T>(path: string, body?: unknown, options?: HttpRequestOptions): Promise<Result<HttpResponse<T>, HttpError>>

🔗 Related Packages

• @verydia/runtime-public — Core runtime primitives
• @verydia/schema-core — Type system and validation
• @verydia/workflow-core — Workflow execution engine

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting changes.

📄 License

Apache-2.0

🆘 Support

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Email: [email protected]