@aialchemy/service-utils

Reusable Node.js helpers for API services:

• Logger — winston factory with optional file transports and Express middleware
• Signing — HMAC-SHA256 request signing and verification
• Redis session — typed JSON session storage on top of redis
• Process manager — single-instance process locking via PID files

ESM + CJS, fully typed, zero side effects on import.

Install

pnpm add @aialchemy/service-utils
# or
npm install @aialchemy/service-utils

The package declares optional peer dependencies. Install only what you use:

pnpm add winston              # for the logger
pnpm add express              # for the Express middleware
pnpm add redis                # for RedisSessionService

Usage

Logger

import { createLogger, createRequestLogger, createErrorLogger } from '@aialchemy/service-utils';
import express from 'express';

const logger = createLogger({
  level: 'info',
  service: 'orders-api',
  version: '1.4.2',
  // file: { dir: 'logs/orders-api' }, // opt-in: file transports
});

const app = express();
app.use(createRequestLogger(logger));
app.use(createErrorLogger(logger));

Signing

import { signRequest, verifySignature, generateBodyHash } from '@aialchemy/service-utils';

const headers = signRequest(process.env.SIGNING_SECRET!, {
  method: 'POST',
  path: '/api/orders',
  body: JSON.stringify({ id: 1 }),
  client: 'orders-portal',
  userId: 'user-123',
});

// On the server:
const ok = verifySignature(
  process.env.SIGNING_SECRET!,
  headers['X-Signature'],
  Number(headers['X-Timestamp']),
  'POST',
  '/api/orders',
  generateBodyHash('{"id":1}'),
);

Redis session

import { RedisSessionService, createLogger } from '@aialchemy/service-utils';

const logger = createLogger({ service: 'orders-api' });
const sessions = new RedisSessionService({ url: process.env.REDIS_URL!, logger });

await sessions.connect();
await sessions.setSession('user:123', { name: 'Ada' }, 3600);
const user = await sessions.getSession<{ name: string }>('user:123');

Process manager

import { initializeProcessManagement } from '@aialchemy/service-utils';

initializeProcessManagement({
  serviceName: 'orders-api',
  lockFilePath: '/tmp/orders-api.lock',
  metadata: { port: 3000 },
});

Development

See CONTRIBUTING.md for setup, scripts, and conventions.

pnpm install
pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build

License

MIT — see LICENSE.