README.md

@catbee/utils

🧰 Utility Modules for Node.js

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications. All utilities are tree-shakable and can be imported independently.

---

🚀 Key Features

• Modular: Import only what you need
• TypeScript-first: Full typings and type safety
• Production-ready: Robust, well-tested utilities
• Tree-shakable: Zero bloat in your bundle
• Express-friendly: Designed for scalable server apps

---

📦 Installation

npm i @catbee/utils

---

⚡ Quick Start

import { ServerConfigBuilder, ExpressServer } from '@catbee/utils/server';
import { Router } from 'express';

const config = new ServerConfigBuilder()
  .withPort(3000)
  .withCors({ origin: '*' })
  .enableRateLimit({ max: 50, windowMs: 60000 })
  .enableRequestLogging({ ignorePaths: ['/healthz', '/metrics'] })
  .withHealthCheck({ path: '/health', detailed: true })
  .enableOpenApi('./openapi.yaml', { mountPath: '/docs' })
  .withGlobalHeaders({ 'X-Powered-By': 'Catbee' })
  .withGlobalPrefix('/api')
  .withRequestId({ headerName: 'X-Request-Id', exposeHeader: true })
  .enableResponseTime({ addHeader: true, logOnComplete: true })
  .build();

const server = new ExpressServer(config, {
  beforeInit: srv => console.log('Initializing server...'),
  beforeRoutes: app => console.log('Setting up routes...'),
  afterRoutes: app => console.log('Routes initialized.'),
  afterInit: srv => console.log('Server initialized'),
  onServerCreated: srv => console.log('HTTP/HTTPS server instance created.'),
  beforeStart: app => console.log('Starting server...'),
  afterStart: srv => console.log('Server started!'),
  beforeStop: srv => console.log('Stopping server...'),
  afterStop: () => console.log('Server stopped.'),
  onRequest: (req, res, next) => {
    console.log('Processing request:', req.method, req.url);
    next();
  },
  onResponse: (req, res, next) => {
    res.setHeader('X-Processed-By', 'ExpressServer');
    next();
  },
  onError: (err, req, res, next) => {
    console.error('Custom error handler:', err);
    res.status(500).json({ error: 'Custom error: ' + err.message });
  }
});

// Register routes
const router = server.createRouter('/users');
router.get('/', (req, res) => res.json({ users: [] }));
router.post('/', (req, res) => res.json({ created: true }));

// Or set a base router for all routes
const baseRouter = Router();
baseRouter.use('/users', router);
server.setBaseRouter(baseRouter);

server.registerHealthCheck('database', async () => await checkDatabaseConnection());
server.useMiddleware(loggingMiddleware, errorMiddleware);

await server.start();
server.enableGracefulShutdown();

---

📚 Modules Overview

Module	Description
Express Server	Fast, secure, and scalable server setup
Array Utilities	Advanced array manipulation
Async Utilities	Promise helpers, concurrency, timing
Cache Utilities	In-memory caching with TTL
Context Store	Per-request context via AsyncLocalStorage
Crypto Utilities	Hashing, encryption, tokens
Date Utilities	Date/time manipulation
Decorators Utilities	TypeScript decorators for Express
Directory Utilities	Directory and file system helpers
Environment Utilities	Env variable management
Exception Utilities	HTTP and error handling
File System Utilities	File operations
HTTP Status Codes	Typed status codes
ID Utilities	UUID and ID generation
Logger Utilities	Structured logging with Pino
Middleware Utilities	Express middleware collection
Object Utilities	Deep merge, flatten, pick/omit, etc.
Performance Utilities	Timing, memoization, memory tracking
Request Utilities	HTTP request parameter parsing/validation
Response Utilities	Standardized API response formatting
Stream Utilities	Stream conversion, batching, throttling, line splitting
String Utilities	Casing, masking, slugifying, formatting
Type Utilities	Type checking, conversion, guards
Types Utilities	Common TypeScript types and interfaces
URL Utilities	URL parsing, query manipulation, normalization
Validate Utilities	Input validation functions

---

🏁 Usage

This library supports flexible import patterns to suit your needs:

Root-level imports (everything available)

Import any utility directly from the root package:

import { chunk, sleep, TTLCache, getLogger, ServerConfigBuilder } from '@catbee/utils';

Module-level imports (scoped imports)

Import only from specific modules for better organization and smaller bundles:

// Import only server-related exports
import { ServerConfigBuilder, ExpressServer } from '@catbee/utils/server';

// Import only date utilities
import { formatDate, addDays, DateBuilder } from '@catbee/utils/date';

// Import only crypto utilities
import { hashPassword, verifyPassword } from '@catbee/utils/crypto';

Both import styles are fully supported and tree-shakable. Use whichever fits your project structure best!

---

📖 Documentation

• Full API Docs & Examples

---

📜 License

MIT © Catbee Technologies (see the LICENSE file for the full text)