@togatherlabs/shared-utils

Shared utilities library for Togather services, providing production-grade utilities including logger, validators, and common helpers.

Togather Shared Utilities

A collection of shared utilities and helpers for Togather services. This library provides production-ready, reusable components to maintain consistency across the infrastructure.

Installation

pnpm add @togatherlabs/shared-utils

Available Modules

Logger

Production-ready structured logging built on Pino. Features include automatic sensitive data redaction, environment-aware formatting (pretty logs in development, JSON in production), and full configurability.

import { Logger, type LoggerConfig } from '@togatherlabs/shared-utils/logger';

// Minimal - uses defaults
const logger = new Logger();

// With environment config from service (recommended)
const logger = new Logger(undefined, {
  nodeEnv: process.env.NODE_ENV,
  logLevel: process.env.LOG_LEVEL,
  serviceName: process.env.SERVICE_NAME
});

logger.info({ label: 'app' }, 'Application started');
logger.error({ err, label: 'database' }, 'Connection failed');

Full documentation: Logger README

Usage

Basic Import

// Import from main entry point
import { Logger, ILogger, type LoggerConfig } from '@togatherlabs/shared-utils';

// Or import from specific module
import { Logger, ILogger, type LoggerConfig } from '@togatherlabs/shared-utils/logger';

Configuration

Services pass environment variables via LoggerConfig:

import { Logger, type LoggerConfig } from '@togatherlabs/shared-utils/logger';

const config: LoggerConfig = {
  nodeEnv: process.env.NODE_ENV,
  logLevel: process.env.LOG_LEVEL,
  serviceName: process.env.SERVICE_NAME
};

const logger = new Logger(undefined, config);

LoggerConfig fields:

• nodeEnv - Environment: 'development' (pretty logs) or 'production' (JSON logs)
• logLevel - Log level (default: 'info')
• serviceName - Service name for context
• hostname - Hostname override (optional)

See the Logger README for detailed configuration options.

With Dependency Injection

import { injectable, inject } from 'inversify';
import type { ILogger } from '@togatherlabs/shared-utils/logger';

@injectable()
class UserService {
  constructor(
    @inject(TYPES.Logger) private logger: ILogger
  ) {}

  async createUser(data: CreateUserDTO) {
    this.logger.info({ userId: data.id, label: 'UserService' }, 'Creating user');
    // ... implementation
  }
}

Development

Setup

# Install dependencies
pnpm install

# Build the library
pnpm run build

# Run type checking
pnpm run typecheck

# Run linting
pnpm run lint

# Format code
pnpm run format

Project Structure

togather-shared-utils/
├── src/
│   ├── logger/              # Logger module
│   │   ├── ILogger.ts       # Logger interface
│   │   ├── logger.ts        # Logger implementation
│   │   ├── index.ts         # Module exports
│   │   └── README.md        # Logger documentation
│   └── index.ts             # Main library exports
├── dist/                    # Compiled output (generated)
├── scripts/                 # Publishing scripts
│   ├── publish.js           # NPM publishing script
│   └── version.js           # Version bumping script
├── package.json
├── tsconfig.json
├── biome.json
└── README.md

Publishing

Version Bumping

# Bump patch version (1.0.0 -> 1.0.1) for bug fixes
pnpm run version:patch

# Bump minor version (1.0.0 -> 1.1.0) for new features
pnpm run version:minor

# Bump major version (1.0.0 -> 2.0.0) for breaking changes
pnpm run version:major

Publishing to NPM

# Dry run (test publishing without actually publishing)
pnpm run publish:npm -- --dry-run

# Publish to npm with 'latest' tag
pnpm run publish:npm

# Publish with a specific tag (e.g., beta)
pnpm run publish:npm -- --tag beta

The publish script automatically:

• ✅ Checks git status
• ✅ Runs type checking
• ✅ Runs linting
• ✅ Builds the package
• ✅ Checks if version already exists
• ✅ Publishes to npm
• ✅ Creates and pushes git tag

Workflow

Adding a New Feature

1. Create a new branch

   git checkout -b feat/new-utility

2. Make your changes and commit

   git add .
   pnpm run commit  # Uses commitizen for conventional commits

3. Bump version

   pnpm run version:minor  # or patch/major

4. Push changes

   git push origin feat/new-utility
   git push --tags

5. Publish to npm

   pnpm run publish:npm

Commit Convention

This project uses Conventional Commits:

<type>(<scope>): <subject>

<body>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Example:

feat(logger): Add support for custom log formatters

Added a new option to Logger constructor that allows users to
provide custom formatters for log messages. This enables better
integration with external logging services.

Use pnpm run commit for an interactive commit prompt.

Testing

# Run tests (when available)
pnpm test

# Run tests with coverage
pnpm test:coverage

Documentation

• Logger Documentation

Contributing

1. Follow the commit convention
2. Write tests for new features
3. Update documentation
4. Ensure all checks pass before publishing

License

Internal use only - Togather Infrastructure

Support

For questions or issues, contact the platform team.

Related Packages

• @togatherlabs/shared-protos - Shared Protocol Buffers
• @togatherlabs/event-sdk - Event handling SDK