alepha/command.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core1 from "alepha";
import { Alepha, AlephaError, Async, Descriptor, KIND, Static, TObject, TSchema, TString } from "alepha";
import * as _alepha_logger0 from "alepha/logger";
import * as fs from "node:fs/promises";
import { glob } from "node:fs/promises";
import * as readline_promises0 from "readline/promises";
import * as typebox0 from "typebox";

//#region src/helpers/Asker.d.ts
interface AskOptions<T$1 extends TSchema = TString> {
  /**
   * Response schema expected.
   *
   * Recommended schemas:
   * - t.text() - for free text input
   * - t.number() - for numeric input
   * - t.boolean() - for yes/no input (accepts "true", "false", "1", "0")
   * - t.enum(["option1", "option2"]) - for predefined options
   *
   * You can use schema.default to provide a default value.
   *
   * @example
   * ```ts
   * ask("What is your name?", { schema: t.text({ default: "John Doe" }) })
   * ```
   *
   * @default TString
   */
  schema?: T$1;
  /**
   * Custom validation function.
   * Throws an AlephaError in case of validation failure.
   */
  validate?: (value: Static<T$1>) => void;
}
interface AskMethod {
  <T extends TSchema = TString>(question: string, options?: AskOptions<T>): Promise<Static<T>>;
}
declare class Asker {
  protected readonly log: _alepha_logger0.Logger;
  readonly ask: AskMethod;
  protected readonly alepha: Alepha;
  constructor();
  protected createAskMethod(): AskMethod;
  protected prompt<T extends TSchema = TString>(question: string, options: AskOptions<T>): Promise<Static<T>>;
  protected createPromptInterface(): readline_promises0.Interface;
}
//#endregion
//#region src/helpers/Runner.d.ts
type Task = {
  name: string;
  handler: () => any;
};
interface Timer {
  name: string;
  duration: string;
}
interface RunOptions {
  /**
   * Rename the command for logging purposes.
   */
  alias?: string;
}
interface RunnerMethod {
  (cmd: string | Task | Array<string | Task>, options?: RunOptions | (() => any)): Promise<string>;
  rm: (glob: string | string[], options?: RunOptions) => Promise<string>;
  cp: (source: string, dest: string, options?: RunOptions) => Promise<string>;
}
declare class Runner {
  protected readonly log: _alepha_logger0.Logger;
  protected readonly timers: Timer[];
  protected readonly startTime: number;
  readonly run: RunnerMethod;
  constructor();
  protected createRunMethod(): RunnerMethod;
  protected exec(cmd: string): Promise<string>;
  /**
   * Executes one or more tasks.
   *
   * @param task - A single task or an array of tasks to run in parallel.
   */
  protected execute(task: Task | Task[]): Promise<string>;
  /**
   * Prints a summary of all executed tasks and their durations.
   */
  summary(): void;
  protected executeTask(task: Task): Promise<string>;
  protected renderTable(data: string[][]): void;
}
//#endregion
//#region src/descriptors/$command.d.ts
/**
 * Declares a CLI command.
 *
 * This descriptor allows you to define a command, its flags, and its handler
 * within your Alepha application structure.
 */
declare const $command: {
  <T extends TObject, A extends TSchema>(options: CommandDescriptorOptions<T, A>): CommandDescriptor<T, A>;
  [KIND]: typeof CommandDescriptor;
};
interface CommandDescriptorOptions<T$1 extends TObject, A$1 extends TSchema> {
  /**
   * The handler function to execute when the command is matched.
   */
  handler: (args: CommandHandlerArgs<T$1, A$1>) => Async<void>;
  /**
   * The name of the command. If omitted, the property key is used.
   *
   * An empty string "" denotes the root command.
   */
  name?: string;
  /**
   * A short description of the command, shown in the help message.
   */
  description?: string;
  /**
   * An array of alternative names for the command.
   */
  aliases?: string[];
  /**
   * A TypeBox object schema defining the flags for the command.
   */
  flags?: T$1;
  /**
   * An optional TypeBox schema defining the arguments for the command.
   *
   * @example
   * args: t.text()
   * my-cli command <arg1: string>
   *
   * args: t.optional(t.text())
   * my-cli command [arg1: string]
   *
   * args: t.tuple([t.text(), t.number()])
   * my-cli command <arg1: string> <arg2: number>
   *
   * args: t.tuple([t.text(), t.optional(t.number())])
   * my-cli command <arg1: string> [arg2: number]
   */
  args?: A$1;
  /**
   * If false, skip summary message at the end of the command execution.
   */
  summary?: boolean;
}
declare class CommandDescriptor<T$1 extends TObject = TObject, A$1 extends TSchema = TSchema> extends Descriptor<CommandDescriptorOptions<T$1, A$1>> {
  readonly flags: TObject<{}>;
  readonly aliases: string[];
  get name(): string;
}
interface CommandHandlerArgs<T$1 extends TObject, A$1 extends TSchema = TSchema> {
  flags: Static<T$1>;
  args: A$1 extends TSchema ? Static<A$1> : Array<string>;
  run: RunnerMethod;
  ask: AskMethod;
  glob: typeof glob;
  fs: typeof fs;
}
//#endregion
//#region src/errors/CommandError.d.ts
declare class CommandError extends AlephaError {
  readonly name = "CommandError";
}
//#endregion
//#region src/providers/CliProvider.d.ts
declare const envSchema: TObject<{
  CLI_NAME: _alepha_core1.TString;
  CLI_DESCRIPTION: _alepha_core1.TString;
}>;
declare module "alepha" {
  interface Env extends Partial<Static<typeof envSchema>> {}
}
declare class CliProvider {
  protected readonly env: {
    CLI_NAME: string;
    CLI_DESCRIPTION: string;
  };
  protected readonly alepha: Alepha;
  protected readonly log: _alepha_logger0.Logger;
  protected readonly runner: Runner;
  protected readonly asker: Asker;
  options: {
    name: string;
    description: string;
    argv: string[];
  };
  protected readonly globalFlags: {
    help: {
      aliases: string[];
      description: string;
      schema: typebox0.TBoolean;
    };
  };
  protected readonly onReady: _alepha_core1.HookDescriptor<"ready">;
  get commands(): CommandDescriptor<any>[];
  private findCommand;
  protected parseCommandFlags(argv: string[], schema: TObject): Record<string, any>;
  protected parseFlags(argv: string[], flagDefs: {
    key: string;
    aliases: string[];
    schema: TSchema;
  }[]): Record<string, any>;
  protected parseCommandArgs(argv: string[], schema?: TSchema): any;
  protected parseArgumentValue(value: string, schema: TSchema): any;
  protected generateArgsUsage(schema?: TSchema): string;
  protected getTypeName(schema: TSchema): string;
  printHelp(command?: CommandDescriptor<any>): void;
  private getMaxCmdLength;
  private getMaxFlagLength;
}
//#endregion
//#region src/index.d.ts
/**
 * This module provides a powerful way to build command-line interfaces
 * directly within your Alepha application, using declarative descriptors.
 *
 * It allows you to define commands using the `$command` descriptor.
 *
 * @see {@link $command}
 * @module alepha.command
 */
declare const AlephaCommand: _alepha_core1.Service<_alepha_core1.Module<{}>>;
declare module "typebox" {
  interface StringOptions {
    /**
     * Additional aliases for the flags.
     *
     * @module alepha.command
     */
    aliases?: string[];
  }
}
//# sourceMappingURL=index.d.ts.map

//#endregion
export { $command, AlephaCommand, AskMethod, AskOptions, Asker, CliProvider, CommandDescriptor, CommandDescriptorOptions, CommandError, CommandHandlerArgs, RunOptions, Runner, RunnerMethod, Task };
//# sourceMappingURL=index.d.ts.map