alepha 0.14.3 → 0.15.0

package/src/core/Alepha.ts

@@ -165,6 +165,13 @@ export class Alepha {
         ...state.env,
         ...process.env,
       };
+
+      // remove empty env variables
+      for (const key in state.env) {
+        if (state.env[key] === "") {
+          delete (state.env as any)[key];
+        }
+      }
     }
 
     // force production mode when building with vite
@@ -908,6 +915,27 @@ export class Alepha {
     return graph;
   }
 
+  public dump(): AlephaDump {
+    const env: Record<string, AlephaDumpEnvVariable> = {};
+    for (const [schema] of this.cacheEnv.entries()) {
+      const ref = schema as any;
+      for (const [key, value] of Object.entries(ref.properties)) {
+        const prop = value as any;
+        env[key] = {
+          description: prop.description,
+          default: prop.default,
+          required: ref.required?.includes(key) ?? undefined,
+          enum: prop.enum ? ([...prop.enum] as Array<string>) : undefined,
+        };
+      }
+    }
+
+    return {
+      env,
+      providers: this.graph(),
+    };
+  }
+
   public services<T extends object>(base: Service<T>): Array<T> {
     const list: Array<T> = [];
     for (const [key, value] of this.registry.entries()) {
@@ -1012,6 +1040,20 @@ export interface Hook<T extends keyof Hooks = any> {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface AlephaDump {
+  env: Record<string, AlephaDumpEnvVariable>;
+  providers: Record<string, { from: string[]; as?: string[]; module?: string }>;
+}
+
+export interface AlephaDumpEnvVariable {
+  description: string;
+  default?: string;
+  required?: boolean;
+  enum?: Array<string>;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * This is how we store services in the Alepha container.
  */

package/src/core/__tests__/Alepha-graph.spec.ts

@@ -80,6 +80,10 @@ describe("Alepha#graph", () => {
         from: ["StateManager", "CodecManager"],
         module: "alepha.core",
       },
+      KeylessJsonSchemaCodec: {
+        from: ["CodecManager"],
+        module: "alepha.core",
+      },
       CodecManager: {
         from: ["Alepha"],
         module: "alepha.core",

package/src/core/index.shared.ts

@@ -28,6 +28,7 @@ export * from "./providers/AlsProvider.ts";
 export * from "./providers/CodecManager.ts";
 export * from "./providers/EventManager.ts";
 export * from "./providers/JsonSchemaCodec.ts";
+export * from "./providers/KeylessJsonSchemaCodec.ts";
 export * from "./providers/SchemaCodec.ts";
 export * from "./providers/StateManager.ts";
 export * from "./providers/TypeProvider.ts";

package/src/core/index.ts

@@ -11,6 +11,7 @@ import { CodecManager } from "./providers/CodecManager.ts";
 import { EventManager } from "./providers/EventManager.ts";
 import { Json } from "./providers/Json.ts";
 import { JsonSchemaCodec } from "./providers/JsonSchemaCodec.ts";
+import { KeylessJsonSchemaCodec } from "./providers/KeylessJsonSchemaCodec.ts";
 import { SchemaCodec } from "./providers/SchemaCodec.ts";
 import { SchemaValidator } from "./providers/SchemaValidator.ts";
 import { StateManager } from "./providers/StateManager.ts";
@@ -30,6 +31,7 @@ export const AlephaCore = $module({
     AlsProvider,
     Json,
     JsonSchemaCodec,
+    KeylessJsonSchemaCodec,
     SchemaCodec,
     SchemaValidator,
   ],

package/src/core/primitives/$hook.ts

@@ -82,12 +82,16 @@ export class HookPrimitive<T extends keyof Hooks> extends Primitive<
   public called = 0;
 
   protected onInit() {
+    // Store reference to handler to avoid property access in hot path
+    const handler = this.options.handler;
+
     this.alepha.events.on(this.options.on, {
       caller: this.config.service,
       priority: this.options.priority,
-      callback: async (args: any) => {
+      // Return handler result directly - EventManager checks if it's a promise
+      callback: (args: any) => {
         this.called += 1;
-        await this.options.handler(args);
+        return handler(args);
       },
     });
   }

package/src/core/primitives/$module.spec.ts

@@ -51,6 +51,10 @@ describe("$module", () => {
         from: ["StateManager", "CodecManager"],
         module: "alepha.core",
       },
+      KeylessJsonSchemaCodec: {
+        from: ["CodecManager"],
+        module: "alepha.core",
+      },
       CodecManager: {
         from: ["Alepha"],
         module: "alepha.core",

package/src/core/providers/AlsProvider.ts

@@ -25,7 +25,7 @@ export class AlsProvider {
     data.registry ??= new Map();
     data.context ??= this.createContextId();
 
-    return this.als.run(data, callback);
+    return this.als.run({ ...data }, callback);
   }
 
   public exists(): boolean {

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

@@ -44,7 +44,10 @@ describe("CodecManager", () => {
       const codecManager = alepha.codec;
       const customCodec = new CustomCodec();
 
-      codecManager.register("custom", customCodec);
+      codecManager.register({
+        name: "custom",
+        codec: customCodec,
+      });
 
       const retrieved = codecManager.getCodec("custom");
       expect(retrieved).toBe(customCodec);
@@ -74,10 +77,13 @@ describe("CodecManager", () => {
 
       const alepha = Alepha.create();
       const codecManager = alepha.codec;
-      codecManager.register("mock", new MockCodec());
+      codecManager.register({
+        name: "mock",
+        codec: new MockCodec(),
+      });
 
       expect(() => codecManager.getCodec("missing")).toThrow(
-        'Codec "missing" not found. Available codecs: json, mock',
+        'Codec "missing" not found. Available codecs: json, keyless, mock',
       );
     });
   });
@@ -298,7 +304,7 @@ describe("CodecManager", () => {
 
       const alepha = Alepha.create();
       const codecManager = alepha.codec;
-      codecManager.register("custom", new CustomCodec());
+      codecManager.register({ name: "custom", codec: new CustomCodec() });
 
       const schema = t.object({ value: t.text() });
       const result = codecManager.encode(
@@ -513,7 +519,7 @@ describe("CodecManager", () => {
 
       const alepha = Alepha.create();
       const codecManager = alepha.codec;
-      codecManager.register("custom", new CustomCodec());
+      codecManager.register({ name: "custom", codec: new CustomCodec() });
 
       const schema = t.object({ value: t.text() });
       const result = codecManager.decode(
@@ -631,7 +637,7 @@ describe("CodecManager", () => {
         codec = $inject(CodecManager);
 
         constructor() {
-          this.codec.register("custom", new CustomCodec());
+          this.codec.register({ name: "custom", codec: new CustomCodec() });
         }
       }
 

package/src/core/providers/CodecManager.ts

@@ -2,6 +2,7 @@ import type { StaticEncode, TSchema } from "typebox";
 import { AlephaError } from "../errors/AlephaError.ts";
 import { $inject } from "../primitives/$inject.ts";
 import { JsonSchemaCodec } from "./JsonSchemaCodec.ts";
+import { KeylessJsonSchemaCodec } from "./KeylessJsonSchemaCodec.ts";
 import type { SchemaCodec } from "./SchemaCodec.ts";
 import { SchemaValidator, type ValidateOptions } from "./SchemaValidator.ts";
 import type { Static } from "./TypeProvider.ts";
@@ -61,23 +62,34 @@ export interface DecodeOptions {
 export class CodecManager {
   protected readonly codecs: Map<string, SchemaCodec> = new Map();
   protected readonly jsonCodec = $inject(JsonSchemaCodec);
+  protected readonly keylessCodec = $inject(KeylessJsonSchemaCodec);
   protected readonly schemaValidator = $inject(SchemaValidator);
 
   public default = "json";
 
   constructor() {
     // Register default JSON codec
-    this.register(this.default, this.jsonCodec);
+    this.register({
+      name: "json",
+      codec: this.jsonCodec,
+      default: true,
+    });
+
+    // Register keyless JSON codec (smaller, faster decoding)
+    this.register({
+      name: "keyless",
+      codec: this.keylessCodec,
+    });
   }
 
   /**
    * Register a new codec format.
-   *
-   * @param name - The name of the codec (e.g., 'json', 'protobuf')
-   * @param codec - The codec implementation
    */
-  public register(name: string, codec: SchemaCodec): void {
-    this.codecs.set(name, codec);
+  public register(opts: CodecRegisterOptions): void {
+    this.codecs.set(opts.name, opts.codec);
+    if (opts.default) {
+      this.default = opts.name;
+    }
   }
 
   /**
@@ -164,3 +176,11 @@ export class CodecManager {
     return this.schemaValidator.validate(schema, value, options);
   }
 }
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface CodecRegisterOptions {
+  name: string;
+  codec: SchemaCodec;
+  default?: boolean;
+}

package/src/core/providers/EventManager.ts

@@ -3,6 +3,23 @@ import { AlephaError } from "../errors/AlephaError.ts";
 import type { Async } from "../interfaces/Async.ts";
 import type { LoggerInterface } from "../interfaces/LoggerInterface.ts";
 
+/**
+ * Compiled event executor - optimized for hot paths.
+ * Returns void for sync-only chains, Promise<void> for chains with async hooks.
+ */
+export type CompiledEventExecutor<T> = (payload: T) => void | Promise<void>;
+
+/**
+ * Options for compiled event executors.
+ */
+export interface CompileOptions {
+  /**
+   * If true, errors will be caught and logged instead of throwing.
+   * @default false
+   */
+  catch?: boolean;
+}
+
 export class EventManager {
   public logFn?: () => LoggerInterface | undefined;
 
@@ -59,8 +76,114 @@ export class EventManager {
     };
   }
 
+  /**
+   * Compiles an event into an optimized executor function.
+   *
+   * Call this after all hooks are registered (e.g., after Alepha.start()).
+   * The returned function checks each hook's return value and awaits promises.
+   * Returns undefined if all hooks are sync, or a Promise if any hook returns one.
+   *
+   * @example
+   * ```ts
+   * // At startup (after hooks are registered)
+   * const onRequest = alepha.events.compile("server:onRequest", { catch: true });
+   *
+   * // In hot path - only await if promise returned
+   * const result = onRequest({ request, route });
+   * if (result) await result;
+   * ```
+   */
+  public compile<T extends keyof Hooks>(
+    event: T,
+    options: CompileOptions = {},
+  ): CompiledEventExecutor<Hooks[T]> {
+    const hooks = this.events[event];
+
+    // No hooks - return no-op
+    if (!hooks || hooks.length === 0) {
+      return () => {};
+    }
+
+    const catchErrors = options.catch ?? false;
+    const log = this.log;
+
+    // Helper to run remaining hooks sequentially after first async hook
+    const runRemainingAsync = async (
+      startIndex: number,
+      payload: Hooks[T],
+    ): Promise<void> => {
+      for (let i = startIndex; i < hooks.length; i++) {
+        const hook = hooks[i];
+        try {
+          const result = hook.callback(payload);
+          if (result && typeof result === "object" && "then" in result) {
+            if (catchErrors) {
+              await (result as Promise<void>).catch((error) => {
+                log?.error(
+                  `${String(event)}(${hook.caller?.name ?? "unknown"}) ERROR`,
+                  error,
+                );
+              });
+            } else {
+              await result;
+            }
+          }
+        } catch (error) {
+          if (catchErrors) {
+            log?.error(
+              `${String(event)}(${hook.caller?.name ?? "unknown"}) ERROR`,
+              error,
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+    };
+
+    // Return executor that runs sync hooks synchronously, then switches to async
+    // when encountering the first async hook. Returns void if all sync.
+    return (payload: Hooks[T]): void | Promise<void> => {
+      for (let i = 0; i < hooks.length; i++) {
+        const hook = hooks[i];
+        try {
+          const result = hook.callback(payload);
+          if (result && typeof result === "object" && "then" in result) {
+            // Hit an async hook - await it and continue remaining hooks async
+            if (catchErrors) {
+              return (result as Promise<void>)
+                .catch((error) => {
+                  log?.error(
+                    `${String(event)}(${hook.caller?.name ?? "unknown"}) ERROR`,
+                    error,
+                  );
+                })
+                .then(() => runRemainingAsync(i + 1, payload));
+            }
+            return (result as Promise<void>).then(() =>
+              runRemainingAsync(i + 1, payload),
+            );
+          }
+        } catch (error) {
+          if (catchErrors) {
+            log?.error(
+              `${String(event)}(${hook.caller?.name ?? "unknown"}) ERROR`,
+              error,
+            );
+          } else {
+            throw error;
+          }
+        }
+      }
+      // All hooks were sync - return void
+    };
+  }
+
   /**
    * Emits the specified event with the given payload.
+   *
+   * For hot paths (like HTTP request handling), use compile() instead
+   * to get an optimized executor.
    */
   public async emit<T extends keyof Hooks>(
     func: T,
@@ -87,36 +210,65 @@ export class EventManager {
       catch?: boolean;
     } = {},
   ): Promise<void> {
+    // Fast path: no listeners for this event
+    const events = this.events[func];
+    if (!events || events.length === 0) {
+      return;
+    }
+
+    // Fast path: single listener, no logging, no reverse
+    if (events.length === 1 && !options.log && !options.reverse) {
+      const hook = events[0];
+      try {
+        const result = hook.callback(payload);
+        if (result && typeof result === "object" && "then" in result) {
+          await result;
+        }
+      } catch (error) {
+        if (options.catch) {
+          this.log?.error(
+            `${String(func)}(${hook.caller?.name ?? "unknown"}) ERROR`,
+            error,
+          );
+          return;
+        }
+        throw error;
+      }
+      return;
+    }
+
     const ctx: any = {};
 
     if (options.log) {
-      ctx.now = Date.now();
-      this.log?.trace(`${func} ...`);
+      ctx.now = performance.now();
+      this.log?.trace(`${String(func)} ...`);
     }
 
-    let events = this.events[func] ?? [];
-
+    let eventList = events;
     if (options.reverse) {
-      events = events.toReversed();
+      eventList = events.toReversed();
     }
 
-    for (const hook of events) {
+    for (const hook of eventList) {
       const name = hook.caller?.name ?? "unknown";
       if (options.log) {
-        ctx.now2 = Date.now();
-        this.log?.trace(`${func}(${name}) ...`);
+        ctx.now2 = performance.now();
+        this.log?.trace(`${String(func)}(${name}) ...`);
       }
 
       try {
-        await hook.callback(payload);
+        const result = hook.callback(payload);
+        if (result && typeof result === "object" && "then" in result) {
+          await result;
+        }
       } catch (error) {
         if (options.catch) {
-          this.log?.error(`${func}(${name}) ERROR`, error);
+          this.log?.error(`${String(func)}(${name}) ERROR`, error);
           continue;
         }
         if (options.log) {
           throw new AlephaError(
-            `Failed during '${func}()' hook for service: ${name}`,
+            `Failed during '${String(func)}()' hook for service: ${name}`,
             { cause: error },
           );
         }
@@ -124,12 +276,16 @@ export class EventManager {
       }
 
       if (options.log) {
-        this.log?.debug(`${func}(${name}) OK [${Date.now() - ctx.now2}ms]`);
+        this.log?.debug(
+          `${String(func)}(${name}) OK [${(performance.now() - ctx.now2).toFixed(1)}ms]`,
+        );
       }
     }
 
     if (options.log) {
-      this.log?.debug(`${func} OK [${Date.now() - ctx.now}ms]`);
+      this.log?.debug(
+        `${String(func)} OK [${(performance.now() - ctx.now).toFixed(1)}ms]`,
+      );
     }
   }
 }