Katax Docs Hub

● Installation

npm install katax-core
npm install katax-service-manager
npm install -g katax-cli

# optional peer deps for katax-service-manager
npm install pg mysql2 mongodb redis socket.io dotenv node-cron pino-pretty

● katax-core

katax-core is the validation layer. The entry point is k. Supports 20+ schema types, coercion, preprocess, async validators, composition and error utilities.

Quick Start

import { k, type kataxInfer } from 'katax-core';

const UserSchema = k.object({
  email: k.email(),
  name: k.string().minLength(2).maxLength(100),
  age: k.number().min(18).optional(),
});

type User = kataxInfer<typeof UserSchema>;

const result = UserSchema.safeParse(req.body);
if (!result.success) return res.status(400).json({ errors: result.issues });

Core Types

type SafeParseResult<T> = 
  | { success: true; data: T }
  | { success: false; issues: Issue[] }

interface Issue {
  path: (string | number)[];
  message: string;
}

interface ValidationResult {
  valid: boolean;
  issues: Issue[];
}

Schema API

All schemas implement: parse(input): T · safeParse(input): SafeParseResult<T> · validate(input): ValidationResult · parseAsync(input): Promise<T> · safeParseAsync(input): Promise<AsyncSafeParseResult<T>> · isValidAsync(input): Promise<AsyncValidationResult> · hasAsyncValidation(): boolean · kataxInfer: T

All k factories

k.string()    k.number()    k.boolean()    k.date()     k.twoDates()
k.object()    k.array()     k.tuple()      k.record()
k.union()     k.intersection()            k.lazy()
k.email()     k.file()      k.base64()
k.custom()    k.literal()   k.enum()
k.any()       k.unknown()   k.never()
k.coerce      k.preprocess()

Modifiers (chainable, all schemas)

schema.optional()             // T | undefined
schema.nullable()             // T | null
schema.default(value)         // Returns default if undefined
schema.transform(fn)          // Transform output type
schema.catch(value)           // Return fallback on validation failure

● String — k.string()

● Number — k.number()

● Boolean — k.boolean()

● Object — k.object(shape)

By default, extra keys are stripped. Use passthrough() to keep them or strict() to reject them.

const schema = k.object({
  name: k.string().minLength(2),
  age: k.number().min(18).optional(),
}).strict();

● Array — k.array(elementSchema?)

● Email — k.email()

RFC 5322 compliant validation.

● Date & TwoDates

k.date()

Input: ISO 8601. Output: Date object. Uses date-fns.

k.twoDates(separator?)

Input: Two ISO dates separated by separator (default '|'). Output: [Date, Date].

● File — k.file()

Compatible with Browser File API and Node.js Multer objects.

● Base64 — k.base64()

Validates base64-encoded strings, including data URLs.

● Union / Intersection / Lazy

// Union — at least one schema must match (short-circuit)
k.union([k.string(), k.number()])

// Intersection — ALL schemas must match (merge objects)
k.intersection([
  k.object({ id: k.number() }),
  k.object({ name: k.string() })
])

// Lazy — deferred resolution for recursive types
const categorySchema = k.lazy(() =>
  k.object({
    name: k.string(),
    subcategories: k.array(categorySchema)
  })
);

● Literal / Enum / Tuple / Record / Any / Unknown / Never

k.literal('active')               // Exact value (===)
k.enum(['active', 'inactive'])    // String union
k.tuple([k.number(), k.string()]) // Fixed-length typed array
k.record(k.number())              // Record<string, number>
k.any()                           // Accepts everything
k.unknown()                       // Accepts everything (forces narrowing)
k.never()                         // Never matches

● Custom — k.custom<T>(validator)

const positiveEven = k.custom<number>((value, path) => {
  if (typeof value !== 'number')
    return [{ path, message: 'Must be number' }];
  if (value <= 0 || value % 2 !== 0)
    return [{ path, message: 'Must be positive even' }];
  return value;
});

// Add refinement
positiveEven.refine((v) => v < 1000, 'Must be less than 1000');

● Modifiers / Coercion / Preprocess

Coercion — k.coerce

Auto-converts types before validating:

k.coerce.number()   // "42" → 42, true → 1, false → 0
k.coerce.boolean()  // "true"/"1"/"yes" → true, "false"/"0"/"no" → false
k.coerce.string()   // 42 → "42", true → "true", null → ""
k.coerce.date()     // ISO string → Date, timestamp → Date

// Proxy validation methods available:
k.coerce.number().positive().integer()
k.coerce.boolean().isTrue()
k.coerce.string().minLength(3).email()
k.coerce.date().isFuture()

Preprocess — k.preprocess(fn, schema)

k.preprocess(
  (val) => typeof val === 'string' ? val.trim().toLowerCase() : val,
  k.string().email()
)

Error Utilities

import { createIssue, issues, mergeIssues, isIssueArray, KataxError } from 'katax-core';

createIssue(['field'], 'error message');   // Issue object
issues(['field'], 'error message');         // Issue[]
mergeIssues(arr1, arr2);                    // Merge issue arrays
isIssueArray(value);                        // Type guard

// KataxError is thrown by parse()/parseAsync()
throw new KataxError(result.issues);

● Async Validation

const usernameSchema = k.string().minLength(3).asyncRefine(async (value, path) => {
  const exists = await usersRepo.existsByUsername(value);
  return exists ? [{ path, message: 'Already taken' }] : [];
});

const result = await usernameSchema.safeParseAsync(input);

// Also available:
await schema.parseAsync(input);      // Throws KataxError
await schema.isValidAsync(input);    // { valid, issues }

● katax-service-manager

Singleton container that manages config, logger, databases, WebSocket, cron, cache, registry, health, and graceful shutdown.

● Initialization, Environment & Lifecycle

Init

import { katax } from 'katax-service-manager';

await katax.init({
  loadEnv: true,
  appName: 'my-api',
  logger: { level: 'info', prettyPrint: true, enableBroadcast: false },
  hooks: {
    beforeInit: () => {},
    afterInit: () => {},
    beforeShutdown: () => {},
    afterShutdown: () => {},
    onError: (context, error) => {},
  },
  registry: { url: 'https://dashboard.example.com/api/services' },
});

Environment Helpers

katax.env('PORT', '3000');        // string with default
katax.env('PORT', 3000);          // number (auto-cast)
katax.env('DEBUG', false);        // boolean (auto-cast)
katax.envRequired('JWT_SECRET');  // throws if missing

katax.isDev    katax.isProd    katax.isTest
katax.nodeEnv  katax.appName   katax.version
katax.isInitialized

Overrides (testing)

import { Katax } from 'katax-service-manager';
beforeEach(() => Katax.reset());

katax.overrideService('db:main', mockDb);
katax.overrideService('logger', mockLogger);
katax.clearOverride('db:main');   // Remove specific
katax.clearOverride();            // Remove all

Shutdown & Hooks

katax.onShutdown(async () => {
  await cleanupCustomResource();
});

await katax.shutdown();
// Closes all services in order: hooks, DB, WS, cron, registry, bridges
// SIGTERM and SIGINT are handled automatically

● Database Service

Supports PostgreSQL, MySQL, MongoDB, and Redis with typed connections and configurable pool.

Setup

// PostgreSQL / MySQL
const db = await katax.database({
  name: 'main', type: 'postgresql',
  connection: { host: 'localhost', port: 5432, database: 'myapp', user: 'admin', password: 'secret' },
  pool: { max: 10, min: 2 },
});

// MongoDB
const mongo = await katax.database({
  name: 'analytics', type: 'mongodb',
  connection: { host: 'localhost', port: 27017, database: 'analytics' },
});

// Redis
const redis = await katax.database({
  name: 'cache', type: 'redis',
  connection: { host: '127.0.0.1', port: 6379 },
});

Typed Access

const db = katax.db('main');

db.asSql()    // ISqlDatabase — query<T>(sql, params?), getClient(), close()
db.asMongo()  // IMongoDatabase — getClient(), close()
db.asRedis()  // IRedisDatabase — redis(...args), close()

// SQL query
const users = await db.asSql().query<User[]>('SELECT * FROM users WHERE id = $1', [userId]);

// Redis command
await db.asRedis().redis('SET', 'key', 'value', 'EX', '60');
await db.asRedis().redis('GET', 'key');

● Cache Service

High-level Redis wrapper with automatic JSON serialization.

const cache = katax.cache('cache'); // Redis connection name

await cache.set('user:123', userData, 3600);
const user = await cache.get<User>('user:123');
await cache.del('user:123');
await cache.incr('page:views');
await cache.mset([['k1', v1], ['k2', v2]]);

● Logger & Transports

Pino-based structured logging with WebSocket broadcast and transport system.

// All log levels
katax.logger.trace('trace message');
katax.logger.debug('debug message');
katax.logger.info({ message: 'Server started', port: 3000 });
katax.logger.warn({ message: 'High memory', percent: 85 });
katax.logger.error({ message: 'Query failed', error: err });
katax.logger.fatal('fatal error');

// Child logger with context
const log = katax.logger.child({ service: 'payments', userId: 123 });
log.info({ message: 'Payment processed' });

// Broadcast to WebSocket
katax.logger.info({ message: 'Trade executed', broadcast: true, room: 'admins' });

Transports

import { RedisTransport, TelegramTransport, CallbackTransport } from 'katax-service-manager';

// Redis transport
const redisTransport = new RedisTransport(katax.db('cache'), {
  streamKey: 'katax:logs', name: 'redis-errors',
});
redisTransport.filter = (log) => log.level === 'error' || log.persist === true;
katax.logger.addTransport(redisTransport);

// Telegram
const telegram = new TelegramTransport({
  botToken: katax.envRequired('TELEGRAM_BOT_TOKEN'),
  chatId: katax.envRequired('TELEGRAM_ALERTS_CHAT_ID'),
  levels: ['error', 'fatal'],
  includePersist: true, parseMode: 'Markdown',
});
katax.logger.addTransport(telegram);

// Management
katax.logger.removeTransport('telegram-errors');
await katax.logger.closeTransports();

● WebSocket (Socket.IO)

// Shared with Express (preferred)
const httpServer = createServer(app);
await katax.socket({
  name: 'main', httpServer,
  cors: { origin: '*' },
});

// Standalone with auth
await katax.socket({
  name: 'events', port: 3001,
  enableAuth: true,
  authValidator: async (token) => token === katax.envRequired('WS_SECRET'),
});

const ws = katax.ws('main');

ws.onConnection((socket) => {
  socket.on('message', (data) => { ... });
  socket.emit('welcome', { status: 'connected' });
  socket.join('room-123');
  socket.leave('room-123');
});

● Cron Service

katax.cron({
  name: 'process-assets',
  schedule: '*/10 6-15 * * 1-5',
  task: processAssets,
  runOnInit: katax.isProd,
  timezone: 'America/Mexico_City',
  enabled: true,
});

// Advanced management
katax.cronService.getJobs();
katax.cronService.startJob('process-assets');
katax.cronService.stopJob('process-assets');
katax.cronService.removeJob('process-assets');
katax.cronService.stopAll();

● Registry & Health Check

await katax.init({
  registry: {
    url: 'https://dashboard.example.com/api/services',
    apiKey: katax.env('REGISTRY_KEY'),
    heartbeatInterval: 30000,
    requestTimeoutMs: 5000,
    retryAttempts: 2,
    retryBaseDelayMs: 300,
    metadata: { env: katax.nodeEnv, region: 'us-east' },
  },
});

// Or custom handler
registry: {
  handler: {
    register: async (info) => { ... },
    heartbeat: async (info) => { ... },
    unregister: async (payload) => { ... },
  }
}

katax.isRegistered;         // boolean
katax.getServiceInfo();     // ServiceInfo | null

Health Check

const health = await katax.healthCheck();
// { status: 'healthy' | 'degraded' | 'unhealthy',
//   services: { databases: {}, sockets: {}, cron: boolean },
//   timestamp: number }

● Redis Stream Bridge & Heartbeat

Stream Bridge

const bridge = katax.bridge('cache', 'main', {
  appName: 'my-api',
  streamKey: 'katax:logs',
  group: 'katax-bridge-my-api',
  batchSize: 10,
  blockTimeout: 2000,
});
await bridge.start();
bridge.isRunning();
bridge.stop();

Heartbeat

// Managed (auto-cleanup on shutdown)
katax.heartbeat(
  { app: katax.appName, port: 3000, version: katax.version, intervalMs: 10000 },
  'cache', 'main',
);

// Manual helpers
import { registerProjectInRedis, startHeartbeat } from 'katax-service-manager';
await registerProjectInRedis(redisDb, { app: katax.appName, version: katax.version, port: PORT });
const hb = startHeartbeat(redisDb, { app: katax.appName, port: PORT, intervalMs: 10000 }, ws);
hb?.stop();

● Bootstrap Template

import dotenv from 'dotenv';
dotenv.config();

import { katax } from 'katax-service-manager';
import { createServer } from 'http';
import app from './app.js';

async function bootstrap(): Promise<void> {
  try {
    await katax.init({
      loadEnv: true,
      logger: { level: katax.env('LOG_LEVEL', 'info') as any, prettyPrint: katax.isDev, enableBroadcast: true },
    });

    await katax.database({
      name: 'main', type: 'postgresql',
      connection: {
        host: katax.envRequired('DB_HOST'),
        port: katax.env('DB_PORT', 5432),
        database: katax.envRequired('DB_NAME'),
        user: katax.envRequired('DB_USER'),
        password: katax.envRequired('DB_PASSWORD'),
      },
      pool: { max: 10, min: 2 },
    });

    await katax.database({
      name: 'cache', type: 'redis',
      connection: { host: katax.env('REDIS_HOST', '127.0.0.1'), port: 6379 },
    });

    const PORT = katax.env('PORT', '3000');
    const httpServer = createServer(app);
    await katax.socket({ name: 'main', httpServer, cors: { origin: '*' } });

    katax.cron({ name: 'cleanup', schedule: '0 3 * * *', task: async () => { /* nightly */ } });

    httpServer.listen(PORT, () => {
      katax.logger.info({ message: 'Server running on http://localhost:' + PORT });
    });
  } catch (err) {
    console.error('Bootstrap failed:', err);
    process.exit(1);
  }
}

void bootstrap();

● katax-cli

CLI for scaffolding Express + TypeScript APIs, generating CRUD/endpoints/repositories, OpenAPI docs, and managing VPS deployments with PM2.

● Commands

katax init [project-name]

Scaffolds a complete Express + TypeScript + katax-core project.

katax add endpoint <name>

Add a new endpoint with validator, controller, handler, and routes.

katax generate crud <resource-name>

Aliases: gen, g. Generates CRUD endpoints: list, get by ID, create, update, delete.

katax generate repository <name>

Data access layer with typed methods: findAll(), findById(), exists(), create(), update(), delete().

katax generate docs

katax info

Aliases: status, ls. Shows project structure, dependencies, and routes.

Deploy

katax deploy init       # Initial PM2 setup (repo, branch, path, cluster, memory, env)
katax deploy update     # Pull, rebuild, restart
  -b, --branch <branch>
  --hard                # Hard reset
  -a, --app-name <name>
katax deploy rollback   # Revert commits
  -c, --commits <n>     # Default: 1
  -a, --app-name <name>
katax deploy logs       # View PM2 logs
  -l, --lines <n>
  -f, --follow
  -a, --app-name <name>
katax deploy status     # Show PM2 apps

Fix

katax fix docs        # Patch build script to copy openapi.json
  --skip-install
katax fix all         # Apply all fixes
katax fix list        # List available patches

Global Options

--no-color     # Disable colored output
--verbose      # Enable verbose logging
-v, --version  # Show version

Examples

katax init my-api --pm pnpm --ignore-scripts --write-npmrc
katax add endpoint admin/audit/logs -m POST
katax generate crud admin/users --no-auth
katax generate repository products
katax generate docs -u https://api.example.com
katax deploy update -b production --hard

● Generators & Templates

Shared Utilities

Result Pattern & Errors

// Result<T, E> pattern
import { ok, err, isOk, isErr, map, mapErr, flatMap,
  unwrap, unwrapOr, tryCatch, tryCatchAsync, combine, match } from './core/result.js';

// AppError hierarchy
import { AppError, ValidationError, AuthenticationError,
  AuthorizationError, NotFoundError, ConflictError,
  DatabaseError, ExternalServiceError, isAppError } from './core/errors.js';

● AI Skill — katax-ecosystem

The Copilot/AI skill for the Katax ecosystem. Knows versions, exports, patterns, CLI commands and troubleshooting.

● Current Published Status

• katax-core 1.5.4: 20+ schema types, coercion, async validation, file/base64, advanced email, union/intersection/lazy, preprocess, error utilities.
• katax-service-manager 0.5.3: Singleton/instance, typed DB (PostgreSQL/MySQL/MongoDB/Redis), cache, cron, WebSocket with auth, transports (Redis/Telegram/Callback), registry, health, lifecycle hooks, stream bridge, heartbeat.
• katax-cli 1.4.4: Init with advanced prompts, CRUD/endpoint/repository generators, OpenAPI docs, PM2 deploy (init/update/rollback/logs/status), fixes, nested resources, typed access.