@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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 12e1f8a: The workspace declares `0.3.0`, the first release with `requestSeed`, so the `@theokit/di` peer range
|
|
8
|
+
of `@theokit/di-agent` (`>=0.3.0 <0.4`) is satisfied by what the workspace installs. The release
|
|
9
|
+
publishes 0.3.1.
|
|
10
|
+
- c03efc6: `Container.runInRequest(callback, { seed })` carries a per-request value, read with
|
|
11
|
+
`container.requestSeed<T>()`. It throws `ScopeViolationError` outside a request and the new
|
|
12
|
+
`MissingRequestSeedError` when the request was opened without a seed. Calls without options behave
|
|
13
|
+
as before (usetheokit/theokit-di#80).
|
|
14
|
+
|
|
15
|
+
## 0.2.1
|
|
16
|
+
|
|
17
|
+
### Patch Changes
|
|
18
|
+
|
|
19
|
+
- 8e59fec: Name an anonymous class `<anonymous>` in diagnostics instead of rendering nothing.
|
|
20
|
+
|
|
21
|
+
Four call sites wrote a class name as `target.name ?? "<anonymous>"`, and that fallback could never
|
|
22
|
+
fire: an anonymous class has `name === ""`, not an absent one, and `"" ?? x` is `""`. A consumer who
|
|
23
|
+
passed a class expression read `Class has no @Module() decorator.` — two spaces where the identity
|
|
24
|
+
belongs, and nothing to search the codebase for. `MissingInjectableError`, `InvalidModuleError`, the
|
|
25
|
+
`emitted as ...` hint in constructor-parameter diagnostics and the cycle labels in `analyze()` are
|
|
26
|
+
all affected.
|
|
27
|
+
|
|
28
|
+
`describeToken` in the same file had the check right all along (`name.length > 0`); the other sites
|
|
29
|
+
had drifted from it. The knowledge now lives in one exported helper, `describeClassName`.
|
|
30
|
+
|
|
31
|
+
- 452d6ba: `analyze()` no longer drops a cycle when two classes share a name.
|
|
32
|
+
|
|
33
|
+
`findCycles` de-duplicated cycles by the token's RENDERING rather than by the token, so two different
|
|
34
|
+
classes with the same `name` produced the same key and the second cycle was discarded as a duplicate
|
|
35
|
+
of the first. Two files each declaring `class Logger` and `class Service` was enough to trigger it, as
|
|
36
|
+
was any two anonymous classes or any two symbol tokens: `analyze()` reported one cycle, and nothing
|
|
37
|
+
said the other had been dropped. A consumer debugging a cyclic dependency fixed the loop they were
|
|
38
|
+
shown and met the next one on the following run.
|
|
39
|
+
|
|
40
|
+
Cycles are now keyed on an identity table. The rotation that makes the key independent of which node
|
|
41
|
+
the walk entered on is unchanged.
|
|
42
|
+
|
|
3
43
|
All notable changes to `@theokit/di` are documented in this file.
|
|
4
44
|
|
|
5
45
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
@@ -7,6 +47,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
47
|
|
|
8
48
|
## [Unreleased]
|
|
9
49
|
|
|
50
|
+
### Fixed
|
|
51
|
+
|
|
52
|
+
- `analyze()` no longer drops a cycle when two classes share a name. Cycles were de-duplicated by the
|
|
53
|
+
token's rendering rather than by the token, so two different classes called `Logger` keyed
|
|
54
|
+
identically and the second cycle was discarded as a duplicate of the first — one cycle reported,
|
|
55
|
+
and nothing to say the other existed. Two anonymous classes and two symbol tokens collided the same
|
|
56
|
+
way. The key is built from an identity table now (#59).
|
|
57
|
+
|
|
58
|
+
- An anonymous class in an error message is now named `<anonymous>` instead of nothing at all.
|
|
59
|
+
Four diagnostics rendered a class name as `target.name ?? "<anonymous>"`, and that fallback can
|
|
60
|
+
never fire — an anonymous class has `name === ""`, not an absent one, so `??` passes the empty
|
|
61
|
+
string straight through. A consumer who passed a class expression read `Class has no @Module()
|
|
62
|
+
decorator.`, with two spaces where the identity belongs and nothing to search for. Affects
|
|
63
|
+
`MissingInjectableError`, `InvalidModuleError`, the `emitted as ...` hint in the container's
|
|
64
|
+
parameter diagnostics, and cycle labels in `analyze()` (#57).
|
|
65
|
+
|
|
66
|
+
### Added
|
|
67
|
+
|
|
68
|
+
- `describeClassName(target, fallback)` is exported alongside `describeToken`. The four sites above
|
|
69
|
+
had each written their own version of "a class's display name, with a fallback"; `describeToken`
|
|
70
|
+
was the only one that got it right, and now it is the only one that states it (#57).
|
|
71
|
+
|
|
10
72
|
## [0.2.0] - 2026-08-21
|
|
11
73
|
|
|
12
74
|
### Added
|
|
@@ -43,7 +105,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
43
105
|
- `@Primary` and `@Qualifier` documented a resolution priority the container has never had. They record metadata and nothing else, and their JSDoc now says exactly that, with the working alternative alongside. Implementing them means holding several registrations per token — which is the cache key, the cycle-detection node identity and the disposal order — so it is a design decision rather than a missing branch, and it has not been made (#5).
|
|
44
106
|
- The English-only lint gate could not fail on an accented word. It split identifiers with an ASCII-only pattern before testing them for diacritics, so `não` became `n` and `o` and the diacritic tier was unreachable. Both tiers now work, verified by planting an accented identifier and watching the sweep turn red (#7).
|
|
45
107
|
|
|
46
|
-
|
|
47
108
|
## 0.1.1
|
|
48
109
|
|
|
49
110
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -56,6 +56,30 @@ const greeter = container.resolve(GreeterService);
|
|
|
56
56
|
console.log(greeter.greet("world")); // Hello, world!
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
+
## Request seed
|
|
60
|
+
|
|
61
|
+
`runInRequest` accepts a seed, the value the request serves (an inbound message, an HTTP request, a
|
|
62
|
+
session key). Read it with `container.requestSeed()` from any REQUEST-scoped factory or code running
|
|
63
|
+
inside the request. Nested requests each see their own seed.
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
import { Container, Scope } from "@theokit/di";
|
|
67
|
+
|
|
68
|
+
const container = new Container();
|
|
69
|
+
container.register({
|
|
70
|
+
provide: "session",
|
|
71
|
+
useFactory: () => ({ key: container.requestSeed<string>() }),
|
|
72
|
+
scope: Scope.REQUEST,
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
const session = await container.runInRequest(() => container.resolveAsync("session"), {
|
|
76
|
+
seed: "user-42",
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`requestSeed()` throws `ScopeViolationError` outside a request, and `MissingRequestSeedError` in a
|
|
81
|
+
request opened without `{ seed }`.
|
|
82
|
+
|
|
59
83
|
## Polyglot strategy
|
|
60
84
|
|
|
61
85
|
`@theokit/di` is **intentionally TS-only**. DI containers are language-specific runtime constructs — Python uses `inspect`/`typing.get_type_hints`, Go uses `reflect`, etc. The cross-language story for the theokit ecosystem lives in the **contract layer** (OpenAPI from `@theokit/http`, SQL migrations + JSON schemas from `@theokit/orm`), not in the container.
|
package/dist/index.cjs
CHANGED
|
@@ -16,6 +16,11 @@ function describeToken(token) {
|
|
|
16
16
|
return "<unknown token>";
|
|
17
17
|
}
|
|
18
18
|
__name(describeToken, "describeToken");
|
|
19
|
+
function describeClassName(target, fallback) {
|
|
20
|
+
const name = target?.name;
|
|
21
|
+
return typeof name === "string" && name.length > 0 ? name : fallback;
|
|
22
|
+
}
|
|
23
|
+
__name(describeClassName, "describeClassName");
|
|
19
24
|
var TokenNotFoundError = class extends Error {
|
|
20
25
|
static {
|
|
21
26
|
__name(this, "TokenNotFoundError");
|
|
@@ -70,6 +75,15 @@ var ScopeViolationError = class extends Error {
|
|
|
70
75
|
super(`Scope violation for token ${describeToken(token)}: ${message}`), this.token = token;
|
|
71
76
|
}
|
|
72
77
|
};
|
|
78
|
+
var MissingRequestSeedError = class extends Error {
|
|
79
|
+
static {
|
|
80
|
+
__name(this, "MissingRequestSeedError");
|
|
81
|
+
}
|
|
82
|
+
name = "MissingRequestSeedError";
|
|
83
|
+
constructor() {
|
|
84
|
+
super("The active request scope has no seed. Pass { seed } to runInRequest: container.runInRequest(cb, { seed }).");
|
|
85
|
+
}
|
|
86
|
+
};
|
|
73
87
|
var MissingInjectableError = class extends Error {
|
|
74
88
|
static {
|
|
75
89
|
__name(this, "MissingInjectableError");
|
|
@@ -77,7 +91,7 @@ var MissingInjectableError = class extends Error {
|
|
|
77
91
|
target;
|
|
78
92
|
name = "MissingInjectableError";
|
|
79
93
|
constructor(target) {
|
|
80
|
-
super(`Class ${target
|
|
94
|
+
super(`Class ${describeClassName(target, "<anonymous>")} has no @Injectable() decorator. Add @Injectable() above the class declaration before registering it.`), this.target = target;
|
|
81
95
|
}
|
|
82
96
|
};
|
|
83
97
|
var ContainerDisposedError = class extends Error {
|
|
@@ -120,14 +134,15 @@ function findCycles(snapshot) {
|
|
|
120
134
|
const cycles = [];
|
|
121
135
|
const seenCycles = /* @__PURE__ */ new Set();
|
|
122
136
|
const visited = /* @__PURE__ */ new Set();
|
|
137
|
+
const tokenIds = /* @__PURE__ */ new Map();
|
|
123
138
|
for (const node of snapshot.nodes) {
|
|
124
139
|
if (visited.has(node.token)) continue;
|
|
125
|
-
iterativeDfs(node.token, adjacency, visited, cycles, seenCycles);
|
|
140
|
+
iterativeDfs(node.token, adjacency, visited, cycles, seenCycles, tokenIds);
|
|
126
141
|
}
|
|
127
142
|
return cycles;
|
|
128
143
|
}
|
|
129
144
|
__name(findCycles, "findCycles");
|
|
130
|
-
function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
145
|
+
function iterativeDfs(root, adjacency, visited, out, seenCycles, tokenIds) {
|
|
131
146
|
const stack = [];
|
|
132
147
|
const onPath = /* @__PURE__ */ new Set();
|
|
133
148
|
const pathOrder = [];
|
|
@@ -160,7 +175,7 @@ function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
|
160
175
|
...pathOrder.slice(cycleStart),
|
|
161
176
|
neighbor
|
|
162
177
|
];
|
|
163
|
-
const key = canonicalCycleKey(cycle);
|
|
178
|
+
const key = canonicalCycleKey(cycle, tokenIds);
|
|
164
179
|
if (!seenCycles.has(key)) {
|
|
165
180
|
seenCycles.add(key);
|
|
166
181
|
out.push(cycle);
|
|
@@ -171,26 +186,27 @@ function iterativeDfs(root, adjacency, visited, out, seenCycles) {
|
|
|
171
186
|
}
|
|
172
187
|
}
|
|
173
188
|
__name(iterativeDfs, "iterativeDfs");
|
|
174
|
-
function canonicalCycleKey(cycle) {
|
|
175
|
-
const
|
|
189
|
+
function canonicalCycleKey(cycle, tokenIds) {
|
|
190
|
+
const ids = cycle.map((token) => {
|
|
191
|
+
let id = tokenIds.get(token);
|
|
192
|
+
if (id === void 0) {
|
|
193
|
+
id = tokenIds.size;
|
|
194
|
+
tokenIds.set(token, id);
|
|
195
|
+
}
|
|
196
|
+
return id;
|
|
197
|
+
});
|
|
176
198
|
let minIndex = 0;
|
|
177
|
-
for (let i = 1; i <
|
|
178
|
-
if (
|
|
199
|
+
for (let i = 1; i < ids.length; i += 1) {
|
|
200
|
+
if (ids[i] < ids[minIndex]) {
|
|
179
201
|
minIndex = i;
|
|
180
202
|
}
|
|
181
203
|
}
|
|
182
204
|
return [
|
|
183
|
-
...
|
|
184
|
-
...
|
|
205
|
+
...ids.slice(minIndex),
|
|
206
|
+
...ids.slice(0, minIndex)
|
|
185
207
|
].join("\u2192");
|
|
186
208
|
}
|
|
187
209
|
__name(canonicalCycleKey, "canonicalCycleKey");
|
|
188
|
-
function stringifyToken(token) {
|
|
189
|
-
if (typeof token === "string") return `s:${token}`;
|
|
190
|
-
if (typeof token === "function") return `c:${token.name ?? "<anon>"}`;
|
|
191
|
-
return "u:<unknown>";
|
|
192
|
-
}
|
|
193
|
-
__name(stringifyToken, "stringifyToken");
|
|
194
210
|
|
|
195
211
|
// src/internal/metadata.ts
|
|
196
212
|
var METADATA_KEYS = {
|
|
@@ -335,7 +351,7 @@ var InvalidModuleError = class extends Error {
|
|
|
335
351
|
target;
|
|
336
352
|
name = "InvalidModuleError";
|
|
337
353
|
constructor(target) {
|
|
338
|
-
super(`Class ${target
|
|
354
|
+
super(`Class ${describeClassName(target, "<anonymous>")} has no @Module() decorator. Add @Module({ providers: [...], imports: [...], exports: [...] }) above the class declaration.`), this.target = target;
|
|
339
355
|
}
|
|
340
356
|
};
|
|
341
357
|
var InvalidExportError = class extends Error {
|
|
@@ -517,11 +533,14 @@ var Container = class {
|
|
|
517
533
|
* try/finally guarantees REQUEST-scoped instances are disposed
|
|
518
534
|
* even if the callback throws.
|
|
519
535
|
*/
|
|
520
|
-
async runInRequest(callback) {
|
|
536
|
+
async runInRequest(callback, options) {
|
|
521
537
|
this.assertNotDisposed();
|
|
538
|
+
const hasSeed = options !== void 0 && Object.hasOwn(options, "seed");
|
|
522
539
|
const store = {
|
|
523
540
|
cache: /* @__PURE__ */ new Map(),
|
|
524
|
-
instances: []
|
|
541
|
+
instances: [],
|
|
542
|
+
seed: hasSeed ? options.seed : void 0,
|
|
543
|
+
hasSeed
|
|
525
544
|
};
|
|
526
545
|
try {
|
|
527
546
|
return await this.requestStorage.run(store, async () => callback());
|
|
@@ -530,6 +549,23 @@ var Container = class {
|
|
|
530
549
|
}
|
|
531
550
|
}
|
|
532
551
|
/**
|
|
552
|
+
* The seed of the active request scope, as passed to
|
|
553
|
+
* `runInRequest(cb, { seed })`.
|
|
554
|
+
*
|
|
555
|
+
* @throws ScopeViolationError outside a request scope.
|
|
556
|
+
* @throws MissingRequestSeedError when the scope was opened without a seed.
|
|
557
|
+
*/
|
|
558
|
+
requestSeed() {
|
|
559
|
+
const store = this.requestStorage.getStore();
|
|
560
|
+
if (store === void 0) {
|
|
561
|
+
throw new ScopeViolationError("requestSeed", "requestSeed() requires container.runInRequest(...) to be active.");
|
|
562
|
+
}
|
|
563
|
+
if (!store.hasSeed) {
|
|
564
|
+
throw new MissingRequestSeedError();
|
|
565
|
+
}
|
|
566
|
+
return store.seed;
|
|
567
|
+
}
|
|
568
|
+
/**
|
|
533
569
|
* Debug helper — returns a snapshot of the dependency graph.
|
|
534
570
|
*
|
|
535
571
|
* Detects cycles in unused providers too (resolve-time
|
|
@@ -780,7 +816,7 @@ var Container = class {
|
|
|
780
816
|
*/
|
|
781
817
|
handlePrimitiveParam(target, paramType, index, isOptional) {
|
|
782
818
|
if (isOptional) return void 0;
|
|
783
|
-
throw new TypeError(`Class ${target.name} has a primitive/interface constructor parameter at index ${index} (emitted as ${paramType
|
|
819
|
+
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.`);
|
|
784
820
|
}
|
|
785
821
|
/**
|
|
786
822
|
* Attempt sync resolution. Returns `{ args }` on success, `{ needsAsync: true }`
|
|
@@ -1150,6 +1186,7 @@ exports.InvalidExportError = InvalidExportError;
|
|
|
1150
1186
|
exports.InvalidModuleError = InvalidModuleError;
|
|
1151
1187
|
exports.METADATA_KEYS = METADATA_KEYS;
|
|
1152
1188
|
exports.MissingInjectableError = MissingInjectableError;
|
|
1189
|
+
exports.MissingRequestSeedError = MissingRequestSeedError;
|
|
1153
1190
|
exports.Module = Module;
|
|
1154
1191
|
exports.Optional = Optional;
|
|
1155
1192
|
exports.PostConstruct = PostConstruct;
|
|
@@ -1160,6 +1197,7 @@ exports.ReflectMetadataMissingError = ReflectMetadataMissingError;
|
|
|
1160
1197
|
exports.Scope = Scope;
|
|
1161
1198
|
exports.ScopeViolationError = ScopeViolationError;
|
|
1162
1199
|
exports.TokenNotFoundError = TokenNotFoundError;
|
|
1200
|
+
exports.describeClassName = describeClassName;
|
|
1163
1201
|
exports.describeToken = describeToken;
|
|
1164
1202
|
//# sourceMappingURL=index.cjs.map
|
|
1165
1203
|
//# sourceMappingURL=index.cjs.map
|