ESSENTIA 3.1

Shared TypeScript library for TWS/sera4 microservices. ESM, strict mode, full type declarations.

Requires Node.js ≥ 22.

What's new in 3.1

Breaking changes

• Node.js ≥ 22 required (was ≥ 18 in 3.x)
• TypeScript 6 (up from 5.3) — stricter inference rules may surface new type errors in consuming projects
• All test files are now .ts only and use the *.test.ts convention; the .js test glob has been removed from the test runner

New

• Biome replaces ad-hoc linting — single tool for lint, format, and import sorting (npm run check)
• Husky pre-commit hook — Biome auto-fixes staged files before every commit
• tsconfig.test.json — separate typecheck pass covering both ts/ and test/
• .nvmrc pinned to Node 22

Improvements

• Strict-mode cleanup across all modules — noImplicitAny, unused imports/variables enforced as errors
• All source files use node: protocol for built-in imports (node:fs, node:path, etc.)
• All file names normalised to kebab-case (e.g. dns-cache.ts, cycle-deployment-watcher.test.ts)
• New test suites added for cache, hal, last-commit, paper-trail, safe-proxy, serializer, utils, s4-formatter, s4-pagination — 190 tests total

Setup

npm install
npm run build
npm test

Scripts

| Script | What it does | | ----------------------- | ---------------------------------------------- | | npm run build | Compile TypeScript → dist/ts/ | | npm test | Run all tests (Mocha + Chai, JUnit XML output) | | npm run test:coverage | Tests with c8 coverage HTML report | | npm run typecheck | Type-check without emitting | | npm run lint | Biome lint across ts/ and test/ | | npm run lint:fix | Biome lint with auto-fix | | npm run format | Biome format write pass | | npm run format:check | Biome format check (CI-safe) | | npm run check | Biome lint + format + import sort | | npm run check:fix | check with auto-fix |

Pre-commit hook

Husky runs Biome on staged files:

npx biome check --write --staged --no-errors-on-unmatched

The hook is wired via npm run prepare (runs automatically after npm install).

Modules

All source lives under ts/. Each module exports from its index.ts.

| Module | Export | Description | | ------------------- | ------------------------------------ | --------------------------------------------------------------------------- | | ts/logger | s4logger, S4Logger | Winston logger with trace/debug/info/warn/error levels | | ts/utils | utils | UUID validation, integer array parsing, route type detection, JSONB helpers | | ts/dns | DnsCache | Singleton DNS lookup cache with configurable TTL | | ts/health | HealthCheck | Health check endpoint utilities | | ts/cycle | CycleDeploymentWatcher | Watches Cycle environment file for deployment tag changes | | ts/constants | TWS_ROUTE_TYPES | Shared route type constants | | ts/helpers | helpers, TestServerWrapper | Misc helpers, test HTTP server wrapper | | ts/paginator | sqlPaginator, paginator | SQL and array pagination | | ts/cache | cache, Cache, CacheConfigError | Redis cache wrapper (fakeredis supported for tests) | | ts/prompts | setupCLIParser, cliSleep, etc. | CLI argument parsing and prompt utilities | | ts/safe-proxy | safeProxy | Axios wrapper that forwards auth headers between services | | ts/queue | queue | AMQP publisher/subscriber with fanout support | | ts/last-commit | lastCommit | Read/write git branch + commit hash to a JSON file | | ts/hal | halDecorator | Decorates Sequelize models with HAL-style _links / _resource | | ts/formatter | S4Formatter | Error response formatting | | ts/serializer | serializer | Sequelize model serialization | | ts/paper-trail | paperTrail | Sequelize hook-based audit trail (diff + revision storage) |

Logger environment policy

S4Logger.resolveLogLevel() reads S4_LOG_LEVEL; when it is set to a valid level, that value always wins. When it is unset or invalid, logging defaults to info.

• S4_LOG_LEVEL=debug: emit debug and above
• S4_LOG_LEVEL=info: emit info and above
• unset or invalid: default to info

Usage

import { s4logger, utils, DnsCache, queue, safeProxy } from "@sera4/essentia";

s4logger.configure({ level: "info", service: "my-service", format: "json" });
s4logger.info("Starting");

const isValid = utils.isValidUuidV4("26d61a82-3587-4875-98a8-e950e1bf2350");

const dns = DnsCache.getInstance();
const ip = await dns.resolveTarget("https://example.com");

await queue.openConnection({ connectionUrl: "amqp://localhost" });
await queue.publishMessage("my-exchange", "routing.key", { payload: true });

await safeProxy.post(res.locals, "http://other-service/endpoint", { data: {} });

Testing

Tests run manually — no CI pipeline yet.

npm test                          # all tests
npm run test:coverage             # HTML coverage report in coverage/
npm test -- --grep "DnsCache"     # run a specific suite

Test files live in test/, mirroring the ts/ structure. Files use the .test.ts naming convention.

License

Proprietary. All rights reserved.