hazo_core

hazo_core

Foundation package for every hazo_* package — errors, correlation ID propagation, config loading, logger factory, debug factory, singleton registry, and HTTP middleware.

Install

npm install hazo_core

Required peer deps (ship alongside hazo_core in Wave 1):

npm install hazo_logs hazo_debug

Quick start

import { createLogger, loadConfig, withContext, HazoError } from 'hazo_core';
import { defineConfig } from 'hazo_core';
import z from 'zod';

// Logger (auto-injects correlationId + pkg)
const log = createLogger('hazo_mypackage');
log.info('server.started', { port: 3000 });

// Config (reads hazo_mypackage_config.ini, validates with Zod)
const config = loadConfig({
  pkg: 'hazo_mypackage',
  schema: defineConfig({ port: z.number().default(3000) }),
});

// Correlation ID (AsyncLocalStorage on server)
withContext({ correlationId: 'req_abc123' }, () => {
  log.info('request.received'); // correlationId auto-included
});

// Errors
throw new HazoNotFoundError({ code: 'HAZO_MY_NOT_FOUND', pkg: 'hazo_mypackage', message: 'Resource missing' });

Public API

See design/architecture.md §5 for the complete public API surface.

Errors

import { HazoError, HazoValidationError, HazoAuthError, HazoNotFoundError,
  HazoConflictError, HazoRateLimitError, HazoUnavailableError,
  HazoExternalError, HazoConfigError, HazoInternalError } from 'hazo_core/errors';

Context (correlation ID)

import { withContext, getContext, getCorrelationId } from 'hazo_core/context';

Config, logger, debug, singletons

import { loadConfig, defineConfig, createLogger, createDebug,
  registerSingleton, getSingleton, generateRequestId,
  fetchWithRequestId, createRequestIdMiddleware, REQUEST_ID_HEADER } from 'hazo_core';

Browser-safe subset

import { HazoError } from 'hazo_core/errors';
import { getCorrelationId, setBrowserCorrelationId } from 'hazo_core/context';
import { REQUEST_ID_HEADER } from 'hazo_core/client';

Configuration

Copy config/hazo_core_config.ini to your app's config directory. See SETUP_CHECKLIST.md for integration steps.

See also

• design/architecture.md — full PRD and design rationale
• SETUP_CHECKLIST.md — step-by-step integration guide