hzd-lib-base

Lightweight collection of infrastructure helpers and small utilities used by Hillz backend services. This repository centralizes common integrations (env, logging, database, queue clients, storage, and gRPC helpers) so service projects can import stable, well-documented building blocks.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Modules
  • Env
  • Logger
  • Database
  • Kafka
  • RabbitMQ
  • Redis
  • S3
  • HTTP Error
  • gRPC tools
• Examples
• Tests

Overview

hzd-lib-base provides TypeScript utilities for common backend needs: environment configuration, structured logging, database connections, message brokers (Kafka/RabbitMQ), cache (Redis), S3 helpers, standard HTTP error construction, and helpers to generate/run gRPC servers and clients.

The code lives in the src folder and exports a small, focused API from the module entrypoints under src/lib.

Features

• Centralized environment configuration helpers
• Opinionated structured logger integration
• Database connection helpers (common DB patterns)
• Kafka and RabbitMQ adapters for producers/consumers
• Redis client helpers
• S3 helper utilities
• Lightweight HTTP error helpers
• gRPC helpers: load proto, generate, client and server helpers, CLI tooling

Installation

Install dependencies and build (project uses Bun by default in dev, but works with Node):

bun install
# or with npm/yarn
npm install
# build / compile (if needed)
bun build

Run tests:

bun test
# or
npm test

Quick Start

Import the helpers you need from your project. Example TypeScript usage (adjust paths according to your packaging or monorepo layout):

import { loadEnv } from './src/lib/env'
import { createLogger } from './src/lib/logger'

const env = loadEnv()
const logger = createLogger({ level: env.LOG_LEVEL })

logger.info('Service starting', { env: env.NODE_ENV })

Modules

Brief descriptions and usage for the main modules in src/lib.

• Env (src/lib/env.ts)

  • Purpose: load environment variables, validate configuration, and provide typed accessors.
  • Usage: const env = loadEnv(); access properties like env.PORT, env.DATABASE_URL, env.LOG_LEVEL.

• Logger (src/lib/logger.ts)

  • Purpose: structured, leveled logger used across services.
  • Usage: const logger = createLogger({ level: env.LOG_LEVEL }); methods: logger.info(), logger.warn(), logger.error().

• Database (src/lib/database.ts)

  • Purpose: helpers for connecting to SQL databases (connection setup, pooling, helpers for migrations or query execution patterns).
  • Usage: const db = createDatabaseClient(env.DATABASE_URL); await db.query(...).

• Kafka (src/lib/kafka.ts)

  • Purpose: lightweight producer/consumer helpers and common configuration patterns.
  • Usage: const producer = createProducer({ brokers }); producer.send(...).

• RabbitMQ (src/lib/rabbitmq.ts)

  • Purpose: utilities for connecting, publishing, and consuming RabbitMQ queues.
  • Usage: const conn = await connectRabbit(url); await conn.publish(queue, message).

• Redis (src/lib/redis.ts)

  • Purpose: helper wrapper around Redis connections and common ops (caching, locks, pub/sub patterns).
  • Usage: const cache = createRedisClient(env.REDIS_URL); await cache.get(key).

• S3 (src/lib/s3.ts)

  • Purpose: helpers for uploading, signing, and downloading objects from S3-compatible stores.
  • Usage: const s3 = createS3Client({ region, credentials }); await s3.upload({ Bucket, Key, Body }).

• HTTP Error (src/lib/http-error.ts)

  • Purpose: small utilities for constructing consistent HTTP error responses and types.
  • Usage: throw new HttpError(404, 'Not Found') or httpError(400, 'Bad request').

• gRPC Tools (src/lib/grpc/*)

  • Purpose: helpers to load proto files, generate TS clients/servers, and small CLI helpers.
  • Files: cli.ts, create-client.ts, create-server.ts, generate.ts, load-proto.ts, plus index.ts.
  • Usage examples:

// create-client.ts usage (example)
import { createGrpcClient } from './src/lib/grpc/create-client'
const client = createGrpcClient(protoPath, 'ServiceName', { url: 'localhost:50051' })

// create-server.ts usage (example)
import { createGrpcServer } from './src/lib/grpc/create-server'
const server = createGrpcServer({ implementations, interceptors })
server.bindAsync('0.0.0.0:50051')

Examples

1. Basic logger + env:

import { loadEnv } from './src/lib/env'
import { createLogger } from './src/lib/logger'

const env = loadEnv()
const logger = createLogger({ service: 'my-service', level: env.LOG_LEVEL })

logger.info('ready')

2. Starting a gRPC server (very small outline):

import { loadProto } from './src/lib/grpc/load-proto'
import { createGrpcServer } from './src/lib/grpc/create-server'

const proto = loadProto('./src/lib/grpc/fixtures/echo.proto')
const server = createGrpcServer({ proto, implementations: { Echo: { echo: (call, cb) => cb(null, { message: call.request.message }) } } })
server.bindAsync('0.0.0.0:50051')

Tests

Tests live under src/__tests__. Run the test suite with bun test or npm test depending on your environment. Tests include unit checks for environment loading, GRPC helpers, message-broker clients, and logger behavior.