GitHub - codibre/js-utils: High performance tuples for Map/Set indexing

Repo for useful js utilities

Overview

This monorepo has some useful javascript utilities that merge seamlessly with vanilla javascript

🛠️ Development

Prerequisites

Node.js >= 22
pnpm >= 10.12.4
Git

Getting Started

Clone the repository

git clone https://github.com/codibre/js-utils.git
cd js-utils

Install dependencies
Run tests
Build packages

Development Commands

# Build all packages
pnpm build

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:cov

# Lint all packages
pnpm lint

# Auto-fix linting issues
pnpm lint:fix

# Format code
pnpm prettier:fix

# Validate commit messages
pnpm commit:validate

💡 Development Tip: Don't Worry About Formatting While Coding!

Focus on your logic, not formatting while developing. The project has automated tools to handle code style:

# After writing your code, run this to fix all formatting/linting issues:
pnpm lint:fix

This command will automatically:

✅ Fix ESLint rule violations
✅ Format code with Prettier
✅ Organize imports
✅ Remove unused variables
✅ Apply consistent code style

Pre-commit hooks will also run these fixes automatically when you commit, so you can stay in the flow of coding without interruption!

Code Quality Standards

TypeScript

Strict TypeScript configuration
Comprehensive type definitions
TSDoc documentation for all public APIs

Testing

Unit Tests: All business logic and utilities
Integration Tests: Real HTTP request testing with spies
Coverage: Maintained above 80%
Test Structure: Descriptive names, success/error scenarios

Commit Convention

We use Conventional Commits:

# Examples
feat(newrelic): add support for HTTP/2 instrumentation
fix(events): resolve memory leak in event emitter
docs(readme): update installation instructions
test(guard): add integration tests for transaction context

Commit Types:

feat: New features
fix: Bug fixes
docs: Documentation changes
test: Test additions or modifications
refactor: Code refactoring
perf: Performance improvements
chore: Build process or auxiliary tool changes

🚀 CI/CD & Publishing

Automated Publishing

The monorepo uses intelligent change detection to automatically:

Detect Changed Packages: Only builds and tests packages that have changes
Semantic Versioning: Automatically bumps versions based on conventional commits
Automated Publishing: Publishes to npm registry when changes are merged to main
Release Notes: Generates changelogs from commit messages

GitHub Actions Workflow

# Automatically triggers on:
# - Pull requests (run tests)
# - Push to main (run tests + publish if needed)
# - Manual dispatch (force publish)

Pipeline Steps:

Setup: Node.js, pnpm, dependencies
Build: Compile TypeScript, generate types
Test: Unit tests, integration tests, coverage
Lint: Code style and formatting checks
Publish: Automatic npm publishing for changed packages

Release Process

Releases are fully automated:

Commit Changes: Using conventional commit format
Create PR: CI runs all tests and checks
Merge to Main: Automatic version bump and publishing
Monitor: Check npm and GitHub releases

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork & Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/your-username/js-utils.git
cd js-utils

2. Create Feature Branch

git checkout -b feat/your-feature-name

3. Development Workflow

# Install dependencies
pnpm install

# Make your changes
# Add tests for new functionality
# Update documentation

# Validate your changes
pnpm build
pnpm test
pnpm lint

4. Commit & Push

# Use conventional commit format
git add .
git commit -m "feat(scope): description of your changes"
git push origin feat/your-feature-name

5. Create Pull Request

Provide clear description of changes
Link any related issues
Ensure all CI checks pass

Pull Request Checklist

Code follows style guidelines
Tests pass locally
New functionality has tests
Documentation is updated
Commit messages follow conventional format
No breaking changes (or properly documented)

📋 Adding New Features

For New Instrumentation Types

Identify Use Case: What isn't covered by existing instrumentation?
Design Solution: Integration with existing components vs. new components
Implement with Tests: Comprehensive unit and integration tests
Documentation: Update README, add examples, document APIs

For Bug Fixes

Reproduce Issue: Create test demonstrating the bug
Fix Minimally: Smallest change to resolve the issue
Test Thoroughly: Verify fix + full test suite + edge cases

🔧 Package Development

Adding a New Package

Create Package Directory

mkdir libs/your-new-package
cd libs/your-new-package

Package Configuration

# Create package.json with proper workspace config
# Add to pnpm-workspace.yaml
# Configure turbo.json for build pipeline

Development Setup

# Add scripts in turbo.json
# Configure Jest for testing
# Set up TypeScript configuration

Testing Integration

Use --runInBand for consistent test execution
Mock external dependencies (New Relic, databases, etc.)
Test both success and error scenarios
Maintain high coverage (>80%)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Support

Documentation: Check package-specific READMEs in libs/
Issues: GitHub Issues
Discussions: GitHub Discussions

🚀 Why Choose This Library?

Production Ready

✅ Battle-tested in high-traffic production environments
✅ Comprehensive testing with >90% coverage
✅ Performance optimized with minimal overhead
✅ Error resilient with graceful degradation

Developer Experience

✅ TypeScript first with complete type definitions
✅ Easy integration with minimal configuration
✅ Extensive documentation with real-world examples
✅ Active maintenance with regular updates

Enterprise Features

✅ Distributed tracing across microservices
✅ Custom transaction naming for better monitoring
✅ Event-driven architecture for real-time insights
✅ Background job instrumentation for complete visibility

Built with ❤️ by Codibre