@optique/core 0.10.0-dev.323 → 0.10.0-dev.327

package/dist/modifiers.js

@@ -1,5 +1,6 @@
 import { formatMessage, message, text } from "./message.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
+import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 
 //#region src/modifiers.ts
 /**
@@ -74,7 +75,6 @@ function processOptionalStyleResult(result, innerState, context) {
 */
 function optional(parser) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	function* suggestSync(context, prefix) {
 		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
 		yield* syncParser.suggest({
@@ -107,36 +107,27 @@ function optional(parser) {
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
 			if (typeof state === "undefined") {
-				if (innerHasWrappedDependency && wrappedPendingState) {
-					if (!isAsync) return syncParser.complete([wrappedPendingState]);
-					return parser.complete([wrappedPendingState]);
-				}
+				if (innerHasWrappedDependency && wrappedPendingState) return dispatchByMode(parser.$mode, () => syncParser.complete([wrappedPendingState]), () => parser.complete([wrappedPendingState]));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
 			if (Array.isArray(state) && state.length === 1 && isPendingDependencySourceState(state[0])) {
-				if (innerHasWrappedDependency) {
-					if (!isAsync) return syncParser.complete(state);
-					return parser.complete(state);
-				}
+				if (innerHasWrappedDependency) return dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 				return {
 					success: true,
 					value: void 0
 				};
 			}
-			if (!isAsync) return syncParser.complete(state[0]);
-			return parser.complete(state[0]);
+			return dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -183,7 +174,6 @@ var WithDefaultError = class extends Error {
 };
 function withDefault(parser, defaultValue, options) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	function* suggestSync(context, prefix) {
 		const innerState = typeof context.state === "undefined" ? syncParser.initialState : context.state[0];
 		yield* syncParser.suggest({
@@ -213,13 +203,12 @@ function withDefault(parser, defaultValue, options) {
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		parse(context) {
-			if (isAsync) return parseOptionalStyleAsync(context, parser);
-			return parseOptionalStyleSync(context, syncParser);
+			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
 			if (typeof state === "undefined") {
 				if (transformsDependencyValue(parser)) {
-					const innerResult = !isAsync ? syncParser.complete(void 0) : parser.complete(void 0);
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
 							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -277,7 +266,7 @@ function withDefault(parser, defaultValue, options) {
 			}
 			if (isPendingDependencySourceState(state[0])) {
 				if (transformsDependencyValue(parser)) {
-					const innerResult = !isAsync ? syncParser.complete(state) : parser.complete(state);
+					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
 							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
@@ -320,12 +309,10 @@ function withDefault(parser, defaultValue, options) {
 					};
 				}
 			}
-			if (!isAsync) return syncParser.complete(state[0]);
-			return parser.complete(state[0]);
+			return dispatchByMode(parser.$mode, () => syncParser.complete(state[0]), () => parser.complete(state[0]));
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestAsync(context, prefix);
-			return suggestSync(context, prefix);
+			return dispatchIterableByMode(parser.$mode, () => suggestSync(context, prefix), () => suggestAsync(context, prefix));
 		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
@@ -432,7 +419,6 @@ function map(parser, transform) {
 */
 function multiple(parser, options = {}) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	const { min = 0, max = Infinity } = options;
 	const parseSync = (context) => {
 		let added = context.state.length < 1;
@@ -494,11 +480,10 @@ function multiple(parser, options = {}) {
 		}],
 		initialState: [],
 		parse(context) {
-			if (isAsync) return parseAsync(context);
-			return parseSync(context);
+			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state) {
-			if (!isAsync) {
+			return dispatchByMode(parser.$mode, () => {
 				const result = [];
 				for (const s of state) {
 					const valueResult = syncParser.complete(s);
@@ -509,8 +494,7 @@ function multiple(parser, options = {}) {
 					};
 				}
 				return validateMultipleResult(result);
-			}
-			return (async () => {
+			}, async () => {
 				const results = await Promise.all(state.map((s) => parser.complete(s)));
 				const values = [];
 				for (const valueResult of results) if (valueResult.success) values.push(valueResult.value);
@@ -519,7 +503,7 @@ function multiple(parser, options = {}) {
 					error: valueResult.error
 				};
 				return validateMultipleResult(values);
-			})();
+			});
 		},
 		suggest(context, prefix) {
 			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
@@ -535,19 +519,18 @@ function multiple(parser, options = {}) {
 				if (suggestion.kind === "literal") return !selectedValues.has(suggestion.text);
 				return true;
 			};
-			if (isAsync) return async function* () {
+			return dispatchIterableByMode(parser.$mode, function* () {
+				for (const s of syncParser.suggest({
+					...context,
+					state: innerState
+				}, prefix)) if (shouldInclude(s)) yield s;
+			}, async function* () {
 				const suggestions = parser.suggest({
 					...context,
 					state: innerState
 				}, prefix);
 				for await (const s of suggestions) if (shouldInclude(s)) yield s;
-			}();
-			return function* () {
-				for (const s of syncParser.suggest({
-					...context,
-					state: innerState
-				}, prefix)) if (shouldInclude(s)) yield s;
-			}();
+			});
 		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
@@ -617,7 +600,6 @@ function multiple(parser, options = {}) {
 */
 function nonEmpty(parser) {
 	const syncParser = parser;
-	const isAsync = parser.$mode === "async";
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -643,8 +625,7 @@ function nonEmpty(parser) {
 		usage: parser.usage,
 		initialState: parser.initialState,
 		parse(context) {
-			if (isAsync) return parseAsync(context);
-			return parseSync(context);
+			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
 		},
 		complete(state) {
 			return parser.complete(state);

package/dist/parser.d.cts

@@ -1,6 +1,7 @@
 import { Message } from "./message.cjs";
 import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
+import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -191,11 +192,9 @@ interface ParserContext<TState> {
    * A registry containing resolved dependency values from DependencySource parsers.
    * This is used during shell completion to provide suggestions based on
    * the actual dependency values that have been parsed, rather than defaults.
-   * The type is `unknown` to avoid circular dependency issues; the actual type
-   * is `DependencyRegistry` from `./dependency.ts`.
    * @since 0.10.0
    */
-  readonly dependencyRegistry?: unknown;
+  readonly dependencyRegistry?: DependencyRegistryLike;
 }
 /**
  * Represents a suggestion for command-line completion or guidance.

package/dist/parser.d.ts

@@ -1,6 +1,7 @@
 import { Message } from "./message.js";
 import { Usage } from "./usage.js";
 import { DocFragments, DocPage } from "./doc.js";
+import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -191,11 +192,9 @@ interface ParserContext<TState> {
    * A registry containing resolved dependency values from DependencySource parsers.
    * This is used during shell completion to provide suggestions based on
    * the actual dependency values that have been parsed, rather than defaults.
-   * The type is `unknown` to avoid circular dependency issues; the actual type
-   * is `DependencyRegistry` from `./dependency.ts`.
    * @since 0.10.0
    */
-  readonly dependencyRegistry?: unknown;
+  readonly dependencyRegistry?: DependencyRegistryLike;
 }
 /**
  * Represents a suggestion for command-line completion or guidance.

package/dist/primitives.cjs

@@ -63,15 +63,15 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry)
 		const derived = valueParser;
 		const suggestWithDep = derived[require_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
-			const depIds = require_dependency.dependencyIds in derived ? derived[require_dependency.dependencyIds] : [derived[require_dependency.dependencyId]];
-			const defaults = require_dependency.defaultValues in derived ? derived[require_dependency.defaultValues]?.() : void 0;
-			const registry = dependencyRegistry;
+			const depIds = require_dependency.getDependencyIds(derived);
+			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
+			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
 			for (let i = 0; i < depIds.length; i++) {
 				const depId = depIds[i];
-				if (registry.has(depId)) {
-					dependencyValues.push(registry.get(depId));
+				if (dependencyRegistry.has(depId)) {
+					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
 				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
@@ -144,15 +144,15 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 		const derived = valueParser;
 		const suggestWithDep = derived[require_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
-			const depIds = require_dependency.dependencyIds in derived ? derived[require_dependency.dependencyIds] : [derived[require_dependency.dependencyId]];
-			const defaults = require_dependency.defaultValues in derived ? derived[require_dependency.defaultValues]?.() : void 0;
-			const registry = dependencyRegistry;
+			const depIds = require_dependency.getDependencyIds(derived);
+			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
+			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
 			for (let i = 0; i < depIds.length; i++) {
 				const depId = depIds[i];
-				if (registry.has(depId)) {
-					dependencyValues.push(registry.get(depId));
+				if (dependencyRegistry.has(depId)) {
+					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
 				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {

package/dist/primitives.js

@@ -1,5 +1,5 @@
 import { message, metavar, optionName, optionNames } from "./message.js";
-import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, dependencyId, dependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
+import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
 import { extractCommandNames, extractOptionNames } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar } from "./suggestion.js";
 import { isValueParser } from "./valueparser.js";
@@ -63,15 +63,15 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry)
 		const derived = valueParser;
 		const suggestWithDep = derived[suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
-			const depIds = dependencyIds in derived ? derived[dependencyIds] : [derived[dependencyId]];
-			const defaults = defaultValues in derived ? derived[defaultValues]?.() : void 0;
-			const registry = dependencyRegistry;
+			const depIds = getDependencyIds(derived);
+			const defaultsFn = getDefaultValuesFunction(derived);
+			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
 			for (let i = 0; i < depIds.length; i++) {
 				const depId = depIds[i];
-				if (registry.has(depId)) {
-					dependencyValues.push(registry.get(depId));
+				if (dependencyRegistry.has(depId)) {
+					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
 				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
@@ -144,15 +144,15 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 		const derived = valueParser;
 		const suggestWithDep = derived[suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
-			const depIds = dependencyIds in derived ? derived[dependencyIds] : [derived[dependencyId]];
-			const defaults = defaultValues in derived ? derived[defaultValues]?.() : void 0;
-			const registry = dependencyRegistry;
+			const depIds = getDependencyIds(derived);
+			const defaultsFn = getDefaultValuesFunction(derived);
+			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
 			for (let i = 0; i < depIds.length; i++) {
 				const depId = depIds[i];
-				if (registry.has(depId)) {
-					dependencyValues.push(registry.get(depId));
+				if (dependencyRegistry.has(depId)) {
+					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
 				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {

package/dist/program.cjs

@@ -0,0 +1,44 @@
+
+//#region src/program.ts
+/**
+* Defines a CLI program with a parser and metadata.
+*
+* This is a helper function that returns its argument unchanged, but provides
+* automatic type inference for the program. This eliminates the need to
+* manually specify type parameters when defining a program.
+*
+* @template M - The mode of the parser ("sync" or "async").
+* @template T - The type of value produced by the parser.
+* @param program - The program definition with parser and metadata.
+* @returns The same program object with inferred types.
+*
+* @example
+* ```typescript
+* import { defineProgram } from "@optique/core/program";
+* import { object } from "@optique/core/constructs";
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { message } from "@optique/core/message";
+*
+* const prog = defineProgram({
+*   parser: object({
+*     name: option("-n", "--name", string()),
+*   }),
+*   metadata: {
+*     name: "myapp",
+*     version: "1.0.0",
+*     brief: message`A simple CLI tool`,
+*   },
+* });
+* // TypeScript automatically infers:
+* // Program<"sync", { readonly name: string }>
+* ```
+*
+* @since 0.11.0
+*/
+function defineProgram(program) {
+	return program;
+}
+
+//#endregion
+exports.defineProgram = defineProgram;

package/dist/program.d.cts

@@ -0,0 +1,124 @@
+import { Message } from "./message.cjs";
+import { Mode, Parser } from "./parser.cjs";
+
+//#region src/program.d.ts
+
+/**
+ * Metadata for a CLI program.
+ *
+ * @since 0.11.0
+ */
+interface ProgramMetadata {
+  /**
+   * The name of the program.
+   */
+  readonly name: string;
+  /**
+   * The version of the program.
+   */
+  readonly version?: string;
+  /**
+   * A brief one-line description of the program.
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program.
+   */
+  readonly description?: Message;
+  /**
+   * Author information.
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   */
+  readonly bugs?: Message;
+  /**
+   * Usage examples for the program.
+   */
+  readonly examples?: Message;
+  /**
+   * Footer text shown at the end of help output.
+   */
+  readonly footer?: Message;
+}
+/**
+ * A CLI program consisting of a parser and its metadata.
+ *
+ * This interface bundles a parser with its metadata (name, version,
+ * description, etc.), providing a single source of truth for CLI application
+ * information that can be shared across different functionalities.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ *
+ * @example
+ * ```typescript
+ * import type { Program } from "@optique/core/program";
+ * import { command, option, string } from "@optique/core";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog: Program<"sync", { name: string }> = {
+ *   parser: command("greet", () => ({
+ *     name: option("name", string()).default("World"),
+ *   })),
+ *   metadata: {
+ *     name: "greet",
+ *     version: "1.0.0",
+ *     brief: message`A simple greeting CLI tool`,
+ *     author: message`Jane Doe <jane@example.com>`,
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.11.0
+ */
+interface Program<M extends Mode, T> {
+  /**
+   * The parser for the program.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata about the program.
+   */
+  readonly metadata: ProgramMetadata;
+}
+/**
+ * Defines a CLI program with a parser and metadata.
+ *
+ * This is a helper function that returns its argument unchanged, but provides
+ * automatic type inference for the program. This eliminates the need to
+ * manually specify type parameters when defining a program.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ * @param program - The program definition with parser and metadata.
+ * @returns The same program object with inferred types.
+ *
+ * @example
+ * ```typescript
+ * import { defineProgram } from "@optique/core/program";
+ * import { object } from "@optique/core/constructs";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog = defineProgram({
+ *   parser: object({
+ *     name: option("-n", "--name", string()),
+ *   }),
+ *   metadata: {
+ *     name: "myapp",
+ *     version: "1.0.0",
+ *     brief: message`A simple CLI tool`,
+ *   },
+ * });
+ * // TypeScript automatically infers:
+ * // Program<"sync", { readonly name: string }>
+ * ```
+ *
+ * @since 0.11.0
+ */
+declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
+//#endregion
+export { Program, ProgramMetadata, defineProgram };

package/dist/program.d.ts

@@ -0,0 +1,124 @@
+import { Message } from "./message.js";
+import { Mode, Parser } from "./parser.js";
+
+//#region src/program.d.ts
+
+/**
+ * Metadata for a CLI program.
+ *
+ * @since 0.11.0
+ */
+interface ProgramMetadata {
+  /**
+   * The name of the program.
+   */
+  readonly name: string;
+  /**
+   * The version of the program.
+   */
+  readonly version?: string;
+  /**
+   * A brief one-line description of the program.
+   */
+  readonly brief?: Message;
+  /**
+   * A detailed description of the program.
+   */
+  readonly description?: Message;
+  /**
+   * Author information.
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   */
+  readonly bugs?: Message;
+  /**
+   * Usage examples for the program.
+   */
+  readonly examples?: Message;
+  /**
+   * Footer text shown at the end of help output.
+   */
+  readonly footer?: Message;
+}
+/**
+ * A CLI program consisting of a parser and its metadata.
+ *
+ * This interface bundles a parser with its metadata (name, version,
+ * description, etc.), providing a single source of truth for CLI application
+ * information that can be shared across different functionalities.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ *
+ * @example
+ * ```typescript
+ * import type { Program } from "@optique/core/program";
+ * import { command, option, string } from "@optique/core";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog: Program<"sync", { name: string }> = {
+ *   parser: command("greet", () => ({
+ *     name: option("name", string()).default("World"),
+ *   })),
+ *   metadata: {
+ *     name: "greet",
+ *     version: "1.0.0",
+ *     brief: message`A simple greeting CLI tool`,
+ *     author: message`Jane Doe <jane@example.com>`,
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.11.0
+ */
+interface Program<M extends Mode, T> {
+  /**
+   * The parser for the program.
+   */
+  readonly parser: Parser<M, T, unknown>;
+  /**
+   * Metadata about the program.
+   */
+  readonly metadata: ProgramMetadata;
+}
+/**
+ * Defines a CLI program with a parser and metadata.
+ *
+ * This is a helper function that returns its argument unchanged, but provides
+ * automatic type inference for the program. This eliminates the need to
+ * manually specify type parameters when defining a program.
+ *
+ * @template M - The mode of the parser ("sync" or "async").
+ * @template T - The type of value produced by the parser.
+ * @param program - The program definition with parser and metadata.
+ * @returns The same program object with inferred types.
+ *
+ * @example
+ * ```typescript
+ * import { defineProgram } from "@optique/core/program";
+ * import { object } from "@optique/core/constructs";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { message } from "@optique/core/message";
+ *
+ * const prog = defineProgram({
+ *   parser: object({
+ *     name: option("-n", "--name", string()),
+ *   }),
+ *   metadata: {
+ *     name: "myapp",
+ *     version: "1.0.0",
+ *     brief: message`A simple CLI tool`,
+ *   },
+ * });
+ * // TypeScript automatically infers:
+ * // Program<"sync", { readonly name: string }>
+ * ```
+ *
+ * @since 0.11.0
+ */
+declare function defineProgram<M extends Mode, T>(program: Program<M, T>): Program<M, T>;
+//#endregion
+export { Program, ProgramMetadata, defineProgram };

package/dist/program.js

@@ -0,0 +1,43 @@
+//#region src/program.ts
+/**
+* Defines a CLI program with a parser and metadata.
+*
+* This is a helper function that returns its argument unchanged, but provides
+* automatic type inference for the program. This eliminates the need to
+* manually specify type parameters when defining a program.
+*
+* @template M - The mode of the parser ("sync" or "async").
+* @template T - The type of value produced by the parser.
+* @param program - The program definition with parser and metadata.
+* @returns The same program object with inferred types.
+*
+* @example
+* ```typescript
+* import { defineProgram } from "@optique/core/program";
+* import { object } from "@optique/core/constructs";
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { message } from "@optique/core/message";
+*
+* const prog = defineProgram({
+*   parser: object({
+*     name: option("-n", "--name", string()),
+*   }),
+*   metadata: {
+*     name: "myapp",
+*     version: "1.0.0",
+*     brief: message`A simple CLI tool`,
+*   },
+* });
+* // TypeScript automatically infers:
+* // Program<"sync", { readonly name: string }>
+* ```
+*
+* @since 0.11.0
+*/
+function defineProgram(program) {
+	return program;
+}
+
+//#endregion
+export { defineProgram };