{"id":13683713,"url":"https://github.com/owja/ioc","last_synced_at":"2025-04-12T19:42:36.913Z","repository":{"id":34896173,"uuid":"187373608","full_name":"owja/ioc","owner":"owja","description":":unicorn: lightweight (\u003c1kb) inversion of control javascript library for dependency injection written in typescript","archived":false,"fork":false,"pushed_at":"2024-09-03T19:51:54.000Z","size":1242,"stargazers_count":296,"open_issues_count":6,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-03T21:13:46.632Z","etag":null,"topics":["decorators","dependency-injection","dependency-inversion","inversion-of-control","ioc","ioc-container","javascript","lightweight","services","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/owja.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-18T15:21:59.000Z","updated_at":"2025-03-14T00:46:48.000Z","dependencies_parsed_at":"2024-01-14T17:17:32.889Z","dependency_job_id":"0d40057c-bdae-43d9-bfae-f4af0db99081","html_url":"https://github.com/owja/ioc","commit_stats":{"total_commits":178,"total_committers":7,"mean_commits":"25.428571428571427","dds":0.6460674157303371,"last_synced_commit":"0abe90c02e52a9d7f0aa04afd52f7cf8a992e78e"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owja%2Fioc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owja%2Fioc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owja%2Fioc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owja%2Fioc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owja","download_url":"https://codeload.github.com/owja/ioc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281418,"owners_count":21077423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decorators","dependency-injection","dependency-inversion","inversion-of-control","ioc","ioc-container","javascript","lightweight","services","typescript"],"created_at":"2024-08-02T13:02:25.597Z","updated_at":"2025-04-12T19:42:36.889Z","avatar_url":"https://github.com/owja.png","language":"TypeScript","readme":"# @owja/ioc\n\n[![npm version](https://img.shields.io/npm/v/@owja/ioc/latest)](https://badge.fury.io/js/%40owja%2Fioc)\n[![npm version](https://img.shields.io/npm/v/@owja/ioc/next)](https://badge.fury.io/js/%40owja%2Fioc)\n[![size](https://img.badgesize.io/https://unpkg.com/@owja/ioc/dist/ioc.js.svg?compression=brotli\u0026label=size\u0026v=1)](https://unpkg.com/@owja/ioc/dist/ioc.js)\n[![CircleCI](https://dl.circleci.com/status-badge/img/gh/owja/ioc/tree/master.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/owja/ioc/tree/master)\n![npm](https://img.shields.io/npm/dm/@owja/ioc)\n\nThis library implements dependency injection for javascript and typescript.\n\n## Features\n\n* Similar syntax to InversifyJS\n* Can be used without decorators\n* Less Features but **straight forward**\n* Can bind dependencies as **classes**, **factories** and **static values** and provide dependencie arguments or parameters if needed\n* Supports binding in **singleton scope**\n* **Cached** - Resolves only once in each dependent class by default\n* **Cache can switched off** directly at the inject decorator\n* Made with **unit testing** in mind\n* Supports dependency **rebinding** and container **snapshots** and **restores**\n* **Lightweight** - Below 1kb brotli/gzip compressed\n* Does **NOT** need reflect-metadata which size is around 50 kb\n* 100% written in **Typescript**\n\n## Install\n\n```bash\nnpm install --save-dev @owja/ioc\n```\n\nLatest preview/dev version (alpha or beta)\n\n```bash\nnpm install --save-dev @owja/ioc@next\n```\n\n## The Container API\n\n### Creating a container\n\nThe container is the place where all dependencies get bound to. It is possible to have\nmultiple container in our project in parallel.\n\n```ts\nimport {Container} from \"@owja/ioc\";\nconst container = new Container();\n```\n\n### Binding\n\n#### Binding a class\n\nThis is the default way to bind a dependency. The class will get instantiated when the\ndependency gets resolved. You will be able to pass down it's dependencie arguments once you resolve it.\n\n\n```ts\ncontainer.bind\u003cServiceInterface\u003e(symbol).to(Service);\n```\n\n#### Binding a class in singleton scope\n\nThis will create only one instance of `Service`\n\n```ts\ncontainer.bind\u003cServiceInterface\u003e(symbol).to(Service).inSingletonScope();\n```\n\n#### Binding a factory\n\nFactories are functions which will get called when the dependency gets resolved \n\n```ts\ncontainer.bind\u003cServiceInterface\u003e(symbol).toFactory(() =\u003e new Service());\ncontainer.bind\u003cstring\u003e(symbol).toFactory(() =\u003e \"just a string\");\ncontainer.bind\u003cstring\u003e(symbol).toFactory((a: string) =\u003e `I need a string parameter: ${a}`);\n```\n\nA factory can configured for singleton scope too. This way will only executed once.\n\n```ts\ncontainer.bind\u003cServiceInterface\u003e(symbol).toFactory(() =\u003e new Service()).inSingletonScope();\n```\n\n#### Binding a value\n\nThis is always like singleton scope, but it should be avoid to instantiate\ndependencies here. If they are circular dependencies, they will fail. \n\n```ts\ncontainer.bind\u003cServiceInterface\u003e(symbol).toValue(new Service()); // Bad, should be avoid\ncontainer.bind\u003cstring\u003e(symbol).toValue(\"just a string\");\ncontainer.bind\u003c() =\u003e string\u003e(symbol).toValue(() =\u003e \"i am a function\");\n```\n\n### Rebinding\n\nThis is the way how we can rebind a dependency while **unit tests**. We should not need to\nrebind in production code.\n\n```ts\ncontainer.rebind\u003cServiceMock\u003e(symbol).toValue(new ServiceMock());\n```\n\n### Removing\n\nNormally this function is not used in production code. This will remove the\ndependency from the container. \n\n```ts\ncontainer.remove(symbol);\n```\n\n### Getting a dependency\n\nGetting dependencies without `@inject` decorators trough `container.get()` is only meant for **unit tests**. \nThis is also the internal way how the `@inject` decorator and the functions `wire()` and `resolve()` are getting the\ndependency.\n \n```ts\ncontainer.get\u003cInterface\u003e(symbol);\n```\n\nTo get a dependency without `@inject` decorator in production code use `wire()` or `resolve()`. Using `container.get()`\ndirectly to getting dependencies can result in infinite loops with circular dependencies when called inside of\nconstructors. In addition `container.get()` does not respect the cache. \n\n\u003e **Important Note:**  You should avoid accessing the dependencies from any constructor. With circular dependencies\n\u003e this can result in a infinite loop.\n\n### Snapshot \u0026 Restore\n\nThis creates a snapshot of the bound dependencies. After this we can rebind dependencies\nand can restore it back to its old state after we made some **unit tests**.\n\n```ts\ncontainer.snapshot();\n```\n```ts\ncontainer.restore();\n```\n\n## The `inject` Decorator\n\nTo use the decorator you have to set `experimentalDecorators` to `true`\nin your `tsconfig.json`.\n\nFirst we have to create a `inject` decorator for each container: \n\n```ts\nimport {createDecorator} from \"@owja/ioc\";\nexport const inject = createDecorator(container);\n```\n\nThen we can use the decorator to inject the dependency.\n\n```ts\nclass Example {\n    @inject(symbol/*, [tags], ...dependencie arguments*/)\n    readonly service!: Interface;\n    \n    method() {\n        this.service.doSomething();\n    }\n}\n```\n\n## The `wire()` Function\n\nIf we do not want to use decorators, we can use the wire function. It does the same like the `inject`\ndecorator and we have to create the function first like we do with `inject`.\n\n```ts\nimport {createWire} from \"@owja/ioc\";\nexport const wire = createWire(container);\n```\n\nThen we can wire up the dependent to the dependency.\n\n```ts\nclass Example {\n    readonly service!: Interface;\n    \n    constructor() {\n        wire(this, \"service\", symbol/*, [tags], ...dependencie arguments*/);\n    }\n    \n    method() {\n        this.service.doSomething();\n    }\n}\n```\n\n\u003e Notice: With `wire()` the property, in this case `service`, has to be public. \n\n## The `resolve()` Function\n\nA second way to resolve a dependency without decorators is to use `resolve()`.\nTo use `resolve()` we have to create the function first.\n\n```ts\nimport {createResolve} from \"@owja/ioc\";\nexport const resolve = createResolve(container);\n```\n\nThen we can resolve the dependency in classes and even functions.\n\n```ts\nclass Example {\n    private readonly service = resolve\u003cInterface\u003e(symbol);\n    \n    method() {\n        this.service(/*...dependencie arguments*/).doSomething();\n    }\n}\n```\n\n```ts\nfunction Example() {\n    const service = resolve\u003cInterface\u003e(symbol);\n    service(/*...dependencie arguments*/).doSomething();\n}\n```\n\n\u003e Notice: We access the dependency trough a function.\n\u003e The dependency is not assigned directly to the property/constant.\n\u003e If we want direct access we can use `container.get()` but we should avoid\n\u003e using `get()` inside of classes because we then loose the lazy dependency\n\u003e resolving/injection behavior and caching.\n\n## The `symbol`\n\nSymbols are used to identify our dependencies. A good practice is to keep them in one place.\n\n```ts\nexport const TYPE = {\n    \"Service\" = Symbol(\"Service\"),\n    // [...]\n}\n```\n\nSymbols can be defined with `Symbol.for()` too. This way they are not unique.\nRemember `Symbol('foo') === Symbol('foo')` is `false` but\n`Symbol.for('foo') === Symbol.for('foo')` is `true`\n\n```ts\nexport const TYPE = {\n    \"Service\" = Symbol.for(\"Service\"),\n    // [...]\n}\n```\n\n\u003e Since 1.0.0-beta.3 we use the symbol itself for indexing the dependencies.\n\u003e Prior to this version we indexed the dependencies by the string of the symbol.\n\n## :new: Type-Safe Token (new in 2.0)\n\nWith version 2 we added the possibility to use a type-safe way to identify our dependencies. This is done with tokens:\n\n```ts\nexport TYPE = {\n    \"Service\" = token\u003cMyServiceInterface\u003e(\"Service\"),\n    // [...]\n}\n```\n\nIn this case the type `MyServiceInterface` is inherited when using `container.get(TYPE.Service)`, `resolve(TYPE.Service)`\nand `wire(this, \"service\", TYPE.Service)`and does not need to be explicitly added. In case of the decorator `@inject(TYPE.Service)` it needs to be added\nbut it throws a type error if the types don't match:\n\n```ts\nclass Example {\n    @inject(TYPE.Service/*, [tags], ...dependencie arguments*/) // throws a type error because WrongInterface is not compatible with MyServiceInterface\n    readonly service!: WrongInterface;\n}\n```\n\nCorrekt:\n\n```ts\nclass Example {\n    @inject(TYPE.Service/*, [tags], ...dependencie arguments*/)\n    readonly service!: MyServiceInterface;\n}\n```\n\n## :new: Plugins (new in 2.0)\n\nPlugins are a way to hook into the dependency resolving process and execute code which can\naccess the dependency and also the dependent object.\n\nA plugin can add directly to a dependency or to the container. \n\n```ts\ncontainer.bind(symbol).to(MyService).withPlugin(plugin);\n```\n\n```ts\ncontainer.addPlugin(plugin);\n```\n\nThe plugin is a simple function which has access to the dependency, the target (the instance which requires the dependency),\nthe arguments which are passed, the token or symbol which represents the dependency and the container.\n\n```ts\ntype Plugin\u003cDependency = unknown\u003e = (\n    dependency: Dependency,\n    target: unknown,\n    args: symbol[],\n    token: MaybeToken\u003cDependency\u003e,\n    container: Container,\n) =\u003e void;\n```\n\n### Plugin Example\n\nThe following code is a plugin which links a preact view component to a service by calling forceUpdate every time the\nservice executes the listener:\n\n```ts\nimport {Plugin} from \"@owja/ioc\";\nimport {Component} from \"preact\";\n\nexport const SUBSCRIBE = Symbol();\n\nexport const serviceListenerPlugin: Plugin\u003cListenable\u003e = (service, component, args) =\u003e {\n    if (args.indexOf(SUBSCRIBE) === -1 || !component) return;\n    if (!isComponent(component)) return;\n\n    const unsubscribe = service.listen(() =\u003e component.forceUpdate());\n    const unmount = component.componentWillUnmount;\n\n    component.componentWillUnmount = () =\u003e {\n        unsubscribe();\n        unmount?.();\n    };\n};\n\nfunction isComponent(target: unknown) : target is Component {\n    return  !!target \u0026\u0026 typeof target === \"object\" \u0026\u0026 \"forceUpdate\" in target;\n}\n\ninterface Listenable {\n    listen(listener: () =\u003e void): () =\u003e void;\n}\n```\n\u003e Note: this will fail on runtime if  `service` does not implement the `Listenable` interface because there is no type checking done\n\nThis plugin is added to the dependency directly:\n\n```ts\nconst TYPE = {\n    TranslationService: token\u003cTranslatorInterface\u003e(\"translation-service\"),\n};\n\ncontainer\n    .bind\u003cTranslatorInterface\u003e(TYPE.TranslationService)\n    .toFactory(translationFactory)\n    .inSingletonScope()\n    .withPlugin(serviceListenerPlugin);\n```\n\nIn a component it is then executed when the dependency is resolved:\n\n```ts\nclass Index extends Component {\n    @inject(TYPE.TranslationService, [SUBSCRIBE]/*, ...dependencie arguments*/)\n    readonly service!: TranslatorInterface;\n\n    render() {\n        return (\n            \u003cdiv\u003e{this.service.t(\"greeting\")}\u003c/div\u003e\n        );\n    }\n}\n```\n\nThis works also with `wire` and `resolve`:\n\n```ts\nclass Index extends Component {\n    readonly service!: TranslatorInterface;\n\n    constructor() {\n        super();\n        wire(this, \"service\", TYPE.TranslationService, [SUBSCRIBE]/*, ...dependencie arguments*/);\n    }\n    \n    [...]\n}\n\nclass Index extends Component {\n    readonly service = resolve(TYPE.TranslationService, [SUBSCRIBE]/*, ...dependencie arguments*/);\n    \n    [...]\n}\n\n```\n\n### Prevent Plugins from Execution\n\nIn case you add a plugin it is executed every time the dependency is resolved. If you want to prevent this you can \nadd the `NOPLUGINS` tag to the arguments:\n\n```ts\nimport {NOPLUGINS} from \"@owja/ioc\";\n\nclass Example {\n    @inject(TYPE.MyService, [NOPLUGINS]/*, ...dependencie arguments*/)\n    readonly service!: MyServiceInterface;\n}\n```\n\n## Getting Started\n\n#### Step 1 - Installing the OWJA! IoC library\n\n```bash\nnpm install --save-dev @owja/ioc\n``` \n\n#### Step 2 - Creating symbols for our dependencies\n\nNow we create the folder ***services*** and add the new file ***services/types.ts***:\n```ts\nexport const TYPE = {\n    MyService: Symbol(\"MyService\"),\n    MyOtherService: Symbol(\"MyOtherService\"),\n};\n```\n\n#### Step 3 - Example services\n\nNext we create out example services.\n\nFile ***services/my-service.ts***\n```ts\nexport interface MyServiceInterface {\n    hello: string;\n}\n\nexport class MyService implements MyServiceInterface{\n    hello = \"world\";\n}\n```\n\nFile ***services/my-other-service.ts***\n```ts\nexport interface MyOtherServiceInterface {\n    random: number;\n}\n\nexport class MyOtherService implements MyOtherServiceInterface {\n    random = Math.random();\n}\n```\n\n#### Step 4 - Creating a container\n\nNext we need a container to bind our dependencies to. Let's create the file ***services/container.ts***\n\n```ts\nimport {Container, createDecorator} from \"@owja/ioc\";\n\nimport {TYPE} from \"./types\";\n\nimport {MyServiceInterface, MyService} from \"./service/my-service\";\nimport {MyOtherServiceInterface, MyOtherService} from \"./service/my-other-service\";\n\nconst container = new Container();\nconst inject = createDecorator(container);\n\ncontainer.bind\u003cMyServiceInterface\u003e(TYPE.MyService).to(MyService);\ncontainer.bind\u003cMyOtherServiceInterface\u003e(TYPE.MyOtherService).to(MyOtherService);\n\nexport {container, TYPE, inject};\n```\n\n#### Step 5 - Injecting dependencies\n\nLets create a ***example.ts*** file in our source root:\n \n```ts\nimport {TYPE, inject} from \"./service/container\";\nimport {MyServiceInterface} from \"./service/my-service\";\nimport {MyOtherServiceInterface} from \"./service/my-other-service\";\n\nclass Example {\n    @inject(TYPE.MyService/*, [tags], ...dependencie arguments*/)\n    readonly myService!: MyServiceInterface;\n\n    @inject(TYPE.MyOtherService/*, [tags], ...dependencie arguments*/)\n    readonly myOtherService!: MyOtherServiceInterface;\n}\n\nconst example = new Example();\n\nconsole.log(example.myService);\nconsole.log(example.myOtherService);\nconsole.log(example.myOtherService);\n```\n\nIf we run this example we should see the content of our example services.\n\nThe dependencies (services) will injected on the first call. This means if you rebind the service after\naccessing the properties of the Example class, it will not resolve a new service. If you want a new \nservice each time you call `example.myService` you have to add the `NOCACHE` tag:\n\n```ts\n// [...]\nimport {NOCACHE} from \"@owja/ioc\";\n\nclass Example {\n    // [...]\n    \n    @inject(TYPE.MyOtherSerice, NOCACHE/*, ...dependencie arguments*/)\n    readonly myOtherService!: MyOtherServiceInterface;\n}\n\n// [...]\n```\n\nIn this case the last two `console.log()` outputs should show different numbers.\n\n## Unit testing with IoC\n\nFor unit testing we first create our mocks\n\n***test/my-service-mock.ts***\n```ts\nimport {MyServiceInterface} from \"../service/my-service\";\n\nexport class MyServiceMock implements MyServiceInterface {\n    hello = \"test\";    \n}\n```\n\n***test/my-other-service-mock.ts***\n```ts\nimport {MyOtherServiceInterface} from \"../service/my-other-service\";\n\nexport class MyOtherServiceMock implements MyOtherServiceInterface {\n    random = 9;\n}\n```\n\nWithin the tests we can snapshot and restore a container.\nWe are able to make multiple snapshots in a row too.\n\nFile ***example.test.ts***\n```ts\nimport {container, TYPE} from \"./service/container\";\nimport {MyServiceInterface} from \"./service/my-service\";\nimport {MyOtherServiceInterface} from \"./service/my-other-service\";\n\nimport {MyServiceMock} from \"./test/my-service-mock\";\nimport {MyOtherServiceMock} from \"./test/my-other-service-mock\";\n\nimport {Example} from \"./example\";\n\ndescribe(\"Example\", () =\u003e {\n    \n    let example: Example;\n    beforeEach(() =\u003e {\n        container.snapshot();\n        container.rebind\u003cMyServiceInterface\u003e(TYPE.MyService).to(MyServiceMock);\n        container.rebind\u003cMyOtherServiceInterface\u003e(TYPE.MyOtherService).to(MyOtherServiceMock);\n\n        example = new Example();\n    });\n\n    afterEach(() =\u003e {\n        container.restore();\n    });\n\n    test(\"should return \\\"test\\\"\", () =\u003e {\n        expect(example.myService.hello).toBe(\"test\");\n    });\n\n    test(\"should return \\\"9\\\"\", () =\u003e {\n        expect(example.myOtherService.random).toBe(9);\n    });\n    \n});\n```\n\n## Development\n\nCurrent state of development can be seen in our\n[Github Projects](https://github.com/owja/ioc/projects).\n\n## Inspiration\n\nThis library is highly inspired by [InversifyJS](https://github.com/inversify/InversifyJS)\nbut has other goals:\n\n1. Make the library very lightweight (less than one kilobyte)\n2. Implementing less features to make the API more straight forward\n3. Always lazy inject the dependencies\n4. No meta-reflect required\n\n## License\n\n**MIT**\n\nCopyright © 2019-2022 The OWJA! Team\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowja%2Fioc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowja%2Fioc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowja%2Fioc/lists"}