@theokit/di 0.1.1 → 0.2.0

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.js CHANGED
@@ -47,6 +47,17 @@ var AsyncProviderInSyncResolveError = class extends Error {
47
47
  super(`Provider for token ${describeToken(token)} is async (factory returned a Promise). Use container.resolveAsync() instead of container.resolve().`), this.token = token;
48
48
  }
49
49
  };
50
+ var AsyncPostConstructInSyncResolveError = class extends Error {
51
+ static {
52
+ __name(this, "AsyncPostConstructInSyncResolveError");
53
+ }
54
+ className;
55
+ methodName;
56
+ name = "AsyncPostConstructInSyncResolveError";
57
+ constructor(className, methodName) {
58
+ super(`@PostConstruct ${className}.${methodName}() returned a Promise, and container.resolve() cannot await it. Use container.resolveAsync() instead, or make ${methodName}() synchronous.`), this.className = className, this.methodName = methodName;
59
+ }
60
+ };
50
61
  var ScopeViolationError = class extends Error {
51
62
  static {
52
63
  __name(this, "ScopeViolationError");
@@ -205,7 +216,7 @@ var METADATA_KEYS = {
205
216
  SQUAD: "usetheo:di:squad",
206
217
  /** Map<string|symbol, StepMetadata> from `@Step()` method decorator. */
207
218
  STEP: "usetheo:di:step",
208
- /** HitlOptions from `@Hitl()` method decorator. */
219
+ /** Map<string|symbol, HitlMetadata> from `@Hitl()` method decorator. */
209
220
  HITL: "usetheo:di:hitl",
210
221
  /** AutoSummarizeConfig from `@AutoSummarize()` class decorator. */
211
222
  AUTO_SUMMARIZE: "usetheo:di:auto-summarize",
@@ -215,7 +226,7 @@ var METADATA_KEYS = {
215
226
  WORKFLOW: "usetheo:di:workflow",
216
227
  /** EvalOptions from `@Eval()` class decorator. */
217
228
  EVAL: "usetheo:di:eval",
218
- /** CronMetadata from `@Cron()` method decorator. */
229
+ /** Map<string|symbol, CronMetadata> from `@Cron()` method decorator. */
219
230
  CRON: "usetheo:di:cron",
220
231
  /** Map<string|symbol, SubscriptionOptions> from `@Subscription()` property decorator. */
221
232
  SUBSCRIPTION: "usetheo:di:subscription",
@@ -267,6 +278,21 @@ function isInjectable(target) {
267
278
  return readInjectableMetadata(target) !== void 0;
268
279
  }
269
280
  __name(isInjectable, "isInjectable");
281
+ function readPostConstruct(target) {
282
+ return readLifecycleHook(target, METADATA_KEYS.POST_CONSTRUCT);
283
+ }
284
+ __name(readPostConstruct, "readPostConstruct");
285
+ function readPreDestroy(target) {
286
+ return readLifecycleHook(target, METADATA_KEYS.PRE_DESTROY);
287
+ }
288
+ __name(readPreDestroy, "readPreDestroy");
289
+ function readLifecycleHook(target, key) {
290
+ if (!hasReflectMetadata()) return void 0;
291
+ const out = Reflect.getMetadata(key, target);
292
+ if (typeof out === "string" || typeof out === "symbol") return out;
293
+ return void 0;
294
+ }
295
+ __name(readLifecycleHook, "readLifecycleHook");
270
296
  var PRIMITIVE_WRAPPERS = /* @__PURE__ */ new Set([
271
297
  Number,
272
298
  String,
@@ -397,6 +423,11 @@ var Scope = {
397
423
  };
398
424
 
399
425
  // src/container.ts
426
+ var ASYNC_CONTEXT = /* @__PURE__ */ Symbol("theokit.di.asyncContext");
427
+ function isAsyncContext(ctx) {
428
+ return ctx[ASYNC_CONTEXT] === true;
429
+ }
430
+ __name(isAsyncContext, "isAsyncContext");
400
431
  var Container = class {
401
432
  static {
402
433
  __name(this, "Container");
@@ -422,7 +453,7 @@ var Container = class {
422
453
  * - A full Provider (useClass / useFactory / useValue / useExisting)
423
454
  * - A bare class (shorthand expands to ClassProvider { provide: X, useClass: X })
424
455
  *
425
- * Per v1.1 EC-1, ClassProvider validation runs via `validateClassProvider()`
456
+ * ClassProvider validation runs via `validateClassProvider()`
426
457
  * regardless of which API path was used.
427
458
  */
428
459
  register(providerOrClass) {
@@ -442,9 +473,9 @@ var Container = class {
442
473
  * modules. Walks imports BFS, registers every provider, validates
443
474
  * exports.
444
475
  *
445
- * Per v1.1 EC-4: undecorated class throws `InvalidModuleError`.
446
- * Per v1.2 EC-R2-5: respects the freeze-after-first-resolve guarantee
447
- * (each child `register()` checks `assertNotFrozen`).
476
+ * An undecorated class throws `InvalidModuleError`. Respects the
477
+ * freeze-after-first-resolve guarantee — each child `register()` checks
478
+ * `assertNotFrozen`.
448
479
  */
449
480
  registerModule(moduleClass) {
450
481
  this.assertNotDisposed();
@@ -481,7 +512,7 @@ var Container = class {
481
512
  * providers resolved within `callback` (or any async continuation) share
482
513
  * a single per-request cache.
483
514
  *
484
- * v1.1 EC-3: try/finally guarantees REQUEST-scoped instances are disposed
515
+ * try/finally guarantees REQUEST-scoped instances are disposed
485
516
  * even if the callback throws.
486
517
  */
487
518
  async runInRequest(callback) {
@@ -499,7 +530,7 @@ var Container = class {
499
530
  /**
500
531
  * Debug helper — returns a snapshot of the dependency graph.
501
532
  *
502
- * Per ADR D7: detects cycles in unused providers too (resolve-time
533
+ * Detects cycles in unused providers too (resolve-time
503
534
  * detection only fires for resolves that actually traverse the cycle).
504
535
  * Use this proactively in tests / dev mode to surface latent cycles.
505
536
  */
@@ -600,7 +631,7 @@ var Container = class {
600
631
  }
601
632
  }
602
633
  /**
603
- * v1.1 EC-1: shared by both declarative providers: [] AND imperative
634
+ * Shared by both declarative providers: [] AND imperative
604
635
  * register() — every class provider must have @Injectable().
605
636
  */
606
637
  validateClassProvider(provider) {
@@ -615,7 +646,7 @@ var Container = class {
615
646
  if (this.disposed) throw new ContainerDisposedError();
616
647
  }
617
648
  /**
618
- * v1.2 EC-R2-5: container freezes on first resolve. Late registrations
649
+ * The container freezes on first resolve. Late registrations
619
650
  * require explicit `allowDynamicRegistration: true` (testing escape hatch).
620
651
  */
621
652
  assertNotFrozen(token) {
@@ -646,7 +677,8 @@ var Container = class {
646
677
  token: provider.provide,
647
678
  scope,
648
679
  factory: /* @__PURE__ */ __name((ctx) => this.constructClassWithAsyncFallback(target, ctx), "factory"),
649
- classTarget: target
680
+ classTarget: target,
681
+ containerOwned: true
650
682
  };
651
683
  }
652
684
  fromFactoryProvider(provider) {
@@ -661,7 +693,8 @@ var Container = class {
661
693
  }
662
694
  return Promise.all(injectTokens.map((dep) => ctx.resolveAsync(dep))).then((asyncArgs) => provider.useFactory(...asyncArgs));
663
695
  }, "factory"),
664
- injectTokens
696
+ injectTokens,
697
+ containerOwned: true
665
698
  };
666
699
  }
667
700
  /**
@@ -692,7 +725,8 @@ var Container = class {
692
725
  return {
693
726
  token: provider.provide,
694
727
  scope: Scope.SINGLETON,
695
- factory: /* @__PURE__ */ __name(() => provider.useValue, "factory")
728
+ factory: /* @__PURE__ */ __name(() => provider.useValue, "factory"),
729
+ containerOwned: false
696
730
  };
697
731
  }
698
732
  fromExistingProvider(provider) {
@@ -700,15 +734,16 @@ var Container = class {
700
734
  token: provider.provide,
701
735
  scope: Scope.SINGLETON,
702
736
  factory: /* @__PURE__ */ __name((ctx) => ctx.resolve(provider.useExisting), "factory"),
703
- aliasTarget: provider.useExisting
737
+ aliasTarget: provider.useExisting,
738
+ containerOwned: false
704
739
  };
705
740
  }
706
741
  /**
707
742
  * Resolve constructor params + build instance. Tries sync first; if any
708
743
  * dep is async, falls back to awaiting via `resolveAsync`.
709
744
  *
710
- * Refactored via Extract Method (ADR D422): orchestrates 3 helpers:
711
- * - validateMetadata: EC-12 detect emitDecoratorMetadata off
745
+ * Refactored via Extract Method: orchestrates 3 helpers:
746
+ * - validateMetadata: detect emitDecoratorMetadata off
712
747
  * - tryResolveSync: sync resolution loop with AsyncProvider bailout
713
748
  * - resolveAllAsync: Promise.all fallback when any dep is async
714
749
  */
@@ -722,12 +757,13 @@ var Container = class {
722
757
  this.validateMetadata(target, paramTypes);
723
758
  const syncResult = this.tryResolveSync(target, paramTypes, injectTokens, optionalFlags, ctx);
724
759
  if ("args" in syncResult) {
725
- return new target(...syncResult.args);
760
+ const instance = new target(...syncResult.args);
761
+ return isAsyncContext(ctx) ? runPostConstructAsync(target, instance) : runPostConstructSync(target, instance);
726
762
  }
727
- return this.resolveAllAsync(target, paramTypes, injectTokens, optionalFlags, ctx);
763
+ return this.resolveAllAsync(target, paramTypes, injectTokens, optionalFlags, ctx).then((instance) => runPostConstructAsync(target, instance));
728
764
  }
729
765
  /**
730
- * EC-12 detection: zero paramTypes for a class that declares a non-empty
766
+ * Detection: zero paramTypes for a class that declares a non-empty
731
767
  * constructor strongly suggests emitDecoratorMetadata is off.
732
768
  */
733
769
  validateMetadata(target, paramTypes) {
@@ -834,14 +870,14 @@ var Container = class {
834
870
  this.storeInCache(token, value, registration.scope);
835
871
  value.then((resolved) => {
836
872
  this.storeInCache(token, resolved, registration.scope);
837
- this.trackInstance(resolved, registration.scope);
873
+ this.trackInstance(resolved, registration);
838
874
  }, () => {
839
875
  this.deleteFromCache(token, registration.scope);
840
876
  });
841
877
  throw new AsyncProviderInSyncResolveError(token);
842
878
  }
843
879
  this.storeInCache(token, value, registration.scope);
844
- this.trackInstance(value, registration.scope);
880
+ this.trackInstance(value, registration);
845
881
  return value;
846
882
  }
847
883
  // ─────────────────────────────────────────────────────────────────────
@@ -874,14 +910,14 @@ var Container = class {
874
910
  this.storeInCache(token, result, registration.scope);
875
911
  result.then((value) => {
876
912
  this.storeInCache(token, value, registration.scope);
877
- this.trackInstance(value, registration.scope);
913
+ this.trackInstance(value, registration);
878
914
  }, () => {
879
915
  this.deleteFromCache(token, registration.scope);
880
916
  });
881
917
  return result;
882
918
  }
883
919
  this.storeInCache(token, result, registration.scope);
884
- this.trackInstance(result, registration.scope);
920
+ this.trackInstance(result, registration);
885
921
  return result;
886
922
  }
887
923
  // ─────────────────────────────────────────────────────────────────────
@@ -916,8 +952,18 @@ var Container = class {
916
952
  store?.cache.delete(token);
917
953
  }
918
954
  }
919
- trackInstance(value, scope) {
920
- if (!isDisposable(value)) return;
955
+ /**
956
+ * Record an instance for teardown, when this container is the one that should tear it down.
957
+ *
958
+ * Two questions, in this order. Does the container OWN it — see `containerOwned`; a value the
959
+ * caller handed in and an instance reached through an alias are both refused here. And does it
960
+ * have any teardown at all: a class whose only teardown is `@PreDestroy` has no `dispose()`, so
961
+ * testing `isDisposable` alone would silently skip it.
962
+ */
963
+ trackInstance(value, registration) {
964
+ if (!registration.containerOwned) return;
965
+ const { scope } = registration;
966
+ if (!isDisposable(value) && !hasPreDestroy(value)) return;
921
967
  if (scope === Scope.SINGLETON) {
922
968
  this.singletonInstances.push(value);
923
969
  return;
@@ -943,11 +989,14 @@ var Container = class {
943
989
  };
944
990
  }
945
991
  createContextAsync(path) {
946
- return {
992
+ const ctx = {
947
993
  path,
948
994
  resolve: /* @__PURE__ */ __name((t) => this.resolveInContext(t, this.createContext(path)), "resolve"),
949
995
  resolveAsync: /* @__PURE__ */ __name((t) => this.resolveAsyncInContext(t, this.createContextAsync(path)), "resolveAsync")
950
996
  };
997
+ return Object.assign(ctx, {
998
+ [ASYNC_CONTEXT]: true
999
+ });
951
1000
  }
952
1001
  // ─────────────────────────────────────────────────────────────────────
953
1002
  // Internal: disposal
@@ -958,10 +1007,11 @@ var Container = class {
958
1007
  const instance = instances[i];
959
1008
  if (instance === void 0) continue;
960
1009
  try {
1010
+ await callPreDestroy(instance);
961
1011
  const asAsync = instance[Symbol.asyncDispose];
962
1012
  if (typeof asAsync === "function") {
963
1013
  await asAsync.call(instance);
964
- } else {
1014
+ } else if (isDisposable(instance)) {
965
1015
  await instance.dispose();
966
1016
  }
967
1017
  } catch (err) {
@@ -982,6 +1032,49 @@ function isDisposable(value) {
982
1032
  return false;
983
1033
  }
984
1034
  __name(isDisposable, "isDisposable");
1035
+ function callPostConstruct(target, instance) {
1036
+ const hook = readPostConstruct(target);
1037
+ if (hook === void 0) return void 0;
1038
+ const method = instance[hook];
1039
+ if (typeof method !== "function") return void 0;
1040
+ return method.call(instance);
1041
+ }
1042
+ __name(callPostConstruct, "callPostConstruct");
1043
+ function runPostConstructSync(target, instance) {
1044
+ const returned = callPostConstruct(target, instance);
1045
+ if (isThenable(returned)) {
1046
+ throw new AsyncPostConstructInSyncResolveError(target.name, String(readPostConstruct(target)));
1047
+ }
1048
+ return instance;
1049
+ }
1050
+ __name(runPostConstructSync, "runPostConstructSync");
1051
+ async function runPostConstructAsync(target, instance) {
1052
+ const returned = callPostConstruct(target, instance);
1053
+ if (isThenable(returned)) await returned;
1054
+ return instance;
1055
+ }
1056
+ __name(runPostConstructAsync, "runPostConstructAsync");
1057
+ async function callPreDestroy(instance) {
1058
+ const ctor = instance.constructor;
1059
+ if (typeof ctor !== "function") return;
1060
+ const hook = readPreDestroy(ctor);
1061
+ if (hook === void 0) return;
1062
+ const method = instance[hook];
1063
+ if (typeof method !== "function") return;
1064
+ await method.call(instance);
1065
+ }
1066
+ __name(callPreDestroy, "callPreDestroy");
1067
+ function hasPreDestroy(value) {
1068
+ if (value === null || typeof value !== "object") return false;
1069
+ const ctor = value.constructor;
1070
+ if (typeof ctor !== "function") return false;
1071
+ return readPreDestroy(ctor) !== void 0;
1072
+ }
1073
+ __name(hasPreDestroy, "hasPreDestroy");
1074
+ function isThenable(value) {
1075
+ return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
1076
+ }
1077
+ __name(isThenable, "isThenable");
985
1078
 
986
1079
  // src/decorators/inject.ts
987
1080
  function Inject(token) {
@@ -1042,6 +1135,6 @@ function Qualifier(name) {
1042
1135
  }
1043
1136
  __name(Qualifier, "Qualifier");
1044
1137
 
1045
- export { AsyncProviderInSyncResolveError, Container, ContainerDisposedError, ContainerFrozenError, CyclicDependencyError, CyclicModuleImportError, Inject, Injectable, InvalidExportError, InvalidModuleError, METADATA_KEYS, MissingInjectableError, Module, Optional, PostConstruct, PreDestroy, Primary, Qualifier, ReflectMetadataMissingError, Scope, ScopeViolationError, TokenNotFoundError, describeToken };
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 };
1046
1139
  //# sourceMappingURL=index.js.map
1047
1140
  //# sourceMappingURL=index.js.map