docs: add lazy loading and use Cli instead

Author: so1ve

docs/.vitepress/plugins/markdownTransform.ts

@@ -5,6 +5,7 @@ const TAB_SIZE = 2;
 // @keep-sorted
 export const clercImports = [
 	"Clerc",
+	"Cli",
 	"completionsPlugin",
 	"friendlyErrorPlugin",
 	"helpPlugin",

docs/advanced.md

@@ -9,13 +9,13 @@ title: Advanced Usage
 Clerc allows you to pass a custom array of arguments instead of using the default `process.argv` / `Deno.args`. This is useful for testing or specific environments.
 
 ```ts
-Clerc.create().parse(["node", "my-cli", "greet"]); // Pass a custom array of arguments
+Cli().parse(["node", "my-cli", "greet"]); // Pass a custom array of arguments
 ```
 
 Alternatively, you can also pass an argument object:
 
 ```ts
-Clerc.create().parse({
+Cli().parse({
 	argv: ["greet"],
 });
 ```
@@ -25,12 +25,13 @@ Clerc.create().parse({
 Sometimes you may want to parse commands and flags without immediately executing the command handler. Clerc provides an option to achieve this:
 
 ```ts
-const result = Clerc.create().parse({
+const result = Cli().parse({
 	run: false, // Parse only, do not execute
 });
 ```
 
 When you need to run, you can call:
 
 ```ts
-result.run(); // Execute the parsed command
+result.run(); // Execute the parsed command
+```

docs/commands.md

@@ -7,9 +7,7 @@ title: Commands
 ## Basic Usage
 
 ```ts
-import { Clerc } from "clerc";
-
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -33,7 +31,7 @@ Command aliases allow users to invoke a command using an alternative name. This
 You can define a single alias for a command using a string:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -53,7 +51,7 @@ Now both `foo-cli foo` and `foo-cli f` will output "It works!".
 You can define multiple aliases for a command using an array:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -73,7 +71,7 @@ Now `foo-cli foo`, `foo-cli f`, `foo-cli bar`, and `foo-cli baz` all work the sa
 #### Example: Git-like Abbreviations
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("git")
 	.command("status", "Show working tree status", {
 		alias: "st",
@@ -112,7 +110,7 @@ $ git co
 You can define subcommands by using spaces in the command name:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -128,7 +126,7 @@ const cli = Clerc.create()
 You can define a root command (a command with no name) to handle cases when no subcommand is specified:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -162,7 +160,7 @@ Example:
 ```ts
 // $ node ./foo-cli.mjs a b c d
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -202,7 +200,7 @@ Example:
 ```ts
 // $ node ./foo-cli.mjs echo -- hello world
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -235,11 +233,11 @@ Where `--flag` is passed directly to the script, not to `deno`.
 You can achieve this usage by using the `ignore` property to specify which arguments or flags to ignore.
 
 ```ts
-import { Clerc, PARAMETER } from "clerc";
+import { PARAMETER } from "clerc";
 
 let encounteredParameter = false;
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("deno")
 	.description("Deno CLI")
 	.version("1.0.0")
@@ -275,7 +273,7 @@ const cli = Clerc.create()
 To separate the handler from the cli definition, you can use the `defineCommand` utility function:
 
 ```ts
-import { Clerc, defineCommand } from "clerc";
+import { defineCommand } from "clerc";
 
 const command = defineCommand({
 	name: "test",
@@ -287,10 +285,144 @@ const command = defineCommand({
 	},
 });
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
 	.command(command)
 	.parse();
 ```
+
+## Lazy Loading
+
+Lazy loading allows you to defer the loading of command handlers until they are actually invoked. This is useful for reducing startup time and memory usage, especially when you have many commands or heavy handlers.
+
+You can implement lazy loading by using dynamic imports (`await import()`) within the handler:
+
+### Basic Lazy Loading
+
+```ts
+const cli = Cli()
+	.scriptName("app")
+	.description("An application with lazy loading")
+	.version("1.0.0")
+	.command("build", "Build the project", {
+		flags: {
+			production: {
+				type: Boolean,
+				description: "Build for production",
+			},
+		},
+	})
+	.on("build", async (ctx) => {
+		// Handler is only loaded when the command is invoked
+		const { buildProject } = await import("./handlers/build.js");
+		await buildProject(ctx);
+	})
+	.command("deploy", "Deploy the application", {
+		flags: {
+			environment: {
+				type: String,
+				default: "staging",
+				description: "Target environment",
+			},
+		},
+	})
+	.on("deploy", async (ctx) => {
+		// Another handler loaded lazily
+		const { deploy } = await import("./handlers/deploy.js");
+		await deploy(ctx);
+	})
+	.parse();
+```
+
+### Lazy Loading with defineCommand
+
+You can also combine lazy loading with the `defineCommand` utility:
+
+```ts
+import { defineCommand } from "clerc";
+
+const command = defineCommand({
+	name: "migrate",
+	description: "Run database migrations",
+	flags: {},
+	parameters: [],
+	handler: async (ctx) => {
+		// Handler loaded only when command is invoked
+		const { runMigrations } = await import("./handlers/migrate.js");
+		await runMigrations(ctx);
+	},
+});
+
+const cli = Cli()
+	.scriptName("app")
+	.description("Application with lazy-loaded commands")
+	.version("1.0.0")
+	.command(command)
+	.parse();
+```
+
+### Benefits
+
+- **Faster startup time**: Only handlers for invoked commands are loaded
+- **Lower memory usage**: Unused handlers don't consume memory
+- **Better scalability**: Easy to add many commands without performance impact
+- **Asynchronous operations**: Handlers can perform async operations like file I/O or network requests
+
+### Example: Modular Command Structure
+
+Directory structure:
+
+```
+project/
+├── cli.ts
+├── handlers/
+│   ├── build.ts
+│   ├── dev.ts
+│   ├── deploy.ts
+│   └── test.ts
+```
+
+`handlers/build.ts`:
+
+```ts
+export async function buildProject(ctx) {
+	if (ctx.flags.production) {
+		console.log("Building for production...");
+	} else {
+		console.log("Building for development...");
+	}
+}
+```
+
+`cli.ts`:
+
+```ts
+const cli = Cli()
+	.scriptName("app")
+	.version("1.0.0")
+	.command("build", "Build the project", {
+		flags: {
+			production: {
+				type: Boolean,
+				description: "Build for production",
+			},
+		},
+	})
+	.on("build", async (ctx) => {
+		const { buildProject } = await import("./handlers/build.js");
+		await buildProject(ctx);
+	})
+	.command("dev", "Start development server", {})
+	.on("dev", async (ctx) => {
+		const { startDev } = await import("./handlers/dev.js");
+		await startDev(ctx);
+	})
+	.command("deploy", "Deploy application")
+	.on("deploy", async (ctx) => {
+		const { deploy } = await import("./handlers/deploy.js");
+		await deploy(ctx);
+	})
+	.parse();
+```

docs/flags.md

@@ -32,7 +32,7 @@ Flag aliases allow users to use shorter or alternative names for flags. This is
 You can define a single alias for a flag using a string:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("build", "Build the project", {
 		flags: {
 			output: {
@@ -64,7 +64,7 @@ const cli = Clerc.create()
 You can define multiple aliases for a flag using an array:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("config", "Configure the application", {
 		flags: {
 			config: {
@@ -97,7 +97,7 @@ const cli = Clerc.create()
 When using short aliases (single characters), they can be combined together:
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("compress", "Compress files", {
 		flags: {
 			output: {
@@ -133,7 +133,7 @@ const cli = Clerc.create()
 ```ts
 // $ node ./foo-cli.mjs echo --some-boolean --some-string hello --some-number 1 -n 2
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("foo-cli")
 	.description("A simple CLI")
 	.version("1.0.0")
@@ -189,7 +189,7 @@ The `String` type is used for flags that accept string values. This is the most
 **Default value behavior:** If the flag is not specified, its value is `undefined` (unless a `default` property is set).
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("greet", "Greet someone", {
 		flags: {
 			name: {
@@ -223,7 +223,7 @@ The `Boolean` type is used for creating boolean switch flags. By default, simply
 **Default value behavior:** If the flag is not specified, its value is `false`.
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("build", "Build the project", {
 		flags: {
 			production: {
@@ -255,7 +255,7 @@ const cli = Clerc.create()
 The Boolean type supports a `negatable` property that allows you to decide whether to enable negated flags. By default, `negatable` is `true`, which means `--no-flag` will set the `flag` flag to `false`.
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("start", "Start the application", {
 		flags: {
 			color: {
@@ -296,7 +296,7 @@ The `Array` type is used for flags that accept multiple values. Define it by wra
 **Default value behavior:** If the flag is not specified, its value is `[]` (empty array).
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("copy", "Copy files", {
 		flags: {
 			// Use [String] to accept multiple string values
@@ -345,7 +345,7 @@ The counter type is used to count how many times a flag is specified. This can b
 **Default value behavior:** If the flag is not specified, its value is `0`.
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("log", "Display logs", {
 		flags: {
 			// [Boolean] type counts how many times the flag is used
@@ -379,7 +379,7 @@ The `Object` type is used for flags that accept key-value pairs. Use dots or oth
 **Default value behavior:** If the flag is not specified, its value is `{}` (empty object).
 
 ```ts
-const cli = Clerc.create()
+const cli = Cli()
 	.command("config", "Configure the application", {
 		flags: {
 			define: {
@@ -408,7 +408,7 @@ Clerc provides some built-in advanced flag types to facilitate common needs:
 ```ts
 import { Choices } from "clerc";
 
-Clerc.create()
+Cli()
 	.command("serve", "Start the server", {
 		flags: {
 			mode: {
@@ -434,7 +434,7 @@ You can create custom flag types by providing a custom type function. The type f
 const CommaSeparatedList = (value: string): string[] =>
 	value.split(",").map((item) => item.trim());
 
-const cli = Clerc.create()
+const cli = Cli()
 	.scriptName("custom-cli")
 	.description("A CLI using a custom flag type")
 	.version("1.0.0")