diff --git a/packages/docs/services/inversify-site/docs/api/container.mdx b/packages/docs/services/inversify-site/docs/api/container.mdx index f1d452a..9220ed9 100644 --- a/packages/docs/services/inversify-site/docs/api/container.mdx +++ b/packages/docs/services/inversify-site/docs/api/container.mdx @@ -2,32 +2,14 @@ sidebar_position: 2 title: Container --- -import containerApiGetAllSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAll.ts.txt'; -import containerApiGetAllAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllAsync.ts.txt'; -import containerApiGetAllAsyncEnforcedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllAsyncEnforced.ts.txt'; -import containerApiGetAllEnforcedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllEnforced.ts.txt'; -import containerApiGetAllNamedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllNamed.ts.txt'; -import containerApiGetAllNamedAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllNamedAsync.ts.txt'; -import containerApiGetAllTaggedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllTagged.ts.txt'; -import containerApiGetAllTaggedAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAllTaggedAsync.ts.txt'; -import containerApiGetAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetAsync.ts.txt'; -import containerApiGetNamedAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetNamedAsync.ts.txt'; -import containerApiGetNamedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetNamed.ts.txt'; -import containerApiGetSource from '@inversifyjs/code-examples/generated/examples/containerApiGet.ts.txt'; -import containerApiGetTaggedAsyncSource from '@inversifyjs/code-examples/generated/examples/containerApiGetTaggedAsync.ts.txt'; -import containerApiGetTaggedSource from '@inversifyjs/code-examples/generated/examples/containerApiGetTagged.ts.txt'; -import containerApiIsBoundSource from '@inversifyjs/code-examples/generated/examples/containerApiIsBound.ts.txt'; -import containerApiIsBoundNamedSource from '@inversifyjs/code-examples/generated/examples/containerApiIsBoundNamed.ts.txt'; -import containerApiIsBoundTaggedSource from '@inversifyjs/code-examples/generated/examples/containerApiIsBoundTagged.ts.txt'; -import containerApiIsCurrentBoundSource from '@inversifyjs/code-examples/generated/examples/containerApiIsCurrentBound.ts.txt'; -import containerApiMergeSource from '@inversifyjs/code-examples/generated/examples/containerApiMerge.ts.txt'; -import containerApiOptionsAutoBindInjectablePrecedenceSource from '@inversifyjs/code-examples/generated/examples/containerApiOptionsAutoBindInjectablePrecedence.ts.txt'; -import containerApiOptionsAutoBindInjectableSource from '@inversifyjs/code-examples/generated/examples/containerApiOptionsAutoBindInjectable.ts.txt'; -import containerApiOptionsDefaultScopeSource from '@inversifyjs/code-examples/generated/examples/containerApiOptionsDefaultScope.ts.txt'; -import containerApiOnActivationSource from '@inversifyjs/code-examples/generated/examples/containerApiOnActivation.ts.txt'; -import containerApiOnDeactivationSource from '@inversifyjs/code-examples/generated/examples/containerApiOnDeactivation.ts.txt'; -import containerApiRebindSource from '@inversifyjs/code-examples/generated/examples/containerApiRebind.ts.txt'; -import containerApiResolveSource from '@inversifyjs/code-examples/generated/examples/containerApiResolve.ts.txt'; +import containerApiGetAllSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiGetAll.ts.txt'; +import containerApiGetAllAsyncSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiGetAllAsync.ts.txt'; +import containerApiGetAsyncSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiGetAsync.ts.txt'; +import containerApiGetSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiGet.ts.txt'; +import containerApiIsBoundSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiIsBound.ts.txt'; +import containerApiIsCurrentBoundSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiIsCurrentBound.ts.txt'; +import containerApiOnActivationSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiOnActivation.ts.txt'; +import containerApiOnDeactivationSource from '@inversifyjs/code-examples/generated/examples/v7/containerApiOnDeactivation.ts.txt'; import CodeBlock from '@theme/CodeBlock'; # Container @@ -45,80 +27,35 @@ You can even provide your own annotation solution. Container options can be passed to the Container constructor, and defaults will be provided if you do not or if you do but omit an option. Options can be changed after construction and will be shared by child containers created from the Container if you do not provide options for them. -### defaultScope - -The default scope is `transient` when binding to/toSelf/toDynamicValue/toService. -Other bindings can only be bound in `singleton` scope. - -You can use container options to change the default scope for the bindings that default to `transient` at the application level: - -{containerApiOptionsDefaultScopeSource} - -### autoBindInjectable - -You can use this to activate automatic binding for `@injectable()` decorated classes. -Whenever an instance is requested via `get`, the container attempts to add a binding if no binding is found for the requested service. - -{containerApiOptionsAutoBindInjectableSource} - -Manually defined bindings will take precedence: - -{containerApiOptionsAutoBindInjectablePrecedenceSource} - -### skipBaseClassChecks - -You can use this to skip checking base classes for the `@injectable` property, which is especially useful if any of your `@injectable` classes extend classes that you don't control (third-party classes). By default, this value is `false`. +### parent ```ts -const container = new Container({ skipBaseClassChecks: true }); +parent?: Container | undefined; ``` -## Container.merge +The parent container, if any. Refer to the [container hierarchy docs](/docs/fundamentals/di-hierarchy) for more information. -```ts -Container.merge(a: interfaces.Container, b: interfaces.Container, ...containers: interfaces.Container[]): interfaces.Container; -``` - -Creates a new Container containing the bindings ( cloned bindings ) of two or more containers: - -{containerApiMergeSource} - -## applyCustomMetadataReader - -```ts -applyCustomMetadataReader(metadataReader: interfaces.MetadataReader): void; -``` - -Sets a custom metadata reader. See [middleware](/docs/fundamentals/lifecycle/middleware). - -## applyMiddleware +### defaultScope ```ts -applyMiddleware(...middleware: interfaces.Middleware[]): void; +defaultScope?: BindingScope | undefined; ``` -An advanced feature that can be used for cross cutting concerns. See [middleware](/docs/fundamentals/lifecycle/middleware). +The default scope for bindings. ## bind ```ts -bind(serviceIdentifier: interfaces.ServiceIdentifier): interfaces.BindingToSyntax +bind(serviceIdentifier: ServiceIdentifier): BindingToSyntax ``` Sets a new binding. -## createChild - -```ts -createChild(containerOptions?: interfaces.ContainerOptions): Container; -``` - -Create a [container hierarchy](/docs/fundamentals/di-hierarchy). Parent `ContainerOptions` are provided by default. - ## get ```ts -get(serviceIdentifier: interfaces.ServiceIdentifier): T; +get(serviceIdentifier: ServiceIdentifier, options: OptionalGetOptions): T | undefined; +get(serviceIdentifier: ServiceIdentifier, options?: GetOptions): T; ``` Resolves a dependency by its runtime identifier. The runtime identifier must be associated with only one binding and the binding must be synchronously resolved, otherwise an error is thrown. @@ -128,125 +65,38 @@ Resolves a dependency by its runtime identifier. The runtime identifier must be ## getAsync ```ts -getAsync(serviceIdentifier: interfaces.ServiceIdentifier): Promise; +getAsync(serviceIdentifier: ServiceIdentifier, options: OptionalGetOptions): Promise; +getAsync(serviceIdentifier: ServiceIdentifier, options?: GetOptions): Promise; ``` Resolves a dependency by its runtime identifier. The runtime identifier must be associated with only one binding, otherwise an error is thrown. {containerApiGetAsyncSource} -## getNamed - -```ts -getNamed(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): T; -``` - -Resolves a dependency by its runtime identifier that matches the given named constraint. The runtime identifier must be associated with only one binding and the binding must be synchronously resolved, otherwise an error is thrown: - -{containerApiGetNamedSource} - -## getNamedAsync - -```ts -getNamedAsync(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): Promise; -``` - -Resolves a dependency by its runtime identifier that matches the given named constraint. The runtime identifier must be associated with only one binding, otherwise an error is thrown: - -{containerApiGetNamedAsyncSource} - -## getTagged - -```ts -getTagged(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): T; -``` - -Resolves a dependency by its runtime identifier that matches the given tagged constraint. The runtime identifier must be associated with only one binding and the binding must be synchronously resolved, otherwise an error is thrown: - -{containerApiGetTaggedSource} - -## getTaggedAsync - -```ts -getTaggedAsync(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): Promise; -``` - -Resolves a dependency by its runtime identifier that matches the given tagged constraint. The runtime identifier must be associated with only one binding, otherwise an error is thrown: - -{containerApiGetTaggedAsyncSource} - ## getAll ```ts -getAll(serviceIdentifier: interfaces.ServiceIdentifier, options?: interfaces.GetAllOptions): T[]; +getAll(serviceIdentifier: ServiceIdentifier, options?: GetAllOptions): T[]; ``` Get all available bindings for a given identifier. All the bindings must be synchronously resolved, otherwise an error is thrown: {containerApiGetAllSource} -Keep in mind `container.getAll` doesn't enforce binding contraints by default in the root level, enable the `enforceBindingConstraints` flag to force this binding constraint check: - -{containerApiGetAllEnforcedSource} - ## getAllAsync ```ts -getAllAsync(serviceIdentifier: interfaces.ServiceIdentifier, options?: interfaces.GetAllOptions): Promise +getAllAsync(serviceIdentifier: ServiceIdentifier, options?: GetAllOptions): Promise ``` Get all available bindings for a given identifier: {containerApiGetAllAsyncSource} -Keep in mind `container.getAll` doesn't enforce binding contraints by default in the root level, enable the `enforceBindingConstraints` flag to force this binding constraint check: - -{containerApiGetAllAsyncEnforcedSource} - -## getAllNamed - -```ts -getAllNamed(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): T[]; -``` - -Resolves all the dependencies by its runtime identifier that matches the given named constraint. All the binding must be synchronously resolved, otherwise an error is thrown: - -{containerApiGetAllNamedSource} - -## getAllNamedAsync - -```ts -getAllNamedAsync(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): Promise; -``` - -Resolves all the dependencies by its runtime identifier that matches the given named constraint: - -{containerApiGetAllNamedAsyncSource} - -## getAllTagged - -```ts -getAllTagged(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): T[]; -``` - -Resolves all the dependencies by its runtime identifier that matches the given tagged constraint. All the binding must be synchronously resolved, otherwise an error is thrown: - -{containerApiGetAllTaggedSource} - -## getAllTaggedAsync - -```ts -getAllTaggedAsync(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): Promise; -``` - -Resolves all the dependencies by its runtime identifier that matches the given tagged constraint: - -{containerApiGetAllTaggedAsyncSource} - ## isBound ```ts -isBound(serviceIdentifier: interfaces.ServiceIdentifier): boolean; +isBound(serviceIdentifier: ServiceIdentifier, options?: IsBoundOptions): boolean; ``` You can use the `isBound` method to check if there are registered bindings for a given service identifier. @@ -257,83 +107,25 @@ You can use the `isBound` method to check if there are registered bindings for a ## isCurrentBound ```ts -isCurrentBound(serviceIdentifier: interfaces.ServiceIdentifier): boolean; +isCurrentBound(serviceIdentifier: ServiceIdentifier, options?: IsBoundOptions): boolean; ``` You can use the `isCurrentBound` method to check if there are registered bindings for a given service identifier only in the current container. {containerApiIsCurrentBoundSource} -## isBoundNamed - -```ts -isBoundNamed(serviceIdentifier: interfaces.ServiceIdentifier, named: string): boolean; -``` - -You can use the `isBoundNamed` method to check if there are registered bindings for a given service identifier with a given named constraint. - -{containerApiIsBoundNamedSource} - -## isBoundTagged - -```ts -isBoundTagged(serviceIdentifier: interfaces.ServiceIdentifier, key: string, value: unknown): boolean; -``` - -You can use the `isBoundTagged` method to check if there are registered bindings for a given service identifier with a given tagged constraint. - -{containerApiIsBoundTaggedSource} - ## load ```ts -load(...modules: interfaces.ContainerModule[]): void; -``` - -Calls the registration method of each module. See [ContainerModule API docs](/docs/api/container-module) - -## loadAsync - -```ts -loadAsync(...modules: interfaces.AsyncContainerModule[]): Promise; -``` - -As per load but for asynchronous registration. - -## rebind - -```ts -rebind(serviceIdentifier: interfaces.ServiceIdentifier): interfaces.BindingToSyntax; -``` - -Replaces all the existing bindings for a given `serviceIdentifier`. -The function returns an instance of `BindingToSyntax` which allows to create the replacement binding. - -{containerApiRebindSource} - -## rebindAsync - -```ts -rebindAsync(serviceIdentifier: interfaces.ServiceIdentifier): Promise>; -``` - -This is an asynchronous version of rebind. If you know deactivation is asynchronous then this should be used. - -## resolve - -```ts -resolve(constructor: interfaces.Newable): T; +load(...modules: ContainerModule[]): Promise; ``` -Resolve works the same way `container.get`, but an automatic binding will be added to the container if no bindings are found for the type provided. -{containerApiResolveSource} - -Please note that it only allows to skip declaring a binding for the root element in the dependency graph (composition root). All the sub-dependencies (e.g. `Katana` in the preceding example) will require a binding to be declared. +Calls the registration method of each module. See [ContainerModule API docs](/docs/api/container-module). ## onActivation ```ts -onActivation(serviceIdentifier: interfaces.ServiceIdentifier, onActivation: interfaces.BindingActivation): void; +onActivation(serviceIdentifier: ServiceIdentifier, onActivation: BindingActivation): void; ``` Adds an activation handler for all services associated to the service identifier. @@ -343,7 +135,7 @@ Adds an activation handler for all services associated to the service identifier ## onDeactivation ```ts -onDeactivation(serviceIdentifier: interfaces.ServiceIdentifier, onDeactivation: interfaces.BindingDeactivation): void; +onDeactivation(serviceIdentifier: ServiceIdentifier, onDeactivation: BindingDeactivation): void; ``` Adds a deactivation handler for a service identifier. @@ -366,163 +158,27 @@ snapshot(): void; Save the state of the container to be later restored with the restore method. Refer to the [docs](/docs/fundamentals/snapshot) for more information. -## tryGet - -```ts -tryGet(serviceIdentifier: interfaces.ServiceIdentifier): T | undefined; -``` - -Same as `container.get`, but returns `undefined` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAsync - -```ts -tryGetAsync(serviceIdentifier: interfaces.ServiceIdentifier): Promise; -``` - -Same as `container.getAsync`, but returns `Promise` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetNamed - -```ts -tryGetNamed(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): T | undefined; -``` - -Same as `container.getNamed`, but returns `undefined` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetNamedAsync - -```ts -tryGetNamedAsync(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): Promise; -``` - -Same as `container.getNamedAsync`, but returns `Promise` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetTagged - -```ts -tryGetTagged(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): T | undefined; -``` - -Same as `container.getTagged`, but returns `undefined` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetTaggedAsync - -```ts -tryGetTaggedAsync(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): Promise -``` - -Same as `container.getTaggedAsync`, but returns `Promise` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAll - -```ts -tryGetAll(serviceIdentifier: interfaces.ServiceIdentifier, options?: interfaces.GetAllOptions): T[] -``` - -Same as `container.getAll`, but returns `[]` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAllAsync - -```ts -tryGetAllAsync(serviceIdentifier: interfaces.ServiceIdentifier, options?: interfaces.GetAllOptions): Promise; -``` - -Same as `container.getAllAsync`, but returns `Promise<[]>` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAllNamed - -```ts -tryGetAllNamed(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): T[]; -``` - -Same as `container.getAllNamed`, but returns `[]` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAllNamedAsync - -```ts -tryGetAllNamedAsync(serviceIdentifier: interfaces.ServiceIdentifier, named: string | number | symbol): Promise; -``` - -Same as `container.getAllNamedAsync`, but returns `Promise<[]>` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAllTagged - -```ts -tryGetAllTagged(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): T[]; -``` - -Same as `container.getAllTagged`, but returns `[]` in the event no bindings are bound to `serviceIdentifier`. - -## tryGetAllTaggedAsync - -```ts -tryGetAllTaggedAsync(serviceIdentifier: interfaces.ServiceIdentifier, key: string | number | symbol, value: unknown): Promise; -``` - -Same as `container.getAllTaggedAsync`, but returns `Promise<[]>` in the event no bindings are bound to `serviceIdentifier`. - ## unbind ```ts -unbind(serviceIdentifier: interfaces.ServiceIdentifier): void; +unbind(serviceIdentifier: ServiceIdentifier): Promise; ``` -Remove all bindings binded in this container to the service identifier. This will result in the [deactivation process](/docs/fundamentals/lifecycle/deactivation). - -## unbindAsync - -```ts -unbindAsync(serviceIdentifier: interfaces.ServiceIdentifier): Promise; -``` - -This is the asynchronous version of unbind. If any deactivation realated to this service identifier is asynchronous then this method should be used instead of `container.unbind`. +Remove all bindings binded in this container to the service identifier. This will result in the [deactivation process](/docs/fundamentals/lifecycle/deactivation). ## unbindAll ```ts -unbindAll(): void; +unbindAll(): Promise; ``` Remove all bindings binded in this container. This will result in the [deactivation process](/docs/fundamentals/lifecycle/deactivation). -## unbindAllAsync - -```ts -unbindAllAsync(): Promise; -``` - -This is the asynchronous version of unbindAll. If any of the container's deactivations is asynchronous then this method should be used instead of `container.unbindAll`. - ## unload ```ts -unload(...modules: interfaces.ContainerModuleBase[]): void; +unload(...modules: ContainerModule[]): Promise; ``` Removes bindings and handlers added by the modules. This will result in the [deactivation process](/docs/fundamentals/lifecycle/deactivation). See [ContainerModule API docs](/docs/api/container-module). - -## unloadAsync - -```ts -unloadAsync(...modules: interfaces.ContainerModuleBase[]): Promise; -``` - -Asynchronous version of unload. If any of the container modules's deactivations is asynchronous then this method should be used instead of `container.unload`. - -## parent - -```ts -parent: Container | null; -``` - -Access the parent container. - -## id - -```ts -id: number; -``` - -The container's unique identifier.