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