@clerc/parser 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -172,4 +172,49 @@ declare function createParser<T extends FlagsDefinition>(options?: ParserOptions
 };
 declare const parse: <T extends FlagsDefinition>(args: string[], options?: ParserOptions<T>) => ParsedResult<InferFlags<T>>;
 //#endregion
-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 };
+//#region src/utils.d.ts
+/**
+* Infers the implicit default value for a flag type based on its type
+* constructor. This is useful for help output to show the default values of
+* types that have built-in defaults.
+*
+* - Boolean: false
+* - [Boolean] (Counter): 0
+* - [T] (Array): []
+* - Object: {}
+* - Others: undefined (no implicit default)
+*
+* @param type The type value (constructor or array of constructor)
+* @returns The inferred default value, or undefined if no implicit default
+*/
+declare function inferDefault(type: TypeValue): unknown;
+/**
+* Default value coercion for Object type. Converts "true" / "" to true, "false"
+* to false, other values remain unchanged.
+*
+* @param value The raw string value from CLI
+* @returns Coerced value (boolean or string)
+*/
+declare function coerceObjectValue(value: string): string | boolean;
+/**
+* Sets a value at a nested path in an object, creating intermediate objects as
+* needed. Does NOT apply type conversion - value is set as-is. Overwrites
+* existing values.
+*
+* @param obj The target object
+* @param path Dot-separated path (e.g., "foo.bar.baz")
+* @param value The value to set (used as-is, no type conversion)
+*/
+declare function setDotValues(obj: any, path: string, value: any): void;
+/**
+* Similar to setDotValues but handles duplicate keys by converting to arrays.
+* Does NOT apply type conversion - value is set as-is. Useful for flags that
+* can be specified multiple times.
+*
+* @param obj The target object
+* @param path Dot-separated path (e.g., "foo.bar")
+* @param value The value to set or append (used as-is, no type conversion)
+*/
+declare function appendDotValues(obj: any, path: string, value: any): void;
+//#endregion
+export { BaseFlagOptions, DOUBLE_DASH, FlagDefaultValue, FlagDefaultValueFunction, FlagDefinitionValue, FlagOptions, FlagsDefinition, IgnoreFunction, InferFlags, InvalidSchemaError, KNOWN_FLAG, ObjectInputType, PARAMETER, ParsedResult, ParserOptions, RawInputType, TypeFunction, TypeValue, UNKNOWN_FLAG, appendDotValues, coerceObjectValue, createParser, inferDefault, parse, setDotValues };

package/dist/index.mjs

@@ -1,302 +1 @@
-import { camelCase, looseIsArray, resolveValue } from "@clerc/utils";
-
-//#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 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.`);
-		if (name.length < 2) throw new InvalidSchemaError(`${prefix} name must be at least 2 characters long.`);
-		const names = [name];
-		if (options.short) {
-			if (options.short.length !== 1) throw new InvalidSchemaError(`${prefix} short flag must be exactly 1 character long.`);
-			names.push(options.short);
-		}
-		if (names.some(isNameInvalid)) throw new InvalidSchemaError(`${prefix} contains reserved characters, which are used as delimiters.`);
-		if (options.required && options.default !== void 0) throw new InvalidSchemaError(`${prefix} cannot be both required and have a default value.`);
-	}
-	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.short) aliases.set(normalized.short, name);
-	}
-	return {
-		configs,
-		aliases
-	};
-}
-
-//#endregion
-//#region src/utils.ts
-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/parse.ts
-const DOUBLE_DASH = "--";
-function createParser(options = {}) {
-	const { flags: flagsConfig = {}, delimiters, ignore } = resolveParserOptions(options);
-	const { configs, aliases } = buildConfigsAndAliases(delimiters, flagsConfig);
-	function resolve(name, isShortFlag = false) {
-		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);
-		if (!isShortFlag && config.short === rootName) return;
-		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)) {
-			const isShortFlag = secondChar !== 45;
-			return !!resolve(isShortFlag ? arg[1] : arg.slice(2), isShortFlag);
-		}
-		if (secondChar === 45 && len > 2) return isLetter(arg.charCodeAt(2));
-		return false;
-	}
-	function isKnownFlag(arg) {
-		if (arg.charCodeAt(1) === 45) {
-			const { rawName } = splitNameAndValue(arg.slice(2), delimiters);
-			if (resolve(rawName, false)) return true;
-			if (resolveNegated(rawName)) return true;
-			return false;
-		}
-		const chars = arg.slice(1);
-		for (const char of chars) if (!resolve(char, true)) return false;
-		return true;
-	}
-	const parse$1 = (args) => {
-		const result = {
-			parameters: [],
-			doubleDash: [],
-			flags: {},
-			raw: args,
-			unknown: {},
-			ignored: [],
-			missingRequiredFlags: []
-		};
-		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 isShortFlag = !current.startsWith(DOUBLE_DASH);
-			const chars = current.slice(isShortFlag ? 1 : 2);
-			if (isShortFlag) {
-				const charsLen = chars.length;
-				for (let j = 0; j < charsLen; j++) {
-					const char = chars[j];
-					const resolved = resolve(char, true);
-					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 value = hasNext && !shouldProcessAsFlag(next) ? eat() ?? "" : "";
-						setValueByType(result.flags, key, value, 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] = resolveValue(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;
-			else if (config.required) result.missingRequiredFlags.push(key);
-		}
-		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 };
+import{camelCase as e,hasOwn as t,looseIsArray as n,resolveValue as r}from"@clerc/utils";var i=class extends Error{constructor(e){super(`Invalid schema: ${e}`),this.name=`InvalidSchemaError`}};const a=`known-flag`,o=`unknown-flag`,s=`parameter`;function c(e,t,n,r,i,c){let l=0,u=!1,d=e.length,f={current:``,index:0,hasNext:!1,next:``,shouldIgnore:e=>i?i(n(e)?r(e)?a:o:s,e):!1,eat:()=>{if(l+1>=d)return;let t=e[l+1];if(f.shouldIgnore(t)){f.exit();return}return l++,p(),e[l]},exit:(n=!0)=>{u||=(n&&t.ignored.push(...e.slice(l+1)),!0)}};function p(){f.current=e[l],f.index=l,f.hasNext=l+1<d,f.next=f.hasNext?e[l+1]:``}for(l=0;l<d&&!u;l++)p(),c(f)}const l={delimiters:[`=`,`:`]},u=(e={})=>({...l,...e}),d=e=>typeof e==`function`||n(e)?{type:e}:e;function f(t,n){let r=new Map,a=new Map,o=e=>t.some(t=>e.includes(t))||e.includes(` `)||e.includes(`.`);function s(e,t){let n=`Flag "${e}"`;if(Array.isArray(t.type)&&t.type.length>1)throw new i(`${n} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);if(e.length<2)throw new i(`${n} name must be at least 2 characters long.`);let r=[e];if(t.short){if(t.short.length!==1)throw new i(`${n} short flag must be exactly 1 character long.`);r.push(t.short)}if(r.some(o))throw new i(`${n} contains reserved characters, which are used as delimiters.`);if(t.required&&t.default!==void 0)throw new i(`${n} cannot be both required and have a default value.`)}for(let[t,i]of Object.entries(n)){let n=d(i);s(t,n),r.set(t,n),a.set(t,t),a.set(e(t),t),n.short&&a.set(n.short,t)}return{configs:r,aliases:a}}const p=(e,t)=>Array.isArray(e)&&e[0]===t;function m(e){if(n(e))return p(e,Boolean)?0:[];if(e===Boolean)return!1;if(e===Object)return{}}const h=e=>e>=65&&e<=90||e>=97&&e<=122,g=e=>e>=48&&e<=57;function _(e,t,r,i){let{type:a}=i;n(a)?p(a,Boolean)?e[t]=(e[t]??0)+1:(e[t]??=[]).push(a[0](r)):e[t]=a(r)}function v(e){return e===`true`||e===``?!0:e===`false`?!1:e}function y(e,t,n){let r=t.split(`.`),i=e;for(let e=0;e<r.length-1;e++){let t=r[e];i[t]??={},i=i[t]}let a=r[r.length-1];i[a]=n}function b(e,n,r){let i=n.split(`.`),a=e;for(let e=0;e<i.length-1;e++){let n=i[e];if(t(a,n)&&(typeof a[n]!=`object`||a[n]===null))return;a[n]??={},a=a[n]}let o=i[i.length-1];if(t(a,o)){let e=a[o];Array.isArray(e)?e.push(r):a[o]=[e,r]}else a[o]=r}function x(e,t){let n=-1,r=0;for(let i of t){let t=e.indexOf(i);t!==-1&&(n===-1||t<n)&&(n=t,r=i.length)}return n===-1?{rawName:e,rawValue:void 0,hasSep:!1}:{rawName:e.slice(0,n),rawValue:e.slice(n+r),hasSep:!0}}const S=`--`;function C(t={}){let{flags:n={},delimiters:i,ignore:a}=u(t),{configs:o,aliases:s}=f(i,n);function l(t,n=!1){let r=t.indexOf(`.`),i=r===-1?t:t.slice(0,r),a=s.get(i);if(!a&&(a=s.get(e(i)),!a))return;let c=o.get(a);if(!(!n&&c.short===i))return{key:a,config:c,path:r===-1?void 0:t.slice(r+1)}}function d(e){if(!e.startsWith(`no`))return;let t=e[2]===`-`?e.slice(3):e.length>2&&e.charCodeAt(2)>=65&&e.charCodeAt(2)<=90?e[2].toLowerCase()+e.slice(3):``;if(t){let e=l(t);if(e?.config.type===Boolean&&e.config.negatable!==!1)return e}}function y(e){if(e.charCodeAt(0)!==45)return!1;let t=e.length;if(t<2)return!1;let n=e.charCodeAt(1);if(h(n))return!0;if(g(n)){let t=n!==45;return!!l(t?e[1]:e.slice(2),t)}return n===45&&t>2?h(e.charCodeAt(2)):!1}function S(e){if(e.charCodeAt(1)===45){let{rawName:t}=x(e.slice(2),i);return!!(l(t,!1)||d(t))}let t=e.slice(1);for(let e of t)if(!l(e,!0))return!1;return!0}return{parse:t=>{let n={parameters:[],doubleDash:[],flags:{},raw:t,unknown:{},ignored:[],missingRequiredFlags:[]};c(t,n,y,S,a,({current:r,eat:a,exit:o,hasNext:s,index:c,next:u,shouldIgnore:f})=>{if(r===`--`){n.doubleDash.push(...t.slice(c+1)),o(!1);return}if(f(r)){n.ignored.push(r),o();return}if(!y(r)){n.parameters.push(r);return}let m=!r.startsWith(`--`),h=r.slice(m?1:2);if(m){let e=h.length;for(let t=0;t<e;t++){let r=h[t],i=l(r,!0);if(!i){n.unknown[r]=!0;continue}let{key:o,config:c}=i,d=c.type;if(d===Boolean||p(d,Boolean))_(n.flags,o,`true`,c);else if(t+1<e){_(n.flags,o,h.slice(t+1),c);break}else{let e=s&&!y(u)?a()??``:``;_(n.flags,o,e,c)}}}else{let{rawName:t,rawValue:r,hasSep:o}=x(h,i),c=l(t),f=!1;if(!c){let e=d(t);e&&(c=e,f=!0)}if(!c){let i=e(t);if(o)n.unknown[i]=r;else if(s&&!y(u)){let e=a();n.unknown[i]=e??!0}else n.unknown[i]=!0;return}let{key:p,config:m,path:g}=c;if(g){if(m.type===Object){n.flags[p]??={};let e=o?r:s&&!y(u)?a()??``:``;b(n.flags[p],g,v(e))}}else if(m.type===Boolean){let e=o?r!==`false`:!0;n.flags[p]=f?!e:e}else{let e=o?r:s&&!y(u)?a()??``:``;_(n.flags,p,e,m)}}});for(let[e,t]of o.entries())n.flags[e]===void 0&&(t.default===void 0?t.required?n.missingRequiredFlags.push(e):n.flags[e]=m(t.type):n.flags[e]=r(t.default));return n}}}const w=(e,t={})=>C(t).parse(e);export{S as DOUBLE_DASH,i as InvalidSchemaError,a as KNOWN_FLAG,s as PARAMETER,o as UNKNOWN_FLAG,b as appendDotValues,v as coerceObjectValue,C as createParser,m as inferDefault,w as parse,y as setDotValues};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clerc/parser",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Ray <i@mk1.io> (https://github.com/so1ve)",
   "type": "module",
   "description": "Clerc parser",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clerc/utils": "1.1.0"
+    "@clerc/utils": "1.2.0"
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",