Skip to content

Piero Bosio Social Web Site Personale Logo Fediverso

Social Forum federato con il resto del mondo. Non contano le istanze, contano le persone
  1. Home
  2. Categories
  3. Uncategorized
  4. Optique 0.7.0: Smarter error messages and validation library integrations

Optique 0.7.0: Smarter error messages and validation library integrations

Uncategorized
1 1 2
  • hongminhee@hackers.pubundefined

    We're thrilled to announce Optique 0.7.0, a release focused on developer experience improvements and expanding Optique's ecosystem with validation library integrations.

    Optique is a type-safe, combinatorial CLI argument parser for TypeScript. Unlike traditional CLI libraries that rely on configuration objects, Optique lets you compose parsers from small, reusable functions—bringing the same functional composition patterns that make Zod powerful to CLI development. If you're new to Optique, check out Why Optique? to learn how this approach unlocks possibilities that configuration-based libraries simply can't match.

    This release introduces automatic “Did you mean?” suggestions for typos, seamless integration with Zod and Valibot validation libraries, duplicate option name detection for catching configuration bugs early, and context-aware error messages that help users understand exactly what went wrong.

    “Did you mean?”: Automatic typo suggestions

    We've all been there: you type --verbos instead of --verbose, and the CLI responds with an unhelpful “unknown option” error. Optique 0.7.0 changes this by automatically suggesting similar options when users make typos:

    const parser = object({
  verbose: option("-v", "--verbose"),
  version: option("--version"),
});

// User types: --verbos (typo)
const result = parse(parser, ["--verbos"]);
// Error: Unexpected option or argument: --verbos.
//
// Did you mean one of these?
//   --verbose
//   --version

    The suggestion system uses Levenshtein distance to find similar names, suggesting up to 3 alternatives when the edit distance is within a reasonable threshold. Suggestions work automatically for both option names and subcommand names across all parser types—option(), flag(), command(), object(), or(), and longestMatch(). See the automatic suggestions documentation for more details.

    Customizing suggestions

    You can customize how suggestions are formatted or disable them entirely through the errors option:

    // Custom suggestion format for option/flag parsers
const portOption = option("--port", integer(), {
  errors: {
    noMatch: (invalidOption, suggestions) =>
      suggestions.length > 0
        ? message`Unknown option ${invalidOption}. Try: ${values(suggestions)}`
        : message`Unknown option ${invalidOption}.`
  }
});

// Custom suggestion format for combinators
const config = object({
  host: option("--host", string()),
  port: option("--port", integer())
}, {
  errors: {
    suggestions: (suggestions) =>
      suggestions.length > 0
        ? message`Available options: ${values(suggestions)}`
        : []
  }
});

    Zod and Valibot integrations

    Two new packages join the Optique family, bringing powerful validation capabilities from the TypeScript ecosystem to your CLI parsers.

    @optique/zod

    The new @optique/zod package lets you use Zod schemas directly as value parsers:

    import { option, object } from "@optique/core";
import { zod } from "@optique/zod";
import { z } from "zod";

const parser = object({
  email: option("--email", zod(z.string().email())),
  port: option("--port", zod(z.coerce.number().int().min(1).max(65535))),
  format: option("--format", zod(z.enum(["json", "yaml", "xml"]))),
});

    The package supports both Zod v3.25.0+ and v4.0.0+, with automatic error formatting that integrates seamlessly with Optique's message system. See the Zod integration guide for complete usage examples.

    @optique/valibot

    For those who prefer a lighter bundle, @optique/valibot integrates with Valibot—a validation library with a significantly smaller footprint (~10KB vs Zod's ~52KB):

    import { option, object } from "@optique/core";
import { valibot } from "@optique/valibot";
import * as v from "valibot";

const parser = object({
  email: option("--email", valibot(v.pipe(v.string(), v.email()))),
  port: option("--port", valibot(v.pipe(
    v.string(),
    v.transform(Number),
    v.integer(),
    v.minValue(1),
    v.maxValue(65535)
  ))),
});

    Both packages support custom error messages through their respective error handler options (zodError and valibotError), giving you full control over how validation failures are presented to users. See the Valibot integration guide for complete usage examples.

    Duplicate option name detection

    A common source of bugs in CLI applications is accidentally using the same option name in multiple places. Previously, this would silently cause ambiguous parsing where the first matching parser consumed the option.

    Optique 0.7.0 now validates option names at parse time and fails with a clear error message when duplicates are detected:

    const parser = object({
  input: option("-i", "--input", string()),
  interactive: option("-i", "--interactive"),  // Oops! -i is already used
});

// Error: Duplicate option name -i found in fields: input, interactive.
// Each option name must be unique within a parser combinator.

    This validation applies to object(), tuple(), merge(), and group() combinators. The or() combinator continues to allow duplicate option names since its branches are mutually exclusive. See the duplicate detection documentation for more details.

    If you have a legitimate use case for duplicate option names, you can opt out with allowDuplicates: true:

    const parser = object({
  input: option("-i", "--input", string()),
  interactive: option("-i", "--interactive"),
}, { allowDuplicates: true });

    Context-aware error messages

    Error messages from combinators are now smarter about what they report. Instead of generic "No matching option or command found" messages, Optique now analyzes what the parser expects and provides specific feedback:

    // When only arguments are expected
const parser1 = or(argument(string()), argument(integer()));
// Error: Missing required argument.

// When only commands are expected
const parser2 = or(command("add", addParser), command("remove", removeParser));
// Error: No matching command found.

// When both options and arguments are expected
const parser3 = object({
  port: option("--port", integer()),
  file: argument(string()),
});
// Error: No matching option or argument found.

    Dynamic error messages with NoMatchContext

    For applications that need internationalization or context-specific messaging, the errors.noMatch option now accepts a function that receives a NoMatchContext object:

    const parser = or(
  command("add", addParser),
  command("remove", removeParser),
  {
    errors: {
      noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
        if (hasCommands && !hasOptions && !hasArguments) {
          return message`일치하는 명령을 찾을 수 없습니다.`;  // Korean
        }
        return message`잘못된 입력입니다.`;
      }
    }
  }
);

    Shell completion naming conventions

    The run() function now supports configuring whether shell completions use singular or plural naming conventions:

    run(parser, {
  completion: {
    name: "plural",  // Uses "completions" and "--completions"
  }
});

// Or for singular only
run(parser, {
  completion: {
    name: "singular",  // Uses "completion" and "--completion"
  }
});

    The default "both" accepts either form, maintaining backward compatibility while letting you enforce a consistent style in your CLI.

    Additional improvements

    • Line break handling: formatMessage() now distinguishes between soft breaks (single \n, converted to spaces) and hard breaks (double \n\n, creating paragraph separations), improving multi-line error message formatting.

    • New utility functions: Added extractOptionNames() and extractArgumentMetavars() to the @optique/core/usage module for programmatic access to parser metadata.

    Installation

    deno add --jsr @optique/core @optique/run
npm  add       @optique/core @optique/run
pnpm add       @optique/core @optique/run
yarn add       @optique/core @optique/run
bun  add       @optique/core @optique/run

    For validation library integrations:

    # Zod integration
deno add jsr:@optique/zod     # Deno
npm  add     @optique/zod      # npm/pnpm/yarn/bun

# Valibot integration
deno add jsr:@optique/valibot  # Deno
npm  add     @optique/valibot  # npm/pnpm/yarn/bun

    Looking forward

    This release represents our commitment to making CLI development in TypeScript as smooth as possible. The “Did you mean?” suggestions and validation library integrations were among the most requested features, and we're excited to see how they improve your CLI applications.

    For detailed documentation and examples, visit the Optique documentation. We welcome your feedback and contributions on GitHub!

    1
    0
  • hongminhee@hollo.socialundefined hongminhee@hollo.social shared this topic
Log in to reply

Feed RSS
Optique 0.7.0: Smarter error messages and validation library integrations

Gli ultimi otto messaggi ricevuti dalla Federazione
@pierobosio@soc.bosio.info
Post suggeriti
  • fedify@hollo.socialundefined

    Exciting news for #Fedify developers!

    Uncategorized bun cli deno node fedify javascript
    1
    0 Votes
    1 Posts
    9 Views
    fedify@hollo.socialundefined
    Exciting news for #Fedify developers! We've just landed a major milestone for Fedify 2.0—the #CLI now runs natively on #Node.js and #Bun, not just #Deno (#456). If you install @fedify/cli@2.0.0-dev.1761 from npm, you'll get actual JavaScript that executes directly in your runtime, no more pre-compiled binaries from deno compile. This is part of our broader transition to Optique, a new cross-runtime CLI framework we've developed specifically for Fedify's needs (#374). This change means a more natural development experience regardless of your #JavaScript runtime preference. Node.js developers can now run the CLI tools directly through their familiar ecosystem, and the same goes for Bun users. While Fedify 2.0 isn't released yet, we're excited to share this progress with the community—feel free to try out the dev version and let us know how it works for you!
  • hongminhee@hackers.pubundefined

    Optique 0.6.0: Shell completion support for type-safe CLI parsers

    Uncategorized optique cli cli-parser shell shell-completion completion bash zsh
    1
    0 Votes
    1 Posts
    7 Views
    hongminhee@hackers.pubundefined
    Optique 0.6.0 is here, bringing intelligent shell completion to your type-safe command-line applications. This release introduces built-in completion support for Bash, zsh, fish, PowerShell, and Nushell, making your CLIs more discoverable and user-friendly—all without sacrificing type safety or requiring duplicate definitions. For those new to [Optique]: it's a TypeScript CLI parser library that takes a fundamentally different approach from traditional configuration-based parsers. Instead of describing your CLI with configuration objects, you compose parsers from small, type-safe functions. TypeScript automatically infers the exact types of your parsed data, ensuring compile-time safety while the parser structure itself provides runtime validation. Think of it as bringing the composability of parser combinators (inspired by Haskell's optparse-applicative) together with the type safety of TypeScript's type system. Shell completion that just works The standout feature of this release is comprehensive shell completion support. Unlike many CLI frameworks that require separate completion definitions, Optique's completion system leverages the same parser structure used for argument parsing. This means your completion suggestions automatically stay synchronized with your CLI's actual behavior—no duplicate definitions, no manual maintenance. import { object } from "@optique/core/constructs"; import { argument, option } from "@optique/core/primitives"; import { string, choice } from "@optique/core/valueparser"; import { run } from "@optique/run"; const parser = object({ format: option("-f", "--format", choice(["json", "yaml", "xml"])), output: option("-o", "--output", string({ metavar: "FILE" })), verbose: option("-v", "--verbose"), input: argument(string({ metavar: "INPUT" })), }); // Enable completion with a single option const config = run(parser, { completion: "both" }); Users can now press Tab to get intelligent suggestions: myapp <TAB> # Shows available commands and options myapp --format <TAB> # Shows: json, yaml, xml myapp --format=<TAB> # Same suggestions with equals syntax myapp -<TAB> # Shows: -f, -o, -v, and other short options Setting up completion is straightforward. Users generate a completion script for their shell and source it: # Bash myapp completion bash > ~/.bashrc.d/myapp.bash source ~/.bashrc.d/myapp.bash # zsh myapp completion zsh > ~/.zsh/completions/_myapp # fish myapp completion fish > ~/.config/fish/completions/myapp.fish # PowerShell myapp completion pwsh > myapp-completion.ps1 . ./myapp-completion.ps1 # Nushell myapp completion nu | save myapp-completion.nu source myapp-completion.nu The completion system works automatically with all Optique parser types. When you use choice() value parsers, the available options become completion suggestions. When you use path() parsers, file system completion kicks in with proper handling of extensions and file types. Subcommands, options, and arguments all provide context-aware suggestions. What makes Optique's completion special is that it leverages the same parser structure used for argument parsing. Every parser has an optional suggest() method that provides context-aware suggestions based on the current input. Parser combinators like object() and or() automatically aggregate suggestions from their constituent parsers, ensuring your completion logic stays in your TypeScript code where it benefits from type safety and testing. Optique handles the differences between shells transparently. Bash uses the complete command with proper handling of word splitting, zsh leverages its powerful compdef system with completion descriptions, fish provides tab-separated format with automatic file type detection, PowerShell uses Register-ArgumentCompleter with AST-based parsing, and Nushell integrates with its external completer system. For file and directory completions, Optique delegates to each shell's native file completion system, ensuring proper handling of spaces, symlinks, and platform-specific path conventions. Custom completion suggestions For domain-specific value parsers, you can implement custom completion logic that provides intelligent suggestions based on your application's needs: import type { ValueParser, ValueParserResult } from "@optique/core/valueparser"; import type { Suggestion } from "@optique/core/parser"; import { message } from "@optique/core/message"; function httpMethod(): ValueParser<string> { const methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]; return { metavar: "METHOD", parse(input: string): ValueParserResult<string> { const method = input.toUpperCase(); if (methods.includes(method)) { return { success: true, value: method }; } return { success: false, error: message`Invalid HTTP method: ${input}. Valid methods: ${methods.join(", ")}.`, }; }, format(value: string): string { return value; }, *suggest(prefix: string): Iterable<Suggestion> { for (const method of methods) { if (method.toLowerCase().startsWith(prefix.toLowerCase())) { yield { kind: "literal", text: method, description: message`HTTP ${method} request method` }; } } }, }; } The built-in value parsers also provide intelligent suggestions. For instance, the locale() parser suggests common locale identifiers, the url() parser offers protocol completions when configured with allowedProtocols, and the timezone parsers from @optique/temporal use Intl.supportedValuesOf() for dynamic timezone suggestions. Enhanced command documentation This release also introduces new documentation capabilities for the command() parser. You can now provide separate brief and description texts, along with a footer for examples and additional information: import { command, object, constant } from "@optique/core/primitives"; import { message } from "@optique/core/message"; const deployCommand = command( "deploy", object({ action: constant("deploy"), // ... options }), { brief: message`Deploy application to production`, // Shown in command list description: message`Deploy the application to the production environment. This command handles database migrations, asset compilation, and cache warming automatically. It performs health checks before switching traffic to ensure zero-downtime deployment.`, // Shown in detailed help footer: message`Examples: myapp deploy --environment staging --dry-run myapp deploy --environment production --force For deployment documentation, see: https://docs.example.com/deploy` } ); The brief text appears when listing commands (like myapp help), while description provides detailed information when viewing command-specific help (myapp deploy --help or myapp help deploy). The footer appears at the bottom of the help text, perfect for examples and additional resources. Command-line example formatting To make help text and examples clearer, we've added a new commandLine() message term type. This displays command-line snippets with distinct cyan coloring in terminals, making it immediately clear what users should type: import { message, commandLine } from "@optique/core/message"; import { run } from "@optique/run"; const config = run(parser, { footer: message`Examples: ${commandLine("myapp --format json input.txt")} ${commandLine("myapp --format=yaml --output result.yml data.txt")} To enable shell completion: ${commandLine("myapp completion bash > ~/.bashrc.d/myapp.bash")} ${commandLine("source ~/.bashrc.d/myapp.bash")}`, completion: "both" }); These command examples stand out visually in help text, making it easier for users to understand how to use your CLI. Migration guide If you're already using Optique, adding completion support is straightforward: Update to Optique 0.6.0 Add the completion option to your run() configuration: // Before const config = run(parser, { help: "both" }); // After const config = run(parser, { help: "both", completion: "both" // Adds both 'completion' command and '--completion' option }); That's it! Your CLI now supports shell completion. The completion option accepts three modes: "command": Only the completion subcommand (e.g., myapp completion bash) "option": Only the --completion option (e.g., myapp --completion bash) "both": Both patterns work For custom value parsers, you can optionally add a suggest() method to provide domain-specific completions. Existing parsers continue to work without modification—they just won't provide custom suggestions beyond what the parser structure implies. Looking forward Shell completion has been one of the most requested features for Optique, and we're thrilled to deliver it in a way that maintains our core principles: type safety, composability, and zero duplication. Your parser definitions remain the single source of truth for both parsing and completion behavior. This release represents a significant step toward making Optique-based CLIs as user-friendly as they are developer-friendly. The completion system proves that we can provide sophisticated runtime features without sacrificing the compile-time guarantees that make Optique unique. We hope you find the new shell completion feature useful and look forward to seeing what you build with it! Getting started To start using Optique 0.6.0: deno add --jsr @optique/core@^0.6.0 @optique/run@^0.6.0 npm add @optique/core@^0.6.0 @optique/run@^0.6.0 pnpm add @optique/core@^0.6.0 @optique/run@^0.6.0 yarn add @optique/core@^0.6.0 @optique/run@^0.6.0 bun add @optique/core@^0.6.0 @optique/run@^0.6.0 For complete documentation, visit optique.dev. Check out the new shell completion guide for detailed setup instructions and advanced usage patterns. For bug reports and feature requests, please visit our GitHub repository.
  • hongminhee@hackers.pubundefined

    Stop writing CLI validation. Parse it right the first time.

    Uncategorized cli validation parsing parser parser-combinators combinators optique options
    2
    0 Votes
    2 Posts
    15 Views
    badrihippo@fosstodon.orgundefined
    @hongminhee this is cool! I've never used NodeJS CLI apps, but I run into similar issues to the ones you described when using Python
  • botkit@hollo.socialundefined

    Introducing #BotKit: A #TypeScript framework for creating truly standalone #ActivityPub bots!

    General Discussion deno botkit fediverse typescript activitypub
    1
    0 Votes
    1 Posts
    15 Views
    botkit@hollo.socialundefined
    :botkit: Introducing #BotKit: A #TypeScript framework for creating truly standalone #ActivityPub bots! Unlike traditional Mastodon bots, BotKit lets you build fully independent #fediverse bots that aren't constrained by platform limits. Create your entire bot in a single TypeScript file using our simple, expressive API. Currently #Deno-only, with Node.js & Bun support planned. Built on the robust @fedify@hollo.social foundation. https://botkit.fedify.dev/