nano-injector 1.0.3 → 1.0.5

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Roman Pukhalskyi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2021 Roman Pukhalskyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,221 +1,240 @@
-# Nano-injector
-
-Miniature dependency injection library for TypeScript and JavaScript.
-
-# Motivation
-
-There is a myriad of dependency injection libraries in typescript ecosystem. Most of them are built around decorators.
-Decorators are an obvious solution for such kinds of tasks. But in terms of dependency injection, they have its
-drawbacks - they are not type safe, which means that theoretically, it is possible to bind any value to the required type,
-and they don't work well with interfaces and primitives, therefore some workaround solutions are required to overcome
-this limitation.
-Typically, injecting of an interface, using these libraries, looks like as follows:
-```typescript
-// binding value
-injector.bind('IStorage').toValue(new DefStorage())
-
-// injecting it
-@Inject('IStorage')
-private storage: IStorage
-```
-where string IStorage should be passed to Inject decorator in order to let the injector know which value should be injected
-to the required property. Since it is just a string, any string can be passed, therefore any type can be injected,
-and the compiler won't warn you about that. Also, there is type duplication, therefore the whole usage looks a bit ugly.
-
-**Nano-injector** is addressing these issues, by doing dependency injection in a little bit different way - instead of using
-decorators, it uses plain functions as dependencies providers. By doing so, the same workflow, using Nano-injector,
-looks as follows:
-
-```typescript
-// defining provider
-const $IStorage = createProvider<IStorage>()
-
-// binding it to the value
-injector.bindProvider($IStorage).toValue(new DefStorage())
-
-// injecting it
-private storage = $IStorage()
-```
-Here _**$IStorage**_ is the provider, which basically is a plain function, and which should be bound to desired value through
-injector. Type of storage property compiler infers automatically, which reduces unneeded code duplication. Also, you can bind only
-value of the type specified during provider creation, if not to do so, the compiler will warn you about that.
-
-Also, unlike other libraries, Nano-injector is very small, with a very concise API.
-More usage details you can find below, and in the example directory.
-
-# Features
-
-- Very simple
-- Ultra lightweight
-- Zero dependencies
-- No decorators
-- Type safe
-- Injectable interfaces and primitives
-
-# Installation
-```bash
-npm i nano-injector
-```
-# Usage
-Importing dependencies:
-```typescript
-import { Injector, createProvider } from 'nano-injector'
-```
-Defining types and providers:
-```typescript
-// to distinguish providers from any other entities $ sign is used
-const $Clock = createProvider<(cb: () => void, time: number) => number>()
-const $ClockRate = createProvider<number>()
-
-const $CPU = createProvider<CPU>()
-interface CPU {
-  readonly model: string
-  readonly numCores: number
-  readonly frequency: number
-}
-
-const $GPU = createProvider<GPU>()
-interface GPU {
-  readonly model: string
-  readonly numRayTracingCores: number
-  readonly memorySize: number
-}
-
-const $RAM = createProvider<RAM>()
-interface RAM {
-  readonly capacity: number
-}
-
-const $Motherboard = createProvider<Motherboard>()
-interface Motherboard {
-  readonly cpu: CPU
-  readonly gpu: GPU
-  readonly ram: RAM
-}
-
-class GeForce911 implements GPU {
-  model = 'GeForce911'
-  numRayTracingCores = 100
-  memorySize = 2048
-}
-
-class DefMotherboard implements Motherboard {
-  constructor(
-    readonly model: string,
-    public cpu = $CPU(),
-    public gpu = $GPU(),
-    public ram = $RAM()
-  ) {}
-}
-
-class PC {
-  constructor(private name: string, private motherboard = $Motherboard()) {}
-}
-```
-Defining injector through which injection occurs:
-```typescript
-const injector = new Injector()
-```
-Binding providers:
-```typescript
-// binding $CPU provider to exact value
-injector.bindProvider($CPU).toValue({ numCores: 4, model: 't7', frequency: 2000 })
-
-// binding $GPU provider to class which conforms to provider's returning type
-// calling asSingleton specifies that value should be created only once
-injector.bindProvider($GPU).toConstructor(GeForce911).asSingleton()
-
-// binding $RAM provider to the factory which creates value conforming to
-// provider's returning type
-injector.bindProvider($RAM).toFactory(() => ({
-  capacity: Math.floor(Math.random() * 1024),
-}))
-
-injector
-  .bindProvider($Motherboard)
-  .toFactory(
-    () =>
-      // only one required parameter is passed, the rest are initialized
-      // automatically through providers
-      new DefMotherboard('Asus ABC-123')
-  )
-  .asSingleton()
-
-// without ignoring compiler would tell you about wrong value's type
-// @ts-expect-error
-injector.bindProvider($ClockRate).toValue('asd')
-
-injector.bindProvider($ClockRate).toValue(1000)
-
-injector.bindProvider($Clock).toValue(setTimeout)
-```
-Creating instances with all dependencies injected:
-```typescript
-// the first parameter of PC constructor is required, so it is passed into the
-// construction method
-injector.createInstance(PC, 'My pc')
-```
-Directly getting the bound to the providers values:
-```typescript
-injector.getValue($CPU)
-injector.getValue($GPU)
-injector.getValue($RAM)
-
-injector.getValue($Clock)(() => console.log('Tick!'), 1000)
-```
-Manually creating instance with all its dependencies:
-```typescript
-new DefMotherboard(
-  'Asus xyz',
-  { frequency: 123, model: 'Intel xyz', numCores: 1 },
-  { model: '', memorySize: 0, numRayTracingCores: 1 },
-  { capacity: 123 },
-)
-```
-Calling function through injector:
-```typescript
-injector.callFunc(() => {
-  // inside function all providers return bound to them values
-  console.log('Inside function')
-  console.log('CPU:', $CPU())
-  console.log('GPU:', $GPU())
-  console.log('RAM:', $RAM())
-})
-```
-It's also possible to bind few providers to the same value. The bound value should conform to
-intersection of all providers' types:
-```typescript
-injector.bindProvider($RAM, $CPU, $GPU).toValue({
-  capacity: 10,
-  frequency: 100,
-  memorySize: 200,
-  model: 'ATB-21',
-  numCores: 2,
-  numRayTracingCores: 60,
-})
-```
-Creating composition of injectors:
-```typescript
-const childInjector = new Injector({ parent: injector })
-```
-Overriding $CPU binding of parent injector inside child injector:
-```typescript
-childInjector.bindProvider($CPU).toValue({ numCores: 1, model: 'z2', frequency: 999 })
-```
-Injecting value to the existing instance:
-```typescript
-const newMotherboard = new class {
-  gpu: GPU
-  cpu: CPU
-}
-injector.injectValues(newMotherboard, { cpu: $CPU, gpu: $GPU })
-```
-# [Docs](https://protoukr.github.io/nano-injector/)
-
-# Contributing
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
-
-Please make sure to update tests as appropriate.
-
-## License
-[MIT](https://choosealicense.com/licenses/mit/)
+# Nano-injector
+
+**Miniature, type-safe dependency injection library for TypeScript and JavaScript.** Zero dependencies. No decorators.
+~1.4KB gzipped.
+
+## Features
+
+- **Type Safe**: leveraged by TypeScript's type inference.
+- **Zero Dependencies**: fast cold starts and small footprint.
+- **No Decorators**: works with plain functions and classes.
+- **Flexible**: supports value, class, and factory bindings.
+- **Hierarchical**: supports parent-child injector relationships.
+- **Circular Dependency Detection**: automatically detects and warns about cycles.
+
+## Motivation
+
+Most dependency injection libraries in the TypeScript ecosystem rely heavily on decorators (e.g., `@Inject`). While
+familiar, this approach has drawbacks:
+
+1.  **Type Safety**: Decorators often use string tokens (e.g., `@Inject('IStorage')`), decoupling the type from the
+    injection token.
+2.  **Complexity**: They don't work natively with interfaces or primitives without workarounds.
+3.  **Verbosity**: requires duplicating type definitions and injection tokens.
+
+**Nano-injector** takes a different approach. It uses **Providers**—plain functions that act as both unique identity
+tokens and accessors. This allows TypeScript to infer types automatically, reducing boilerplate and runtime errors.
+
+## Installation
+
+```bash
+npm install nano-injector
+```
+
+## Core Concepts
+
+- **Provider**: A typed function created via `createProvider<T>()`. It acts as a unique key for the dependency and a way
+  to access it.
+- **Injector**: The container that manages bindings and resolves dependencies.
+- **Binder**: An intermediate object returned when you bind a provider, used to configure _how_ it resolves (to a value,
+  a class, or a factory).
+
+## Usage
+
+### 1. Define Interfaces and Providers
+
+Define your interfaces (or types) and create a corresponding provider for each. By convention, providers often start
+with `$` to distinguish them from values.
+
+```typescript
+import { createProvider } from 'nano-injector';
+
+// Define interfaces
+interface Logger {
+  log(msg: string): void;
+}
+
+interface Config {
+  apiKey: string;
+  port: number;
+}
+
+// Create providers
+export const $Logger = createProvider<Logger>();
+export const $Config = createProvider<Config>();
+```
+
+### 2. Create the Injector
+
+```typescript
+import { Injector } from 'nano-injector';
+
+const injector = new Injector();
+```
+
+### 3. Bind Dependencies
+
+You can bind providers to specific values, classes, or factories.
+
+#### Value Binding
+
+Useful for configuration, primitives, or existing instances.
+
+```typescript
+injector.bindProvider($Config).toValue({
+  apiKey: 'secret-key',
+  port: 8080,
+});
+```
+
+#### Class Binding
+
+Useful for services. You can also make them singletons.
+
+```typescript
+class ConsoleLogger implements Logger {
+  log(msg: string) {
+    console.log(msg);
+  }
+}
+
+// Bind to a class (created on demand)
+injector.bindProvider($Logger).toConstructor(ConsoleLogger);
+
+// Bind as a singleton (created once and reused)
+injector.bindProvider($Logger).toConstructor(ConsoleLogger).asSingleton();
+```
+
+#### Factory Binding
+
+Useful when creation logic is dynamic or depends on other factors.
+
+```typescript
+injector.bindProvider($Logger).toFactory((injector) => {
+  // logic to determine which logger to return
+  return new ConsoleLogger();
+});
+```
+
+### 4. Injection
+
+Nano-injector leverages TypeScript's default parameter values for injection. This makes your code cleaner and testable
+(you can simply pass mocks as arguments in tests).
+
+#### Constructor Injection
+
+Used in classes. Simply assign the provider call as a default value.
+
+```typescript
+class UserService {
+  // Dependencies are automatically resolved when `new` is called by the injector
+  constructor(
+    private logger = $Logger(),
+    private config = $Config(),
+  ) {}
+
+  doWork() {
+    this.logger.log(`Starting work on port ${this.config.port}`);
+  }
+}
+```
+
+To instantiate this class with dependencies resolved:
+
+```typescript
+// The injector resolves arguments automatically
+const userService = injector.createInstance(UserService);
+userService.doWork();
+```
+
+#### Mixing Manual and Injected Parameters
+
+You can mix manual arguments with injected ones. Since injection relies on default parameter values, manual arguments
+usually come first.
+
+```typescript
+class User {
+  constructor(
+    public name: string, // Manual argument
+    private logger = $Logger(), // Injected
+  ) {}
+}
+
+// Pass manual arguments to createInstance
+const user = injector.createInstance(User, 'Alice');
+```
+
+#### Function Injection
+
+You can also use providers inside functions called by the injector.
+
+```typescript
+function startServer() {
+  const config = $Config(); // Resolve dependency
+  console.log(`Server started on ${config.port}`);
+}
+
+// Execute the function within the injection context
+injector.callFunc(startServer);
+```
+
+#### Direct Retrieval
+
+If you need to get a value imperatively:
+
+```typescript
+const config = injector.getValue($Config);
+```
+
+## Advanced Features
+
+### Multi-Binding (Intersection Types)
+
+You can bind multiple providers to a single value that implements all of them.
+
+```typescript
+interface Writer {
+  write(data: string): void;
+}
+interface Reader {
+  read(): string;
+}
+
+const $Writer = createProvider<Writer>();
+const $Reader = createProvider<Reader>();
+
+class FileSystem implements Writer, Reader {
+  write(data: string) {
+    /*...*/
+  }
+  read() {
+    return '';
+  }
+}
+
+// Bind both providers to the same singleton instance
+injector.bindProvider($Writer, $Reader).toConstructor(FileSystem).asSingleton();
+```
+
+### Hierarchical Injectors
+
+Injectors can have parents. If a provider isn't found in the current injector, it looks up the tree.
+
+```typescript
+const parent = new Injector();
+parent.bindProvider($Config).toValue({ apiKey: 'global', port: 80 });
+
+const child = new Injector({ parent });
+
+// Child resolves $Config from parent
+const config = child.getValue($Config);
+```
+
+### Circular Dependencies
+
+The library automatically detects circular dependencies during resolution and throws a specific error to help you debug
+the structure of your application.
+
+## License
+
+MIT