@clerc/parser 1.1.1 → 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 +1 @@
-import{camelCase as e,looseIsArray as t,resolveValue as n}from"@clerc/utils";var r=class extends Error{constructor(e){super(`Invalid schema: ${e}`),this.name=`InvalidSchemaError`}};const i=`known-flag`,a=`unknown-flag`,o=`parameter`;function s(e,t,n,r,s,c){let l=0,u=!1,d=e.length,f={current:``,index:0,hasNext:!1,next:``,shouldIgnore:e=>s?s(n(e)?r(e)?i:a:o,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 c={delimiters:[`=`,`:`]},l=(e={})=>({...c,...e}),u=e=>typeof e==`function`||t(e)?{type:e}:e,d=/[\s.]/;function f(t,n){let i=new Map,a=new Map,o=e=>t.some(t=>e.includes(t))||d.test(e);function s(e,t){let n=`Flag "${e}"`;if(Array.isArray(t.type)&&t.type.length>1)throw new r(`${n} has an invalid type array. Only single-element arrays are allowed to denote multiple occurrences.`);if(e.length<2)throw new r(`${n} name must be at least 2 characters long.`);let i=[e];if(t.short){if(t.short.length!==1)throw new r(`${n} short flag must be exactly 1 character long.`);i.push(t.short)}if(i.some(o))throw new r(`${n} contains reserved characters, which are used as delimiters.`);if(t.required&&t.default!==void 0)throw new r(`${n} cannot be both required and have a default value.`)}for(let[t,r]of Object.entries(n)){let n=u(r);s(t,n),i.set(t,n),a.set(t,t),a.set(e(t),t),n.short&&a.set(n.short,t)}return{configs:i,aliases:a}}const p=(e,t)=>Array.isArray(e)&&e[0]===t,m=e=>e>=65&&e<=90||e>=97&&e<=122,h=e=>e>=48&&e<=57;function g(e,n,r,i){let{type:a}=i;t(a)?p(a,Boolean)?e[n]=(e[n]??0)+1:(e[n]??=[]).push(a[0](r)):e[n]=a(r)}function _(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];n===`true`||n===``?i[a]=!0:n===`false`?i[a]=!1:i[a]=n}function v(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 y=`--`;function b(t={}){let{flags:r={},delimiters:i,ignore:a}=l(t),{configs:o,aliases:c}=f(i,r);function u(t,n=!1){let r=t.indexOf(`.`),i=r===-1?t:t.slice(0,r),a=c.get(i);if(!a&&(a=c.get(e(i)),!a))return;let s=o.get(a);if(!(!n&&s.short===i))return{key:a,config:s,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&&/[A-Z]/.test(e[2])?e[2].toLowerCase()+e.slice(3):``;if(t){let e=u(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(m(n))return!0;if(h(n)){let t=n!==45;return!!u(t?e[1]:e.slice(2),t)}return n===45&&t>2?m(e.charCodeAt(2)):!1}function b(e){if(e.charCodeAt(1)===45){let{rawName:t}=v(e.slice(2),i);return!!(u(t,!1)||d(t))}let t=e.slice(1);for(let e of t)if(!u(e,!0))return!1;return!0}return{parse:t=>{let r={parameters:[],doubleDash:[],flags:{},raw:t,unknown:{},ignored:[],missingRequiredFlags:[]};s(t,r,y,b,a,({current:n,eat:a,exit:o,hasNext:s,index:c,next:l,shouldIgnore:f})=>{if(n===`--`){r.doubleDash.push(...t.slice(c+1)),o(!1);return}if(f(n)){r.ignored.push(n),o();return}if(!y(n)){r.parameters.push(n);return}let m=!n.startsWith(`--`),h=n.slice(m?1:2);if(m){let e=h.length;for(let t=0;t<e;t++){let n=h[t],i=u(n,!0);if(!i){r.unknown[n]=!0;continue}let{key:o,config:c}=i,d=c.type;if(d===Boolean||p(d,Boolean))g(r.flags,o,`true`,c);else if(t+1<e){g(r.flags,o,h.slice(t+1),c);break}else{let e=s&&!y(l)?a()??``:``;g(r.flags,o,e,c)}}}else{let{rawName:t,rawValue:n,hasSep:o}=v(h,i),c=u(t),f=!1;if(!c){let e=d(t);e&&(c=e,f=!0)}if(!c){let i=e(t);if(o)r.unknown[i]=n;else if(s&&!y(l)){let e=a();r.unknown[i]=e??!0}else r.unknown[i]=!0;return}let{key:p,config:m,path:b}=c;if(b){if(m.type===Object){r.flags[p]??={};let e=o?n:s&&!y(l)?a()??``:``;_(r.flags[p],b,e)}}else if(m.type===Boolean){let e=o?n!==`false`:!0;r.flags[p]=f?!e:e}else{let e=o?n:s&&!y(l)?a()??``:``;g(r.flags,p,e,m)}}});for(let[e,t]of o.entries())r.flags[e]===void 0&&(t.default===void 0?Array.isArray(t.type)?r.flags[e]=p(t.type,Boolean)?0:[]:t.type===Object?r.flags[e]={}:t.type===Boolean?r.flags[e]=!1:t.required&&r.missingRequiredFlags.push(e):r.flags[e]=n(t.default));return r}}}const x=(e,t={})=>b(t).parse(e);export{y as DOUBLE_DASH,r as InvalidSchemaError,i as KNOWN_FLAG,o as PARAMETER,a as UNKNOWN_FLAG,b as createParser,x as 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.1",
+  "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.1"
+    "@clerc/utils": "1.2.0"
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",