alepha 0.13.3 → 0.13.5

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 (138) hide show
  1. package/README.md +7 -7
  2. package/dist/api-files/index.browser.js +5 -5
  3. package/dist/api-files/index.d.ts +16 -16
  4. package/dist/api-files/index.js +9 -9
  5. package/dist/api-jobs/index.browser.js +5 -5
  6. package/dist/api-jobs/index.d.ts +17 -17
  7. package/dist/api-jobs/index.js +9 -9
  8. package/dist/api-notifications/index.browser.js +11 -11
  9. package/dist/api-notifications/index.d.ts +158 -158
  10. package/dist/api-notifications/index.js +11 -11
  11. package/dist/api-parameters/index.browser.js +2 -2
  12. package/dist/api-parameters/index.d.ts +3 -3
  13. package/dist/api-parameters/index.js +3 -3
  14. package/dist/api-users/index.browser.js +6 -6
  15. package/dist/api-users/index.d.ts +55 -55
  16. package/dist/api-users/index.js +36 -36
  17. package/dist/api-verifications/index.browser.js +5 -5
  18. package/dist/api-verifications/index.d.ts +9 -9
  19. package/dist/api-verifications/index.js +10 -10
  20. package/dist/batch/index.d.ts +3 -3
  21. package/dist/batch/index.js +3 -3
  22. package/dist/bin/index.js +1 -1
  23. package/dist/bucket/index.d.ts +6 -6
  24. package/dist/bucket/index.js +7 -7
  25. package/dist/cache/index.d.ts +4 -4
  26. package/dist/cache/index.js +5 -5
  27. package/dist/cache-redis/index.d.ts +2 -2
  28. package/dist/cache-redis/index.js +2 -2
  29. package/dist/cli/{dist-lGnqsKpu.js → dist-BlfFtOk2.js} +16 -16
  30. package/dist/cli/{dist-lGnqsKpu.js.map → dist-BlfFtOk2.js.map} +1 -1
  31. package/dist/cli/index.d.ts +31 -75
  32. package/dist/cli/index.js +94 -171
  33. package/dist/cli/index.js.map +1 -1
  34. package/dist/command/index.d.ts +8 -8
  35. package/dist/command/index.js +11 -10
  36. package/dist/command/index.js.map +1 -1
  37. package/dist/core/index.browser.js +40 -36
  38. package/dist/core/index.browser.js.map +1 -1
  39. package/dist/core/index.d.ts +255 -253
  40. package/dist/core/index.js +40 -36
  41. package/dist/core/index.js.map +1 -1
  42. package/dist/core/index.native.js +40 -36
  43. package/dist/core/index.native.js.map +1 -1
  44. package/dist/datetime/index.d.ts +3 -3
  45. package/dist/datetime/index.js +3 -3
  46. package/dist/email/index.d.ts +7 -7
  47. package/dist/email/index.js +42 -42
  48. package/dist/fake/index.d.ts +2 -2
  49. package/dist/fake/index.js +5 -5
  50. package/dist/file/index.d.ts +4 -4
  51. package/dist/file/index.js +4 -4
  52. package/dist/lock/index.d.ts +5 -5
  53. package/dist/lock/index.js +5 -5
  54. package/dist/lock-redis/index.d.ts +2 -2
  55. package/dist/lock-redis/index.js +2 -2
  56. package/dist/logger/index.d.ts +11 -11
  57. package/dist/logger/index.js +12 -12
  58. package/dist/orm/index.browser.js +12 -12
  59. package/dist/orm/index.d.ts +33 -33
  60. package/dist/orm/index.js +32 -32
  61. package/dist/queue/index.d.ts +7 -7
  62. package/dist/queue/index.js +6 -6
  63. package/dist/queue-redis/index.d.ts +2 -2
  64. package/dist/queue-redis/index.js +2 -2
  65. package/dist/redis/index.d.ts +13 -13
  66. package/dist/redis/index.js +3 -3
  67. package/dist/retry/index.d.ts +5 -5
  68. package/dist/retry/index.js +5 -5
  69. package/dist/router/index.d.ts +1 -1
  70. package/dist/router/index.js +1 -1
  71. package/dist/scheduler/index.d.ts +4 -4
  72. package/dist/scheduler/index.js +7 -7
  73. package/dist/security/index.browser.js +7 -7
  74. package/dist/security/index.d.ts +15 -15
  75. package/dist/security/index.js +46 -46
  76. package/dist/server/index.browser.js +14 -14
  77. package/dist/server/index.d.ts +26 -26
  78. package/dist/server/index.js +26 -26
  79. package/dist/server-auth/index.browser.js +6 -6
  80. package/dist/server-auth/index.d.ts +11 -11
  81. package/dist/server-auth/index.js +13 -13
  82. package/dist/server-cache/index.d.ts +2 -2
  83. package/dist/server-cache/index.js +2 -2
  84. package/dist/server-compress/index.d.ts +2 -2
  85. package/dist/server-compress/index.js +2 -2
  86. package/dist/server-cookies/index.browser.js +3 -3
  87. package/dist/server-cookies/index.d.ts +4 -4
  88. package/dist/server-cookies/index.js +4 -4
  89. package/dist/server-cors/index.d.ts +3 -3
  90. package/dist/server-cors/index.js +3 -3
  91. package/dist/server-health/index.d.ts +3 -3
  92. package/dist/server-health/index.js +3 -3
  93. package/dist/server-helmet/index.d.ts +2 -2
  94. package/dist/server-helmet/index.js +2 -2
  95. package/dist/server-links/index.browser.js +5 -5
  96. package/dist/server-links/index.d.ts +40 -40
  97. package/dist/server-links/index.js +7 -7
  98. package/dist/server-metrics/index.d.ts +2 -2
  99. package/dist/server-metrics/index.js +86 -86
  100. package/dist/server-multipart/index.d.ts +2 -2
  101. package/dist/server-multipart/index.js +2 -2
  102. package/dist/server-proxy/index.d.ts +3 -3
  103. package/dist/server-proxy/index.js +3 -3
  104. package/dist/server-rate-limit/index.d.ts +3 -3
  105. package/dist/server-rate-limit/index.js +3 -3
  106. package/dist/server-security/index.browser.js +1 -1
  107. package/dist/server-security/index.d.ts +4 -4
  108. package/dist/server-security/index.js +4 -4
  109. package/dist/server-static/index.d.ts +3 -3
  110. package/dist/server-static/index.js +3 -3
  111. package/dist/server-swagger/index.d.ts +3 -3
  112. package/dist/server-swagger/index.js +3 -3
  113. package/dist/sms/index.d.ts +6 -6
  114. package/dist/sms/index.js +6 -6
  115. package/dist/thread/index.d.ts +3 -3
  116. package/dist/thread/index.js +3 -3
  117. package/dist/topic/index.d.ts +6 -6
  118. package/dist/topic/index.js +6 -6
  119. package/dist/topic-redis/index.d.ts +2 -2
  120. package/dist/topic-redis/index.js +2 -2
  121. package/dist/vite/index.d.ts +17 -17
  122. package/dist/vite/index.js +20 -20
  123. package/dist/websocket/index.browser.js +9 -9
  124. package/dist/websocket/index.d.ts +17 -17
  125. package/dist/websocket/index.js +10 -10
  126. package/package.json +5 -4
  127. package/src/cli/apps/AlephaCli.ts +1 -2
  128. package/src/cli/commands/BiomeCommands.ts +4 -6
  129. package/src/cli/commands/CoreCommands.ts +2 -2
  130. package/src/cli/commands/DrizzleCommands.ts +76 -78
  131. package/src/cli/commands/VerifyCommands.ts +3 -5
  132. package/src/cli/commands/ViteCommands.ts +6 -8
  133. package/src/cli/index.ts +1 -1
  134. package/src/cli/services/{ProjectUtils.ts → AlephaCliUtils.ts} +101 -16
  135. package/src/command/providers/CliProvider.ts +12 -4
  136. package/src/core/Alepha.ts +14 -0
  137. package/src/core/primitives/$module.ts +1 -1
  138. package/src/cli/services/ProcessRunner.ts +0 -89
@@ -8,7 +8,7 @@ import { TLocalizedValidationError } from "typebox/error";
8
8
  import { Readable } from "node:stream";
9
9
  import { ReadableStream as ReadableStream$1 } from "node:stream/web";
10
10
 
11
- //#region src/core/constants/KIND.d.ts
11
+ //#region ../../src/core/constants/KIND.d.ts
12
12
  /**
13
13
  * Used for identifying primitives.
14
14
  *
@@ -16,7 +16,7 @@ import { ReadableStream as ReadableStream$1 } from "node:stream/web";
16
16
  */
17
17
  declare const KIND: unique symbol;
18
18
  //#endregion
19
- //#region src/core/constants/MODULE.d.ts
19
+ //#region ../../src/core/constants/MODULE.d.ts
20
20
  /**
21
21
  * Used for identifying modules.
22
22
  *
@@ -24,7 +24,7 @@ declare const KIND: unique symbol;
24
24
  */
25
25
  declare const MODULE: unique symbol;
26
26
  //#endregion
27
- //#region src/core/interfaces/Service.d.ts
27
+ //#region ../../src/core/interfaces/Service.d.ts
28
28
  /**
29
29
  * In Alepha, a service is a class that can be instantiated or an abstract class. Nothing more, nothing less...
30
30
  */
@@ -72,7 +72,7 @@ interface ServiceSubstitution<T extends object = any> {
72
72
  type ServiceEntry<T extends object = any> = Service<T> | ServiceSubstitution<T>;
73
73
  declare function isClass(func: any): func is InstantiableClass;
74
74
  //#endregion
75
- //#region src/core/helpers/primitive.d.ts
75
+ //#region ../../src/core/helpers/primitive.d.ts
76
76
  interface PrimitiveArgs<T extends object = {}> {
77
77
  options: T;
78
78
  alepha: Alepha;
@@ -106,7 +106,7 @@ declare const createPrimitive: <TPrimitive extends Primitive>(primitive: Instant
106
106
  [MODULE]?: Service;
107
107
  }, options: TPrimitive["options"]) => TPrimitive;
108
108
  //#endregion
109
- //#region src/core/interfaces/Async.d.ts
109
+ //#region ../../src/core/interfaces/Async.d.ts
110
110
  /**
111
111
  * Represents a value that can be either a value or a promise of value.
112
112
  */
@@ -120,7 +120,7 @@ type AsyncFn = (...args: any[]) => Async<any>;
120
120
  */
121
121
  type MaybePromise<T> = T extends Promise<any> ? T : Promise<T>;
122
122
  //#endregion
123
- //#region src/core/interfaces/LoggerInterface.d.ts
123
+ //#region ../../src/core/interfaces/LoggerInterface.d.ts
124
124
  type LogLevel = "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE" | "SILENT";
125
125
  interface LoggerInterface {
126
126
  trace(message: string, data?: unknown): void;
@@ -130,170 +130,7 @@ interface LoggerInterface {
130
130
  error(message: string, data?: unknown): void;
131
131
  }
132
132
  //#endregion
133
- //#region src/core/primitives/$inject.d.ts
134
- /**
135
- * Get the instance of the specified type from the context.
136
- *
137
- * ```ts
138
- * class A { }
139
- * class B {
140
- * a = $inject(A);
141
- * }
142
- * ```
143
- */
144
- declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions<T>) => T;
145
- declare class InjectPrimitive extends Primitive {}
146
- interface InjectOptions<T extends object = any> {
147
- /**
148
- * - 'transient' → Always a new instance on every inject. Zero caching.
149
- * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
150
- * - 'scoped' → One instance per AsyncLocalStorage context.
151
- * - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
152
- * - You can also start a manual scope via alepha.context.run(() => { ... }).
153
- * - When the scope ends, the scoped registry is discarded.
154
- *
155
- * @default "singleton"
156
- */
157
- lifetime?: "transient" | "singleton" | "scoped";
158
- /**
159
- * Constructor arguments to pass when creating a new instance.
160
- */
161
- args?: ConstructorParameters<InstantiableClass<T>>;
162
- /**
163
- * Parent that requested the instance.
164
- *
165
- * @internal
166
- */
167
- parent?: Service | null;
168
- }
169
- //#endregion
170
- //#region src/core/primitives/$module.d.ts
171
- /**
172
- * Wrap Services and Primitives into a Module.
173
- *
174
- * - A module is just a Service with some extra {@link Module}.
175
- * - You must attach a `name` to it.
176
- * - Name must follow the pattern: `project.module.submodule`. (e.g. `myapp.users.auth`).
177
- *
178
- * @example
179
- * ```ts
180
- * import { $module } from "alepha";
181
- * import { MyService } from "./MyService.ts";
182
- *
183
- * // export MyService, so it can be used everywhere (optional)
184
- * export * from "./MyService.ts";
185
- *
186
- * export default $module({
187
- * name: "my.project.module",
188
- * // MyService will have a module context "my.project.module"
189
- * services: [MyService],
190
- * });
191
- * ```
192
- *
193
- * ### Why Modules?
194
- *
195
- * #### Logging
196
- *
197
- * By default, AlephaLogger will log the module name in the logs.
198
- * This helps to identify where the logs are coming from.
199
- *
200
- * You can also set different log levels for different modules.
201
- * It means you can set 'some.very.specific.module' to 'debug' and keep the rest of the application to 'info'.
202
- *
203
- * #### Modulith
204
- *
205
- * Force to structure your application in modules, even if it's a single deployable unit.
206
- * It helps to keep a clean architecture and avoid monolithic applications.
207
- *
208
- * A strict mode flag will probably come to enforce module boundaries.
209
- * -> Throwing errors when a service from another module is injected.
210
- * But it's not implemented yet.
211
- *
212
- * ### When not to use Modules?
213
- *
214
- * Small applications does not need modules. It's better to keep it simple.
215
- * Modules are more useful when the application grows and needs to be structured.
216
- * If we speak with number of `$actions`, a module should be used when you have more than 30 actions in a single module.
217
- * Meaning that if you have 100 actions, you should have at least 3 modules.
218
- */
219
- declare const $module: <T extends object = {}>(options: ModulePrimitiveOptions) => Service<Module>;
220
- interface ModulePrimitiveOptions {
221
- /**
222
- * Name of the module.
223
- *
224
- * It should be in the format of `project.module.submodule`.
225
- */
226
- name: string;
227
- /**
228
- * List all services related to this module.
229
- *
230
- * If you don't declare 'register' function, all services will be registered automatically.
231
- * If you declare 'register' function, you must handle the registration of ALL services manually.
232
- */
233
- services?: Array<Service>;
234
- /**
235
- * List of $primitives to register in the module.
236
- */
237
- primitives?: Array<PrimitiveFactoryLike>;
238
- /**
239
- * By default, module will register ALL services.
240
- * You can override this behavior by providing a register function.
241
- * It's useful when you want to register services conditionally or in a specific order.
242
- *
243
- * Again, if you declare 'register', you must handle the registration of ALL services manually.
244
- */
245
- register?: (alepha: Alepha) => void;
246
- }
247
- /**
248
- * Base class for all modules.
249
- */
250
- declare abstract class Module {
251
- abstract readonly options: ModulePrimitiveOptions;
252
- abstract register(alepha: Alepha): void;
253
- static NAME_REGEX: RegExp;
254
- /**
255
- * Check if a Service is a Module.
256
- */
257
- static is(ctor: Service): boolean;
258
- /**
259
- * Get the Module of a Service.
260
- *
261
- * Returns undefined if the Service is not part of a Module.
262
- */
263
- static of(ctor: Service): Service<Module> | undefined;
264
- }
265
- /**
266
- * Helper type to add Module metadata to a Service.
267
- */
268
- type WithModule<T extends object = any> = T & {
269
- [MODULE]?: Service;
270
- };
271
- //#endregion
272
- //#region src/core/providers/AlsProvider.d.ts
273
- type AsyncLocalStorageData = any;
274
- declare class AlsProvider {
275
- static create: () => AsyncLocalStorage<AsyncLocalStorageData> | undefined;
276
- als?: AsyncLocalStorage<AsyncLocalStorageData>;
277
- constructor();
278
- createContextId(): string;
279
- run<R>(callback: () => R, data?: Record<string, any>): R;
280
- exists(): boolean;
281
- get<T>(key: string): T | undefined;
282
- set<T>(key: string, value: T): void;
283
- }
284
- //#endregion
285
- //#region src/core/providers/Json.d.ts
286
- /**
287
- * Mimics the JSON global object with stringify and parse methods.
288
- *
289
- * Used across the codebase via dependency injection.
290
- */
291
- declare class Json {
292
- stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
293
- parse(text: string, reviver?: (this: any, key: string, value: any) => any): any;
294
- }
295
- //#endregion
296
- //#region src/core/errors/AlephaError.d.ts
133
+ //#region ../../src/core/errors/AlephaError.d.ts
297
134
  /**
298
135
  * Default error class for Alepha.
299
136
  */
@@ -301,7 +138,7 @@ declare class AlephaError extends Error {
301
138
  name: string;
302
139
  }
303
140
  //#endregion
304
- //#region src/core/errors/TypeBoxError.d.ts
141
+ //#region ../../src/core/errors/TypeBoxError.d.ts
305
142
  declare class TypeBoxError extends AlephaError {
306
143
  name: string;
307
144
  readonly cause: TLocalizedValidationError;
@@ -315,7 +152,7 @@ interface TypeBoxErrorParams {
315
152
  requiredProperties?: string[];
316
153
  }
317
154
  //#endregion
318
- //#region src/core/helpers/FileLike.d.ts
155
+ //#region ../../src/core/helpers/FileLike.d.ts
319
156
  interface FileLike {
320
157
  /**
321
158
  * Filename.
@@ -378,7 +215,7 @@ declare const isFileLike: (value: any) => value is FileLike;
378
215
  type StreamLike = ReadableStream | ReadableStream$1 | Readable | NodeJS.ReadableStream;
379
216
  type TStream = TUnsafe$1<StreamLike>;
380
217
  //#endregion
381
- //#region src/core/providers/TypeProvider.d.ts
218
+ //#region ../../src/core/providers/TypeProvider.d.ts
382
219
  declare const isUUID: typeof TypeBoxFormat.IsUuid;
383
220
  declare const isEmail: typeof TypeBoxFormat.IsEmail;
384
221
  declare const isURL: typeof TypeBoxFormat.IsUrl;
@@ -492,8 +329,8 @@ declare class TypeProvider {
492
329
  * ```
493
330
  */
494
331
  readonly schema: TypeGuard;
495
- extend<T extends TSchema$1[], U$1 extends TProperties$1>(schema: [...T], properties: U$1, options?: TSchemaOptions): TInterface<T, U$1>;
496
- extend<T extends TObject$1, U$1 extends TProperties$1>(schema: T, properties: U$1, options?: TSchemaOptions): TInterface<[T], U$1>;
332
+ extend<T extends TSchema$1[], U extends TProperties$1>(schema: [...T], properties: U, options?: TSchemaOptions): TInterface<T, U>;
333
+ extend<T extends TObject$1, U extends TProperties$1>(schema: T, properties: U, options?: TSchemaOptions): TInterface<[T], U>;
497
334
  pick<T extends TObject$1, Indexer extends PropertyKey[]>(schema: T, keys: [...Indexer], options?: TObjectOptions$1): TPick$1<T, TKeysToIndexer$1<Indexer>>;
498
335
  omit<T extends TObject$1, Indexer extends PropertyKey[]>(schema: T, keys: [...Indexer], options?: TObjectOptions$1): TOmit<T, TKeysToIndexer$1<Indexer>>;
499
336
  partial<T extends TSchema$1>(schema: T, options?: TSchemaOptions): TPartial<T>;
@@ -675,7 +512,226 @@ interface TTextOptions extends TStringOptions$1 {
675
512
  }
676
513
  declare const t: TypeProvider;
677
514
  //#endregion
678
- //#region src/core/providers/SchemaCodec.d.ts
515
+ //#region ../../src/core/primitives/$atom.d.ts
516
+ /**
517
+ * Define an atom for state management.
518
+ *
519
+ * Atom lets you define a piece of state with a name, schema, and default value.
520
+ *
521
+ * By default, Alepha state is just a simple key-value store.
522
+ * Using atoms allows you to have type safety, validation, and default values for your state.
523
+ *
524
+ * You control how state is structured and validated.
525
+ *
526
+ * Features:
527
+ * - Set a schema for validation
528
+ * - Set a default value for initial state
529
+ * - Rules, like read-only, custom validation, etc.
530
+ * - Automatic getter access in services with {@link $use}
531
+ * - SSR support (server state automatically serialized and hydrated on client)
532
+ * - React integration (useAtom hook for automatic component re-renders)
533
+ * - Middleware
534
+ * - Persistence adapters (localStorage, Redis, database, file system, cookie, etc.)
535
+ * - State migrations (version upgrades when schema changes)
536
+ * - Documentation generation & devtools integration
537
+ *
538
+ * Common use cases:
539
+ * - user preferences
540
+ * - feature flags
541
+ * - configuration options
542
+ * - session data
543
+ *
544
+ * Atom must contain only serializable data.
545
+ * Avoid storing complex objects like class instances, functions, or DOM elements.
546
+ * If you need to store complex data, consider using identifiers or references instead.
547
+ */
548
+ declare const $atom: {
549
+ <T extends TObject<TProperties$2> | TArray$1, N extends string>(options: AtomOptions<T, N>): Atom<T, N>;
550
+ [KIND]: string;
551
+ };
552
+ type AtomOptions<T extends TAtomObject, N extends string> = {
553
+ name: N;
554
+ schema: T;
555
+ description?: string;
556
+ } & (T extends TOptionalAdd<T> ? {
557
+ default?: Static<T>;
558
+ } : {
559
+ default: Static<T>;
560
+ });
561
+ declare class Atom<T extends TAtomObject = TObject, N extends string = string> {
562
+ readonly options: AtomOptions<T, N>;
563
+ get schema(): T;
564
+ get key(): N;
565
+ constructor(options: AtomOptions<T, N>);
566
+ }
567
+ type TProperties$2 = any;
568
+ type TAtomObject = TObject<any> | TArray$1;
569
+ type AtomStatic<T extends TAtomObject> = T extends TOptionalAdd<T> ? Static<T> | undefined : Static<T>;
570
+ //#endregion
571
+ //#region ../../src/core/primitives/$inject.d.ts
572
+ /**
573
+ * Get the instance of the specified type from the context.
574
+ *
575
+ * ```ts
576
+ * class A { }
577
+ * class B {
578
+ * a = $inject(A);
579
+ * }
580
+ * ```
581
+ */
582
+ declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions<T>) => T;
583
+ declare class InjectPrimitive extends Primitive {}
584
+ interface InjectOptions<T extends object = any> {
585
+ /**
586
+ * - 'transient' → Always a new instance on every inject. Zero caching.
587
+ * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
588
+ * - 'scoped' → One instance per AsyncLocalStorage context.
589
+ * - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
590
+ * - You can also start a manual scope via alepha.context.run(() => { ... }).
591
+ * - When the scope ends, the scoped registry is discarded.
592
+ *
593
+ * @default "singleton"
594
+ */
595
+ lifetime?: "transient" | "singleton" | "scoped";
596
+ /**
597
+ * Constructor arguments to pass when creating a new instance.
598
+ */
599
+ args?: ConstructorParameters<InstantiableClass<T>>;
600
+ /**
601
+ * Parent that requested the instance.
602
+ *
603
+ * @internal
604
+ */
605
+ parent?: Service | null;
606
+ }
607
+ //#endregion
608
+ //#region ../../src/core/primitives/$module.d.ts
609
+ /**
610
+ * Wrap Services and Primitives into a Module.
611
+ *
612
+ * - A module is just a Service with some extra {@link Module}.
613
+ * - You must attach a `name` to it.
614
+ * - Name must follow the pattern: `project.module.submodule`. (e.g. `myapp.users.auth`).
615
+ *
616
+ * @example
617
+ * ```ts
618
+ * import { $module } from "alepha";
619
+ * import { MyService } from "./MyService.ts";
620
+ *
621
+ * // export MyService, so it can be used everywhere (optional)
622
+ * export * from "./MyService.ts";
623
+ *
624
+ * export default $module({
625
+ * name: "my.project.module",
626
+ * // MyService will have a module context "my.project.module"
627
+ * services: [MyService],
628
+ * });
629
+ * ```
630
+ *
631
+ * ### Why Modules?
632
+ *
633
+ * #### Logging
634
+ *
635
+ * By default, AlephaLogger will log the module name in the logs.
636
+ * This helps to identify where the logs are coming from.
637
+ *
638
+ * You can also set different log levels for different modules.
639
+ * It means you can set 'some.very.specific.module' to 'debug' and keep the rest of the application to 'info'.
640
+ *
641
+ * #### Modulith
642
+ *
643
+ * Force to structure your application in modules, even if it's a single deployable unit.
644
+ * It helps to keep a clean architecture and avoid monolithic applications.
645
+ *
646
+ * A strict mode flag will probably come to enforce module boundaries.
647
+ * -> Throwing errors when a service from another module is injected.
648
+ * But it's not implemented yet.
649
+ *
650
+ * ### When not to use Modules?
651
+ *
652
+ * Small applications does not need modules. It's better to keep it simple.
653
+ * Modules are more useful when the application grows and needs to be structured.
654
+ * If we speak with number of `$actions`, a module should be used when you have more than 30 actions in a single module.
655
+ * Meaning that if you have 100 actions, you should have at least 3 modules.
656
+ */
657
+ declare const $module: <T extends object = {}>(options: ModulePrimitiveOptions) => Service<Module>;
658
+ interface ModulePrimitiveOptions {
659
+ /**
660
+ * Name of the module.
661
+ *
662
+ * It should be in the format of `project.module.submodule`.
663
+ */
664
+ name: string;
665
+ /**
666
+ * List all services related to this module.
667
+ *
668
+ * If you don't declare 'register' function, all services will be registered automatically.
669
+ * If you declare 'register' function, you must handle the registration of ALL services manually.
670
+ */
671
+ services?: Array<Service>;
672
+ /**
673
+ * List of $primitives to register in the module.
674
+ */
675
+ primitives?: Array<PrimitiveFactoryLike>;
676
+ /**
677
+ * By default, module will register ALL services.
678
+ * You can override this behavior by providing a register function.
679
+ * It's useful when you want to register services conditionally or in a specific order.
680
+ *
681
+ * Again, if you declare 'register', you must handle the registration of ALL services manually.
682
+ */
683
+ register?: (alepha: Alepha) => void;
684
+ }
685
+ /**
686
+ * Base class for all modules.
687
+ */
688
+ declare abstract class Module {
689
+ abstract readonly options: ModulePrimitiveOptions;
690
+ abstract register(alepha: Alepha): void;
691
+ static NAME_REGEX: RegExp;
692
+ /**
693
+ * Check if a Service is a Module.
694
+ */
695
+ static is(ctor: Service): boolean;
696
+ /**
697
+ * Get the Module of a Service.
698
+ *
699
+ * Returns undefined if the Service is not part of a Module.
700
+ */
701
+ static of(ctor: Service): Service<Module> | undefined;
702
+ }
703
+ /**
704
+ * Helper type to add Module metadata to a Service.
705
+ */
706
+ type WithModule<T extends object = any> = T & {
707
+ [MODULE]?: Service;
708
+ };
709
+ //#endregion
710
+ //#region ../../src/core/providers/AlsProvider.d.ts
711
+ type AsyncLocalStorageData = any;
712
+ declare class AlsProvider {
713
+ static create: () => AsyncLocalStorage<AsyncLocalStorageData> | undefined;
714
+ als?: AsyncLocalStorage<AsyncLocalStorageData>;
715
+ constructor();
716
+ createContextId(): string;
717
+ run<R>(callback: () => R, data?: Record<string, any>): R;
718
+ exists(): boolean;
719
+ get<T>(key: string): T | undefined;
720
+ set<T>(key: string, value: T): void;
721
+ }
722
+ //#endregion
723
+ //#region ../../src/core/providers/Json.d.ts
724
+ /**
725
+ * Mimics the JSON global object with stringify and parse methods.
726
+ *
727
+ * Used across the codebase via dependency injection.
728
+ */
729
+ declare class Json {
730
+ stringify(value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): string;
731
+ parse(text: string, reviver?: (this: any, key: string, value: any) => any): any;
732
+ }
733
+ //#endregion
734
+ //#region ../../src/core/providers/SchemaCodec.d.ts
679
735
  declare abstract class SchemaCodec {
680
736
  /**
681
737
  * Encode the value to a string format.
@@ -691,7 +747,7 @@ declare abstract class SchemaCodec {
691
747
  abstract decode<T>(schema: TSchema, value: unknown): T;
692
748
  }
693
749
  //#endregion
694
- //#region src/core/providers/JsonSchemaCodec.d.ts
750
+ //#region ../../src/core/providers/JsonSchemaCodec.d.ts
695
751
  declare class JsonSchemaCodec extends SchemaCodec {
696
752
  protected readonly json: Json;
697
753
  protected readonly encoder: TextEncoder;
@@ -701,7 +757,7 @@ declare class JsonSchemaCodec extends SchemaCodec {
701
757
  decode<T>(schema: TSchema$1, value: unknown): T;
702
758
  }
703
759
  //#endregion
704
- //#region src/core/providers/SchemaValidator.d.ts
760
+ //#region ../../src/core/providers/SchemaValidator.d.ts
705
761
  declare class SchemaValidator {
706
762
  protected cache: Map<TSchema$1, Validator<TypeBox.TProperties, TSchema$1, unknown, unknown>>;
707
763
  /**
@@ -729,7 +785,7 @@ interface ValidateOptions {
729
785
  deleteUndefined?: boolean;
730
786
  }
731
787
  //#endregion
732
- //#region src/core/providers/CodecManager.d.ts
788
+ //#region ../../src/core/providers/CodecManager.d.ts
733
789
  type Encoding = "object" | "string" | "binary";
734
790
  interface EncodeOptions<T extends Encoding = Encoding> {
735
791
  /**
@@ -805,7 +861,7 @@ declare class CodecManager {
805
861
  validate<T extends TSchema$1>(schema: T, value: unknown, options?: ValidateOptions): Static<T>;
806
862
  }
807
863
  //#endregion
808
- //#region src/core/providers/EventManager.d.ts
864
+ //#region ../../src/core/providers/EventManager.d.ts
809
865
  declare class EventManager {
810
866
  protected logFn?: () => LoggerInterface | undefined;
811
867
  /**
@@ -844,63 +900,7 @@ declare class EventManager {
844
900
  }): Promise<void>;
845
901
  }
846
902
  //#endregion
847
- //#region src/core/primitives/$atom.d.ts
848
- /**
849
- * Define an atom for state management.
850
- *
851
- * Atom lets you define a piece of state with a name, schema, and default value.
852
- *
853
- * By default, Alepha state is just a simple key-value store.
854
- * Using atoms allows you to have type safety, validation, and default values for your state.
855
- *
856
- * You control how state is structured and validated.
857
- *
858
- * Features:
859
- * - Set a schema for validation
860
- * - Set a default value for initial state
861
- * - Rules, like read-only, custom validation, etc.
862
- * - Automatic getter access in services with {@link $use}
863
- * - SSR support (server state automatically serialized and hydrated on client)
864
- * - React integration (useAtom hook for automatic component re-renders)
865
- * - Middleware
866
- * - Persistence adapters (localStorage, Redis, database, file system, cookie, etc.)
867
- * - State migrations (version upgrades when schema changes)
868
- * - Documentation generation & devtools integration
869
- *
870
- * Common use cases:
871
- * - user preferences
872
- * - feature flags
873
- * - configuration options
874
- * - session data
875
- *
876
- * Atom must contain only serializable data.
877
- * Avoid storing complex objects like class instances, functions, or DOM elements.
878
- * If you need to store complex data, consider using identifiers or references instead.
879
- */
880
- declare const $atom: {
881
- <T extends TObject<TProperties$2> | TArray$1, N extends string>(options: AtomOptions<T, N>): Atom<T, N>;
882
- [KIND]: string;
883
- };
884
- type AtomOptions<T extends TAtomObject, N extends string> = {
885
- name: N;
886
- schema: T;
887
- description?: string;
888
- } & (T extends TOptionalAdd<T> ? {
889
- default?: Static<T>;
890
- } : {
891
- default: Static<T>;
892
- });
893
- declare class Atom<T extends TAtomObject = TObject, N extends string = string> {
894
- readonly options: AtomOptions<T, N>;
895
- get schema(): T;
896
- get key(): N;
897
- constructor(options: AtomOptions<T, N>);
898
- }
899
- type TProperties$2 = any;
900
- type TAtomObject = TObject<any> | TArray$1;
901
- type AtomStatic<T extends TAtomObject> = T extends TOptionalAdd<T> ? Static<T> | undefined : Static<T>;
902
- //#endregion
903
- //#region src/core/providers/StateManager.d.ts
903
+ //#region ../../src/core/providers/StateManager.d.ts
904
904
  interface AtomWithValue {
905
905
  atom: Atom;
906
906
  value: unknown;
@@ -952,7 +952,7 @@ declare class StateManager<State$1 extends object = State> {
952
952
  }
953
953
  type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never };
954
954
  //#endregion
955
- //#region src/core/Alepha.d.ts
955
+ //#region ../../src/core/Alepha.d.ts
956
956
  /**
957
957
  * Core container of the Alepha framework.
958
958
  *
@@ -1176,6 +1176,8 @@ declare class Alepha {
1176
1176
  */
1177
1177
  get env(): Readonly<Env>;
1178
1178
  constructor(init?: Partial<State>);
1179
+ set<T extends TAtomObject>(target: Atom<T>, value: AtomStatic<T>): this;
1180
+ set<Key extends keyof State>(target: Key, value: State[Key] | undefined): this;
1179
1181
  /**
1180
1182
  * True when start() is called.
1181
1183
  *
@@ -1471,7 +1473,7 @@ interface Hooks {
1471
1473
  };
1472
1474
  }
1473
1475
  //#endregion
1474
- //#region src/core/interfaces/Run.d.ts
1476
+ //#region ../../src/core/interfaces/Run.d.ts
1475
1477
  interface RunOptions {
1476
1478
  /**
1477
1479
  * Environment variables to be used by the application.
@@ -1498,7 +1500,7 @@ interface RunOptions {
1498
1500
  cluster?: boolean;
1499
1501
  }
1500
1502
  //#endregion
1501
- //#region src/core/constants/OPTIONS.d.ts
1503
+ //#region ../../src/core/constants/OPTIONS.d.ts
1502
1504
  /**
1503
1505
  * Used for primitives options.
1504
1506
  *
@@ -1506,31 +1508,31 @@ interface RunOptions {
1506
1508
  */
1507
1509
  declare const OPTIONS: unique symbol;
1508
1510
  //#endregion
1509
- //#region src/core/errors/AppNotStartedError.d.ts
1511
+ //#region ../../src/core/errors/AppNotStartedError.d.ts
1510
1512
  declare class AppNotStartedError extends AlephaError {
1511
1513
  readonly name = "AppNotStartedError";
1512
1514
  constructor();
1513
1515
  }
1514
1516
  //#endregion
1515
- //#region src/core/errors/CircularDependencyError.d.ts
1517
+ //#region ../../src/core/errors/CircularDependencyError.d.ts
1516
1518
  declare class CircularDependencyError extends AlephaError {
1517
1519
  readonly name = "CircularDependencyError";
1518
1520
  constructor(provider: string, parents?: string[]);
1519
1521
  }
1520
1522
  //#endregion
1521
- //#region src/core/errors/ContainerLockedError.d.ts
1523
+ //#region ../../src/core/errors/ContainerLockedError.d.ts
1522
1524
  declare class ContainerLockedError extends AlephaError {
1523
1525
  readonly name = "ContainerLockedError";
1524
1526
  constructor(message?: string);
1525
1527
  }
1526
1528
  //#endregion
1527
- //#region src/core/errors/TooLateSubstitutionError.d.ts
1529
+ //#region ../../src/core/errors/TooLateSubstitutionError.d.ts
1528
1530
  declare class TooLateSubstitutionError extends AlephaError {
1529
1531
  readonly name = "TooLateSubstitutionError";
1530
1532
  constructor(original: string, substitution: string);
1531
1533
  }
1532
1534
  //#endregion
1533
- //#region src/core/schemas/pageSchema.d.ts
1535
+ //#region ../../src/core/schemas/pageSchema.d.ts
1534
1536
  declare const pageMetadataSchema: TObject<{
1535
1537
  number: TInteger;
1536
1538
  size: TInteger;
@@ -1623,7 +1625,7 @@ declare module "alepha" {
1623
1625
  }
1624
1626
  }
1625
1627
  //#endregion
1626
- //#region src/core/helpers/createPagination.d.ts
1628
+ //#region ../../src/core/helpers/createPagination.d.ts
1627
1629
  /**
1628
1630
  * Create a pagination object from an array of entities.
1629
1631
  *
@@ -1673,7 +1675,7 @@ declare function createPagination<T>(entities: T[], limit?: number, offset?: num
1673
1675
  direction: "asc" | "desc";
1674
1676
  }>): Page<T>;
1675
1677
  //#endregion
1676
- //#region src/core/interfaces/Pagination.d.ts
1678
+ //#region ../../src/core/interfaces/Pagination.d.ts
1677
1679
  /**
1678
1680
  * Generic pagination request parameters.
1679
1681
  *
@@ -1728,7 +1730,7 @@ interface SortField {
1728
1730
  direction: SortDirection;
1729
1731
  }
1730
1732
  //#endregion
1731
- //#region src/core/primitives/$context.d.ts
1733
+ //#region ../../src/core/primitives/$context.d.ts
1732
1734
  /**
1733
1735
  * Get Alepha instance and current service from the current context.
1734
1736
  *
@@ -1773,7 +1775,7 @@ interface ContextPrimitive {
1773
1775
  module?: Service;
1774
1776
  }
1775
1777
  //#endregion
1776
- //#region src/core/primitives/$env.d.ts
1778
+ //#region ../../src/core/primitives/$env.d.ts
1777
1779
  /**
1778
1780
  * Get typed values from environment variables.
1779
1781
  *
@@ -1802,7 +1804,7 @@ interface ContextPrimitive {
1802
1804
  */
1803
1805
  declare const $env: <T extends TObject$1>(type: T) => Static$1<T>;
1804
1806
  //#endregion
1805
- //#region src/core/primitives/$hook.d.ts
1807
+ //#region ../../src/core/primitives/$hook.d.ts
1806
1808
  /**
1807
1809
  * Registers a new hook.
1808
1810
  *
@@ -1873,7 +1875,7 @@ declare class HookPrimitive<T extends keyof Hooks> extends Primitive<HookOptions
1873
1875
  protected onInit(): void;
1874
1876
  }
1875
1877
  //#endregion
1876
- //#region src/core/primitives/$use.d.ts
1878
+ //#region ../../src/core/primitives/$use.d.ts
1877
1879
  /**
1878
1880
  * Subscribes to an atom's state and returns its current value for use in components.
1879
1881
  *
@@ -1898,7 +1900,7 @@ declare class HookPrimitive<T extends keyof Hooks> extends Primitive<HookOptions
1898
1900
  */
1899
1901
  declare const $use: <T extends TObject, N extends string>(atom: Atom<T, N>) => Readonly<Static<T>>;
1900
1902
  //#endregion
1901
- //#region src/core/schemas/pageQuerySchema.d.ts
1903
+ //#region ../../src/core/schemas/pageQuerySchema.d.ts
1902
1904
  declare const pageQuerySchema: TObject<{
1903
1905
  page: TOptional<TInteger>;
1904
1906
  size: TOptional<TInteger>;
@@ -1906,7 +1908,7 @@ declare const pageQuerySchema: TObject<{
1906
1908
  }>;
1907
1909
  type PageQuery = Static<typeof pageQuerySchema>;
1908
1910
  //#endregion
1909
- //#region src/core/index.d.ts
1911
+ //#region ../../src/core/index.d.ts
1910
1912
  /**
1911
1913
  * Run Alepha application, trigger start lifecycle.
1912
1914
  *