Optique 0.5.0: Enhanced error handling and message customization

[hongminhee@hackers.pub]

We're pleased to announce the release of Optique 0.5.0, which brings significant improvements to error handling, help text generation, and overall developer experience. This release maintains full backward compatibility, so you can upgrade without modifying existing code.

Better code organization through module separation

The large @optique/core/parser module has been refactored into three focused modules that better reflect their purposes. Primitive parsers like option() and argument() now live in @optique/core/primitives, modifier functions such as optional() and withDefault() have moved to @optique/core/modifiers, and combinator functions including object() and or() are now in @optique/core/constructs.

// Before: everything from one module
import { 
  option, flag, argument,        // primitives
  optional, withDefault, multiple, // modifiers
  object, or, merge              // constructs
} from "@optique/core/parser";

// After: organized imports (recommended)
import { option, flag, argument } from "@optique/core/primitives";
import { optional, withDefault, multiple } from "@optique/core/modifiers";
import { object, or, merge } from "@optique/core/constructs";

While we recommend importing from these specialized modules for better clarity, all functions continue to be re-exported from the original @optique/core/parser module to ensure your existing code works unchanged. This reorganization makes the codebase more maintainable and helps developers understand the relationships between different parser types.

Smarter error handling with automatic conversion

One of the most requested features has been better error handling for default value callbacks in withDefault(). Previously, if your callback threw an error—say, when an environment variable wasn't set—that error would bubble up as a runtime exception. Starting with 0.5.0, these errors are automatically caught and converted to parser-level errors, providing consistent error formatting and proper exit codes.

// Before (0.4.x): runtime exception that crashes the app
const parser = object({
  apiUrl: withDefault(option("--url", url()), () => {
    if (!process.env.API_URL) {
      throw new Error("API_URL not set"); // Uncaught exception!
    }
    return new URL(process.env.API_URL);
  })
});

// After (0.5.0): graceful parser error
const parser = object({
  apiUrl: withDefault(option("--url", url()), () => {
    if (!process.env.API_URL) {
      throw new Error("API_URL not set"); // Automatically caught and formatted
    }
    return new URL(process.env.API_URL);
  })
});

We've also introduced the WithDefaultError class, which accepts structured messages instead of plain strings. This means you can now throw errors with rich formatting that matches the rest of Optique's error output:

import { WithDefaultError, message, envVar } from "@optique/core";

const parser = object({
  // Plain error - automatically converted to text
  databaseUrl: withDefault(option("--db", url()), () => {
    if (!process.env.DATABASE_URL) {
      throw new Error("Database URL not configured");
    }
    return new URL(process.env.DATABASE_URL);
  }),

  // Rich error with structured message
  apiToken: withDefault(option("--token", string()), () => {
    if (!process.env.API_TOKEN) {
      throw new WithDefaultError(
        message`Environment variable ${envVar("API_TOKEN")} is required for authentication`
      );
    }
    return process.env.API_TOKEN;
  })
});

The new envVar message component ensures environment variables are visually distinct in error messages, appearing bold and underlined in colored output or wrapped in backticks in plain text.

More helpful help text with custom default descriptions

Default values in help text can sometimes be misleading, especially when they come from environment variables or are computed at runtime. Optique 0.5.0 allows you to customize how default values appear in help output through an optional third parameter to withDefault().

import { withDefault, message, envVar } from "@optique/core";

const parser = object({
  // Before: shows actual URL value in help
  apiUrl: withDefault(
    option("--api-url", url()),
    new URL("https://api.example.com")
  ),
  // Help shows: --api-url URL [https://api.example.com]

  // After: shows descriptive text
  apiUrl: withDefault(
    option("--api-url", url()),
    new URL("https://api.example.com"),
    { message: message`Default API endpoint` }
  ),
  // Help shows: --api-url URL [Default API endpoint]
});

This is particularly useful for environment variables and computed defaults:

const parser = object({
  // Environment variable
  authToken: withDefault(
    option("--token", string()),
    () => process.env.AUTH_TOKEN || "anonymous",
    { message: message`${envVar("AUTH_TOKEN")} or anonymous` }
  ),
  // Help shows: --token STRING [AUTH_TOKEN or anonymous]

  // Computed value
  workers: withDefault(
    option("--workers", integer()),
    () => os.cpus().length,
    { message: message`Number of CPU cores` }
  ),
  // Help shows: --workers INT [Number of CPU cores]

  // Sensitive information
  apiKey: withDefault(
    option("--api-key", string()),
    () => process.env.SECRET_KEY || "",
    { message: message`From secure storage` }
  ),
  // Help shows: --api-key STRING [From secure storage]
});

Instead of displaying the actual default value, you can now show descriptive text that better explains where the value comes from. This is particularly useful for sensitive information like API tokens or for computed defaults like the number of CPU cores.

The help system now properly handles ANSI color codes in default value displays, maintaining dim styling even when inner components have their own color formatting. This ensures default values remain visually distinct from the main help text.

Comprehensive error message customization

We've added a systematic way to customize error messages across all parser types and combinators. Every parser now accepts an errors option that lets you provide context-specific feedback instead of generic error messages. This applies to primitive parsers, value parsers, combinators, and even specialized parsers in companion packages.

Primitive parser errors

import { option, flag, argument, command } from "@optique/core/primitives";
import { message, optionName, metavar } from "@optique/core/message";

// Option parser with custom errors
const serverPort = option("--port", integer(), {
  errors: {
    missing: message`Server port is required. Use ${optionName("--port")} to specify.`,
    invalidValue: (error) => message`Invalid port number: ${error}`,
    endOfInput: message`${optionName("--port")} requires a ${metavar("PORT")} number.`
  }
});

// Command parser with custom errors
const deployCommand = command("deploy", deployParser, {
  errors: {
    notMatched: (expected, actual) => 
      message`Unknown command "${actual}". Did you mean "${expected}"?`
  }
});

Value parser errors

Error customization can be static messages for consistent errors or dynamic functions that incorporate the problematic input:

import { integer, choice, string } from "@optique/core/valueparser";

// Integer with range validation
const port = integer({
  min: 1024,
  max: 65535,
  errors: {
    invalidInteger: message`Port must be a valid number.`,
    belowMinimum: (value, min) =>
      message`Port ${String(value)} is reserved. Use ${String(min)} or higher.`,
    aboveMaximum: (value, max) =>
      message`Port ${String(value)} exceeds maximum. Use ${String(max)} or lower.`
  }
});

// Choice with helpful suggestions
const logLevel = choice(["debug", "info", "warn", "error"], {
  errors: {
    invalidChoice: (input, choices) =>
      message`"${input}" is not a valid log level. Choose from: ${values(choices)}.`
  }
});

// String with pattern validation
const email = string({
  pattern: /^[^@]+@[^@]+\.[^@]+$/,
  errors: {
    patternMismatch: (input) =>
      message`"${input}" is not a valid email address. Use format: user@example.com`
  }
});

Combinator errors

import { or, multiple, object } from "@optique/core/constructs";

// Or combinator with custom no-match error
const format = or(
  flag("--json"),
  flag("--yaml"),
  flag("--xml"),
  {
    errors: {
      noMatch: message`Please specify an output format: --json, --yaml, or --xml.`,
      unexpectedInput: (token) =>
        message`Unknown format option "${token}".`
    }
  }
);

// Multiple parser with count validation
const inputFiles = multiple(argument(string()), {
  min: 1,
  max: 5,
  errors: {
    tooFew: (count, min) =>
      message`At least ${String(min)} file required, but got ${String(count)}.`,
    tooMany: (count, max) =>
      message`Maximum ${String(max)} files allowed, but got ${String(count)}.`
  }
});

Package-specific errors

Both @optique/run and @optique/temporal packages have been updated with error customization support for their specialized parsers:

// @optique/run path parser
import { path } from "@optique/run/valueparser";

const configFile = option("--config", path({
  mustExist: true,
  type: "file",
  extensions: [".json", ".yaml"],
  errors: {
    pathNotFound: (input) =>
      message`Configuration file "${input}" not found. Please check the path.`,
    notAFile: (input) =>
      message`"${input}" is a directory. Please specify a file.`,
    invalidExtension: (input, extensions, actual) =>
      message`Invalid config format "${actual}". Use ${values(extensions)}.`
  }
}));

// @optique/temporal instant parser
import { instant, duration } from "@optique/temporal";

const timestamp = option("--time", instant({
  errors: {
    invalidFormat: (input) =>
      message`"${input}" is not a valid timestamp. Use ISO 8601 format: 2024-01-01T12:00:00Z`
  }
}));

const timeout = option("--timeout", duration({
  errors: {
    invalidFormat: (input) =>
      message`"${input}" is not a valid duration. Use ISO 8601 format: PT30S (30 seconds), PT5M (5 minutes)`
  }
}));

Error customization integrates seamlessly with Optique's structured message format, ensuring consistent styling across all error output. The system helps you provide helpful, actionable feedback that guides users toward correct usage rather than leaving them confused by generic error messages.

Looking forward

This release focuses on improving the developer experience without breaking existing code. Every new feature is opt-in, and all changes maintain backward compatibility. We believe these improvements make Optique more pleasant to work with, especially when building user-friendly CLI applications that need clear error messages and helpful documentation.

We're grateful to the community members who suggested these improvements and helped shape this release through discussions and issue reports. Your feedback continues to drive Optique's evolution toward being a more capable and ergonomic CLI parser for TypeScript.

To upgrade to Optique 0.5.0, simply update your dependencies:

npm update @optique/core @optique/run
# or
deno update

For detailed migration guidance and API documentation, please refer to the official documentation. While no code changes are required, we encourage you to explore the new error customization options and help text improvements to enhance your CLI applications.