@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/dependency.cjs

@@ -66,6 +66,7 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 * // Create a derived parser that depends on the directory
 * const branchParser = cwdParser.derive({
 *   metavar: "BRANCH",
+*   mode: "sync",
 *   factory: (dir) => gitBranch({ dir }),
 *   defaultValue: () => process.cwd(),
 * });
@@ -79,14 +80,15 @@ function dependency(parser) {
 		[dependencySourceMarker]: true,
 		[dependencyId]: id,
 		derive(options) {
-			return createDerivedValueParser(id, parser, options);
+			if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("derive() requires an explicit mode field (\"sync\" or \"async\").");
+			return createDerivedValueParser(id, parser, options, options.mode);
 		},
 		deriveSync(options) {
 			if (parser.$mode === "async") return createAsyncDerivedParserFromSyncFactory(id, options);
 			return createSyncDerivedParser(id, options);
 		},
 		deriveAsync(options) {
-			return createDerivedValueParser(id, parser, options);
+			return createAsyncDerivedParserFromAsyncFactory(id, options);
 		}
 	};
 	return result;
@@ -132,6 +134,7 @@ function isDerivedValueParser(parser) {
 *
 * const configParser = deriveFrom({
 *   metavar: "CONFIG",
+*   mode: "sync",
 *   dependencies: [dirParser, modeParser] as const,
 *   factory: (dir, mode) =>
 *     choice(mode === "dev"
@@ -140,12 +143,14 @@ function isDerivedValueParser(parser) {
 *   defaultValues: () => ["/config", "dev"],
 * });
 * ```
+* @throws {TypeError} If the `mode` field is missing or invalid.
 * @since 0.10.0
 */
 function deriveFrom(options) {
+	if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("deriveFrom() requires an explicit mode field (\"sync\" or \"async\").");
 	const depsAsync = options.dependencies.some((dep) => dep.$mode === "async");
-	const factoryReturnsAsync = determineFactoryModeForDeriveFrom(options);
 	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const factoryReturnsAsync = options.mode === "async";
 	const isAsync = depsAsync || factoryReturnsAsync;
 	if (isAsync) {
 		if (factoryReturnsAsync) return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
@@ -191,14 +196,6 @@ function deriveFromAsync(options) {
 	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
 	return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
 }
-/**
-* Determines if the factory returns an async parser for deriveFrom options.
-*/
-function determineFactoryModeForDeriveFrom(options) {
-	const defaultValues$1 = options.defaultValues();
-	const parser = options.factory(...defaultValues$1);
-	return parser.$mode === "async";
-}
 function isAsyncModeParser(parser) {
 	return parser.$mode === "async";
 }
@@ -212,8 +209,17 @@ function createSyncDerivedFromParser(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				};
+			}
 			if (isAsyncModeParser(derivedParser)) return {
 				success: false,
 				error: require_message.message`Factory returned an async parser where a sync parser is required.`
@@ -238,14 +244,25 @@ function createSyncDerivedFromParser(sourceId, options) {
 			return derivedParser.parse(input);
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		*suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
@@ -259,7 +276,8 @@ function createSyncDerivedFromParser(sourceId, options) {
 					return;
 				}
 			}
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		}
 	};
 }
@@ -277,9 +295,18 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
-			return derivedParser.parse(input);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				});
+			}
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
 			let derivedParser;
@@ -292,16 +319,26 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 					error: require_message.message`Factory error: ${msg}`
 				});
 			}
-			return derivedParser.parse(input);
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		},
 		async *[suggestWithDependency](prefix, dependencyValue) {
@@ -334,8 +371,17 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				});
+			}
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -352,13 +398,23 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
@@ -377,8 +433,8 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 		}
 	};
 }
-function createDerivedValueParser(sourceId, sourceParser, options) {
-	const factoryReturnsAsync = determineFactoryMode(options);
+function createDerivedValueParser(sourceId, sourceParser, options, factoryMode) {
+	const factoryReturnsAsync = factoryMode === "async";
 	const isAsync = sourceParser.$mode === "async" || factoryReturnsAsync;
 	if (isAsync) {
 		if (factoryReturnsAsync) return createAsyncDerivedParserFromAsyncFactory(sourceId, options);
@@ -386,15 +442,6 @@ function createDerivedValueParser(sourceId, sourceParser, options) {
 	}
 	return createSyncDerivedParser(sourceId, options);
 }
-/**
-* Determines if the factory returns an async parser by calling it with
-* the default value and checking the mode.
-*/
-function determineFactoryMode(options) {
-	const defaultValue = options.defaultValue();
-	const parser = options.factory(defaultValue);
-	return parser.$mode === "async";
-}
 function createSyncDerivedParser(sourceId, options) {
 	return {
 		$mode: "sync",
@@ -402,8 +449,17 @@ function createSyncDerivedParser(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				};
+			}
 			if (isAsyncModeParser(derivedParser)) return {
 				success: false,
 				error: require_message.message`Factory returned an async parser where a sync parser is required.`
@@ -428,14 +484,25 @@ function createSyncDerivedParser(sourceId, options) {
 			return derivedParser.parse(input);
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		*suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
@@ -448,7 +515,8 @@ function createSyncDerivedParser(sourceId, options) {
 					return;
 				}
 			}
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		}
 	};
 }
@@ -463,9 +531,18 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
-			return derivedParser.parse(input);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				});
+			}
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
 			let derivedParser;
@@ -478,16 +555,26 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 					error: require_message.message`Factory error: ${msg}`
 				});
 			}
-			return derivedParser.parse(input);
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		},
 		async *[suggestWithDependency](prefix, dependencyValue) {
@@ -516,8 +603,17 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: require_message.message`Derived parser error: ${msg}`
+				});
+			}
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -534,13 +630,23 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {

package/dist/dependency.d.cts

@@ -77,7 +77,7 @@ interface DeriveOptions<S, T, FM extends Mode = Mode> {
    * @param sourceValue The value parsed from the dependency source.
    * @returns A {@link ValueParser} for the derived value.
    */
-  readonly factory: (sourceValue: S) => ValueParser<FM, T>;
+  readonly factory: (sourceValue: S) => ValueParser<NoInfer<FM>, T>;
   /**
    * Default value to use when the dependency source is not provided.
    * This allows the derived parser to work even when the dependency
@@ -86,6 +86,14 @@ interface DeriveOptions<S, T, FM extends Mode = Mode> {
    * @returns The default value for the dependency source.
    */
   readonly defaultValue: () => S;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
 }
 /**
  * Options for creating a derived value parser with a synchronous factory.
@@ -165,6 +173,7 @@ interface DependencySource<M extends Mode = "sync", T = unknown> extends ValuePa
    * @template FM The mode of the factory's returned parser.
    * @param options Configuration for the derived parser.
    * @returns A {@link DerivedValueParser} that depends on this source.
+   * @throws {TypeError} If the `mode` field is missing or invalid.
    */
   derive<U, FM extends Mode = "sync">(options: DeriveOptions<T, U, FM>): DerivedValueParser<CombineMode<M, FM>, U, T>;
   /**
@@ -247,7 +256,7 @@ interface DeriveFromOptions<Deps extends readonly AnyDependencySource[], T, FM e
    * @param values The values parsed from the dependency sources (in order).
    * @returns A {@link ValueParser} for the derived value.
    */
-  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<FM, T>;
+  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<NoInfer<FM>, T>;
   /**
    * Default values to use when the dependency sources are not provided.
    * Must return a tuple with the same length and types as the dependencies.
@@ -255,6 +264,14 @@ interface DeriveFromOptions<Deps extends readonly AnyDependencySource[], T, FM e
    * @returns A tuple of default values for each dependency source.
    */
   readonly defaultValues: () => DependencyValues<Deps>;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
 }
 /**
  * Options for creating a derived value parser from multiple dependencies
@@ -390,6 +407,7 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  * // Create a derived parser that depends on the directory
  * const branchParser = cwdParser.derive({
  *   metavar: "BRANCH",
+ *   mode: "sync",
  *   factory: (dir) => gitBranch({ dir }),
  *   defaultValue: () => process.cwd(),
  * });
@@ -434,6 +452,7 @@ declare function isDerivedValueParser<M extends Mode, T>(parser: ValueParser<M,
  *
  * const configParser = deriveFrom({
  *   metavar: "CONFIG",
+ *   mode: "sync",
  *   dependencies: [dirParser, modeParser] as const,
  *   factory: (dir, mode) =>
  *     choice(mode === "dev"
@@ -442,6 +461,7 @@ declare function isDerivedValueParser<M extends Mode, T>(parser: ValueParser<M,
  *   defaultValues: () => ["/config", "dev"],
  * });
  * ```
+ * @throws {TypeError} If the `mode` field is missing or invalid.
  * @since 0.10.0
  */
 declare function deriveFrom<Deps extends readonly AnyDependencySource[], T, FM extends Mode = "sync">(options: DeriveFromOptions<Deps, T, FM>): DerivedValueParser<CombineMode<CombinedDependencyMode<Deps>, FM>, T, DependencyValues<Deps>>;

package/dist/dependency.d.ts

@@ -77,7 +77,7 @@ interface DeriveOptions<S, T, FM extends Mode = Mode> {
    * @param sourceValue The value parsed from the dependency source.
    * @returns A {@link ValueParser} for the derived value.
    */
-  readonly factory: (sourceValue: S) => ValueParser<FM, T>;
+  readonly factory: (sourceValue: S) => ValueParser<NoInfer<FM>, T>;
   /**
    * Default value to use when the dependency source is not provided.
    * This allows the derived parser to work even when the dependency
@@ -86,6 +86,14 @@ interface DeriveOptions<S, T, FM extends Mode = Mode> {
    * @returns The default value for the dependency source.
    */
   readonly defaultValue: () => S;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
 }
 /**
  * Options for creating a derived value parser with a synchronous factory.
@@ -165,6 +173,7 @@ interface DependencySource<M extends Mode = "sync", T = unknown> extends ValuePa
    * @template FM The mode of the factory's returned parser.
    * @param options Configuration for the derived parser.
    * @returns A {@link DerivedValueParser} that depends on this source.
+   * @throws {TypeError} If the `mode` field is missing or invalid.
    */
   derive<U, FM extends Mode = "sync">(options: DeriveOptions<T, U, FM>): DerivedValueParser<CombineMode<M, FM>, U, T>;
   /**
@@ -247,7 +256,7 @@ interface DeriveFromOptions<Deps extends readonly AnyDependencySource[], T, FM e
    * @param values The values parsed from the dependency sources (in order).
    * @returns A {@link ValueParser} for the derived value.
    */
-  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<FM, T>;
+  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<NoInfer<FM>, T>;
   /**
    * Default values to use when the dependency sources are not provided.
    * Must return a tuple with the same length and types as the dependencies.
@@ -255,6 +264,14 @@ interface DeriveFromOptions<Deps extends readonly AnyDependencySource[], T, FM e
    * @returns A tuple of default values for each dependency source.
    */
   readonly defaultValues: () => DependencyValues<Deps>;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
 }
 /**
  * Options for creating a derived value parser from multiple dependencies
@@ -390,6 +407,7 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
  * // Create a derived parser that depends on the directory
  * const branchParser = cwdParser.derive({
  *   metavar: "BRANCH",
+ *   mode: "sync",
  *   factory: (dir) => gitBranch({ dir }),
  *   defaultValue: () => process.cwd(),
  * });
@@ -434,6 +452,7 @@ declare function isDerivedValueParser<M extends Mode, T>(parser: ValueParser<M,
  *
  * const configParser = deriveFrom({
  *   metavar: "CONFIG",
+ *   mode: "sync",
  *   dependencies: [dirParser, modeParser] as const,
  *   factory: (dir, mode) =>
  *     choice(mode === "dev"
@@ -442,6 +461,7 @@ declare function isDerivedValueParser<M extends Mode, T>(parser: ValueParser<M,
  *   defaultValues: () => ["/config", "dev"],
  * });
  * ```
+ * @throws {TypeError} If the `mode` field is missing or invalid.
  * @since 0.10.0
  */
 declare function deriveFrom<Deps extends readonly AnyDependencySource[], T, FM extends Mode = "sync">(options: DeriveFromOptions<Deps, T, FM>): DerivedValueParser<CombineMode<CombinedDependencyMode<Deps>, FM>, T, DependencyValues<Deps>>;