cli-kiss 0.2.4 → 0.2.6

package/src/lib/Option.ts

@@ -44,15 +44,15 @@ export type OptionDecoder<Value> = {
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → {@link TypoError}.
+ * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → throws {@link TypoError}.
  *
  * @param definition.long - Long-form name (without `--`).
  * @param definition.short - Short-form name (without `-`).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.default - Default when absent. Defaults to `false`.
+ * @param definition.default - Default value when absent.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -62,102 +62,50 @@ export type OptionDecoder<Value> = {
  *   short: "v",
  *   description: "Enable verbose output",
  * });
+ * // Usage:
+ * //   my-cli  →  false
+ * //   my-cli --verbose  →  true
+ * //   my-cli --verbose=yes  →  true
+ * //   my-cli -v=no  →  false
  * ```
  */
 export function optionFlag(definition: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
   default?: boolean;
 }): Option<boolean> {
-  const label = `<${typeBoolean.content.toUpperCase()}>`;
+  const type = typeBoolean("value");
+  const { long, short, description, hint, aliases } = definition;
   return {
     generateUsage() {
-      return {
-        short: definition.short,
-        long: definition.long,
-        label: undefined,
-        annotation: "[=no]",
-        description: definition.description,
-        hint: definition.hint,
-      };
+      return { short, long, annotation: "[=no]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
-      const longNegative = `no-${definition.long}` as Lowercase<string>;
-      const aliasesLongsNegatives = definition.aliases?.longs?.map(
-        (aliasLong) => `no-${aliasLong}` as Lowercase<string>,
-      );
-      const keyNegative = registerOption(readerOptions, {
-        long: longNegative,
-        short: undefined,
-        aliasesShorts: undefined,
-        aliasesLongs: aliasesLongsNegatives,
-        parsing: { consumeShortGroup: false, consumeNextArg: () => false },
-      });
-      const keyPositive = registerOption(readerOptions, {
-        long: definition.long,
-        short: definition.short,
-        aliasesLongs: definition.aliases?.longs,
-        aliasesShorts: definition.aliases?.shorts,
+      const key = registerOption(readerOptions, {
+        long,
+        short,
+        aliasesLongs: aliases?.longs,
+        aliasesShorts: aliases?.shorts,
         parsing: { consumeShortGroup: false, consumeNextArg: () => false },
       });
       return {
         getAndDecodeValue() {
-          const negativeResults = readerOptions.getOptionValues(keyNegative);
-          const positiveResults = readerOptions.getOptionValues(keyPositive);
-          if (positiveResults.length > 1) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: Must not be set multiple times`),
-              ),
-            );
-          }
-          if (negativeResults.length > 1) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${longNegative}`, typoStyleConstants),
-                new TypoString(`: Must not be set multiple times`),
-              ),
-            );
-          }
-          if (negativeResults.length > 0 && positiveResults.length > 0) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: Must not be set in combination with: `),
-                new TypoString(`--${longNegative}`, typoStyleConstants),
-              ),
-            );
-          }
-          if (negativeResults.length > 0) {
-            const negativeResult = negativeResults[0]!;
-            if (negativeResult.inlined) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(`--${longNegative}`, typoStyleConstants),
-                  new TypoString(`: Must not have a value`),
-                ),
-              );
-            }
-            return false;
+          const optionResults = readerOptions.getOptionValues(key);
+          if (optionResults.length > 1) {
+            throwSetMultipleTimesError(long);
           }
-          if (positiveResults.length > 0) {
-            const positiveResult = positiveResults[0]!;
-            return decodeValue({
-              long: definition.long,
-              short: definition.short,
-              label,
-              type: typeBoolean,
-              input:
-                positiveResult.inlined === null
-                  ? "true"
-                  : positiveResult.inlined,
-            });
+          if (optionResults.length === 0) {
+            return definition.default === undefined
+              ? false
+              : definition.default;
           }
-          return definition.default ?? false;
+          const positiveResult = optionResults[0]!;
+          const value =
+            positiveResult.inlined === null ? "true" : positiveResult.inlined;
+          return decodeValue({ long, short, type, input: value });
         },
       };
     },
@@ -167,7 +115,7 @@ export function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
  * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
  * @typeParam Value - Type produced by the decoder.
@@ -177,9 +125,9 @@ export function optionFlag(definition: {
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.default - Default when absent. Throw to make the option required.
+ * @param definition.valueWhenNotDefined - Default value when the option is not specified at all.
+ * @param definition.valueWhenNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -187,79 +135,75 @@ export function optionFlag(definition: {
  * const outputOption = optionSingleValue({
  *   long: "output",
  *   short: "o",
- *   type: typeString,
- *   label: "PATH",
+ *   type: typePath(),
  *   description: "Output directory",
- *   default: () => "dist/",
+ *   valueWhenNotDefined: () => "dist",
  * });
+ * // Usage:
+ * //   my-cli  →  "dist"
+ * //   my-cli --output folder  →  "folder"
+ * //   my-cli -o folder  →  "folder"
  * ```
  */
 export function optionSingleValue<Value>(definition: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  label?: Uppercase<string>;
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
-  default: () => Value;
+  defaultWhenNotDefined: () => Value;
+  defaultWhenNotInlined?: () => Value;
 }): Option<Value> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { long, short, description, hint, aliases, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      return {
-        short: definition.short,
-        long: definition.long,
-        label: label as Uppercase<string>,
-        annotation: undefined,
-        description: definition.description,
-        hint: definition.hint,
-      };
+      return { short, long, label, description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        long: definition.long,
-        short: definition.short,
-        aliasesLongs: definition.aliases?.longs,
-        aliasesShorts: definition.aliases?.shorts,
+        long,
+        short,
+        aliasesLongs: aliases?.longs,
+        aliasesShorts: aliases?.shorts,
         parsing: {
           consumeShortGroup: true,
-          consumeNextArg: (inlined, separated) =>
-            inlined === null && separated.length === 0,
+          consumeNextArg(inlined, separated) {
+            if (definition.defaultWhenNotInlined !== undefined) {
+              return false;
+            }
+            return inlined === null && separated.length === 0;
+          },
         },
       });
       return {
         getAndDecodeValue() {
           const optionResults = readerOptions.getOptionValues(key);
           if (optionResults.length > 1) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: Requires a single value, but got multiple`),
-              ),
-            );
+            throwSetMultipleTimesError(long);
           }
           const optionResult = optionResults[0];
           if (optionResult === undefined) {
             try {
-              return definition.default();
+              return definition.defaultWhenNotDefined();
             } catch (error) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(`--${definition.long}`, typoStyleConstants),
-                  new TypoString(`: Failed to get default value`),
-                ),
-                error,
-              );
+              throwFailedToGetDefaultValueError(long, error, "not set");
             }
           }
-          return decodeValue({
-            long: definition.long,
-            short: definition.short,
-            label,
-            type: definition.type,
-            input: optionResult.inlined ?? optionResult.separated[0]!,
-          });
+          if (optionResult.inlined) {
+            const inlined = optionResult.inlined;
+            return decodeValue({ long, short, label, type, input: inlined });
+          }
+          if (definition.defaultWhenNotInlined !== undefined) {
+            try {
+              return definition.defaultWhenNotInlined();
+            } catch (error) {
+              throwFailedToGetDefaultValueError(long, error, "not inlined");
+            }
+          }
+          const separated = optionResult.separated[0]!;
+          return decodeValue({ long, short, label, type, input: separated });
         },
       };
     },
@@ -279,7 +223,6 @@ export function optionSingleValue<Value>(definition: {
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
- * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each raw string value.
  * @returns An {@link Option}`<Array<Value>>`.
  *
@@ -296,33 +239,25 @@ export function optionSingleValue<Value>(definition: {
  * ```
  */
 export function optionRepeatable<Value>(definition: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  label?: Uppercase<string>;
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
 }): Option<Array<Value>> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { long, short, description, hint, aliases, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      // TODO - showcase that it can be repeated ?
-      return {
-        short: definition.short,
-        long: definition.long,
-        label: label as Uppercase<string>,
-        annotation: " [*]",
-        description: definition.description,
-        hint: definition.hint,
-      };
+      return { short, long, label, annotation: " [*]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        long: definition.long,
-        short: definition.short,
-        aliasesLongs: definition.aliases?.longs,
-        aliasesShorts: definition.aliases?.shorts,
+        long,
+        short,
+        aliasesLongs: aliases?.longs,
+        aliasesShorts: aliases?.shorts,
         parsing: {
           consumeShortGroup: true,
           consumeNextArg: (inlined, separated) =>
@@ -332,15 +267,10 @@ export function optionRepeatable<Value>(definition: {
       return {
         getAndDecodeValue() {
           const optionResults = readerOptions.getOptionValues(key);
-          return optionResults.map((optionResult) =>
-            decodeValue({
-              long: definition.long,
-              short: definition.short,
-              label,
-              type: definition.type,
-              input: optionResult.inlined ?? optionResult.separated[0]!,
-            }),
-          );
+          return optionResults.map((optionResult) => {
+            const input = optionResult.inlined ?? optionResult.separated[0]!;
+            return decodeValue({ long, short, label, type, input });
+          });
         },
       };
     },
@@ -349,8 +279,8 @@ export function optionRepeatable<Value>(definition: {
 
 function decodeValue<Value>(params: {
   long: string;
-  short: string | undefined;
-  label: string;
+  short?: string | undefined;
+  label?: string | undefined;
   type: Type<Value>;
   input: string;
 }): Value {
@@ -363,10 +293,13 @@ function decodeValue<Value>(params: {
         text.push(new TypoString(`, `));
       }
       text.push(new TypoString(`--${params.long}`, typoStyleConstants));
-      text.push(new TypoString(`: `));
-      text.push(new TypoString(params.label, typoStyleUserInput));
-      text.push(new TypoString(`: `));
-      text.push(new TypoString(params.type.content, typoStyleLogic));
+      if (params.label) {
+        text.push(new TypoString(`: `));
+        text.push(new TypoString(params.label, typoStyleUserInput));
+      } else {
+        text.push(new TypoString(`: `));
+        text.push(new TypoString(params.type.content, typoStyleLogic));
+      }
       return text;
     },
   );
@@ -375,9 +308,9 @@ function decodeValue<Value>(params: {
 function registerOption(
   readerOptions: ReaderOptions,
   definition: {
-    long: Lowercase<string>;
+    long: string;
     short: undefined | string;
-    aliasesLongs: undefined | Array<Lowercase<string>>;
+    aliasesLongs: undefined | Array<string>;
     aliasesShorts: undefined | Array<string>;
     parsing: ReaderOptionParsing;
   },
@@ -393,3 +326,26 @@ function registerOption(
   }
   return readerOptions.registerOption({ longs, shorts, parsing });
 }
+
+function throwSetMultipleTimesError(long: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(`--${long}`, typoStyleConstants),
+      new TypoString(`: Must not be set multiple times`),
+    ),
+  );
+}
+
+function throwFailedToGetDefaultValueError(
+  long: string,
+  error: unknown,
+  context: string,
+): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(`--${long}`, typoStyleConstants),
+      new TypoString(`: Failed to get default value (${context})`),
+    ),
+    error,
+  );
+}

package/src/lib/Positional.ts

@@ -1,12 +1,6 @@
 import { ReaderPositionals } from "./Reader";
 import { Type } from "./Type";
-import {
-  TypoError,
-  TypoString,
-  typoStyleLogic,
-  typoStyleUserInput,
-  TypoText,
-} from "./Typo";
+import { TypoError, TypoString, typoStyleUserInput, TypoText } from "./Typo";
 import { UsagePositional } from "./Usage";
 
 /**
@@ -45,40 +39,34 @@ export type PositionalDecoder<Value> = {
 
 /**
  * Creates a required positional — missing token throws {@link TypoError}.
- * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
  * @typeParam Value - Type produced by the decoder.
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
  * ```ts
  * const namePositional = positionalRequired({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Parses: my-cli Alice  →  "Alice"
+ * // Usage:
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalRequired<Value>(definition: {
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Value> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { description, hint, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: label as Uppercase<string>,
-      };
+      return { description, hint, label };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
@@ -101,13 +89,11 @@ export function positionalRequired<Value>(definition: {
 
 /**
  * Creates an optional positional — absent token falls back to `default()`.
- * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
  *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
@@ -115,30 +101,26 @@ export function positionalRequired<Value>(definition: {
  * @example
  * ```ts
  * const greeteePositional = positionalOptional({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "Name to greet (default: world)",
  *   default: () => "world",
  * });
- * // my-cli         →  "world"
- * // my-cli Alice   →  "Alice"
+ * // Usage:
+ * //   my-cli  →  "world"
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalOptional<Value>(definition: {
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
   default: () => Value;
 }): Positional<Value> {
-  const label = `[${definition.label ?? definition.type.content.toUpperCase()}]`;
+  const { description, hint, type } = definition;
+  const label = `[${type.content}]`;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: label as Uppercase<string>,
-      };
+      return { description, hint, label };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
@@ -148,13 +130,7 @@ export function positionalOptional<Value>(definition: {
             try {
               return definition.default();
             } catch (error) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(label, typoStyleUserInput),
-                  new TypoString(`: Failed to get default value`),
-                ),
-                error,
-              );
+              throwsWhenFailedToGetDefault(label);
             }
           }
           return decodeValue(label, definition.type, positional);
@@ -166,46 +142,41 @@ export function positionalOptional<Value>(definition: {
 
 /**
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
- * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
+ * Optionally stops at `endDelimiter` (consumed, not included).
  *
  * @typeParam Value - Type produced by the decoder for each token.
  *
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
  * ```ts
  * const filesPositional = positionalVariadics({
- *   type: typeString,
- *   label: "FILE",
+ *   type: typePath(),
  *   description: "Files to process",
  * });
- * // my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
- * // my-cli                  →  []
+ * // Usage:
+ * //   my-cli  →  []
+ * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 export function positionalVariadics<Value>(definition: {
   endDelimiter?: string;
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Array<Value>> {
-  const label = `[${definition.label ?? definition.type.content.toUpperCase()}]`;
+  const { description, hint, type } = definition;
+  const labelSingle = `[${type.content}]`;
+  const labelMultiple =
+    `${labelSingle}...` +
+    (definition.endDelimiter ? ` ["${definition.endDelimiter}"]` : "");
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: (`${label}...` +
-          (definition.endDelimiter
-            ? ` ["${definition.endDelimiter}"]`
-            : "")) as Uppercase<string>,
-      };
+      return { description, hint, label: labelMultiple };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positionals = new Array<string>();
@@ -222,7 +193,7 @@ export function positionalVariadics<Value>(definition: {
       return {
         decodeValue() {
           return positionals.map((positional) =>
-            decodeValue(label, definition.type, positional),
+            decodeValue(labelSingle, definition.type, positional),
           );
         },
       };
@@ -237,11 +208,15 @@ function decodeValue<Value>(
 ): Value {
   return TypoError.tryWithContext(
     () => type.decoder(input),
-    () =>
-      new TypoText(
-        new TypoString(label, typoStyleUserInput),
-        new TypoString(`: `),
-        new TypoString(type.content, typoStyleLogic),
-      ),
+    () => new TypoText(new TypoString(label, typoStyleUserInput)),
+  );
+}
+
+function throwsWhenFailedToGetDefault(label: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(label, typoStyleUserInput),
+      new TypoString(`: Failed to get default value`),
+    ),
   );
 }

package/src/lib/Reader.ts

@@ -17,11 +17,11 @@ export type ReaderOptionKey = (string | { __brand: "ReaderOptionKey" }) & {
  * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
  */
 export type ReaderOptionParsing = {
-  consumeShortGroup: boolean;
+  consumeShortGroup: boolean; // TODO - this doesnt matter when no short option
   consumeNextArg: (
     inlined: string | null,
     separated: Array<string>,
-    next: string | undefined,
+    nextArg: string | undefined,
   ) => boolean;
 };
 
@@ -340,7 +340,7 @@ export class ReaderArgs {
   }
 
   #isValidOptionName(name: string): boolean {
-    return name.length > 0 && !name.includes("=");
+    return name.length > 0 && !name.includes("=") && !name.includes("\0");
   }
 }