assemblerjs 0.9.7 → 1.0.1

package/README.md

@@ -1,96 +1,233 @@
 # assembler.js
 
-A general purpose and zero-dependency [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) library for node and browser.
+A modern, type-safe, and lightweight [Dependency Injection](https://en.wikipedia.org/wiki/Dependency_injection) library for **Node.js and Browsers** 🌐.
+
+> ✨ **Universal Library**: Works seamlessly in Node.js, browsers, and any JavaScript environment that supports ES2020+
 
 ![Statements](https://img.shields.io/badge/statements-91.01%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-79.6%25-red.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-87.62%25-yellow.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-90.76%25-brightgreen.svg?style=flat)
 
+## Performance Metrics
+
+![Assembler Building](https://img.shields.io/badge/assembler%20building-156k%20ops%2Fsec-brightgreen.svg?style=flat)
+![Injectable Resolution](https://img.shields.io/badge/singleton%20cache-1.2M%20ops%2Fsec-brightgreen.svg?style=flat)
+![Event System](https://img.shields.io/badge/event%20emit-432k%20ops%2Fsec-brightgreen.svg?style=flat)
+![Decorators](https://img.shields.io/badge/decorators-890k%20ops%2Fsec-brightgreen.svg?style=flat)
+
+[→ Full Benchmarks](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/performance/benchmarks.md)
+
 ---
 
-`assembler.js` is inspired by both DIOD and Nestjs.
+## Features
 
-`assembler.js` name is a tribute to Gilles Deleuze and Felix Guattari concept of [_Agencement_](<https://fr.wikipedia.org/wiki/Agencement_(philosophie)>) (in french) that can be translated into [Assemblage](<https://en.wikipedia.org/wiki/Assemblage_(philosophy)>).
+- 🎯 **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
+- 🎨 **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)
 
-## Install
+Inspired by [DIOD](https://github.com/artberri/diod) and [NestJS](https://nestjs.com/).
+
+## Installation
+
+Install `assemblerjs` and its peer dependency `reflect-metadata` using npm or yarn:
 
 ```sh
-yarn add assemblerjs
+npm install assemblerjs reflect-metadata
 ```
 
 ```sh
-npm install assemblerjs
+yarn add assemblerjs reflect-metadata
 ```
 
-## Usage
+**Important:** You must import `reflect-metadata` at the entry point of your application:
 
-The main block of `assembler.js` is the **Assemblage**. It is created by decorating classes with the `@Assemblage` decorator. To keep everything type-safe, classes may implement `AbstractAssemblage` abstract class or define their own abstract class that extends it.
-These abstract classes are used as identifiers to inject dependencies.
+```typescript
+import 'reflect-metadata';
+```
 
-## Order of execution
+> ✨ **Works everywhere**: This installation works for **Node.js, browsers (with Vite/Webpack/Rollup), React, Vue, Angular, and any JavaScript environment**.
 
-Dependencies are registered and built recursively from the entry assemblage resolved by `Assembler.build`.
+### Alternative: CDN (for quick prototyping)
 
-##### `onRegister`
+If you want to try assemblerjs without a build step:
 
-Static hook called when registering the assemblage.
-Other dependencies may or may not have been registered at this point, and dependency tree is not built yet.
+```html
+<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>
+```
 
-##### `constructor`
+## Quick Start
 
-Build the instance and requires an instance of each dependency passed to the constructor.
-If the dependency is not a singleton a new instance is returned, meaning the same dependency required in another assemblage will be another object, as when using the `require` method of the `AssemblerContext` passed to hooks or injected by the `@Context` decorator.
+```typescript
+import 'reflect-metadata';
+import { Assemblage, Assembler, AbstractAssemblage } from 'assemblerjs';
 
-##### `onInit`
+// Define a service
+@Assemblage()
+class Logger implements AbstractAssemblage {
+  log(message: string) {
+    console.log(message);
+  }
+}
 
-Called on every dependency when the dependency tree is ready.
-Except for the entry assemblage (i.e. the one built on bootstrap by `Assembler.build`) the hook is called according to the latter.
-The entry point assemblage is called last.
+// Define an application that depends on Logger
+@Assemblage({
+  inject: [[Logger]], // Declare dependencies
+})
+class App implements AbstractAssemblage {
+  constructor(private logger: Logger) {}
 
-##### `onDispose`
+  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](https://github.com/benoitlahoz/assemblerjs/tree/main/docs/assemblerjs)**
+
+### Quick Links
+
+#### Getting Started
+- [Installation](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/getting-started/installation.md)
+- [Quick Start Guide](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/getting-started/quick-start.md)
+- [TypeScript Setup](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/getting-started/typescript-setup.md)
 
-Called when disposing the assembler via the `dispose` method injected by the `@Dispose` decorator.
-This will be called like the `onInit` method, walking through the dependency tree, except for the entry point assemblage, called last.
+#### Core Concepts
+- [Assemblage](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/core-concepts/assemblage.md) - Building blocks
+- [Dependency Injection](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/core-concepts/dependency-injection.md) - DI patterns
+- [Abstraction Pattern](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/core-concepts/abstraction-pattern.md) - Interface-based design
+- [Lifecycle Hooks](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/core-concepts/lifecycle-hooks.md) - Initialization & cleanup
 
-## Events
+#### Decorators
+- [Parameter Decorators](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/decorators/parameter-decorators.md) - Built-in decorators
+- [Custom Parameter Decorators](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/decorators/custom-parameter.md) - Create your own
+- [Custom Class Decorators](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/decorators/custom-class.md) - Type-safe class decorators
 
-`assembler.js` provides an `EventManager` that can be subclassed by any assemblage.
+#### Features
+- [Event System](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/features/events.md) - Event-driven architecture
+- [Tags](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/features/tags.md) - Group assemblages
+- [Singleton vs Transient](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/features/singleton-transient.md) - Instance lifecycle
 
-Because all events **are forwarded by `AssemblerContext`** the `EventManager` is quite strict on which events can be broadcasted and they must be registered explicitly using the `events` property of the `AssemblageDefinition`. To avoid collision between events channels, user is strongly encouraged to create _strong_ channels names, e.g.: `com.domain.app.assemblage-name:init`.
+#### API Reference
+- [Assembler API](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/api/assembler.md) - Container methods
+- [AssemblerContext API](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/api/context.md) - Context interface
+- [Types](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/api/types.md) - TypeScript types
+
+#### Guides
+- [Advanced Examples](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/guides/advanced-examples.md) - Real-world patterns
+- [Tree-Shaking](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/guides/tree-shaking.md) - Bundle optimization
+
+#### Performance
+- [Benchmarks](https://github.com/benoitlahoz/assemblerjs/blob/main/docs/assemblerjs/performance/benchmarks.md) - Performance metrics & best practices
+
+## Tree-Shaking & Bundle Optimization
+
+`assembler.js` is optimized for tree-shaking with modular exports. Import only what you need:
 
 ```typescript
-const prefix = 'com.domain.app.emitter-assemblage';
+// ❌ Large bundle (imports everything)
+import * as Assembler from 'assemblerjs';
 
-export enum EmitterAssemblageEvents {
-  Init = `${prefix}:init`,
-}
+// ✅ Optimal (only imports required modules)
+import { Assemblage, Assembler, AbstractAssemblage } from 'assemblerjs';
+```
 
-@Assemblage({
-  events: Object.values(EmitterAssemblageEvents),
-})
-export class EmitterAssemblage
-  extends EventManager
-  implements AbstractEventAssemblage
-{
-  constructor() {
-    super();
-  }
+### Bundle Size Examples
 
-  public async onInit(): Promise<void> {
-    this.emit(EmitterAssemblageEvents.Init, true);
-  }
-}
+- **Minimal usage** (~5-6 KB): Core DI features only
+- **Medium usage** (~15-18 KB): DI + Events + Parameter decorators
+- **Full library** (~35 KB): All features
 
-@Assemblage()
-export class SubcriberAssemblage implements AbstractAssemblage {
-  constructor(@Context() private context: AssemblerContext) {
-    context.on(EmitterAssemblageEvents.Init, (value: boolean) => {
-      console.log(value); // true.
-    });
-
-    context.on('*', (value: boolean) => {
-      console.log(value); // true.
-    });
+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`:
+
+```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
 
-Assembler.build(SubcriberAssemblage);
+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
+
+```bash
+# 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**