alepha 0.13.6 → 0.13.7

package/src/command/providers/CliProvider.ts

@@ -169,8 +169,23 @@ export class CliProvider {
           root: process.cwd(),
         };
 
+        // Execute pre-hooks
+        const preHooks = this.findPreHooks(command.name);
+        for (const hook of preHooks) {
+          this.log.debug(`Executing pre-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
+        // Execute main command
         await command.options.handler(args as CommandHandlerArgs<TObject>);
 
+        // Execute post-hooks
+        const postHooks = this.findPostHooks(command.name);
+        for (const hook of postHooks) {
+          this.log.debug(`Executing post-hook for '${command.name}'...`);
+          await hook.options.handler(args as CommandHandlerArgs<TObject>);
+        }
+
         if (command.options.summary !== false) {
           runner.summary();
         }
@@ -185,11 +200,25 @@ export class CliProvider {
   }
 
   protected findCommand(name: string): CommandPrimitive<TObject> | undefined {
-    return this.commands.find(
+    return this.commands.findLast(
       (command) => command.name === name || command.aliases.includes(name),
     );
   }
 
+  /**
+   * Find all pre-hooks for a command.
+   */
+  protected findPreHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `pre${commandName}`);
+  }
+
+  /**
+   * Find all post-hooks for a command.
+   */
+  protected findPostHooks(commandName: string): CommandPrimitive<TObject>[] {
+    return this.commands.filter((cmd) => cmd.name === `post${commandName}`);
+  }
+
   /**
    * Get all global flags including those from the root command (name === "")
    */
@@ -464,8 +493,8 @@ export class CliProvider {
       const maxCmdLength = this.getMaxCmdLength(this.commands);
 
       for (const command of this.commands) {
-        // skip root command in list
-        if (command.name === "") {
+        // skip root command and hooks in list
+        if (command.name === "" || command.options.hide) {
           continue;
         }
 
@@ -495,11 +524,13 @@ export class CliProvider {
 
   private getMaxCmdLength(commands: CommandPrimitive[]): number {
     return Math.max(
-      ...commands.map((c) => {
-        const cmdStr = [c.name, ...c.aliases].join(", ");
-        const argsUsage = this.generateArgsUsage(c.options.args);
-        return `${cmdStr}${argsUsage}`.length;
-      }),
+      ...commands
+        .filter((c) => !c.options.hide && c.name !== "")
+        .map((c) => {
+          const cmdStr = [c.name, ...c.aliases].join(", ");
+          const argsUsage = this.generateArgsUsage(c.options.args);
+          return `${cmdStr}${argsUsage}`.length;
+        }),
     );
   }
 

package/src/core/Alepha.ts

@@ -1,4 +1,4 @@
-import type { Static, TObject } from "typebox";
+import type { Record, Static, TObject } from "typebox";
 import { KIND } from "./constants/KIND.ts";
 import { MODULE } from "./constants/MODULE.ts";
 import { OPTIONS } from "./constants/OPTIONS.ts";
@@ -165,6 +165,11 @@ export class Alepha {
         ...state.env,
         ...process.env,
       };
+
+      // force production mode when building with vite
+      if (process.env.NODE_ENV === "production") {
+        (state.env as Record<string, string>).NODE_ENV ??= "production";
+      }
     }
 
     const alepha = new Alepha(state);
@@ -224,13 +229,6 @@ export class Alepha {
    */
   protected starting?: PromiseWithResolvers<this>;
 
-  /**
-   * Initial state of the container.
-   *
-   * > Used to initialize the StateManager.
-   */
-  protected init: Partial<State>;
-
   /**
    * During the instantiation process, we keep a list of pending instantiations.
    * > It allows us to detect circular dependencies.
@@ -276,37 +274,24 @@ export class Alepha {
    *
    * Mocked for browser environments.
    */
-  public get context(): AlsProvider {
-    return this.inject(AlsProvider);
-  }
+  public context: AlsProvider;
 
   /**
    * Event manager to handle lifecycle events and custom events.
    */
-  public get events(): EventManager {
-    return this.inject(EventManager, {
-      args: [() => this.log],
-    });
-  }
+  public events: EventManager;
 
   /**
    * State manager to store arbitrary values.
    */
-  public get store(): StateManager<State> {
-    this.events; // ensure events is initialized first (TODO: move this to constructor?)
-    return this.inject(StateManager, {
-      args: [this.init],
-    });
-  }
+  public store: StateManager<State>;
 
   /**
    * Codec manager for encoding and decoding data with different formats.
    *
    * Supports multiple codec formats (JSON, Protobuf, etc.) with a unified interface.
    */
-  public get codec(): CodecManager {
-    return this.inject(CodecManager);
-  }
+  public codec: CodecManager;
 
   /**
    * Get logger instance.
@@ -322,8 +307,14 @@ export class Alepha {
     return this.store.get("env") ?? {};
   }
 
-  constructor(init: Partial<State> = {}) {
-    this.init = init;
+  constructor(state: Partial<State> = {}) {
+    this.store = this.inject(StateManager, {
+      args: [state],
+    });
+    this.events = this.inject(EventManager);
+    this.events.logFn = () => this.log;
+    this.context = this.inject(AlsProvider);
+    this.codec = this.inject(CodecManager);
   }
 
   public set<T extends TAtomObject>(
@@ -416,11 +407,16 @@ export class Alepha {
       return false;
     }
 
+    // Vercel support
     if (this.env.VERCEL_REGION) {
       return true;
     }
 
-    if (this.env.ALEPHA_SERVERLESS) {
+    // Cloudflare Workers support
+    if (
+      typeof global === "object" &&
+      typeof (global as any).Cloudflare === "object"
+    ) {
       return true;
     }
 
@@ -471,8 +467,6 @@ export class Alepha {
       return this.starting.promise;
     }
 
-    this.codec; // ensure codec is initialized
-
     this.starting = Promise.withResolvers();
 
     const now = Date.now();
@@ -832,6 +826,22 @@ export class Alepha {
     return config as Static<T>;
   }
 
+  /**
+   * Get all environment variable schemas and their parsed values.
+   *
+   * This is useful for DevTools to display all expected environment variables.
+   */
+  public getEnvSchemas(): Array<{
+    schema: TSchema;
+    values: Record<string, any>;
+  }> {
+    const result: Array<{ schema: TSchema; values: Record<string, any> }> = [];
+    for (const [schema, values] of this.cacheEnv.entries()) {
+      result.push({ schema, values });
+    }
+    return result;
+  }
+
   // -------------------------------------------------------------------------------------------------------------------
 
   /**

package/src/core/helpers/jsonSchemaToTypeBox.ts

@@ -0,0 +1,307 @@
+import type {
+  TArrayOptions,
+  TNumberOptions,
+  TObjectOptions,
+  TSchema,
+  TStringOptions,
+} from "typebox";
+import { t } from "../providers/TypeProvider.ts";
+
+/**
+ * JSON Schema representation for conversion to TypeBox.
+ */
+export interface JsonSchemaObject {
+  type?: string | string[];
+  properties?: Record<string, JsonSchemaObject>;
+  required?: string[];
+  items?: JsonSchemaObject;
+  enum?: (string | number | boolean)[];
+  const?: unknown;
+  format?: string;
+  title?: string;
+  description?: string;
+  default?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+  pattern?: string;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  // TypeBox internal markers (pass through)
+  "~kind"?: string;
+  // Not supported
+  oneOf?: JsonSchemaObject[];
+  anyOf?: JsonSchemaObject[];
+  allOf?: JsonSchemaObject[];
+  not?: JsonSchemaObject;
+  $ref?: string;
+}
+
+/**
+ * Converts a JSON Schema object to a TypeBox schema using Alepha's type system.
+ *
+ * This is useful when receiving JSON Schema from an API (e.g., configuration schemas)
+ * and needing to use them with TypeBox-based form rendering or validation.
+ *
+ * **Supports:**
+ * - Basic types: string, number, integer, boolean, null, object, array
+ * - String formats: email, uuid, date-time, date, time, url/uri, binary, bigint, duration, color
+ * - Enums (string enums)
+ * - Nested objects with required/optional properties
+ * - Arrays with item schemas
+ * - Common validation options: minLength, maxLength, minimum, maximum, pattern
+ *
+ * **Not supported:**
+ * - oneOf, anyOf, allOf, not (composition schemas)
+ * - $ref (references)
+ * - additionalProperties, patternProperties
+ *
+ * @param schema - JSON Schema object to convert
+ * @returns TypeBox TSchema
+ *
+ * @example
+ * ```ts
+ * const jsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     email: { type: "string", format: "email" },
+ *     age: { type: "integer", minimum: 0 },
+ *     active: { type: "boolean" },
+ *   },
+ *   required: ["email"]
+ * };
+ *
+ * const typeBoxSchema = jsonSchemaToTypeBox(jsonSchema);
+ * // Equivalent to:
+ * // t.object({
+ * //   email: t.email(),
+ * //   age: t.optional(t.integer({ minimum: 0 })),
+ * //   active: t.optional(t.boolean()),
+ * // })
+ * ```
+ */
+export function jsonSchemaToTypeBox(schema: JsonSchemaObject): TSchema {
+  // If it already has TypeBox marker, return as-is
+  if (schema["~kind"]) {
+    return schema as unknown as TSchema;
+  }
+
+  // Handle const (literal)
+  if (schema.const !== undefined) {
+    return t.const(schema.const as string | number | boolean);
+  }
+
+  // Handle enum
+  if (schema.enum && Array.isArray(schema.enum)) {
+    // String enum
+    if (schema.enum.every((v) => typeof v === "string")) {
+      return t.enum(
+        schema.enum as string[],
+        filterUndefined({
+          title: schema.title,
+          description: schema.description,
+          default: schema.default as string,
+        }),
+      );
+    }
+    // For non-string enums, use union of literals
+    return t.union(
+      schema.enum.map((v) => t.const(v as string | number | boolean)),
+    );
+  }
+
+  // Handle type
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+
+  switch (type) {
+    case "string":
+      return convertString(schema);
+    case "number":
+      return convertNumber(schema);
+    case "integer":
+      return convertInteger(schema);
+    case "boolean":
+      return convertBoolean(schema);
+    case "null":
+      return t.null();
+    case "object":
+      return convertObject(schema);
+    case "array":
+      return convertArray(schema);
+    default:
+      // If no type specified but has properties, treat as object
+      if (schema.properties) {
+        return convertObject(schema);
+      }
+      // Fallback to any
+      return t.any();
+  }
+}
+
+/**
+ * Remove undefined values from an object.
+ */
+function filterUndefined<T extends Record<string, unknown>>(
+  obj: T,
+): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([_, v]) => v !== undefined),
+  ) as Partial<T>;
+}
+
+/**
+ * Convert JSON Schema string type to TypeBox.
+ */
+function convertString(schema: JsonSchemaObject): TSchema {
+  const options: TStringOptions = filterUndefined({
+    title: schema.title,
+    description: schema.description,
+    default: schema.default as string,
+    minLength: schema.minLength,
+    maxLength: schema.maxLength,
+    pattern: schema.pattern,
+  });
+
+  switch (schema.format) {
+    case "email":
+      return t.email(options);
+    case "uuid":
+      return t.uuid(options);
+    case "date-time":
+      return t.datetime(options);
+    case "date":
+      return t.date(options);
+    case "time":
+      return t.time(options);
+    case "url":
+    case "uri":
+      return t.url(options);
+    case "binary":
+      return t.binary(options);
+    case "bigint":
+      return t.bigint(options);
+    case "duration":
+      return t.duration(options);
+    case "color":
+      return t.text({ ...options, format: "color" });
+    case "e164":
+      return t.e164(options);
+    case "bcp47":
+      return t.bcp47(options);
+    default:
+      // For unknown formats, preserve the format in text
+      if (schema.format) {
+        return t.text({ ...options, format: schema.format });
+      }
+      return t.text(options);
+  }
+}
+
+/**
+ * Convert JSON Schema number type to TypeBox.
+ */
+function convertNumber(schema: JsonSchemaObject): TSchema {
+  return t.number(
+    filterUndefined({
+      title: schema.title,
+      description: schema.description,
+      default: schema.default as number,
+      minimum: schema.minimum,
+      maximum: schema.maximum,
+      exclusiveMinimum: schema.exclusiveMinimum,
+      exclusiveMaximum: schema.exclusiveMaximum,
+      multipleOf: schema.multipleOf,
+    }) as TNumberOptions,
+  );
+}
+
+/**
+ * Convert JSON Schema integer type to TypeBox.
+ */
+function convertInteger(schema: JsonSchemaObject): TSchema {
+  return t.integer(
+    filterUndefined({
+      title: schema.title,
+      description: schema.description,
+      default: schema.default as number,
+      minimum: schema.minimum,
+      maximum: schema.maximum,
+      exclusiveMinimum: schema.exclusiveMinimum,
+      exclusiveMaximum: schema.exclusiveMaximum,
+      multipleOf: schema.multipleOf,
+    }) as TNumberOptions,
+  );
+}
+
+/**
+ * Convert JSON Schema boolean type to TypeBox.
+ */
+function convertBoolean(schema: JsonSchemaObject): TSchema {
+  return t.boolean(
+    filterUndefined({
+      title: schema.title,
+      description: schema.description,
+      default: schema.default as boolean,
+    }),
+  );
+}
+
+/**
+ * Convert JSON Schema object type to TypeBox.
+ */
+function convertObject(schema: JsonSchemaObject): TSchema {
+  // No properties means it's a generic object/record
+  if (!schema.properties) {
+    return t.json(
+      filterUndefined({
+        title: schema.title,
+        description: schema.description,
+      }),
+    );
+  }
+
+  const required = new Set(schema.required ?? []);
+  const properties: Record<string, TSchema> = {};
+
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    let converted = jsonSchemaToTypeBox(propSchema);
+
+    // Wrap in optional if not required
+    if (!required.has(key)) {
+      converted = t.optional(converted);
+    }
+
+    properties[key] = converted;
+  }
+
+  return t.object(
+    properties,
+    filterUndefined({
+      title: schema.title,
+      description: schema.description,
+    }) as TObjectOptions,
+  );
+}
+
+/**
+ * Convert JSON Schema array type to TypeBox.
+ */
+function convertArray(schema: JsonSchemaObject): TSchema {
+  const itemSchema = schema.items ? jsonSchemaToTypeBox(schema.items) : t.any();
+
+  return t.array(
+    itemSchema,
+    filterUndefined({
+      title: schema.title,
+      description: schema.description,
+      minItems: schema.minItems,
+      maxItems: schema.maxItems,
+      uniqueItems: schema.uniqueItems,
+    }) as TArrayOptions,
+  );
+}

package/src/core/index.shared.ts

@@ -11,6 +11,7 @@ export * from "./errors/TooLateSubstitutionError.ts";
 export * from "./errors/TypeBoxError.ts";
 export * from "./helpers/createPagination.ts";
 export * from "./helpers/FileLike.ts";
+export * from "./helpers/jsonSchemaToTypeBox.ts";
 export * from "./helpers/primitive.ts";
 export * from "./interfaces/Async.ts";
 export * from "./interfaces/LoggerInterface.ts";

package/src/core/index.ts

@@ -5,7 +5,15 @@ import { cpus } from "node:os";
 import { Alepha } from "./Alepha.ts";
 import type { RunOptions } from "./interfaces/Run.ts";
 import type { Service } from "./interfaces/Service.ts";
+import { $module } from "./primitives/$module.ts";
 import { AlsProvider } from "./providers/AlsProvider.ts";
+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 { SchemaCodec } from "./providers/SchemaCodec.ts";
+import { SchemaValidator } from "./providers/SchemaValidator.ts";
+import { StateManager } from "./providers/StateManager.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
@@ -13,6 +21,25 @@ export * from "./index.shared.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export const AlephaCore = $module({
+  name: "alepha.core",
+  services: [
+    StateManager,
+    CodecManager,
+    EventManager,
+    AlsProvider,
+    Json,
+    JsonSchemaCodec,
+    SchemaCodec,
+    SchemaValidator,
+  ],
+  register: () => {
+    // skip registration, Alepha will handle it
+  },
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 /**
  * Run Alepha application, trigger start lifecycle.
  *
@@ -50,6 +77,7 @@ export const run = (
   // it's not recommended, we should force 'export default run(alepha)'
   (globalThis as any).__alepha = alepha;
 
+  // when alepha instance is imported via CLI, use a different global variable
   if (env.ALEPHA_CLI_IMPORT) {
     (globalThis as any).__cli_alepha = alepha;
   }
@@ -63,8 +91,7 @@ export const run = (
     return alepha;
   }
 
-  // default runner
-  (async () => {
+  setTimeout(async () => {
     try {
       await opts?.configure?.(alepha);
 
@@ -106,7 +133,7 @@ export const run = (
         process.exit(1);
       }
     }
-  })();
+  });
 
   return alepha;
 };

package/src/core/providers/EventManager.ts

@@ -4,7 +4,7 @@ import type { Async } from "../interfaces/Async.ts";
 import type { LoggerInterface } from "../interfaces/LoggerInterface.ts";
 
 export class EventManager {
-  protected logFn?: () => LoggerInterface | undefined;
+  public logFn?: () => LoggerInterface | undefined;
 
   /**
    * List of events that can be triggered. Powered by $hook().

package/src/core/providers/StateManager.ts

@@ -54,7 +54,9 @@ export class StateManager<State extends object = AlephaState> {
     if (!this.atoms.has(key)) {
       this.atoms.set(key, atom);
       if (!(key in this.store)) {
-        this.set(key, atom.options.default as State[keyof State]);
+        this.set(key, atom.options.default as State[keyof State], {
+          skipContext: true,
+        });
       }
     }
 
@@ -85,12 +87,14 @@ export class StateManager<State extends object = AlephaState> {
   public set<T extends TAtomObject>(
     target: Atom<T>,
     value: AtomStatic<T>,
+    options?: SetStateOptions,
   ): this;
   public set<Key extends keyof State>(
     target: Key,
     value: State[Key] | undefined,
+    options?: SetStateOptions,
   ): this;
-  public set(target: any, value: any): this {
+  public set(target: any, value: any, options?: SetStateOptions): this {
     if (target instanceof Atom) {
       this.register(target);
     }
@@ -103,19 +107,21 @@ export class StateManager<State extends object = AlephaState> {
       return this;
     }
 
-    if (this.als?.exists()) {
+    if (options?.skipContext !== true && this.als?.exists()) {
       this.als.set(key as string, value);
     } else {
       store[key] = value;
     }
 
-    this.events
-      ?.emit(
-        "state:mutate",
-        { key: key as keyof AlephaState, value, prevValue },
-        { catch: true },
-      )
-      .catch(() => null);
+    if (options?.skipEvents !== true) {
+      this.events
+        ?.emit(
+          "state:mutate",
+          { key: key as keyof AlephaState, value, prevValue },
+          { catch: true },
+        )
+        .catch(() => null);
+    }
 
     return this;
   }
@@ -156,11 +162,11 @@ export class StateManager<State extends object = AlephaState> {
    */
   public push<Key extends keyof OnlyArray<State>>(
     key: Key,
-    value: NonNullable<State[Key]> extends Array<infer U> ? U : never,
+    ...value: Array<NonNullable<State[Key]> extends Array<infer U> ? U : never>
   ): this {
     const current = (this.get(key) ?? []) as Array<any>; // default to empty array
     if (Array.isArray(current)) {
-      this.set(key, [...current, value] as State[Key]);
+      this.set(key, [...current, ...value] as State[Key]);
     }
     return this;
   }
@@ -184,3 +190,8 @@ export class StateManager<State extends object = AlephaState> {
 type OnlyArray<T extends object> = {
   [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never;
 };
+
+export interface SetStateOptions {
+  skipContext?: boolean;
+  skipEvents?: boolean;
+}