@optique/core 1.0.0-dev.1778 → 1.0.0-dev.1786

package/dist/modifiers.js

@@ -2,6 +2,7 @@ import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations,
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
+import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 
 //#region src/modifiers.ts
@@ -79,6 +80,10 @@ function unwrapMultipleItemState(state) {
 function isPromiseLike(value) {
 	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
+function extractOptionalLikePhase2Seed(parser, state, exec) {
+	if (!Array.isArray(state) && !(state != null && typeof state === "object")) return wrapForMode(parser.$mode, null);
+	return completeOrExtractPhase2Seed(parser, normalizeOptionalLikeInnerState(state, parser.initialState, parser), exec);
+}
 /**
 * Computes the inner state to pass through to the wrapped parser inside
 * {@link optional} / {@link withDefault}.  When the outer state is an
@@ -251,6 +256,9 @@ function optional(parser) {
 				state: innerState
 			}] : []);
 		},
+		[extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
@@ -416,6 +424,9 @@ function withDefault(parser, defaultValue, options) {
 				state: innerState
 			}] : []);
 		},
+		[extractPhase2SeedKey](state, exec) {
+			return extractOptionalLikePhase2Seed(parser, state, exec);
+		},
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
@@ -656,6 +667,23 @@ function map(parser, transform) {
 		...parser,
 		$valueType: [],
 		complete,
+		[extractPhase2SeedKey](state, exec) {
+			return mapModeValue(parser.$mode, completeOrExtractPhase2Seed(parser, state, exec), (seed) => {
+				if (seed == null) return null;
+				if (seed.deferred) try {
+					return {
+						value: transform(seed.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						value: void 0,
+						deferred: true
+					};
+				}
+				return { value: transform(seed.value) };
+			});
+		},
 		getSuggestRuntimeNodes(state, path) {
 			if (mappedParser.dependencyMetadata?.source != null) return [{
 				path,
@@ -795,6 +823,26 @@ function multiple(parser, options = {}) {
 			});
 		}
 	};
+	const extractPhase2SeedSyncWithUnwrappedFallback = (state, exec) => {
+		try {
+			const seed = completeOrExtractPhase2Seed(syncParser, state, exec);
+			if (seed == null && isInjectedAnnotationWrapper(state)) return completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return completeOrExtractPhase2Seed(syncParser, unwrapInjectedWrapper(state), exec);
+		}
+	};
+	const extractPhase2SeedAsyncWithUnwrappedFallback = async (state, exec) => {
+		try {
+			const seed = await completeOrExtractPhase2Seed(parser, state, exec);
+			if (seed == null && isInjectedAnnotationWrapper(state)) return await completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+			return seed;
+		} catch (error) {
+			if (!isInjectedAnnotationWrapper(state)) throw error;
+			return await completeOrExtractPhase2Seed(parser, unwrapInjectedWrapper(state), exec);
+		}
+	};
 	const getInnerSuggestRuntimeNodes = (state, path) => parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
 		path,
 		parser,
@@ -1023,6 +1071,53 @@ function multiple(parser, options = {}) {
 				return validateMultipleResult(values, deferredIndices, hasDeferred);
 			});
 		},
+		[extractPhase2SeedKey](state, exec) {
+			return dispatchByMode(parser.$mode, () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = extractPhase2SeedSyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
+				};
+			}, async () => {
+				const values = [];
+				const deferredIndices = /* @__PURE__ */ new Map();
+				let hasDeferred = false;
+				let hasAnySeed = false;
+				for (let i = 0; i < state.length; i++) {
+					const seed = await extractPhase2SeedAsyncWithUnwrappedFallback(state[i], withChildExecPath(exec, i));
+					if (seed == null) continue;
+					hasAnySeed = true;
+					values[i] = seed.value;
+					if (seed.deferred) if (seed.deferredKeys) deferredIndices.set(i, seed.deferredKeys);
+					else if (seed.value == null || typeof seed.value !== "object") deferredIndices.set(i, null);
+					else hasDeferred = true;
+				}
+				if (!hasAnySeed) return null;
+				return {
+					value: values,
+					...deferredIndices.size > 0 || hasDeferred ? {
+						deferred: true,
+						...deferredIndices.size > 0 ? { deferredKeys: deferredIndices } : {}
+					} : {}
+				};
+			});
+		},
 		suggest(context, prefix) {
 			const currentItemState = context.state.at(-1);
 			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
@@ -1365,6 +1460,13 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(nonEmptyParser, extractPhase2SeedKey, {
+		value(state, exec) {
+			return extractPhase2Seed(parser, state, exec);
+		},
+		configurable: true,
+		enumerable: false
+	});
 	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
 		value: parser.normalizeValue.bind(parser),
 		configurable: true,

package/dist/phase2-seed.cjs

@@ -0,0 +1,59 @@
+const require_annotations = require('./annotations.cjs');
+const require_mode_dispatch = require('./mode-dispatch.cjs');
+
+//#region src/phase2-seed.ts
+/**
+* Internal parser hook key for phase-two seed extraction.
+*
+* @internal
+*/
+const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
+/**
+* Converts a successful complete() result into a phase-two seed.
+*
+* @internal
+*/
+function phase2SeedFromValueResult(result) {
+	return {
+		value: require_annotations.unwrapInjectedAnnotationWrapper(result.value),
+		...result.deferred ? { deferred: true } : {},
+		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
+	};
+}
+/**
+* Invokes a parser's internal phase-two seed hook when present.
+*
+* @internal
+*/
+function extractPhase2Seed(parser, state, exec) {
+	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : extractor(state, exec);
+	}, async () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : await extractor(state, exec);
+	});
+}
+/**
+* Attempts to complete a parser and falls back to the internal phase-two
+* seed hook when completion returns an unsuccessful result.
+*
+* @internal
+*/
+function completeOrExtractPhase2Seed(parser, state, exec) {
+	return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+		const result = parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return extractPhase2Seed(parser, state, exec);
+	}, async () => {
+		const result = await parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return await extractPhase2Seed(parser, state, exec);
+	});
+}
+
+//#endregion
+exports.completeOrExtractPhase2Seed = completeOrExtractPhase2Seed;
+exports.extractPhase2Seed = extractPhase2Seed;
+exports.extractPhase2SeedKey = extractPhase2SeedKey;
+exports.phase2SeedFromValueResult = phase2SeedFromValueResult;

package/dist/phase2-seed.js

@@ -0,0 +1,56 @@
+import { unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { dispatchByMode } from "./mode-dispatch.js";
+
+//#region src/phase2-seed.ts
+/**
+* Internal parser hook key for phase-two seed extraction.
+*
+* @internal
+*/
+const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
+/**
+* Converts a successful complete() result into a phase-two seed.
+*
+* @internal
+*/
+function phase2SeedFromValueResult(result) {
+	return {
+		value: unwrapInjectedAnnotationWrapper(result.value),
+		...result.deferred ? { deferred: true } : {},
+		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
+	};
+}
+/**
+* Invokes a parser's internal phase-two seed hook when present.
+*
+* @internal
+*/
+function extractPhase2Seed(parser, state, exec) {
+	return dispatchByMode(parser.$mode, () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : extractor(state, exec);
+	}, async () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : await extractor(state, exec);
+	});
+}
+/**
+* Attempts to complete a parser and falls back to the internal phase-two
+* seed hook when completion returns an unsuccessful result.
+*
+* @internal
+*/
+function completeOrExtractPhase2Seed(parser, state, exec) {
+	return dispatchByMode(parser.$mode, () => {
+		const result = parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return extractPhase2Seed(parser, state, exec);
+	}, async () => {
+		const result = await parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return await extractPhase2Seed(parser, state, exec);
+	});
+}
+
+//#endregion
+export { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };

package/dist/primitives.cjs

@@ -5,6 +5,7 @@ const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_dependency_metadata = require('./dependency-metadata.cjs');
+const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 const require_valueparser = require('./valueparser.cjs');
@@ -1342,6 +1343,34 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state during completion.`
 			};
 		},
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			if (typeof state === "undefined") return require_mode_dispatch.wrapForMode(parser.$mode, null);
+			if (state[0] === "matched") {
+				const childExec = withChildExecPath(exec, name);
+				const childContext = {
+					buffer: [],
+					optionsTerminated: false,
+					usage: parser.usage,
+					state: parser.initialState,
+					...childExec != null ? {
+						exec: childExec,
+						trace: childExec.trace,
+						dependencyRegistry: childExec.dependencyRegistry
+					} : {}
+				};
+				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+					const parseResult = syncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return require_phase2_seed.completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+				}, async () => {
+					const parseResult = await asyncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return await require_phase2_seed.completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+				});
+			}
+			if (state[0] === "parsing") return require_phase2_seed.completeOrExtractPhase2Seed(parser, state[1], withChildExecPath(exec, name));
+			return require_mode_dispatch.wrapForMode(parser.$mode, null);
+		},
 		suggest(context, prefix) {
 			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
 			return suggestCommandSync(context, prefix, name, parser, options);

package/dist/primitives.js

@@ -5,6 +5,7 @@ import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./mode-dispatch.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
+import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
 import { isValueParser } from "./valueparser.js";
@@ -1342,6 +1343,34 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? message`Invalid command state during completion.`
 			};
 		},
+		[extractPhase2SeedKey](state, exec) {
+			if (typeof state === "undefined") return wrapForMode(parser.$mode, null);
+			if (state[0] === "matched") {
+				const childExec = withChildExecPath(exec, name);
+				const childContext = {
+					buffer: [],
+					optionsTerminated: false,
+					usage: parser.usage,
+					state: parser.initialState,
+					...childExec != null ? {
+						exec: childExec,
+						trace: childExec.trace,
+						dependencyRegistry: childExec.dependencyRegistry
+					} : {}
+				};
+				return dispatchByMode(parser.$mode, () => {
+					const parseResult = syncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? parseResult.next.state : syncInnerParser.initialState, nextExec);
+				}, async () => {
+					const parseResult = await asyncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return await completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? parseResult.next.state : parser.initialState, nextExec);
+				});
+			}
+			if (state[0] === "parsing") return completeOrExtractPhase2Seed(parser, state[1], withChildExecPath(exec, name));
+			return wrapForMode(parser.$mode, null);
+		},
 		suggest(context, prefix) {
 			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
 			return suggestCommandSync(context, prefix, name, parser, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1778+0b813b67",
+  "version": "1.0.0-dev.1786+fe69db9f",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",