@clerc/core 1.0.2 → 1.1.0

package/README.md

@@ -2,7 +2,9 @@
 
 [![NPM version](https://img.shields.io/npm/v/@clerc/core?color=a1b858&label=)](https://www.npmjs.com/package/@clerc/core)
 
-See [Clerc](https://github.com/clercjs/clerc) for documentation.
+## Documenation
+
+Read the [documentation](https://clerc.so1ve.dev) for more details.
 
 ## 📝 License
 

package/dist/chunk-15K8U1wQ.mjs

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };

package/dist/{index.d.ts → index.d.mts}

@@ -1,208 +1,43 @@
-//#endregion
-//#region ../parser/src/errors.d.ts
-declare class InvalidSchemaError extends Error {
-  constructor(message: string);
-}
-//#endregion
-//#region ../utils/src/types/type-fest.d.ts
-type LiteralUnion<LiteralType, BaseType> = LiteralType | (BaseType & Record<never, never>);
-type Prettify<T> = { [K in keyof T]: T[K] } & {};
-type Primitive = null | undefined | string | number | boolean | symbol | bigint;
-type BuiltIns = Primitive | void | Date | RegExp;
-type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown) | Promise<unknown>;
-type UnknownArray = readonly unknown[];
-type MapsSetsOrArrays = ReadonlyMap<unknown, unknown> | WeakMap<WeakKey, unknown> | ReadonlySet<unknown> | WeakSet<WeakKey> | UnknownArray;
-type ConditionalDeepPrettify<T, E = never, I$1 = unknown> = T extends E ? T : T extends I$1 ? { [TypeKey in keyof T]: ConditionalDeepPrettify<T[TypeKey], E, I$1> } : T;
-type DeepPrettify<T, E = never> = ConditionalDeepPrettify<T, E | NonRecursiveType | MapsSetsOrArrays, object>;
-type IsAny<T> = 0 extends 1 & T ? true : false;
-type RequireExactlyOneOrNone<T, Keys extends keyof T = keyof T> = ({ [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys] & Omit<T, Keys>) | (Partial<Record<Keys, never>> & Omit<T, Keys>);
-//#endregion
-//#region ../utils/src/types/index.d.ts
-type MaybeArray<T> = T | T[];
-type PartialRequired<T, K$1 extends keyof T> = T & { [P in K$1]-?: T[P] };
-type UnionToIntersection<U$1> = (U$1 extends any ? (k: U$1) => void : never) extends ((k: infer I) => void) ? I : never;
-type CamelCase<S extends string> = S extends `${infer Head} ${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
-//#endregion
-//#region ../parser/src/types.d.ts
-interface FlagDefaultValueFunction<T> {
-  (): T;
-  display?: string;
-}
-type FlagDefaultValue<T = unknown> = T | FlagDefaultValueFunction<T>;
-/**
-* Defines how a string input is converted to the target type T.
-*
-* @template T The target type.
-*/
-interface TypeFunction<T = unknown> {
-  (value: string): T;
-  /**
-  * Optional display name for the type, useful in help output.
-  * If provided, this will be shown instead of the function name.
-  */
-  display?: string;
-}
-/**
-* A callback function to conditionally stop parsing.
-* When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
-*
-* @param type - The type of the current argument: 'known-flag' or 'unknown-flag' for flags, 'parameter' for positional arguments
-* @param arg - The current argument being processed
-* @returns true to stop parsing, false to continue
-*/
-type IgnoreFunction = (type: typeof KNOWN_FLAG | typeof UNKNOWN_FLAG | typeof PARAMETER, arg: string) => boolean;
-type TypeValue<T = unknown> = TypeFunction<T> | readonly [TypeFunction<T>];
-type FlagRequiredOrDefault = RequireExactlyOneOrNone<{
-  /** The default value of the flag. */
-  default?: unknown;
-  /** Whether the flag is required. */
-  required?: boolean;
-}, "default" | "required">;
-type BaseFlagOptions<T extends TypeValue = TypeValue> = FlagRequiredOrDefault & {
-  /**
-  * The type constructor or a function to convert the string value.
-  * To support multiple occurrences of a flag (e.g., --file a --file b), wrap the type in an array: [String], [Number].
-  * e.g., String, Number, [String], (val) => val.split(',')
-  */
-  type: T;
-  /** Short flag alias (single character). */
-  short?: string;
-};
-type FlagOptions = (BaseFlagOptions<BooleanConstructor> & {
-  /**
-  * Whether to enable the `--no-<flag>` syntax to set the value to false.
-  * Only useful for boolean flags.
-  * When set on a non-boolean flag, a type error will be shown.
-  *
-  * @default true
-  */
-  negatable?: boolean;
-}) | (BaseFlagOptions & {
-  negatable?: never;
-});
-type FlagDefinitionValue = FlagOptions | TypeValue;
-type FlagsDefinition = Record<string, FlagDefinitionValue>;
-/**
-* Configuration options for the parser.
-*/
-interface ParserOptions<T extends FlagsDefinition = {}> {
-  /**
-  * Detailed configuration for flags.
-  * Supports the full object syntax or a type constructor as a shorthand.
-  * The key is the flag name (e.g., "file" for "--file").
-  */
-  flags?: T;
-  /**
-  * Delimiters to split flag names and values.
-  *
-  * @default ['=', ':']
-  */
-  delimiters?: string[];
-  /**
-  * A callback function to conditionally stop parsing.
-  * When it returns true, parsing stops and remaining arguments are preserved in `ignored`.
-  */
-  ignore?: IgnoreFunction;
-}
-type RawInputType = string | boolean;
-interface ObjectInputType {
-  [key: string]: RawInputType | ObjectInputType;
-}
-/**
-* The parsed result.
-* @template TFlags The specific flags type inferred from ParserOptions.
-*/
-interface ParsedResult<TFlags extends Record<string, any>> {
-  /** Positional arguments or commands. */
-  parameters: string[];
-  /** Arguments after the `--` delimiter. */
-  doubleDash: string[];
-  /**
-  * The parsed flags.
-  * This is a strongly-typed object whose structure is inferred from the `flags` configuration in ParserOptions.
-  */
-  flags: TFlags;
-  /** The raw command-line arguments. */
-  raw: string[];
-  /** Unknown flags encountered during parsing. */
-  unknown: Record<string, RawInputType>;
-  /** Arguments that were not parsed due to ignore callback. */
-  ignored: string[];
-  /** List of required flags that were not provided. */
-  missingRequiredFlags: string[];
-}
-type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
-  default: FlagDefaultValue<infer DefaultType>;
-} ? DefaultType : Fallback;
-type IsTypeAny<T extends FlagDefinitionValue> = IsAny<T> extends true ? true : T extends {
-  type: infer Type;
-} ? IsAny<Type> extends true ? true : false : false;
-type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: IsTypeAny<T[K]> extends true ? any : T[K] extends readonly [BooleanConstructor] | {
-  type: readonly [BooleanConstructor];
-} ? number | InferFlagDefault<T[K], never> : T[K] extends ObjectConstructor | {
-  type: ObjectConstructor;
-} ? ObjectInputType | InferFlagDefault<T[K], never> : T[K] extends readonly [TypeValue<infer U>] | {
-  type: readonly [TypeValue<infer U>];
-} ? U[] | InferFlagDefault<T[K], never> : T[K] extends TypeValue<infer U> | {
-  type: TypeValue<infer U>;
-} ? U | InferFlagDefault<T[K], [U] extends [boolean] ? never : T[K] extends {
-  required: true;
-} ? never : undefined> : never };
-/**
-* An advanced utility type that infers the exact type of the `flags` object in the parsed result,
-* based on the provided `flags` configuration object T.
-*
-* @template T The type of the flags configuration object.
-*/
-type InferFlags<T extends FlagsDefinition> = Prettify<_InferFlags<T>>;
-//#endregion
-//#region ../parser/src/iterator.d.ts
-declare const KNOWN_FLAG = "known-flag";
-declare const UNKNOWN_FLAG = "unknown-flag";
-declare const PARAMETER = "parameter";
-//#endregion
-//#region ../parser/src/parse.d.ts
-declare const DOUBLE_DASH = "--";
-type ParseFunction<T extends FlagsDefinition> = (args: string[]) => ParsedResult<InferFlags<T>>;
-declare function createParser<T extends FlagsDefinition>(options?: ParserOptions<T>): {
-  parse: ParseFunction<T>;
-};
-declare const parse: <T extends FlagsDefinition>(args: string[], options?: ParserOptions<T>) => ParsedResult<InferFlags<T>>;
-declare namespace index_d_exports {
-  export { BaseFlagOptions, DOUBLE_DASH, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, TypeFunction, TypeValue, UNKNOWN_FLAG, createParser, parse };
-}
-//#endregion
+import * as Parser from "@clerc/parser";
+import { DOUBLE_DASH, FlagOptions, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, PARAMETER, ParsedResult, TypeFunction, TypeValue, UNKNOWN_FLAG } from "@clerc/parser";
+import { CamelCase, DeepPrettify, LiteralUnion, MaybeArray, PartialRequired, Prettify, UnionToIntersection } from "@clerc/utils";
+
 //#region ../advanced-types/src/errors.d.ts
 declare class FlagValidationError extends Error {}
-declare namespace index_d_exports$1 {
+declare namespace index_d_exports {
   export { Enum, FlagValidationError, Range, Regex };
 }
 /**
 * Creates a Enum type function that validates the input against allowed values.
-* The display name will be formatted as "value1 | value2 | ..." for help output.
-*
-* @param values - Array of allowed string values
-* @returns A TypeFunction that validates and returns the input value
-* @throws {Error} If the value is not in the allowed values list
+* The display name will be formatted as "value1 | value2 | ..." for help
+* output.
 *
 * @example
+*
 * ```typescript
-* const format = Enum(['json', 'yaml', 'xml']);
+* const format = Enum(["json", "yaml", "xml"]);
 * // Help output will show: json | yaml | xml
 * ```
+*
+* @param values - Array of allowed string values
+* @returns A TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
 */
 declare function Enum<T extends string>(...values: T[]): TypeFunction<T>;
 /**
-* Creates a range type function that validates the input is a number within the specified range.
+* Creates a range type function that validates the input is a number within the
+* specified range.
 *
 * @param min - The minimum acceptable value (inclusive)
 * @param max - The maximum acceptable value (inclusive)
 * @returns A TypeFunction that validates the input value
-* @throws {Error} If the value is not a number or is outside the specified range
+* @throws {Error} If the value is not a number or is outside the specified
+*   range
 */
 declare function Range(min: number, max: number): TypeFunction<number>;
 /**
-* Creates a regex type function that validates the input against the provided pattern.
+* Creates a regex type function that validates the input against the provided
+* pattern.
 *
 * @param pattern - The regular expression pattern to validate against
 * @param description - Optional description for display purposes
@@ -224,7 +59,7 @@ type ClercFlagsDefinition = Record<string, ClercFlagDefinitionValue>;
 //#endregion
 //#region src/types/parameter.d.ts
 interface ParameterCustomOptions {}
-type InferStringParameter<T extends string, Type$1 = string> = T extends `<${infer Name extends string}...>` | `[${infer Name extends string}...]` ? Record<CamelCase<Name>, Type$1[]> : T extends `<${infer Name extends string}>` ? Record<CamelCase<Name>, Type$1> : T extends `[${infer Name extends string}]` ? Record<CamelCase<Name>, Type$1 | undefined> : never;
+type InferStringParameter<T extends string, Type = string> = T extends `<${infer Name extends string}...>` | `[${infer Name extends string}...]` ? Record<CamelCase<Name>, Type[]> : T extends `<${infer Name extends string}>` ? Record<CamelCase<Name>, Type> : T extends `[${infer Name extends string}]` ? Record<CamelCase<Name>, Type | undefined> : never;
 type InferParameter<T extends ParameterDefinitionValue> = T extends string ? InferStringParameter<T> : T extends ParameterOptions ? T["type"] extends TypeFunction<infer U> ? InferStringParameter<T["key"], U> : InferStringParameter<T["key"]> : never;
 type InferParameters<T extends readonly ParameterDefinitionValue[]> = T extends readonly (infer U extends ParameterDefinitionValue)[] ? Prettify<UnionToIntersection<InferParameter<U>>> : never;
 type ParameterOptions = {
@@ -256,7 +91,8 @@ interface CommandOptions<Parameters extends readonly ParameterDefinitionValue[]
   parameters?: Parameters;
   flags?: Flags;
   /**
-  * A callback function to conditionally stop parsing. When it returns true, parsing stops and remaining arguments are preserved in ignored.
+  * A callback function to conditionally stop parsing. When it returns true,
+  * parsing stops and remaining arguments are preserved in ignored.
   */
   ignore?: IgnoreFunction;
 }
@@ -278,8 +114,7 @@ type CommandHandler<C extends Command = Command, GF extends ClercFlagsDefinition
 //#region src/types/interceptor.d.ts
 type InterceptorContext<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = DeepPrettify<BaseContext<C, GF>>;
 /**
-* Function to call the next interceptor in the chain.
-* **MUST** be awaited.
+* Function to call the next interceptor in the chain. **MUST** be awaited.
 */
 type InterceptorNext = () => void | Promise<void>;
 type InterceptorHandler<C extends Command = Command, GF extends ClercFlagsDefinition = {}> = (context: InterceptorContext<C, GF>, next: InterceptorNext) => void | Promise<void>;
@@ -375,4 +210,4 @@ declare const definePlugin: (plugin: Plugin) => Plugin;
 declare const normalizeFlagValue: (flag: ClercFlagDefinitionValue) => ClercFlagOptions;
 declare const normalizeParameterValue: (parameter: ParameterDefinitionValue) => ParameterOptions;
 //#endregion
-export { BaseContext, Clerc, ClercFlagDefinitionValue, ClercFlagOptions, ClercFlagsDefinition, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, ContextStore, type CreateOptions, DOUBLE_DASH, ErrorHandler, FlagCustomOptions, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, InvalidSchemaError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredFlagError, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, ParameterCustomOptions, ParameterDefinitionValue, ParameterOptions, type ParseOptions, type index_d_exports as Parser, Plugin, index_d_exports$1 as Types, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, extractParameterInfo, normalizeFlagValue, normalizeParameterValue, resolveCommand };
+export { BaseContext, Clerc, ClercFlagDefinitionValue, ClercFlagOptions, ClercFlagsDefinition, Command, CommandCustomOptions, CommandHandler, CommandHandlerContext, CommandOptions, CommandWithHandler, CommandsMap, CommandsRecord, ContextStore, type CreateOptions, DOUBLE_DASH, ErrorHandler, FlagCustomOptions, InferParameters, Interceptor, InterceptorContext, InterceptorHandler, InterceptorNext, InterceptorObject, InvalidCommandError, InvalidParametersError, InvalidSchemaError, KNOWN_FLAG, MakeEmitterEvents, MissingRequiredFlagError, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, ParameterCustomOptions, ParameterDefinitionValue, ParameterOptions, type ParseOptions, type Parser, Plugin, index_d_exports as Types, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, extractParameterInfo, normalizeFlagValue, normalizeParameterValue, resolveCommand };

package/dist/{index.js → index.mjs}

@@ -1,29 +1,78 @@
-import * as Types from "@clerc/advanced-types";
+import { t as __exportAll } from "./chunk-15K8U1wQ.mjs";
 import { DOUBLE_DASH, DOUBLE_DASH as DOUBLE_DASH$1, InvalidSchemaError, KNOWN_FLAG, PARAMETER, PARAMETER as PARAMETER$1, UNKNOWN_FLAG, parse } from "@clerc/parser";
+import { camelCase, looseIsArray, toArray } from "@clerc/utils";
 import { LiteEmit } from "lite-emit";
 
-//#region ../utils/src/index.ts
-const looseIsArray = (arr) => Array.isArray(arr);
-const toArray = (a) => Array.isArray(a) ? a : [a];
+//#region ../advanced-types/src/errors.ts
+var FlagValidationError = class extends Error {};
+
+//#endregion
+//#region ../advanced-types/src/index.ts
+var src_exports = /* @__PURE__ */ __exportAll({
+	Enum: () => Enum,
+	FlagValidationError: () => FlagValidationError,
+	Range: () => Range,
+	Regex: () => Regex
+});
 /**
-* Converts a dash- or space-separated string to camelCase.
-* Not using regexp for better performance, because this function is used in parser.
+* Creates a Enum type function that validates the input against allowed values.
+* The display name will be formatted as "value1 | value2 | ..." for help
+* output.
+*
+* @example
+*
+* ```typescript
+* const format = Enum(["json", "yaml", "xml"]);
+* // Help output will show: json | yaml | xml
+* ```
+*
+* @param values - Array of allowed string values
+* @returns A TypeFunction that validates and returns the input value
+* @throws {Error} If the value is not in the allowed values list
 */
-function camelCase(str) {
-	const firstIdx = Math.min(str.includes("-") ? str.indexOf("-") : Infinity, str.includes(" ") ? str.indexOf(" ") : Infinity);
-	if (firstIdx === Infinity) return str;
-	let result = str.slice(0, firstIdx);
-	for (let i = firstIdx; i < str.length; i++) if ((str[i] === "-" || str[i] === " ") && i + 1 < str.length) {
-		const nextChar = str.charCodeAt(i + 1);
-		if (nextChar >= 97 && nextChar <= 122) {
-			result += String.fromCharCode(nextChar - 32);
-			i++;
-		} else {
-			result += str[i + 1];
-			i++;
-		}
-	} else if (str[i] !== "-" && str[i] !== " ") result += str[i];
-	return result;
+function Enum(...values) {
+	const fn = ((value) => {
+		if (!values.includes(value)) throw new FlagValidationError(`Invalid value: ${value}. Must be one of: ${values.join(", ")}`);
+		return value;
+	});
+	fn.display = values.join(" | ");
+	return fn;
+}
+/**
+* Creates a range type function that validates the input is a number within the
+* specified range.
+*
+* @param min - The minimum acceptable value (inclusive)
+* @param max - The maximum acceptable value (inclusive)
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value is not a number or is outside the specified
+*   range
+*/
+function Range(min, max) {
+	const fn = ((value) => {
+		const num = Number(value);
+		if (Number.isNaN(num) || num < min || num > max) throw new FlagValidationError(`Invalid value: ${value}. Must be a number between ${min} and ${max}`);
+		return num;
+	});
+	fn.display = `${min} - ${max}`;
+	return fn;
+}
+/**
+* Creates a regex type function that validates the input against the provided
+* pattern.
+*
+* @param pattern - The regular expression pattern to validate against
+* @param description - Optional description for display purposes
+* @returns A TypeFunction that validates the input value
+* @throws {Error} If the value does not match the regex pattern
+*/
+function Regex(pattern, description) {
+	const fn = ((value) => {
+		if (!pattern.test(value)) throw new FlagValidationError(`Invalid value: ${value}. Must match pattern: ${pattern}`);
+		return value;
+	});
+	fn.display = description ?? `Regex: ${pattern.toString()}`;
+	return fn;
 }
 
 //#endregion
@@ -371,4 +420,4 @@ function createStopAtFirstParameter() {
 const definePlugin = (plugin) => plugin;
 
 //#endregion
-export { Clerc, DOUBLE_DASH, InvalidCommandError, InvalidParametersError, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, Types, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, extractParameterInfo, normalizeFlagValue, normalizeParameterValue, resolveCommand };
+export { Clerc, DOUBLE_DASH, InvalidCommandError, InvalidParametersError, InvalidSchemaError, KNOWN_FLAG, MissingRequiredFlagError, MissingRequiredMetadataError, NoCommandSpecifiedError, NoSuchCommandError, PARAMETER, src_exports as Types, UNKNOWN_FLAG, createStopAtFirstParameter, defineCommand, definePlugin, extractParameterInfo, normalizeFlagValue, normalizeParameterValue, resolveCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/core",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc core",
@@ -24,19 +24,12 @@
   "license": "MIT",
   "sideEffects": false,
   "exports": {
-    ".": "./dist/index.js"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "*": [
-        "./dist/*",
-        "./dist/index.d.ts"
-      ]
-    }
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
   },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],
@@ -45,11 +38,11 @@
   },
   "dependencies": {
     "lite-emit": "^4.0.0",
-    "@clerc/advanced-types": "1.0.2",
-    "@clerc/parser": "1.0.2"
+    "@clerc/parser": "1.1.0",
+    "@clerc/utils": "1.1.0"
   },
   "devDependencies": {
     "is-platform": "^1.0.0",
-    "@clerc/utils": "1.0.2"
+    "@clerc/advanced-types": "1.1.0"
   }
 }