alepha 0.15.0 → 0.15.2

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/primitives/$module.ts

@@ -4,6 +4,7 @@ import { MODULE } from "../constants/MODULE.ts";
 import { AlephaError } from "../errors/AlephaError.ts";
 import type { PrimitiveFactoryLike } from "../helpers/primitive.ts";
 import type { Service } from "../interfaces/Service.ts";
+import type { Atom } from "./$atom.ts";
 
 /**
  * Wrap Services and Primitives into a Module.
@@ -69,6 +70,12 @@ export const $module = <T extends object = {}>(
     options = options;
 
     register(alepha: Alepha): void {
+      if (options.atoms) {
+        for (const atom of options.atoms) {
+          alepha.store.register(atom);
+        }
+      }
+
       if (typeof options.register === "function") {
         options.register(alepha);
         return;
@@ -134,6 +141,11 @@ export interface ModulePrimitiveOptions {
    * Again, if you declare 'register', you must handle the registration of ALL services manually.
    */
   register?: (alepha: Alepha) => void;
+
+  /**
+   * List of atoms to register in the module.
+   */
+  atoms?: Array<Atom<any>>;
 }
 
 /**

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/core/providers/KeylessJsonSchemaCodec.spec.ts

@@ -1,5 +1,6 @@
 import { Alepha, t } from "alepha";
 import { describe, test } from "vitest";
+import { KeylessJsonSchemaCodec } from "./KeylessJsonSchemaCodec.ts";
 
 describe("KeylessJsonSchemaCodec", () => {
   describe("Basic types", () => {
@@ -618,4 +619,260 @@ describe("KeylessJsonSchemaCodec", () => {
       expect(keylessSize).toBeLessThan(jsonSize);
     });
   });
+
+  describe("Safe Mode (Interpreted)", () => {
+    test("should work correctly in safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      // Force safe mode (no Function compilation)
+      codec.configure({ useFunctionCompilation: false });
+
+      const schema = t.object({
+        name: t.text(),
+        age: t.integer(),
+        active: t.boolean(),
+      });
+
+      const data = {
+        name: "Alice",
+        age: 30,
+        active: true,
+      };
+
+      const encoded = codec.encodeToString(schema, data);
+      expect(encoded).toBe('["Alice",30,true]');
+
+      const decoded = codec.decode(schema, encoded);
+      expect(decoded).toEqual(data);
+    });
+
+    test("should handle nested objects in safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      codec.configure({ useFunctionCompilation: false });
+
+      const schema = t.object({
+        user: t.object({
+          name: t.text(),
+          profile: t.object({
+            bio: t.text(),
+            age: t.integer(),
+          }),
+        }),
+      });
+
+      const data = {
+        user: {
+          name: "Alice",
+          profile: {
+            bio: "Developer",
+            age: 30,
+          },
+        },
+      };
+
+      const encoded = codec.encodeToString(schema, data);
+      expect(encoded).toBe('[["Alice",["Developer",30]]]');
+
+      const decoded = codec.decode(schema, encoded);
+      expect(decoded).toEqual(data);
+    });
+
+    test("should handle arrays of objects in safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      codec.configure({ useFunctionCompilation: false });
+
+      const schema = t.object({
+        users: t.array(
+          t.object({
+            name: t.text(),
+            age: t.integer(),
+          }),
+        ),
+      });
+
+      const data = {
+        users: [
+          { name: "Alice", age: 30 },
+          { name: "Bob", age: 25 },
+        ],
+      };
+
+      const encoded = codec.encodeToString(schema, data);
+      const decoded = codec.decode(schema, encoded);
+      expect(decoded).toEqual(data);
+    });
+
+    test("should handle optional fields in safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      codec.configure({ useFunctionCompilation: false });
+
+      const schema = t.object({
+        name: t.text(),
+        bio: t.optional(t.text()),
+      });
+
+      // With optional field
+      const dataWithBio = { name: "Alice", bio: "Developer" };
+      const encodedWith = codec.encodeToString(schema, dataWithBio);
+      const decodedWith = codec.decode(schema, encodedWith);
+      expect(decodedWith).toEqual(dataWithBio);
+
+      // Without optional field
+      const dataWithoutBio = { name: "Bob" };
+      const encodedWithout = codec.encodeToString(schema, dataWithoutBio);
+      const decodedWithout = codec.decode<{ name: string; bio?: string }>(
+        schema,
+        encodedWithout,
+      );
+      expect(decodedWithout.name).toBe("Bob");
+      expect(decodedWithout.bio).toBeUndefined();
+    });
+
+    test("should handle nullable fields in safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      codec.configure({ useFunctionCompilation: false });
+
+      const schema = t.object({
+        name: t.text(),
+        deletedAt: t.nullable(t.datetime()),
+      });
+
+      // With null value
+      const dataNull = { name: "Alice", deletedAt: null };
+      const encodedNull = codec.encodeToString(schema, dataNull);
+      const decodedNull = codec.decode<{
+        name: string;
+        deletedAt: string | null;
+      }>(schema, encodedNull);
+      expect(decodedNull.deletedAt).toBeNull();
+
+      // With non-null value
+      const dataValue = { name: "Bob", deletedAt: "2024-01-15T10:00:00Z" };
+      const encodedValue = codec.encodeToString(schema, dataValue);
+      const decodedValue = codec.decode(schema, encodedValue);
+      expect(decodedValue).toEqual(dataValue);
+    });
+  });
+
+  describe("Compiled Mode (Function)", () => {
+    test("should work correctly in compiled mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      // Force compiled mode
+      codec.configure({ useFunctionCompilation: true });
+
+      const schema = t.object({
+        name: t.text(),
+        age: t.integer(),
+        active: t.boolean(),
+      });
+
+      const data = {
+        name: "Alice",
+        age: 30,
+        active: true,
+      };
+
+      const encoded = codec.encodeToString(schema, data);
+      expect(encoded).toBe('["Alice",30,true]');
+
+      const decoded = codec.decode(schema, encoded);
+      expect(decoded).toEqual(data);
+    });
+
+    test("should produce same results as safe mode", async ({ expect }) => {
+      const alepha = Alepha.create();
+
+      const codecSafe = alepha.inject(KeylessJsonSchemaCodec);
+      codecSafe.configure({ useFunctionCompilation: false });
+
+      // Create a second Alepha instance for the compiled codec
+      const alepha2 = Alepha.create();
+      const codecCompiled = alepha2.inject(KeylessJsonSchemaCodec);
+      codecCompiled.configure({ useFunctionCompilation: true });
+
+      const schema = t.object({
+        user: t.object({
+          name: t.text(),
+          age: t.integer(),
+        }),
+        tags: t.array(t.text()),
+        active: t.boolean(),
+      });
+
+      const data = {
+        user: { name: "Alice", age: 30 },
+        tags: ["dev", "typescript"],
+        active: true,
+      };
+
+      const encodedSafe = codecSafe.encodeToString(schema, data);
+      const encodedCompiled = codecCompiled.encodeToString(schema, data);
+
+      // Both modes should produce the same output
+      expect(encodedSafe).toBe(encodedCompiled);
+
+      const decodedSafe = codecSafe.decode(schema, encodedSafe);
+      const decodedCompiled = codecCompiled.decode(schema, encodedCompiled);
+
+      // Both modes should decode to the same result
+      expect(decodedSafe).toEqual(data);
+      expect(decodedCompiled).toEqual(data);
+    });
+  });
+
+  describe("Configuration", () => {
+    test("should allow configuring options", async ({ expect }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      // Configure all options
+      codec.configure({
+        useFunctionCompilation: false,
+        maxArrayLength: 100,
+        maxStringLength: 1000,
+        maxDepth: 10,
+      });
+
+      // Test that configuration works by encoding/decoding
+      const schema = t.object({ name: t.text() });
+      const data = { name: "test" };
+
+      const encoded = codec.encodeToString(schema, data);
+      const decoded = codec.decode(schema, encoded);
+
+      expect(decoded).toEqual(data);
+    });
+
+    test("should clear cache when compilation mode changes", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create();
+      const codec = alepha.inject(KeylessJsonSchemaCodec);
+
+      const schema = t.object({ name: t.text() });
+      const data = { name: "test" };
+
+      // Use compiled mode first
+      codec.configure({ useFunctionCompilation: true });
+      const encoded1 = codec.encodeToString(schema, data);
+
+      // Switch to safe mode (cache should be cleared)
+      codec.configure({ useFunctionCompilation: false });
+      const encoded2 = codec.encodeToString(schema, data);
+
+      // Both should produce the same result
+      expect(encoded1).toBe(encoded2);
+    });
+  });
 });