alepha 0.15.0 → 0.15.1

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 (222) hide show
  1. package/README.md +43 -98
  2. package/dist/api/audits/index.d.ts +240 -240
  3. package/dist/api/audits/index.d.ts.map +1 -1
  4. package/dist/api/audits/index.js +2 -2
  5. package/dist/api/audits/index.js.map +1 -1
  6. package/dist/api/files/index.d.ts +185 -185
  7. package/dist/api/files/index.d.ts.map +1 -1
  8. package/dist/api/files/index.js +2 -2
  9. package/dist/api/files/index.js.map +1 -1
  10. package/dist/api/jobs/index.d.ts +245 -245
  11. package/dist/api/jobs/index.d.ts.map +1 -1
  12. package/dist/api/notifications/index.browser.js +4 -4
  13. package/dist/api/notifications/index.browser.js.map +1 -1
  14. package/dist/api/notifications/index.d.ts +74 -74
  15. package/dist/api/notifications/index.d.ts.map +1 -1
  16. package/dist/api/notifications/index.js +4 -4
  17. package/dist/api/notifications/index.js.map +1 -1
  18. package/dist/api/parameters/index.d.ts +221 -221
  19. package/dist/api/parameters/index.d.ts.map +1 -1
  20. package/dist/api/users/index.d.ts +1632 -1631
  21. package/dist/api/users/index.d.ts.map +1 -1
  22. package/dist/api/users/index.js +26 -34
  23. package/dist/api/users/index.js.map +1 -1
  24. package/dist/api/verifications/index.d.ts +132 -132
  25. package/dist/api/verifications/index.d.ts.map +1 -1
  26. package/dist/batch/index.d.ts +122 -122
  27. package/dist/batch/index.d.ts.map +1 -1
  28. package/dist/bucket/index.d.ts +163 -163
  29. package/dist/bucket/index.d.ts.map +1 -1
  30. package/dist/cache/core/index.d.ts +46 -46
  31. package/dist/cache/core/index.d.ts.map +1 -1
  32. package/dist/cache/redis/index.d.ts.map +1 -1
  33. package/dist/cache/redis/index.js +2 -2
  34. package/dist/cache/redis/index.js.map +1 -1
  35. package/dist/cli/index.d.ts +5933 -201
  36. package/dist/cli/index.d.ts.map +1 -1
  37. package/dist/cli/index.js +609 -169
  38. package/dist/cli/index.js.map +1 -1
  39. package/dist/command/index.d.ts +296 -296
  40. package/dist/command/index.d.ts.map +1 -1
  41. package/dist/command/index.js +19 -19
  42. package/dist/command/index.js.map +1 -1
  43. package/dist/core/index.browser.js +268 -79
  44. package/dist/core/index.browser.js.map +1 -1
  45. package/dist/core/index.d.ts +768 -694
  46. package/dist/core/index.d.ts.map +1 -1
  47. package/dist/core/index.js +268 -79
  48. package/dist/core/index.js.map +1 -1
  49. package/dist/core/index.native.js +268 -79
  50. package/dist/core/index.native.js.map +1 -1
  51. package/dist/datetime/index.d.ts +44 -44
  52. package/dist/datetime/index.d.ts.map +1 -1
  53. package/dist/email/index.d.ts +25 -25
  54. package/dist/email/index.d.ts.map +1 -1
  55. package/dist/fake/index.d.ts +5409 -5409
  56. package/dist/fake/index.d.ts.map +1 -1
  57. package/dist/fake/index.js +22 -22
  58. package/dist/fake/index.js.map +1 -1
  59. package/dist/file/index.d.ts +435 -435
  60. package/dist/file/index.d.ts.map +1 -1
  61. package/dist/lock/core/index.d.ts +208 -208
  62. package/dist/lock/core/index.d.ts.map +1 -1
  63. package/dist/lock/redis/index.d.ts.map +1 -1
  64. package/dist/logger/index.d.ts +24 -24
  65. package/dist/logger/index.d.ts.map +1 -1
  66. package/dist/logger/index.js +1 -5
  67. package/dist/logger/index.js.map +1 -1
  68. package/dist/mcp/index.d.ts +216 -198
  69. package/dist/mcp/index.d.ts.map +1 -1
  70. package/dist/mcp/index.js +28 -4
  71. package/dist/mcp/index.js.map +1 -1
  72. package/dist/orm/index.browser.js +9 -9
  73. package/dist/orm/index.browser.js.map +1 -1
  74. package/dist/orm/index.bun.js +83 -76
  75. package/dist/orm/index.bun.js.map +1 -1
  76. package/dist/orm/index.d.ts +961 -960
  77. package/dist/orm/index.d.ts.map +1 -1
  78. package/dist/orm/index.js +88 -81
  79. package/dist/orm/index.js.map +1 -1
  80. package/dist/queue/core/index.d.ts +244 -244
  81. package/dist/queue/core/index.d.ts.map +1 -1
  82. package/dist/queue/redis/index.d.ts.map +1 -1
  83. package/dist/redis/index.d.ts +105 -105
  84. package/dist/redis/index.d.ts.map +1 -1
  85. package/dist/retry/index.d.ts +69 -69
  86. package/dist/retry/index.d.ts.map +1 -1
  87. package/dist/router/index.d.ts +6 -6
  88. package/dist/router/index.d.ts.map +1 -1
  89. package/dist/scheduler/index.d.ts +108 -26
  90. package/dist/scheduler/index.d.ts.map +1 -1
  91. package/dist/scheduler/index.js +393 -1
  92. package/dist/scheduler/index.js.map +1 -1
  93. package/dist/security/index.d.ts +532 -209
  94. package/dist/security/index.d.ts.map +1 -1
  95. package/dist/security/index.js +1422 -11
  96. package/dist/security/index.js.map +1 -1
  97. package/dist/server/auth/index.d.ts +1296 -271
  98. package/dist/server/auth/index.d.ts.map +1 -1
  99. package/dist/server/auth/index.js +1249 -18
  100. package/dist/server/auth/index.js.map +1 -1
  101. package/dist/server/cache/index.d.ts +56 -56
  102. package/dist/server/cache/index.d.ts.map +1 -1
  103. package/dist/server/compress/index.d.ts +3 -3
  104. package/dist/server/compress/index.d.ts.map +1 -1
  105. package/dist/server/cookies/index.d.ts +6 -6
  106. package/dist/server/cookies/index.d.ts.map +1 -1
  107. package/dist/server/core/index.d.ts +196 -186
  108. package/dist/server/core/index.d.ts.map +1 -1
  109. package/dist/server/core/index.js +43 -27
  110. package/dist/server/core/index.js.map +1 -1
  111. package/dist/server/cors/index.d.ts +11 -11
  112. package/dist/server/cors/index.d.ts.map +1 -1
  113. package/dist/server/health/index.d.ts.map +1 -1
  114. package/dist/server/helmet/index.d.ts +2 -2
  115. package/dist/server/helmet/index.d.ts.map +1 -1
  116. package/dist/server/links/index.browser.js +9 -1
  117. package/dist/server/links/index.browser.js.map +1 -1
  118. package/dist/server/links/index.d.ts +83 -83
  119. package/dist/server/links/index.d.ts.map +1 -1
  120. package/dist/server/links/index.js +13 -5
  121. package/dist/server/links/index.js.map +1 -1
  122. package/dist/server/metrics/index.d.ts +514 -1
  123. package/dist/server/metrics/index.d.ts.map +1 -1
  124. package/dist/server/metrics/index.js +4462 -4
  125. package/dist/server/metrics/index.js.map +1 -1
  126. package/dist/server/multipart/index.d.ts +6 -6
  127. package/dist/server/multipart/index.d.ts.map +1 -1
  128. package/dist/server/proxy/index.d.ts +102 -102
  129. package/dist/server/proxy/index.d.ts.map +1 -1
  130. package/dist/server/rate-limit/index.d.ts +16 -16
  131. package/dist/server/rate-limit/index.d.ts.map +1 -1
  132. package/dist/server/static/index.d.ts +44 -44
  133. package/dist/server/static/index.d.ts.map +1 -1
  134. package/dist/server/swagger/index.d.ts +47 -47
  135. package/dist/server/swagger/index.d.ts.map +1 -1
  136. package/dist/sms/index.d.ts +11 -11
  137. package/dist/sms/index.d.ts.map +1 -1
  138. package/dist/sms/index.js +3 -3
  139. package/dist/sms/index.js.map +1 -1
  140. package/dist/thread/index.d.ts +71 -71
  141. package/dist/thread/index.d.ts.map +1 -1
  142. package/dist/thread/index.js +2 -2
  143. package/dist/thread/index.js.map +1 -1
  144. package/dist/topic/core/index.d.ts +318 -318
  145. package/dist/topic/core/index.d.ts.map +1 -1
  146. package/dist/topic/redis/index.d.ts +6 -6
  147. package/dist/topic/redis/index.d.ts.map +1 -1
  148. package/dist/vite/index.d.ts +2324 -1719
  149. package/dist/vite/index.d.ts.map +1 -1
  150. package/dist/vite/index.js +123 -475
  151. package/dist/vite/index.js.map +1 -1
  152. package/dist/websocket/index.browser.js +3 -3
  153. package/dist/websocket/index.browser.js.map +1 -1
  154. package/dist/websocket/index.d.ts +275 -275
  155. package/dist/websocket/index.d.ts.map +1 -1
  156. package/dist/websocket/index.js +3 -3
  157. package/dist/websocket/index.js.map +1 -1
  158. package/package.json +9 -9
  159. package/src/api/users/services/SessionService.ts +0 -10
  160. package/src/cli/apps/AlephaCli.ts +2 -2
  161. package/src/cli/apps/AlephaPackageBuilderCli.ts +9 -1
  162. package/src/cli/assets/apiHelloControllerTs.ts +2 -1
  163. package/src/cli/assets/biomeJson.ts +2 -1
  164. package/src/cli/assets/claudeMd.ts +9 -4
  165. package/src/cli/assets/dummySpecTs.ts +2 -1
  166. package/src/cli/assets/editorconfig.ts +2 -1
  167. package/src/cli/assets/mainBrowserTs.ts +2 -1
  168. package/src/cli/assets/mainCss.ts +24 -0
  169. package/src/cli/assets/tsconfigJson.ts +2 -1
  170. package/src/cli/assets/webAppRouterTs.ts +2 -1
  171. package/src/cli/assets/webHelloComponentTsx.ts +6 -2
  172. package/src/cli/atoms/appEntryOptions.ts +13 -0
  173. package/src/cli/atoms/buildOptions.ts +1 -1
  174. package/src/cli/atoms/changelogOptions.ts +1 -1
  175. package/src/cli/commands/build.ts +63 -47
  176. package/src/cli/commands/dev.ts +16 -33
  177. package/src/cli/commands/gen/env.ts +1 -1
  178. package/src/cli/commands/init.ts +17 -8
  179. package/src/cli/commands/lint.ts +1 -1
  180. package/src/cli/defineConfig.ts +9 -0
  181. package/src/cli/index.ts +2 -1
  182. package/src/cli/providers/AppEntryProvider.ts +131 -0
  183. package/src/cli/providers/ViteBuildProvider.ts +82 -0
  184. package/src/cli/providers/ViteDevServerProvider.ts +350 -0
  185. package/src/cli/providers/ViteTemplateProvider.ts +27 -0
  186. package/src/cli/services/AlephaCliUtils.ts +33 -2
  187. package/src/cli/services/PackageManagerUtils.ts +13 -6
  188. package/src/cli/services/ProjectScaffolder.ts +72 -49
  189. package/src/core/Alepha.ts +2 -8
  190. package/src/core/primitives/$module.ts +12 -0
  191. package/src/core/providers/KeylessJsonSchemaCodec.spec.ts +257 -0
  192. package/src/core/providers/KeylessJsonSchemaCodec.ts +396 -14
  193. package/src/core/providers/SchemaValidator.spec.ts +236 -0
  194. package/src/logger/providers/PrettyFormatterProvider.ts +0 -9
  195. package/src/mcp/errors/McpError.ts +30 -0
  196. package/src/mcp/index.ts +3 -0
  197. package/src/mcp/transports/SseMcpTransport.ts +16 -6
  198. package/src/orm/providers/DrizzleKitProvider.ts +3 -5
  199. package/src/orm/services/Repository.ts +11 -0
  200. package/src/server/core/index.ts +1 -1
  201. package/src/server/core/providers/BunHttpServerProvider.ts +1 -1
  202. package/src/server/core/providers/NodeHttpServerProvider.spec.ts +125 -0
  203. package/src/server/core/providers/NodeHttpServerProvider.ts +71 -22
  204. package/src/server/core/providers/ServerLoggerProvider.ts +2 -2
  205. package/src/server/core/providers/ServerProvider.ts +9 -12
  206. package/src/server/links/atoms/apiLinksAtom.ts +7 -0
  207. package/src/server/links/index.browser.ts +2 -0
  208. package/src/server/links/index.ts +2 -0
  209. package/src/vite/index.ts +3 -2
  210. package/src/vite/tasks/buildClient.ts +0 -1
  211. package/src/vite/tasks/buildServer.ts +68 -21
  212. package/src/vite/tasks/copyAssets.ts +5 -4
  213. package/src/vite/tasks/generateSitemap.ts +64 -23
  214. package/src/vite/tasks/index.ts +0 -2
  215. package/src/vite/tasks/prerenderPages.ts +49 -24
  216. package/src/cli/assets/indexHtml.ts +0 -15
  217. package/src/cli/commands/format.ts +0 -23
  218. package/src/vite/helpers/boot.ts +0 -117
  219. package/src/vite/plugins/viteAlephaDev.ts +0 -177
  220. package/src/vite/tasks/devServer.ts +0 -71
  221. package/src/vite/tasks/runAlepha.ts +0 -270
  222. /package/dist/orm/{chunk-DtkW-qnP.js → chunk-DH6iiROE.js} +0 -0
@@ -45,19 +45,19 @@ type AbstractClass<T extends object = any> = abstract new (...args: any[]) => T;
45
45
  */
46
46
  interface ServiceSubstitution<T extends object = any> {
47
47
  /**
48
- * Every time someone asks for this class, it will be provided with the 'use' class.
49
- */
48
+ * Every time someone asks for this class, it will be provided with the 'use' class.
49
+ */
50
50
  provide: Service<T>;
51
51
  /**
52
- * Service to use instead of the 'provide' service.
53
- *
54
- * Syntax is inspired by Angular's DI system.
55
- */
52
+ * Service to use instead of the 'provide' service.
53
+ *
54
+ * Syntax is inspired by Angular's DI system.
55
+ */
56
56
  use: Service<T>;
57
57
  /**
58
- * If true, if the service already exists -> just ignore the substitution and do not throw an error.
59
- * Mostly used for plugins to enforce a substitution without throwing an error.
60
- */
58
+ * If true, if the service already exists -> just ignore the substitution and do not throw an error.
59
+ * Mostly used for plugins to enforce a substitution without throwing an error.
60
+ */
61
61
  optional?: boolean;
62
62
  }
63
63
  /**
@@ -90,8 +90,8 @@ declare abstract class Primitive<T extends object = {}> {
90
90
  readonly config: PrimitiveConfig;
91
91
  constructor(args: PrimitiveArgs<T>);
92
92
  /**
93
- * Called automatically by Alepha after the primitive is created.
94
- */
93
+ * Called automatically by Alepha after the primitive is created.
94
+ */
95
95
  protected onInit(): void;
96
96
  }
97
97
  type PrimitiveFactory<TPrimitive extends Primitive = Primitive> = {
@@ -155,55 +155,55 @@ interface TypeBoxErrorParams {
155
155
  //#region ../../src/core/helpers/FileLike.d.ts
156
156
  interface FileLike {
157
157
  /**
158
- * Filename.
159
- * @default "file"
160
- */
158
+ * Filename.
159
+ * @default "file"
160
+ */
161
161
  name: string;
162
162
  /**
163
- * Mandatory MIME type of the file.
164
- * @default "application/octet-stream"
165
- */
163
+ * Mandatory MIME type of the file.
164
+ * @default "application/octet-stream"
165
+ */
166
166
  type: string;
167
167
  /**
168
- * Size of the file in bytes.
169
- *
170
- * Always 0 for streams, as the size is not known until the stream is fully read.
171
- *
172
- * @default 0
173
- */
168
+ * Size of the file in bytes.
169
+ *
170
+ * Always 0 for streams, as the size is not known until the stream is fully read.
171
+ *
172
+ * @default 0
173
+ */
174
174
  size: number;
175
175
  /**
176
- * Last modified timestamp in milliseconds since epoch.
177
- *
178
- * Always the current timestamp for streams, as the last modified time is not known.
179
- * We use this field to ensure compatibility with File API.
180
- *
181
- * @default Date.now()
182
- */
176
+ * Last modified timestamp in milliseconds since epoch.
177
+ *
178
+ * Always the current timestamp for streams, as the last modified time is not known.
179
+ * We use this field to ensure compatibility with File API.
180
+ *
181
+ * @default Date.now()
182
+ */
183
183
  lastModified: number;
184
184
  /**
185
- * Returns a ReadableStream or Node.js Readable stream of the file content.
186
- *
187
- * For streams, this is the original stream.
188
- */
185
+ * Returns a ReadableStream or Node.js Readable stream of the file content.
186
+ *
187
+ * For streams, this is the original stream.
188
+ */
189
189
  stream(): StreamLike;
190
190
  /**
191
- * Returns the file content as an ArrayBuffer.
192
- *
193
- * For streams, this reads the entire stream into memory.
194
- */
191
+ * Returns the file content as an ArrayBuffer.
192
+ *
193
+ * For streams, this reads the entire stream into memory.
194
+ */
195
195
  arrayBuffer(): Promise<ArrayBuffer>;
196
196
  /**
197
- * Returns the file content as a string.
198
- *
199
- * For streams, this reads the entire stream into memory and converts it to a string.
200
- */
197
+ * Returns the file content as a string.
198
+ *
199
+ * For streams, this reads the entire stream into memory and converts it to a string.
200
+ */
201
201
  text(): Promise<string>;
202
202
  /**
203
- * Optional file path, if the file is stored on disk.
204
- *
205
- * This is not from the File API, but rather a custom field to indicate where the file is stored.
206
- */
203
+ * Optional file path, if the file is stored on disk.
204
+ *
205
+ * This is not from the File API, but rather a custom field to indicate where the file is stored.
206
+ */
207
207
  filepath?: string;
208
208
  }
209
209
  /**
@@ -259,47 +259,47 @@ declare class TypeProvider {
259
259
  static setLocale(locale: string): void;
260
260
  static isValidBigInt(value: string | number): boolean;
261
261
  /**
262
- * Default maximum length for strings.
263
- *
264
- * It can be set to a larger value:
265
- * ```ts
266
- * TypeProvider.DEFAULT_STRING_MAX_LENGTH = 1000000;
267
- * TypeProvider.DEFAULT_STRING_MAX_LENGTH = undefined; // no limit (not recommended)
268
- * ```
269
- */
262
+ * Default maximum length for strings.
263
+ *
264
+ * It can be set to a larger value:
265
+ * ```ts
266
+ * TypeProvider.DEFAULT_STRING_MAX_LENGTH = 1000000;
267
+ * TypeProvider.DEFAULT_STRING_MAX_LENGTH = undefined; // no limit (not recommended)
268
+ * ```
269
+ */
270
270
  static DEFAULT_STRING_MAX_LENGTH: number | undefined;
271
271
  /**
272
- * Maximum length for short strings, such as names or titles.
273
- */
272
+ * Maximum length for short strings, such as names or titles.
273
+ */
274
274
  static DEFAULT_SHORT_STRING_MAX_LENGTH: number | undefined;
275
275
  /**
276
- * Maximum length for long strings, such as descriptions or comments.
277
- * It can be overridden in the string options.
278
- *
279
- * It can be set to a larger value:
280
- * ```ts
281
- * TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH = 2048;
282
- * ```
283
- */
276
+ * Maximum length for long strings, such as descriptions or comments.
277
+ * It can be overridden in the string options.
278
+ *
279
+ * It can be set to a larger value:
280
+ * ```ts
281
+ * TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH = 2048;
282
+ * ```
283
+ */
284
284
  static DEFAULT_LONG_STRING_MAX_LENGTH: number | undefined;
285
285
  /**
286
- * Maximum length for rich strings, such as HTML or Markdown.
287
- * This is a large value to accommodate rich text content.
288
- * > It's also the maximum length of PG's TEXT type.
289
- *
290
- * It can be overridden in the string options.
291
- *
292
- * It can be set to a larger value:
293
- * ```ts
294
- * TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH = 1000000;
295
- * ```
296
- */
286
+ * Maximum length for rich strings, such as HTML or Markdown.
287
+ * This is a large value to accommodate rich text content.
288
+ * > It's also the maximum length of PG's TEXT type.
289
+ *
290
+ * It can be overridden in the string options.
291
+ *
292
+ * It can be set to a larger value:
293
+ * ```ts
294
+ * TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH = 1000000;
295
+ * ```
296
+ */
297
297
  static DEFAULT_RICH_STRING_MAX_LENGTH: number | undefined;
298
298
  /**
299
- * Maximum number of items in an array.
300
- * This is a default value to prevent excessive memory usage.
301
- * It can be overridden in the array options.
302
- */
299
+ * Maximum number of items in an array.
300
+ * This is a default value to prevent excessive memory usage.
301
+ * It can be overridden in the array options.
302
+ */
303
303
  static DEFAULT_ARRAY_MAX_ITEMS: number;
304
304
  raw: typeof Type;
305
305
  any: typeof Type.Any;
@@ -312,16 +312,16 @@ declare class TypeProvider {
312
312
  const: typeof Type.Literal;
313
313
  options: typeof Type.Options;
314
314
  /**
315
- * Type guards to check the type of schema.
316
- * This is not a runtime type check, but a compile-time type guard.
317
- *
318
- * @example
319
- * ```ts
320
- * if (t.schema.isString(schema)) {
321
- * // schema is TString
322
- * }
323
- * ```
324
- */
315
+ * Type guards to check the type of schema.
316
+ * This is not a runtime type check, but a compile-time type guard.
317
+ *
318
+ * @example
319
+ * ```ts
320
+ * if (t.schema.isString(schema)) {
321
+ * // schema is TString
322
+ * }
323
+ * ```
324
+ */
325
325
  readonly schema: TypeGuard;
326
326
  extend<T extends TSchema$1[], U extends TProperties$1>(schema: [...T], properties: U, options?: TSchemaOptions): TInterface<T, U>;
327
327
  extend<T extends TObject$1, U extends TProperties$1>(schema: T, properties: U, options?: TSchemaOptions): TInterface<[T], U>;
@@ -329,76 +329,76 @@ declare class TypeProvider {
329
329
  omit<T extends TObject$1, Indexer extends PropertyKey[]>(schema: T, keys: [...Indexer], options?: TObjectOptions$1): TOmit<T, TKeysToIndexer$1<Indexer>>;
330
330
  partial<T extends TSchema$1>(schema: T, options?: TSchemaOptions): TPartial<T>;
331
331
  /**
332
- * Create a schema for an object.
333
- * By default, additional properties are not allowed.
334
- *
335
- * @example
336
- * ```ts
337
- * const userSchema = t.object({
338
- * id: t.integer(),
339
- * name: t.string(),
340
- * });
341
- * ```
342
- */
332
+ * Create a schema for an object.
333
+ * By default, additional properties are not allowed.
334
+ *
335
+ * @example
336
+ * ```ts
337
+ * const userSchema = t.object({
338
+ * id: t.integer(),
339
+ * name: t.string(),
340
+ * });
341
+ * ```
342
+ */
343
343
  object<T extends TProperties$1>(properties: T, options?: TObjectOptions$1): TObject$1<T>;
344
344
  /**
345
- * Create a schema for an array.
346
- * By default, the maximum number of items is limited to prevent excessive memory usage.
347
- *
348
- * @see TypeProvider.DEFAULT_ARRAY_MAX_ITEMS
349
- */
345
+ * Create a schema for an array.
346
+ * By default, the maximum number of items is limited to prevent excessive memory usage.
347
+ *
348
+ * @see TypeProvider.DEFAULT_ARRAY_MAX_ITEMS
349
+ */
350
350
  array<T extends TSchema$1>(schema: T, options?: TArrayOptions): TArray$1<T>;
351
351
  /**
352
- * Create a schema for a string.
353
- * For db or input fields, consider using `t.text()` instead, which has length limits.
354
- *
355
- * If you need a string with specific format (e.g. email, uuid), consider using the corresponding method (e.g. `t.email()`, `t.uuid()`).
356
- */
352
+ * Create a schema for a string.
353
+ * For db or input fields, consider using `t.text()` instead, which has length limits.
354
+ *
355
+ * If you need a string with specific format (e.g. email, uuid), consider using the corresponding method (e.g. `t.email()`, `t.uuid()`).
356
+ */
357
357
  string(options?: TStringOptions$1): TString$1;
358
358
  /**
359
- * Create a schema for a string with length limits.
360
- * For internal strings without length limits, consider using `t.string()` instead.
361
- *
362
- * Default size is "regular", which has a max length of 255 characters.
363
- */
359
+ * Create a schema for a string with length limits.
360
+ * For internal strings without length limits, consider using `t.string()` instead.
361
+ *
362
+ * Default size is "regular", which has a max length of 255 characters.
363
+ */
364
364
  text(options?: TTextOptions): TString$1;
365
365
  /**
366
- * Create a schema for a JSON object.
367
- * This is a record with string keys and any values.
368
- */
366
+ * Create a schema for a JSON object.
367
+ * This is a record with string keys and any values.
368
+ */
369
369
  json<T = any>(options?: TSchemaOptions): TRecord$1<string, TAny$1>;
370
370
  /**
371
- * Create a schema for a boolean.
372
- */
371
+ * Create a schema for a boolean.
372
+ */
373
373
  boolean(options?: TSchemaOptions): TBoolean$1;
374
374
  /**
375
- * Create a schema for a number.
376
- */
375
+ * Create a schema for a number.
376
+ */
377
377
  number(options?: TNumberOptions$1): TNumber$1;
378
378
  /**
379
- * Create a schema for an integer.
380
- */
379
+ * Create a schema for an integer.
380
+ */
381
381
  integer(options?: TNumberOptions$1): TInteger$1;
382
382
  int32(options?: TNumberOptions$1): TInteger$1;
383
383
  /**
384
- * Mimic a signed 64-bit integer.
385
- *
386
- * This is NOT a true int64, as JavaScript cannot represent all int64 values.
387
- * It is a number that is an integer and between -9007199254740991 and 9007199254740991.
388
- * Use `t.bigint()` for true int64 values represented as strings.
389
- */
384
+ * Mimic a signed 64-bit integer.
385
+ *
386
+ * This is NOT a true int64, as JavaScript cannot represent all int64 values.
387
+ * It is a number that is an integer and between -9007199254740991 and 9007199254740991.
388
+ * Use `t.bigint()` for true int64 values represented as strings.
389
+ */
390
390
  int64(options?: TNumberOptions$1): TNumber$1;
391
391
  /**
392
- * Make a schema optional.
393
- */
392
+ * Make a schema optional.
393
+ */
394
394
  optional<T extends TSchema$1>(schema: T): TOptionalAdd$1<T>;
395
395
  /**
396
- * Make a schema nullable.
397
- */
396
+ * Make a schema nullable.
397
+ */
398
398
  nullable<T extends TSchema$1>(schema: T, options?: TObjectOptions$1): TUnion$1<[TNull$1, T]>;
399
399
  /**
400
- * Create a schema that maps all properties of an object schema to nullable.
401
- */
400
+ * Create a schema that maps all properties of an object schema to nullable.
401
+ */
402
402
  nullify: <T extends TSchema$1>(schema: T, options?: TObjectOptions$1) => typebox0.TMappedInstantiate<{}, {
403
403
  callstack: [];
404
404
  }, Type.TIdentifier<"K">, typebox0.TKeyOfInstantiate<{}, {
@@ -407,65 +407,65 @@ declare class TypeProvider {
407
407
  callstack: [];
408
408
  }, T, Type.TRef<"K">>, TNull$1]>>;
409
409
  /**
410
- * Create a schema for a string enum.
411
- */
410
+ * Create a schema for a string enum.
411
+ */
412
412
  enum<T extends string[]>(values: [...T], options?: TTextOptions): TUnsafe$1<T[number]>;
413
413
  /**
414
- * Create a schema for a bigint represented as a string.
415
- * This is a string that validates bigint format (e.g. "123456789").
416
- */
414
+ * Create a schema for a bigint represented as a string.
415
+ * This is a string that validates bigint format (e.g. "123456789").
416
+ */
417
417
  bigint(options?: TStringOptions$1): TString$1;
418
418
  /**
419
- * Create a schema for a URL represented as a string.
420
- */
419
+ * Create a schema for a URL represented as a string.
420
+ */
421
421
  url(options?: TStringOptions$1): TString$1;
422
422
  /**
423
- * Create a schema for binary data represented as a base64 string.
424
- */
423
+ * Create a schema for binary data represented as a base64 string.
424
+ */
425
425
  binary(options: TStringOptions$1): TString$1;
426
426
  /**
427
- * Create a schema for uuid.
428
- */
427
+ * Create a schema for uuid.
428
+ */
429
429
  uuid(options?: TStringOptions$1): TString$1;
430
430
  /**
431
- * Create a schema for a file-like object.
432
- *
433
- * File like mimics the File API in browsers, but is adapted to work in Node.js as well.
434
- *
435
- * Implementation of file-like objects is handled by "alepha/file" package.
436
- */
431
+ * Create a schema for a file-like object.
432
+ *
433
+ * File like mimics the File API in browsers, but is adapted to work in Node.js as well.
434
+ *
435
+ * Implementation of file-like objects is handled by "alepha/file" package.
436
+ */
437
437
  file(options?: {
438
438
  maxSize?: number;
439
439
  }): TFile;
440
440
  /**
441
- * @experimental
442
- */
441
+ * @experimental
442
+ */
443
443
  stream(): TStream;
444
444
  email(options?: TStringOptions$1): TString$1;
445
445
  e164(options?: TStringOptions$1): TString$1;
446
446
  bcp47(options?: TStringOptions$1): TString$1;
447
447
  /**
448
- * Create a schema for short text, such as names or titles.
449
- * Default max length is 64 characters.
450
- */
448
+ * Create a schema for short text, such as names or titles.
449
+ * Default max length is 64 characters.
450
+ */
451
451
  shortText(options?: TStringOptions$1): TString$1;
452
452
  /**
453
- * Create a schema for long text, such as descriptions or comments.
454
- * Default max length is 1024 characters.
455
- */
453
+ * Create a schema for long text, such as descriptions or comments.
454
+ * Default max length is 1024 characters.
455
+ */
456
456
  longText(options?: TStringOptions$1): TString$1;
457
457
  /**
458
- * Create a schema for rich text, such as HTML or Markdown.
459
- * Default max length is 65535 characters.
460
- */
458
+ * Create a schema for rich text, such as HTML or Markdown.
459
+ * Default max length is 65535 characters.
460
+ */
461
461
  richText(options?: TStringOptions$1): TString$1;
462
462
  /**
463
- * Create a schema for a string enum e.g. LIKE_THIS.
464
- */
463
+ * Create a schema for a string enum e.g. LIKE_THIS.
464
+ */
465
465
  snakeCase: (options?: TStringOptions$1) => TString$1;
466
466
  /**
467
- * Create a schema for an object with a value and label.
468
- */
467
+ * Create a schema for an object with a value and label.
468
+ */
469
469
  valueLabel: (options?: TObjectOptions$1) => TObject$1<{
470
470
  value: TString$1;
471
471
  label: TString$1;
@@ -479,29 +479,29 @@ declare class TypeProvider {
479
479
  type TextLength = "short" | "regular" | "long" | "rich";
480
480
  interface TTextOptions extends TStringOptions$1 {
481
481
  /**
482
- * Predefined size of the text.
483
- *
484
- * - `short` - short text, such as names or titles. Default max length is 64 characters.
485
- * - `regular` - regular text, such as single-line input. Default max length is 255 characters.
486
- * - `long` - long text, such as descriptions or comments. Default max length is 1024 characters.
487
- * - `rich` - rich text, such as HTML or Markdown. Default max length is 65535 characters.
488
- *
489
- * You can override the default max length by specifying `maxLength` in the options.
490
- *
491
- * @default "regular"
492
- */
482
+ * Predefined size of the text.
483
+ *
484
+ * - `short` - short text, such as names or titles. Default max length is 64 characters.
485
+ * - `regular` - regular text, such as single-line input. Default max length is 255 characters.
486
+ * - `long` - long text, such as descriptions or comments. Default max length is 1024 characters.
487
+ * - `rich` - rich text, such as HTML or Markdown. Default max length is 65535 characters.
488
+ *
489
+ * You can override the default max length by specifying `maxLength` in the options.
490
+ *
491
+ * @default "regular"
492
+ */
493
493
  size?: TextLength;
494
494
  /**
495
- * Trim whitespace from both ends of the string.
496
- *
497
- * @default true
498
- */
495
+ * Trim whitespace from both ends of the string.
496
+ *
497
+ * @default true
498
+ */
499
499
  trim?: boolean;
500
500
  /**
501
- * Convert the string to lowercase.
502
- *
503
- * @default false
504
- */
501
+ * Convert the string to lowercase.
502
+ *
503
+ * @default false
504
+ */
505
505
  lowercase?: boolean;
506
506
  }
507
507
  declare const t: TypeProvider;
@@ -577,25 +577,25 @@ declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions
577
577
  declare class InjectPrimitive extends Primitive {}
578
578
  interface InjectOptions<T extends object = any> {
579
579
  /**
580
- * - 'transient' → Always a new instance on every inject. Zero caching.
581
- * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
582
- * - 'scoped' → One instance per AsyncLocalStorage context.
583
- * - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
584
- * - You can also start a manual scope via alepha.context.run(() => { ... }).
585
- * - When the scope ends, the scoped registry is discarded.
586
- *
587
- * @default "singleton"
588
- */
580
+ * - 'transient' → Always a new instance on every inject. Zero caching.
581
+ * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
582
+ * - 'scoped' → One instance per AsyncLocalStorage context.
583
+ * - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
584
+ * - You can also start a manual scope via alepha.context.run(() => { ... }).
585
+ * - When the scope ends, the scoped registry is discarded.
586
+ *
587
+ * @default "singleton"
588
+ */
589
589
  lifetime?: "transient" | "singleton" | "scoped";
590
590
  /**
591
- * Constructor arguments to pass when creating a new instance.
592
- */
591
+ * Constructor arguments to pass when creating a new instance.
592
+ */
593
593
  args?: ConstructorParameters<InstantiableClass<T>>;
594
594
  /**
595
- * Parent that requested the instance.
596
- *
597
- * @internal
598
- */
595
+ * Parent that requested the instance.
596
+ *
597
+ * @internal
598
+ */
599
599
  parent?: Service | null;
600
600
  }
601
601
  //#endregion
@@ -651,30 +651,34 @@ interface InjectOptions<T extends object = any> {
651
651
  declare const $module: <T extends object = {}>(options: ModulePrimitiveOptions) => Service<Module>;
652
652
  interface ModulePrimitiveOptions {
653
653
  /**
654
- * Name of the module.
655
- *
656
- * It should be in the format of `project.module.submodule`.
657
- */
654
+ * Name of the module.
655
+ *
656
+ * It should be in the format of `project.module.submodule`.
657
+ */
658
658
  name: string;
659
659
  /**
660
- * List all services related to this module.
661
- *
662
- * If you don't declare 'register' function, all services will be registered automatically.
663
- * If you declare 'register' function, you must handle the registration of ALL services manually.
664
- */
660
+ * List all services related to this module.
661
+ *
662
+ * If you don't declare 'register' function, all services will be registered automatically.
663
+ * If you declare 'register' function, you must handle the registration of ALL services manually.
664
+ */
665
665
  services?: Array<Service>;
666
666
  /**
667
- * List of $primitives to register in the module.
668
- */
667
+ * List of $primitives to register in the module.
668
+ */
669
669
  primitives?: Array<PrimitiveFactoryLike>;
670
670
  /**
671
- * By default, module will register ALL services.
672
- * You can override this behavior by providing a register function.
673
- * It's useful when you want to register services conditionally or in a specific order.
674
- *
675
- * Again, if you declare 'register', you must handle the registration of ALL services manually.
676
- */
671
+ * By default, module will register ALL services.
672
+ * You can override this behavior by providing a register function.
673
+ * It's useful when you want to register services conditionally or in a specific order.
674
+ *
675
+ * Again, if you declare 'register', you must handle the registration of ALL services manually.
676
+ */
677
677
  register?: (alepha: Alepha) => void;
678
+ /**
679
+ * List of atoms to register in the module.
680
+ */
681
+ atoms?: Array<Atom<any>>;
678
682
  }
679
683
  /**
680
684
  * Base class for all modules.
@@ -684,14 +688,14 @@ declare abstract class Module {
684
688
  abstract register(alepha: Alepha): void;
685
689
  static NAME_REGEX: RegExp;
686
690
  /**
687
- * Check if a Service is a Module.
688
- */
691
+ * Check if a Service is a Module.
692
+ */
689
693
  static is(ctor: Service): boolean;
690
694
  /**
691
- * Get the Module of a Service.
692
- *
693
- * Returns undefined if the Service is not part of a Module.
694
- */
695
+ * Get the Module of a Service.
696
+ *
697
+ * Returns undefined if the Service is not part of a Module.
698
+ */
695
699
  static of(ctor: Service): Service<Module> | undefined;
696
700
  }
697
701
  /**
@@ -728,16 +732,16 @@ declare class Json {
728
732
  //#region ../../src/core/providers/SchemaCodec.d.ts
729
733
  declare abstract class SchemaCodec {
730
734
  /**
731
- * Encode the value to a string format.
732
- */
735
+ * Encode the value to a string format.
736
+ */
733
737
  abstract encodeToString<T extends TSchema>(schema: T, value: Static<T>): string;
734
738
  /**
735
- * Encode the value to a binary format.
736
- */
739
+ * Encode the value to a binary format.
740
+ */
737
741
  abstract encodeToBinary<T extends TSchema>(schema: T, value: Static<T>): Uint8Array;
738
742
  /**
739
- * Decode string, binary, or other formats to the schema type.
740
- */
743
+ * Decode string, binary, or other formats to the schema type.
744
+ */
741
745
  abstract decode<T>(schema: TSchema, value: unknown): T;
742
746
  }
743
747
  //#endregion
@@ -751,61 +755,6 @@ declare class JsonSchemaCodec extends SchemaCodec {
751
755
  decode<T>(schema: TSchema$1, value: unknown): T;
752
756
  }
753
757
  //#endregion
754
- //#region ../../src/core/providers/KeylessJsonSchemaCodec.d.ts
755
- interface KeylessCodec<T = any> {
756
- encode: (value: T) => string;
757
- decode: (str: string) => T;
758
- }
759
- /**
760
- * KeylessJsonSchemaCodec provides schema-driven JSON encoding without keys.
761
- *
762
- * It uses the schema to determine field order, allowing the encoded output
763
- * to be a simple JSON array instead of an object with keys.
764
- *
765
- * Performance characteristics:
766
- * - Encode: 0.94-1.53x vs JSON.stringify (faster for complex objects)
767
- * - Decode: 1.76-2.00x vs JSON.parse
768
- * - Size: 50-56% smaller than JSON
769
- */
770
- declare class KeylessJsonSchemaCodec extends SchemaCodec {
771
- protected readonly cache: Map<TSchema$1, KeylessCodec<any>>;
772
- protected readonly encoder: TextEncoder;
773
- protected readonly decoder: TextDecoder;
774
- protected varCounter: number;
775
- /**
776
- * Encode value to a keyless JSON string.
777
- */
778
- encodeToString<T extends TSchema$1>(schema: T, value: Static<T>): string;
779
- /**
780
- * Encode value to binary (UTF-8 encoded keyless JSON).
781
- */
782
- encodeToBinary<T extends TSchema$1>(schema: T, value: Static<T>): Uint8Array;
783
- /**
784
- * Decode keyless JSON string or binary to value.
785
- */
786
- decode<T>(schema: TSchema$1, value: unknown): T;
787
- /**
788
- * Get a compiled codec for the given schema.
789
- * Codecs are cached for reuse.
790
- */
791
- protected getCodec<T>(schema: TSchema$1): KeylessCodec<T>;
792
- protected nextVar(): string;
793
- protected compile(schema: TSchema$1): KeylessCodec;
794
- protected genEnc(schema: TSchema$1, ve: string): string;
795
- protected genDec(schema: TSchema$1): {
796
- code: string;
797
- result: string;
798
- };
799
- protected genDecFromValue(schema: TSchema$1, expr: string): string;
800
- protected isEnum(schema: TSchema$1): boolean;
801
- protected isNullable(schema: TSchema$1): boolean;
802
- protected unwrap(schema: TSchema$1): TSchema$1;
803
- /**
804
- * Reconstruct an object from a parsed array (for when input is already parsed).
805
- */
806
- protected reconstructObject(schema: TSchema$1, arr: any[]): any;
807
- }
808
- //#endregion
809
758
  //#region ../../src/core/primitives/$hook.d.ts
810
759
  /**
811
760
  * Registers a new hook.
@@ -852,24 +801,24 @@ declare const $hook: {
852
801
  };
853
802
  interface HookOptions<T extends keyof Hooks> {
854
803
  /**
855
- * The name of the hook. "configure", "start", "ready", "stop", ...
856
- */
804
+ * The name of the hook. "configure", "start", "ready", "stop", ...
805
+ */
857
806
  on: T;
858
807
  /**
859
- * The handler to run when the hook is triggered.
860
- */
808
+ * The handler to run when the hook is triggered.
809
+ */
861
810
  handler: (args: Hooks[T]) => Async<any>;
862
811
  /**
863
- * Force the hook to run first or last on the list of hooks.
864
- */
812
+ * Force the hook to run first or last on the list of hooks.
813
+ */
865
814
  priority?: "first" | "last";
866
815
  /**
867
- * Empty placeholder, not implemented yet. :-)
868
- */
816
+ * Empty placeholder, not implemented yet. :-)
817
+ */
869
818
  before?: object | Array<object>;
870
819
  /**
871
- * Empty placeholder, not implemented yet. :-)
872
- */
820
+ * Empty placeholder, not implemented yet. :-)
821
+ */
873
822
  after?: object | Array<object>;
874
823
  }
875
824
  declare class HookPrimitive<T extends keyof Hooks> extends Primitive<HookOptions<T>> {
@@ -877,27 +826,152 @@ declare class HookPrimitive<T extends keyof Hooks> extends Primitive<HookOptions
877
826
  protected onInit(): void;
878
827
  }
879
828
  //#endregion
829
+ //#region ../../src/core/providers/KeylessJsonSchemaCodec.d.ts
830
+ interface KeylessCodec<T = any> {
831
+ encode: (value: T) => string;
832
+ decode: (str: string) => T;
833
+ }
834
+ interface KeylessCodecOptions {
835
+ /**
836
+ * Whether to use `new Function()` for code compilation.
837
+ * When false, uses an interpreter-based approach (safer but slower).
838
+ *
839
+ * @default Auto-detected: false in browser (CSP compatibility), true on server
840
+ */
841
+ useFunctionCompilation?: boolean;
842
+ /**
843
+ * Maximum allowed array length during encoding/decoding.
844
+ * Prevents DoS attacks via large arrays.
845
+ *
846
+ * @default 10000
847
+ */
848
+ maxArrayLength?: number;
849
+ /**
850
+ * Maximum allowed string length during encoding/decoding.
851
+ * Prevents DoS attacks via large strings.
852
+ *
853
+ * @default 1000000 (1MB)
854
+ */
855
+ maxStringLength?: number;
856
+ /**
857
+ * Maximum recursion depth for nested objects.
858
+ * Prevents stack overflow attacks.
859
+ *
860
+ * @default 50
861
+ */
862
+ maxDepth?: number;
863
+ }
864
+ /**
865
+ * KeylessJsonSchemaCodec provides schema-driven JSON encoding without keys.
866
+ *
867
+ * It uses the schema to determine field order, allowing the encoded output
868
+ * to be a simple JSON array instead of an object with keys.
869
+ */
870
+ declare class KeylessJsonSchemaCodec extends SchemaCodec {
871
+ protected readonly cache: Map<TSchema$1, KeylessCodec<any>>;
872
+ protected readonly textEncoder: TextEncoder;
873
+ protected readonly textDecoder: TextDecoder;
874
+ protected varCounter: number;
875
+ protected useFunctionCompilation: boolean;
876
+ protected maxArrayLength: number;
877
+ protected maxStringLength: number;
878
+ protected maxDepth: number;
879
+ /**
880
+ * Configure codec options.
881
+ */
882
+ configure(options: KeylessCodecOptions): this;
883
+ /**
884
+ * Hook to auto-detect safe mode on configure.
885
+ * Disables function compilation in browser by default.
886
+ */
887
+ protected onConfigure: HookPrimitive<"configure">;
888
+ /**
889
+ * Encode value to a keyless JSON string.
890
+ */
891
+ encodeToString<T extends TSchema$1>(schema: T, value: Static<T>): string;
892
+ /**
893
+ * Encode value to binary (UTF-8 encoded keyless JSON).
894
+ */
895
+ encodeToBinary<T extends TSchema$1>(schema: T, value: Static<T>): Uint8Array;
896
+ /**
897
+ * Decode keyless JSON string or binary to value.
898
+ */
899
+ decode<T>(schema: TSchema$1, value: unknown): T;
900
+ /**
901
+ * Test if `new Function()` is available (not blocked by CSP).
902
+ */
903
+ protected canUseFunction(): boolean;
904
+ /**
905
+ * Validate schema keys for prototype pollution.
906
+ * Uses a visited set to avoid infinite recursion on recursive schemas.
907
+ */
908
+ protected validateSchemaKeys(schema: TSchema$1, depth?: number, visited?: Set<TSchema$1>): void;
909
+ /**
910
+ * Validate array length.
911
+ */
912
+ protected validateArrayLength(arr: unknown[]): void;
913
+ /**
914
+ * Validate string length.
915
+ */
916
+ protected validateStringLength(str: string): void;
917
+ /**
918
+ * Get a compiled codec for the given schema.
919
+ * Codecs are cached for reuse.
920
+ */
921
+ protected getCodec<T>(schema: TSchema$1): KeylessCodec<T>;
922
+ protected nextVar(): string;
923
+ /**
924
+ * Compile codec using `new Function()` for maximum performance.
925
+ * Only used when CSP allows and useFunctionCompilation is true.
926
+ */
927
+ protected compileWithFunction(schema: TSchema$1): KeylessCodec;
928
+ /**
929
+ * Compile codec using interpreter-based approach.
930
+ * Safer (no eval/Function) but slower. Used in browser by default.
931
+ */
932
+ protected compileInterpreted(schema: TSchema$1): KeylessCodec;
933
+ protected interpretEncode(schema: TSchema$1, value: any): any;
934
+ protected interpretDecode(schema: TSchema$1, ctx: {
935
+ arr: any[];
936
+ i: number;
937
+ }): any;
938
+ protected interpretDecodeFromValue(schema: TSchema$1, value: any): any;
939
+ protected genEnc(schema: TSchema$1, ve: string): string;
940
+ protected genDec(schema: TSchema$1): {
941
+ code: string;
942
+ result: string;
943
+ };
944
+ protected genDecFromValue(schema: TSchema$1, expr: string): string;
945
+ protected isEnum(schema: TSchema$1): boolean;
946
+ protected isNullable(schema: TSchema$1): boolean;
947
+ protected unwrap(schema: TSchema$1): TSchema$1;
948
+ /**
949
+ * Reconstruct an object from a parsed array (for when input is already parsed).
950
+ */
951
+ protected reconstructObject(schema: TSchema$1, arr: any[]): any;
952
+ }
953
+ //#endregion
880
954
  //#region ../../src/core/providers/SchemaValidator.d.ts
881
955
  declare class SchemaValidator {
882
956
  protected cache: Map<TSchema$1, Validator<typebox0.TProperties, TSchema$1, unknown, unknown>>;
883
957
  protected useEval: boolean;
884
958
  /**
885
- * Validate the value against the provided schema.
886
- *
887
- * Validation create a new value by applying some preprocessing. (e.g., trimming text)
888
- */
959
+ * Validate the value against the provided schema.
960
+ *
961
+ * Validation create a new value by applying some preprocessing. (e.g., trimming text)
962
+ */
889
963
  validate<T extends TSchema$1>(schema: T, value: unknown, options?: ValidateOptions): Static<T>;
890
964
  protected getValidator<T extends TSchema$1>(schema: T): Validator<{}, T>;
891
965
  /**
892
- * Preprocess the value based on the schema before validation.
893
- *
894
- * - If the value is `null` and the schema does not allow `null`, it converts it to `undefined`.
895
- * - If the value is a string and the schema has a `~options.trim` flag, it trims whitespace from the string.
896
- */
966
+ * Preprocess the value based on the schema before validation.
967
+ *
968
+ * - If the value is `null` and the schema does not allow `null`, it converts it to `undefined`.
969
+ * - If the value is a string and the schema has a `~options.trim` flag, it trims whitespace from the string.
970
+ */
897
971
  beforeParse(schema: any, value: any, options: ValidateOptions): any;
898
972
  /**
899
- * Used by `beforeParse` to determine if a schema allows null values.
900
- */
973
+ * Used by `beforeParse` to determine if a schema allows null values.
974
+ */
901
975
  protected isSchemaNullable: (schema: any) => boolean;
902
976
  protected onConfigure: HookPrimitive<"configure">;
903
977
  protected canEval(): boolean;
@@ -912,35 +986,35 @@ interface ValidateOptions {
912
986
  type Encoding = "object" | "string" | "binary";
913
987
  interface EncodeOptions<T extends Encoding = Encoding> {
914
988
  /**
915
- * The output encoding format:
916
- * - 'string': Returns JSON string
917
- * - 'binary': Returns Uint8Array (for protobuf, msgpack, etc.)
918
- *
919
- * @default "string"
920
- */
989
+ * The output encoding format:
990
+ * - 'string': Returns JSON string
991
+ * - 'binary': Returns Uint8Array (for protobuf, msgpack, etc.)
992
+ *
993
+ * @default "string"
994
+ */
921
995
  as?: T;
922
996
  /**
923
- * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
924
- *
925
- * @default "json"
926
- */
997
+ * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
998
+ *
999
+ * @default "json"
1000
+ */
927
1001
  encoder?: string;
928
1002
  /**
929
- * Validation options to apply before encoding.
930
- */
1003
+ * Validation options to apply before encoding.
1004
+ */
931
1005
  validation?: ValidateOptions | false;
932
1006
  }
933
1007
  type EncodeResult<T extends TSchema$1, E extends Encoding> = E extends "string" ? string : E extends "binary" ? Uint8Array : StaticEncode$1<T>;
934
1008
  interface DecodeOptions {
935
1009
  /**
936
- * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
937
- *
938
- * @default "json"
939
- */
1010
+ * The encoder to use (e.g., 'json', 'protobuf', 'msgpack')
1011
+ *
1012
+ * @default "json"
1013
+ */
940
1014
  encoder?: string;
941
1015
  /**
942
- * Validation options to apply before encoding.
943
- */
1016
+ * Validation options to apply before encoding.
1017
+ */
944
1018
  validation?: ValidateOptions | false;
945
1019
  }
946
1020
  /**
@@ -955,30 +1029,30 @@ declare class CodecManager {
955
1029
  default: string;
956
1030
  constructor();
957
1031
  /**
958
- * Register a new codec format.
959
- */
1032
+ * Register a new codec format.
1033
+ */
960
1034
  register(opts: CodecRegisterOptions): void;
961
1035
  /**
962
- * Get a specific codec by name.
963
- *
964
- * @param name - The name of the codec
965
- * @returns The codec instance
966
- * @throws {AlephaError} If the codec is not found
967
- */
1036
+ * Get a specific codec by name.
1037
+ *
1038
+ * @param name - The name of the codec
1039
+ * @returns The codec instance
1040
+ * @throws {AlephaError} If the codec is not found
1041
+ */
968
1042
  getCodec(name: string): SchemaCodec;
969
1043
  /**
970
- * Encode data using the specified codec and output format.
971
- */
1044
+ * Encode data using the specified codec and output format.
1045
+ */
972
1046
  encode<T extends TSchema$1, E extends Encoding = "object">(schema: T, value: unknown, options?: EncodeOptions<E>): EncodeResult<T, E>;
973
1047
  /**
974
- * Decode data using the specified codec.
975
- */
1048
+ * Decode data using the specified codec.
1049
+ */
976
1050
  decode<T extends TSchema$1>(schema: T, data: any, options?: DecodeOptions): Static<T>;
977
1051
  /**
978
- * Validate decoded data against the schema.
979
- *
980
- * This is automatically called before encoding or after decoding.
981
- */
1052
+ * Validate decoded data against the schema.
1053
+ *
1054
+ * This is automatically called before encoding or after decoding.
1055
+ */
982
1056
  validate<T extends TSchema$1>(schema: T, value: unknown, options?: ValidateOptions): Static<T>;
983
1057
  }
984
1058
  interface CodecRegisterOptions {
@@ -998,67 +1072,67 @@ type CompiledEventExecutor<T> = (payload: T) => void | Promise<void>;
998
1072
  */
999
1073
  interface CompileOptions {
1000
1074
  /**
1001
- * If true, errors will be caught and logged instead of throwing.
1002
- * @default false
1003
- */
1075
+ * If true, errors will be caught and logged instead of throwing.
1076
+ * @default false
1077
+ */
1004
1078
  catch?: boolean;
1005
1079
  }
1006
1080
  declare class EventManager {
1007
1081
  logFn?: () => LoggerInterface | undefined;
1008
1082
  /**
1009
- * List of events that can be triggered. Powered by $hook().
1010
- */
1083
+ * List of events that can be triggered. Powered by $hook().
1084
+ */
1011
1085
  protected events: Record<string, Array<Hook>>;
1012
1086
  constructor(logFn?: () => LoggerInterface | undefined);
1013
1087
  protected get log(): LoggerInterface | undefined;
1014
1088
  clear(): void;
1015
1089
  /**
1016
- * Registers a hook for the specified event.
1017
- */
1090
+ * Registers a hook for the specified event.
1091
+ */
1018
1092
  on<T extends keyof Hooks>(event: T, hookOrFunc: Hook<T> | ((payload: Hooks[T]) => Async<void>)): () => void;
1019
1093
  /**
1020
- * Compiles an event into an optimized executor function.
1021
- *
1022
- * Call this after all hooks are registered (e.g., after Alepha.start()).
1023
- * The returned function checks each hook's return value and awaits promises.
1024
- * Returns undefined if all hooks are sync, or a Promise if any hook returns one.
1025
- *
1026
- * @example
1027
- * ```ts
1028
- * // At startup (after hooks are registered)
1029
- * const onRequest = alepha.events.compile("server:onRequest", { catch: true });
1030
- *
1031
- * // In hot path - only await if promise returned
1032
- * const result = onRequest({ request, route });
1033
- * if (result) await result;
1034
- * ```
1035
- */
1094
+ * Compiles an event into an optimized executor function.
1095
+ *
1096
+ * Call this after all hooks are registered (e.g., after Alepha.start()).
1097
+ * The returned function checks each hook's return value and awaits promises.
1098
+ * Returns undefined if all hooks are sync, or a Promise if any hook returns one.
1099
+ *
1100
+ * @example
1101
+ * ```ts
1102
+ * // At startup (after hooks are registered)
1103
+ * const onRequest = alepha.events.compile("server:onRequest", { catch: true });
1104
+ *
1105
+ * // In hot path - only await if promise returned
1106
+ * const result = onRequest({ request, route });
1107
+ * if (result) await result;
1108
+ * ```
1109
+ */
1036
1110
  compile<T extends keyof Hooks>(event: T, options?: CompileOptions): CompiledEventExecutor<Hooks[T]>;
1037
1111
  /**
1038
- * Emits the specified event with the given payload.
1039
- *
1040
- * For hot paths (like HTTP request handling), use compile() instead
1041
- * to get an optimized executor.
1042
- */
1112
+ * Emits the specified event with the given payload.
1113
+ *
1114
+ * For hot paths (like HTTP request handling), use compile() instead
1115
+ * to get an optimized executor.
1116
+ */
1043
1117
  emit<T extends keyof Hooks>(func: T, payload: Hooks[T], options?: {
1044
1118
  /**
1045
- * If true, the hooks will be executed in reverse order.
1046
- * This is useful for "stop" hooks that should be executed in reverse order.
1047
- *
1048
- * @default false
1049
- */
1119
+ * If true, the hooks will be executed in reverse order.
1120
+ * This is useful for "stop" hooks that should be executed in reverse order.
1121
+ *
1122
+ * @default false
1123
+ */
1050
1124
  reverse?: boolean;
1051
1125
  /**
1052
- * If true, the hooks will be logged with their execution time.
1053
- *
1054
- * @default false
1055
- */
1126
+ * If true, the hooks will be logged with their execution time.
1127
+ *
1128
+ * @default false
1129
+ */
1056
1130
  log?: boolean;
1057
1131
  /**
1058
- * If true, errors will be caught and logged instead of throwing.
1059
- *
1060
- * @default false
1061
- */
1132
+ * If true, errors will be caught and logged instead of throwing.
1133
+ *
1134
+ * @default false
1135
+ */
1062
1136
  catch?: boolean;
1063
1137
  }): Promise<void>;
1064
1138
  }
@@ -1078,39 +1152,39 @@ declare class StateManager<State$1 extends object = State> {
1078
1152
  getAtoms(context?: boolean): Array<AtomWithValue>;
1079
1153
  register(atom: Atom<any>): this;
1080
1154
  /**
1081
- * Get a value from the state with proper typing
1082
- */
1155
+ * Get a value from the state with proper typing
1156
+ */
1083
1157
  get<T extends TAtomObject>(target: Atom<T>): Static<T>;
1084
1158
  get<Key extends keyof State$1>(target: Key): State$1[Key] | undefined;
1085
1159
  /**
1086
- * Set a value in the state
1087
- */
1160
+ * Set a value in the state
1161
+ */
1088
1162
  set<T extends TAtomObject>(target: Atom<T>, value: AtomStatic<T>, options?: SetStateOptions): this;
1089
1163
  set<Key extends keyof State$1>(target: Key, value: State$1[Key] | undefined, options?: SetStateOptions): this;
1090
1164
  /**
1091
- * Mutate a value in the state.
1092
- */
1165
+ * Mutate a value in the state.
1166
+ */
1093
1167
  mut<T extends TObject$1>(target: Atom<T>, mutator: (current: Static<T>) => Static<T>): this;
1094
1168
  mut<Key extends keyof State$1>(target: Key, mutator: (current: State$1[Key] | undefined) => State$1[Key] | undefined): this;
1095
1169
  /**
1096
- * Check if a key exists in the state
1097
- */
1170
+ * Check if a key exists in the state
1171
+ */
1098
1172
  has<Key extends keyof State$1>(key: Key): boolean;
1099
1173
  /**
1100
- * Delete a key from the state (set to undefined)
1101
- */
1174
+ * Delete a key from the state (set to undefined)
1175
+ */
1102
1176
  del<Key extends keyof State$1>(key: Key): this;
1103
1177
  /**
1104
- * Push a value to an array in the state
1105
- */
1178
+ * Push a value to an array in the state
1179
+ */
1106
1180
  push<Key extends keyof OnlyArray<State$1>>(key: Key, ...value: Array<NonNullable<State$1[Key]> extends Array<infer U> ? U : never>): this;
1107
1181
  /**
1108
- * Clear all state
1109
- */
1182
+ * Clear all state
1183
+ */
1110
1184
  clear(): this;
1111
1185
  /**
1112
- * Get all keys that exist in the state
1113
- */
1186
+ * Get all keys that exist in the state
1187
+ */
1114
1188
  keys(): (keyof State$1)[];
1115
1189
  }
1116
1190
  type OnlyArray<T extends object> = { [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never };
@@ -1245,264 +1319,264 @@ interface SetStateOptions {
1245
1319
  */
1246
1320
  declare class Alepha {
1247
1321
  /**
1248
- * Creates a new instance of the Alepha container with some helpers:
1249
- *
1250
- * - merges `process.env` with the provided state.env when available.
1251
- * - populates the test hooks for Vitest or Jest environments when available.
1252
- *
1253
- * If you are not interested about these helpers, you can use the constructor directly.
1254
- */
1322
+ * Creates a new instance of the Alepha container with some helpers:
1323
+ *
1324
+ * - merges `process.env` with the provided state.env when available.
1325
+ * - populates the test hooks for Vitest or Jest environments when available.
1326
+ *
1327
+ * If you are not interested about these helpers, you can use the constructor directly.
1328
+ */
1255
1329
  static create(state?: Partial<State>): Alepha;
1256
1330
  /**
1257
- * Flag indicating whether the App won't accept any further changes.
1258
- * Pass to true when #start() is called.
1259
- */
1331
+ * Flag indicating whether the App won't accept any further changes.
1332
+ * Pass to true when #start() is called.
1333
+ */
1260
1334
  protected locked: boolean;
1261
1335
  /**
1262
- * True if the App has been configured.
1263
- */
1336
+ * True if the App has been configured.
1337
+ */
1264
1338
  protected configured: boolean;
1265
1339
  /**
1266
- * True if the App has started.
1267
- */
1340
+ * True if the App has started.
1341
+ */
1268
1342
  protected started: boolean;
1269
1343
  /**
1270
- * True if the App is ready.
1271
- */
1344
+ * True if the App is ready.
1345
+ */
1272
1346
  protected ready: boolean;
1273
1347
  /**
1274
- * A promise that resolves when the App has started.
1275
- */
1348
+ * A promise that resolves when the App has started.
1349
+ */
1276
1350
  protected starting?: PromiseWithResolvers<this>;
1277
1351
  /**
1278
- * During the instantiation process, we keep a list of pending instantiations.
1279
- * > It allows us to detect circular dependencies.
1280
- */
1352
+ * During the instantiation process, we keep a list of pending instantiations.
1353
+ * > It allows us to detect circular dependencies.
1354
+ */
1281
1355
  protected pendingInstantiations: Service[];
1282
1356
  /**
1283
- * Cache for environment variables.
1284
- * > It allows us to avoid parsing the same schema multiple times.
1285
- */
1357
+ * Cache for environment variables.
1358
+ * > It allows us to avoid parsing the same schema multiple times.
1359
+ */
1286
1360
  protected cacheEnv: Map<TSchema, any>;
1287
1361
  /**
1288
- * List of modules that are registered in the container.
1289
- *
1290
- * Modules are used to group services and provide a way to register them in the container.
1291
- */
1362
+ * List of modules that are registered in the container.
1363
+ *
1364
+ * Modules are used to group services and provide a way to register them in the container.
1365
+ */
1292
1366
  protected modules: Array<Module>;
1293
1367
  /**
1294
- * List of service substitutions.
1295
- *
1296
- * Services registered here will be replaced by the specified service when injected.
1297
- */
1368
+ * List of service substitutions.
1369
+ *
1370
+ * Services registered here will be replaced by the specified service when injected.
1371
+ */
1298
1372
  protected substitutions: Map<Service, {
1299
1373
  use: Service;
1300
1374
  }>;
1301
1375
  /**
1302
- * Registry of primitives.
1303
- */
1376
+ * Registry of primitives.
1377
+ */
1304
1378
  protected primitiveRegistry: Map<Service<Primitive<{}>>, Primitive<{}>[]>;
1305
1379
  /**
1306
- * List of all services + how they are provided.
1307
- */
1380
+ * List of all services + how they are provided.
1381
+ */
1308
1382
  protected registry: Map<Service, ServiceDefinition>;
1309
1383
  /**
1310
- * Node.js feature that allows to store context across asynchronous calls.
1311
- *
1312
- * This is used for logging, tracing, and other context-related features.
1313
- *
1314
- * Mocked for browser environments.
1315
- */
1384
+ * Node.js feature that allows to store context across asynchronous calls.
1385
+ *
1386
+ * This is used for logging, tracing, and other context-related features.
1387
+ *
1388
+ * Mocked for browser environments.
1389
+ */
1316
1390
  context: AlsProvider;
1317
1391
  /**
1318
- * Event manager to handle lifecycle events and custom events.
1319
- */
1392
+ * Event manager to handle lifecycle events and custom events.
1393
+ */
1320
1394
  events: EventManager;
1321
1395
  /**
1322
- * State manager to store arbitrary values.
1323
- */
1396
+ * State manager to store arbitrary values.
1397
+ */
1324
1398
  store: StateManager<State>;
1325
1399
  /**
1326
- * Codec manager for encoding and decoding data with different formats.
1327
- *
1328
- * Supports multiple codec formats (JSON, Protobuf, etc.) with a unified interface.
1329
- */
1400
+ * Codec manager for encoding and decoding data with different formats.
1401
+ *
1402
+ * Supports multiple codec formats (JSON, Protobuf, etc.) with a unified interface.
1403
+ */
1330
1404
  codec: CodecManager;
1331
1405
  /**
1332
- * Get logger instance.
1333
- */
1406
+ * Get logger instance.
1407
+ */
1334
1408
  get log(): LoggerInterface | undefined;
1335
1409
  /**
1336
- * The environment variables for the App.
1337
- */
1410
+ * The environment variables for the App.
1411
+ */
1338
1412
  get env(): Readonly<Env>;
1339
1413
  constructor(state?: Partial<State>);
1340
1414
  set<T extends TAtomObject>(target: Atom<T>, value: AtomStatic<T>): this;
1341
1415
  set<Key extends keyof State>(target: Key, value: State[Key] | undefined): this;
1342
1416
  /**
1343
- * True when start() is called.
1344
- *
1345
- * -> No more services can be added, it's over, bye!
1346
- */
1417
+ * True when start() is called.
1418
+ *
1419
+ * -> No more services can be added, it's over, bye!
1420
+ */
1347
1421
  isLocked(): boolean;
1348
1422
  /**
1349
- * Returns whether the App is configured.
1350
- *
1351
- * It means that Alepha#configure() has been called.
1352
- *
1353
- * > By default, configure() is called automatically when start() is called, but you can also call it manually.
1354
- */
1423
+ * Returns whether the App is configured.
1424
+ *
1425
+ * It means that Alepha#configure() has been called.
1426
+ *
1427
+ * > By default, configure() is called automatically when start() is called, but you can also call it manually.
1428
+ */
1355
1429
  isConfigured(): boolean;
1356
1430
  /**
1357
- * Returns whether the App has started.
1358
- *
1359
- * It means that #start() has been called but maybe not all services are ready.
1360
- */
1431
+ * Returns whether the App has started.
1432
+ *
1433
+ * It means that #start() has been called but maybe not all services are ready.
1434
+ */
1361
1435
  isStarted(): boolean;
1362
1436
  /**
1363
- * True if the App is ready. It means that Alepha is started AND ready() hook has beed called.
1364
- */
1437
+ * True if the App is ready. It means that Alepha is started AND ready() hook has beed called.
1438
+ */
1365
1439
  isReady(): boolean;
1366
1440
  /**
1367
- * True if the App is running in a Continuous Integration environment.
1368
- */
1441
+ * True if the App is running in a Continuous Integration environment.
1442
+ */
1369
1443
  isCI(): boolean;
1370
1444
  /**
1371
- * True if the App is running in a browser environment.
1372
- */
1445
+ * True if the App is running in a browser environment.
1446
+ */
1373
1447
  isBrowser(): boolean;
1374
1448
  /**
1375
- * Returns whether the App is running in Vite dev mode.
1376
- */
1449
+ * Returns whether the App is running in Vite dev mode.
1450
+ */
1377
1451
  isViteDev(): boolean;
1378
1452
  isBun(): boolean;
1379
1453
  /**
1380
- * Returns whether the App is running in a serverless environment.
1381
- */
1454
+ * Returns whether the App is running in a serverless environment.
1455
+ */
1382
1456
  isServerless(): boolean;
1383
1457
  /**
1384
- * Returns whether the App is in test mode. (Running in a test environment)
1385
- *
1386
- * > This is automatically set when running tests with Jest or Vitest.
1387
- */
1458
+ * Returns whether the App is in test mode. (Running in a test environment)
1459
+ *
1460
+ * > This is automatically set when running tests with Jest or Vitest.
1461
+ */
1388
1462
  isTest(): boolean;
1389
1463
  /**
1390
- * Returns whether the App is in production mode. (Running in a production environment)
1391
- *
1392
- * > This is automatically set by Vite or Vercel. However, you have to set it manually when running Docker apps.
1393
- */
1464
+ * Returns whether the App is in production mode. (Running in a production environment)
1465
+ *
1466
+ * > This is automatically set by Vite or Vercel. However, you have to set it manually when running Docker apps.
1467
+ */
1394
1468
  isProduction(): boolean;
1395
1469
  /**
1396
- * Starts the App.
1397
- *
1398
- * - Lock any further changes to the container.
1399
- * - Run "configure" hook for all services. Primitives will be processed.
1400
- * - Run "start" hook for all services. Providers will connect/listen/...
1401
- * - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
1402
- *
1403
- * @return A promise that resolves when the App has started.
1404
- */
1470
+ * Starts the App.
1471
+ *
1472
+ * - Lock any further changes to the container.
1473
+ * - Run "configure" hook for all services. Primitives will be processed.
1474
+ * - Run "start" hook for all services. Providers will connect/listen/...
1475
+ * - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
1476
+ *
1477
+ * @return A promise that resolves when the App has started.
1478
+ */
1405
1479
  start(): Promise<this>;
1406
1480
  /**
1407
- * Stops the App.
1408
- *
1409
- * - Run "stop" hook for all services.
1410
- *
1411
- * Stop will NOT reset the container.
1412
- * Stop will NOT unlock the container.
1413
- *
1414
- * > Stop is used to gracefully shut down the application, nothing more. There is no "restart".
1415
- *
1416
- * @return A promise that resolves when the App has stopped.
1417
- */
1481
+ * Stops the App.
1482
+ *
1483
+ * - Run "stop" hook for all services.
1484
+ *
1485
+ * Stop will NOT reset the container.
1486
+ * Stop will NOT unlock the container.
1487
+ *
1488
+ * > Stop is used to gracefully shut down the application, nothing more. There is no "restart".
1489
+ *
1490
+ * @return A promise that resolves when the App has stopped.
1491
+ */
1418
1492
  stop(): Promise<void>;
1419
1493
  /**
1420
- * Check if entry is registered in the container.
1421
- */
1494
+ * Check if entry is registered in the container.
1495
+ */
1422
1496
  has(entry: ServiceEntry, opts?: {
1423
1497
  /**
1424
- * Check if the entry is registered in the pending instantiation stack.
1425
- *
1426
- * @default true
1427
- */
1498
+ * Check if the entry is registered in the pending instantiation stack.
1499
+ *
1500
+ * @default true
1501
+ */
1428
1502
  inStack?: boolean;
1429
1503
  /**
1430
- * Check if the entry is registered in the container registry.
1431
- *
1432
- * @default true
1433
- */
1504
+ * Check if the entry is registered in the container registry.
1505
+ *
1506
+ * @default true
1507
+ */
1434
1508
  inRegistry?: boolean;
1435
1509
  /**
1436
- * Check if the entry is registered in the substitutions.
1437
- *
1438
- * @default true
1439
- */
1510
+ * Check if the entry is registered in the substitutions.
1511
+ *
1512
+ * @default true
1513
+ */
1440
1514
  inSubstitutions?: boolean;
1441
1515
  /**
1442
- * Where to look for registered services.
1443
- *
1444
- * @default this.registry
1445
- */
1516
+ * Where to look for registered services.
1517
+ *
1518
+ * @default this.registry
1519
+ */
1446
1520
  registry?: Map<Service, ServiceDefinition>;
1447
1521
  }): boolean;
1448
1522
  /**
1449
- * Registers the specified service in the container.
1450
- *
1451
- * - If the service is ALREADY registered, the method does nothing.
1452
- * - If the service is NOT registered, a new instance is created and registered.
1453
- *
1454
- * Method is chainable, so you can register multiple services in a single call.
1455
- *
1456
- * > ServiceEntry allows to provide a service **substitution** feature.
1457
- *
1458
- * @example
1459
- * ```ts
1460
- * class A { value = "a"; }
1461
- * class B { value = "b"; }
1462
- * class M { a = $inject(A); }
1463
- *
1464
- * Alepha.create().with({ provide: A, use: B }).get(M).a.value; // "b"
1465
- * ```
1466
- *
1467
- * > **Substitution** is an advanced feature that allows you to replace a service with another service.
1468
- * > It's useful for testing or for providing different implementations of a service.
1469
- * > If you are interested in configuring a service, use Alepha#configure() instead.
1470
- *
1471
- * @param serviceEntry - The service to register in the container.
1472
- * @return Current instance of Alepha.
1473
- */
1523
+ * Registers the specified service in the container.
1524
+ *
1525
+ * - If the service is ALREADY registered, the method does nothing.
1526
+ * - If the service is NOT registered, a new instance is created and registered.
1527
+ *
1528
+ * Method is chainable, so you can register multiple services in a single call.
1529
+ *
1530
+ * > ServiceEntry allows to provide a service **substitution** feature.
1531
+ *
1532
+ * @example
1533
+ * ```ts
1534
+ * class A { value = "a"; }
1535
+ * class B { value = "b"; }
1536
+ * class M { a = $inject(A); }
1537
+ *
1538
+ * Alepha.create().with({ provide: A, use: B }).get(M).a.value; // "b"
1539
+ * ```
1540
+ *
1541
+ * > **Substitution** is an advanced feature that allows you to replace a service with another service.
1542
+ * > It's useful for testing or for providing different implementations of a service.
1543
+ * > If you are interested in configuring a service, use Alepha#configure() instead.
1544
+ *
1545
+ * @param serviceEntry - The service to register in the container.
1546
+ * @return Current instance of Alepha.
1547
+ */
1474
1548
  with<T extends object>(serviceEntry: ServiceEntry<T> | {
1475
1549
  default: ServiceEntry<T>;
1476
1550
  }): this;
1477
1551
  /**
1478
- * Get an instance of the specified service from the container.
1479
- *
1480
- * @see {@link InjectOptions} for the available options.
1481
- */
1552
+ * Get an instance of the specified service from the container.
1553
+ *
1554
+ * @see {@link InjectOptions} for the available options.
1555
+ */
1482
1556
  inject<T extends object>(service: Service<T> | string, opts?: InjectOptions<T>): T;
1483
1557
  /**
1484
- * Applies environment variables to the provided schema and state object.
1485
- *
1486
- * It replaces also all templated $ENV inside string values.
1487
- *
1488
- * @param schema - The schema object to apply environment variables to.
1489
- * @return The schema object with environment variables applied.
1490
- */
1558
+ * Applies environment variables to the provided schema and state object.
1559
+ *
1560
+ * It replaces also all templated $ENV inside string values.
1561
+ *
1562
+ * @param schema - The schema object to apply environment variables to.
1563
+ * @return The schema object with environment variables applied.
1564
+ */
1491
1565
  parseEnv<T extends TObject$1>(schema: T): Static$1<T>;
1492
1566
  /**
1493
- * Get all environment variable schemas and their parsed values.
1494
- *
1495
- * This is useful for DevTools to display all expected environment variables.
1496
- */
1567
+ * Get all environment variable schemas and their parsed values.
1568
+ *
1569
+ * This is useful for DevTools to display all expected environment variables.
1570
+ */
1497
1571
  getEnvSchemas(): Array<{
1498
1572
  schema: TSchema;
1499
1573
  values: Record<string, any>;
1500
1574
  }>;
1501
1575
  /**
1502
- * Dump the current dependency graph of the App.
1503
- *
1504
- * This method returns a record where the keys are the names of the services.
1505
- */
1576
+ * Dump the current dependency graph of the App.
1577
+ *
1578
+ * This method returns a record where the keys are the names of the services.
1579
+ */
1506
1580
  graph(): Record<string, {
1507
1581
  from: string[];
1508
1582
  as?: string[];
@@ -1511,8 +1585,8 @@ declare class Alepha {
1511
1585
  dump(): AlephaDump;
1512
1586
  services<T extends object>(base: Service<T>): Array<T>;
1513
1587
  /**
1514
- * Get all primitives of the specified type.
1515
- */
1588
+ * Get all primitives of the specified type.
1589
+ */
1516
1590
  primitives<TPrimitive extends Primitive>(factory: {
1517
1591
  [KIND]: InstantiableClass<TPrimitive>;
1518
1592
  } | string): Array<TPrimitive>;
@@ -1543,145 +1617,145 @@ interface AlephaDumpEnvVariable {
1543
1617
  */
1544
1618
  interface ServiceDefinition<T extends object = any> {
1545
1619
  /**
1546
- * The instance of the class or type definition.
1547
- * Mostly used for caching / singleton but can be used for other purposes like forcing the instance.
1548
- */
1620
+ * The instance of the class or type definition.
1621
+ * Mostly used for caching / singleton but can be used for other purposes like forcing the instance.
1622
+ */
1549
1623
  instance: T;
1550
1624
  /**
1551
- * List of classes which use this class.
1552
- */
1625
+ * List of classes which use this class.
1626
+ */
1553
1627
  parents: Array<Service | null>;
1554
1628
  }
1555
1629
  interface Env {
1556
1630
  [key: string]: string | boolean | number | undefined;
1557
1631
  /**
1558
- * Optional environment variable that indicates the current environment.
1559
- */
1632
+ * Optional environment variable that indicates the current environment.
1633
+ */
1560
1634
  NODE_ENV?: string;
1561
1635
  /**
1562
- * Optional name of the application.
1563
- */
1636
+ * Optional name of the application.
1637
+ */
1564
1638
  APP_NAME?: string;
1565
1639
  /**
1566
- * Optional root module name.
1567
- */
1640
+ * Optional root module name.
1641
+ */
1568
1642
  MODULE_NAME?: string;
1569
1643
  }
1570
1644
  interface State {
1571
1645
  /**
1572
- * Environment variables for the application.
1573
- */
1646
+ * Environment variables for the application.
1647
+ */
1574
1648
  env?: Readonly<Env>;
1575
1649
  /**
1576
- * Logger instance to be used by the Alepha container.
1577
- *
1578
- * @internal
1579
- */
1650
+ * Logger instance to be used by the Alepha container.
1651
+ *
1652
+ * @internal
1653
+ */
1580
1654
  "alepha.logger"?: LoggerInterface;
1581
1655
  /**
1582
- * If defined, the Alepha container will only register this service and its dependencies.
1583
- *
1584
- * @example
1585
- * ```ts
1586
- * class MigrateCmd {
1587
- * db = $inject(DatabaseProvider);
1588
- * alepha = $inject(Alepha);
1589
- * env = $env(
1590
- * t.object({
1591
- * MIGRATE: t.optional(t.boolean()),
1592
- * }),
1593
- * );
1594
- *
1595
- * constructor() {
1596
- * if (this.env.MIGRATE) {
1597
- * this.alepha.set("alepha.target", MigrateCmd);
1598
- * }
1599
- * }
1600
- *
1601
- * ready = $hook({
1602
- * on: "ready",
1603
- * handler: async () => {
1604
- * if (this.env.MIGRATE) {
1605
- * await this.db.migrate();
1606
- * }
1607
- * },
1608
- * });
1609
- * }
1610
- * ```
1611
- */
1656
+ * If defined, the Alepha container will only register this service and its dependencies.
1657
+ *
1658
+ * @example
1659
+ * ```ts
1660
+ * class MigrateCmd {
1661
+ * db = $inject(DatabaseProvider);
1662
+ * alepha = $inject(Alepha);
1663
+ * env = $env(
1664
+ * t.object({
1665
+ * MIGRATE: t.optional(t.boolean()),
1666
+ * }),
1667
+ * );
1668
+ *
1669
+ * constructor() {
1670
+ * if (this.env.MIGRATE) {
1671
+ * this.alepha.set("alepha.target", MigrateCmd);
1672
+ * }
1673
+ * }
1674
+ *
1675
+ * ready = $hook({
1676
+ * on: "ready",
1677
+ * handler: async () => {
1678
+ * if (this.env.MIGRATE) {
1679
+ * await this.db.migrate();
1680
+ * }
1681
+ * },
1682
+ * });
1683
+ * }
1684
+ * ```
1685
+ */
1612
1686
  "alepha.target"?: Service;
1613
1687
  /**
1614
- * Bind to Vitest 'beforeAll' hook.
1615
- * Used for testing purposes.
1616
- * This is automatically attached if Alepha#create() detects a test environment and global 'beforeAll' is available.
1617
- */
1688
+ * Bind to Vitest 'beforeAll' hook.
1689
+ * Used for testing purposes.
1690
+ * This is automatically attached if Alepha#create() detects a test environment and global 'beforeAll' is available.
1691
+ */
1618
1692
  "alepha.test.beforeAll"?: (run: any) => any;
1619
1693
  /**
1620
- * Bind to Vitest 'afterAll' hook.
1621
- * Used for testing purposes.
1622
- * This is automatically attached if Alepha#create() detects a test environment and global 'afterAll' is available.
1623
- */
1694
+ * Bind to Vitest 'afterAll' hook.
1695
+ * Used for testing purposes.
1696
+ * This is automatically attached if Alepha#create() detects a test environment and global 'afterAll' is available.
1697
+ */
1624
1698
  "alepha.test.afterAll"?: (run: any) => any;
1625
1699
  /**
1626
- * Bind to Vitest 'afterEach' hook.
1627
- * Used for testing purposes.
1628
- * This is automatically attached if Alepha#create() detects a test environment and global 'afterEach' is available.
1629
- */
1700
+ * Bind to Vitest 'afterEach' hook.
1701
+ * Used for testing purposes.
1702
+ * This is automatically attached if Alepha#create() detects a test environment and global 'afterEach' is available.
1703
+ */
1630
1704
  "alepha.test.afterEach"?: (run: any) => any;
1631
1705
  /**
1632
- * Bind to Vitest 'onTestFinished' hook.
1633
- * Used for testing purposes.
1634
- * This is automatically attached if Alepha#create() detects a test environment and global 'onTestFinished' is available.
1635
- */
1706
+ * Bind to Vitest 'onTestFinished' hook.
1707
+ * Used for testing purposes.
1708
+ * This is automatically attached if Alepha#create() detects a test environment and global 'onTestFinished' is available.
1709
+ */
1636
1710
  "alepha.test.onTestFinished"?: (run: any) => any;
1637
1711
  /**
1638
- * List of static assets to be copied to the output directory during the build process.
1639
- *
1640
- * Used for Alepha-based applications that require static assets.
1641
- *
1642
- * See alepha/vite for more details.
1643
- */
1712
+ * List of static assets to be copied to the output directory during the build process.
1713
+ *
1714
+ * Used for Alepha-based applications that require static assets.
1715
+ *
1716
+ * See alepha/vite for more details.
1717
+ */
1644
1718
  "alepha.build.assets"?: Array<string>;
1645
1719
  }
1646
1720
  interface Hooks {
1647
1721
  /**
1648
- * Used for testing purposes.
1649
- */
1722
+ * Used for testing purposes.
1723
+ */
1650
1724
  echo: unknown;
1651
1725
  /**
1652
- * Triggered during the configuration phase. Before the start phase.
1653
- */
1726
+ * Triggered during the configuration phase. Before the start phase.
1727
+ */
1654
1728
  configure: Alepha;
1655
1729
  /**
1656
- * Triggered during the start phase. When `Alepha#start()` is called.
1657
- */
1730
+ * Triggered during the start phase. When `Alepha#start()` is called.
1731
+ */
1658
1732
  start: Alepha;
1659
1733
  /**
1660
- * Triggered during the ready phase. After the start phase.
1661
- */
1734
+ * Triggered during the ready phase. After the start phase.
1735
+ */
1662
1736
  ready: Alepha;
1663
1737
  /**
1664
- * Triggered during the stop phase.
1665
- *
1666
- * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application. (@see `run()` method)
1667
- *
1668
- */
1738
+ * Triggered during the stop phase.
1739
+ *
1740
+ * - Stop should be called after a SIGINT or SIGTERM signal in order to gracefully shutdown the application. (@see `run()` method)
1741
+ *
1742
+ */
1669
1743
  stop: Alepha;
1670
1744
  /**
1671
- * Triggered when a state value is mutated.
1672
- */
1745
+ * Triggered when a state value is mutated.
1746
+ */
1673
1747
  "state:mutate": {
1674
1748
  /**
1675
- * The key of the state that was mutated.
1676
- */
1749
+ * The key of the state that was mutated.
1750
+ */
1677
1751
  key: keyof State;
1678
1752
  /**
1679
- * The new value of the state.
1680
- */
1753
+ * The new value of the state.
1754
+ */
1681
1755
  value: any;
1682
1756
  /**
1683
- * The previous value of the state.
1684
- */
1757
+ * The previous value of the state.
1758
+ */
1685
1759
  prevValue: any;
1686
1760
  };
1687
1761
  }
@@ -1796,8 +1870,8 @@ type TPage<T extends TObject | TRecord> = TObject<{
1796
1870
  */
1797
1871
  type Page<T> = {
1798
1872
  /**
1799
- * Array of items on the current page.
1800
- */
1873
+ * Array of items on the current page.
1874
+ */
1801
1875
  content: T[];
1802
1876
  page: Static<typeof pageMetadataSchema>;
1803
1877
  };
@@ -1805,8 +1879,8 @@ type PageMetadata = Static<typeof pageMetadataSchema>;
1805
1879
  declare module "alepha" {
1806
1880
  interface TypeProvider {
1807
1881
  /**
1808
- * Create a schema for a paginated response.
1809
- */
1882
+ * Create a schema for a paginated response.
1883
+ */
1810
1884
  page<T extends TObject | TRecord>(itemSchema: T): TPage<T>;
1811
1885
  }
1812
1886
  } //# sourceMappingURL=pageSchema.d.ts.map
@@ -1965,14 +2039,14 @@ declare function jsonSchemaToTypeBox(schema: JsonSchemaObject): TSchema$1;
1965
2039
  */
1966
2040
  interface PageRequest {
1967
2041
  /**
1968
- * The page number to retrieve (0-indexed).
1969
- * @default 0
1970
- */
2042
+ * The page number to retrieve (0-indexed).
2043
+ * @default 0
2044
+ */
1971
2045
  page?: number;
1972
2046
  /**
1973
- * The number of items per page.
1974
- * @default 10
1975
- */
2047
+ * The number of items per page.
2048
+ * @default 10
2049
+ */
1976
2050
  size?: number;
1977
2051
  }
1978
2052
  /**
@@ -1984,13 +2058,13 @@ type SortDirection = "asc" | "desc";
1984
2058
  */
1985
2059
  interface SortField {
1986
2060
  /**
1987
- * The field/column name to sort by.
1988
- */
2061
+ * The field/column name to sort by.
2062
+ */
1989
2063
  field: string;
1990
2064
  /**
1991
- * The sort direction.
1992
- * @default "asc"
1993
- */
2065
+ * The sort direction.
2066
+ * @default "asc"
2067
+ */
1994
2068
  direction: SortDirection;
1995
2069
  }
1996
2070
  //#endregion
@@ -2025,17 +2099,17 @@ interface SortField {
2025
2099
  declare const $context: () => ContextPrimitive;
2026
2100
  interface ContextPrimitive {
2027
2101
  /**
2028
- * Alepha instance.
2029
- */
2102
+ * Alepha instance.
2103
+ */
2030
2104
  alepha: Alepha;
2031
2105
  /**
2032
- * Service definition which is creating this primitive.
2033
- * This is NOT the instance but the service definition.
2034
- */
2106
+ * Service definition which is creating this primitive.
2107
+ * This is NOT the instance but the service definition.
2108
+ */
2035
2109
  service?: Service;
2036
2110
  /**
2037
- * Module definition, if any.
2038
- */
2111
+ * Module definition, if any.
2112
+ */
2039
2113
  module?: Service;
2040
2114
  }
2041
2115
  //#endregion
@@ -2104,27 +2178,27 @@ type PageQuery = Static<typeof pageQuerySchema>;
2104
2178
  //#region ../../src/core/interfaces/Run.d.ts
2105
2179
  interface RunOptions {
2106
2180
  /**
2107
- * Environment variables to be used by the application.
2108
- * It will be merged with the current process environment.
2109
- */
2181
+ * Environment variables to be used by the application.
2182
+ * It will be merged with the current process environment.
2183
+ */
2110
2184
  env?: Env;
2111
2185
  /**
2112
- * A callback that will be executed before the application starts.
2113
- */
2186
+ * A callback that will be executed before the application starts.
2187
+ */
2114
2188
  configure?: (alepha: Alepha) => Async<void>;
2115
2189
  /**
2116
- * A callback that will be executed once the application is ready.
2117
- * This is useful for initializing resources or starting background tasks.
2118
- */
2190
+ * A callback that will be executed once the application is ready.
2191
+ * This is useful for initializing resources or starting background tasks.
2192
+ */
2119
2193
  ready?: (alepha: Alepha) => Async<void>;
2120
2194
  /**
2121
- * If true, the application will .stop() after the ready callback is executed.
2122
- * Useful for one-time tasks!
2123
- */
2195
+ * If true, the application will .stop() after the ready callback is executed.
2196
+ * Useful for one-time tasks!
2197
+ */
2124
2198
  once?: boolean;
2125
2199
  /**
2126
- * If true, the application will run in cluster mode.
2127
- */
2200
+ * If true, the application will run in cluster mode.
2201
+ */
2128
2202
  cluster?: boolean;
2129
2203
  }
2130
2204
  //#endregion
@@ -2146,5 +2220,5 @@ declare const AlephaCore: Service<Module>;
2146
2220
  */
2147
2221
  declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => Alepha;
2148
2222
  //#endregion
2149
- export { $atom, $context, $env, $hook, $inject, $module, $use, AbstractClass, Alepha, AlephaCore, AlephaDump, AlephaDumpEnvVariable, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, Atom, AtomOptions, AtomStatic, AtomWithValue, CircularDependencyError, CodecManager, CodecRegisterOptions, CompileOptions, CompiledEventExecutor, ContainerLockedError, ContextPrimitive, DecodeOptions, EncodeOptions, EncodeResult, Encoding, Env, EventManager, FileLike, Format, Hook, HookOptions, HookPrimitive, Hooks, InjectOptions, InjectPrimitive, InstantiableClass, JsonSchemaCodec, JsonSchemaObject, KIND, KeylessCodec, KeylessJsonSchemaCodec, LogLevel, LoggerInterface, MaybePromise, Module, ModulePrimitiveOptions, OPTIONS, Page, PageMetadata, PageQuery, PageRequest, Primitive, PrimitiveArgs, PrimitiveConfig, PrimitiveFactory, PrimitiveFactoryLike, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, SetStateOptions, SortDirection, SortField, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, TAtomObject, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, TPage, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, Type, TypeBoxError, TypeBoxErrorParams, TypeGuard, TypeProvider, Value, WithModule, createPagination, createPrimitive, isClass, isFileLike, isTypeFile, isUUID, jsonSchemaToTypeBox, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
2223
+ export { $atom, $context, $env, $hook, $inject, $module, $use, AbstractClass, Alepha, AlephaCore, AlephaDump, AlephaDumpEnvVariable, AlephaError, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, Atom, AtomOptions, AtomStatic, AtomWithValue, CircularDependencyError, CodecManager, CodecRegisterOptions, CompileOptions, CompiledEventExecutor, ContainerLockedError, ContextPrimitive, DecodeOptions, EncodeOptions, EncodeResult, Encoding, Env, EventManager, FileLike, Format, Hook, HookOptions, HookPrimitive, Hooks, InjectOptions, InjectPrimitive, InstantiableClass, JsonSchemaCodec, JsonSchemaObject, KIND, KeylessCodec, KeylessCodecOptions, KeylessJsonSchemaCodec, LogLevel, LoggerInterface, MaybePromise, Module, ModulePrimitiveOptions, OPTIONS, Page, PageMetadata, PageQuery, PageRequest, Primitive, PrimitiveArgs, PrimitiveConfig, PrimitiveFactory, PrimitiveFactoryLike, RunFunction, SchemaCodec, Service, ServiceEntry, ServiceSubstitution, SetStateOptions, SortDirection, SortField, State, StateManager, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, TAtomObject, type TBigInt, type TBoolean, TFile, type TInteger, type TKeysToIndexer, type TNull, type TNumber, type TNumberOptions, type TObject, type TObjectOptions, type TOptional, type TOptionalAdd, TPage, type TPick, type TProperties, type TRecord, type TSchema, TStream, type TString, type TStringOptions, TTextOptions, type TTuple, type TUnion, type TUnsafe, type TVoid, TextLength, TooLateSubstitutionError, Type, TypeBoxError, TypeBoxErrorParams, TypeGuard, TypeProvider, Value, WithModule, createPagination, createPrimitive, isClass, isFileLike, isTypeFile, isUUID, jsonSchemaToTypeBox, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
2150
2224
  //# sourceMappingURL=index.d.ts.map