@navios/di 0.3.0 → 0.4.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 (96) hide show
  1. package/README.md +67 -6
  2. package/coverage/base.css +224 -0
  3. package/coverage/block-navigation.js +87 -0
  4. package/coverage/clover.xml +2659 -0
  5. package/coverage/coverage-final.json +46 -0
  6. package/coverage/docs/examples/basic-usage.mts.html +376 -0
  7. package/coverage/docs/examples/factory-pattern.mts.html +1039 -0
  8. package/coverage/docs/examples/index.html +176 -0
  9. package/coverage/docs/examples/injection-tokens.mts.html +760 -0
  10. package/coverage/docs/examples/request-scope-example.mts.html +847 -0
  11. package/coverage/docs/examples/service-lifecycle.mts.html +1162 -0
  12. package/coverage/favicon.png +0 -0
  13. package/coverage/index.html +236 -0
  14. package/coverage/lib/_tsup-dts-rollup.d.mts.html +2806 -0
  15. package/coverage/lib/index.d.mts.html +310 -0
  16. package/coverage/lib/index.html +131 -0
  17. package/coverage/prettify.css +1 -0
  18. package/coverage/prettify.js +2 -0
  19. package/coverage/sort-arrow-sprite.png +0 -0
  20. package/coverage/sorter.js +196 -0
  21. package/coverage/src/container.mts.html +586 -0
  22. package/coverage/src/decorators/factory.decorator.mts.html +322 -0
  23. package/coverage/src/decorators/index.html +146 -0
  24. package/coverage/src/decorators/index.mts.html +91 -0
  25. package/coverage/src/decorators/injectable.decorator.mts.html +394 -0
  26. package/coverage/src/enums/index.html +146 -0
  27. package/coverage/src/enums/index.mts.html +91 -0
  28. package/coverage/src/enums/injectable-scope.enum.mts.html +127 -0
  29. package/coverage/src/enums/injectable-type.enum.mts.html +97 -0
  30. package/coverage/src/errors/errors.enum.mts.html +109 -0
  31. package/coverage/src/errors/factory-not-found.mts.html +109 -0
  32. package/coverage/src/errors/factory-token-not-resolved.mts.html +115 -0
  33. package/coverage/src/errors/index.html +221 -0
  34. package/coverage/src/errors/index.mts.html +106 -0
  35. package/coverage/src/errors/instance-destroying.mts.html +109 -0
  36. package/coverage/src/errors/instance-expired.mts.html +109 -0
  37. package/coverage/src/errors/instance-not-found.mts.html +109 -0
  38. package/coverage/src/errors/unknown-error.mts.html +130 -0
  39. package/coverage/src/event-emitter.mts.html +400 -0
  40. package/coverage/src/factory-context.mts.html +109 -0
  41. package/coverage/src/index.html +296 -0
  42. package/coverage/src/index.mts.html +139 -0
  43. package/coverage/src/injection-token.mts.html +571 -0
  44. package/coverage/src/injector.mts.html +133 -0
  45. package/coverage/src/interfaces/factory.interface.mts.html +121 -0
  46. package/coverage/src/interfaces/index.html +161 -0
  47. package/coverage/src/interfaces/index.mts.html +94 -0
  48. package/coverage/src/interfaces/on-service-destroy.interface.mts.html +94 -0
  49. package/coverage/src/interfaces/on-service-init.interface.mts.html +94 -0
  50. package/coverage/src/registry.mts.html +247 -0
  51. package/coverage/src/request-context-holder.mts.html +607 -0
  52. package/coverage/src/service-instantiator.mts.html +559 -0
  53. package/coverage/src/service-locator-event-bus.mts.html +289 -0
  54. package/coverage/src/service-locator-instance-holder.mts.html +307 -0
  55. package/coverage/src/service-locator-manager.mts.html +604 -0
  56. package/coverage/src/service-locator.mts.html +2911 -0
  57. package/coverage/src/symbols/index.html +131 -0
  58. package/coverage/src/symbols/index.mts.html +88 -0
  59. package/coverage/src/symbols/injectable-token.mts.html +88 -0
  60. package/coverage/src/utils/defer.mts.html +304 -0
  61. package/coverage/src/utils/get-injectable-token.mts.html +142 -0
  62. package/coverage/src/utils/get-injectors.mts.html +691 -0
  63. package/coverage/src/utils/index.html +176 -0
  64. package/coverage/src/utils/index.mts.html +97 -0
  65. package/coverage/src/utils/types.mts.html +241 -0
  66. package/docs/README.md +5 -2
  67. package/docs/api-reference.md +38 -0
  68. package/docs/container.md +75 -0
  69. package/docs/getting-started.md +4 -3
  70. package/docs/injectable.md +4 -3
  71. package/docs/migration.md +177 -0
  72. package/docs/request-contexts.md +364 -0
  73. package/lib/_tsup-dts-rollup.d.mts +180 -35
  74. package/lib/_tsup-dts-rollup.d.ts +180 -35
  75. package/lib/index.d.mts +1 -0
  76. package/lib/index.d.ts +1 -0
  77. package/lib/index.js +485 -279
  78. package/lib/index.js.map +1 -1
  79. package/lib/index.mjs +485 -280
  80. package/lib/index.mjs.map +1 -1
  81. package/package.json +1 -1
  82. package/src/__tests__/defer.spec.mts +166 -0
  83. package/src/__tests__/errors.spec.mts +61 -0
  84. package/src/__tests__/event-emitter.spec.mts +163 -0
  85. package/src/__tests__/get-injectors.spec.mts +70 -0
  86. package/src/__tests__/registry.spec.mts +335 -0
  87. package/src/__tests__/request-scope.spec.mts +167 -4
  88. package/src/__tests__/service-instantiator.spec.mts +408 -0
  89. package/src/__tests__/service-locator-event-bus.spec.mts +242 -0
  90. package/src/__tests__/service-locator-manager.spec.mts +370 -0
  91. package/src/__tests__/unified-api.spec.mts +130 -0
  92. package/src/base-instance-holder-manager.mts +175 -0
  93. package/src/index.mts +1 -0
  94. package/src/request-context-holder.mts +85 -27
  95. package/src/service-locator-manager.mts +12 -70
  96. package/src/service-locator.mts +421 -226
@@ -16,6 +16,93 @@ declare type BaseInjectionTokenSchemaType = ZodObject | ZodRecord;
16
16
  export { BaseInjectionTokenSchemaType }
17
17
  export { BaseInjectionTokenSchemaType as BaseInjectionTokenSchemaType_alias_1 }
18
18
 
19
+ /**
20
+ * Abstract base class that provides common functionality for managing ServiceLocatorInstanceHolder objects.
21
+ * This class contains shared patterns used by both RequestContextHolder and ServiceLocatorManager.
22
+ */
23
+ declare abstract class BaseInstanceHolderManager {
24
+ protected readonly logger: Console | null;
25
+ protected readonly _holders: Map<string, ServiceLocatorInstanceHolder>;
26
+ constructor(logger?: Console | null);
27
+ /**
28
+ * Protected getter for accessing the holders map from subclasses.
29
+ */
30
+ protected get holders(): Map<string, ServiceLocatorInstanceHolder>;
31
+ /**
32
+ * Abstract method to get a holder by name. Each implementation defines its own return type
33
+ * based on their specific error handling and validation needs.
34
+ */
35
+ abstract get(name: string): any;
36
+ /**
37
+ * Abstract method to set a holder by name. Each implementation may have different validation logic.
38
+ */
39
+ abstract set(name: string, holder: ServiceLocatorInstanceHolder): void;
40
+ /**
41
+ * Abstract method to check if a holder exists. Each implementation may have different validation logic.
42
+ */
43
+ abstract has(name: string): any;
44
+ /**
45
+ * Deletes a holder by name.
46
+ * @param name The name of the holder to delete
47
+ * @returns true if the holder was deleted, false if it didn't exist
48
+ */
49
+ delete(name: string): boolean;
50
+ /**
51
+ * Filters holders based on a predicate function.
52
+ * @param predicate Function to test each holder
53
+ * @returns A new Map containing only the holders that match the predicate
54
+ */
55
+ filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
56
+ /**
57
+ * Clears all holders from this manager.
58
+ */
59
+ clear(): void;
60
+ /**
61
+ * Gets the number of holders currently managed.
62
+ */
63
+ size(): number;
64
+ /**
65
+ * Creates a new holder with Creating status and a deferred creation promise.
66
+ * This is useful for creating placeholder holders that can be fulfilled later.
67
+ * @param name The name of the instance
68
+ * @param type The injectable type
69
+ * @param scope The injectable scope
70
+ * @param deps Optional set of dependencies
71
+ * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
72
+ * @returns A tuple containing the deferred promise and the holder
73
+ */
74
+ createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): [
75
+ ReturnType<typeof createDeferred<[undefined, Instance]>>,
76
+ ServiceLocatorInstanceHolder<Instance>
77
+ ];
78
+ /**
79
+ * Creates a new holder with Created status and an actual instance.
80
+ * This is useful for creating holders that already have their instance ready.
81
+ * @param name The name of the instance
82
+ * @param instance The actual instance to store
83
+ * @param type The injectable type
84
+ * @param scope The injectable scope
85
+ * @param deps Optional set of dependencies
86
+ * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
87
+ * @returns The created holder
88
+ */
89
+ protected createCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): ServiceLocatorInstanceHolder<Instance>;
90
+ /**
91
+ * Gets all holder names currently managed.
92
+ */
93
+ getAllNames(): string[];
94
+ /**
95
+ * Gets all holders currently managed.
96
+ */
97
+ getAllHolders(): ServiceLocatorInstanceHolder[];
98
+ /**
99
+ * Checks if this manager has any holders.
100
+ */
101
+ isEmpty(): boolean;
102
+ }
103
+ export { BaseInstanceHolderManager }
104
+ export { BaseInstanceHolderManager as BaseInstanceHolderManager_alias_1 }
105
+
19
106
  declare class BoundInjectionToken<T, S extends InjectionTokenSchemaType> {
20
107
  readonly token: InjectionToken<T, S>;
21
108
  readonly value: z.input<S>;
@@ -138,18 +225,29 @@ export { defaultInjectors as defaultInjectors_alias_1 }
138
225
  /**
139
226
  * Default implementation of RequestContextHolder.
140
227
  */
141
- declare class DefaultRequestContextHolder implements RequestContextHolder {
228
+ declare class DefaultRequestContextHolder extends BaseInstanceHolderManager implements RequestContextHolder {
142
229
  readonly requestId: string;
143
230
  readonly priority: number;
144
- readonly instances: Map<string, any>;
145
- readonly holders: Map<string, ServiceLocatorInstanceHolder>;
146
231
  readonly metadata: Map<string, any>;
147
232
  readonly createdAt: number;
148
233
  constructor(requestId: string, priority?: number, initialMetadata?: Record<string, any>);
149
- addInstance(instanceName: string, instance: any, holder: ServiceLocatorInstanceHolder): void;
150
- getInstance(instanceName: string): any | undefined;
151
- getHolder(instanceName: string): ServiceLocatorInstanceHolder | undefined;
152
- hasInstance(instanceName: string): boolean;
234
+ /**
235
+ * Public getter for holders to maintain interface compatibility.
236
+ */
237
+ get holders(): Map<string, ServiceLocatorInstanceHolder>;
238
+ /**
239
+ * Gets a holder by name. For RequestContextHolder, this is a simple lookup.
240
+ */
241
+ get(name: string): ServiceLocatorInstanceHolder | undefined;
242
+ /**
243
+ * Sets a holder by name.
244
+ */
245
+ set(name: string, holder: ServiceLocatorInstanceHolder): void;
246
+ /**
247
+ * Checks if a holder exists by name.
248
+ */
249
+ has(name: string): boolean;
250
+ addInstance(instanceName: string | InjectionToken<any, undefined>, instance: any, holder?: ServiceLocatorInstanceHolder): void;
153
251
  clear(): void;
154
252
  getMetadata(key: string): any | undefined;
155
253
  setMetadata(key: string, value: any): void;
@@ -555,10 +653,6 @@ declare interface RequestContextHolder {
555
653
  * Unique identifier for this request context.
556
654
  */
557
655
  readonly requestId: string;
558
- /**
559
- * Pre-prepared instances for this request, keyed by instance name.
560
- */
561
- readonly instances: Map<string, any>;
562
656
  /**
563
657
  * Instance holders for request-scoped services.
564
658
  */
@@ -581,17 +675,17 @@ declare interface RequestContextHolder {
581
675
  */
582
676
  addInstance(instanceName: string, instance: any, holder: ServiceLocatorInstanceHolder): void;
583
677
  /**
584
- * Gets a pre-prepared instance from this context.
678
+ * Adds a pre-prepared instance to this context.
585
679
  */
586
- getInstance(instanceName: string): any | undefined;
680
+ addInstance(token: InjectionToken<any, undefined>, instance: any): void;
587
681
  /**
588
682
  * Gets an instance holder from this context.
589
683
  */
590
- getHolder(instanceName: string): ServiceLocatorInstanceHolder | undefined;
684
+ get(instanceName: string): ServiceLocatorInstanceHolder | undefined;
591
685
  /**
592
686
  * Checks if this context has a pre-prepared instance.
593
687
  */
594
- hasInstance(instanceName: string): boolean;
688
+ has(instanceName: string): boolean;
595
689
  /**
596
690
  * Clears all instances and holders from this context.
597
691
  */
@@ -604,6 +698,22 @@ declare interface RequestContextHolder {
604
698
  * Sets metadata value by key.
605
699
  */
606
700
  setMetadata(key: string, value: any): void;
701
+ /**
702
+ * Filters holders based on a predicate function.
703
+ */
704
+ filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
705
+ /**
706
+ * Deletes a holder by name.
707
+ */
708
+ delete(name: string): boolean;
709
+ /**
710
+ * Gets the number of holders currently managed.
711
+ */
712
+ size(): number;
713
+ /**
714
+ * Checks if this manager has any holders.
715
+ */
716
+ isEmpty(): boolean;
607
717
  }
608
718
  export { RequestContextHolder }
609
719
  export { RequestContextHolder as RequestContextHolder_alias_1 }
@@ -664,7 +774,19 @@ declare class ServiceLocator {
664
774
  getOrThrowInstance<Instance>(token: AnyInjectableType, args: any): Promise<Instance>;
665
775
  getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined): Instance | null;
666
776
  invalidate(service: string, round?: number): Promise<any>;
667
- ready(): Promise<null>;
777
+ /**
778
+ * Invalidates a single holder based on its current status.
779
+ */
780
+ private invalidateHolder;
781
+ /**
782
+ * Destroys a holder and cleans up its resources.
783
+ */
784
+ private destroyHolder;
785
+ ready(): Promise<void>;
786
+ /**
787
+ * Waits for a holder to settle (either created, destroyed, or error state).
788
+ */
789
+ private waitForHolderToSettle;
668
790
  /**
669
791
  * Begins a new request context with the given parameters.
670
792
  * @param requestId Unique identifier for this request
@@ -701,6 +823,23 @@ declare class ServiceLocator {
701
823
  * Gets an instance by its instance name, handling all the logic after instance name creation.
702
824
  */
703
825
  private retrieveOrCreateInstanceByInstanceName;
826
+ /**
827
+ * Attempts to retrieve an existing instance, handling request-scoped and singleton instances.
828
+ * Returns null if no instance exists and a new one should be created.
829
+ */
830
+ private tryGetExistingInstance;
831
+ /**
832
+ * Attempts to get a request-scoped instance if applicable.
833
+ */
834
+ private tryGetRequestScopedInstance;
835
+ /**
836
+ * Attempts to get a singleton instance from the manager.
837
+ */
838
+ private tryGetSingletonInstance;
839
+ /**
840
+ * Waits for an instance holder to be ready and returns the appropriate result.
841
+ */
842
+ private waitForInstanceReady;
704
843
  /**
705
844
  * Emits events to listeners for instance lifecycle events.
706
845
  */
@@ -713,6 +852,26 @@ declare class ServiceLocator {
713
852
  * Instantiates a service from the registry using the service instantiator.
714
853
  */
715
854
  private instantiateServiceFromRegistry;
855
+ /**
856
+ * Handles the result of service instantiation.
857
+ */
858
+ private handleInstantiationResult;
859
+ /**
860
+ * Handles successful service instantiation.
861
+ */
862
+ private handleInstantiationSuccess;
863
+ /**
864
+ * Handles service instantiation errors.
865
+ */
866
+ private handleInstantiationError;
867
+ /**
868
+ * Stores an instance holder based on its scope.
869
+ */
870
+ private storeInstanceByScope;
871
+ /**
872
+ * Tries to get a pre-prepared instance from request contexts.
873
+ */
874
+ private tryGetPrePreparedInstance;
716
875
  /**
717
876
  * Creates a factory context for dependency injection during service instantiation.
718
877
  * @param contextHolder Optional request context holder for priority-based resolution
@@ -722,6 +881,10 @@ declare class ServiceLocator {
722
881
  * Generates a unique instance name based on token and arguments.
723
882
  */
724
883
  private generateInstanceName;
884
+ /**
885
+ * Formats a single argument value for instance name generation.
886
+ */
887
+ private formatArgValue;
725
888
  }
726
889
  export { ServiceLocator }
727
890
  export { ServiceLocator as ServiceLocator_alias_1 }
@@ -821,29 +984,11 @@ declare enum ServiceLocatorInstanceHolderStatus {
821
984
  export { ServiceLocatorInstanceHolderStatus }
822
985
  export { ServiceLocatorInstanceHolderStatus as ServiceLocatorInstanceHolderStatus_alias_1 }
823
986
 
824
- declare class ServiceLocatorManager {
825
- private readonly logger;
826
- private readonly instancesHolders;
987
+ declare class ServiceLocatorManager extends BaseInstanceHolderManager {
827
988
  constructor(logger?: Console | null);
828
989
  get(name: string): [InstanceExpired | InstanceDestroying, ServiceLocatorInstanceHolder] | [InstanceNotFound] | [undefined, ServiceLocatorInstanceHolder];
829
990
  set(name: string, holder: ServiceLocatorInstanceHolder): void;
830
991
  has(name: string): [InstanceExpired | InstanceDestroying] | [undefined, boolean];
831
- delete(name: string): boolean;
832
- filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
833
- /**
834
- * Creates a new holder with Creating status and a deferred creation promise.
835
- * This is useful for creating placeholder holders that can be fulfilled later.
836
- * @param name The name of the instance
837
- * @param type The injectable type
838
- * @param scope The injectable scope
839
- * @param deps Optional set of dependencies
840
- * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
841
- * @returns A tuple containing the deferred promise and the holder
842
- */
843
- createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): [
844
- ReturnType<typeof createDeferred<[undefined, Instance]>>,
845
- ServiceLocatorInstanceHolder<Instance>
846
- ];
847
992
  /**
848
993
  * Creates a new holder with Created status and an actual instance.
849
994
  * This is useful for creating holders that already have their instance ready.
@@ -16,6 +16,93 @@ declare type BaseInjectionTokenSchemaType = ZodObject | ZodRecord;
16
16
  export { BaseInjectionTokenSchemaType }
17
17
  export { BaseInjectionTokenSchemaType as BaseInjectionTokenSchemaType_alias_1 }
18
18
 
19
+ /**
20
+ * Abstract base class that provides common functionality for managing ServiceLocatorInstanceHolder objects.
21
+ * This class contains shared patterns used by both RequestContextHolder and ServiceLocatorManager.
22
+ */
23
+ declare abstract class BaseInstanceHolderManager {
24
+ protected readonly logger: Console | null;
25
+ protected readonly _holders: Map<string, ServiceLocatorInstanceHolder>;
26
+ constructor(logger?: Console | null);
27
+ /**
28
+ * Protected getter for accessing the holders map from subclasses.
29
+ */
30
+ protected get holders(): Map<string, ServiceLocatorInstanceHolder>;
31
+ /**
32
+ * Abstract method to get a holder by name. Each implementation defines its own return type
33
+ * based on their specific error handling and validation needs.
34
+ */
35
+ abstract get(name: string): any;
36
+ /**
37
+ * Abstract method to set a holder by name. Each implementation may have different validation logic.
38
+ */
39
+ abstract set(name: string, holder: ServiceLocatorInstanceHolder): void;
40
+ /**
41
+ * Abstract method to check if a holder exists. Each implementation may have different validation logic.
42
+ */
43
+ abstract has(name: string): any;
44
+ /**
45
+ * Deletes a holder by name.
46
+ * @param name The name of the holder to delete
47
+ * @returns true if the holder was deleted, false if it didn't exist
48
+ */
49
+ delete(name: string): boolean;
50
+ /**
51
+ * Filters holders based on a predicate function.
52
+ * @param predicate Function to test each holder
53
+ * @returns A new Map containing only the holders that match the predicate
54
+ */
55
+ filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
56
+ /**
57
+ * Clears all holders from this manager.
58
+ */
59
+ clear(): void;
60
+ /**
61
+ * Gets the number of holders currently managed.
62
+ */
63
+ size(): number;
64
+ /**
65
+ * Creates a new holder with Creating status and a deferred creation promise.
66
+ * This is useful for creating placeholder holders that can be fulfilled later.
67
+ * @param name The name of the instance
68
+ * @param type The injectable type
69
+ * @param scope The injectable scope
70
+ * @param deps Optional set of dependencies
71
+ * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
72
+ * @returns A tuple containing the deferred promise and the holder
73
+ */
74
+ createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): [
75
+ ReturnType<typeof createDeferred<[undefined, Instance]>>,
76
+ ServiceLocatorInstanceHolder<Instance>
77
+ ];
78
+ /**
79
+ * Creates a new holder with Created status and an actual instance.
80
+ * This is useful for creating holders that already have their instance ready.
81
+ * @param name The name of the instance
82
+ * @param instance The actual instance to store
83
+ * @param type The injectable type
84
+ * @param scope The injectable scope
85
+ * @param deps Optional set of dependencies
86
+ * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
87
+ * @returns The created holder
88
+ */
89
+ protected createCreatedHolder<Instance>(name: string, instance: Instance, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): ServiceLocatorInstanceHolder<Instance>;
90
+ /**
91
+ * Gets all holder names currently managed.
92
+ */
93
+ getAllNames(): string[];
94
+ /**
95
+ * Gets all holders currently managed.
96
+ */
97
+ getAllHolders(): ServiceLocatorInstanceHolder[];
98
+ /**
99
+ * Checks if this manager has any holders.
100
+ */
101
+ isEmpty(): boolean;
102
+ }
103
+ export { BaseInstanceHolderManager }
104
+ export { BaseInstanceHolderManager as BaseInstanceHolderManager_alias_1 }
105
+
19
106
  declare class BoundInjectionToken<T, S extends InjectionTokenSchemaType> {
20
107
  readonly token: InjectionToken<T, S>;
21
108
  readonly value: z.input<S>;
@@ -138,18 +225,29 @@ export { defaultInjectors as defaultInjectors_alias_1 }
138
225
  /**
139
226
  * Default implementation of RequestContextHolder.
140
227
  */
141
- declare class DefaultRequestContextHolder implements RequestContextHolder {
228
+ declare class DefaultRequestContextHolder extends BaseInstanceHolderManager implements RequestContextHolder {
142
229
  readonly requestId: string;
143
230
  readonly priority: number;
144
- readonly instances: Map<string, any>;
145
- readonly holders: Map<string, ServiceLocatorInstanceHolder>;
146
231
  readonly metadata: Map<string, any>;
147
232
  readonly createdAt: number;
148
233
  constructor(requestId: string, priority?: number, initialMetadata?: Record<string, any>);
149
- addInstance(instanceName: string, instance: any, holder: ServiceLocatorInstanceHolder): void;
150
- getInstance(instanceName: string): any | undefined;
151
- getHolder(instanceName: string): ServiceLocatorInstanceHolder | undefined;
152
- hasInstance(instanceName: string): boolean;
234
+ /**
235
+ * Public getter for holders to maintain interface compatibility.
236
+ */
237
+ get holders(): Map<string, ServiceLocatorInstanceHolder>;
238
+ /**
239
+ * Gets a holder by name. For RequestContextHolder, this is a simple lookup.
240
+ */
241
+ get(name: string): ServiceLocatorInstanceHolder | undefined;
242
+ /**
243
+ * Sets a holder by name.
244
+ */
245
+ set(name: string, holder: ServiceLocatorInstanceHolder): void;
246
+ /**
247
+ * Checks if a holder exists by name.
248
+ */
249
+ has(name: string): boolean;
250
+ addInstance(instanceName: string | InjectionToken<any, undefined>, instance: any, holder?: ServiceLocatorInstanceHolder): void;
153
251
  clear(): void;
154
252
  getMetadata(key: string): any | undefined;
155
253
  setMetadata(key: string, value: any): void;
@@ -555,10 +653,6 @@ declare interface RequestContextHolder {
555
653
  * Unique identifier for this request context.
556
654
  */
557
655
  readonly requestId: string;
558
- /**
559
- * Pre-prepared instances for this request, keyed by instance name.
560
- */
561
- readonly instances: Map<string, any>;
562
656
  /**
563
657
  * Instance holders for request-scoped services.
564
658
  */
@@ -581,17 +675,17 @@ declare interface RequestContextHolder {
581
675
  */
582
676
  addInstance(instanceName: string, instance: any, holder: ServiceLocatorInstanceHolder): void;
583
677
  /**
584
- * Gets a pre-prepared instance from this context.
678
+ * Adds a pre-prepared instance to this context.
585
679
  */
586
- getInstance(instanceName: string): any | undefined;
680
+ addInstance(token: InjectionToken<any, undefined>, instance: any): void;
587
681
  /**
588
682
  * Gets an instance holder from this context.
589
683
  */
590
- getHolder(instanceName: string): ServiceLocatorInstanceHolder | undefined;
684
+ get(instanceName: string): ServiceLocatorInstanceHolder | undefined;
591
685
  /**
592
686
  * Checks if this context has a pre-prepared instance.
593
687
  */
594
- hasInstance(instanceName: string): boolean;
688
+ has(instanceName: string): boolean;
595
689
  /**
596
690
  * Clears all instances and holders from this context.
597
691
  */
@@ -604,6 +698,22 @@ declare interface RequestContextHolder {
604
698
  * Sets metadata value by key.
605
699
  */
606
700
  setMetadata(key: string, value: any): void;
701
+ /**
702
+ * Filters holders based on a predicate function.
703
+ */
704
+ filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
705
+ /**
706
+ * Deletes a holder by name.
707
+ */
708
+ delete(name: string): boolean;
709
+ /**
710
+ * Gets the number of holders currently managed.
711
+ */
712
+ size(): number;
713
+ /**
714
+ * Checks if this manager has any holders.
715
+ */
716
+ isEmpty(): boolean;
607
717
  }
608
718
  export { RequestContextHolder }
609
719
  export { RequestContextHolder as RequestContextHolder_alias_1 }
@@ -664,7 +774,19 @@ declare class ServiceLocator {
664
774
  getOrThrowInstance<Instance>(token: AnyInjectableType, args: any): Promise<Instance>;
665
775
  getSyncInstance<Instance, Schema extends InjectionTokenSchemaType | undefined>(token: AnyInjectableType, args: Schema extends ZodObject ? z.input<Schema> : Schema extends ZodOptional<ZodObject> ? z.input<Schema> | undefined : undefined): Instance | null;
666
776
  invalidate(service: string, round?: number): Promise<any>;
667
- ready(): Promise<null>;
777
+ /**
778
+ * Invalidates a single holder based on its current status.
779
+ */
780
+ private invalidateHolder;
781
+ /**
782
+ * Destroys a holder and cleans up its resources.
783
+ */
784
+ private destroyHolder;
785
+ ready(): Promise<void>;
786
+ /**
787
+ * Waits for a holder to settle (either created, destroyed, or error state).
788
+ */
789
+ private waitForHolderToSettle;
668
790
  /**
669
791
  * Begins a new request context with the given parameters.
670
792
  * @param requestId Unique identifier for this request
@@ -701,6 +823,23 @@ declare class ServiceLocator {
701
823
  * Gets an instance by its instance name, handling all the logic after instance name creation.
702
824
  */
703
825
  private retrieveOrCreateInstanceByInstanceName;
826
+ /**
827
+ * Attempts to retrieve an existing instance, handling request-scoped and singleton instances.
828
+ * Returns null if no instance exists and a new one should be created.
829
+ */
830
+ private tryGetExistingInstance;
831
+ /**
832
+ * Attempts to get a request-scoped instance if applicable.
833
+ */
834
+ private tryGetRequestScopedInstance;
835
+ /**
836
+ * Attempts to get a singleton instance from the manager.
837
+ */
838
+ private tryGetSingletonInstance;
839
+ /**
840
+ * Waits for an instance holder to be ready and returns the appropriate result.
841
+ */
842
+ private waitForInstanceReady;
704
843
  /**
705
844
  * Emits events to listeners for instance lifecycle events.
706
845
  */
@@ -713,6 +852,26 @@ declare class ServiceLocator {
713
852
  * Instantiates a service from the registry using the service instantiator.
714
853
  */
715
854
  private instantiateServiceFromRegistry;
855
+ /**
856
+ * Handles the result of service instantiation.
857
+ */
858
+ private handleInstantiationResult;
859
+ /**
860
+ * Handles successful service instantiation.
861
+ */
862
+ private handleInstantiationSuccess;
863
+ /**
864
+ * Handles service instantiation errors.
865
+ */
866
+ private handleInstantiationError;
867
+ /**
868
+ * Stores an instance holder based on its scope.
869
+ */
870
+ private storeInstanceByScope;
871
+ /**
872
+ * Tries to get a pre-prepared instance from request contexts.
873
+ */
874
+ private tryGetPrePreparedInstance;
716
875
  /**
717
876
  * Creates a factory context for dependency injection during service instantiation.
718
877
  * @param contextHolder Optional request context holder for priority-based resolution
@@ -722,6 +881,10 @@ declare class ServiceLocator {
722
881
  * Generates a unique instance name based on token and arguments.
723
882
  */
724
883
  private generateInstanceName;
884
+ /**
885
+ * Formats a single argument value for instance name generation.
886
+ */
887
+ private formatArgValue;
725
888
  }
726
889
  export { ServiceLocator }
727
890
  export { ServiceLocator as ServiceLocator_alias_1 }
@@ -821,29 +984,11 @@ declare enum ServiceLocatorInstanceHolderStatus {
821
984
  export { ServiceLocatorInstanceHolderStatus }
822
985
  export { ServiceLocatorInstanceHolderStatus as ServiceLocatorInstanceHolderStatus_alias_1 }
823
986
 
824
- declare class ServiceLocatorManager {
825
- private readonly logger;
826
- private readonly instancesHolders;
987
+ declare class ServiceLocatorManager extends BaseInstanceHolderManager {
827
988
  constructor(logger?: Console | null);
828
989
  get(name: string): [InstanceExpired | InstanceDestroying, ServiceLocatorInstanceHolder] | [InstanceNotFound] | [undefined, ServiceLocatorInstanceHolder];
829
990
  set(name: string, holder: ServiceLocatorInstanceHolder): void;
830
991
  has(name: string): [InstanceExpired | InstanceDestroying] | [undefined, boolean];
831
- delete(name: string): boolean;
832
- filter(predicate: (value: ServiceLocatorInstanceHolder<any>, key: string) => boolean): Map<string, ServiceLocatorInstanceHolder>;
833
- /**
834
- * Creates a new holder with Creating status and a deferred creation promise.
835
- * This is useful for creating placeholder holders that can be fulfilled later.
836
- * @param name The name of the instance
837
- * @param type The injectable type
838
- * @param scope The injectable scope
839
- * @param deps Optional set of dependencies
840
- * @param ttl Optional time-to-live in milliseconds (defaults to Infinity)
841
- * @returns A tuple containing the deferred promise and the holder
842
- */
843
- createCreatingHolder<Instance>(name: string, type: InjectableType, scope: InjectableScope, deps?: Set<string>, ttl?: number): [
844
- ReturnType<typeof createDeferred<[undefined, Instance]>>,
845
- ServiceLocatorInstanceHolder<Instance>
846
- ];
847
992
  /**
848
993
  * Creates a new holder with Created status and an actual instance.
849
994
  * This is useful for creating holders that already have their instance ready.
package/lib/index.d.mts CHANGED
@@ -27,6 +27,7 @@ export { PopUnion } from './_tsup-dts-rollup.mjs';
27
27
  export { IsUnion } from './_tsup-dts-rollup.mjs';
28
28
  export { UnionToArray } from './_tsup-dts-rollup.mjs';
29
29
  export { InjectState } from './_tsup-dts-rollup.mjs';
30
+ export { BaseInstanceHolderManager_alias_1 as BaseInstanceHolderManager } from './_tsup-dts-rollup.mjs';
30
31
  export { EventsConfig_alias_1 as EventsConfig } from './_tsup-dts-rollup.mjs';
31
32
  export { EventsNames_alias_1 as EventsNames } from './_tsup-dts-rollup.mjs';
32
33
  export { EventsArgs_alias_1 as EventsArgs } from './_tsup-dts-rollup.mjs';
package/lib/index.d.ts CHANGED
@@ -27,6 +27,7 @@ export { PopUnion } from './_tsup-dts-rollup.js';
27
27
  export { IsUnion } from './_tsup-dts-rollup.js';
28
28
  export { UnionToArray } from './_tsup-dts-rollup.js';
29
29
  export { InjectState } from './_tsup-dts-rollup.js';
30
+ export { BaseInstanceHolderManager_alias_1 as BaseInstanceHolderManager } from './_tsup-dts-rollup.js';
30
31
  export { EventsConfig_alias_1 as EventsConfig } from './_tsup-dts-rollup.js';
31
32
  export { EventsNames_alias_1 as EventsNames } from './_tsup-dts-rollup.js';
32
33
  export { EventsArgs_alias_1 as EventsArgs } from './_tsup-dts-rollup.js';