@codefast/di 0.12.0 → 0.14.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.
Files changed (54) hide show
  1. package/CHANGELOG.md +192 -0
  2. package/README.md +142 -43
  3. package/dist/ambient-container.d.ts +46 -0
  4. package/dist/ambient-container.js +72 -1
  5. package/dist/container/binding-chain.js +3 -3
  6. package/dist/container/container.d.ts +41 -30
  7. package/dist/container/container.js +59 -243
  8. package/dist/container/introspect.d.ts +47 -0
  9. package/dist/container/introspect.js +53 -0
  10. package/dist/core/binding-builders.d.ts +27 -3
  11. package/dist/core/binding-declaration.d.ts +2 -2
  12. package/dist/core/binding-declaration.js +4 -4
  13. package/dist/core/module.d.ts +4 -25
  14. package/dist/core/module.js +3 -27
  15. package/dist/core/state-epoch.d.ts +1 -1
  16. package/dist/core/state-epoch.js +1 -1
  17. package/dist/core/types.d.ts +16 -7
  18. package/dist/decorators/inject.d.ts +3 -1
  19. package/dist/decorators/inject.js +27 -22
  20. package/dist/decorators/injectable.d.ts +14 -18
  21. package/dist/decorators/injectable.js +23 -2
  22. package/dist/decorators/lifecycle.d.ts +9 -3
  23. package/dist/decorators/lifecycle.js +5 -1
  24. package/dist/errors.d.ts +33 -15
  25. package/dist/errors.js +41 -21
  26. package/dist/index.d.ts +9 -8
  27. package/dist/index.js +4 -3
  28. package/dist/injection/dependency-slot.d.ts +17 -0
  29. package/dist/injection/dependency-slot.js +46 -0
  30. package/dist/injection/descriptor.d.ts +9 -3
  31. package/dist/injection/descriptor.js +10 -1
  32. package/dist/introspection/explanation.js +26 -8
  33. package/dist/introspection/validation.d.ts +28 -0
  34. package/dist/introspection/validation.js +244 -0
  35. package/dist/lifecycle/hooks.d.ts +13 -2
  36. package/dist/lifecycle/hooks.js +36 -18
  37. package/dist/lifecycle/scopes.d.ts +21 -2
  38. package/dist/lifecycle/scopes.js +86 -2
  39. package/dist/metadata/keys.d.ts +1 -1
  40. package/dist/metadata/keys.js +1 -1
  41. package/dist/resolution/cache/class-introspector.d.ts +7 -8
  42. package/dist/resolution/cache/class-introspector.js +40 -3
  43. package/dist/resolution/cache/lookup.d.ts +10 -0
  44. package/dist/resolution/cache/lookup.js +27 -0
  45. package/dist/resolution/context.d.ts +12 -12
  46. package/dist/resolution/path.d.ts +12 -2
  47. package/dist/resolution/path.js +22 -2
  48. package/dist/resolution/plan/codegen.d.ts +2 -1
  49. package/dist/resolution/plan/codegen.js +1 -1
  50. package/dist/resolution/plan/compiler.d.ts +6 -6
  51. package/dist/resolution/plan/compiler.js +152 -22
  52. package/dist/resolution/resolver.d.ts +6 -0
  53. package/dist/resolution/resolver.js +39 -84
  54. package/package.json +11 -3
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The functions that check and describe a container without resolving from it.
3
+ */
4
+ import type { Container } from "#container/container";
5
+ import type { Token } from "#core/token";
6
+ import type { Constructor } from "#core/types";
7
+ import type { ContainerGraphJson, GraphOptions } from "#introspection/dependency-graph";
8
+ import type { ExplainOptions, ResolutionExplanation } from "#introspection/explanation";
9
+ import type { BindingSnapshot, ContainerSnapshot } from "#introspection/inspector";
10
+ /**
11
+ * Checks a container's singleton graphs, lifecycle hooks and constraints without instantiating anything.
12
+ *
13
+ * @remarks A singleton graph is followed through its declared dependencies the way `resolve` would follow them, so
14
+ * a missing binding, a cycle or a captive dependency fails here instead of on the first request.
15
+ *
16
+ * @since 0.14.0
17
+ */
18
+ export declare function validate(container: Container): void;
19
+ /**
20
+ * Describes a container: the bindings it registers itself, its cached singletons, and whether it has a parent and is
21
+ * disposed.
22
+ *
23
+ * @since 0.14.0
24
+ */
25
+ export declare function inspect(container: Container): ContainerSnapshot;
26
+ /**
27
+ * Describes the bindings a container registers itself for one token, ancestors excluded.
28
+ *
29
+ * @since 0.14.0
30
+ */
31
+ export declare function lookupBindings<Value>(container: Container, token: Token<Value> | Constructor<Value>): ReadonlyArray<BindingSnapshot>;
32
+ /**
33
+ * Explains why a request selects the binding it does, reading each registry the way `resolve` does and deciding by
34
+ * the same rules, without instantiating anything.
35
+ *
36
+ * @remarks A `when()` predicate runs here as it would in `resolve`. `options.ancestors` names the resolutions the
37
+ * request is nested in, so a predicate that reads the parent sees the one it would.
38
+ *
39
+ * @since 0.14.0
40
+ */
41
+ export declare function explain<Names extends string = string>(container: Container, token: Token<unknown, Names> | Constructor, options?: NoInfer<ExplainOptions<Names>>): ResolutionExplanation;
42
+ /**
43
+ * Builds the dependency graph of a container's own bindings, with the ancestors they resolve through.
44
+ *
45
+ * @since 0.14.0
46
+ */
47
+ export declare function generateDependencyGraph(container: Container, options?: GraphOptions): ContainerGraphJson;
@@ -0,0 +1,53 @@
1
+ import { containerInspector, containerInternals } from "#container/container";
2
+ import { buildDependencyGraph } from "#introspection/dependency-graph";
3
+ import { explainRequest } from "#introspection/explanation";
4
+ import { validateChain } from "#introspection/validation";
5
+ /**
6
+ * Checks a container's singleton graphs, lifecycle hooks and constraints without instantiating anything.
7
+ *
8
+ * @remarks A singleton graph is followed through its declared dependencies the way `resolve` would follow them, so
9
+ * a missing binding, a cycle or a captive dependency fails here instead of on the first request.
10
+ *
11
+ * @since 0.14.0
12
+ */
13
+ export function validate(container) {
14
+ validateChain(containerInternals(container));
15
+ }
16
+ /**
17
+ * Describes a container: the bindings it registers itself, its cached singletons, and whether it has a parent and is
18
+ * disposed.
19
+ *
20
+ * @since 0.14.0
21
+ */
22
+ export function inspect(container) {
23
+ return containerInspector(container).inspect();
24
+ }
25
+ /**
26
+ * Describes the bindings a container registers itself for one token, ancestors excluded.
27
+ *
28
+ * @since 0.14.0
29
+ */
30
+ export function lookupBindings(container, token) {
31
+ return containerInspector(container).lookupBindings(token);
32
+ }
33
+ /**
34
+ * Explains why a request selects the binding it does, reading each registry the way `resolve` does and deciding by
35
+ * the same rules, without instantiating anything.
36
+ *
37
+ * @remarks A `when()` predicate runs here as it would in `resolve`. `options.ancestors` names the resolutions the
38
+ * request is nested in, so a predicate that reads the parent sees the one it would.
39
+ *
40
+ * @since 0.14.0
41
+ */
42
+ export function explain(container, token, options) {
43
+ return explainRequest(containerInternals(container).registries, token, options);
44
+ }
45
+ /**
46
+ * Builds the dependency graph of a container's own bindings, with the ancestors they resolve through.
47
+ *
48
+ * @since 0.14.0
49
+ */
50
+ export function generateDependencyGraph(container, options) {
51
+ const { registries, metadataReader } = containerInternals(container);
52
+ return buildDependencyGraph(registries[0], metadataReader, options, registries.slice(1));
53
+ }
@@ -25,6 +25,28 @@ export interface SlotConstrainedBuilder<Names extends string = string> {
25
25
  */
26
26
  many(): this;
27
27
  }
28
+ /**
29
+ * The first step of a chain whose key is a class, which can also construct that class itself.
30
+ *
31
+ * @remarks A token names no class to construct, so only this chain offers `toSelf()`.
32
+ *
33
+ * @since 0.14.0
34
+ */
35
+ export interface ClassBindToBuilder<Value> extends BindToBuilder<Value> {
36
+ toSelf(): BindingBuilder<Value>;
37
+ }
38
+ /**
39
+ * The `bind` a container and a module builder share, so every place a binding starts is typed by one declaration.
40
+ *
41
+ * @remarks A class key starts a chain that can `toSelf()`; a token, or a key typed as either, starts one that cannot.
42
+ *
43
+ * @since 0.14.0
44
+ */
45
+ export interface Binder {
46
+ bind<Value>(type: Constructor<Value>): ClassBindToBuilder<Value>;
47
+ bind<Value, Names extends string = string>(token: Token<Value, Names>): BindToBuilder<Value, Names>;
48
+ bind<Value, Names extends string = string>(key: Token<Value, Names> | Constructor<Value>): BindToBuilder<Value, Names>;
49
+ }
28
50
  /**
29
51
  * The first step of the fluent chain: the slot, then the `to*` strategy that registers the binding.
30
52
  *
@@ -32,7 +54,6 @@ export interface SlotConstrainedBuilder<Names extends string = string> {
32
54
  */
33
55
  export interface BindToBuilder<Value, Names extends string = string> extends SlotConstrainedBuilder<Names> {
34
56
  to(type: Constructor<Value>): BindingBuilder<Value>;
35
- toSelf(): BindingBuilder<Value>;
36
57
  toConstantValue(value: Value): ConstantBindingBuilder<Value>;
37
58
  toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
38
59
  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
@@ -96,11 +117,14 @@ export interface TransientBindingBuilder<Value> {
96
117
  id(): BindingIdentifier;
97
118
  }
98
119
  /**
99
- * The fluent chain after `scoped()`, sharing the `transient()` surface.
120
+ * The fluent chain after `scoped()`, where both lifecycle hooks stay available: a child deactivates what it cached.
100
121
  *
101
122
  * @since 0.3.16-canary.0
102
123
  */
103
- export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {
124
+ export interface ScopedBindingBuilder<Value> {
125
+ onActivation(fn: ActivationHandler<Value>): this;
126
+ onDeactivation(fn: DeactivationHandler<Value>): this;
127
+ id(): BindingIdentifier;
104
128
  }
105
129
  /**
106
130
  * The fluent chain a constant enters once a lifecycle hook is added.
@@ -23,11 +23,11 @@ type SlotDefinition<Names extends string> = ({
23
23
  } & Never<"whenNamed" | "whenTagged">);
24
24
  /** How long an instance lives, and the hooks that lifetime allows. */
25
25
  type LifetimeDefinition<Value> = {
26
- readonly scope: "singleton";
26
+ readonly scope: "singleton" | "scoped";
27
27
  readonly onActivation?: ActivationHandler<Value> | undefined;
28
28
  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
29
29
  } | ({
30
- readonly scope?: "transient" | "scoped" | undefined;
30
+ readonly scope?: "transient" | undefined;
31
31
  readonly onActivation?: ActivationHandler<Value> | undefined;
32
32
  } & Never<"onDeactivation">);
33
33
  type BuiltDefinition<Value, Deps extends ReadonlyArray<InjectableDependency>> = ({
@@ -2,7 +2,7 @@ import { DEFAULT_BINDING_SLOT, withSlotCriterion } from "#core/binding";
2
2
  import { slotName } from "#core/tag";
3
3
  import { tokenName } from "#core/token";
4
4
  import { InvalidBindingDeclarationError, ManyBindingSlotError, SelfBindingRequiresClassError } from "#errors";
5
- import { normalizeToDescriptor } from "#injection/descriptor";
5
+ import { settledDescriptorsOf } from "#injection/descriptor";
6
6
  // Only this module can mint the symbol, so an entry carrying it was made by `binding()`.
7
7
  const declarationBrand = Symbol("di:binding-declaration");
8
8
  /** Whether an entry carries the brand `binding()` alone sets, and so every field a declaration holds. */
@@ -132,7 +132,7 @@ export function binding(key, definition) {
132
132
  }
133
133
  kind = strategy === "toResolved" ? "resolved" : "resolved-async";
134
134
  factory = strategy === "toResolved" ? definition.toResolved : definition.toResolvedAsync;
135
- deps = declaredDeps.map((dependency) => normalizeToDescriptor(dependency));
135
+ deps = settledDescriptorsOf(declaredDeps);
136
136
  break;
137
137
  }
138
138
  case "toAlias":
@@ -157,8 +157,8 @@ export function binding(key, definition) {
157
157
  if (kind === "alias" && (onActivation !== undefined || onDeactivation !== undefined)) {
158
158
  throw new InvalidBindingDeclarationError(name, "`toAlias` takes no lifecycle hook");
159
159
  }
160
- if (onDeactivation !== undefined && kind !== "constant" && scope !== "singleton") {
161
- throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"`');
160
+ if (onDeactivation !== undefined && kind !== "constant" && scope === "transient") {
161
+ throw new InvalidBindingDeclarationError(name, '`onDeactivation` needs `scope: "singleton"` or `scope: "scoped"`');
162
162
  }
163
163
  if (definition.many !== undefined && definition.many !== true) {
164
164
  throw new InvalidBindingDeclarationError(name, "`many` takes `true`");
@@ -1,7 +1,5 @@
1
- import type { BindToBuilder } from "#core/binding-builders";
1
+ import type { Binder } from "#core/binding-builders";
2
2
  import type { BindingDeclaration, DeclaredBinding } from "#core/binding-declaration";
3
- import type { Token } from "#core/token";
4
- import type { Constructor } from "#core/types";
5
3
  declare const SYNC_MODULE_BRAND: unique symbol;
6
4
  declare const ASYNC_MODULE_BRAND: unique symbol;
7
5
  /**
@@ -36,8 +34,7 @@ export interface AsyncModule {
36
34
  *
37
35
  * @since 0.3.16-canary.0
38
36
  */
39
- export interface ModuleBuilder {
40
- bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
37
+ export interface ModuleBuilder extends Binder {
41
38
  import(...modules: Array<SyncModule>): void;
42
39
  }
43
40
  /**
@@ -45,29 +42,11 @@ export interface ModuleBuilder {
45
42
  *
46
43
  * @since 0.3.16-canary.0
47
44
  */
48
- export interface AsyncModuleBuilder {
49
- bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
45
+ export interface AsyncModuleBuilder extends Binder {
50
46
  import(...modules: Array<SyncModule | AsyncModule>): void;
51
47
  }
52
48
  /**
53
- * The companion factory that creates `SyncModule` values.
54
- *
55
- * @since 0.3.16-canary.0
56
- */
57
- export declare const SyncModule: {
58
- create(name: string, setup: (builder: ModuleBuilder) => void): SyncModule;
59
- fromBindings(name: string, declarations: ReadonlyArray<BindingDeclaration>): SyncModule;
60
- };
61
- /**
62
- * The companion factory that creates `AsyncModule` values.
63
- *
64
- * @since 0.3.16-canary.0
65
- */
66
- export declare const AsyncModule: {
67
- create(name: string, setup: (builder: AsyncModuleBuilder) => Promise<void>): AsyncModule;
68
- };
69
- /**
70
- * The unified module factory — `create` and `fromBindings` for sync modules, `createAsync` for async ones.
49
+ * The module factory: `create` and `fromBindings` for a sync module, `createAsync` for an async one.
71
50
  *
72
51
  * @since 0.3.16-canary.0
73
52
  */
@@ -11,11 +11,11 @@ const ASYNC_MODULE_BRAND = Symbol("di:async-module");
11
11
  export const MODULE_SETUP = Symbol("di:module-setup");
12
12
  // ── Static factories ─────────────────────────────────────────────────────────────────────────────────────────────────
13
13
  /**
14
- * The companion factory that creates `SyncModule` values.
14
+ * The module factory: `create` and `fromBindings` for a sync module, `createAsync` for an async one.
15
15
  *
16
16
  * @since 0.3.16-canary.0
17
17
  */
18
- export const SyncModule = {
18
+ export const Module = {
19
19
  create(name, setup) {
20
20
  return {
21
21
  name,
@@ -33,14 +33,7 @@ export const SyncModule = {
33
33
  [MODULE_SETUP]: declared,
34
34
  };
35
35
  },
36
- };
37
- /**
38
- * The companion factory that creates `AsyncModule` values.
39
- *
40
- * @since 0.3.16-canary.0
41
- */
42
- export const AsyncModule = {
43
- create(name, setup) {
36
+ createAsync(name, setup) {
44
37
  return {
45
38
  name,
46
39
  [ASYNC_MODULE_BRAND]: true,
@@ -48,23 +41,6 @@ export const AsyncModule = {
48
41
  };
49
42
  },
50
43
  };
51
- // ── Module — unified API ─────────────────────────────────────────────────────────────────────────────────────────────
52
- /**
53
- * The unified module factory — `create` and `fromBindings` for sync modules, `createAsync` for async ones.
54
- *
55
- * @since 0.3.16-canary.0
56
- */
57
- export const Module = {
58
- create(name, setup) {
59
- return SyncModule.create(name, setup);
60
- },
61
- fromBindings(name, declarations) {
62
- return SyncModule.fromBindings(name, declarations);
63
- },
64
- createAsync(name, setup) {
65
- return AsyncModule.create(name, setup);
66
- },
67
- };
68
44
  /**
69
45
  * Narrows a module union to `SyncModule` by checking its brand.
70
46
  *
@@ -16,7 +16,7 @@ export declare function stateEpoch(): number;
16
16
  export declare function advanceStateEpoch(): void;
17
17
  /**
18
18
  * The container-disposal counter, held in a cell so a hot reader dereferences a field rather than
19
- * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `dispose()`
19
+ * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `disposeAsync()`
20
20
  * does not invalidate the chain-version memo that keeps deep resolves cheap. A child compares it to
21
21
  * learn whether an ancestor was disposed, re-walking the chain only after a disposal somewhere.
22
22
  *
@@ -21,7 +21,7 @@ export function advanceStateEpoch() {
21
21
  }
22
22
  /**
23
23
  * The container-disposal counter, held in a cell so a hot reader dereferences a field rather than
24
- * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `dispose()`
24
+ * paying a cross-module call — apart from {@link stateEpoch} so a per-request child's `disposeAsync()`
25
25
  * does not invalidate the chain-version memo that keeps deep resolves cheap. A child compares it to
26
26
  * learn whether an ancestor was disposed, re-walking the chain only after a disposal somewhere.
27
27
  *
@@ -102,18 +102,27 @@ export interface ConstraintContext {
102
102
  * @since 0.6.0
103
103
  */
104
104
  export type BindingConstraint = (ctx: ConstraintContext) => boolean;
105
+ /**
106
+ * The resolve methods a container and a factory's resolution context share.
107
+ *
108
+ * @remarks One declaration for both, so a slot name narrows the same way wherever a token is resolved.
109
+ *
110
+ * @since 0.14.0
111
+ */
112
+ export interface Resolver {
113
+ resolve<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Value;
114
+ resolveAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value>;
115
+ resolveOptional<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Value | undefined;
116
+ resolveOptionalAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<Value | undefined>;
117
+ resolveAll<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): ReadonlyArray<Value>;
118
+ resolveAllAsync<Value, Names extends string = string>(token: Token<Value, Names> | Constructor<Value>, options?: NoInfer<ResolveOptions<Names>>): Promise<ReadonlyArray<Value>>;
119
+ }
105
120
  /**
106
121
  * The container view a dynamic factory or activation handler resolves further dependencies through.
107
122
  *
108
123
  * @since 0.3.16-canary.0
109
124
  */
110
- export interface ResolutionContext {
111
- resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value;
112
- resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
113
- resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
114
- resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
115
- resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
116
- resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
125
+ export interface ResolutionContext extends Resolver {
117
126
  readonly graph: ConstraintContext;
118
127
  }
119
128
  /**
@@ -2,7 +2,9 @@
2
2
  import type { Token } from "#core/token";
3
3
  import type { Constructor } from "#core/types";
4
4
  import type { InjectionDescriptor, InjectOptions } from "#injection/descriptor";
5
- type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => ClassAccessorDecoratorResult<This, Value> | void;
5
+ type ClassAccessorDecorator<This, Value> = (target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value> & {
6
+ readonly static: false;
7
+ }) => ClassAccessorDecoratorResult<This, Value> | void;
6
8
  /**
7
9
  * Creates a dual-role value: an injection descriptor that also works as a class accessor decorator.
8
10
  *
@@ -1,4 +1,4 @@
1
- import { getActiveContainer, getAmbientResolution } from "#ambient-container";
1
+ import { getActiveContainer, getAmbientResolution, markPreparableSlot, NOT_PREPARED } from "#ambient-container";
2
2
  import { decoratorMetadataOf } from "#decorators/metadata-record";
3
3
  import { MissingContainerContextError, StaticMemberDecoratorError } from "#errors";
4
4
  import { injectionSlotToResolveOptions } from "#injection/dependency-slot";
@@ -47,27 +47,32 @@ export function inject(token, options) {
47
47
  key: context.name,
48
48
  descriptor,
49
49
  });
50
- context.addInitializer(function () {
51
- // Prefer the engine's path-continuing resolver: it keeps this accessor's dependencies on the
52
- // live resolution path, so a cycle through an accessor is detected instead of recursing.
53
- const ambient = getAmbientResolution();
54
- if (ambient !== undefined) {
55
- const value = descriptor.optional
56
- ? ambient.resolveOptional(resolveKey, resolveOptions)
57
- : ambient.resolve(resolveKey, resolveOptions);
58
- context.access.set(this, value);
59
- return;
60
- }
61
- const container = getActiveContainer();
62
- if (container === undefined) {
63
- throw new MissingContainerContextError(classNameOf(this), context.name);
64
- }
65
- const value = descriptor.optional
66
- ? container.resolveOptional(resolveKey, resolveOptions)
67
- : container.resolve(resolveKey, resolveOptions);
68
- context.access.set(this, value);
69
- });
70
- return {};
50
+ markPreparableSlot(descriptor);
51
+ // The value is the accessor's initial value, so its storage is written once as the field initializes.
52
+ return {
53
+ init() {
54
+ // Prefer the engine's path-continuing resolver: it keeps this accessor's dependencies on the
55
+ // live resolution path, so a cycle through an accessor is detected instead of recursing.
56
+ const ambient = getAmbientResolution();
57
+ if (ambient !== undefined) {
58
+ // A compiled plan resolved this accessor before construction; take its value when it holds one.
59
+ const prepared = ambient.takePrepared === undefined ? NOT_PREPARED : ambient.takePrepared(this, descriptor);
60
+ if (prepared !== NOT_PREPARED) {
61
+ return prepared;
62
+ }
63
+ return (descriptor.optional
64
+ ? ambient.resolveOptional(resolveKey, resolveOptions)
65
+ : ambient.resolve(resolveKey, resolveOptions));
66
+ }
67
+ const container = getActiveContainer();
68
+ if (container === undefined) {
69
+ throw new MissingContainerContextError(classNameOf(this), context.name);
70
+ }
71
+ return (descriptor.optional
72
+ ? container.resolveOptional(resolveKey, resolveOptions)
73
+ : container.resolve(resolveKey, resolveOptions));
74
+ },
75
+ };
71
76
  };
72
77
  // Use defineProperties to handle read-only `name` property of functions
73
78
  const props = {};
@@ -1,11 +1,15 @@
1
+ import type { SyncModule } from "#core/module";
1
2
  import type { BindingScope, Constructor } from "#core/types";
2
3
  import type { InjectableDependency, ResolvedDependencyValue } from "#injection/descriptor";
3
4
  /**
4
- * The collector `@injectable` registers a class into, for a container to bind later.
5
+ * The collector `@injectable` registers a class into: a module that binds every registered class to itself.
6
+ *
7
+ * @remarks It loads like any `SyncModule` — deduplicated and ref-counted, and torn down by `unload()`.
8
+ * A load binds the entries registered by then; the set one load bound is the set its unload removes.
5
9
  *
6
10
  * @since 0.3.16-canary.0
7
11
  */
8
- export interface AutoRegisterRegistry {
12
+ export interface AutoRegisterRegistry extends SyncModule {
9
13
  register(target: Constructor, scope: BindingScope): void;
10
14
  entries(): ReadonlyArray<{
11
15
  target: Constructor;
@@ -13,11 +17,11 @@ export interface AutoRegisterRegistry {
13
17
  }>;
14
18
  }
15
19
  /**
16
- * Creates an empty auto-register registry.
20
+ * Creates an empty auto-register registry, loaded under `name`.
17
21
  *
18
22
  * @since 0.3.16-canary.0
19
23
  */
20
- export declare function createAutoRegisterRegistry(): AutoRegisterRegistry;
24
+ export declare function createAutoRegisterRegistry(name: string): AutoRegisterRegistry;
21
25
  /**
22
26
  * Auto-registration options `@injectable` accepts alongside its deps list.
23
27
  *
@@ -31,27 +35,19 @@ export interface InjectableOptions {
31
35
  * The parameters a constructor is handed, given what its `deps` declare.
32
36
  *
33
37
  * @remarks Reuses the same reading a `toResolved` factory gets, so `injectAll` arrives as an array
34
- * and `optional` as possibly undefined in both places.
38
+ * and `injectOptional` as possibly undefined in both places.
35
39
  */
36
40
  type InjectedParameters<Deps extends ReadonlyArray<InjectableDependency>> = {
37
41
  -readonly [Index in keyof Deps]: ResolvedDependencyValue<Deps[Index]>;
38
42
  };
39
43
  /**
40
- * Declare a class injectable, and what its constructor is to be handed.
44
+ * Declares a class injectable, and what its constructor is to be handed.
41
45
  *
42
- * @since 0.3.16-canary.0
43
- */
44
- export declare function injectable(): (target: unknown, context: ClassDecoratorContext) => void;
45
- /**
46
- * @remarks Declaring dependencies constrains the class: the decorator only accepts one whose
47
- * constructor takes exactly what `deps` resolve to, in that order — including arity, so a literal
48
- * deps list longer than the constructor is a compile error rather than a resolved-and-discarded
49
- * value. Optional trailing parameters admit every arity they declare, and a rest parameter admits
50
- * any list. A deps *array* — one whose length the compiler cannot know — skips the arity check,
51
- * which is also the deliberate spelling for declaring more dependencies than the constructor
52
- * takes, e.g. for the dependency graph's edges.
46
+ * @remarks The decorator only accepts a class whose constructor takes exactly what `deps` resolve to, in that order —
47
+ * no deps means no required parameter, so a class (or a subclass inheriting its base's constructor) cannot be built
48
+ * with an argument left `undefined`. A deps *array* whose length the compiler cannot know skips the arity check.
53
49
  *
54
50
  * @since 0.3.16-canary.0
55
51
  */
56
- export declare function injectable<const Deps extends ReadonlyArray<InjectableDependency>>(deps: Deps, options?: InjectableOptions): <Target extends abstract new (...args: InjectedParameters<Deps>) => unknown>(target: Target & (number extends Deps["length"] ? unknown : Deps["length"] extends ConstructorParameters<Target>["length"] ? unknown : never), context: ClassDecoratorContext) => void;
52
+ export declare function injectable<const Deps extends ReadonlyArray<InjectableDependency> = []>(deps?: Deps, options?: InjectableOptions): <Target extends abstract new (...args: InjectedParameters<Deps>) => unknown>(target: Target & (number extends Deps["length"] ? unknown : Deps["length"] extends ConstructorParameters<Target>["length"] ? unknown : never), context: ClassDecoratorContext) => void;
57
53
  export type { InjectableDependency };
@@ -1,14 +1,22 @@
1
+ import { Module } from "#core/module";
1
2
  import { decoratorMetadataOf } from "#decorators/metadata-record";
2
3
  import { normalizeToDescriptor } from "#injection/descriptor";
3
4
  import { INJECTABLE_KEY } from "#metadata/keys";
4
5
  /**
5
- * Creates an empty auto-register registry.
6
+ * Creates an empty auto-register registry, loaded under `name`.
6
7
  *
7
8
  * @since 0.3.16-canary.0
8
9
  */
9
- export function createAutoRegisterRegistry() {
10
+ export function createAutoRegisterRegistry(name) {
10
11
  const registeredEntries = [];
12
+ // A setup callback rather than declarations, so a class decorated after the registry exists still loads.
13
+ const module = Module.create(name, (builder) => {
14
+ for (const { target, scope } of registeredEntries) {
15
+ APPLY_BINDING_SCOPE[scope](builder.bind(target).toSelf());
16
+ }
17
+ });
11
18
  return {
19
+ ...module,
12
20
  register(target, scope) {
13
21
  registeredEntries.push({ target, scope });
14
22
  },
@@ -17,6 +25,19 @@ export function createAutoRegisterRegistry() {
17
25
  },
18
26
  };
19
27
  }
28
+ // A Record rather than an if-chain, so a new `BindingScope` is a compile error here instead of
29
+ // silently landing in whichever branch happened to be last.
30
+ const APPLY_BINDING_SCOPE = {
31
+ singleton: (builder) => {
32
+ builder.singleton();
33
+ },
34
+ scoped: (builder) => {
35
+ builder.scoped();
36
+ },
37
+ transient: (builder) => {
38
+ builder.transient();
39
+ },
40
+ };
20
41
  /**
21
42
  * Writes the declared dependencies into the class's metadata and optionally auto-registers it.
22
43
  *
@@ -1,14 +1,20 @@
1
- type MethodDecorator = (target: unknown, context: ClassMethodDecoratorContext) => void;
1
+ /** The only method a hook can be: the lifecycle reader calls it on the instance by its string name. */
2
+ type LifecycleMethodContext = ClassMethodDecoratorContext & {
3
+ readonly static: false;
4
+ readonly private: false;
5
+ readonly name: string;
6
+ };
7
+ type LifecycleMethodDecorator = (target: unknown, context: LifecycleMethodContext) => void;
2
8
  /**
3
9
  * Marks an instance method to run after the container constructs and wires the instance.
4
10
  *
5
11
  * @since 0.3.16-canary.0
6
12
  */
7
- export declare function postConstruct(): MethodDecorator;
13
+ export declare function postConstruct(): LifecycleMethodDecorator;
8
14
  /**
9
15
  * Marks an instance method to run when the instance's container or scope is disposed.
10
16
  *
11
17
  * @since 0.3.16-canary.0
12
18
  */
13
- export declare function preDestroy(): MethodDecorator;
19
+ export declare function preDestroy(): LifecycleMethodDecorator;
14
20
  export {};
@@ -1,12 +1,16 @@
1
1
  import { decoratorMetadataOf } from "#decorators/metadata-record";
2
- import { StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
2
+ import { PrivateLifecycleMethodError, StaticMemberDecoratorError, SymbolKeyedLifecycleError } from "#errors";
3
3
  import { LIFECYCLE_KEY } from "#metadata/keys";
4
4
  /** Records the decorated method under one lifecycle phase; both decorators differ only in that phase. */
5
5
  function recordLifecycleMethod(phase) {
6
+ // Typed wide on purpose: the checks below are what an untyped caller meets instead of the compiler.
6
7
  return function (target, context) {
7
8
  if (context.static) {
8
9
  throw new StaticMemberDecoratorError(phase, String(context.name));
9
10
  }
11
+ if (context.private) {
12
+ throw new PrivateLifecycleMethodError(phase, String(context.name));
13
+ }
10
14
  // The lifecycle reader keys methods by their string name, so a symbol-keyed method can never be
11
15
  // found again — fail here, where the declaration is, rather than at resolve.
12
16
  if (typeof context.name === "symbol") {