alepha 0.14.2 → 0.14.4

package/src/command/primitives/$command.ts

@@ -105,12 +105,6 @@ export interface CommandPrimitiveOptions<
    */
   args?: A;
 
-  /**
-   * If false, skip summary message at the end of the command execution.
-   * Summary will display only if ({ run }) method calls were made.
-   */
-  summary?: boolean;
-
   /**
    * Marks this command as the root command.
    * Equivalent to setting name to an empty string "".

package/src/command/providers/CliProvider.ts

@@ -14,6 +14,7 @@ import {
   t,
 } from "alepha";
 import { $logger } from "alepha/logger";
+import { ConsoleColorProvider } from "../../logger/providers/ConsoleColorProvider.ts";
 import { CommandError } from "../errors/CommandError.ts";
 import { Asker } from "../helpers/Asker.ts";
 import { EnvUtils } from "../helpers/EnvUtils.ts";
@@ -80,6 +81,7 @@ export class CliProvider {
   protected readonly env = $env(envSchema);
   protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
+  protected readonly color = $inject(ConsoleColorProvider);
   protected readonly runner = $inject(Runner);
   protected readonly asker = $inject(Asker);
   protected readonly envUtils = $inject(EnvUtils);
@@ -235,9 +237,7 @@ export class CliProvider {
         await hook.options.handler(args as CommandHandlerArgs<TObject>);
       }
 
-      if (command.options.summary !== false) {
-        runner.summary();
-      }
+      runner.end();
 
       this.log.debug(`Command '${command.name}' executed successfully.`);
     });
@@ -708,17 +708,19 @@ export class CliProvider {
 
   public printHelp(command?: CommandPrimitive<any>): void {
     const cliName = this.name || "cli";
+    const c = this.color;
     this.log.info(""); // Newline
 
     if (command?.name) {
       // Command-specific help
       const hasChildren = command.hasChildren;
       const argsUsage = hasChildren
-        ? " <command>"
-        : this.generateArgsUsage(command.options.args);
+        ? ` ${c.set("CYAN", "<command>")}`
+        : this.generateColoredArgsUsage(command.options.args);
       const commandPath = this.getCommandPath(command);
-      const usage = `${cliName} ${commandPath}${argsUsage}`.trim();
-      this.log.info(`Usage: \`${usage}\``);
+      const usage =
+        `${c.set("GREY_LIGHT", cliName)} ${c.set("CYAN", commandPath)}${argsUsage}`.trim();
+      this.log.info(`${c.set("WHITE_BOLD", "Usage:")} ${usage}`);
 
       if (command.options.description) {
         this.log.info(``);
@@ -728,7 +730,7 @@ export class CliProvider {
       // Show subcommands if this is a parent command
       if (hasChildren) {
         this.log.info("");
-        this.log.info("Commands:");
+        this.log.info(c.set("WHITE_BOLD", "Commands:"));
         const maxSubCmdLength = this.getMaxChildCmdLength(command.children);
 
         for (const child of command.children) {
@@ -738,14 +740,18 @@ export class CliProvider {
           const childArgsUsage = this.generateArgsUsage(child.options.args);
           const cmdStr = [child.name, ...child.aliases].join(", ");
           const fullCmdStr = `${cmdStr}${childArgsUsage}`;
+          const coloredCmd = `${c.set("GREY_LIGHT", cliName)} ${c.set("CYAN", command.name)} ${c.set("CYAN", fullCmdStr)}`;
+          const padding = " ".repeat(
+            Math.max(0, maxSubCmdLength - fullCmdStr.length),
+          );
           this.log.info(
-            `    ${cliName} ${command.name} ${fullCmdStr.padEnd(maxSubCmdLength)} # ${child.options.description ?? ""}`,
+            `    ${coloredCmd}${padding}  ${child.options.description ?? ""}`,
           );
         }
       }
 
       this.log.info("");
-      this.log.info("Flags:");
+      this.log.info(c.set("WHITE_BOLD", "Flags:"));
 
       const flags = [
         ...Object.entries(command.flags.properties).map(([key, value]) => ({
@@ -778,23 +784,27 @@ export class CliProvider {
         const flagStr = (Array.isArray(aliases) ? aliases : [aliases])
           .map((a: string) => (a.length === 1 ? `-${a}` : `--${a}`))
           .join(", ");
-        this.log.info(
-          `    ${flagStr.padEnd(maxFlagLength)} # ${description ?? ""}`,
-        );
+        const coloredFlag = c.set("GREY_LIGHT", flagStr);
+        const padding = " ".repeat(Math.max(0, maxFlagLength - flagStr.length));
+        this.log.info(`    ${coloredFlag}${padding}  ${description ?? ""}`);
       }
 
       // Show environment variables if defined
       const envVars = Object.entries(command.env.properties);
       if (envVars.length > 0) {
         this.log.info("");
-        this.log.info("Env:");
+        this.log.info(c.set("WHITE_BOLD", "Env:"));
         const maxEnvLength = Math.max(...envVars.map(([key]) => key.length));
         for (const [key, schema] of envVars) {
           const isOptional = t.schema.isOptional(schema as TSchema);
           const description = (schema as any).description ?? "";
-          const optionalStr = isOptional ? " (optional)" : "";
+          const optionalStr = isOptional
+            ? c.set("GREY_DARK", " (optional)")
+            : c.set("RED", " (required)");
+          const coloredKey = c.set("CYAN", key);
+          const padding = " ".repeat(Math.max(0, maxEnvLength - key.length));
           this.log.info(
-            `    ${key.padEnd(maxEnvLength)} # ${description}${optionalStr}`,
+            `    ${coloredKey}${padding}  ${description}${optionalStr}`,
           );
         }
       }
@@ -802,30 +812,34 @@ export class CliProvider {
       // general help
       this.log.info(this.description || "Available commands:");
       this.log.info("");
-      this.log.info("Commands:");
+      this.log.info(c.set("WHITE_BOLD", "Commands:"));
 
       // Get top-level commands (commands that are not children of other commands)
       const topLevelCommands = this.getTopLevelCommands();
       const maxCmdLength = this.getMaxCmdLength(topLevelCommands);
 
-      for (const command of topLevelCommands) {
+      for (const cmd of topLevelCommands) {
         // skip root command and hooks in list
-        if (command.name === "" || command.options.hide) {
+        if (cmd.name === "" || cmd.options.hide) {
           continue;
         }
 
-        const cmdStr = [command.name, ...command.aliases].join(", ");
-        const argsUsage = command.hasChildren
+        const cmdStr = [cmd.name, ...cmd.aliases].join(", ");
+        const argsUsage = cmd.hasChildren
           ? " <command>"
-          : this.generateArgsUsage(command.options.args);
+          : this.generateArgsUsage(cmd.options.args);
         const fullCmdStr = `${cmdStr}${argsUsage}`;
+        const coloredCmd = `${c.set("GREY_LIGHT", cliName)} ${c.set("CYAN", fullCmdStr)}`;
+        const padding = " ".repeat(
+          Math.max(0, maxCmdLength - fullCmdStr.length),
+        );
         this.log.info(
-          `    ${cliName} ${fullCmdStr.padEnd(maxCmdLength)} # ${command.options.description ?? ""}`,
+          `    ${coloredCmd}${padding}  ${cmd.options.description ?? ""}`,
         );
       }
 
       this.log.info("");
-      this.log.info("Flags:");
+      this.log.info(c.set("WHITE_BOLD", "Flags:"));
 
       // In general help, also show root command flags
       const rootCommand = this.commands.find((cmd) => cmd.name === "");
@@ -851,14 +865,48 @@ export class CliProvider {
         const flagStr = aliases
           .map((a) => (a.length === 1 ? `-${a}` : `--${a}`))
           .join(", ");
-        this.log.info(
-          `    ${flagStr.padEnd(maxFlagLength)} # ${description ?? ""}`,
-        );
+        const coloredFlag = c.set("GREY_LIGHT", flagStr);
+        const padding = " ".repeat(Math.max(0, maxFlagLength - flagStr.length));
+        this.log.info(`    ${coloredFlag}${padding}  ${description ?? ""}`);
       }
     }
     this.log.info(""); // Newline
   }
 
+  /**
+   * Generate colored args usage string for help display.
+   */
+  protected generateColoredArgsUsage(schema?: TSchema): string {
+    if (!schema) {
+      return "";
+    }
+
+    const c = this.color;
+
+    if (t.schema.isOptional(schema)) {
+      const typeName = this.getTypeName(schema);
+      const key = "title" in schema ? (schema as any).title : "arg1";
+      return ` ${c.set("GREY_DARK", `[${key}${typeName}]`)}`;
+    }
+
+    if (t.schema.isTuple(schema) && schema.items) {
+      const items = schema.items;
+      const args = items.map((item, index) => {
+        const argName = `arg${index + 1}`;
+        const typeName = this.getTypeName(item);
+        if (t.schema.isOptional(item)) {
+          return c.set("GREY_DARK", `[${argName}${typeName}]`);
+        }
+        return c.set("CYAN", `<${argName}${typeName}>`);
+      });
+      return ` ${args.join(" ")}`;
+    }
+
+    const typeName = this.getTypeName(schema);
+    const key = "title" in schema ? (schema as any).title : "arg1";
+    return ` ${c.set("CYAN", `<${key}${typeName}>`)}`;
+  }
+
   /**
    * Get the full command path (e.g., "deploy vercel" for a child command).
    */

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
@@ -482,9 +489,17 @@ export class Alepha {
 
     const target = this.store.get("alepha.target");
     if (target) {
+      this.modules = [];
       this.registry = new Map();
       this.primitiveRegistry = new Map();
+      this.pendingInstantiations = [];
+      this.substitutions = new Map();
+      this.events.clear();
+      delete (target as any)[MODULE];
       this.with(target);
+      for (const [key] of this.substitutions.entries()) {
+        this.inject(key);
+      }
     }
 
     this.locked = true;
@@ -868,6 +883,15 @@ export class Alepha {
     > = {};
 
     for (const [provide, { parents }] of this.registry.entries()) {
+      if (provide.name === "") {
+        // ignore anonymous classes
+        continue;
+      }
+
+      if (Module.is(provide)) {
+        continue;
+      }
+
       graph[provide.name] = {
         from: parents.filter((it) => !!it).map((it) => it.name),
       };
@@ -891,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()) {
@@ -995,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.
  */
@@ -1049,6 +1108,34 @@ export interface State {
 
   /**
    * If defined, the Alepha container will only register this service and its dependencies.
+   *
+   * @example
+   * ```ts
+   * class MigrateCmd {
+   *   db = $inject(DatabaseProvider);
+   *   alepha = $inject(Alepha);
+   *   env = $env(
+   *     t.object({
+   *       MIGRATE: t.optional(t.boolean()),
+   *     }),
+   *   );
+   *
+   *   constructor() {
+   *     if (this.env.MIGRATE) {
+   *       this.alepha.set("alepha.target", MigrateCmd);
+   *     }
+   *   }
+   *
+   *   ready = $hook({
+   *     on: "ready",
+   *     handler: async () => {
+   *       if (this.env.MIGRATE) {
+   *         await this.db.migrate();
+   *       }
+   *     },
+   *   });
+   * }
+   * ```
    */
   "alepha.target"?: Service;
 

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

@@ -0,0 +1,22 @@
+import { Alepha } from "alepha";
+import { describe, it } from "vitest";
+
+describe("alepha.events.emit", () => {
+  it("should handle errors with catch option", async ({ expect }) => {
+    const alepha = Alepha.create();
+
+    alepha.events.on("echo", () => {
+      throw new Error("Error in echo");
+    });
+
+    await alepha.start();
+
+    await expect(() => alepha.events.emit("echo", {})).rejects.toThrowError(
+      "Error in echo",
+    );
+
+    expect(await alepha.events.emit("echo", {}, { catch: true })).toEqual(
+      undefined,
+    );
+  });
+});

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

@@ -0,0 +1,93 @@
+import { $inject, Alepha } from "alepha";
+import { describe, expect, it } from "vitest";
+
+describe("Alepha#graph", () => {
+  it("should generate dependency graph", async () => {
+    class A {
+      value = "a";
+    }
+
+    class B {
+      a = $inject(A);
+    }
+
+    class C {
+      a = $inject(A);
+    }
+
+    class M {
+      b = $inject(B);
+      c = $inject(C);
+    }
+
+    class A3X {
+      value = "a3bis";
+    }
+
+    class A3 {
+      deps = $inject(A3X);
+      value = "a2";
+    }
+
+    class X {
+      value = "x";
+    }
+
+    class X2 {
+      value = "x2";
+    }
+
+    const a = Alepha.create();
+
+    a.with({
+      provide: A,
+      use: A3,
+    });
+
+    a.with({
+      provide: X,
+      use: X2,
+    });
+
+    a.with(M);
+
+    await a.start();
+
+    expect(a.graph()).toEqual({
+      B: { from: ["M"] },
+      C: { from: ["M"] },
+      M: { from: ["Alepha"] },
+      A3X: { from: ["A3"] },
+      A3: { from: ["B", "C", "Alepha"], as: ["A"] },
+      X2: { from: ["Alepha"], as: ["X"] },
+      AlsProvider: {
+        from: ["StateManager", "Alepha"],
+        module: "alepha.core",
+      },
+      EventManager: {
+        from: ["StateManager", "Alepha"],
+        module: "alepha.core",
+      },
+      StateManager: {
+        from: ["Alepha"],
+        module: "alepha.core",
+      },
+      Json: {
+        from: ["JsonSchemaCodec"],
+        module: "alepha.core",
+      },
+      JsonSchemaCodec: {
+        from: ["StateManager", "CodecManager"],
+        module: "alepha.core",
+      },
+      CodecManager: {
+        from: ["Alepha"],
+        module: "alepha.core",
+      },
+      SchemaValidator: {
+        from: ["CodecManager"],
+        module: "alepha.core",
+      },
+    });
+  });
+});

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

@@ -0,0 +1,41 @@
+import { $inject, Alepha } from "alepha";
+import { describe, expect, it } from "vitest";
+
+class A {}
+
+class B {}
+
+class C {
+  a = $inject(A);
+}
+
+class D {
+  alepha = $inject(Alepha);
+  constructor() {
+    if (this.alepha.has(A)) {
+      this.alepha.with(B);
+    }
+  }
+}
+
+describe("Alepha#has", () => {
+  it("should check if service is registered", () => {
+    const container = new Alepha();
+    expect(container.has(A)).toBe(false);
+    expect(container.has(B)).toBe(false);
+    expect(container.has(C)).toBe(false);
+    container.with(C);
+    expect(container.has(A)).toBe(true);
+    expect(container.has(B)).toBe(false);
+    expect(container.has(C)).toBe(true);
+  });
+
+  it("should check service dependencies", () => {
+    const container = new Alepha().with(D);
+    expect(container.has(D)).toBe(true);
+    expect(container.has(B)).toBe(false);
+    const container2 = new Alepha().with(D).with(A);
+    expect(container2.has(D)).toBe(true);
+    expect(container2.has(B)).toBe(false);
+  });
+});

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

@@ -0,0 +1,93 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { describe, expect, it } from "vitest";
+
+describe("Alepha#inject", () => {
+  it("should handle transient lifetime", ({ expect }) => {
+    class Logger {
+      id = randomUUID();
+    }
+
+    const alepha = new Alepha();
+
+    expect(alepha.inject(Logger, { lifetime: "transient" }).id).not.toBe(
+      alepha.inject(Logger, { lifetime: "transient" }).id,
+    );
+
+    const log = alepha.inject(Logger);
+
+    expect(log.id).toBe(alepha.inject(Logger).id);
+
+    expect(alepha.inject(Logger, { lifetime: "transient" }).id).not.toBe(
+      log.id,
+    );
+  });
+
+  it("should handle transient lifetime with substitution", ({ expect }) => {
+    class BaseLogger {
+      print(msg: string): string {
+        return msg;
+      }
+    }
+
+    class EmojiLogger extends BaseLogger {
+      print(msg: string): string {
+        return `${msg}😊`;
+      }
+    }
+
+    const alepha = new Alepha().with({
+      provide: BaseLogger,
+      use: EmojiLogger,
+    });
+
+    const log = alepha.inject(BaseLogger, { lifetime: "transient" });
+
+    expect(log).toBeInstanceOf(EmojiLogger);
+    expect(log.print("Hello")).toBe("Hello😊");
+
+    expect(alepha.has(BaseLogger)).toBe(true);
+
+    // no trace of EmojiLogger in Alepha
+    expect(alepha.has(EmojiLogger)).toBe(false);
+    expect(alepha.has(BaseLogger, { inSubstitutions: false })).toBe(false);
+  });
+
+  it("should handle scoped lifetime", ({ expect }) => {
+    class Request {
+      id = randomUUID();
+    }
+
+    const alepha = new Alepha();
+
+    const base = alepha.inject(Request, { lifetime: "scoped" });
+
+    expect(alepha.inject(Request, { lifetime: "scoped" }).id).toBe(base.id);
+
+    alepha.context.run(() => {
+      expect(alepha.inject(Request, { lifetime: "scoped" }).id).not.toBe(
+        base.id,
+      );
+      expect(alepha.inject(Request, { lifetime: "scoped" }).id).toBe(
+        alepha.inject(Request, { lifetime: "scoped" }).id,
+      );
+    });
+  });
+
+  it("should pass constructor args correctly", () => {
+    class Logger {
+      constructor(public a: string) {}
+    }
+
+    const alepha = new Alepha();
+
+    expect(alepha.inject(Logger, { args: ["a"] }).a).toBe("a");
+    expect(alepha.inject(Logger).a).toBe("a");
+  });
+
+  it("should inject Alepha instance itself", () => {
+    const alepha = new Alepha();
+
+    expect(alepha.inject(Alepha)).toBe(alepha);
+  });
+});

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

@@ -0,0 +1,81 @@
+import { $inject, Alepha, TooLateSubstitutionError } from "alepha";
+import { describe, expect, it } from "vitest";
+
+describe("Alepha#with", () => {
+  it("should allow substitution", () => {
+    class A {
+      value = "a";
+    }
+
+    class M {
+      a = $inject(A);
+    }
+
+    expect(
+      Alepha.create()
+        .with({
+          provide: A,
+          use: class extends A {
+            value = "z";
+          },
+        })
+        .inject(M).a.value,
+    ).toBe("z");
+  });
+
+  class A {
+    a = "a";
+  }
+
+  class B {
+    a = "b";
+  }
+
+  class C {
+    a = "c";
+  }
+
+  class M {
+    a = $inject(A);
+  }
+
+  it("should allow optional substitution", () => {
+    const T1 = Alepha.create().with(M);
+    expect(T1.inject(M).a.a).toBe("a");
+
+    const T2 = Alepha.create().with({
+      provide: A,
+      use: B,
+    });
+    expect(T2.inject(M).a.a).toBe("b");
+
+    const T3 = Alepha.create();
+    T3.with({
+      provide: A,
+      use: C,
+      optional: true,
+    });
+    expect(T3.inject(M).a.a).toBe("c");
+
+    const T4 = Alepha.create();
+    T4.with(M);
+    T4.with({
+      provide: A,
+      use: C,
+      optional: true,
+    });
+    expect(T1.inject(M).a.a).toBe("a");
+  });
+
+  it("should reject substitution of already registered service", () => {
+    const T5 = Alepha.create();
+    T5.with(M);
+    expect(() =>
+      T5.with({
+        provide: A,
+        use: C,
+        optional: false, // should throw, because the default is already set
+      }),
+    ).toThrow(TooLateSubstitutionError);
+  });
+});