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

package/dist/facade.cjs

@@ -403,7 +403,30 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;

package/dist/facade.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
+import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
 
@@ -213,7 +214,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
+import { Program } from "./program.js";
 
 //#region src/facade.d.ts
 
@@ -213,7 +214,10 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
+ * @since 0.11.0 Added support for {@link Program} objects.
  */
+declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
+declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
 declare function runParser<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
 declare function runParser<TParser extends Parser<"async", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<InferValue<TParser>>;
 declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): ModeValue<InferMode<TParser>, InferValue<TParser>>;

package/dist/facade.js

@@ -403,7 +403,30 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 	return callOnCompletion(0);
 }
-function runParser(parser, programName, args, options = {}) {
+function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
+	const isProgram = typeof programNameOrArgs !== "string";
+	let parser;
+	let programName;
+	let args;
+	let options;
+	if (isProgram) {
+		const program = parserOrProgram;
+		parser = program.parser;
+		programName = program.metadata.name;
+		args = programNameOrArgs;
+		options = argsOrOptions ?? {};
+		options = {
+			...options,
+			brief: options.brief ?? program.metadata.brief,
+			description: options.description ?? program.metadata.description,
+			footer: options.footer ?? program.metadata.footer
+		};
+	} else {
+		parser = parserOrProgram;
+		programName = programNameOrArgs;
+		args = argsOrOptions;
+		options = optionsParam ?? {};
+	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;

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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.324+5bba27e5",
+  "version": "0.10.0-dev.327+76d21ea0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -131,6 +131,14 @@
       "import": "./dist/primitives.js",
       "require": "./dist/primitives.cjs"
     },
+    "./program": {
+      "types": {
+        "import": "./dist/program.d.ts",
+        "require": "./dist/program.d.cts"
+      },
+      "import": "./dist/program.js",
+      "require": "./dist/program.cjs"
+    },
     "./usage": {
       "types": {
         "import": "./dist/usage.d.ts",