Package Exports

@verydia/tooling-core

Readme

@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: 'john@example.com',
});

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>>

@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: oss@verydia.dev

Built with ❤️ for developers who value simplicity, type safety, and production readiness.

Website • GitHub • npm