@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.
- package/CHANGELOG.md +192 -0
- package/README.md +142 -43
- package/dist/ambient-container.d.ts +46 -0
- package/dist/ambient-container.js +72 -1
- package/dist/container/binding-chain.js +3 -3
- package/dist/container/container.d.ts +41 -30
- package/dist/container/container.js +59 -243
- package/dist/container/introspect.d.ts +47 -0
- package/dist/container/introspect.js +53 -0
- package/dist/core/binding-builders.d.ts +27 -3
- package/dist/core/binding-declaration.d.ts +2 -2
- package/dist/core/binding-declaration.js +4 -4
- package/dist/core/module.d.ts +4 -25
- package/dist/core/module.js +3 -27
- package/dist/core/state-epoch.d.ts +1 -1
- package/dist/core/state-epoch.js +1 -1
- package/dist/core/types.d.ts +16 -7
- package/dist/decorators/inject.d.ts +3 -1
- package/dist/decorators/inject.js +27 -22
- package/dist/decorators/injectable.d.ts +14 -18
- package/dist/decorators/injectable.js +23 -2
- package/dist/decorators/lifecycle.d.ts +9 -3
- package/dist/decorators/lifecycle.js +5 -1
- package/dist/errors.d.ts +33 -15
- package/dist/errors.js +41 -21
- package/dist/index.d.ts +9 -8
- package/dist/index.js +4 -3
- package/dist/injection/dependency-slot.d.ts +17 -0
- package/dist/injection/dependency-slot.js +46 -0
- package/dist/injection/descriptor.d.ts +9 -3
- package/dist/injection/descriptor.js +10 -1
- package/dist/introspection/explanation.js +26 -8
- package/dist/introspection/validation.d.ts +28 -0
- package/dist/introspection/validation.js +244 -0
- package/dist/lifecycle/hooks.d.ts +13 -2
- package/dist/lifecycle/hooks.js +36 -18
- package/dist/lifecycle/scopes.d.ts +21 -2
- package/dist/lifecycle/scopes.js +86 -2
- package/dist/metadata/keys.d.ts +1 -1
- package/dist/metadata/keys.js +1 -1
- package/dist/resolution/cache/class-introspector.d.ts +7 -8
- package/dist/resolution/cache/class-introspector.js +40 -3
- package/dist/resolution/cache/lookup.d.ts +10 -0
- package/dist/resolution/cache/lookup.js +27 -0
- package/dist/resolution/context.d.ts +12 -12
- package/dist/resolution/path.d.ts +12 -2
- package/dist/resolution/path.js +22 -2
- package/dist/resolution/plan/codegen.d.ts +2 -1
- package/dist/resolution/plan/codegen.js +1 -1
- package/dist/resolution/plan/compiler.d.ts +6 -6
- package/dist/resolution/plan/compiler.js +152 -22
- package/dist/resolution/resolver.d.ts +6 -0
- package/dist/resolution/resolver.js +39 -84
- 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()`,
|
|
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>
|
|
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" |
|
|
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 {
|
|
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
|
|
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
|
|
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`");
|
package/dist/core/module.d.ts
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
|
-
import type {
|
|
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
|
|
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
|
*/
|
package/dist/core/module.js
CHANGED
|
@@ -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
|
|
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
|
|
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 `
|
|
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
|
*
|
package/dist/core/state-epoch.js
CHANGED
|
@@ -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 `
|
|
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
|
*
|
package/dist/core/types.d.ts
CHANGED
|
@@ -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>
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
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 `
|
|
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
|
-
*
|
|
44
|
+
* Declares a class injectable, and what its constructor is to be handed.
|
|
41
45
|
*
|
|
42
|
-
* @
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
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
|
-
|
|
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():
|
|
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():
|
|
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") {
|