assemblerjs

assembler.js

A modern, type-safe, and lightweight Dependency Injection library for Node.js and Browsers 🌐.

✨ Universal Library: Works seamlessly in Node.js, browsers, and any JavaScript environment that supports ES2020+

Performance Metrics

→ Full Benchmarks

Features

• 🎯 Minimal Dependencies - Only requires reflect-metadata
• 🔒 Type-Safe - Full TypeScript support with generics
• 🌳 Tree-Shakable - Optimized bundle size (~5-6 KB for minimal usage)
• ♻️ Lifecycle Hooks - onRegister, onInit, onDispose
• 📡 Built-in Event System - Integrated EventManager
• 🔀 AOP/Transversals - Cross-cutting concerns (logging, security, caching, performance)
  • 🎯 Caller Tracking - Audit logging, authorization, and request tracing with full caller context
• 🎨 Custom Decorators - Easy creation with ParameterDecoratorFactory and createConstructorDecorator
• 🔧 Flexible Configuration - Runtime configuration override
• 🏷️ Tags Support - Group and retrieve dependencies by tags
• 🌐 Universal - Works in Node.js AND Browsers - No platform-specific dependencies
• 🔄 Singleton & Transient - Control instance lifecycle
• 📦 Small Bundle Size - Perfect for frontend applications (~5-6 KB minified)

Inspired by DIOD and NestJS.

Installation

Install assemblerjs and its peer dependency reflect-metadata using npm or yarn:

npm install assemblerjs reflect-metadata

yarn add assemblerjs reflect-metadata

Important: You must import reflect-metadata at the entry point of your application:

import 'reflect-metadata';

✨ Works everywhere: This installation works for Node.js, browsers (with Vite/Webpack/Rollup), React, Vue, Angular, and any JavaScript environment.

Alternative: CDN (for quick prototyping)

If you want to try assemblerjs without a build step:

<script src="https://unpkg.com/reflect-metadata@latest/Reflect.js"></script>
<script type="module">
  import { Assemblage, Assembler } from 'https://unpkg.com/assemblerjs@latest/dist/index.js';
  // Your code here
</script>

Quick Start

import 'reflect-metadata';
import { Assemblage, Assembler, AbstractAssemblage } from 'assemblerjs';

// Define a service
@Assemblage()
class Logger implements AbstractAssemblage {
  log(message: string) {
    console.log(message);
  }
}

// Define an application that depends on Logger
@Assemblage({
  provide: [[Logger]], // Declare dependencies
})
class App implements AbstractAssemblage {
  constructor(private logger: Logger) {}

  start() {
    this.logger.log('App started!');
  }
}

// Bootstrap the application
const app = Assembler.build(App);
app.start(); // Output: "App started!"

📚 Documentation

Comprehensive documentation is available at:

→ Full Documentation

Quick Links

Getting Started

• Installation
• Quick Start Guide
• TypeScript Setup

Core Concepts

• Assemblage - Building blocks
• Dependency Injection - DI patterns
• Abstraction Pattern - Interface-based design
• Lifecycle Hooks - Initialization & cleanup
• Transversals (AOP) - Aspect-Oriented Programming

Decorators

• Parameter Decorators - Built-in decorators
• Custom Parameter Decorators - Create your own
• Custom Class Decorators - Type-safe class decorators
• AOP Decorators - @Transversal, @Before, @After, @Around, @Affect

Features

• Event System - Event-driven architecture
• Tags - Group assemblages
• Singleton vs Transient - Instance lifecycle

API Reference

• Assembler API - Container methods
• AssemblerContext API - Context interface
• Types - TypeScript types

Guides

• Advanced Examples - Real-world patterns
• Tree-Shaking - Bundle optimization

Performance

• Benchmarks - Performance metrics & best practices

Tree-Shaking & Bundle Optimization

assembler.js is optimized for tree-shaking with modular exports. Import only what you need:

// ❌ Large bundle (imports everything)
import * as Assembler from 'assemblerjs';

// ✅ Optimal (only imports required modules)
import { Assemblage, Assembler, AbstractAssemblage } from 'assemblerjs';

Bundle Size Examples

• Minimal usage (~5-6 KB): Core DI features only
• Medium usage (~15-18 KB): DI + Events + Parameter decorators
• Full library (~35 KB): All features

The package uses:

• ✅ "sideEffects": false - Safe to remove unused modules
• ✅ Modular exports - Each feature in separate files
• ✅ ESM format - Native tree-shaking support

TypeScript Configuration

Enable decorators and reflection in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"]
  }
}

Requirements

• Node.js: ≥ 18.12.0
• TypeScript: ≥ 5.0 (with decorator support)
• reflect-metadata: Required for dependency injection

For Contributors

Architecture

This package is part of the assemblerjs monorepo and depends on:

• @assemblerjs/core - Internal utilities package providing:
  • Type utilities and helpers
  • Collection management utilities
  • Error handling utilities
  • Conditional utilities
  • Array manipulation helpers

This dependency is automatically installed with assemblerjs and transparent to end users.

Development

# Install dependencies from workspace root
yarn install

# Build the package
npx nx build assemblerjs

# Run tests
npx nx test assemblerjs

Monorepo Structure

assemblerjs/
├── packages/
│   ├── assemblerjs/       # Main DI library (this package)
│   ├── core/              # Internal utilities
│   ├── dto/               # DTO utilities
│   ├── electron/          # Electron integration
│   ├── fetch/             # Fetch utilities
│   ├── mongo/             # MongoDB integration
│   └── rest/              # REST utilities

License

MIT

Made with ❤️ in Marseille