alepha 0.15.1 → 0.15.3

package/src/core/helpers/jsonSchemaToTypeBox.ts

@@ -32,8 +32,11 @@ export interface JsonSchemaObject {
   minItems?: number;
   maxItems?: number;
   uniqueItems?: boolean;
-  // TypeBox internal markers (pass through)
-  "~kind"?: string;
+  // Alepha text options (trim, lowercase)
+  "~options"?: {
+    trim?: boolean;
+    lowercase?: boolean;
+  };
   // Not supported
   oneOf?: JsonSchemaObject[];
   anyOf?: JsonSchemaObject[];
@@ -55,11 +58,13 @@ export interface JsonSchemaObject {
  * - Nested objects with required/optional properties
  * - Arrays with item schemas
  * - Common validation options: minLength, maxLength, minimum, maximum, pattern
+ * - anyOf/oneOf/allOf with nullable patterns (e.g., `anyOf: [type, null]` → `t.nullable(type)`)
+ * - Alepha ~options (trim, lowercase) pass-through
  *
  * **Not supported:**
- * - oneOf, anyOf, allOf, not (composition schemas)
  * - $ref (references)
  * - additionalProperties, patternProperties
+ * - Complex composition schemas (multiple non-null types in anyOf/oneOf/allOf)
  *
  * @param schema - JSON Schema object to convert
  * @returns TypeBox TSchema
@@ -85,12 +90,7 @@ export interface JsonSchemaObject {
  * // })
  * ```
  */
-export function jsonSchemaToTypeBox(schema: JsonSchemaObject): TSchema {
-  // If it already has TypeBox marker, return as-is
-  if (schema["~kind"]) {
-    return schema as unknown as TSchema;
-  }
-
+export function jsonSchemaToTypeBox(schema: JsonSchemaObject): any {
   // Handle const (literal)
   if (schema.const !== undefined) {
     return t.const(schema.const as string | number | boolean);
@@ -115,6 +115,53 @@ export function jsonSchemaToTypeBox(schema: JsonSchemaObject): TSchema {
     );
   }
 
+  // Handle anyOf (typically used for nullable types: anyOf: [type, null])
+  if (schema.anyOf && Array.isArray(schema.anyOf)) {
+    const nullSchema = schema.anyOf.find((s) => s.type === "null");
+    const nonNullSchemas = schema.anyOf.filter((s) => s.type !== "null");
+
+    // If anyOf is [someType, null], convert to t.nullable(someType)
+    if (nullSchema && nonNullSchemas.length === 1) {
+      const converted = jsonSchemaToTypeBox(nonNullSchemas[0]);
+      return t.nullable(converted);
+    }
+
+    // For other anyOf cases, create a union
+    return t.union(schema.anyOf.map((s) => jsonSchemaToTypeBox(s)));
+  }
+
+  // Handle allOf (merge schemas)
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    const nullSchema = schema.allOf.find((s) => s.type === "null");
+    const nonNullSchemas = schema.allOf.filter((s) => s.type !== "null");
+
+    // If allOf includes null, convert to nullable
+    if (nullSchema && nonNullSchemas.length === 1) {
+      const converted = jsonSchemaToTypeBox(nonNullSchemas[0]);
+      return t.nullable(converted);
+    }
+
+    // For other allOf cases, merge the first non-null schema (simplified)
+    if (nonNullSchemas.length > 0) {
+      return jsonSchemaToTypeBox(nonNullSchemas[0]);
+    }
+  }
+
+  // Handle oneOf (similar to anyOf)
+  if (schema.oneOf && Array.isArray(schema.oneOf)) {
+    const nullSchema = schema.oneOf.find((s) => s.type === "null");
+    const nonNullSchemas = schema.oneOf.filter((s) => s.type !== "null");
+
+    // If oneOf is [someType, null], convert to t.nullable(someType)
+    if (nullSchema && nonNullSchemas.length === 1) {
+      const converted = jsonSchemaToTypeBox(nonNullSchemas[0]);
+      return t.nullable(converted);
+    }
+
+    // For other oneOf cases, create a union
+    return t.union(schema.oneOf.map((s) => jsonSchemaToTypeBox(s)));
+  }
+
   // Handle type
   const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
 
@@ -158,7 +205,7 @@ function filterUndefined<T extends Record<string, unknown>>(
  * Convert JSON Schema string type to TypeBox.
  */
 function convertString(schema: JsonSchemaObject): TSchema {
-  const options: TStringOptions = filterUndefined({
+  const baseOptions: TStringOptions = filterUndefined({
     title: schema.title,
     description: schema.description,
     default: schema.default as string,
@@ -167,6 +214,11 @@ function convertString(schema: JsonSchemaObject): TSchema {
     pattern: schema.pattern,
   });
 
+  // Preserve ~options if present (for t.text() compatibility)
+  const options: TStringOptions = schema["~options"]
+    ? { ...baseOptions, "~options": schema["~options"] }
+    : baseOptions;
+
   switch (schema.format) {
     case "email":
       return t.email(options);

package/src/core/index.shared.ts

@@ -27,6 +27,7 @@ export * from "./primitives/$use.ts";
 export * from "./providers/AlsProvider.ts";
 export * from "./providers/CodecManager.ts";
 export * from "./providers/EventManager.ts";
+export * from "./providers/Json.ts";
 export * from "./providers/JsonSchemaCodec.ts";
 export * from "./providers/KeylessJsonSchemaCodec.ts";
 export * from "./providers/SchemaCodec.ts";

package/src/core/index.ts

@@ -22,6 +22,26 @@ export * from "./index.shared.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | epic | stable |
+ *
+ * Foundation of the entire framework with dependency injection and lifecycle management.
+ *
+ * **Features:**
+ * - Dependency injection for services
+ * - Service substitution/mocking
+ * - Type-safe environment variable loading with TypeBox schemas
+ * - Lifecycle hooks (start, stop, log, etc.)
+ * - Module definitions and composition
+ * - Request-scoped context access via Async Local Storage (ALS)
+ * - Reactive state management with atoms
+ * - Cluster mode with automatic worker forking
+ * - Full TypeScript generics and type inference
+ *
+ * @module alepha.core
+ */
 export const AlephaCore = $module({
   name: "alepha.core",
   services: [

package/src/core/providers/EventManager.spec.ts

@@ -285,77 +285,6 @@ describe("EventManager", () => {
     });
   });
 
-  describe("reverse execution order", () => {
-    it("should execute hooks in reverse order when reverse option is true", async () => {
-      const eventManager = new EventManager();
-      const order: number[] = [];
-
-      eventManager.on("echo", async () => {
-        order.push(1);
-      });
-      eventManager.on("echo", async () => {
-        order.push(2);
-      });
-      eventManager.on("echo", async () => {
-        order.push(3);
-      });
-
-      await eventManager.emit("echo", {}, { reverse: true });
-
-      expect(order).toEqual([3, 2, 1]);
-    });
-
-    it("should reverse priorities correctly", async () => {
-      const eventManager = new EventManager();
-      const order: string[] = [];
-
-      eventManager.on("echo", {
-        callback: async () => {
-          order.push("first");
-        },
-        priority: "first",
-      });
-      eventManager.on("echo", async () => {
-        order.push("normal");
-      });
-      eventManager.on("echo", {
-        callback: async () => {
-          order.push("last");
-        },
-        priority: "last",
-      });
-
-      await eventManager.emit("echo", {}, { reverse: true });
-
-      // Reversed: last -> normal -> first
-      expect(order).toEqual(["last", "normal", "first"]);
-    });
-
-    it("should work with stop lifecycle event", async () => {
-      const alepha = Alepha.create();
-      const order: string[] = [];
-
-      alepha.events.on("start", async () => {
-        order.push("start-1");
-      });
-      alepha.events.on("start", async () => {
-        order.push("start-2");
-      });
-      alepha.events.on("stop", async () => {
-        order.push("stop-1");
-      });
-      alepha.events.on("stop", async () => {
-        order.push("stop-2");
-      });
-
-      await alepha.start();
-      await alepha.stop();
-
-      // Start should be in order, stop should be reversed
-      expect(order).toEqual(["start-1", "start-2", "stop-2", "stop-1"]);
-    });
-  });
-
   describe("error handling", () => {
     it("should throw error when callback throws", async () => {
       const eventManager = new EventManager();

package/src/core/providers/EventManager.ts

@@ -189,13 +189,6 @@ export class EventManager {
     func: T,
     payload: Hooks[T],
     options: {
-      /**
-       * If true, the hooks will be executed in reverse order.
-       * This is useful for "stop" hooks that should be executed in reverse order.
-       *
-       * @default false
-       */
-      reverse?: boolean;
       /**
        * If true, the hooks will be logged with their execution time.
        *
@@ -216,8 +209,8 @@ export class EventManager {
       return;
     }
 
-    // Fast path: single listener, no logging, no reverse
-    if (events.length === 1 && !options.log && !options.reverse) {
+    // Fast path: single listener, no logging
+    if (events.length === 1 && !options.log) {
       const hook = events[0];
       try {
         const result = hook.callback(payload);
@@ -244,12 +237,7 @@ export class EventManager {
       this.log?.trace(`${String(func)} ...`);
     }
 
-    let eventList = events;
-    if (options.reverse) {
-      eventList = events.toReversed();
-    }
-
-    for (const hook of eventList) {
+    for (const hook of events) {
       const name = hook.caller?.name ?? "unknown";
       if (options.log) {
         ctx.now2 = performance.now();

package/src/core/providers/Json.ts

@@ -4,18 +4,6 @@
  * Used across the codebase via dependency injection.
  */
 export class Json {
-  public stringify(
-    value: any,
-    replacer?: (this: any, key: string, value: any) => any,
-    space?: string | number,
-  ): string {
-    return JSON.stringify(value, replacer, space);
-  }
-
-  public parse(
-    text: string,
-    reviver?: (this: any, key: string, value: any) => any,
-  ) {
-    return JSON.parse(text, reviver);
-  }
+  stringify = JSON.stringify;
+  parse = JSON.parse;
 }

package/src/datetime/index.ts

@@ -7,6 +7,21 @@ export * from "./providers/DateTimeProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | standard | stable |
+ *
+ * Date and time operations.
+ *
+ * **Features:**
+ * - Recurring interval definitions
+ * - Duration parsing (ISO 8601, human-readable)
+ * - Timezone support
+ * - Dayjs integration
+ *
+ * @module alepha.datetime
+ */
 export const AlephaDateTime = $module({
   name: "alepha.datetime",
   primitives: [$interval],

package/src/email/index.ts

@@ -36,13 +36,18 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides email sending capabilities for Alepha applications with multiple provider backends.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | stable |
  *
- * The email module enables declarative email sending through the `$email` primitive, allowing you to send
- * emails through different providers: memory (for testing), local file system, or SMTP via Nodemailer.
- * It supports HTML email content and automatic provider selection based on environment configuration.
+ * Email delivery with template support.
+ *
+ * **Features:**
+ * - Send emails with templates
+ * - Multiple recipients
+ * - SMTP via Nodemailer
+ * - Local file provider for development
  *
- * @see {@link EmailProvider}
  * @module alepha.email
  */
 export const AlephaEmail = $module({

package/src/email/providers/LocalEmailProvider.spec.ts

@@ -1,5 +1,5 @@
 import { Alepha } from "alepha";
-import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/file";
+import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/system";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { EmailError } from "../errors/EmailError.ts";
 import {

package/src/email/providers/LocalEmailProvider.ts

@@ -1,6 +1,6 @@
 import { $atom, $hook, $inject, $use, type Static, t } from "alepha";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
+import { FileSystemProvider } from "alepha/system";
 import { EmailError } from "../errors/EmailError.ts";
 import type { EmailProvider, EmailSendOptions } from "./EmailProvider.ts";
 

package/src/fake/__tests__/keyName.example.ts

@@ -2,7 +2,7 @@ import { t } from "alepha";
 import { FakeProvider } from "../providers/FakeProvider.ts";
 
 // Example showing how key names influence generated data
-const fake = new FakeProvider({ seed: 12345 });
+const fake = new FakeProvider();
 
 const userSchema = t.object({
   id: t.uuid(),

package/src/fake/__tests__/keyName.spec.ts

@@ -4,7 +4,7 @@ import { FakeProvider } from "../providers/FakeProvider.ts";
 
 describe("FakeProvider - Key Name Intelligence", () => {
   test("generates contextual data based on key names", ({ expect }) => {
-    const fake = new FakeProvider({ seed: 12345 });
+    const fake = new FakeProvider();
     const schema = t.object({
       firstName: t.text(),
       lastName: t.text(),
@@ -39,7 +39,7 @@ describe("FakeProvider - Key Name Intelligence", () => {
   });
 
   test("format takes precedence over key name", ({ expect }) => {
-    const fake = new FakeProvider({ seed: 12345 });
+    const fake = new FakeProvider();
     const schema = t.object({
       // Even though key is "email", format: uuid should generate UUID
       email: t.uuid(),
@@ -59,7 +59,7 @@ describe("FakeProvider - Key Name Intelligence", () => {
   });
 
   test("enum values ignore key name context", ({ expect }) => {
-    const fake = new FakeProvider({ seed: 12345 });
+    const fake = new FakeProvider();
     const schema = t.object({
       // Even though key is "email", enum should pick from values
       email: t.enum(["user1", "user2", "user3"]),
@@ -73,7 +73,7 @@ describe("FakeProvider - Key Name Intelligence", () => {
   });
 
   test("generates realistic user profiles", ({ expect }) => {
-    const fake = new FakeProvider({ seed: 67890 });
+    const fake = new FakeProvider().configure({ seed: 67890 });
     const userSchema = t.object({
       firstName: t.shortText(),
       lastName: t.shortText(),
@@ -121,7 +121,7 @@ describe("FakeProvider - Key Name Intelligence", () => {
   });
 
   test("numeric key names influence generation", ({ expect }) => {
-    const fake = new FakeProvider({ seed: 12345 });
+    const fake = new FakeProvider();
     const schema = t.object({
       age: t.integer(),
       year: t.integer(),

package/src/fake/index.ts

@@ -9,14 +9,17 @@ export * from "./providers/FakeProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides fake data generation capabilities for Alepha applications using faker.js and TypeBox schemas.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | rare | stable |
  *
- * The fake module enables declarative fake data generation from TypeBox schemas, making it easy to create
- * realistic test data, seed databases, or generate mock responses. It intelligently uses property key names
- * to generate contextually appropriate data (e.g., "email" generates an email address, "firstName" generates
- * a first name).
+ * Test data generation with Faker.js.
+ *
+ * **Features:**
+ * - TypeBox schema-based generation
+ * - Context-aware field generation (email field -> email address)
+ * - Test data seeding
  *
- * @see {@link FakeProvider}
  * @module alepha.fake
  */
 export const AlephaFake = $module({