@optique/core 0.4.1 → 0.5.0-dev.63

package/dist/index.cjs

@@ -6,6 +6,7 @@ const require_parser = require('./parser.cjs');
 const require_facade = require('./facade.cjs');
 
 exports.RunError = require_facade.RunError;
+exports.WithDefaultError = require_parser.WithDefaultError;
 exports.argument = require_parser.argument;
 exports.choice = require_valueparser.choice;
 exports.command = require_parser.command;

package/dist/index.d.cts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
-import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.d.ts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.js

@@ -2,7 +2,7 @@ import { formatMessage, message, metavar, optionName, optionNames, text, value,
 import { formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { RunError, WithDefaultError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/parser.cjs

@@ -523,6 +523,40 @@ function optional(parser) {
 	};
 }
 /**
+* Error type for structured error messages in {@link withDefault} default value callbacks.
+* Unlike regular errors that only support string messages, this error type accepts
+* a {@link Message} object that supports rich formatting, colors, and structured content.
+*
+* @example
+* ```typescript
+* withDefault(option("--url", url()), () => {
+*   if (!process.env.INSTANCE_URL) {
+*     throw new WithDefaultError(
+*       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+*     );
+*   }
+*   return new URL(process.env.INSTANCE_URL);
+* })
+* ```
+*
+* @since 0.5.0
+*/
+var WithDefaultError = class extends Error {
+	/**
+	* The structured message associated with this error.
+	*/
+	errorMessage;
+	/**
+	* Creates a new WithDefaultError with a structured message.
+	* @param message The structured {@link Message} describing the error.
+	*/
+	constructor(message$1) {
+		super(require_message.formatMessage(message$1));
+		this.errorMessage = message$1;
+		this.name = "WithDefaultError";
+	}
+};
+/**
 * Creates a parser that makes another parser use a default value when it fails
 * to match or consume input. This is similar to {@link optional}, but instead
 * of returning `undefined` when the wrapped parser doesn't match, it returns
@@ -563,10 +597,18 @@ function withDefault(parser, defaultValue) {
 			return result;
 		},
 		complete(state) {
-			if (typeof state === "undefined") return {
-				success: true,
-				value: typeof defaultValue === "function" ? defaultValue() : defaultValue
-			};
+			if (typeof state === "undefined") try {
+				const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				return {
+					success: true,
+					value
+				};
+			} catch (error) {
+				return {
+					success: false,
+					error: error instanceof WithDefaultError ? error.errorMessage : require_message.message`${require_message.text(String(error))}`
+				};
+			}
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, upperDefaultValue) {
@@ -1645,6 +1687,7 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
+exports.WithDefaultError = WithDefaultError;
 exports.argument = argument;
 exports.command = command;
 exports.concat = concat;

package/dist/parser.d.cts

@@ -276,6 +276,36 @@ declare function argument<T>(valueParser: ValueParser<T>, options?: ArgumentOpti
  *          or `undefined` if the wrapped parser fails to match.
  */
 declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parser<TValue | undefined, [TState] | undefined>;
+/**
+ * Error type for structured error messages in {@link withDefault} default value callbacks.
+ * Unlike regular errors that only support string messages, this error type accepts
+ * a {@link Message} object that supports rich formatting, colors, and structured content.
+ *
+ * @example
+ * ```typescript
+ * withDefault(option("--url", url()), () => {
+ *   if (!process.env.INSTANCE_URL) {
+ *     throw new WithDefaultError(
+ *       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+ *     );
+ *   }
+ *   return new URL(process.env.INSTANCE_URL);
+ * })
+ * ```
+ *
+ * @since 0.5.0
+ */
+declare class WithDefaultError extends Error {
+  /**
+   * The structured message associated with this error.
+   */
+  readonly errorMessage: Message;
+  /**
+   * Creates a new WithDefaultError with a structured message.
+   * @param message The structured {@link Message} describing the error.
+   */
+  constructor(message: Message);
+}
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -1431,4 +1461,4 @@ declare function group<TValue, TState>(label: string, parser: Parser<TValue, TSt
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.d.ts

@@ -276,6 +276,36 @@ declare function argument<T>(valueParser: ValueParser<T>, options?: ArgumentOpti
  *          or `undefined` if the wrapped parser fails to match.
  */
 declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parser<TValue | undefined, [TState] | undefined>;
+/**
+ * Error type for structured error messages in {@link withDefault} default value callbacks.
+ * Unlike regular errors that only support string messages, this error type accepts
+ * a {@link Message} object that supports rich formatting, colors, and structured content.
+ *
+ * @example
+ * ```typescript
+ * withDefault(option("--url", url()), () => {
+ *   if (!process.env.INSTANCE_URL) {
+ *     throw new WithDefaultError(
+ *       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+ *     );
+ *   }
+ *   return new URL(process.env.INSTANCE_URL);
+ * })
+ * ```
+ *
+ * @since 0.5.0
+ */
+declare class WithDefaultError extends Error {
+  /**
+   * The structured message associated with this error.
+   */
+  readonly errorMessage: Message;
+  /**
+   * Creates a new WithDefaultError with a structured message.
+   * @param message The structured {@link Message} describing the error.
+   */
+  constructor(message: Message);
+}
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -1431,4 +1461,4 @@ declare function group<TValue, TState>(label: string, parser: Parser<TValue, TSt
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { message, metavar, optionName, optionNames, text, values } from "./message.js";
+import { formatMessage, message, metavar, optionName, optionNames, text, values } from "./message.js";
 import { normalizeUsage } from "./usage.js";
 import { isValueParser } from "./valueparser.js";
 
@@ -523,6 +523,40 @@ function optional(parser) {
 	};
 }
 /**
+* Error type for structured error messages in {@link withDefault} default value callbacks.
+* Unlike regular errors that only support string messages, this error type accepts
+* a {@link Message} object that supports rich formatting, colors, and structured content.
+*
+* @example
+* ```typescript
+* withDefault(option("--url", url()), () => {
+*   if (!process.env.INSTANCE_URL) {
+*     throw new WithDefaultError(
+*       message`Environment variable ${text("INSTANCE_URL")} is not set.`
+*     );
+*   }
+*   return new URL(process.env.INSTANCE_URL);
+* })
+* ```
+*
+* @since 0.5.0
+*/
+var WithDefaultError = class extends Error {
+	/**
+	* The structured message associated with this error.
+	*/
+	errorMessage;
+	/**
+	* Creates a new WithDefaultError with a structured message.
+	* @param message The structured {@link Message} describing the error.
+	*/
+	constructor(message$1) {
+		super(formatMessage(message$1));
+		this.errorMessage = message$1;
+		this.name = "WithDefaultError";
+	}
+};
+/**
 * Creates a parser that makes another parser use a default value when it fails
 * to match or consume input. This is similar to {@link optional}, but instead
 * of returning `undefined` when the wrapped parser doesn't match, it returns
@@ -563,10 +597,18 @@ function withDefault(parser, defaultValue) {
 			return result;
 		},
 		complete(state) {
-			if (typeof state === "undefined") return {
-				success: true,
-				value: typeof defaultValue === "function" ? defaultValue() : defaultValue
-			};
+			if (typeof state === "undefined") try {
+				const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				return {
+					success: true,
+					value
+				};
+			} catch (error) {
+				return {
+					success: false,
+					error: error instanceof WithDefaultError ? error.errorMessage : message`${text(String(error))}`
+				};
+			}
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, upperDefaultValue) {
@@ -1645,4 +1687,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.4.1",
+  "version": "0.5.0-dev.63+48ac6884",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",