@amazon/vinyl-di

中文文档
5.0.0发布于 2026/11/16Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2567

Simple dependency injection

原始使用文档
文档目录4 节
  1. Install
  2. Dependency Injection
  3. External Dependencies
  4. License

@amazon/vinyl-di

Website npm size

Constructor-based dependency injection with a compile-time-checked dependency graph. Used internally by Amazon Vinyl, but standalone.

Install

npm install @amazon/vinyl-di

Dependency Injection

Amazon Vinyl uses the most common form of dependency injection; requesting dependencies through constructors.

Class constructors have a deps parameter describing the required dependencies.

E.g.

/**
 * Dependencies for {@link RequesterImpl}
 */
export type RequesterImplDeps = {
    readonly networkState: NetworkState
    readonly fetch: Fetch
    readonly networkMetricsController: NetworkMetricsController
}

export class RequesterImpl {
    constructor(protected readonly deps: RequesterImplDeps) {}

    // ...
}

const requester = new Requester({
    networkState: new NetworkStateImpl(),
    fetch: new FetchImpl(),
})

There are two steps to dependency injection: creating a record of dependency factories, then creating a container that uses the factories to construct implementations.

When creating a record of dependency factories, the keys match the dependency properties, and the values are functions that produce a dependency. The factory functions may accept a single argument indicating any dependencies required for the implementation. Wrap the record in a call to validateFactories which is a compile-time-only check that ensures the dependency graph is sound. That is, there are no cyclic dependencies, missing dependencies, or incompatible types.

Example:

import { validateFactories } from '@amazon/vinyl-di'

class A {}

type BDependencies = {
    readonly a: A
}

class B {
    constructor(deps: BDependencies) {}
}

type CDependencies = {
    readonly a: A
    readonly b: B
}

class C {
    constructor(deps: CDependencies) {}
}

const factories = validateFactories({
    a: () => new A(),
    b: (deps: BDependencies) => new B(deps),
    c: (deps: CDependencies) => new C(deps),
} as const)

These factories will be used to create implementations. Use createContainer to create a container that may be disposed and provides an object with getters to lazily construct implementations from the provided factories.

import { createContainer } from '@amazon/vinyl-di'
import { createDisposer } from '@amazon/vinyl-util'

const { add, dispose } = createDisposer()

const deps = add(createContainer(factories)).dependencies

deps.a // A {}
deps.b // B {}
deps.c // C {}

External Dependencies

Sometimes you need to inject existing instances into a dependency container without transferring ownership. Use externalDependencies to wrap external dependencies that should not be disposed when the container is disposed.

import {
    externalDependencies,
    validateFactories,
    createContainer,
} from '@amazon/vinyl-di'

// External services managed elsewhere
const logger = new Logger()
const options = { port: 8080, host: 'localhost' }

const factories = validateFactories({
    // These won't be disposed by the container
    ...externalDependencies({ logger, options }),

    // This will be disposed by the container [if Server implements Disposable]
    server: (deps: {
        readonly options: ServerOptions
        readonly logger: Logger
    }) => new Server(deps.options, deps.logger),
})

const container = createContainer(factories)

// Use dependencies normally
container.dependencies.server.start()

// Only server.dispose() is called, logger and options are left alone
container.dispose()

As a general guideline, when defining a dependency to be provided, the interface requested should be the minimum API needed, and disposal should be the responsibility of the creator.

License

Apache-2.0

版本与发布记录

@amazon/vinyl-di 共发布 44 个版本,首次发布于 2026/05/28;过去 12 个月发布了 44 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/11/16今天
4.1.1-next.20261115174554next2026/11/16今天
4.1.1-next.202611151724472026/11/16今天
4.1.1-next.202611151644392026/11/16今天
4.1.1-next.202611150013552026/11/151 天前
4.1.1-next.202611131749092026/11/142 天前

其他发布通道:hotfix-chromos → 1.2.1,hotfix-close-drm-sessions → 1.2.2,next → 4.1.1-next.20261115174554。

关于 @amazon/vinyl-di 的常见问题

@amazon/vinyl-di 是什么?

Simple dependency injection

如何安装 @amazon/vinyl-di?

在项目目录运行 npm install @amazon/vinyl-di,或使用 pnpm add / yarn add / bun add。

@amazon/vinyl-di 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@amazon/vinyl-di 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@amazon/vinyl-di 可以商用吗?

@amazon/vinyl-di 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@amazon/vinyl-di 的下载量有多少?

根据 npm 官方下载统计,@amazon/vinyl-di 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,567 次,日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@amazon/vinyl-di 还在维护吗?

最新版本 5.0.0 发布于 2026/11/16(今天);至今共发布 44 个版本,其中过去 12 个月发布了 44 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。