@optique/derived-defaults 1.2.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+@optique/derived-defaults
+=========================
+
+Derived default value support for [Optique].
+
+This package lets CLI applications compute default values from the first-pass
+parse result while keeping clear priority handling:
+
+CLI arguments > derived defaults > static defaults.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/derived-defaults
+npm add @optique/derived-defaults
+pnpm add @optique/derived-defaults
+yarn add @optique/derived-defaults
+bun add @optique/derived-defaults
+~~~~
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
+import { string } from "@optique/core/valueparser";
+import { runAsync } from "@optique/run";
+import {
+  bindDerivedDefault,
+  createDerivedDefaults,
+} from "@optique/derived-defaults";
+
+const derived = createDerivedDefaults({
+  workspaceRoot: (parsed: { readonly serviceRoot?: string }) =>
+    parsed.serviceRoot == null
+      ? undefined
+      : `${parsed.serviceRoot}/workspace`,
+});
+
+const parser = object({
+  serviceRoot: option("--service-root", string()),
+  workspaceRoot: bindDerivedDefault(option("--workspace-root", string()), {
+    context: derived.context,
+    key: "workspaceRoot",
+  }),
+});
+
+const result = await runAsync(parser, {
+  args: ["--service-root", "/srv/app"],
+  contexts: [derived.context],
+});
+
+console.log(result);
+~~~~
+
+
+Features
+--------
+
+ -  *Two-pass defaults* derived from already parsed CLI values
+ -  *Async resolver support* with `runAsync()`/`runWith()`
+ -  *Fallback validation* through the wrapped Optique parser
+ -  *Custom help text* for values that are computed at runtime
+ -  *Composable contexts* with `run()`/`runAsync()`/`runWith()`
+
+
+Documentation
+-------------
+
+For full documentation, visit
+<https://optique.dev/concepts/derived-defaults>.
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/index.cjs

@@ -0,0 +1,348 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_message = __toESM(require("@optique/core/message"));
+const __optique_core_extension = __toESM(require("@optique/core/extension"));
+const __optique_core_fluent = __toESM(require("@optique/core/fluent"));
+const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+
+//#region src/index.ts
+const phase1DerivedDefaultAnnotationMarker = Symbol("@optique/derived-defaults/phase1Annotation");
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+function validateSourceContextRequest(request) {
+	if (request === void 0) return;
+	if (request === null || typeof request !== "object" || !("phase" in request) || request.phase !== "phase1" && request.phase !== "phase2" || request.phase === "phase2" && !("parsed" in request)) throw new TypeError(`Expected getAnnotations() to receive no request or a SourceContextRequest ({ phase: "phase1" } or { phase: "phase2", parsed }), but got: ${getTypeName(request)}.`);
+}
+function replaceDefaultDescription(fragments, description) {
+	if (description == null) return fragments;
+	return fragments.map((fragment) => {
+		if (fragment.type === "entry") return {
+			...fragment,
+			default: description
+		};
+		return {
+			...fragment,
+			entries: fragment.entries.map((entry) => ({
+				...entry,
+				default: description
+			}))
+		};
+	});
+}
+function validateFallbackValue(mode, innerParser, value) {
+	if (innerParser == null || typeof innerParser.validateValue !== "function") return (0, __optique_core_extension.wrapForMode)(mode, {
+		success: true,
+		value
+	});
+	return (0, __optique_core_extension.wrapForMode)(mode, innerParser.validateValue(value));
+}
+/**
+* Creates a derived-default context.
+*
+* @param resolvers Resolver map keyed by derived value name.
+* @returns A derived-default context bundle.
+* @throws {TypeError} If `resolvers` is not an object or contains a
+* non-function resolver.
+* @since 1.2.0
+*/
+function createDerivedDefaults(resolvers) {
+	if (resolvers == null || typeof resolvers !== "object") throw new TypeError(`Expected resolvers to be an object, but got: ${getTypeName(resolvers)}.`);
+	for (const key of Reflect.ownKeys(resolvers)) {
+		const resolver = resolvers[key];
+		if (typeof resolver !== "function") throw new TypeError(`Expected resolver ${String(key)} to be a function, but got: ${getTypeName(resolver)}.`);
+	}
+	const contextId = Symbol(`@optique/derived-defaults:${Math.random()}`);
+	const context = {
+		id: contextId,
+		phase: "two-pass",
+		getInternalAnnotations(request, annotations) {
+			if (request.phase === "phase1") return { [contextId]: phase1DerivedDefaultAnnotationMarker };
+			return contextId in annotations ? void 0 : { [contextId]: void 0 };
+		},
+		getAnnotations(request) {
+			validateSourceContextRequest(request);
+			if (request?.phase !== "phase2") return {};
+			const values = {};
+			const pending = [];
+			for (const key of Reflect.ownKeys(resolvers)) {
+				const resolver = resolvers[key];
+				if (request.parsed == null && resolver.length > 0) continue;
+				const resolved = resolver(request.parsed ?? void 0);
+				if (isPromiseLike(resolved)) pending.push(Promise.resolve(resolved).then((value) => {
+					if (value !== void 0) values[key] = value;
+				}));
+				else if (resolved !== void 0) values[key] = resolved;
+			}
+			const buildAnnotations = () => Reflect.ownKeys(values).length === 0 ? {} : { [contextId]: { values } };
+			return pending.length === 0 ? buildAnnotations() : Promise.all(pending).then(buildAnnotations);
+		},
+		[Symbol.dispose]() {}
+	};
+	return { context };
+}
+/**
+* Binds a parser to a derived default value.
+*
+* @param parser Parser that reads the CLI value.
+* @param options Derived default binding options.
+* @returns A parser with derived fallback behavior.
+* @throws {TypeError} If `options.key` is not a property key.
+* @since 1.2.0
+*/
+function bindDerivedDefault(parser, options) {
+	const keyType = typeof options.key;
+	if (keyType !== "string" && keyType !== "number" && keyType !== "symbol") throw new TypeError(`Expected key to be a property key, but got: ${getTypeName(options.key)}.`);
+	const bindStateKey = Symbol("@optique/derived-defaults/bindState");
+	function isBindState(value) {
+		return value != null && typeof value === "object" && bindStateKey in value;
+	}
+	function shouldDeferCompletion(state, exec) {
+		const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+		if (annotations?.[options.context.id] === phase1DerivedDefaultAnnotationMarker) return true;
+		return parser.shouldDeferCompletion?.(getInnerState(state), exec) === true;
+	}
+	function getInnerState(state) {
+		if (!isBindState(state)) return state;
+		if (state.cliState !== void 0) return state.cliState;
+		const initialState = parser.initialState;
+		if (initialState != null && typeof initialState !== "object") return initialState;
+		const annotated = (0, __optique_core_extension.inheritAnnotations)(state, initialState);
+		if (annotated === initialState && initialState != null && typeof initialState === "object") {
+			const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+			return annotations == null ? initialState : (0, __optique_core_extension.withAnnotationView)(initialState, annotations);
+		}
+		return annotated;
+	}
+	function getDerivedValue(state) {
+		const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+		const annotationValue = annotations?.[options.context.id];
+		if (annotationValue == null || typeof annotationValue !== "object" || !("values" in annotationValue)) return void 0;
+		return annotationValue.values[options.key];
+	}
+	function hasDerivedFallback(state) {
+		if (getDerivedValue(state) !== void 0) return true;
+		return options.default !== void 0;
+	}
+	function getDerivedOrDefault(state, mode, exec, innerParser) {
+		const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+		const contextId = options.context.id;
+		const contextAbsent = annotations != null && !(contextId in annotations);
+		const derivedValue = getDerivedValue(state);
+		if (derivedValue !== void 0) return validateFallbackValue(mode, innerParser, derivedValue);
+		if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+		if (innerParser?.canSkip?.(getInnerState(state), exec) === true) return (0, __optique_core_extension.mapModeValue)(mode, (0, __optique_core_extension.wrapForMode)(mode, innerParser.complete(getInnerState(state), exec)), (result) => {
+			if (result.success) return result;
+			if (contextAbsent) return {
+				success: false,
+				error: __optique_core_message.message`Derived default value could not be read: the derived default context was not passed to run()'s contexts option.`
+			};
+			return result;
+		});
+		if (contextAbsent) return (0, __optique_core_extension.wrapForMode)(mode, {
+			success: false,
+			error: __optique_core_message.message`Derived default value could not be read: the derived default context was not passed to run()'s contexts option.`
+		});
+		return (0, __optique_core_extension.wrapForMode)(mode, {
+			success: false,
+			error: __optique_core_message.message`Missing required derived default value.`
+		});
+	}
+	function getDerivedSourceValue(state, innerState, mode, extractInnerSourceValue, innerParser) {
+		const derivedValue = getDerivedValue(state);
+		const validateFallback = (parsed) => {
+			if (!parsed.success) return parsed;
+			if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+			return (0, __optique_core_extension.wrapForMode)(mode, innerParser.validateValue(parsed.value));
+		};
+		if (derivedValue !== void 0) return (0, __optique_core_extension.wrapForMode)(mode, validateFallback({
+			success: true,
+			value: derivedValue
+		}));
+		if (options.default !== void 0) return (0, __optique_core_extension.wrapForMode)(mode, validateFallback({
+			success: true,
+			value: options.default
+		}));
+		return (0, __optique_core_extension.wrapForMode)(mode, extractInnerSourceValue(innerState));
+	}
+	const boundParser = {
+		mode: parser.mode,
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: options.default !== void 0 ? [{
+			type: "optional",
+			terms: parser.usage
+		}] : parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		initialState: parser.initialState,
+		canSkip(state, exec) {
+			if (isBindState(state)) {
+				if (state.hasCliValue) return parser.canSkip?.(state.cliState, exec) === true;
+				if (hasDerivedFallback(state)) return true;
+				return parser.canSkip?.(getInnerState(state), exec) === true;
+			}
+			if (hasDerivedFallback(state)) return true;
+			return parser.canSkip?.(state, exec) === true;
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = getInnerState(state);
+			return (0, __optique_core_extension.delegateSuggestNodes)(parser, boundParser, state, path, innerState);
+		},
+		parse(context) {
+			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
+			const innerState = isBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result) => {
+				if (result.success) {
+					const cliConsumed = result.consumed.length > 0;
+					const nextState$1 = (0, __optique_core_extension.injectAnnotations)({
+						[bindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result.next.state
+					}, annotations);
+					return {
+						success: true,
+						...result.provisional ? { provisional: true } : {},
+						next: {
+							...result.next,
+							state: nextState$1
+						},
+						consumed: result.consumed
+					};
+				}
+				if (result.consumed > 0) return result;
+				const nextState = (0, __optique_core_extension.injectAnnotations)({
+					[bindStateKey]: true,
+					hasCliValue: false
+				}, annotations);
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			return (0, __optique_core_extension.mapModeValue)(parser.mode, (0, __optique_core_extension.wrapForMode)(parser.mode, parser.parse(innerContext)), processResult);
+		},
+		complete(state, exec) {
+			if (isBindState(state) && state.hasCliValue) return (0, __optique_core_extension.wrapForMode)(parser.mode, parser.complete(state.cliState, exec));
+			return getDerivedOrDefault(state, parser.mode, exec, parser);
+		},
+		suggest(context, prefix) {
+			const innerState = getInnerState(context.state);
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			return parser.suggest(innerContext, prefix);
+		},
+		shouldDeferCompletion,
+		getDocFragments(state, upperDefaultValue) {
+			const defaultValue = upperDefaultValue ?? options.default;
+			const fragments = parser.getDocFragments(state, defaultValue);
+			if (upperDefaultValue !== void 0 || options.defaultDescription == null) return fragments;
+			return {
+				...fragments,
+				fragments: replaceDefaultDescription(fragments.fragments, options.defaultDescription)
+			};
+		}
+	};
+	Object.defineProperty(boundParser, __optique_core_extension.extractPhase2SeedKey, {
+		value(state, exec) {
+			const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+			if (annotations?.[options.context.id] !== phase1DerivedDefaultAnnotationMarker) {
+				const extractInnerPhase2Seed = parser[__optique_core_extension.extractPhase2SeedKey];
+				return extractInnerPhase2Seed == null ? (0, __optique_core_extension.wrapForMode)(parser.mode, null) : (0, __optique_core_extension.wrapForMode)(parser.mode, extractInnerPhase2Seed(getInnerState(state), exec));
+			}
+			return (0, __optique_core_extension.wrapForMode)(parser.mode, {
+				value: void 0,
+				deferred: true
+			});
+		},
+		configurable: true
+	});
+	(0, __optique_core_extension.defineTraits)(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(boundParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = (0, __optique_core_extension.mapSourceMetadata)(parser, (sourceMetadata) => ({
+		...sourceMetadata,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return (0, __optique_core_extension.wrapForMode)(parser.mode, parser.validateValue(options.default));
+			return (0, __optique_core_extension.wrapForMode)(parser.mode, {
+				success: true,
+				value: options.default
+			});
+		} : void 0,
+		extractSourceValue: (state) => {
+			if (!isBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getDerivedSourceValue(state, state, parser.mode, sourceMetadata.extractSourceValue, parser);
+				return (0, __optique_core_extension.wrapForMode)(parser.mode, sourceMetadata.extractSourceValue(state));
+			}
+			if (state.hasCliValue) return (0, __optique_core_extension.wrapForMode)(parser.mode, sourceMetadata.extractSourceValue(state.cliState));
+			const fallbackState = state.cliState ?? state;
+			if (!sourceMetadata.preservesSourceValue) return (0, __optique_core_extension.wrapForMode)(parser.mode, sourceMetadata.extractSourceValue(fallbackState));
+			return getDerivedSourceValue(state, fallbackState, parser.mode, sourceMetadata.extractSourceValue, parser);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	return (0, __optique_core_fluent.fluent)(boundParser);
+}
+
+//#endregion
+exports.bindDerivedDefault = bindDerivedDefault;
+exports.createDerivedDefaults = createDerivedDefaults;

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+import { Message } from "@optique/core/message";
+import { FluentParser } from "@optique/core/fluent";
+import { Mode, Parser } from "@optique/core/parser";
+import { SourceContext } from "@optique/core/context";
+
+//#region src/index.d.ts
+
+/**
+ * Resolver function for a derived default value.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultResolver<TParsed, TValue> = (parsed: TParsed) => TValue | undefined | Promise<TValue | undefined>;
+/**
+ * Values produced by a derived-default resolver map.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultValues<TResolvers> = { readonly [K in keyof TResolvers]: TResolvers[K] extends ((parsed: infer _TParsed) => infer TValue) ? Exclude<Awaited<TValue>, undefined> : never };
+/**
+ * Keys whose derived default values are assignable to a parser value type.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultKey<TValues extends object, TValue> = { readonly [K in keyof TValues]: TValues[K] extends TValue ? K : never }[keyof TValues];
+/**
+ * Source context for derived defaults.
+ *
+ * @since 1.2.0
+ */
+interface DerivedDefaultsContext<TValues extends object> extends SourceContext {
+  readonly phase: "two-pass";
+  readonly $values?: TValues;
+}
+/**
+ * Derived-default context bundle.
+ *
+ * @since 1.2.0
+ */
+interface DerivedDefaults<TValues extends object> {
+  readonly context: DerivedDefaultsContext<TValues>;
+}
+/**
+ * Options for binding a parser to a derived default value.
+ *
+ * @since 1.2.0
+ */
+interface BindDerivedDefaultOptions<TValues extends object, TValue, TKey extends DerivedDefaultKey<TValues, TValue>> {
+  readonly context: DerivedDefaultsContext<TValues>;
+  readonly key: TKey;
+  readonly default?: TValue;
+  readonly defaultDescription?: Message;
+}
+/**
+ * Creates a derived-default context.
+ *
+ * @param resolvers Resolver map keyed by derived value name.
+ * @returns A derived-default context bundle.
+ * @throws {TypeError} If `resolvers` is not an object or contains a
+ * non-function resolver.
+ * @since 1.2.0
+ */
+declare function createDerivedDefaults<const TResolvers extends object>(resolvers: TResolvers): DerivedDefaults<DerivedDefaultValues<TResolvers>>;
+/**
+ * Binds a parser to a derived default value.
+ *
+ * @param parser Parser that reads the CLI value.
+ * @param options Derived default binding options.
+ * @returns A parser with derived fallback behavior.
+ * @throws {TypeError} If `options.key` is not a property key.
+ * @since 1.2.0
+ */
+declare function bindDerivedDefault<M extends Mode, TValue, TState, TValues extends object, TKey extends DerivedDefaultKey<TValues, TValue>>(parser: Parser<M, TValue, TState>, options: BindDerivedDefaultOptions<TValues, TValue, TKey>): FluentParser<M, TValue, TState>;
+//#endregion
+export { BindDerivedDefaultOptions, DerivedDefaultKey, DerivedDefaultResolver, DerivedDefaultValues, DerivedDefaults, DerivedDefaultsContext, bindDerivedDefault, createDerivedDefaults };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { Message } from "@optique/core/message";
+import { FluentParser } from "@optique/core/fluent";
+import { Mode, Parser } from "@optique/core/parser";
+import { SourceContext } from "@optique/core/context";
+
+//#region src/index.d.ts
+
+/**
+ * Resolver function for a derived default value.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultResolver<TParsed, TValue> = (parsed: TParsed) => TValue | undefined | Promise<TValue | undefined>;
+/**
+ * Values produced by a derived-default resolver map.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultValues<TResolvers> = { readonly [K in keyof TResolvers]: TResolvers[K] extends ((parsed: infer _TParsed) => infer TValue) ? Exclude<Awaited<TValue>, undefined> : never };
+/**
+ * Keys whose derived default values are assignable to a parser value type.
+ *
+ * @since 1.2.0
+ */
+type DerivedDefaultKey<TValues extends object, TValue> = { readonly [K in keyof TValues]: TValues[K] extends TValue ? K : never }[keyof TValues];
+/**
+ * Source context for derived defaults.
+ *
+ * @since 1.2.0
+ */
+interface DerivedDefaultsContext<TValues extends object> extends SourceContext {
+  readonly phase: "two-pass";
+  readonly $values?: TValues;
+}
+/**
+ * Derived-default context bundle.
+ *
+ * @since 1.2.0
+ */
+interface DerivedDefaults<TValues extends object> {
+  readonly context: DerivedDefaultsContext<TValues>;
+}
+/**
+ * Options for binding a parser to a derived default value.
+ *
+ * @since 1.2.0
+ */
+interface BindDerivedDefaultOptions<TValues extends object, TValue, TKey extends DerivedDefaultKey<TValues, TValue>> {
+  readonly context: DerivedDefaultsContext<TValues>;
+  readonly key: TKey;
+  readonly default?: TValue;
+  readonly defaultDescription?: Message;
+}
+/**
+ * Creates a derived-default context.
+ *
+ * @param resolvers Resolver map keyed by derived value name.
+ * @returns A derived-default context bundle.
+ * @throws {TypeError} If `resolvers` is not an object or contains a
+ * non-function resolver.
+ * @since 1.2.0
+ */
+declare function createDerivedDefaults<const TResolvers extends object>(resolvers: TResolvers): DerivedDefaults<DerivedDefaultValues<TResolvers>>;
+/**
+ * Binds a parser to a derived default value.
+ *
+ * @param parser Parser that reads the CLI value.
+ * @param options Derived default binding options.
+ * @returns A parser with derived fallback behavior.
+ * @throws {TypeError} If `options.key` is not a property key.
+ * @since 1.2.0
+ */
+declare function bindDerivedDefault<M extends Mode, TValue, TState, TValues extends object, TKey extends DerivedDefaultKey<TValues, TValue>>(parser: Parser<M, TValue, TState>, options: BindDerivedDefaultOptions<TValues, TValue, TKey>): FluentParser<M, TValue, TState>;
+//#endregion
+export { BindDerivedDefaultOptions, DerivedDefaultKey, DerivedDefaultResolver, DerivedDefaultValues, DerivedDefaults, DerivedDefaultsContext, bindDerivedDefault, createDerivedDefaults };

package/dist/index.js

@@ -0,0 +1,324 @@
+import { message } from "@optique/core/message";
+import { defineTraits, delegateSuggestNodes, extractPhase2SeedKey, inheritAnnotations, injectAnnotations, mapModeValue, mapSourceMetadata, withAnnotationView, wrapForMode } from "@optique/core/extension";
+import { fluent } from "@optique/core/fluent";
+import { getAnnotations } from "@optique/core/annotations";
+
+//#region src/index.ts
+const phase1DerivedDefaultAnnotationMarker = Symbol("@optique/derived-defaults/phase1Annotation");
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+function validateSourceContextRequest(request) {
+	if (request === void 0) return;
+	if (request === null || typeof request !== "object" || !("phase" in request) || request.phase !== "phase1" && request.phase !== "phase2" || request.phase === "phase2" && !("parsed" in request)) throw new TypeError(`Expected getAnnotations() to receive no request or a SourceContextRequest ({ phase: "phase1" } or { phase: "phase2", parsed }), but got: ${getTypeName(request)}.`);
+}
+function replaceDefaultDescription(fragments, description) {
+	if (description == null) return fragments;
+	return fragments.map((fragment) => {
+		if (fragment.type === "entry") return {
+			...fragment,
+			default: description
+		};
+		return {
+			...fragment,
+			entries: fragment.entries.map((entry) => ({
+				...entry,
+				default: description
+			}))
+		};
+	});
+}
+function validateFallbackValue(mode, innerParser, value) {
+	if (innerParser == null || typeof innerParser.validateValue !== "function") return wrapForMode(mode, {
+		success: true,
+		value
+	});
+	return wrapForMode(mode, innerParser.validateValue(value));
+}
+/**
+* Creates a derived-default context.
+*
+* @param resolvers Resolver map keyed by derived value name.
+* @returns A derived-default context bundle.
+* @throws {TypeError} If `resolvers` is not an object or contains a
+* non-function resolver.
+* @since 1.2.0
+*/
+function createDerivedDefaults(resolvers) {
+	if (resolvers == null || typeof resolvers !== "object") throw new TypeError(`Expected resolvers to be an object, but got: ${getTypeName(resolvers)}.`);
+	for (const key of Reflect.ownKeys(resolvers)) {
+		const resolver = resolvers[key];
+		if (typeof resolver !== "function") throw new TypeError(`Expected resolver ${String(key)} to be a function, but got: ${getTypeName(resolver)}.`);
+	}
+	const contextId = Symbol(`@optique/derived-defaults:${Math.random()}`);
+	const context = {
+		id: contextId,
+		phase: "two-pass",
+		getInternalAnnotations(request, annotations) {
+			if (request.phase === "phase1") return { [contextId]: phase1DerivedDefaultAnnotationMarker };
+			return contextId in annotations ? void 0 : { [contextId]: void 0 };
+		},
+		getAnnotations(request) {
+			validateSourceContextRequest(request);
+			if (request?.phase !== "phase2") return {};
+			const values = {};
+			const pending = [];
+			for (const key of Reflect.ownKeys(resolvers)) {
+				const resolver = resolvers[key];
+				if (request.parsed == null && resolver.length > 0) continue;
+				const resolved = resolver(request.parsed ?? void 0);
+				if (isPromiseLike(resolved)) pending.push(Promise.resolve(resolved).then((value) => {
+					if (value !== void 0) values[key] = value;
+				}));
+				else if (resolved !== void 0) values[key] = resolved;
+			}
+			const buildAnnotations = () => Reflect.ownKeys(values).length === 0 ? {} : { [contextId]: { values } };
+			return pending.length === 0 ? buildAnnotations() : Promise.all(pending).then(buildAnnotations);
+		},
+		[Symbol.dispose]() {}
+	};
+	return { context };
+}
+/**
+* Binds a parser to a derived default value.
+*
+* @param parser Parser that reads the CLI value.
+* @param options Derived default binding options.
+* @returns A parser with derived fallback behavior.
+* @throws {TypeError} If `options.key` is not a property key.
+* @since 1.2.0
+*/
+function bindDerivedDefault(parser, options) {
+	const keyType = typeof options.key;
+	if (keyType !== "string" && keyType !== "number" && keyType !== "symbol") throw new TypeError(`Expected key to be a property key, but got: ${getTypeName(options.key)}.`);
+	const bindStateKey = Symbol("@optique/derived-defaults/bindState");
+	function isBindState(value) {
+		return value != null && typeof value === "object" && bindStateKey in value;
+	}
+	function shouldDeferCompletion(state, exec) {
+		const annotations = getAnnotations(state);
+		if (annotations?.[options.context.id] === phase1DerivedDefaultAnnotationMarker) return true;
+		return parser.shouldDeferCompletion?.(getInnerState(state), exec) === true;
+	}
+	function getInnerState(state) {
+		if (!isBindState(state)) return state;
+		if (state.cliState !== void 0) return state.cliState;
+		const initialState = parser.initialState;
+		if (initialState != null && typeof initialState !== "object") return initialState;
+		const annotated = inheritAnnotations(state, initialState);
+		if (annotated === initialState && initialState != null && typeof initialState === "object") {
+			const annotations = getAnnotations(state);
+			return annotations == null ? initialState : withAnnotationView(initialState, annotations);
+		}
+		return annotated;
+	}
+	function getDerivedValue(state) {
+		const annotations = getAnnotations(state);
+		const annotationValue = annotations?.[options.context.id];
+		if (annotationValue == null || typeof annotationValue !== "object" || !("values" in annotationValue)) return void 0;
+		return annotationValue.values[options.key];
+	}
+	function hasDerivedFallback(state) {
+		if (getDerivedValue(state) !== void 0) return true;
+		return options.default !== void 0;
+	}
+	function getDerivedOrDefault(state, mode, exec, innerParser) {
+		const annotations = getAnnotations(state);
+		const contextId = options.context.id;
+		const contextAbsent = annotations != null && !(contextId in annotations);
+		const derivedValue = getDerivedValue(state);
+		if (derivedValue !== void 0) return validateFallbackValue(mode, innerParser, derivedValue);
+		if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+		if (innerParser?.canSkip?.(getInnerState(state), exec) === true) return mapModeValue(mode, wrapForMode(mode, innerParser.complete(getInnerState(state), exec)), (result) => {
+			if (result.success) return result;
+			if (contextAbsent) return {
+				success: false,
+				error: message`Derived default value could not be read: the derived default context was not passed to run()'s contexts option.`
+			};
+			return result;
+		});
+		if (contextAbsent) return wrapForMode(mode, {
+			success: false,
+			error: message`Derived default value could not be read: the derived default context was not passed to run()'s contexts option.`
+		});
+		return wrapForMode(mode, {
+			success: false,
+			error: message`Missing required derived default value.`
+		});
+	}
+	function getDerivedSourceValue(state, innerState, mode, extractInnerSourceValue, innerParser) {
+		const derivedValue = getDerivedValue(state);
+		const validateFallback = (parsed) => {
+			if (!parsed.success) return parsed;
+			if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+			return wrapForMode(mode, innerParser.validateValue(parsed.value));
+		};
+		if (derivedValue !== void 0) return wrapForMode(mode, validateFallback({
+			success: true,
+			value: derivedValue
+		}));
+		if (options.default !== void 0) return wrapForMode(mode, validateFallback({
+			success: true,
+			value: options.default
+		}));
+		return wrapForMode(mode, extractInnerSourceValue(innerState));
+	}
+	const boundParser = {
+		mode: parser.mode,
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: options.default !== void 0 ? [{
+			type: "optional",
+			terms: parser.usage
+		}] : parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		initialState: parser.initialState,
+		canSkip(state, exec) {
+			if (isBindState(state)) {
+				if (state.hasCliValue) return parser.canSkip?.(state.cliState, exec) === true;
+				if (hasDerivedFallback(state)) return true;
+				return parser.canSkip?.(getInnerState(state), exec) === true;
+			}
+			if (hasDerivedFallback(state)) return true;
+			return parser.canSkip?.(state, exec) === true;
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = getInnerState(state);
+			return delegateSuggestNodes(parser, boundParser, state, path, innerState);
+		},
+		parse(context) {
+			const annotations = getAnnotations(context.state);
+			const innerState = isBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result) => {
+				if (result.success) {
+					const cliConsumed = result.consumed.length > 0;
+					const nextState$1 = injectAnnotations({
+						[bindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result.next.state
+					}, annotations);
+					return {
+						success: true,
+						...result.provisional ? { provisional: true } : {},
+						next: {
+							...result.next,
+							state: nextState$1
+						},
+						consumed: result.consumed
+					};
+				}
+				if (result.consumed > 0) return result;
+				const nextState = injectAnnotations({
+					[bindStateKey]: true,
+					hasCliValue: false
+				}, annotations);
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			return mapModeValue(parser.mode, wrapForMode(parser.mode, parser.parse(innerContext)), processResult);
+		},
+		complete(state, exec) {
+			if (isBindState(state) && state.hasCliValue) return wrapForMode(parser.mode, parser.complete(state.cliState, exec));
+			return getDerivedOrDefault(state, parser.mode, exec, parser);
+		},
+		suggest(context, prefix) {
+			const innerState = getInnerState(context.state);
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			return parser.suggest(innerContext, prefix);
+		},
+		shouldDeferCompletion,
+		getDocFragments(state, upperDefaultValue) {
+			const defaultValue = upperDefaultValue ?? options.default;
+			const fragments = parser.getDocFragments(state, defaultValue);
+			if (upperDefaultValue !== void 0 || options.defaultDescription == null) return fragments;
+			return {
+				...fragments,
+				fragments: replaceDefaultDescription(fragments.fragments, options.defaultDescription)
+			};
+		}
+	};
+	Object.defineProperty(boundParser, extractPhase2SeedKey, {
+		value(state, exec) {
+			const annotations = getAnnotations(state);
+			if (annotations?.[options.context.id] !== phase1DerivedDefaultAnnotationMarker) {
+				const extractInnerPhase2Seed = parser[extractPhase2SeedKey];
+				return extractInnerPhase2Seed == null ? wrapForMode(parser.mode, null) : wrapForMode(parser.mode, extractInnerPhase2Seed(getInnerState(state), exec));
+			}
+			return wrapForMode(parser.mode, {
+				value: void 0,
+				deferred: true
+			});
+		},
+		configurable: true
+	});
+	defineTraits(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(boundParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = mapSourceMetadata(parser, (sourceMetadata) => ({
+		...sourceMetadata,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return wrapForMode(parser.mode, parser.validateValue(options.default));
+			return wrapForMode(parser.mode, {
+				success: true,
+				value: options.default
+			});
+		} : void 0,
+		extractSourceValue: (state) => {
+			if (!isBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getDerivedSourceValue(state, state, parser.mode, sourceMetadata.extractSourceValue, parser);
+				return wrapForMode(parser.mode, sourceMetadata.extractSourceValue(state));
+			}
+			if (state.hasCliValue) return wrapForMode(parser.mode, sourceMetadata.extractSourceValue(state.cliState));
+			const fallbackState = state.cliState ?? state;
+			if (!sourceMetadata.preservesSourceValue) return wrapForMode(parser.mode, sourceMetadata.extractSourceValue(fallbackState));
+			return getDerivedSourceValue(state, fallbackState, parser.mode, sourceMetadata.extractSourceValue, parser);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
+	return fluent(boundParser);
+}
+
+//#endregion
+export { bindDerivedDefault, createDerivedDefaults };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@optique/derived-defaults",
+  "version": "1.2.0-dev.0",
+  "description": "Derived default value support for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "defaults",
+    "source-context"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/derived-defaults/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "imports": {
+    "#src/*.ts": {
+      "node": "./dist/*.js",
+      "default": "./src/*.ts"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "fast-check": "^4.7.0",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3",
+    "@optique/config": "1.2.0",
+    "@optique/env": "1.2.0",
+    "@optique/run": "1.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --test && bun test && deno test"
+  }
+}