@dep/command@3.0.0

Author: estarlincito

README.md

@@ -38,82 +38,94 @@
 
 ## Usage 🎯
 
-### CLI 💻 <!-- if available -->
+Use the `Command` class to build and run CLI applications with arguments,
+options, and subcommands.
 
-This package is a library for building CLI tools. Once you've defined your
-command, you can run it from the command line using Deno or Node.js. For
-example, save the script below as `mycli.ts` and execute it with
-`deno run mycli.ts [args]` or `node mycli.js [args]`.
+```ts
+//cli.ts
+import { Command, CommandError } from "@dep/command";
 
-Example command execution:
-
-```bash
-deno run mycli.ts input.txt --output output.txt
-```
-
-### API 🧩
-
-Use the `Command` class to build and configure your CLI. Here's a basic example:
+const http = new Command()
+  .name("http")
+  .version("1.0.0")
+  .description("A lightweight HTTP client CLI")
+  .argument("url", "The target URL for the request")
+  .option("--header", {
+    shortFlag: "-H",
+    description: 'Custom header (e.g., "Content-Type: application/json")',
+    optional: true,
+  });
 
-```typescript
-import { Command } from "@dep/command";
+http.command("get", "Perform a GET request").handler(({ args, options }) => {
+  console.log(`GET ${args.url}`);
+  console.log(`Header: ${options.header}`);
+});
 
-const cmd = new Command()
-  .name("mycli")
-  .description("A simple CLI tool example")
-  .version("1.0.0")
-  .argument("input", { description: "Input file path" })
-  .option("--output", {
-    kind: "value",
-    description: "Output file path",
-    shortFlag: "-o",
+http
+  .command("post", "Perform a POST request")
+  .option("--body", {
+    shortFlag: "-B",
+    description: "The JSON body string to send",
   })
   .handler(({ args, options }) => {
-    console.log("Input file:", args.input);
-    console.log("Output file:", options.output);
+    console.log(`POST ${args.url}`);
+    console.log(`Body: ${options.body}`);
   });
 
 try {
-  await clit.run(); // (defaults tokens Deno.args | `process.argv.slice(2)`)
+  // uses Deno.args or process.argv.slice(2)
+  await http.run();
 } catch (err) {
   if (err instanceof CommandError) {
     console.error(`\nError: ${err.message}\n`);
-    cmd.help();
-    Deno.exit(1); //or process.exit(1);
+    http.help();
+    Deno.exit(1); // or process.exit(1)
   }
   throw err;
 }
 ```
 
-For more advanced usage, including subcommands:
+### Running the CLI 💻
 
-```typescript
-import { Command } from "@dep/command";
+```bash
+deno run cli.ts --help
+```
 
-const cmd = new Command()
-  .name("mycli")
-  .description("CLI with subcommands")
-  .command("sub", "Subcommand description")
-  .argument("arg", "Subcommand argument")
-  .handler(({ args }) => {
-    console.log("Subcommand arg:", args.arg);
-  });
+```text
+Usage: http <url> [options] [command]
 
-try {
-  await clit.run(); // (defaults tokens Deno.args | `process.argv.slice(2)`)
-} catch (err) {
-  if (err instanceof CommandError) {
-    console.error(`\nError: ${err.message}\n`);
-    cmd.help();
-    Deno.exit(1); //or process.exit(1);
-  }
-  throw err;
-}
+A lightweight HTTP client CLI
+
+Arguments:
+  <url>           The target URL for the request
+
+Options:
+--header, -H  [header]             Custom header (e.g., "Content-Type: application/json")
+--help, -h                         Show help
+--version, -v                      Show version
+
+Commands:
+  get             Perform a GET request
+  post            Perform a POST request
 ```
 
-Run with `mycli sub value` to execute the subcommand.
+```bash
+deno run cli.ts get 'https://estarlincito.com' --header "Authorization: Kyumiu"
+```
 
----
+```text
+GET https://estarlincito.com
+Header: Authorization: Kyumiu
+```
+
+```bash
+deno run cli.ts post 'https://estarlincito.com' --body "user: estarlincito"
+```
+
+```text
+POST https://estarlincito.com
+Body: user: estarlincito
+```
 
 ## License 📄
 

deno.json

@@ -1,12 +1,13 @@
 {
   "name": "@dep/command",
-  "version": "2.5.1",
+  "version": "3.0.0",
   "exports": "./src/main.ts",
   "compilerOptions": {
     "strict": true
   },
   "imports": {
     "@/": "./src/",
+    "@dep/assert": "jsr:@dep/assert@^1.3.0",
     "@dep/table": "jsr:@dep/table@^1.0.1"
   },
   "tasks": {
@@ -18,7 +19,7 @@
     "lint": "deno lint",
     "fmt": "deno fmt",
     "clean": "rm -rf dist",
-    "pack": "deno compile -A -o yaml-layer ./cli.ts",
+    "pack": "deno compile -A -o command ./cli.ts",
     "prerelease": "deno lint && deno fmt",
     "release": "deno task prerelease && jsr publish ./"
   },

deno.lock

@@ -1,6 +1,6 @@
 {
   "name": "@dep/command",
-  "version": "2.5.0",
+  "version": "3.0.0",
   "description": "A type-safe CLI command builder for Deno and Node.js, enabling easy creation of commands with arguments, options, subcommands, and handlers.",
   "exports": "./src/main.ts",
   "author": {

jsr.json

@@ -122,7 +122,7 @@ export class CommandBuilder<
     config?: K extends "flag" ? Partial<
         Pick<CommandOption<L, K, O>, "kind" | "shortFlag" | "description">
       >
-      : Partial<Omit<CommandOption<L, K, O>, "shortFlag">>,
+      : Partial<CommandOption<L, K, O>>,
   ): With<[...Options, CommandOption<L, K, O>], Arguments>[Kind] {
     const option: CommandOption<L, "value", false> = {
       longFlag,

src/core/builder.ts

@@ -0,0 +1,58 @@
+import { Command } from "./command.ts";
+import { assertDeepEqual } from "@dep/assert";
+
+const http = new Command()
+  .name("http")
+  .version("1.0.0")
+  .description("A lightweight HTTP client CLI")
+  .argument("url", "The target URL for the request")
+  .option("--header", {
+    shortFlag: "-H",
+    description: 'Custom header (e.g., "Content-Type: application/json")',
+    optional: true,
+  });
+
+http.command("get", "Perform a GET request").handler(({ args, options }) => {
+  console.log(`GET ${args.url}`);
+  console.log(`Header: ${options.header}`);
+});
+
+http
+  .command("post", "Perform a POST request")
+  .option("--body", {
+    shortFlag: "-B",
+    description: "The JSON body string to send",
+  })
+  .handler(({ args, options }) => {
+    console.log(`POST ${args.url}`);
+    console.log(`Body: ${options.body}`);
+  });
+
+const url = "https://estarlincito.com";
+
+Deno.test("http", () =>
+  assertDeepEqual(http.parse([url]).args, {
+    url,
+  }));
+
+Deno.test("get", () =>
+  assertDeepEqual(http.parse(["get", url]).args, {
+    url,
+  }));
+
+Deno.test("post", () => {
+  assertDeepEqual(
+    http.parse([
+      "post",
+      url,
+      "--header",
+      "Authorization: Kyumiu",
+      "--body",
+      "user: estarlincito",
+    ]).options,
+    {
+      header: "Authorization: Kyumiu",
+      body: "user: estarlincito",
+    },
+  );
+});

src/core/command.test.ts

@@ -1,12 +1,13 @@
 import { showHelp } from "@/helpers/help.ts";
-import { parseRuntime } from "@/helpers/parse/index.ts";
+import { ParsedCommand, parser } from "@/helpers/parse/main.ts";
 import { runner } from "@/helpers/runner.ts";
 import { CommandBuilder } from "./builder.ts";
+import { getDefaultTokens } from "@/helpers/token.ts";
+import { type Config } from "@/helpers/utils.ts";
 
 import type {
   CommandArgument,
   CommandHideKind,
-  CommandInput,
   CommandOption,
 } from "./types.ts";
 
@@ -26,13 +27,13 @@ import { $config } from "@/helpers/utils.ts";
  *   .description('A simple CLI tool example')
  *   .version('1.0.0')
  *   .argument('input', { description: 'Input file path' })
- *   .option('--output', { kind: 'value', description: 'Output file path', shortFlag: '-o' })
+ *   .option('--output', { description: 'Output file path', shortFlag: '-o' })
  *   .handler(({ args, options }) => {
  *     console.log('Input file:', args.input);
  *     console.log('Output file:', options.output);
  *   });
  *
- * cmd.run();
+ * await cmd.run();
  * ```
  */
 export class Command<
@@ -76,22 +77,19 @@ export class Command<
 
   /**
    * Parses the provided tokens (or default CLI arguments) into a typed CommandInput.
-   * @param tokens - Optional array of tokens to parse; defaults to process/Deno args.
-   * @returns The parsed CommandInput with typed args, options, and unparsed tokens.
+   * @param tokens - Optional array of tokens to run with; defaults to process/Deno args.
+   * @returns The parsed CommandInput with typed args, options, handled, chains, and unparsed tokens.
    */
-  parse(tokens?: string[]): CommandInput<Options, Arguments> {
-    return parseRuntime(this[$config](), tokens ?? []) as CommandInput<
-      Options,
-      Arguments
-    >;
+  parse(tokens: string[] = getDefaultTokens()): ParsedCommand {
+    return parser(this[$config]() as Config, tokens);
   }
 
   /**
    * Displays the help information for the command if not hidden.
    */
   help() {
     if (!this[$config]().hidden.help) {
-      showHelp(this[$config]());
+      showHelp([this[$config]()]);
     }
   }
 
@@ -102,7 +100,23 @@ export class Command<
    * @param tokens - Optional array of tokens to run with; defaults to process/Deno args.
    * @returns A Promise that resolves when the command execution completes.
    */
-  async run(tokens?: string[]): Promise<void> {
+  async run(tokens: string[] = getDefaultTokens()): Promise<void> {
+    // Auto-add --help / --version unless hidden
+    if (!this[$config]().hidden.help) {
+      this.option("--help", {
+        kind: "flag",
+        description: `Show help`,
+        shortFlag: "-h",
+      });
+    }
+
+    if (!this[$config]().hidden.version) {
+      this.option("--version", {
+        kind: "flag",
+        description: `Show version`,
+        shortFlag: "-v",
+      });
+    }
     await runner(this[$config](), tokens);
   }
 }