@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 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.name ?? "<anonymous>"} has no @Injectable() decorator. Add @Injectable() above the class declaration before registering it.`), this.target = 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 strs = cycle.map(stringifyToken);
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 < strs.length; i += 1) {
178
- if (strs[i] < strs[minIndex]) {
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
- ...strs.slice(minIndex),
184
- ...strs.slice(0, minIndex)
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.name ?? "<anonymous>"} has no @Module() decorator. Add @Module({ providers: [...], imports: [...], exports: [...] }) above the class declaration.`), this.target = 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.name ?? "<unknown>"}). Primitives and interfaces cannot be auto-resolved \u2014 use \`@Inject('SOME_STRING_TOKEN')\` to provide an explicit token.`);
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