webiny-dependency-injection

# Dependency Injection Patterns ## TL;DR Every Webiny extension type uses the same DI pattern: define a class implementing `*.Interface`, declare dependencies in the constructor, and export via `*.createImplementation({ implementation, dependencies })`. The DI container automatically provides the required services, ensures type safety, and validates at compile time. This pattern is the connective tissue across all extension types -- API, Admin, CLI, and Infrastructure. ## Working Context This skill applies to both **extension developers** (working in `extensions/`) and **core developers** (working in `packages/`). The DI pattern is universal — only the import paths differ. | | Extensions (`extensions/`) | Core (`packages/`) | | ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | **`createAbstraction`** | `from "webiny/api"` or `from "webiny/admin"` | `from "@webiny/feature/api"` or `from "@webiny/feature/admin"` | | **`createFeature`** | `from "webiny/api"` or `from "webiny/admin"` | `from "@webiny/feature/api"` or `from "@webiny/feature/admin"` | | **Factory imports** | `from "webiny/api/graphql"`, `from "webiny/api/cms/model"`, etc. | Direct package paths: `from "@webiny/handler-graphql/..."`, `from "@webiny/api-headless-cms/..."` | | **Catalog paths** | Use the `Import:` path | Use the `Source:` path | Detect which context you're in by checking the file path: `extensions/` → extension mode, `packages/` → core mode. The `dependencies` array, constructor injection, scoping rules, and all other patterns are identical in both contexts. ## The Universal Pattern ```typescript import { SomeFactory } from "webiny/some/path"; import { Logger, BuildParams } from "webiny/api"; class MyImplementation implements SomeFactory.Interface { constructor( private logger: Logger.Interface, private buildParams: BuildParams.Interface ) {} execute(/* factory-specific params */) { this.logger.info("Doing something..."); // buildParams.get() returns T | null — always account for null. const value = this.buildParams.get<string>("MY_PARAM"); } } export default SomeFactory.createImplementation({ implementation: MyImplementation, dependencies: [Logger, BuildParams] }); ``` Key rules: 1. **One class per file** -- each extension file exports a single implementation. 2. **Constructor injection** -- dependencies are received as constructor parameters, in the same order as the `dependencies` array. 3. **Dependencies array** -- must exactly match the constructor parameter order and types. 4. **Interface types** -- always type constructor params as `Feature.Interface`. ## Where This Pattern Appears | Extension Type | Factory | Import Path | | --------------- | ---------------------- | ------------------------ | | Content Models | `ModelFactory` | `"webiny/api/cms/model"` | | GraphQL Schemas | `GraphQLSchemaFactory` | `"webiny/api/graphql"` | | API Keys | `ApiKeyFactory` | `"webiny/api/security"` | | CLI Commands | `CliCommandFactory` | `"webiny/cli/command"` | | Pulumi Handlers | `CorePulumi` | `"webiny/infra/core"` | > **Event handlers** use the same `createImplementation` pattern but are not injectable dependencies. ## Examples Across Extension Types ### API Extension (GraphQL Schema with DI) GraphQL schemas use the **builder pattern**. The `execute` method receives a `builder` and uses `addTypeDefs` and `addResolver` to define the schema. Resolver-level DI is declared per-resolver via `dependencies` in `addResolver`, resolved at request time from the request-scoped container. ```typescript import { GraphQLSchemaFactory } from "webiny/api/graphql"; import { IdentityContext } from "webiny/api/security"; class WhoAmISchema implements GraphQLSchemaFactory.Interface { async execute( builder: GraphQLSchemaFactory.SchemaBuilder ): Promise<GraphQLSchemaFactory.SchemaBuilder> { builder.addTypeDefs(/* GraphQL */ ` extend type Query { whoAmI: String } `); builder.addResolver({ path: "Query.whoAmI", dependencies: [IdentityContext], resolver: (identityContext: IdentityContext.Interface) => { return () => { const identity = identityContext.getIdentity(); return `Hello, ${identity.displayName}!`; }; } }); return builder; } } export default GraphQLSchemaFactory.createImplementation({ implementation: WhoAmISchema, dependencies: [] }); ``` Note: `GraphQLSchemaFactory` implementations typically have `dependencies: []` because DI happens at the resolver level via `addResolver({ dependencies })`, not at the class constructor level. ### CLI Command with DI ```typescript import { Ui } from "webiny/cli"; import { CliCommandFactory } from "webiny/cli/command"; class MyCommandImpl implements CliCommandFactory.Interface<{ name: string }> { constructor(private ui: Ui.Interface) {} execute(): CliCommandFactory.CommandDefinition<{ name: string }> { return { name: "greet", description: "Greet someone", params: [{ name: "name", description: "Name", type: "string" }], handler: async params => { this.ui.success(`Hello, ${params.name}!`); } }; } } export default CliCommandFactory.createImplementation({ implementation: MyCommandImpl, dependencies: [Ui] }); ``` ### Pulumi Handler with DI ```typescript import { Ui } from "webiny/infra"; import { CorePulumi } from "webiny/infra/core"; class MyPulumiImpl implements CorePulumi.Interface { constructor(private ui: Ui.Interface) {} execute(app: any) { this.ui.info("Deploying with environment:", app.env); } } export default CorePulumi.createImplementation({ implementation: MyPulumiImpl, dependencies: [Ui] }); ``` ## Advanced Dependency Options The `dependencies` array supports three forms per entry: | Form | Meaning | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `Abstraction` | Single required dependency (shorthand) | | `[Abstraction, { optional: true }]` | Single optional dependency — injects `undefined` if not registered | | `[Abstraction, { multiple: true }]` | Multi-injection — injects **all** registered implementations as `T[]` | | `[Abstraction, { multiple: true, optional: true }]` | Multi-injection, optional — injects `undefined` if none registered (vs empty `[]` with just `multiple`) | ### Multi-injection (`{ multiple: true }`) Use when a class needs all registered implementations of an abstraction. The container calls `resolveAll()` internally and injects the results as an array. **Abstraction:** ```ts interface IPageType { name: string; label: string; modify(form: IFormModel): void; } export const PageType = createAbstraction<IPageType>("PageType"); export namespace PageType { export type Interface = IPageType; } ``` **Multiple implementations registered separately:** ```ts // StaticPageType.ts class StaticPageTypeImpl implements PageType.Interface { name = "static"; label = "Static Page"; modify(form: IFormModel) { /* no-op — base form is sufficient */ } } export const StaticPageType = PageType.createImplementation({ implementation: StaticPageTypeImpl, dependencies: [] }); // ProductPageType.ts (in another package/extension) class ProductPageTypeImpl implements PageType.Interface { name = "product"; label = "Product Page"; modify(form: IFormModel) { form.fields(fields => ({ product: fields.select().label("Product").required("Product is required") })); form.field("title").disabled(true); form.field("path").disabled(true); } } export const ProductPageType = PageType.createImplementation({ implementation: ProductPageTypeImpl, dependencies: [] }); ``` **Consumer injects the array:** ```ts class CreatePagePresenterImpl implements CreatePagePresenter.Interface { constructor( private factory: FormModelFactory.Interface, private pageTypes: PageType.Interface[], private modifiers: CreatePageFormModifier.Interface[] ) {} } export const CreatePagePresenter = PresenterAbstraction.createImplementation({ implementation: CreatePagePresenterImpl, dependencies: [ FormModelFactory, [PageType, { multiple: true }], [CreatePageFormModifier, { multiple: true }] ] }); ``` **Registration — each implementation is a separate `container.register()` call:** ```ts export const CreatePageFeature = createFeature({ name: "CreatePage", register(container) { container.register(StaticPageType); // first PageType impl container.register(ProductPageType); // second PageType impl container.register(CreatePagePresenter); } }); ``` When `CreatePagePresenter` is resolved, `pageTypes` receives `[StaticPageTypeImpl, ProductPageTypeImpl]` in registration order. ### Optional dependency (`{ optional: true }`) Use when a dependency may not be registered. The container injects `undefined` instead of throwing. ```ts class MyPresenterImpl { constructor( private required: RequiredService.Interface, private analytics: AnalyticsService.Interface | undefined ) {} } export const MyPresenter = Abstraction.createImplementation({ implementation: MyPresenterImpl, dependencies: [RequiredService, [AnalyticsService, { optional: true }]] }); ``` ## Container API Reference ### Registration | Method | Description |