@theokit/di 0.2.0 → 0.3.1
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/CHANGELOG.md +62 -1
- package/README.md +24 -0
- package/dist/index.cjs +58 -20
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +33 -2
- package/dist/index.d.ts +33 -2
- package/dist/index.js +57 -21
- package/dist/index.js.map +1 -1
- package/package.json +4 -2
package/dist/index.d.cts
CHANGED
|
@@ -240,7 +240,17 @@ declare class Container {
|
|
|
240
240
|
* try/finally guarantees REQUEST-scoped instances are disposed
|
|
241
241
|
* even if the callback throws.
|
|
242
242
|
*/
|
|
243
|
-
runInRequest<R>(callback: () => R | Promise<R
|
|
243
|
+
runInRequest<R>(callback: () => R | Promise<R>, options?: {
|
|
244
|
+
seed?: unknown;
|
|
245
|
+
}): Promise<R>;
|
|
246
|
+
/**
|
|
247
|
+
* The seed of the active request scope, as passed to
|
|
248
|
+
* `runInRequest(cb, { seed })`.
|
|
249
|
+
*
|
|
250
|
+
* @throws ScopeViolationError outside a request scope.
|
|
251
|
+
* @throws MissingRequestSeedError when the scope was opened without a seed.
|
|
252
|
+
*/
|
|
253
|
+
requestSeed<T>(): T;
|
|
244
254
|
/**
|
|
245
255
|
* Debug helper — returns a snapshot of the dependency graph.
|
|
246
256
|
*
|
|
@@ -540,6 +550,19 @@ declare function Qualifier(name: string): ParameterDecorator;
|
|
|
540
550
|
* - Anything else: `<unknown token>` (defensive — should never happen)
|
|
541
551
|
*/
|
|
542
552
|
declare function describeToken(token: Token): string;
|
|
553
|
+
/**
|
|
554
|
+
* Renders a constructor's name for a diagnostic, falling back when it has none.
|
|
555
|
+
*
|
|
556
|
+
* `??` is WRONG here and was used at four call sites until 2026-09-01. An
|
|
557
|
+
* anonymous class does not have an absent `name` — it has `""`, and `"" ?? x` is
|
|
558
|
+
* `""`. So the fallbacks never fired, and a consumer who passed a class
|
|
559
|
+
* expression read `Class has no @Module() decorator.`: two spaces where the
|
|
560
|
+
* identity should be, and nothing at all to search the codebase for.
|
|
561
|
+
*
|
|
562
|
+
* `describeToken` above had the check right (`name.length > 0`) and the other
|
|
563
|
+
* sites drifted from it, so the knowledge lives in one place now.
|
|
564
|
+
*/
|
|
565
|
+
declare function describeClassName(target: unknown, fallback: string): string;
|
|
543
566
|
/**
|
|
544
567
|
* Thrown when `resolve()` / `resolveAsync()` is asked for a token that
|
|
545
568
|
* was never registered.
|
|
@@ -596,6 +619,14 @@ declare class ScopeViolationError extends Error {
|
|
|
596
619
|
readonly name: "ScopeViolationError";
|
|
597
620
|
constructor(token: Token, message: string);
|
|
598
621
|
}
|
|
622
|
+
/**
|
|
623
|
+
* Thrown by `container.requestSeed()` inside a request scope that was opened
|
|
624
|
+
* without a seed.
|
|
625
|
+
*/
|
|
626
|
+
declare class MissingRequestSeedError extends Error {
|
|
627
|
+
readonly name: "MissingRequestSeedError";
|
|
628
|
+
constructor();
|
|
629
|
+
}
|
|
599
630
|
/**
|
|
600
631
|
* Thrown when a class is registered as a provider (via `useClass` or shorthand)
|
|
601
632
|
* but lacks the `@Injectable()` decorator. The decorator emits
|
|
@@ -742,4 +773,4 @@ declare class CyclicModuleImportError extends Error {
|
|
|
742
773
|
constructor(cycle: ReadonlyArray<string>);
|
|
743
774
|
}
|
|
744
775
|
|
|
745
|
-
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, type ClassConstructor, type ClassProvider, Container, ContainerDisposedError, ContainerFrozenError, type ContainerOptions, CyclicDependencyError, CyclicModuleImportError, type DependencyGraph, type Disposable, type ExistingProvider, type FactoryProvider, Inject, Injectable, type InjectableOptions, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, Module, type ModuleMetadata, Optional, PostConstruct, PreDestroy, Primary, type Provider, Qualifier, ReflectMetadataMissingError, type ResolutionContext, Scope, ScopeViolationError, type Token, TokenNotFoundError, type ValueProvider, describeToken };
|
|
776
|
+
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, type ClassConstructor, type ClassProvider, Container, ContainerDisposedError, ContainerFrozenError, type ContainerOptions, CyclicDependencyError, CyclicModuleImportError, type DependencyGraph, type Disposable, type ExistingProvider, type FactoryProvider, Inject, Injectable, type InjectableOptions, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, MissingRequestSeedError, Module, type ModuleMetadata, Optional, PostConstruct, PreDestroy, Primary, type Provider, Qualifier, ReflectMetadataMissingError, type ResolutionContext, Scope, ScopeViolationError, type Token, TokenNotFoundError, type ValueProvider, describeClassName, describeToken };
|
package/dist/index.d.ts
CHANGED
|
@@ -240,7 +240,17 @@ declare class Container {
|
|
|
240
240
|
* try/finally guarantees REQUEST-scoped instances are disposed
|
|
241
241
|
* even if the callback throws.
|
|
242
242
|
*/
|
|
243
|
-
runInRequest<R>(callback: () => R | Promise<R
|
|
243
|
+
runInRequest<R>(callback: () => R | Promise<R>, options?: {
|
|
244
|
+
seed?: unknown;
|
|
245
|
+
}): Promise<R>;
|
|
246
|
+
/**
|
|
247
|
+
* The seed of the active request scope, as passed to
|
|
248
|
+
* `runInRequest(cb, { seed })`.
|
|
249
|
+
*
|
|
250
|
+
* @throws ScopeViolationError outside a request scope.
|
|
251
|
+
* @throws MissingRequestSeedError when the scope was opened without a seed.
|
|
252
|
+
*/
|
|
253
|
+
requestSeed<T>(): T;
|
|
244
254
|
/**
|
|
245
255
|
* Debug helper — returns a snapshot of the dependency graph.
|
|
246
256
|
*
|
|
@@ -540,6 +550,19 @@ declare function Qualifier(name: string): ParameterDecorator;
|
|
|
540
550
|
* - Anything else: `<unknown token>` (defensive — should never happen)
|
|
541
551
|
*/
|
|
542
552
|
declare function describeToken(token: Token): string;
|
|
553
|
+
/**
|
|
554
|
+
* Renders a constructor's name for a diagnostic, falling back when it has none.
|
|
555
|
+
*
|
|
556
|
+
* `??` is WRONG here and was used at four call sites until 2026-09-01. An
|
|
557
|
+
* anonymous class does not have an absent `name` — it has `""`, and `"" ?? x` is
|
|
558
|
+
* `""`. So the fallbacks never fired, and a consumer who passed a class
|
|
559
|
+
* expression read `Class has no @Module() decorator.`: two spaces where the
|
|
560
|
+
* identity should be, and nothing at all to search the codebase for.
|
|
561
|
+
*
|
|
562
|
+
* `describeToken` above had the check right (`name.length > 0`) and the other
|
|
563
|
+
* sites drifted from it, so the knowledge lives in one place now.
|
|
564
|
+
*/
|
|
565
|
+
declare function describeClassName(target: unknown, fallback: string): string;
|
|
543
566
|
/**
|
|
544
567
|
* Thrown when `resolve()` / `resolveAsync()` is asked for a token that
|
|
545
568
|
* was never registered.
|
|
@@ -596,6 +619,14 @@ declare class ScopeViolationError extends Error {
|
|
|
596
619
|
readonly name: "ScopeViolationError";
|
|
597
620
|
constructor(token: Token, message: string);
|
|
598
621
|
}
|
|
622
|
+
/**
|
|
623
|
+
* Thrown by `container.requestSeed()` inside a request scope that was opened
|
|
624
|
+
* without a seed.
|
|
625
|
+
*/
|
|
626
|
+
declare class MissingRequestSeedError extends Error {
|
|
627
|
+
readonly name: "MissingRequestSeedError";
|
|
628
|
+
constructor();
|
|
629
|
+
}
|
|
599
630
|
/**
|
|
600
631
|
* Thrown when a class is registered as a provider (via `useClass` or shorthand)
|
|
601
632
|
* but lacks the `@Injectable()` decorator. The decorator emits
|
|
@@ -742,4 +773,4 @@ declare class CyclicModuleImportError extends Error {
|
|
|
742
773
|
constructor(cycle: ReadonlyArray<string>);
|
|
743
774
|
}
|
|
744
775
|
|
|
745
|
-
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, type ClassConstructor, type ClassProvider, Container, ContainerDisposedError, ContainerFrozenError, type ContainerOptions, CyclicDependencyError, CyclicModuleImportError, type DependencyGraph, type Disposable, type ExistingProvider, type FactoryProvider, Inject, Injectable, type InjectableOptions, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, Module, type ModuleMetadata, Optional, PostConstruct, PreDestroy, Primary, type Provider, Qualifier, ReflectMetadataMissingError, type ResolutionContext, Scope, ScopeViolationError, type Token, TokenNotFoundError, type ValueProvider, describeToken };
|
|
776
|
+
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, type ClassConstructor, type ClassProvider, Container, ContainerDisposedError, ContainerFrozenError, type ContainerOptions, CyclicDependencyError, CyclicModuleImportError, type DependencyGraph, type Disposable, type ExistingProvider, type FactoryProvider, Inject, Injectable, type InjectableOptions, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, MissingRequestSeedError, Module, type ModuleMetadata, Optional, PostConstruct, PreDestroy, Primary, type Provider, Qualifier, ReflectMetadataMissingError, type ResolutionContext, Scope, ScopeViolationError, type Token, TokenNotFoundError, type ValueProvider, describeClassName, describeToken };
|
package/dist/index.js
CHANGED
|
@@ -14,6 +14,11 @@ function describeToken(token) {
|
|
|
14
14
|
return "<unknown token>";
|
|
15
15
|
}
|
|
16
16
|
__name(describeToken, "describeToken");
|
|
17
|
+
function describeClassName(target, fallback) {
|
|
18
|
+
const name = target?.name;
|
|
19
|
+
return typeof name === "string" && name.length > 0 ? name : fallback;
|
|
20
|
+
}
|
|
21
|
+
__name(describeClassName, "describeClassName");
|
|
17
22
|
var TokenNotFoundError = class extends Error {
|
|
18
23
|
static {
|
|
19
24
|
__name(this, "TokenNotFoundError");
|
|
@@ -68,6 +73,15 @@ var ScopeViolationError = class extends Error {
|
|
|
68
73
|
super(`Scope violation for token ${describeToken(token)}: ${message}`), this.token = token;
|
|
69
74
|
}
|
|
70
75
|
};
|
|
76
|
+
var MissingRequestSeedError = class extends Error {
|
|
77
|
+
static {
|
|
78
|
+
__name(this, "MissingRequestSeedError");
|
|
79
|
+
}
|
|
80
|
+
name = "MissingRequestSeedError";
|
|
81
|
+
constructor() {
|
|
82
|
+
super("The active request scope has no seed. Pass { seed } to runInRequest: container.runInRequest(cb, { seed }).");
|
|
83
|
+
}
|
|
84
|
+
};
|
|
71
85
|
var MissingInjectableError = class extends Error {
|
|
72
86
|
static {
|
|
73
87
|
__name(this, "MissingInjectableError");
|
|
@@ -75,7 +89,7 @@ var MissingInjectableError = class extends Error {
|
|
|
75
89
|
target;
|
|
76
90
|
name = "MissingInjectableError";
|
|
77
91
|
constructor(target) {
|
|
78
|
-
super(`Class ${target
|
|
92
|
+
super(`Class ${describeClassName(target, "<anonymous>")} has no @Injectable() decorator. Add @Injectable() above the class declaration before registering it.`), this.target = target;
|
|
79
93
|
}
|
|
80
94
|
};
|
|
81
95
|
var ContainerDisposedError = class extends Error {
|
|
@@ -118,14 +132,15 @@ function findCycles(snapshot) {
|
|
|
118
132
|
const cycles = [];
|
|
119
133
|
const seenCycles = /* @__PURE__ */ new Set();
|
|
120
134
|
const visited = /* @__PURE__ */ new Set();
|
|
135
|
+
const tokenIds = /* @__PURE__ */ new Map();
|
|
121
136
|
for (const node of snapshot.nodes) {
|
|
122
137
|
if (visited.has(node.token)) continue;
|
|
123
|
-
iterativeDfs(node.token, adjacency, visited, cycles, seenCycles);
|
|
138
|
+
iterativeDfs(node.token, adjacency, visited, cycles, seenCycles, tokenIds);
|
|
124
139
|
}
|
|
125
140
|
return cycles;
|
|
126
141
|
}
|
|
127
142
|
__name(findCycles, "findCycles");
|
|
128
|
-
function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
143
|
+
function iterativeDfs(root, adjacency, visited, out, seenCycles, tokenIds) {
|
|
129
144
|
const stack = [];
|
|
130
145
|
const onPath = /* @__PURE__ */ new Set();
|
|
131
146
|
const pathOrder = [];
|
|
@@ -158,7 +173,7 @@ function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
|
158
173
|
...pathOrder.slice(cycleStart),
|
|
159
174
|
neighbor
|
|
160
175
|
];
|
|
161
|
-
const key = canonicalCycleKey(cycle);
|
|
176
|
+
const key = canonicalCycleKey(cycle, tokenIds);
|
|
162
177
|
if (!seenCycles.has(key)) {
|
|
163
178
|
seenCycles.add(key);
|
|
164
179
|
out.push(cycle);
|
|
@@ -169,26 +184,27 @@ function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
|
169
184
|
}
|
|
170
185
|
}
|
|
171
186
|
__name(iterativeDfs, "iterativeDfs");
|
|
172
|
-
function canonicalCycleKey(cycle) {
|
|
173
|
-
const
|
|
187
|
+
function canonicalCycleKey(cycle, tokenIds) {
|
|
188
|
+
const ids = cycle.map((token) => {
|
|
189
|
+
let id = tokenIds.get(token);
|
|
190
|
+
if (id === void 0) {
|
|
191
|
+
id = tokenIds.size;
|
|
192
|
+
tokenIds.set(token, id);
|
|
193
|
+
}
|
|
194
|
+
return id;
|
|
195
|
+
});
|
|
174
196
|
let minIndex = 0;
|
|
175
|
-
for (let i = 1; i <
|
|
176
|
-
if (
|
|
197
|
+
for (let i = 1; i < ids.length; i += 1) {
|
|
198
|
+
if (ids[i] < ids[minIndex]) {
|
|
177
199
|
minIndex = i;
|
|
178
200
|
}
|
|
179
201
|
}
|
|
180
202
|
return [
|
|
181
|
-
...
|
|
182
|
-
...
|
|
203
|
+
...ids.slice(minIndex),
|
|
204
|
+
...ids.slice(0, minIndex)
|
|
183
205
|
].join("\u2192");
|
|
184
206
|
}
|
|
185
207
|
__name(canonicalCycleKey, "canonicalCycleKey");
|
|
186
|
-
function stringifyToken(token) {
|
|
187
|
-
if (typeof token === "string") return `s:${token}`;
|
|
188
|
-
if (typeof token === "function") return `c:${token.name ?? "<anon>"}`;
|
|
189
|
-
return "u:<unknown>";
|
|
190
|
-
}
|
|
191
|
-
__name(stringifyToken, "stringifyToken");
|
|
192
208
|
|
|
193
209
|
// src/internal/metadata.ts
|
|
194
210
|
var METADATA_KEYS = {
|
|
@@ -333,7 +349,7 @@ var InvalidModuleError = class extends Error {
|
|
|
333
349
|
target;
|
|
334
350
|
name = "InvalidModuleError";
|
|
335
351
|
constructor(target) {
|
|
336
|
-
super(`Class ${target
|
|
352
|
+
super(`Class ${describeClassName(target, "<anonymous>")} has no @Module() decorator. Add @Module({ providers: [...], imports: [...], exports: [...] }) above the class declaration.`), this.target = target;
|
|
337
353
|
}
|
|
338
354
|
};
|
|
339
355
|
var InvalidExportError = class extends Error {
|
|
@@ -515,11 +531,14 @@ var Container = class {
|
|
|
515
531
|
* try/finally guarantees REQUEST-scoped instances are disposed
|
|
516
532
|
* even if the callback throws.
|
|
517
533
|
*/
|
|
518
|
-
async runInRequest(callback) {
|
|
534
|
+
async runInRequest(callback, options) {
|
|
519
535
|
this.assertNotDisposed();
|
|
536
|
+
const hasSeed = options !== void 0 && Object.hasOwn(options, "seed");
|
|
520
537
|
const store = {
|
|
521
538
|
cache: /* @__PURE__ */ new Map(),
|
|
522
|
-
instances: []
|
|
539
|
+
instances: [],
|
|
540
|
+
seed: hasSeed ? options.seed : void 0,
|
|
541
|
+
hasSeed
|
|
523
542
|
};
|
|
524
543
|
try {
|
|
525
544
|
return await this.requestStorage.run(store, async () => callback());
|
|
@@ -528,6 +547,23 @@ var Container = class {
|
|
|
528
547
|
}
|
|
529
548
|
}
|
|
530
549
|
/**
|
|
550
|
+
* The seed of the active request scope, as passed to
|
|
551
|
+
* `runInRequest(cb, { seed })`.
|
|
552
|
+
*
|
|
553
|
+
* @throws ScopeViolationError outside a request scope.
|
|
554
|
+
* @throws MissingRequestSeedError when the scope was opened without a seed.
|
|
555
|
+
*/
|
|
556
|
+
requestSeed() {
|
|
557
|
+
const store = this.requestStorage.getStore();
|
|
558
|
+
if (store === void 0) {
|
|
559
|
+
throw new ScopeViolationError("requestSeed", "requestSeed() requires container.runInRequest(...) to be active.");
|
|
560
|
+
}
|
|
561
|
+
if (!store.hasSeed) {
|
|
562
|
+
throw new MissingRequestSeedError();
|
|
563
|
+
}
|
|
564
|
+
return store.seed;
|
|
565
|
+
}
|
|
566
|
+
/**
|
|
531
567
|
* Debug helper — returns a snapshot of the dependency graph.
|
|
532
568
|
*
|
|
533
569
|
* Detects cycles in unused providers too (resolve-time
|
|
@@ -778,7 +814,7 @@ var Container = class {
|
|
|
778
814
|
*/
|
|
779
815
|
handlePrimitiveParam(target, paramType, index, isOptional) {
|
|
780
816
|
if (isOptional) return void 0;
|
|
781
|
-
throw new TypeError(`Class ${target.name} has a primitive/interface constructor parameter at index ${index} (emitted as ${paramType
|
|
817
|
+
throw new TypeError(`Class ${target.name} has a primitive/interface constructor parameter at index ${index} (emitted as ${describeClassName(paramType, "<unknown>")}). Primitives and interfaces cannot be auto-resolved \u2014 use \`@Inject('SOME_STRING_TOKEN')\` to provide an explicit token.`);
|
|
782
818
|
}
|
|
783
819
|
/**
|
|
784
820
|
* Attempt sync resolution. Returns `{ args }` on success, `{ needsAsync: true }`
|
|
@@ -1135,6 +1171,6 @@ function Qualifier(name) {
|
|
|
1135
1171
|
}
|
|
1136
1172
|
__name(Qualifier, "Qualifier");
|
|
1137
1173
|
|
|
1138
|
-
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, Container, ContainerDisposedError, ContainerFrozenError, CyclicDependencyError, CyclicModuleImportError, Inject, Injectable, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, Module, Optional, PostConstruct, PreDestroy, Primary, Qualifier, ReflectMetadataMissingError, Scope, ScopeViolationError, TokenNotFoundError, describeToken };
|
|
1174
|
+
export { AsyncPostConstructInSyncResolveError, AsyncProviderInSyncResolveError, Container, ContainerDisposedError, ContainerFrozenError, CyclicDependencyError, CyclicModuleImportError, Inject, Injectable, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, MissingRequestSeedError, Module, Optional, PostConstruct, PreDestroy, Primary, Qualifier, ReflectMetadataMissingError, Scope, ScopeViolationError, TokenNotFoundError, describeClassName, describeToken };
|
|
1139
1175
|
//# sourceMappingURL=index.js.map
|
|
1140
1176
|
//# sourceMappingURL=index.js.map
|