@optique/core 1.0.0-dev.1561 → 1.0.0-dev.1572

package/dist/constructs.cjs

@@ -941,18 +941,20 @@ function isPlainObject(value) {
 function collectDependencyValues(deferredState, registry) {
 	const depIds = deferredState.dependencyIds;
 	if (depIds && depIds.length > 0) {
-		const defaults = deferredState.defaultValues;
+		const defaults$1 = deferredState.defaultValues;
 		const dependencyValues = [];
 		for (let i = 0; i < depIds.length; i++) {
 			const depId$1 = depIds[i];
 			if (registry.has(depId$1)) dependencyValues.push(registry.get(depId$1));
-			else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+			else if (defaults$1 && i < defaults$1.length) dependencyValues.push(defaults$1[i]);
 			else return null;
 		}
 		return dependencyValues;
 	}
 	const depId = deferredState.dependencyId;
 	if (registry.has(depId)) return registry.get(depId);
+	const defaults = deferredState.defaultValues;
+	if (defaults && defaults.length > 0) return defaults[0];
 	return null;
 }
 /**

package/dist/constructs.js

@@ -941,18 +941,20 @@ function isPlainObject(value) {
 function collectDependencyValues(deferredState, registry) {
 	const depIds = deferredState.dependencyIds;
 	if (depIds && depIds.length > 0) {
-		const defaults = deferredState.defaultValues;
+		const defaults$1 = deferredState.defaultValues;
 		const dependencyValues = [];
 		for (let i = 0; i < depIds.length; i++) {
 			const depId$1 = depIds[i];
 			if (registry.has(depId$1)) dependencyValues.push(registry.get(depId$1));
-			else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+			else if (defaults$1 && i < defaults$1.length) dependencyValues.push(defaults$1[i]);
 			else return null;
 		}
 		return dependencyValues;
 	}
 	const depId = deferredState.dependencyId;
 	if (registry.has(depId)) return registry.get(depId);
+	const defaults = deferredState.defaultValues;
+	if (defaults && defaults.length > 0) return defaults[0];
 	return null;
 }
 /**

package/dist/context.d.cts

@@ -96,7 +96,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**

package/dist/context.d.ts

@@ -96,7 +96,9 @@ interface SourceContext<TRequiredOptions = void> {
    * Unique identifier for this context.
    *
    * This symbol is typically the same as the annotation key used by parsers
-   * that consume this context's data.
+   * that consume this context's data.  Passing multiple contexts with the
+   * same id to {@link runWith}, {@link runWithSync}, or {@link runWithAsync}
+   * throws a `TypeError`.
    */
   readonly id: symbol;
   /**

package/dist/facade.cjs

@@ -1192,6 +1192,8 @@ function disposeContextsSync(contexts) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 *
 * @example
@@ -1221,6 +1223,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		require_validate.validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) {
 			if (parser.$mode === "async") return runParser(parser, programName, args, options);
 			return Promise.resolve(runParser(parser, programName, args, options));
@@ -1281,6 +1284,8 @@ async function runWith(parser, programName, contexts, options) {
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
@@ -1290,6 +1295,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		require_validate.validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
@@ -1333,6 +1339,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/dist/facade.d.cts

@@ -428,6 +428,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  *
  * @example
@@ -467,6 +469,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
@@ -486,6 +490,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.d.ts

@@ -428,6 +428,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  *
  * @example
@@ -467,6 +469,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @returns The parsed result.
  * @throws {TypeError} If an async parser is passed at runtime.  Use
  * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
@@ -486,6 +490,8 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns Promise that resolves to the parsed result.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.js

@@ -2,7 +2,7 @@ import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
-import { validateCommandNames, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
+import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
@@ -1192,6 +1192,8 @@ function disposeContextsSync(contexts) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 *
 * @example
@@ -1221,6 +1223,7 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
+		validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) {
 			if (parser.$mode === "async") return runParser(parser, programName, args, options);
 			return Promise.resolve(runParser(parser, programName, args, options));
@@ -1281,6 +1284,8 @@ async function runWith(parser, programName, contexts, options) {
 * @returns The parsed result.
 * @throws {TypeError} If an async parser is passed at runtime.  Use
 * {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
@@ -1290,6 +1295,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
+		validateContextIds(contexts);
 		if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 		const ctxOptions = options?.contextOptions;
 		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
@@ -1333,6 +1339,8 @@ function runWithSync(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/dist/validate.cjs

@@ -177,9 +177,25 @@ function validateLabel(label) {
 	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
 	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
 }
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
+exports.validateContextIds = validateContextIds;
 exports.validateLabel = validateLabel;
 exports.validateMetaNameCollisions = validateMetaNameCollisions;
 exports.validateOptionNames = validateOptionNames;

package/dist/validate.js

@@ -176,6 +176,21 @@ function validateLabel(label) {
 	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
 	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
 }
+/**
+* Validates that all source contexts have unique
+* {@link import("./context.ts").SourceContext.id | id} values.
+*
+* @param contexts The source contexts to validate.
+* @throws {TypeError} If two or more contexts share the same id.
+* @since 1.0.0
+*/
+function validateContextIds(contexts) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const context of contexts) {
+		if (seen.has(context.id)) throw new TypeError(`Duplicate SourceContext id: ${String(context.id)}`);
+		seen.add(context.id);
+	}
+}
 
 //#endregion
-export { validateCommandNames, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateContextIds, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/dist/valueparser.cjs

@@ -1161,8 +1161,8 @@ function ipv4(options) {
 		metavar,
 		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
-			const parts = input.split(".");
-			if (parts.length !== 4) {
+			const octets = parseIpv4Octets(input);
+			if (octets === null) {
 				const errorMsg = options?.errors?.invalidIpv4;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
 				return {
@@ -1170,51 +1170,6 @@ function ipv4(options) {
 					error: msg
 				};
 			}
-			const octets = [];
-			for (const part of parts) {
-				if (part.length === 0) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.trim() !== part) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.length > 1 && part[0] === "0") {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (!/^[0-9]+$/.test(part)) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				const octet = Number(part);
-				if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				octets.push(octet);
-			}
 			const ipAddress = octets.join(".");
 			if (!allowPrivate && isPrivateIp(octets)) {
 				const errorMsg = options?.errors?.privateNotAllowed;
@@ -2855,6 +2810,33 @@ function ipv6(options) {
 	return ipv6ParserObj;
 }
 /**
+* Parses a dotted-decimal IPv4 string into four validated octets.
+* Returns null if the input is not a valid strict IPv4 address
+* (exactly four decimal octets 0–255, no leading zeros, no whitespace,
+* no non-decimal characters).
+*/
+function parseIpv4Octets(input) {
+	const parts = input.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [
+		0,
+		0,
+		0,
+		0
+	];
+	for (let i = 0; i < 4; i++) {
+		const part = parts[i];
+		if (part.length === 0) return null;
+		if (part.trim() !== part) return null;
+		if (part.length > 1 && part[0] === "0") return null;
+		if (!/^[0-9]+$/.test(part)) return null;
+		const octet = Number(part);
+		if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+		octets[i] = octet;
+	}
+	return octets;
+}
+/**
 * Parses and normalizes an IPv6 address to canonical form.
 * Returns null if the input is not a valid IPv6 address.
 */
@@ -2864,10 +2846,8 @@ function parseAndNormalizeIpv6(input) {
 	if (ipv4MappedMatch) {
 		const ipv6Part = ipv4MappedMatch[1];
 		const ipv4Part = ipv4MappedMatch[2];
-		const ipv4Octets = ipv4Part.split(".");
-		if (ipv4Octets.length !== 4) return null;
-		const octets = ipv4Octets.map((o) => parseInt(o, 10));
-		if (octets.some((o) => isNaN(o) || o < 0 || o > 255)) return null;
+		const octets = parseIpv4Octets(ipv4Part);
+		if (octets === null) return null;
 		const group1 = octets[0] << 8 | octets[1];
 		const group2 = octets[2] << 8 | octets[3];
 		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;

package/dist/valueparser.js

@@ -1161,8 +1161,8 @@ function ipv4(options) {
 		metavar,
 		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
-			const parts = input.split(".");
-			if (parts.length !== 4) {
+			const octets = parseIpv4Octets(input);
+			if (octets === null) {
 				const errorMsg = options?.errors?.invalidIpv4;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
 				return {
@@ -1170,51 +1170,6 @@ function ipv4(options) {
 					error: msg
 				};
 			}
-			const octets = [];
-			for (const part of parts) {
-				if (part.length === 0) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.trim() !== part) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.length > 1 && part[0] === "0") {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (!/^[0-9]+$/.test(part)) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				const octet = Number(part);
-				if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				octets.push(octet);
-			}
 			const ipAddress = octets.join(".");
 			if (!allowPrivate && isPrivateIp(octets)) {
 				const errorMsg = options?.errors?.privateNotAllowed;
@@ -2855,6 +2810,33 @@ function ipv6(options) {
 	return ipv6ParserObj;
 }
 /**
+* Parses a dotted-decimal IPv4 string into four validated octets.
+* Returns null if the input is not a valid strict IPv4 address
+* (exactly four decimal octets 0–255, no leading zeros, no whitespace,
+* no non-decimal characters).
+*/
+function parseIpv4Octets(input) {
+	const parts = input.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [
+		0,
+		0,
+		0,
+		0
+	];
+	for (let i = 0; i < 4; i++) {
+		const part = parts[i];
+		if (part.length === 0) return null;
+		if (part.trim() !== part) return null;
+		if (part.length > 1 && part[0] === "0") return null;
+		if (!/^[0-9]+$/.test(part)) return null;
+		const octet = Number(part);
+		if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+		octets[i] = octet;
+	}
+	return octets;
+}
+/**
 * Parses and normalizes an IPv6 address to canonical form.
 * Returns null if the input is not a valid IPv6 address.
 */
@@ -2864,10 +2846,8 @@ function parseAndNormalizeIpv6(input) {
 	if (ipv4MappedMatch) {
 		const ipv6Part = ipv4MappedMatch[1];
 		const ipv4Part = ipv4MappedMatch[2];
-		const ipv4Octets = ipv4Part.split(".");
-		if (ipv4Octets.length !== 4) return null;
-		const octets = ipv4Octets.map((o) => parseInt(o, 10));
-		if (octets.some((o) => isNaN(o) || o < 0 || o > 255)) return null;
+		const octets = parseIpv4Octets(ipv4Part);
+		if (octets === null) return null;
 		const group1 = octets[0] << 8 | octets[1];
 		const group2 = octets[2] << 8 | octets[3];
 		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1561+241c020e",
+  "version": "1.0.0-dev.1572+6945a5ef",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",