@ivlev-dev/silent-di 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +182 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
# @ivlev-dev/silent-di
|
|
2
|
+
|
|
3
|
+
Асинхронный контейнер зависимостей без декораторов: токены, скоупы, кеш промисов и compile-time привязка интерфейсов к реализациям.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@ivlev-dev/silent-di)
|
|
6
|
+
[](https://github.com/ivlev-dev/silent-framework/blob/main/LICENSE)
|
|
7
|
+
[](https://www.npmjs.com/package/@ivlev-dev/silent-di)
|
|
8
|
+
|
|
9
|
+
## Возможности
|
|
10
|
+
|
|
11
|
+
- DI без декораторов: токены-символы и классы как токены, зависимости как обычные параметры конструктора.
|
|
12
|
+
- Автопоиск реализаций: компилятор строит индекс `интерфейс → реализация` и подставляет единственную реализацию на этапе компиляции.
|
|
13
|
+
- Скоупы: `singleton`, `scoped`, `transient` и дочерние контейнеры с наследованием привязок.
|
|
14
|
+
- Асинхронное разрешение: `resolve` всегда возвращает `Promise`, кеш промисов разделяет параллельные вызовы.
|
|
15
|
+
- Детектор циклов: `CircularDependencyError` с путём из токенов.
|
|
16
|
+
- Точечное управление: `peek`, `has`, `clearCache(token?)`, `onDispose`-хуки, рекурсивный `dispose`.
|
|
17
|
+
|
|
18
|
+
## Установка
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add @ivlev-dev/silent-di
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install @ivlev-dev/silent-di
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
yarn add @ivlev-dev/silent-di
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Требуется Node.js >= 22. Пакет ESM-only (`type: "module"`).
|
|
33
|
+
|
|
34
|
+
## Быстрый старт
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { container, createToken } from "@ivlev-dev/silent-di";
|
|
38
|
+
|
|
39
|
+
const token = createToken<string>("config");
|
|
40
|
+
|
|
41
|
+
container.bind(token, () => "hello");
|
|
42
|
+
|
|
43
|
+
const value = await container.resolve<string>(token);
|
|
44
|
+
|
|
45
|
+
container.dispose();
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`bind` принимает фабрику в виде функции, класса или константы; по умолчанию привязка — `singleton`. `dispose()` рекурсивно очищает контейнер и все дочерние скоупы.
|
|
49
|
+
|
|
50
|
+
## Интерфейсы и автопоиск
|
|
51
|
+
|
|
52
|
+
Рантайм работает с токенами — `Symbol` с phantom-параметром типа. Токен создаётся функцией `createToken`, класс может выступать токеном напрямую, декораторы не нужны:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
import type { Store } from "./store.types";
|
|
56
|
+
|
|
57
|
+
export class MemoryStore implements Store {}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Сканер индекса собирает отображение `интерфейс → список реализаций`. При компиляции конструктора, принимающего интерфейс через `import type`, подставляется единственная найденная реализация — её класс становится токеном:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import type { Store } from "./store.types";
|
|
64
|
+
|
|
65
|
+
export class ViewModel {
|
|
66
|
+
constructor(private readonly store: Store) {}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Чтобы автопоиск сработал, интерфейс нужно импортировать как `import type`. В рантайме компилятор оборачивает классы через статический метод по символу `DI_CREATE` (`Symbol.for("silent.di.create")`) и передаёт туда контейнер для разрешения зависимостей.
|
|
71
|
+
|
|
72
|
+
Класс без явной привязки при `resolve` автоматически регистрируется как синглтон в контейнере, с которого началось разрешение:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import { Container } from "@ivlev-dev/silent-di";
|
|
76
|
+
|
|
77
|
+
class Service {}
|
|
78
|
+
|
|
79
|
+
const root = new Container("root");
|
|
80
|
+
const service = await root.resolve(Service);
|
|
81
|
+
root.has(Service);
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Если интерфейс имеет более одной реализации, используйте явный `bind`.
|
|
85
|
+
|
|
86
|
+
## Скоупы
|
|
87
|
+
|
|
88
|
+
Привязки наследуются: скоуп, созданный через `createScope(name?)`, разрешает привязки родителя, а `dispose` скоупа не затрагивает родителя.
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import { Container, createToken } from "@ivlev-dev/silent-di";
|
|
92
|
+
|
|
93
|
+
const root = new Container("root");
|
|
94
|
+
|
|
95
|
+
const singletonToken = createToken<object>("singleton");
|
|
96
|
+
const scopedToken = createToken<object>("scoped");
|
|
97
|
+
const transientToken = createToken<object>("transient");
|
|
98
|
+
|
|
99
|
+
root.bind(singletonToken, () => ({}));
|
|
100
|
+
root.bind(scopedToken, () => ({})).inScopedScope();
|
|
101
|
+
root.bind(transientToken, () => ({})).inTransientScope();
|
|
102
|
+
|
|
103
|
+
const scope = root.createScope("request");
|
|
104
|
+
|
|
105
|
+
const singletonA = await scope.resolve(singletonToken);
|
|
106
|
+
const singletonB = await root.resolve(singletonToken);
|
|
107
|
+
|
|
108
|
+
const scopedA = await scope.resolve(scopedToken);
|
|
109
|
+
const scopedB = await scope.resolve(scopedToken);
|
|
110
|
+
|
|
111
|
+
const transientA = await root.resolve(transientToken);
|
|
112
|
+
const transientB = await root.resolve(transientToken);
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- `singleton` — экземпляр кешируется в контейнере-владельце привязки и разделяется между всеми скоупами (`singletonA === singletonB`).
|
|
116
|
+
- `scoped` — экземпляр кешируется в контейнере, с которого начался `resolve` (`scopedA === scopedB` внутри одного скоупа, но не между скоупами).
|
|
117
|
+
- `transient` — каждый последовательный `resolve` создаёт новый экземпляр; параллельные вызовы до завершения разрешения разделяют один промис.
|
|
118
|
+
|
|
119
|
+
## Ошибки и защита
|
|
120
|
+
|
|
121
|
+
- `CircularDependencyError` — выбрасывается при циклической зависимости; поле `path` содержит токены в порядке обхода.
|
|
122
|
+
- Отсутствующая привязка — `resolve` неизвестного токена выбрасывает ошибку `Async DI: no binding registered for token ...`.
|
|
123
|
+
- После `dispose()` — `resolve` выбрасывает ошибку, `has` возвращает `false`, `peek` возвращает `undefined`, повторный `dispose` — no-op.
|
|
124
|
+
- `resolve(undefined)` — выбрасывает ошибку `Async DI: resolve<T>() must be transformed by silentwire before runtime`.
|
|
125
|
+
- При ошибке фабрики кеш токена очищается, следующий `resolve` повторяет попытку.
|
|
126
|
+
- `clearCache()` без аргумента сбрасывает кеш текущего контейнера и всех потомков; `clearCache(token)` — только один токен.
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
import { CircularDependencyError, Container, createToken } from "@ivlev-dev/silent-di";
|
|
130
|
+
|
|
131
|
+
const root = new Container("root");
|
|
132
|
+
const token = createToken<never>("parent");
|
|
133
|
+
|
|
134
|
+
const scope = root.createScope("loop");
|
|
135
|
+
scope.bind(token, (c: Container) => c.resolve(token));
|
|
136
|
+
|
|
137
|
+
try {
|
|
138
|
+
await scope.resolve(token);
|
|
139
|
+
} catch (error) {
|
|
140
|
+
if (error instanceof CircularDependencyError) {
|
|
141
|
+
console.log(error.path.length);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## API
|
|
147
|
+
|
|
148
|
+
| Символ | Назначение |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| `Container` | Асинхронный контейнер: `bind`, `resolve`, `createScope`, `peek`, `has`, `clearCache`, `onDispose`, `dispose` |
|
|
151
|
+
| `container` | Глобальный корневой экземпляр `Container("root")` |
|
|
152
|
+
| `createToken` | Создаёт типизированный токен (`symbol` c phantom-типом `T`) |
|
|
153
|
+
| `Token` | Тип токена: `symbol` c phantom-параметром `T` |
|
|
154
|
+
| `DI_CREATE` | Рантайм-символ `Symbol.for("silent.di.create")` для инстанциирования классов компилятором |
|
|
155
|
+
| `CircularDependencyError` | Ошибка циклической зависимости с полем `path` |
|
|
156
|
+
| `ScopeName` | Тип скоупа: `"singleton"`, `"transient"`, `"scoped"` |
|
|
157
|
+
| `Factory` | Фабрика: `(container: Container) => T | Promise<T>` |
|
|
158
|
+
| `Binding` | Привязка: `factory` + `scope` |
|
|
159
|
+
| `BindingBuilder` | Строитель скоупа привязки: `inSingletonScope`, `inTransientScope`, `inScopedScope` |
|
|
160
|
+
|
|
161
|
+
Подробнее — в [справочнике API](https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/di.md).
|
|
162
|
+
|
|
163
|
+
## Ограничения и совместимость
|
|
164
|
+
|
|
165
|
+
- ESM-only: экспорт только через `import` (`"type": "module"`).
|
|
166
|
+
- Node.js >= 22.
|
|
167
|
+
- Синхронных вызовов нет: `resolve` всегда возвращает `Promise`.
|
|
168
|
+
- Интерфейс должен иметь ровно одну реализацию в индексе; иначе — явный `bind`.
|
|
169
|
+
- Сложные re-export и generic-типы в DI требуют ручной привязки.
|
|
170
|
+
- Автопоиск работает только через компилятор Silent Framework; рантайм сам по себе резолвит только токены и классы.
|
|
171
|
+
- Глобальный `container` один на процесс; для изоляции используйте дочерние скоупы или собственный `Container`.
|
|
172
|
+
|
|
173
|
+
## Ссылки
|
|
174
|
+
|
|
175
|
+
- Репозиторий: https://github.com/ivlev-dev/silent-framework
|
|
176
|
+
- Документация API: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/di.md
|
|
177
|
+
- CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
|
|
178
|
+
- Issues: https://github.com/ivlev-dev/silent-framework/issues
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
MIT © ivlev-dev
|