add onMissing config option for interactive/async default values (#245)

* add onMissing to types and options

* add onMissing callback support to flags and multioptions

* update docs

* changeset

Author: Schniz

.changeset/chatty-seals-arrive.md

@@ -0,0 +1,22 @@
+---
+'cmd-ts': patch
+---
+
+Added onMissing callback support to flags, options, and custom types
+
+That allows providing dynamic fallback values when command-line arguments are not provided, This enables:
+
+- Hiding default values from help output
+- Interactive prompts: Ask users for input when flags/options are missing
+- Environment-based defaults: Check environment variables or config files dynamically
+- Auto-discovery: Automatically find files or resources when not specified
+- Async support: Handle both synchronous and asynchronous fallback logic
+
+The onMissing callback is used as a fallback when defaultValue is not provided, following the precedence order: environment variables → defaultValue → onMissing → type defaults.
+
+New APIs:
+
+- flag({ onMissing: () => boolean | Promise<boolean> })
+- option({ onMissing: () => T | Promise<T> })
+- multioption({ onMissing: () => T[] | Promise<T[]> })
+- Custom Type interface now supports onMissing property

docs/custom_types.md

@@ -65,6 +65,7 @@ const ReadStream: Type<string, Stream> = {
   - `description` to provide a default description for this type
   - `displayName` is a short way to describe the type in the help
   - `defaultValue(): B` to allow the type to be optional and have a default value
+  - `onMissing(): B | Promise<B>` to provide a dynamic fallback when the argument is not provided (used as fallback if `defaultValue` is not provided)
 
 Using the type we've just created is no different that using `string`:
 
@@ -93,4 +94,40 @@ Now, we can add more features to our `ReadStream` type and stop touching our cod
 - We can try to parse the string as a URI and check if the protocol is HTTP, if so - make an HTTP request and return the body stream
 - We can see if the string is `-`, and when it happens, return `process.stdin` like many Unix applications
 
+### Custom Types with `onMissing`
+
+Custom types can also provide dynamic defaults using `onMissing`. This is useful when you want the type itself to determine what happens when no argument is provided:
+
+```ts
+const ConfigFile: Type<string, Config> = {
+  async from(str) {
+    if (!fs.existsSync(str)) {
+      throw new Error(`Config file not found: ${str}`);
+    }
+    return JSON.parse(fs.readFileSync(str, 'utf8'));
+  },
+  
+  displayName: 'config-file',
+  
+  async onMissing() {
+    // Look for config in standard locations when not provided
+    const candidates = [
+      './config.json',
+      path.join(os.homedir(), '.myapp', 'config.json'),
+      '/etc/myapp/config.json'
+    ];
+    
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        console.log(`Using config from: ${candidate}`);
+        return JSON.parse(fs.readFileSync(candidate, 'utf8'));
+      }
+    }
+    
+    // Return default config if none found
+    return { debug: false, verbose: false };
+  },
+};
+```
+
 And the best thing about it — everything is encapsulated to an easily tested type definition, which can be easily shared and reused. Take a look at [io-ts-types](https://github.com/gcanti/io-ts-types), for instance, which has types like DateFromISOString, NumberFromString and more, which is something we can totally do.

docs/parsers/flags.md

@@ -46,6 +46,46 @@ const cmd = command({
 });
 ```
 
+### Dynamic Defaults with `onMissing`
+
+The `onMissing` callback provides a way to dynamically generate values when a flag is not provided. This is useful for environment-based defaults, configuration file lookups, or user prompts.
+
+```ts
+import { command, flag } from 'cmd-ts';
+
+const verboseFlag = flag({
+  long: 'verbose',
+  short: 'v',
+  description: 'Enable verbose output',
+  onMissing: () => {
+    // Check environment variable as fallback
+    return process.env.NODE_ENV === 'development';
+  },
+});
+
+const debugFlag = flag({
+  long: 'debug',
+  short: 'd',
+  description: 'Enable debug mode',
+  onMissing: async () => {
+    // Async example: check config file or make API call
+    const config = await loadConfig();
+    return config.debug || false;
+  },
+});
+
+const cmd = command({
+  name: 'my app',
+  args: { 
+    verbose: verboseFlag,
+    debug: debugFlag,
+  },
+  handler: ({ verbose, debug }) => {
+    console.log(`Verbose: ${verbose}, Debug: ${debug}`);
+  },
+});
+```
+
 ### Config
 
 - `type` (required): A type from `boolean` to any value
@@ -55,6 +95,7 @@ const cmd = command({
 - `displayName`: A short description regarding the option
 - `defaultValue`: A function that returns a default value for the option
 - `defaultValueIsSerializable`: Whether to print the defaultValue as a string in the help docs.
+- `onMissing`: A function (sync or async) that returns a value when the flag is not provided. Used as fallback if `defaultValue` is not provided.
 
 ## `multiflag`
 

docs/parsers/options.md

@@ -44,6 +44,43 @@ const cmd = command({
 });
 ```
 
+### Dynamic Defaults with `onMissing`
+
+The `onMissing` callback provides a way to dynamically generate values when an option is not provided. This is perfect for interactive prompts:
+
+```ts
+import { command, option, string } from './src';
+import { createInterface } from 'readline/promises';
+
+const name = option({
+  type: string,
+  long: 'name',
+  short: 'n',
+  description: 'Your name for the greeting',
+  onMissing: async () => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    try {
+      const answer = await rl.question("What's your name? ");
+      return answer.trim() || 'Anonymous';
+    } finally {
+      rl.close();
+    }
+  },
+});
+
+const cmd = command({
+  name: 'greeting',
+  args: { name },
+  handler: ({ name }) => {
+    console.log(`Hello, ${name}!`);
+  },
+});
+```
+
 ### Config
 
 - `type` (required): A type from `string` to any value
@@ -53,6 +90,7 @@ const cmd = command({
 - `displayName`: A short description regarding the option
 - `defaultValue`: A function that returns a default value for the option
 - `defaultValueIsSerializable`: Whether to print the defaultValue as a string in the help docs.
+- `onMissing`: A function (sync or async) that returns a value when the option is not provided. Used as fallback if `defaultValue` is not provided.
 
 ## `multioption`
 
@@ -65,6 +103,42 @@ This parser will fail to parse if:
 - No value was provided (if it was treated like [a flag](./flags.md))
 - Decoding the user input fails
 
+### Dynamic Defaults for `multioption`
+
+Like single options, `multioption` supports `onMissing` callbacks for dynamic default arrays:
+
+```ts
+import { command, multioption } from 'cmd-ts';
+import type { Type } from 'cmd-ts';
+
+const stringArray: Type<string[], string[]> = {
+  async from(strings) {
+    return strings;
+  },
+  displayName: 'string',
+};
+
+const includes = multioption({
+  type: stringArray,
+  long: 'include',
+  short: 'i',
+  description: 'Files to include',
+  onMissing: async () => {
+    // Auto-discover files when none specified
+    const files = await glob('src/**/*.ts');
+    return files;
+  },
+});
+
+const cmd = command({
+  name: 'build',
+  args: { includes },
+  handler: ({ includes }) => {
+    console.log(`Processing files: ${includes.join(', ')}`);
+  },
+});
+```
+
 ### Config
 
 - `type` (required): A type from `string[]` to any value
@@ -74,3 +148,4 @@ This parser will fail to parse if:
 - `displayName`: A short description regarding the option
 - `defaultValue`: A function that returns a default value for the option array in case no options were provided. If not provided, the default value will be an empty array.
 - `defaultValueIsSerializable`: Whether to print the defaultValue as a string in the help docs.
+- `onMissing`: A function (sync or async) that returns a value when the option is not provided. Used as fallback if `defaultValue` is not provided.

example/app4.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env YARN_SILENT=1 yarn ts-node
+
+import { command, extendType, option, run, string } from "../src";
+
+const AsyncType = extendType(string, {
+	async from(str) {
+		return str;
+	},
+	onMissing: () => Promise.resolve("default value"),
+	description: "A type with onMissing callback",
+});
+
+const app = command({
+	name: "async-test",
+	args: {
+		asyncArg: option({
+			type: AsyncType,
+			long: "async-arg",
+			short: "a",
+		}),
+		asyncArg2: option({
+			long: "async-arg-2",
+			type: AsyncType,
+			defaultValue: () => "Hi",
+			defaultValueIsSerializable: true,
+		}),
+		arg3: option({
+			long: "async-arg-3",
+			type: string,
+			onMissing: () => "Hello from opt",
+		}),
+	},
+	handler: ({ asyncArg, asyncArg2, arg3 }) => {
+		console.log(`Result: ${asyncArg}, ${asyncArg2}, ${arg3}`);
+	},
+});
+
+run(app, process.argv.slice(2));

example/app5.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env YARN_SILENT=1 yarn ts-node
+
+import { command, extendType, option, run, string } from "../src";
+
+const AsyncFailureType = extendType(string, {
+	async from(str) {
+		return str;
+	},
+	onMissing: () => Promise.reject(new Error("Async onMissing failed")),
+	description: "A type with onMissing callback that fails",
+});
+
+const app = command({
+	name: "async-test-failure",
+	args: {
+		failArg: option({
+			type: AsyncFailureType,
+			long: "fail-arg",
+			short: "f",
+		}),
+	},
+	handler: ({ failArg }) => {
+		console.log(`Result: ${failArg}`);
+	},
+});
+
+run(app, process.argv.slice(2));

example/app6.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env YARN_SILENT=1 yarn ts-node
+
+import { command, flag, run } from "../src";
+
+const app = command({
+	name: "flag-onmissing-demo",
+	args: {
+		verbose: flag({
+			long: "verbose",
+			short: "v",
+			description: "Enable verbose output",
+			onMissing: () => {
+				console.log("🤔 Verbose flag not provided, checking environment...");
+				return process.env.NODE_ENV === "development";
+			},
+		}),
+		debug: flag({
+			long: "debug",
+			short: "d",
+			description: "Enable debug mode",
+			onMissing: async () => {
+				console.log("🔍 Debug flag missing, simulating config check...");
+				await new Promise((resolve) => setTimeout(resolve, 100));
+				return Math.random() > 0.5; // Simulate config-based decision
+			},
+		}),
+		force: flag({
+			long: "force",
+			short: "f",
+			description: "Force operation without confirmation",
+			onMissing: () => {
+				console.log("⚠️  Force flag not set, would normally prompt user...");
+				// In real scenario: return prompt("Force operation? (y/n)") === "y"
+				return false; // Safe default for demo
+			},
+		}),
+	},
+	handler: ({ verbose, debug, force }) => {
+		console.log("\n📋 Results:");
+		console.log(`  Verbose: ${verbose ? "✅" : "❌"}`);
+		console.log(`  Debug: ${debug ? "✅" : "❌"}`);
+		console.log(`  Force: ${force ? "✅" : "❌"}`);
+	},
+});
+
+run(app, process.argv.slice(2));