@clerc/parser 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Ray <https://github.com/so1ve>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# @clerc/parser
+
+A powerful, lightweight, and flexible command-line arguments parser.
+
+## Installation
+
+```bash
+npm install @clerc/parser
+# or
+yarn add @clerc/parser
+# or
+pnpm add @clerc/parser
+```
+
+## Usage
+
+The core of this package is the `parse` function. It takes an array of arguments and a configuration object, and returns a structured object containing the parsed flags, parameters, and other useful information.
+
+```typescript
+import { parse } from "@clerc/parser";
+
+const { flags, parameters, unknown } = parse(process.argv.slice(2), {
+	flags: {
+		// Define your flags here
+		port: {
+			type: Number,
+			alias: "p",
+			default: 8080,
+		},
+		help: {
+			type: Boolean,
+			alias: "h",
+		},
+	},
+});
+
+console.log("Flags:", flags);
+console.log("Parameters:", parameters);
+console.log("Unknown args:", unknown);
+```
+
+## API
+
+### `parse(args, options)`
+
+#### `args`
+
+- Type: `string[]`
+- The array of command-line arguments to parse (e.g., `process.argv.slice(2)`).
+
+#### `options`
+
+- Type: `ParseOptions`
+
+An object to configure the parser.
+
+- **`flags`**: An object defining the flags to parse.
+  - Key: The name of the flag (in camelCase).
+  - Value: The flag's configuration, which can be a type constructor (`String`, `Number`, `Boolean`) or a custom function that takes a string and returns a parsed value or an object with the following properties:
+    - `type`: The type of the flag. Can be a constructor like `String`, `Number`, `Boolean`, `Object`, an array of a constructor (e.g., `[String]`), or a custom function that takes a string and returns a parsed value.
+    - `alias`: A string or an array of strings for alternative names (e.g., short flags).
+  - `default`: A default value for the flag if it's not provided in the arguments. Can be a value or a function that returns a value.
+  - `negatable`: (For Booleans) Whether to support `--no-<flag>` syntax. Defaults to `true`.
+- **`ignore`**: A function to conditionally stop parsing. It receives the `type` (`flag` or `parameter`) and the `arg` string, and should return `true` to stop parsing from that point.
+
+#### Returns
+
+An object with the following properties:
+
+- `flags`: An object containing the parsed flags.
+- `parameters`: An array of positional arguments.
+- `unknown`: An object containing flags that were not defined in the schema.
+- `doubleDash`: An array of arguments that appear after a `--`.
+- `ignored`: An array of arguments that were ignored due to the `ignore` function.
+
+## Features
+
+### Basic Types
+
+Supports `Boolean`, `String`, and `Number`.
+
+```typescript
+const { flags } = parse(["--bool", "--str", "hello", "--num", "42"], {
+	flags: {
+		bool: { type: Boolean },
+		str: { type: String },
+		num: { type: Number },
+	},
+});
+// flags: { bool: true, str: "hello", num: 42 }
+```
+
+### Aliases
+
+Use `alias` to define short or alternative names for flags.
+
+```typescript
+const { flags } = parse(["-b", "-s", "hello"], {
+	flags: {
+		bool: { type: Boolean, alias: "b" },
+		str: { type: String, alias: "s" },
+	},
+});
+// flags: { bool: true, str: "hello" }
+```
+
+### Arrays and Counters
+
+- To collect multiple values for a flag, use an array type like `[String]`.
+- To count the occurrences of a boolean flag, use `[Boolean]`.
+
+```typescript
+// Array of strings
+const { flags: arrayFlags } = parse(["--arr", "a", "--arr", "b"], {
+	flags: {
+		arr: { type: [String] },
+	},
+});
+// arrayFlags: { arr: ["a", "b"] }
+
+// Counter
+const { flags: counterFlags } = parse(["-vvv"], {
+	flags: {
+		verbose: { type: [Boolean], alias: "v" },
+	},
+});
+// counterFlags: { verbose: 3 }
+```
+
+### Merged Short Flags
+
+Multiple boolean short flags can be combined. The last flag in the group can take a value.
+
+```typescript
+// -abc => a=true, b=true, c=true
+const { flags: merged } = parse(["-abc"], {
+	flags: {
+		a: Boolean,
+		b: Boolean,
+		c: Boolean,
+	},
+});
+// merged: { a: true, b: true, c: true }
+
+// -ab val => a=true, b="val"
+const { flags: withValue } = parse(["-ab", "val"], {
+	flags: {
+		a: Boolean,
+		b: String,
+	},
+});
+// or -abval, b is not boolean
+const { flags: withValue } = parse(["-abval"], {
+	flags: {
+		a: Boolean,
+		b: String,
+	},
+});
+// withValue: { a: true, b: "val" }
+```
+
+### Default Values
+
+Provide a `default` value for flags that are not present.
+
+```typescript
+const { flags } = parse([], {
+	flags: {
+		str: { type: String, default: "default" },
+		num: { type: Number, default: 123 },
+		fn: { type: String, default: () => "computed" },
+	},
+});
+// flags: { str: "default", num: 123, fn: "computed" }
+```
+
+By default, booleans, counters, arrays and objects have implicit defaults when `default` is not provided:
+
+- Boolean: `false`
+- Counter: `0`
+- Array: `[]`
+- Object: `{}`
+
+### Negatable Flags
+
+Boolean flags are negatable by default using the `--no-` prefix.
+
+If you want to disable this behavior, set `negatable: false` in the flag configuration. Passing `--no-<flag>` will then be treated as an unknown flag.
+
+```typescript
+const { flags, unknown } = parse(
+	["--no-cache", "--no-ssl=false", "--no-disable-negate"],
+	{
+		flags: {
+			cache: { type: Boolean, default: true },
+			ssl: { type: Boolean, default: true },
+			disableNegate: { type: Boolean, negatable: false, default: true },
+		},
+	},
+);
+// flags: { cache: false, ssl: true, disableNegate: true }
+// unknown: { noDisableNegate: true }
+```
+
+### Custom Type Functions
+
+You can provide a custom function to the `type` property for advanced parsing logic. The function receives the string value and should return the parsed value.
+
+```typescript
+// Let's limit port between 1 and 65535
+const { flags } = parse(["--port", "8080"], {
+	flags: {
+		port: {
+			type: (value: string) => {
+				const parsed = Number.parseInt(value, 10);
+				if (Number.isNaN(parsed)) {
+					throw new TypeError("Port must be a number!");
+				}
+				if (parsed < 1 || parsed > 65_535) {
+					throw new Error("Port must be between 1 and 65535!");
+				}
+
+				return parsed;
+			},
+		},
+	},
+});
+// flags: { port: 8080 }
+```
+
+### Dot-Nested Objects
+
+Define flags with `Object` type to parse dot-notation arguments into a nested object.
+
+```typescript
+const { flags } = parse(
+	["--config.port", "8080", "--config.host", "localhost"],
+	{
+		flags: {
+			config: { type: Object },
+		},
+	},
+);
+// flags: { config: { port: "8080", host: "localhost" } }
+```
+
+Multi-level nesting is also supported.
+
+```typescript
+const { flags } = parse(
+	[
+		"--db.host",
+		"localhost",
+		"--db.port",
+		"5432",
+		"--db.credentials.user",
+		"admin",
+		"--db.credentials.password",
+		"secret",
+	],
+	{
+		flags: {
+			db: { type: Object },
+		},
+	},
+);
+// flags: { db: { host: "localhost", port: "5432", credentials: { user: "admin", password: "secret" } } }
+```
+
+### Unknown Flags
+
+Flags that are not defined in the schema are collected in the `unknown` object. If possible, they will be converted to boolean `true`.
+
+```typescript
+const { flags, unknown } = parse([
+	"--unknown1",
+	"--unknown2=foo",
+	"--unknown3",
+	"bar",
+	"--unknown.foo",
+]);
+
+// unknown: { unknown1: true, unknown2: "foo", unknown3: "bar", "unknown.foo": true }
+```
+
+### Stop Parsing
+
+Use the `ignore` function to stop parsing when a certain condition is met. Subsequent arguments will be added to the `ignored` array.
+
+```typescript
+const { flags, ignored } = parse(["--a", "--b", "stop", "--c"], {
+	flags: {
+		a: Boolean,
+		b: Boolean,
+		c: Boolean,
+	},
+	ignore: (type, arg) => arg === "stop",
+});
+// flags: { a: true, b: true, c: false }
+// ignored: ["stop", "--c"]
+```
+
+You can ignore everything after the first positional parameter by checking the `type`.
+
+```typescript
+const { flags, parameters, ignored } = parse(
+	["--allow-all", "./deno.ts", "--param"],
+	{
+		flags: {
+			allowAll: Boolean,
+		},
+		ignore: (type) => type === "parameter",
+	},
+);
+
+// flags: { allowAll: true }
+// parameters: []
+// ignored: ["./deno.ts", "--param"]
+```
+
+### Double Dash (`--`)
+
+Arguments after `--` are not parsed as flags and are collected in the `doubleDash` array.
+
+```typescript
+const { flags, doubleDash } = parse(["--foo", "--", "--bar"], {
+	flags: {
+		foo: Boolean,
+		bar: Boolean,
+	},
+});
+// flags: { foo: true, bar: false }
+// doubleDash: ["--bar"]
+```

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+//#region src/errors.d.ts
+declare class InvalidSchemaError extends Error {
+  constructor(message: string);
+}
+//#endregion
+//#region ../utils/src/types/type-fest.d.ts
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+//#endregion
+//#region ../utils/src/types/index.d.ts
+type MaybeArray<T> = T | T[];
+//#endregion
+//#region src/types.d.ts
+type FlagDefaultValue<T = unknown> = T | (() => T);
+/**
+* Defines how a string input is converted to the target type T.
+*
+* @template T The target type.
+*/
+type FlagTypeFunction<T = unknown> = (value: string) => T;
+/**
+* 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 FlagType<T = unknown> = FlagTypeFunction<T> | readonly [FlagTypeFunction<T>];
+interface BaseFlagOptions<T extends FlagType = FlagType> {
+  /**
+  * 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;
+  /** Aliases for the flag. */
+  alias?: MaybeArray<string>;
+  /** The default value of the flag. */
+  default?: unknown;
+}
+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 | FlagType;
+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[];
+}
+type InferFlagDefault<T extends FlagDefinitionValue, Fallback> = T extends {
+  default: FlagDefaultValue<infer DefaultType>;
+} ? DefaultType : Fallback;
+type _InferFlags<T extends FlagsDefinition> = { [K in keyof T]: T[K] extends readonly [BooleanConstructor] | {
+  type: readonly [BooleanConstructor];
+} ? number : T[K] extends ObjectConstructor | {
+  type: ObjectConstructor;
+} ? ObjectInputType : T[K] extends readonly [FlagType<infer U>] | {
+  type: readonly [FlagType<infer U>];
+} ? U[] | InferFlagDefault<T[K], never> : T[K] extends FlagType<infer U> | {
+  type: FlagType<infer U>;
+} ? U | InferFlagDefault<T[K], [U] extends [boolean] ? 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 src/iterator.d.ts
+declare const KNOWN_FLAG = "known-flag";
+declare const UNKNOWN_FLAG = "unknown-flag";
+declare const PARAMETER = "parameter";
+//#endregion
+//#region 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>>;
+//#endregion
+export { BaseFlagOptions, DOUBLE_DASH, FlagDefaultValue, FlagDefinitionValue, FlagOptions, FlagType, FlagTypeFunction, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, UNKNOWN_FLAG, createParser, parse };

package/dist/index.js

@@ -0,0 +1,319 @@
+//#region src/errors.ts
+var InvalidSchemaError = class extends Error {
+	constructor(message) {
+		super(`Invalid schema: ${message}`);
+		this.name = "InvalidSchemaError";
+	}
+};
+
+//#endregion
+//#region src/iterator.ts
+const KNOWN_FLAG = "known-flag";
+const UNKNOWN_FLAG = "unknown-flag";
+const PARAMETER = "parameter";
+function iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, callback) {
+	let index = 0;
+	let stopped = false;
+	const argsLength = args.length;
+	const iterator = {
+		current: "",
+		index: 0,
+		hasNext: false,
+		next: "",
+		shouldIgnore: (arg) => {
+			if (ignore) return ignore(shouldProcessAsFlag(arg) ? isKnownFlag(arg) ? KNOWN_FLAG : UNKNOWN_FLAG : PARAMETER, arg);
+			return false;
+		},
+		eat: () => {
+			if (index + 1 >= argsLength) return;
+			const nextArg = args[index + 1];
+			if (iterator.shouldIgnore(nextArg)) {
+				iterator.exit();
+				return;
+			}
+			index++;
+			next();
+			return args[index];
+		},
+		exit: (push = true) => {
+			if (!stopped) {
+				if (push) result.ignored.push(...args.slice(index + 1));
+				stopped = true;
+			}
+		}
+	};
+	function next() {
+		iterator.current = args[index];
+		iterator.index = index;
+		iterator.hasNext = index + 1 < argsLength;
+		iterator.next = iterator.hasNext ? args[index + 1] : "";
+	}
+	for (index = 0; index < argsLength; index++) {
+		if (stopped) break;
+		next();
+		callback(iterator);
+	}
+}
+
+//#endregion
+//#region ../utils/dist/index.js
+const toArray = (a) => Array.isArray(a) ? a : [a];
+/**
+* Converts a dash-separated string to camelCase.
+* Not using regexp for better performance, because this function is used in parser.
+*/
+function camelCase(str) {
+	const dashIdx = str.indexOf("-");
+	if (dashIdx === -1) return str;
+	let result = str.slice(0, dashIdx);
+	for (let i = dashIdx; i < str.length; i++) if (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] !== "-") result += str[i];
+	return result;
+}
+
+//#endregion
+//#region src/utils.ts
+const looseIsArray = (arr) => Array.isArray(arr);
+const isArrayOfType = (arr, type) => Array.isArray(arr) && arr[0] === type;
+/**
+* Check if it's a letter (a-z: 97-122, A-Z: 65-90)
+*/
+const isLetter = (charCode) => charCode >= 65 && charCode <= 90 || charCode >= 97 && charCode <= 122;
+/**
+* Check if it's a digit (0-9: 48-57)
+*/
+const isDigit = (charCode) => charCode >= 48 && charCode <= 57;
+function setValueByType(flags, key, value, config) {
+	const { type } = config;
+	if (looseIsArray(type)) if (isArrayOfType(type, Boolean)) flags[key] = (flags[key] ?? 0) + 1;
+	else (flags[key] ??= []).push(type[0](value));
+	else flags[key] = type(value);
+}
+function setDotValues(obj, path, value) {
+	const keys = path.split(".");
+	let current = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const key = keys[i];
+		current[key] ??= {};
+		current = current[key];
+	}
+	const lastKey = keys[keys.length - 1];
+	if (value === "true" || value === "") current[lastKey] = true;
+	else if (value === "false") current[lastKey] = false;
+	else current[lastKey] = value;
+}
+function splitNameAndValue(arg, delimiters) {
+	let sepIdx = -1;
+	let delimiterLen = 0;
+	for (const delimiter of delimiters) {
+		const idx = arg.indexOf(delimiter);
+		if (idx !== -1 && (sepIdx === -1 || idx < sepIdx)) {
+			sepIdx = idx;
+			delimiterLen = delimiter.length;
+		}
+	}
+	if (!(sepIdx !== -1)) return {
+		rawName: arg,
+		rawValue: void 0,
+		hasSep: false
+	};
+	return {
+		rawName: arg.slice(0, sepIdx),
+		rawValue: arg.slice(sepIdx + delimiterLen),
+		hasSep: true
+	};
+}
+
+//#endregion
+//#region src/config.ts
+const defaultParserOptions = { delimiters: ["=", ":"] };
+const resolveParserOptions = (options = {}) => ({
+	...defaultParserOptions,
+	...options
+});
+const normalizeConfig = (config) => typeof config === "function" || looseIsArray(config) ? { type: config } : config;
+const BUILDTIN_DELIMITERS_RE = /[\s.]/;
+function buildConfigsAndAliases(delimiters, flags) {
+	const configs = /* @__PURE__ */ new Map();
+	const aliases = /* @__PURE__ */ new Map();
+	const isNameInvalid = (name) => delimiters.some((char) => name.includes(char)) || BUILDTIN_DELIMITERS_RE.test(name);
+	function validateFlagOptions(name, options) {
+		const prefix = `Flag "${name}"`;
+		if (Array.isArray(options.type) && options.type.length > 1) throw new InvalidSchemaError(`${prefix} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);
+		const names = [name];
+		if (options.alias) names.push(...toArray(options.alias));
+		if (names.some(isNameInvalid)) throw new InvalidSchemaError(`${prefix} contains reserved characters, which are used as delimiters.`);
+	}
+	for (const [name, config] of Object.entries(flags)) {
+		const normalized = normalizeConfig(config);
+		validateFlagOptions(name, normalized);
+		configs.set(name, normalized);
+		aliases.set(name, name);
+		aliases.set(camelCase(name), name);
+		if (normalized.alias) {
+			const list = Array.isArray(normalized.alias) ? normalized.alias : [normalized.alias];
+			for (const a of list) aliases.set(a, name);
+		}
+	}
+	return {
+		configs,
+		aliases
+	};
+}
+
+//#endregion
+//#region src/parse.ts
+const DOUBLE_DASH = "--";
+function createParser(options = {}) {
+	const { flags: flagsConfig = {}, delimiters, ignore } = resolveParserOptions(options);
+	const { configs, aliases } = buildConfigsAndAliases(delimiters, flagsConfig);
+	function resolve(name) {
+		const dotIdx = name.indexOf(".");
+		const rootName = dotIdx === -1 ? name : name.slice(0, dotIdx);
+		let key = aliases.get(rootName);
+		if (!key) {
+			key = aliases.get(camelCase(rootName));
+			if (!key) return;
+		}
+		const config = configs.get(key);
+		return {
+			key,
+			config,
+			path: dotIdx === -1 ? void 0 : name.slice(dotIdx + 1)
+		};
+	}
+	function resolveNegated(name) {
+		if (!name.startsWith("no")) return;
+		const possibleName = name[2] === "-" ? name.slice(3) : name.length > 2 && /[A-Z]/.test(name[2]) ? name[2].toLowerCase() + name.slice(3) : "";
+		if (possibleName) {
+			const possibleResolved = resolve(possibleName);
+			if (possibleResolved?.config.type === Boolean && possibleResolved.config.negatable !== false) return possibleResolved;
+		}
+	}
+	function shouldProcessAsFlag(arg) {
+		if (arg.charCodeAt(0) !== 45) return false;
+		const len = arg.length;
+		if (len < 2) return false;
+		const secondChar = arg.charCodeAt(1);
+		if (isLetter(secondChar)) return true;
+		if (isDigit(secondChar)) return !!resolve(secondChar !== 45 ? arg[1] : arg.slice(2));
+		if (secondChar === 45 && len > 2) return isLetter(arg.charCodeAt(2));
+		return false;
+	}
+	function isKnownFlag(arg) {
+		const secondChar = arg.charCodeAt(1);
+		if (secondChar === 45) {
+			const { rawName } = splitNameAndValue(arg.slice(2), delimiters);
+			if (resolve(rawName)) return true;
+			if (resolveNegated(rawName)) return true;
+			return false;
+		}
+		if (isDigit(secondChar)) return true;
+		const chars = arg.slice(1);
+		for (const char of chars) if (!resolve(char)) return false;
+		return true;
+	}
+	const parse$1 = (args) => {
+		const result = {
+			parameters: [],
+			doubleDash: [],
+			flags: {},
+			raw: args,
+			unknown: {},
+			ignored: []
+		};
+		iterateArgs(args, result, shouldProcessAsFlag, isKnownFlag, ignore, ({ current, eat, exit, hasNext, index, next, shouldIgnore }) => {
+			if (current === DOUBLE_DASH) {
+				result.doubleDash.push(...args.slice(index + 1));
+				exit(false);
+				return;
+			}
+			if (shouldIgnore(current)) {
+				result.ignored.push(current);
+				exit();
+				return;
+			}
+			if (!shouldProcessAsFlag(current)) {
+				result.parameters.push(current);
+				return;
+			}
+			const isAlias = !current.startsWith(DOUBLE_DASH);
+			const chars = current.slice(isAlias ? 1 : 2);
+			if (isAlias) {
+				const charsLen = chars.length;
+				for (let j = 0; j < charsLen; j++) {
+					const char = chars[j];
+					const resolved = resolve(char);
+					if (!resolved) {
+						result.unknown[char] = true;
+						continue;
+					}
+					const { key, config } = resolved;
+					const configType = config.type;
+					if (configType === Boolean || isArrayOfType(configType, Boolean)) setValueByType(result.flags, key, "true", config);
+					else if (j + 1 < charsLen) {
+						setValueByType(result.flags, key, chars.slice(j + 1), config);
+						break;
+					} else {
+						const nextValue = eat();
+						if (nextValue && !shouldProcessAsFlag(nextValue)) setValueByType(result.flags, key, nextValue, config);
+					}
+				}
+			} else {
+				const { rawName, rawValue, hasSep } = splitNameAndValue(chars, delimiters);
+				let resolved = resolve(rawName);
+				let isNegated = false;
+				if (!resolved) {
+					const negated = resolveNegated(rawName);
+					if (negated) {
+						resolved = negated;
+						isNegated = true;
+					}
+				}
+				if (!resolved) {
+					const key$1 = camelCase(rawName);
+					if (hasSep) result.unknown[key$1] = rawValue;
+					else if (hasNext && !shouldProcessAsFlag(next)) {
+						const value = eat();
+						result.unknown[key$1] = value ?? true;
+					} else result.unknown[key$1] = true;
+					return;
+				}
+				const { key, config, path } = resolved;
+				if (path) {
+					if (config.type === Object) {
+						result.flags[key] ??= {};
+						const value = hasSep ? rawValue : hasNext && !shouldProcessAsFlag(next) ? eat() ?? "" : "";
+						setDotValues(result.flags[key], path, value);
+					}
+				} else if (config.type === Boolean) {
+					const value = hasSep ? rawValue !== "false" : true;
+					result.flags[key] = isNegated ? !value : value;
+				} else {
+					const value = hasSep ? rawValue : hasNext && !shouldProcessAsFlag(next) ? eat() ?? "" : "";
+					setValueByType(result.flags, key, value, config);
+				}
+			}
+		});
+		for (const [key, config] of configs.entries()) if (result.flags[key] === void 0) {
+			if (config.default !== void 0) result.flags[key] = typeof config.default === "function" ? config.default() : config.default;
+			else if (Array.isArray(config.type)) result.flags[key] = isArrayOfType(config.type, Boolean) ? 0 : [];
+			else if (config.type === Object) result.flags[key] = {};
+			else if (config.type === Boolean) result.flags[key] = false;
+		}
+		return result;
+	};
+	return { parse: parse$1 };
+}
+const parse = (args, options = {}) => createParser(options).parse(args);
+
+//#endregion
+export { DOUBLE_DASH, InvalidSchemaError, KNOWN_FLAG, PARAMETER, UNKNOWN_FLAG, createParser, parse };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@clerc/parser",
+  "version": "1.0.0-beta.1",
+  "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
+  "type": "module",
+  "description": "Clerc parser",
+  "keywords": [
+    "args",
+    "arguments",
+    "argv",
+    "clerc",
+    "cli",
+    "getopt",
+    "parser",
+    "terminal",
+    "utils"
+  ],
+  "homepage": "https://github.com/clercjs/clerc/tree/main/packages/parser#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clercjs/clerc.git",
+    "directory": "/"
+  },
+  "bugs": {
+    "url": "https://github.com/clercjs/clerc/issues"
+  },
+  "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"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5",
+    "@types/nopt": "^3.0.32",
+    "@types/yargs-parser": "^21.0.3",
+    "minimist": "^1.2.8",
+    "mri": "^1.2.0",
+    "nopt": "^9.0.0",
+    "type-flag": "^4.0.3",
+    "yargs-parser": "^22.0.0",
+    "@clerc/utils": "1.0.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}