@mxweb/core 1.0.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/LICENSE +21 -0
- package/README.md +61 -0
- package/dist/application.d.ts +402 -0
- package/dist/application.js +1 -0
- package/dist/application.mjs +1 -0
- package/dist/common.d.ts +323 -0
- package/dist/common.js +1 -0
- package/dist/common.mjs +1 -0
- package/dist/config.d.ts +258 -0
- package/dist/config.js +1 -0
- package/dist/config.mjs +1 -0
- package/dist/context.d.ts +48 -0
- package/dist/context.js +1 -0
- package/dist/context.mjs +1 -0
- package/dist/controller.d.ts +238 -0
- package/dist/controller.js +1 -0
- package/dist/controller.mjs +1 -0
- package/dist/decorator.d.ts +349 -0
- package/dist/decorator.js +1 -0
- package/dist/decorator.mjs +1 -0
- package/dist/error.d.ts +301 -0
- package/dist/error.js +1 -0
- package/dist/error.mjs +1 -0
- package/dist/execute.d.ts +469 -0
- package/dist/execute.js +1 -0
- package/dist/execute.mjs +1 -0
- package/dist/feature.d.ts +239 -0
- package/dist/feature.js +1 -0
- package/dist/feature.mjs +1 -0
- package/dist/hooks.d.ts +251 -0
- package/dist/hooks.js +1 -0
- package/dist/hooks.mjs +1 -0
- package/dist/index.d.ts +14 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +1 -0
- package/dist/logger.d.ts +360 -0
- package/dist/logger.js +1 -0
- package/dist/logger.mjs +1 -0
- package/dist/response.d.ts +665 -0
- package/dist/response.js +1 -0
- package/dist/response.mjs +1 -0
- package/dist/route.d.ts +298 -0
- package/dist/route.js +1 -0
- package/dist/route.mjs +1 -0
- package/dist/router.d.ts +205 -0
- package/dist/router.js +1 -0
- package/dist/router.mjs +1 -0
- package/dist/service.d.ts +261 -0
- package/dist/service.js +1 -0
- package/dist/service.mjs +1 -0
- package/package.json +168 -0
package/dist/common.d.ts
ADDED
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Common types, interfaces, and utilities used throughout the @mxweb/core framework.
|
|
3
|
+
* This module provides foundational types for dependency injection, routing, and lifecycle management.
|
|
4
|
+
* @module common
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* Interface for Application-level dependency injects.
|
|
8
|
+
* All global injects must implement this interface to ensure consistent lifecycle management.
|
|
9
|
+
*
|
|
10
|
+
* @remarks
|
|
11
|
+
* Application injects are singleton instances that persist across all requests.
|
|
12
|
+
* They are initialized once when the first request arrives and destroyed when the application shuts down.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* class DatabaseConnection implements ApplicationInject {
|
|
17
|
+
* private connection: Connection;
|
|
18
|
+
*
|
|
19
|
+
* async onInit() {
|
|
20
|
+
* this.connection = await createConnection();
|
|
21
|
+
* console.log("Database connected");
|
|
22
|
+
* }
|
|
23
|
+
*
|
|
24
|
+
* async onDestroy() {
|
|
25
|
+
* await this.connection.close();
|
|
26
|
+
* console.log("Database disconnected");
|
|
27
|
+
* }
|
|
28
|
+
* }
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export interface ApplicationInject {
|
|
32
|
+
/**
|
|
33
|
+
* Called when the inject is initialized (on first request).
|
|
34
|
+
* Use this to establish connections, load resources, or perform async setup.
|
|
35
|
+
*/
|
|
36
|
+
onInit?(): void | Promise<void>;
|
|
37
|
+
/**
|
|
38
|
+
* Called when the application is shutting down (SIGTERM/SIGINT).
|
|
39
|
+
* Use this to clean up resources, close connections, or flush buffers.
|
|
40
|
+
*/
|
|
41
|
+
onDestroy?(): void | Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Interface for Feature-specific dependency injects.
|
|
45
|
+
* Use this for injects that are scoped to a specific feature/module.
|
|
46
|
+
*
|
|
47
|
+
* @remarks
|
|
48
|
+
* Feature injects are local to a feature and can have different instances per feature.
|
|
49
|
+
* They are loaded when the feature is first accessed and destroyed on application shutdown.
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* ```ts
|
|
53
|
+
* class ProductRepository implements FeatureInject {
|
|
54
|
+
* async onFeature() {
|
|
55
|
+
* console.log("ProductRepository initialized for this feature");
|
|
56
|
+
* }
|
|
57
|
+
*
|
|
58
|
+
* async onFeatureDestroy() {
|
|
59
|
+
* console.log("ProductRepository destroyed");
|
|
60
|
+
* }
|
|
61
|
+
* }
|
|
62
|
+
* ```
|
|
63
|
+
*/
|
|
64
|
+
export interface FeatureInject {
|
|
65
|
+
/**
|
|
66
|
+
* Called when the feature is loaded.
|
|
67
|
+
* Use this for feature-specific initialization.
|
|
68
|
+
*/
|
|
69
|
+
onFeature?(): void | Promise<void>;
|
|
70
|
+
/**
|
|
71
|
+
* Called when the feature is destroyed/shutdown.
|
|
72
|
+
* Use this for feature-specific cleanup.
|
|
73
|
+
*/
|
|
74
|
+
onFeatureDestroy?(): void | Promise<void>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Utility type for values that can be either synchronous or async.
|
|
78
|
+
* Commonly used for configuration that may need async resolution.
|
|
79
|
+
*
|
|
80
|
+
* @template Result - The type of the resolved value
|
|
81
|
+
* @template Arg - The argument type passed to the function (defaults to void)
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* // Can be used as a plain value
|
|
86
|
+
* const config: AsyncFn<Config> = { port: 3000 };
|
|
87
|
+
*
|
|
88
|
+
* // Or as an async resolver
|
|
89
|
+
* const config: AsyncFn<Config> = async () => {
|
|
90
|
+
* return await loadConfigFromEnv();
|
|
91
|
+
* };
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
export type AsyncFn<Result, Arg = void> = Result | ((arg: Arg) => Promise<Result>);
|
|
95
|
+
/**
|
|
96
|
+
* Payload structure for Next.js catch-all routes.
|
|
97
|
+
* Contains the promise of route parameters extracted from the URL path.
|
|
98
|
+
*
|
|
99
|
+
* @template Key - The key name used in the catch-all route (defaults to "path")
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```ts
|
|
103
|
+
* // For route: app/api/[[...path]]/route.ts
|
|
104
|
+
* // URL: /api/products/123
|
|
105
|
+
* // payload.params resolves to { path: ["products", "123"] }
|
|
106
|
+
* ```
|
|
107
|
+
*/
|
|
108
|
+
export interface RoutePayload<Key extends string = "path"> {
|
|
109
|
+
/** Promise containing the parsed path segments */
|
|
110
|
+
params: Promise<{
|
|
111
|
+
[K in Key]?: string[];
|
|
112
|
+
}>;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Function type for middleware next() callback.
|
|
116
|
+
* Call this function to continue to the next middleware in the chain.
|
|
117
|
+
*/
|
|
118
|
+
export type RouteNextHandler = () => void;
|
|
119
|
+
/**
|
|
120
|
+
* Function type for call handlers used in interceptors.
|
|
121
|
+
* Returns a promise of the handler result.
|
|
122
|
+
*
|
|
123
|
+
* @template T - The type of the resolved value
|
|
124
|
+
*/
|
|
125
|
+
export type CallHandler<T = unknown> = () => Promise<T>;
|
|
126
|
+
/**
|
|
127
|
+
* Interface for pipe transformers.
|
|
128
|
+
* Pipes are used to transform input data before it reaches the handler.
|
|
129
|
+
*
|
|
130
|
+
* @template Input - The type of input value
|
|
131
|
+
* @template Output - The type of transformed output value
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```ts
|
|
135
|
+
* class ValidationPipe implements PipeTransform<unknown, ValidatedDto> {
|
|
136
|
+
* transform(value: unknown): ValidatedDto {
|
|
137
|
+
* // Validate and transform the input
|
|
138
|
+
* return validateAndTransform(value);
|
|
139
|
+
* }
|
|
140
|
+
* }
|
|
141
|
+
* ```
|
|
142
|
+
*/
|
|
143
|
+
export interface PipeTransform<Input = unknown, Output = unknown> {
|
|
144
|
+
/**
|
|
145
|
+
* Transforms the input value to the output value.
|
|
146
|
+
*
|
|
147
|
+
* @param value - The input value to transform
|
|
148
|
+
* @returns The transformed value (can be async)
|
|
149
|
+
*/
|
|
150
|
+
transform(value: Input): Output | Promise<Output>;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* Constructor type for Pipe classes.
|
|
154
|
+
*
|
|
155
|
+
* @template Input - The type of input value the pipe accepts
|
|
156
|
+
* @template Output - The type of output value the pipe produces
|
|
157
|
+
*/
|
|
158
|
+
export type Pipe<Input = unknown, Output = unknown> = new (...args: unknown[]) => PipeTransform<Input, Output>;
|
|
159
|
+
/**
|
|
160
|
+
* Constructor type for inject classes.
|
|
161
|
+
* Used when registering injects that need to be instantiated.
|
|
162
|
+
*
|
|
163
|
+
* @template T - The type of the inject instance (must implement ApplicationInject)
|
|
164
|
+
*/
|
|
165
|
+
export type InjectClass<T extends ApplicationInject = ApplicationInject> = new (...args: unknown[]) => T;
|
|
166
|
+
/**
|
|
167
|
+
* Generic class constructor type.
|
|
168
|
+
*
|
|
169
|
+
* @template T - The type of instance the constructor creates
|
|
170
|
+
* @template Injects - Tuple type of constructor arguments
|
|
171
|
+
*/
|
|
172
|
+
export interface ClassContructor<T, Injects extends any[] = []> {
|
|
173
|
+
new (...args: Injects): T;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Interface for injectable classes with singleton and factory methods.
|
|
177
|
+
* Classes implementing this interface can be registered in the InjectionRegistry.
|
|
178
|
+
*
|
|
179
|
+
* @template T - The type of instance the class creates
|
|
180
|
+
* @template Args - Tuple type of constructor/factory arguments
|
|
181
|
+
*
|
|
182
|
+
* @example
|
|
183
|
+
* ```ts
|
|
184
|
+
* class UserService implements InjectedClass<UserService> {
|
|
185
|
+
* static readonly injectionName = "userService";
|
|
186
|
+
*
|
|
187
|
+
* private static instance: UserService | null = null;
|
|
188
|
+
*
|
|
189
|
+
* static singleton(): UserService {
|
|
190
|
+
* if (!this.instance) {
|
|
191
|
+
* this.instance = new UserService();
|
|
192
|
+
* }
|
|
193
|
+
* return this.instance;
|
|
194
|
+
* }
|
|
195
|
+
*
|
|
196
|
+
* static get(): UserService {
|
|
197
|
+
* return new UserService();
|
|
198
|
+
* }
|
|
199
|
+
* }
|
|
200
|
+
* ```
|
|
201
|
+
*/
|
|
202
|
+
export interface InjectedClass<T, Args extends any[] = []> extends ClassContructor<T, Args> {
|
|
203
|
+
/**
|
|
204
|
+
* Factory method to get a new instance.
|
|
205
|
+
* @param args - Arguments to pass to the constructor
|
|
206
|
+
* @returns A new instance or null if creation fails
|
|
207
|
+
*/
|
|
208
|
+
get(...args: Args): T | null;
|
|
209
|
+
/**
|
|
210
|
+
* Factory method to get a singleton instance.
|
|
211
|
+
* @param args - Arguments to pass to the constructor (only used on first call)
|
|
212
|
+
* @returns The singleton instance or null if creation fails
|
|
213
|
+
*/
|
|
214
|
+
singleton(...args: Args): T | null;
|
|
215
|
+
/** Unique name for this injectable class */
|
|
216
|
+
readonly injectionName: string;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Global registry for injectable classes and their singleton instances.
|
|
220
|
+
* Provides static methods to register, retrieve, and manage injectable dependencies.
|
|
221
|
+
*
|
|
222
|
+
* @remarks
|
|
223
|
+
* This registry acts as a simple IoC container for managing class constructors
|
|
224
|
+
* and their singleton instances across the application.
|
|
225
|
+
*
|
|
226
|
+
* @example
|
|
227
|
+
* ```ts
|
|
228
|
+
* // Register an injectable class
|
|
229
|
+
* InjectionRegistry.registry("userService", UserService);
|
|
230
|
+
*
|
|
231
|
+
* // Retrieve and use
|
|
232
|
+
* const UserServiceClass = InjectionRegistry.get("userService");
|
|
233
|
+
* const instance = UserServiceClass?.singleton();
|
|
234
|
+
*
|
|
235
|
+
* // Store singleton instance
|
|
236
|
+
* InjectionRegistry.setInstance("userService", instance);
|
|
237
|
+
* ```
|
|
238
|
+
*/
|
|
239
|
+
export declare class InjectionRegistry {
|
|
240
|
+
/** Map of registered class constructors by name */
|
|
241
|
+
private static constructors;
|
|
242
|
+
/** Map of singleton instances by name */
|
|
243
|
+
private static instances;
|
|
244
|
+
/**
|
|
245
|
+
* Registers an injectable class constructor with a given name.
|
|
246
|
+
*
|
|
247
|
+
* @template T - The type of instance the class creates
|
|
248
|
+
* @template Args - Tuple type of constructor arguments
|
|
249
|
+
* @param name - Unique name to register the class under
|
|
250
|
+
* @param Contructor - The injectable class constructor
|
|
251
|
+
*/
|
|
252
|
+
static registry<T, Args extends any[] = []>(name: string, Contructor: InjectedClass<T, Args>): void;
|
|
253
|
+
/**
|
|
254
|
+
* Returns a copy of all registered class constructors.
|
|
255
|
+
*
|
|
256
|
+
* @returns A new Map containing all registered name-constructor pairs
|
|
257
|
+
*/
|
|
258
|
+
static getAll(): Map<string, InjectedClass<any, any[]>>;
|
|
259
|
+
/**
|
|
260
|
+
* Retrieves a registered class constructor by name.
|
|
261
|
+
*
|
|
262
|
+
* @template T - The type of instance the class creates
|
|
263
|
+
* @template Args - Tuple type of constructor arguments
|
|
264
|
+
* @param name - The name the class was registered under
|
|
265
|
+
* @returns The class constructor or null if not found
|
|
266
|
+
*/
|
|
267
|
+
static get<T, Args extends any[] = []>(name: string): InjectedClass<T, Args> | null;
|
|
268
|
+
/**
|
|
269
|
+
* Checks if a class constructor is registered under the given name.
|
|
270
|
+
*
|
|
271
|
+
* @param name - The name to check
|
|
272
|
+
* @returns true if a constructor is registered, false otherwise
|
|
273
|
+
*/
|
|
274
|
+
static has(name: string): boolean;
|
|
275
|
+
/**
|
|
276
|
+
* Returns an array of all registered injection names.
|
|
277
|
+
*
|
|
278
|
+
* @returns Array of registered names
|
|
279
|
+
*/
|
|
280
|
+
static names(): string[];
|
|
281
|
+
/**
|
|
282
|
+
* Stores a singleton instance by name.
|
|
283
|
+
*
|
|
284
|
+
* @param name - The name to store the instance under
|
|
285
|
+
* @param instance - The instance to store
|
|
286
|
+
*/
|
|
287
|
+
static setInstance(name: string, instance: unknown): void;
|
|
288
|
+
/**
|
|
289
|
+
* Retrieves a stored singleton instance by name.
|
|
290
|
+
*
|
|
291
|
+
* @template T - The expected type of the instance
|
|
292
|
+
* @param name - The name the instance was stored under
|
|
293
|
+
* @returns The instance or undefined if not found
|
|
294
|
+
*/
|
|
295
|
+
static getInstance<T>(name: string): T | undefined;
|
|
296
|
+
/**
|
|
297
|
+
* Checks if a singleton instance exists for the given name.
|
|
298
|
+
*
|
|
299
|
+
* @param name - The name to check
|
|
300
|
+
* @returns true if an instance exists, false otherwise
|
|
301
|
+
*/
|
|
302
|
+
static hasInstance(name: string): boolean;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Enumeration of supported HTTP methods.
|
|
306
|
+
* Used throughout the framework for route matching and handler creation.
|
|
307
|
+
*/
|
|
308
|
+
export declare enum RouteMethod {
|
|
309
|
+
/** HTTP GET method - retrieve resources */
|
|
310
|
+
GET = "GET",
|
|
311
|
+
/** HTTP POST method - create resources */
|
|
312
|
+
POST = "POST",
|
|
313
|
+
/** HTTP PUT method - replace resources */
|
|
314
|
+
PUT = "PUT",
|
|
315
|
+
/** HTTP PATCH method - partial update resources */
|
|
316
|
+
PATCH = "PATCH",
|
|
317
|
+
/** HTTP DELETE method - remove resources */
|
|
318
|
+
DELETE = "DELETE",
|
|
319
|
+
/** HTTP HEAD method - retrieve headers only */
|
|
320
|
+
HEAD = "HEAD",
|
|
321
|
+
/** HTTP OPTIONS method - CORS preflight requests */
|
|
322
|
+
OPTIONS = "OPTIONS"
|
|
323
|
+
}
|
package/dist/common.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";class t{static registry(t,s){this.constructors.set(t,s)}static getAll(){return new Map(this.constructors)}static get(t){return this.constructors.get(t)||null}static has(t){return this.constructors.has(t)}static names(){return Array.from(this.constructors.keys())}static setInstance(t,s){this.instances.set(t,s)}static getInstance(t){return this.instances.get(t)}static hasInstance(t){return this.instances.has(t)}}var s;t.constructors=new Map,t.instances=new Map,exports.RouteMethod=void 0,(s=exports.RouteMethod||(exports.RouteMethod={})).GET="GET",s.POST="POST",s.PUT="PUT",s.PATCH="PATCH",s.DELETE="DELETE",s.HEAD="HEAD",s.OPTIONS="OPTIONS",exports.InjectionRegistry=t;
|
package/dist/common.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
class t{static registry(t,s){this.constructors.set(t,s)}static getAll(){return new Map(this.constructors)}static get(t){return this.constructors.get(t)||null}static has(t){return this.constructors.has(t)}static names(){return Array.from(this.constructors.keys())}static setInstance(t,s){this.instances.set(t,s)}static getInstance(t){return this.instances.get(t)}static hasInstance(t){return this.instances.has(t)}}var s;t.constructors=new Map,t.instances=new Map,function(t){t.GET="GET",t.POST="POST",t.PUT="PUT",t.PATCH="PATCH",t.DELETE="DELETE",t.HEAD="HEAD",t.OPTIONS="OPTIONS"}(s||(s={}));export{t as InjectionRegistry,s as RouteMethod};
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Configuration management module for @mxweb/core framework.
|
|
3
|
+
* Provides a centralized configuration system similar to @nestjs/config.
|
|
4
|
+
* @module config
|
|
5
|
+
*/
|
|
6
|
+
import { ApplicationInject } from "./common";
|
|
7
|
+
/**
|
|
8
|
+
* Configuration management class that provides a centralized way to register
|
|
9
|
+
* and access application configuration values.
|
|
10
|
+
*
|
|
11
|
+
* This class implements the {@link ApplicationInject} interface, allowing it
|
|
12
|
+
* to be injected into the Application and participate in lifecycle management.
|
|
13
|
+
*
|
|
14
|
+
* @remarks
|
|
15
|
+
* - Configuration must be registered BEFORE importing features
|
|
16
|
+
* - Supports both synchronous and asynchronous configuration providers
|
|
17
|
+
* - Uses lazy evaluation - factories are only called when config is first accessed
|
|
18
|
+
* - Singleton pattern ensures consistent configuration across the application
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* ```ts
|
|
22
|
+
* // Step 1: Register config in config.ts (before importing features)
|
|
23
|
+
* import { Config } from "@mxweb/core";
|
|
24
|
+
*
|
|
25
|
+
* Config.register("dbType", () => "mongodb");
|
|
26
|
+
* Config.register("apiVersion", () => "v1");
|
|
27
|
+
* Config.registerAsync("secretKey", async () => await loadSecret());
|
|
28
|
+
*
|
|
29
|
+
* // Step 2: Import config before features in route.ts
|
|
30
|
+
* import "./config";
|
|
31
|
+
* import "@/features/products/product.feature";
|
|
32
|
+
*
|
|
33
|
+
* // Step 3: Inject Config into Application
|
|
34
|
+
* const app = Application.create({
|
|
35
|
+
* injects: {
|
|
36
|
+
* config: Config.forRoot(),
|
|
37
|
+
* },
|
|
38
|
+
* });
|
|
39
|
+
*
|
|
40
|
+
* // Step 4: Access config values anywhere
|
|
41
|
+
* const dbType = Config.get<string>("dbType"); // "mongodb"
|
|
42
|
+
* const secret = await Config.getAsync<string>("secretKey");
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* @implements {ApplicationInject}
|
|
46
|
+
*/
|
|
47
|
+
export declare class Config implements ApplicationInject {
|
|
48
|
+
/** Singleton instance of Config */
|
|
49
|
+
private static instance;
|
|
50
|
+
/** Store for resolved configuration values */
|
|
51
|
+
private static store;
|
|
52
|
+
/** Map of synchronous configuration factory functions */
|
|
53
|
+
private static providers;
|
|
54
|
+
/** Map of asynchronous configuration factory functions */
|
|
55
|
+
private static asyncProviders;
|
|
56
|
+
/** Flag indicating if sync providers have been built */
|
|
57
|
+
private static built;
|
|
58
|
+
/** Flag indicating if async providers have been built */
|
|
59
|
+
private static asyncBuilt;
|
|
60
|
+
/**
|
|
61
|
+
* Creates and returns the singleton Config instance for injection into Application.
|
|
62
|
+
*
|
|
63
|
+
* @returns The singleton Config instance
|
|
64
|
+
*
|
|
65
|
+
* @example
|
|
66
|
+
* ```ts
|
|
67
|
+
* const app = Application.create({
|
|
68
|
+
* injects: {
|
|
69
|
+
* config: Config.forRoot(),
|
|
70
|
+
* },
|
|
71
|
+
* });
|
|
72
|
+
* ```
|
|
73
|
+
*/
|
|
74
|
+
static forRoot(): Config;
|
|
75
|
+
/**
|
|
76
|
+
* ApplicationInject lifecycle hook - called when the inject is initialized.
|
|
77
|
+
* Builds all async providers to ensure configuration is ready.
|
|
78
|
+
*
|
|
79
|
+
* @returns Promise that resolves when all async config is built
|
|
80
|
+
*/
|
|
81
|
+
onInit(): Promise<void>;
|
|
82
|
+
/**
|
|
83
|
+
* Registers a synchronous configuration provider.
|
|
84
|
+
* The factory function will be called lazily when the config value is first accessed.
|
|
85
|
+
*
|
|
86
|
+
* @template T - The type of the configuration value
|
|
87
|
+
* @param key - Unique key to identify this configuration
|
|
88
|
+
* @param factory - Factory function that returns the configuration value
|
|
89
|
+
* @returns The Config class for method chaining
|
|
90
|
+
*
|
|
91
|
+
* @example
|
|
92
|
+
* ```ts
|
|
93
|
+
* Config.register("port", () => 3000);
|
|
94
|
+
* Config.register("env", () => process.env.NODE_ENV ?? "development");
|
|
95
|
+
*
|
|
96
|
+
* // Method chaining
|
|
97
|
+
* Config
|
|
98
|
+
* .register("db.host", () => "localhost")
|
|
99
|
+
* .register("db.port", () => 5432);
|
|
100
|
+
* ```
|
|
101
|
+
*/
|
|
102
|
+
static register<T = unknown>(key: string, factory: () => T): typeof Config;
|
|
103
|
+
/**
|
|
104
|
+
* Registers an asynchronous configuration provider.
|
|
105
|
+
* The factory function will be called lazily when buildAsync() is invoked.
|
|
106
|
+
*
|
|
107
|
+
* @template T - The type of the configuration value
|
|
108
|
+
* @param key - Unique key to identify this configuration
|
|
109
|
+
* @param factory - Async factory function that returns the configuration value
|
|
110
|
+
* @returns The Config class for method chaining
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```ts
|
|
114
|
+
* Config.registerAsync("secretKey", async () => {
|
|
115
|
+
* return await fetchSecretFromVault();
|
|
116
|
+
* });
|
|
117
|
+
*
|
|
118
|
+
* Config.registerAsync("remoteConfig", async () => {
|
|
119
|
+
* const response = await fetch("https://config.example.com/app");
|
|
120
|
+
* return response.json();
|
|
121
|
+
* });
|
|
122
|
+
* ```
|
|
123
|
+
*/
|
|
124
|
+
static registerAsync<T = unknown>(key: string, factory: () => T | Promise<T>): typeof Config;
|
|
125
|
+
/**
|
|
126
|
+
* Builds all synchronous providers and stores their values.
|
|
127
|
+
* This method is idempotent - subsequent calls have no effect.
|
|
128
|
+
*
|
|
129
|
+
* @remarks
|
|
130
|
+
* Called automatically when accessing config via {@link get} or {@link getOrThrow}.
|
|
131
|
+
*/
|
|
132
|
+
private static build;
|
|
133
|
+
/**
|
|
134
|
+
* Builds all providers (sync and async) and stores their values.
|
|
135
|
+
* This method is idempotent - subsequent calls have no effect.
|
|
136
|
+
*
|
|
137
|
+
* @remarks
|
|
138
|
+
* Called automatically when accessing config via {@link getAsync} or {@link getAsyncOrThrow}.
|
|
139
|
+
* Also called during {@link onInit} lifecycle hook.
|
|
140
|
+
*/
|
|
141
|
+
private static buildAsync;
|
|
142
|
+
/**
|
|
143
|
+
* Retrieves a configuration value by key (synchronous).
|
|
144
|
+
* Automatically builds sync providers if not already built.
|
|
145
|
+
*
|
|
146
|
+
* @template T - The expected type of the configuration value
|
|
147
|
+
* @param key - The configuration key to retrieve
|
|
148
|
+
* @returns The configuration value or undefined if not found
|
|
149
|
+
*
|
|
150
|
+
* @remarks
|
|
151
|
+
* This method only returns values from sync providers.
|
|
152
|
+
* For async providers, use {@link getAsync}.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```ts
|
|
156
|
+
* const port = Config.get<number>("port"); // 3000
|
|
157
|
+
* const missing = Config.get("nonexistent"); // undefined
|
|
158
|
+
* ```
|
|
159
|
+
*/
|
|
160
|
+
static get<T = unknown>(key: string): T | undefined;
|
|
161
|
+
/**
|
|
162
|
+
* Retrieves a configuration value by key (asynchronous).
|
|
163
|
+
* Automatically builds all providers (sync + async) if not already built.
|
|
164
|
+
*
|
|
165
|
+
* @template T - The expected type of the configuration value
|
|
166
|
+
* @param key - The configuration key to retrieve
|
|
167
|
+
* @returns Promise resolving to the configuration value or undefined if not found
|
|
168
|
+
*
|
|
169
|
+
* @example
|
|
170
|
+
* ```ts
|
|
171
|
+
* const secret = await Config.getAsync<string>("secretKey");
|
|
172
|
+
* const remoteConfig = await Config.getAsync<RemoteConfig>("remoteConfig");
|
|
173
|
+
* ```
|
|
174
|
+
*/
|
|
175
|
+
static getAsync<T = unknown>(key: string): Promise<T | undefined>;
|
|
176
|
+
/**
|
|
177
|
+
* Retrieves a configuration value by key, throwing an error if not found (synchronous).
|
|
178
|
+
*
|
|
179
|
+
* @template T - The expected type of the configuration value
|
|
180
|
+
* @param key - The configuration key to retrieve
|
|
181
|
+
* @returns The configuration value
|
|
182
|
+
* @throws {Error} If the configuration key is not found
|
|
183
|
+
*
|
|
184
|
+
* @example
|
|
185
|
+
* ```ts
|
|
186
|
+
* const port = Config.getOrThrow<number>("port"); // 3000
|
|
187
|
+
* const missing = Config.getOrThrow("nonexistent"); // throws Error
|
|
188
|
+
* ```
|
|
189
|
+
*/
|
|
190
|
+
static getOrThrow<T = unknown>(key: string): T;
|
|
191
|
+
/**
|
|
192
|
+
* Retrieves a configuration value by key, throwing an error if not found (asynchronous).
|
|
193
|
+
*
|
|
194
|
+
* @template T - The expected type of the configuration value
|
|
195
|
+
* @param key - The configuration key to retrieve
|
|
196
|
+
* @returns Promise resolving to the configuration value
|
|
197
|
+
* @throws {Error} If the configuration key is not found
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* ```ts
|
|
201
|
+
* const secret = await Config.getAsyncOrThrow<string>("secretKey");
|
|
202
|
+
* ```
|
|
203
|
+
*/
|
|
204
|
+
static getAsyncOrThrow<T = unknown>(key: string): Promise<T>;
|
|
205
|
+
/**
|
|
206
|
+
* Checks if a configuration key exists (registered or already built).
|
|
207
|
+
*
|
|
208
|
+
* @param key - The configuration key to check
|
|
209
|
+
* @returns true if the key exists, false otherwise
|
|
210
|
+
*
|
|
211
|
+
* @example
|
|
212
|
+
* ```ts
|
|
213
|
+
* if (Config.has("featureFlag")) {
|
|
214
|
+
* // Feature is configured
|
|
215
|
+
* }
|
|
216
|
+
* ```
|
|
217
|
+
*/
|
|
218
|
+
static has(key: string): boolean;
|
|
219
|
+
/**
|
|
220
|
+
* Returns a copy of all built configuration values.
|
|
221
|
+
*
|
|
222
|
+
* @returns A new Map containing all built configuration key-value pairs
|
|
223
|
+
*
|
|
224
|
+
* @remarks
|
|
225
|
+
* Only includes values that have already been built.
|
|
226
|
+
* Call after {@link buildAsync} to ensure all values are included.
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```ts
|
|
230
|
+
* await Config.getAsync("anyKey"); // Ensure all are built
|
|
231
|
+
* const allConfig = Config.getAll();
|
|
232
|
+
* for (const [key, value] of allConfig) {
|
|
233
|
+
* console.log(`${key}: ${value}`);
|
|
234
|
+
* }
|
|
235
|
+
* ```
|
|
236
|
+
*/
|
|
237
|
+
static getAll(): Map<string, unknown>;
|
|
238
|
+
/**
|
|
239
|
+
* Resets all configuration state.
|
|
240
|
+
* Primarily used for testing to ensure clean state between tests.
|
|
241
|
+
*
|
|
242
|
+
* @remarks
|
|
243
|
+
* This method clears:
|
|
244
|
+
* - The singleton instance
|
|
245
|
+
* - All stored values
|
|
246
|
+
* - All registered providers (sync and async)
|
|
247
|
+
* - Build flags
|
|
248
|
+
*
|
|
249
|
+
* @example
|
|
250
|
+
* ```ts
|
|
251
|
+
* // In test setup/teardown
|
|
252
|
+
* beforeEach(() => {
|
|
253
|
+
* Config.reset();
|
|
254
|
+
* });
|
|
255
|
+
* ```
|
|
256
|
+
*/
|
|
257
|
+
static reset(): void;
|
|
258
|
+
}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";class t{static forRoot(){return t.instance||(t.instance=new t),t.instance}async onInit(){await t.buildAsync()}static register(s,r){return t.providers.set(s,r),t}static registerAsync(s,r){return t.asyncProviders.set(s,r),t}static build(){if(!t.built){for(const[s,r]of t.providers)t.store.has(s)||t.store.set(s,r());t.built=!0}}static async buildAsync(){if(t.build(),!t.asyncBuilt){for(const[s,r]of t.asyncProviders)t.store.has(s)||t.store.set(s,await r());t.asyncBuilt=!0}}static get(s){return t.build(),t.store.get(s)}static async getAsync(s){return await t.buildAsync(),t.store.get(s)}static getOrThrow(s){if(t.build(),!t.store.has(s))throw new Error(`[Config] Config key "${s}" not found`);return t.store.get(s)}static async getAsyncOrThrow(s){if(await t.buildAsync(),!t.store.has(s))throw new Error(`[Config] Config key "${s}" not found`);return t.store.get(s)}static has(s){return t.store.has(s)||t.providers.has(s)||t.asyncProviders.has(s)}static getAll(){return new Map(t.store)}static reset(){t.instance=null,t.store.clear(),t.providers.clear(),t.asyncProviders.clear(),t.built=!1,t.asyncBuilt=!1}}t.instance=null,t.store=new Map,t.providers=new Map,t.asyncProviders=new Map,t.built=!1,t.asyncBuilt=!1,exports.Config=t;
|
package/dist/config.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
class t{static forRoot(){return t.instance||(t.instance=new t),t.instance}async onInit(){await t.buildAsync()}static register(s,r){return t.providers.set(s,r),t}static registerAsync(s,r){return t.asyncProviders.set(s,r),t}static build(){if(!t.built){for(const[s,r]of t.providers)t.store.has(s)||t.store.set(s,r());t.built=!0}}static async buildAsync(){if(t.build(),!t.asyncBuilt){for(const[s,r]of t.asyncProviders)t.store.has(s)||t.store.set(s,await r());t.asyncBuilt=!0}}static get(s){return t.build(),t.store.get(s)}static async getAsync(s){return await t.buildAsync(),t.store.get(s)}static getOrThrow(s){if(t.build(),!t.store.has(s))throw new Error(`[Config] Config key "${s}" not found`);return t.store.get(s)}static async getAsyncOrThrow(s){if(await t.buildAsync(),!t.store.has(s))throw new Error(`[Config] Config key "${s}" not found`);return t.store.get(s)}static has(s){return t.store.has(s)||t.providers.has(s)||t.asyncProviders.has(s)}static getAll(){return new Map(t.store)}static reset(){t.instance=null,t.store.clear(),t.providers.clear(),t.asyncProviders.clear(),t.built=!1,t.asyncBuilt=!1}}t.instance=null,t.store=new Map,t.providers=new Map,t.asyncProviders=new Map,t.built=!1,t.asyncBuilt=!1;export{t as Config};
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Internal context module for request-scoped state management.
|
|
3
|
+
* This module provides access to the singleton ExecuteContext instance.
|
|
4
|
+
*
|
|
5
|
+
* @remarks
|
|
6
|
+
* **INTERNAL USE ONLY** - This module is not exported from the package.
|
|
7
|
+
* It provides a convenient way to access the ExecuteContext singleton
|
|
8
|
+
* throughout the framework internals without importing ExecuteContext directly.
|
|
9
|
+
*
|
|
10
|
+
* @internal
|
|
11
|
+
* @module context
|
|
12
|
+
*/
|
|
13
|
+
import { ExecuteContext } from "./execute";
|
|
14
|
+
/**
|
|
15
|
+
* Singleton ExecuteContext instance for managing request-scoped state.
|
|
16
|
+
*
|
|
17
|
+
* This instance uses AsyncLocalStorage to maintain request context across
|
|
18
|
+
* async operations, allowing services and controllers to access request
|
|
19
|
+
* data without explicit parameter passing.
|
|
20
|
+
*
|
|
21
|
+
* @remarks
|
|
22
|
+
* **INTERNAL USE ONLY** - Do not export from the package.
|
|
23
|
+
*
|
|
24
|
+
* Used internally by:
|
|
25
|
+
* - Application: To run handlers within request scope
|
|
26
|
+
* - Controller: To access request context via `this.context`
|
|
27
|
+
* - Service: To access request context via `this.context`
|
|
28
|
+
* - Decorators: To extract request data (Body, Query, Params, etc.)
|
|
29
|
+
*
|
|
30
|
+
* @internal
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* ```ts
|
|
34
|
+
* // Internal usage in a module
|
|
35
|
+
* import { executeContext } from "./context";
|
|
36
|
+
*
|
|
37
|
+
* // Run code within request scope
|
|
38
|
+
* await executeContext.run(requestContext, async () => {
|
|
39
|
+
* // Access context anywhere in this scope
|
|
40
|
+
* const ctx = executeContext.getContext();
|
|
41
|
+
* });
|
|
42
|
+
*
|
|
43
|
+
* // Access HTTP helpers
|
|
44
|
+
* const body = await executeContext.switchHttp().json();
|
|
45
|
+
* const params = executeContext.switchHttp().params();
|
|
46
|
+
* ```
|
|
47
|
+
*/
|
|
48
|
+
export declare const executeContext: ExecuteContext;
|
package/dist/context.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"use strict";const e=require("./execute.js").ExecuteContext.instance;exports.executeContext=e;
|
package/dist/context.mjs
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{ExecuteContext as e}from"./execute.mjs";const t=e.instance;export{t as executeContext};
|