https://github.com/libreworks/container
A simple dependency injection container and event target
https://github.com/libreworks/container
dependency-injection eventtarget service-locator
Last synced: 9 months ago
JSON representation
A simple dependency injection container and event target
- Host: GitHub
- URL: https://github.com/libreworks/container
- Owner: libreworks
- License: mit
- Created: 2023-09-03T21:28:43.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-21T01:10:26.000Z (about 1 year ago)
- Last Synced: 2025-08-30T01:45:17.036Z (10 months ago)
- Topics: dependency-injection, eventtarget, service-locator
- Language: TypeScript
- Homepage: https://libreworks.github.io/container/
- Size: 787 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @libreworks/container
[](https://github.com/libreworks/container/blob/main/LICENSE)
[](https://www.npmjs.com/package/@libreworks/container)
[](https://github.com/libreworks/container/actions/workflows/release.yml)
[](https://github.com/libreworks/container/releases)
[](https://codecov.io/gh/libreworks/container)
A simple asynchronous dependency injection container and event target.
## Installation
```shell
npm install @libreworks/container
```
This library conforms to ECMAScript Modules (ESM). You can import this module using ESM or TypeScript syntax.
```TypeScript
import { Builder, Container, Producer } from "@libreworks/container";
```
If you're using CommonJS, you must use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) instead.
## Usage
You can use this library to create a graph of objects with intertwined dependencies. These objects and values can even be produced asynchronously.
### Container
A container provides named values.
```typescript
import { Foobar } from "your-package-name-here";
// Assume we created a Container.
declare const container: Container;
// Retrieve a value by its name.
const myObject: Foobar = await container.get("MyObject");
// Retrieve multiple values by their names.
const allObjects: Foobar[] = await container.getAll(["MyObject", "Another"]);
// Retrieve values by tag.
const taggedByMe: Foobar[] = await container.getAllTagged("my-tag");
```
#### Events
The `Container` class extends the `EventTarget` class ([see MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)).
### Builder
In order to put together a `Container`, you can use the `Builder` class.
```typescript
const builder = new Builder()
// Register a constant
.constant("ExampleValue", "Lorem ipsum dolor sit amet")
// Register an array.
.constant("my.numbers", [1, 2, 3, 5, 8, 13, 21])
// Register an object created synchronously.
.register("RandomName", () => AnotherClass.doSomething())
// Register an object created asynchronously.
.register(
"an-async-value",
async (c) => {
const myNumbers = await c.get("my.numbers");
return await createNewThingy(myNumbers);
},
["my-tag", "AnotherTag", "Yet another"]
);
const container = await builder.build();
// Use the get method's generic type if you prefer.
const anAsyncValue = await container.get("an-async-value");
```
You provide a name and a "factory" function when you call the `register` method. The factory function needs to return the value you want to register; it can be asynchronous or return a `Promise` as well.
Once the container is built, a call to `get` using the same name will invoke the factory function. The container provides itself as the first argument. That way, you can recursively locate other dependencies immediately before constructing the return value.
Since the container is an `EventTarget`, the factory function could broadcast an event, or the value returned by the factory function can register itself as an event listener. This feature allows objects inside the container to communicate in a loosely-coupled way.
The factory function will only ever be invoked once, no matter how many times `get` is invoked.
#### Eager Creation
Normally, values are lazy-loaded; they are created on-demand. However, you can provide the `@eager` tag when you call the `register` method to ensure your objects initialize themselves when the container is created.
```typescript
const builder = new Builder().register("FooBar", () => new Thingy(), [
"@eager",
]);
const container = await builder.build();
// Thingy has already been instantiated.
```