@minelang-ts/parser 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Maysara Elshewehy (https://github.com/maysara-elshewehy)
+
+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,45 @@
+<!-- ╔═══════════════════════════ BEG ════════════════════════════╗ -->
+
+<br>
+<div align="center">
+    <p>
+        <img src="./assets/img/logo.png" alt="logo" style="" height="60" />
+    </p>
+</div>
+
+<div align="center">
+    <img data="version" src="https://img.shields.io/badge/v-0.0.1-black"/>
+    <a href="https://github.com/minelang-ts"><img src="https://img.shields.io/badge/@-minelang--ts-black"/></a>
+    <img src="https://img.shields.io/badge/coverage-99.91%25-brightgreen" alt="Test Coverage" />
+</div>
+<br>
+
+<!-- ╚════════════════════════════════════════════════════════════╝ -->
+
+
+
+<!-- ╔═══════════════════════════ DOC ════════════════════════════╗ -->
+
+- ## Note 📝
+
+    > All repositories related to `minelang-ts`, **like this repository**, are temporary repositories created for the purpose of simulating the final form of the Mine language.
+    >
+    > This means that they will later be ignored or deleted entirely after the real version of Mine is created using Mine itself rather than TypeScript. Until that happens, I will not provide any guarantees for the use of these repositories, since I will not spend much time on them because, as I said, they are temporary.
+
+<!-- ╚════════════════════════════════════════════════════════════╝ -->
+
+
+
+<!-- ╔═══════════════════════════ END ════════════════════════════╗ -->
+
+<br>
+
+<div align="center"><img src="./assets/img/line.png" alt="logo" style="" width="50%" /></div>
+
+<br>
+
+<div align="center">
+    <a href="https://github.com/maysara-elshewehy"><img src="https://img.shields.io/badge/by-Maysara-black"/></a>
+</div>
+
+<!-- ╚════════════════════════════════════════════════════════════╝ -->

package/dist/index.cjs

@@ -0,0 +1,3 @@
+'use strict';var h=class s{constructor(e,t,r,n){this.span={start:-99,end:-99};this.status="unset";this.source=null;this.mode="unset";this.errors=[];this.status=e,this.source=t,this.mode=r,this.span=n;}static create(e,t,r,n){return new s(e,t,r,n)}static createAsToken(e,t,r){return s.create(e,{source_kind:"token-source",type:t?.type??"unset",text:t?.text??void 0,span:r},"token",r)}static createAsOptional(e,t,r){return s.create(e,{source_kind:"optional-source",result:t},"optional",r)}static createAsChoice(e,t,r,n){return s.create(e,{source_kind:"choice-source",atIndex:r,result:t},"choice",n)}static createAsRepeat(e,t,r,n=false){return s.create(e,{source_kind:"repeat-source",endsWithSep:n,result:t??[]},"repeat",r)}static createAsSequence(e,t,r){return s.create(e,{source_kind:"sequence-source",result:t??[]},"seq",r)}static createAsPratt(e,t,r){return s.create(e,{source_kind:"pratt-source",result:t},"pratt",r)}static createAsCustom(e,t,r,n){return s.create(e,{source_kind:"custom-source",name:t,data:r},"custom",n)}isPassed(){return this.status==="passed"}isFailed(){return this.status==="failed"}isUnset(){return this.status==="unset"}isToken(){return this.mode==="token"}isOptional(){return this.mode==="optional"}isChoice(){return this.mode==="choice"}isRepeat(){return this.mode==="repeat"}isSequence(){return this.mode==="seq"}isPratt(){return this.mode==="pratt"}isFullyPassed(){return !(!this.isPassed()||this.isOptional()&&!this.isOptionalPassed())}isOptionalPassed(){return this.isOptional()&&this.source.result!==null}isCustom(e){return this.mode!=="custom"?false:e?this.source.name===e:true}getTokenType(){return this.isToken()?this.source.type:void 0}getTokenSpan(){return this.isToken()?this.source.span:void 0}getOptionalResult(){return this.isOptionalPassed()?this.source.result:void 0}getChoiceIndex(){return this.isChoice()?this.source.atIndex:void 0}getChoiceResult(){return this.isChoice()?this.source.result:void 0}getRepeatCount(){return this.isRepeat()?this.source.result.length:void 0}getRepeatResult(){return this.isRepeat()?this.source.result:void 0}isRepeatEndsWithSep(){return this.isRepeat()?this.source.endsWithSep:void 0}getSequenceCount(){return this.isSequence()?this.source.result.length:void 0}getSequenceResult(){return this.isSequence()?this.source.result:void 0}getPrattResult(){return this.isPratt()?this.source.result:void 0}getCustomData(){return this.isCustom()?this.source.data:void 0}getCustomName(){return this.isCustom()?this.source.name:void 0}getTokenValue(){if(!this.isToken())return;let e=this.source.text;return e===void 0?null:e}getTokenData(){if(!this.isToken())return;let e=this.source;return {type:e.type,text:e.text,span:e.span}}clone(){let e=new s(this.status,this.source,this.mode,this.span);return e.errors=[...this.errors],e}hasErrors(){return this.errors.length>0}withError(e){return this.errors.push(e),this}};var p={LEXICAL_ERROR:"LEXICAL_ERROR",TOKEN_EXPECTED_EOF:"TOKEN_EXPECTED_EOF",TOKEN_MISMATCH:"TOKEN_MISMATCH",RULE_FAILED:"RULE_FAILED",BUILD_FUNCTION_FAILED:"BUILD_FUNCTION_FAILED",REPEAT_MIN_NOT_MET:"REPEAT_MIN_NOT_MET",SEQUENCE_FAILED:"SEQUENCE_FAILED",CUSTOM_ERROR:"CUSTOM_ERROR",CHOICE_ALL_FAILED:"CHOICE_ALL_FAILED",PRATT_NO_PREFIX:"PRATT_NO_PREFIX",FATAL_ERROR:"FATAL_ERROR",UNKNOWN_ERROR:"UNKNOWN_ERROR",RECOVERY_CUSTOM:"RECOVERY_CUSTOM"},E={};var d=h.create("failed",null,"unset",{start:-1,end:-1}),g=class{constructor(e,t){this.tokens=[];this.index=0;this.errors=[];this.ast=[];this.stats={tokensProcessed:0,rulesApplied:0,errorsRecovered:0,parseTimeMs:0};this._compiled=new Map;this._ruleIndex=new Map;this._laTable=new Map;this._memo=new Map;this._depth=0;this._silentDepth=0;this._rootStart=0;this._startTime=0;this._debugLevel="off";this._ignoredSet=new Set;this.lastHandledRule="unknown";this.lastVisitedIndex=0;this.ruleStack=[];this.rules=new Map(e.map(i=>[i.name,i])),this.settings=this._normalizeSettings(t),this._debugLevel=this.settings.debug,this._ignoredSet=new Set(this.settings.ignored);let r=0;for(let i of this.rules.keys())this._ruleIndex.set(i,r++);let n=this._validateGrammar();if(n.length)throw new Error(`Grammar validation failed:
+  ${n.join(`
+  `)}`);this._buildLookaheadSets();for(let[i,o]of this.rules)this._compiled.set(i,this._compilePattern(o.pattern,o));}parse(e){if(this._reset(e),this._startTime=Date.now(),!e.length)return {ast:[],errors:[]};let t=e.find(a=>a.type==="error");if(t)return {ast:[],errors:[this._mkError(p.LEXICAL_ERROR,`Unexpected token '${t.text}'`,t.span,0,0,"lexer")]};let r=this.rules.get(this.settings.startRule);if(!r)throw new Error(`Start rule '${this.settings.startRule}' not found`);let n=this._compiled.get(this.settings.startRule),i=this.settings.errorRecovery.maxErrors;this.settings.errorRecovery.mode==="resilient";try{for(this._skipIgnored();this.index<this.tokens.length&&!(i>0&&this.errors.length>=i);){let a=this.index;this._rootStart=a;let u=n(!1);if(u.isPassed()){let l=r.options?.build?this._safeBuild(r.options.build,u):u;l&&this.ast.push(l);}if(this.index===a)break;this._skipIgnored();}}catch(a){this._handleFatal(a);}return this.stats.parseTimeMs=Date.now()-this._startTime,{ast:this.ast,errors:this.errors,statistics:this.stats}}dispose(){this._memo.clear(),this._compiled.clear(),this.tokens=[],this.ast=[],this.errors=[];}isNextToken(e,t){let r=new Set([...this._ignoredSet,...t??[]]);for(let n=this.index;n<this.tokens.length;n++){let i=this.tokens[n];if(i.type===e)return  true;if(!r.has(i.type))break}return  false}isPrevToken(e,t=-1,r){let n=new Set([...this._ignoredSet,...r??[]]),i=t<0?this.index:t;for(let o=i-1;o>=0;o--){let a=this.tokens[o];if(a.type===e)return  true;if(!n.has(a.type))break}return  false}isPrevRule(e){return this.lastHandledRule===e}_buildLookaheadSets(){for(let t of this.rules.keys())this._laTable.set(t,new Set);let e=true;for(;e;){e=false;for(let[t,r]of this.rules){let n=this._laTable.get(t),i=this._firstOfPattern(r.pattern);for(let o of i)n.has(o)||(n.add(o),e=true);}}}_firstOfPattern(e){let t=new Set;switch(e.type){case "token":t.add(e.name);break;case "rule":{let r=this._laTable.get(e.name);if(r)for(let n of r)t.add(n);break}case "seq":for(let r of e.patterns??[]){for(let n of this._firstOfPattern(r))t.add(n);if(r.type!=="optional")break}break;case "choice":for(let r of e.patterns??[])for(let n of this._firstOfPattern(r))t.add(n);break;case "optional":case "repeat":case "conditional":case "not":case "lookahead":if(e.pattern)for(let r of this._firstOfPattern(e.pattern))t.add(r);break;case "action":break;case "pratt":if(e.table)for(let r of e.table.prefix.keys())t.add(r);break}return t}_compilePattern(e,t){switch(e.type){case "token":return this._compileToken(e,t);case "rule":return this._compileRule(e,t);case "seq":return this._compileSeq(e,t);case "choice":return this._compileChoice(e,t);case "repeat":return this._compileRepeat(e,t);case "optional":return this._compileOptional(e,t);case "pratt":return this._compilePratt(e,t);case "conditional":return this._compileConditional(e,t);case "action":return this._compileAction(e,t);case "not":return this._compileNot(e,t);case "lookahead":return this._compileLookahead(e,t);default:throw new Error(`Unknown pattern type: ${e.type}`)}}_compileToken(e,t){let r=e.name,n=e.value;return i=>{if(this.lastHandledRule=t?.name??r,this.lastVisitedIndex=this.index,this.index>=this.tokens.length){if(i)return d;throw this._mkError(p.TOKEN_EXPECTED_EOF,`Expected '${r}', got EOF`,this._span(),0,this.index,this.lastHandledRule)}let o=this.tokens[this.index];if(o.type===r){if(n!==void 0&&o.text!==n){if(i)return d;throw this._mkError(p.TOKEN_MISMATCH,`Expected '${r}' with value '${n}', got '${o.text}'`,o.span,0,this.index,this.lastHandledRule)}return this.index++,this.stats.tokensProcessed++,h.createAsToken("passed",o,o.span)}if(i)return d;let a=this._mkError(p.TOKEN_MISMATCH,`Expected '${r}', got '${o.type}'`,o.span,0,this.index,this.lastHandledRule);throw this._customErrorOr(t,a)}}_compileRule(e,t){let r=e.name;return n=>{let i=this.rules.get(r);if(!i)throw new Error(`Rule '${r}' not found`);let o=this._compiled.get(r);if(!o)throw new Error(`Rule '${r}' not compiled`);this.ruleStack.push(r),this.stats.rulesApplied++;let u=(this._ruleIndex.get(r)??0)<<16|this.index,l=this._getMemo(u);if(l)return this.ruleStack.pop(),this.index=l.endIndex,l.result??d;let c=this.index,f=this.errors.length,m=o(n);if(!m.isFullyPassed()){if(this.index=c,this.ruleStack.pop(),n)return d;let _=this._mkError(p.RULE_FAILED,`Rule '${r}' failed`,this._span(),0,this.lastVisitedIndex,r);throw this._customErrorOr(t,_)}let R=m;if(i.options?.build){let _=this._safeBuild(i.options.build,m);_&&(R=_);}return this._setMemo(u,R,this.index,f),this.ruleStack.pop(),R}}_compileSeq(e,t){let r=(e.patterns??[]).map(n=>this._compilePattern(n,t));return n=>{let i=this.index,o=[];for(let a=0;a<r.length;a++){this._skipIgnored(t?.options?.ignored);let u=r[a](n);if(!u.isPassed()){if(this.index=i,n)return d;let l=this._mkError(p.SEQUENCE_FAILED,`Sequence failed at element ${a+1}/${r.length}`,this._span(),a,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,l)}o.push(u);}return h.createAsSequence("passed",o,this._spanOf(o))}}_compileChoice(e,t){let r=e.patterns??[],n=r.map(o=>this._firstOfPattern(o)),i=r.map(o=>this._compilePattern(o,t));return o=>{let a=this.index;if(this._silentDepth++,this.index<this.tokens.length){let c=this.tokens[this.index].type,f=-1,m=false;for(let R=0;R<n.length;R++)if(n[R].has(c)){if(f>=0){m=true;break}f=R;}if(!m&&f>=0){this._silentDepth--;let R=i[f](o);if(R.isFullyPassed())return h.createAsChoice("passed",R,f,R.span);this.index=a,this._silentDepth++;}}let u=null;for(let c=0;c<i.length;c++){this.index=a;let f=i[c](true);if(f.isFullyPassed())return this._silentDepth--,h.createAsChoice("passed",f,c,f.span);let m=this.lastVisitedIndex-a;(!u||m>u.index-a)&&(u={index:this.lastVisitedIndex,err:null,altIdx:c});}if(this._silentDepth--,this.index=a,o)return d;let l=this._mkError(p.CHOICE_ALL_FAILED,`Expected one of: ${r.map(c=>this._patStr(c)).join(" | ")}`,this._span(),u?.altIdx??0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,l)}}_compileOptional(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);return this._silentDepth--,o.isFullyPassed()?h.createAsOptional("passed",o,o.span):(this.index=i,h.createAsOptional("passed",null,this._span()))}}_compileRepeat(e,t){let r=e.min??0,n=e.max??1/0,i=this._compilePattern(e.pattern,t),o=e.separator?this._compilePattern(e.separator,t):null;return a=>{let u=[],l=false,c=this.index;for(;u.length<n&&this.index<this.tokens.length;){let f=this.index;this._silentDepth++;let m=i(true);if(this._silentDepth--,!m.isFullyPassed()){this.index=f,l=false;break}if(u.push(m),l=false,this.index===f)break;if(o&&u.length<n&&this.index<this.tokens.length){let R=this.index;this._silentDepth++;let _=o(true);if(this._silentDepth--,!_.isFullyPassed()){this.index=R;break}l=true;}}if(u.length<r){if(this.index=c,a)return d;throw this._mkError(p.REPEAT_MIN_NOT_MET,`Expected at least ${r} occurrences, got ${u.length}`,this._span(),0,this.index,this.lastHandledRule)}return h.createAsRepeat("passed",u,this._spanOf(u),l)}}_compilePratt(e,t){let r=e.table;return n=>{if(this.index>=this.tokens.length){if(n)return d;throw this._mkError(p.PRATT_NO_PREFIX,"Expected an expression",this._span(),0,this.index,"pratt")}let i=this.tokens[this.index],o=r.prefix.get(i.type);if(!o){if(n)return d;throw this._mkError(p.PRATT_NO_PREFIX,`Unexpected token '${i.type}' in expression`,i.span,0,this.index,"pratt")}this.index++;let a=o.parse(this,i);if(!a.isPassed())return n?d:a;for(;this.index<this.tokens.length&&(this._skipIgnored(),!(this.index>=this.tokens.length));){let u=this.tokens[this.index],l=r.infix.get(u.type);if(!l||l.lbp<=0||(this.index++,a=l.parse(this,a,u),!a.isPassed()))break}return a}}_compileConditional(e,t){let r=this._compilePattern(e.pattern,t),n=e.predicate;return i=>{let o=this.index,a;if(i?(this._silentDepth++,a=r(true),this._silentDepth--):a=r(false),!a.isFullyPassed())return this.index=o,i?d:a;try{let u={parser:this,result:a,index:this.index,depth:this._depth,ruleStack:[...this.ruleStack]};if(n(u))return h.createAsCustom("passed","conditional",a,a.span);{if(this.index=o,i)return d;let c=this._mkError(p.RULE_FAILED,"Conditional predicate returned false",this._span(),0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,c)}}catch(u){if(this.index=o,i)return d;let l=u instanceof Error?u.message:String(u),c=this._mkError(p.RULE_FAILED,`Conditional predicate threw: ${l}`,this._span(),0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,c)}}}_compileAction(e,t){let r=e.fn;return n=>{try{r(this);}catch(i){let o=i instanceof Error?i.message:String(i);throw this._mkError(p.RULE_FAILED,`Action function threw: ${o}`,this._span(),0,this.index,"action")}return h.createAsCustom("passed","action",null,this._span())}}_compileNot(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);if(this._silentDepth--,o.isFullyPassed()){if(this.index=i,n)return d;let a=this._mkError(p.RULE_FAILED,"NOT pattern failed - inner pattern matched",this._span(),0,i,this.lastHandledRule);throw this._customErrorOr(t,a)}else return this.index=i,h.createAsCustom("passed","not",null,this._span())}}_compileLookahead(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);if(this._silentDepth--,this.index=i,o.isFullyPassed())return h.createAsCustom("passed","lookahead",null,this._span());{if(n)return d;let a=this._mkError(p.RULE_FAILED,"Lookahead pattern failed",this._span(),0,i,this.lastHandledRule);throw this._customErrorOr(t,a)}}}_getMemo(e){let t=this._memo.get(e);return t?t.errorCount!==this.errors.length?(this._memo.delete(e),null):t:null}_setMemo(e,t,r,n){this._memo.set(e,{result:t,endIndex:r,errorCount:this.errors.length});}_mkError(e,t,r,n,i,o,a){return {code:e,msg:t,span:r,failedAt:n,tokenIndex:i,startIndex:this._rootStart,prevRule:o,prevInnerRule:a??this.ruleStack.at(-1)??"unknown"}}_customErrorOr(e,t){if(!e?.options?.errors)return t;for(let r of e.options.errors){let n=false;if(typeof r.cond=="number")n=t.failedAt===r.cond;else if(typeof r.cond=="function")try{n=r.cond(this,{failedAt:t.failedAt,tokenIndex:t.tokenIndex});}catch{}if(n)return this._mkError(r.code??p.CUSTOM_ERROR,r.msg,t.span,t.failedAt,t.tokenIndex,t.prevRule,t.prevInnerRule)}return t}_addError(e){if(this._silentDepth>0)return;let t=this.settings.errorRecovery.maxErrors;t>0&&this.errors.length>=t||this.settings.errorRecovery.mode==="strict"&&this.errors.length>0||this.errors.some(r=>r.span?.start===e.span?.start)||this.errors.push(e);}_handleFatal(e){e&&typeof e=="object"&&"msg"in e&&"code"in e?this._addError(e):e instanceof Error&&this._addError(this._mkError(p.FATAL_ERROR,e.message,this._span(),0,this.index,this.lastHandledRule));}_safeBuild(e,t){try{return e(t,this)}catch(r){let n=this._mkError(p.BUILD_FUNCTION_FAILED,r instanceof Error?r.message:String(r),this._span(),0,this.index,this.lastHandledRule);return this._addError(n),t}}_span(){if(!this.tokens.length)return {start:0,end:0};if(this.index>=this.tokens.length){let e=this.tokens[this.tokens.length-1];return {start:e.span.end,end:e.span.end}}return this.tokens[this.index].span}_spanOf(e){return e.length?{start:e[0].span.start,end:e[e.length-1].span.end}:this._span()}_skipIgnored(e){let t=e?new Set([...this._ignoredSet,...e]):this._ignoredSet;for(;this.index<this.tokens.length&&t.has(this.tokens[this.index].type);)this.index++,this.stats.tokensProcessed++;}_patStr(e){switch(e.type){case "token":return e.name;case "rule":return e.name;case "seq":return `(${(e.patterns??[]).map(t=>this._patStr(t)).join(" ")})`;case "choice":return (e.patterns??[]).map(t=>this._patStr(t)).join(" | ");case "optional":return `${this._patStr(e.pattern)}?`;case "repeat":return `${this._patStr(e.pattern)}*`;case "conditional":return `${this._patStr(e.pattern)}.if(...)`;case "action":return "action(...)";case "not":return `!${this._patStr(e.pattern)}`;case "lookahead":return `lookahead(${this._patStr(e.pattern)})`;case "pratt":return "expr";default:return e.type}}_validateGrammar(){let e=[],t=new Set(this.rules.keys()),r=(n,i)=>{n.type==="rule"&&!t.has(n.name)&&e.push(`Rule '${i}' references undefined rule '${n.name}'`);for(let o of [n.pattern,...n.patterns??[]])o&&r(o,i);n.separator&&r(n.separator,i);};for(let[n,i]of this.rules)r(i.pattern,n);return this.rules.has(this.settings.startRule)||e.push(`Start rule '${this.settings.startRule}' is not defined`),e}_normalizeSettings(e){return {startRule:e?.startRule??"root",errorRecovery:{mode:e?.errorRecovery?.mode??"strict",maxErrors:e?.errorRecovery?.maxErrors??1},ignored:e?.ignored??["ws"],debug:e?.debug??"off",maxDepth:e?.maxDepth??1e3}}_reset(e){this.tokens=e,this.index=0,this.errors=[],this.ast=[],this._depth=0,this._silentDepth=0,this._rootStart=0,this.ruleStack=[],this._memo.clear(),this.stats={tokensProcessed:0,rulesApplied:0,errorsRecovered:0,parseTimeMs:0};}};function w(s){Object.assign(E,s);}function F(s,e,t){let r=new g(e,t);try{return r.parse(s)}finally{r.dispose();}}function L(s,e,t={}){return {name:s,pattern:e,options:{name:false,...t}}}function M(s,e){if(!s)throw new Error("token(): name must be a non-empty string");return {type:"token",name:s,value:e,silent:false}}function k(s){return {type:"optional",pattern:s,silent:false}}function D(...s){if(!s.length)throw new Error("choice(): at least one pattern required");return {type:"choice",patterns:s,silent:false}}function T(s,e=0,t=1/0,r){if(e<0)throw new Error("repeat(): min cannot be negative");if(t<e)throw new Error("repeat(): max cannot be less than min");return {type:"repeat",pattern:s,min:e,max:t,separator:r,silent:false}}function H(s,e){return T(s,1,1/0,e)}function x(s,e){return T(s,0,1/0,e)}function N(s,e){return O(T(s,0,1,e))}function y(...s){if(!s.length)throw new Error("seq(): at least one pattern required");return {type:"seq",patterns:s,silent:false}}function U(s,e){if(!s)throw new Error("rule(): name must be a non-empty string");return {type:"rule",name:s,params:e,silent:false}}function O(s){return {...s,silent:true}}function $(s){return {...s,silent:false}}function q(s){return {type:"pratt",table:s,silent:false}}function S(s,e){return {type:"conditional",pattern:s,predicate:e,silent:false}}function V(s,e){return S(s,e)}function B(s,e){return S(s,e)}function K(s){return {type:"action",fn:s,silent:false}}function X(s){return {type:"not",pattern:s,silent:false}}function I(s){return {type:"lookahead",pattern:s,silent:false}}function j(s){return I(s)}function W(s){return {prefix:new Map(Object.entries(s.prefix??{})),infix:new Map(Object.entries(s.infix??{}))}}function z(s,e,t){let{min:r=0,trailingOk:n=false}=t??{},i;return r===0?n?i=k(y(T(s,1,1/0),x(y(e,s)),k(e))):i=k(y(T(s,1,1/0),x(y(e,s)))):r===1?n?i=y(T(s,1,1/0),x(y(e,s)),k(e)):i=y(T(s,1,1/0),x(y(e,s))):n?i=y(T(s,r,1/0),x(y(e,s)),k(e)):i=y(T(s,r,1/0),x(y(e,s))),i}function G(s,e,t){return y(e,s,t)}function Q(s,e,t){return y(s,e,t)}function Y(s,e,t){return {cond:s,msg:e,code:t??p.RECOVERY_CUSTOM}}var J={skipUntil(s){return {type:"skipUntil",tokens:Array.isArray(s)?s:[s]}}};exports.ERRORS=p;exports.Parser=g;exports.Result=h;exports.action=K;exports.between=Q;exports.buildPrattTable=W;exports.choice=D;exports.conditional=S;exports.createRule=L;exports.delimited=z;exports.error=Y;exports.errorRecoveryStrategies=J;exports.globalTokenMap=E;exports.ifCondition=B;exports.lookahead=I;exports.loud=$;exports.not=X;exports.oneOrMore=H;exports.optional=k;exports.parse=F;exports.peek=j;exports.pratt=q;exports.registerTokenMap=w;exports.repeat=T;exports.rule=U;exports.seq=y;exports.silent=O;exports.surrounded=G;exports.token=M;exports.when=V;exports.zeroOrMore=x;exports.zeroOrOne=N;

package/dist/index.d.cts

@@ -0,0 +1,500 @@
+import { Span, Token } from '@minelang-ts/lexer';
+export { Span, Token } from '@minelang-ts/lexer';
+
+type ResultStatus = 'unset' | 'failed' | 'passed';
+type ResultMode = 'unset' | 'token' | 'optional' | 'choice' | 'repeat' | 'seq' | 'pratt' | 'custom';
+interface TokenSource {
+    source_kind: 'token-source';
+    type: string;
+    text?: string;
+    span?: Span;
+}
+interface OptionalSource {
+    source_kind: 'optional-source';
+    result: Result | null;
+}
+interface ChoiceSource {
+    source_kind: 'choice-source';
+    atIndex: number;
+    result: Result | null;
+}
+interface RepeatSource {
+    source_kind: 'repeat-source';
+    endsWithSep: boolean;
+    result: Result[];
+}
+interface SequenceSource {
+    source_kind: 'sequence-source';
+    result: Result[];
+}
+interface PrattSource {
+    source_kind: 'pratt-source';
+    result: Result[];
+}
+interface CustomSource {
+    source_kind: 'custom-source';
+    name: string;
+    data: unknown;
+}
+type ResultSource = TokenSource | OptionalSource | ChoiceSource | RepeatSource | SequenceSource | PrattSource | CustomSource | null;
+declare class Result {
+    span: Span;
+    status: ResultStatus;
+    source: ResultSource;
+    mode: ResultMode;
+    errors: ParseError[];
+    constructor(status: ResultStatus, source: ResultSource | null, mode: ResultMode, span: Span);
+    static create(status: ResultStatus, source: ResultSource | null, mode: ResultMode, span: Span): Result;
+    static createAsToken(status: ResultStatus, source: Token | null, span: Span): Result;
+    static createAsOptional(status: ResultStatus, source: Result | null, span: Span): Result;
+    static createAsChoice(status: ResultStatus, source: Result | null, index: number, span: Span): Result;
+    static createAsRepeat(status: ResultStatus, source: Result[] | null, span: Span, endsWithSep?: boolean): Result;
+    static createAsSequence(status: ResultStatus, source: Result[] | null, span: Span): Result;
+    static createAsPratt(status: ResultStatus, source: Result[], span: Span): Result;
+    static createAsCustom(status: ResultStatus, name: string, data: unknown, span: Span): Result;
+    isPassed(): boolean;
+    isFailed(): boolean;
+    isUnset(): boolean;
+    isToken(): boolean;
+    isOptional(): boolean;
+    isChoice(): boolean;
+    isRepeat(): boolean;
+    isSequence(): boolean;
+    isPratt(): boolean;
+    isFullyPassed(): boolean;
+    isOptionalPassed(): boolean;
+    isCustom(tag?: string): boolean;
+    getTokenType(): string | undefined;
+    getTokenSpan(): Span | undefined;
+    getOptionalResult(): Result | null | undefined;
+    getChoiceIndex(): number | undefined;
+    getChoiceResult(): Result | null | undefined;
+    getRepeatCount(): number | undefined;
+    getRepeatResult(): Result[] | undefined;
+    isRepeatEndsWithSep(): boolean | undefined;
+    getSequenceCount(): number | undefined;
+    getSequenceResult(): Result[] | undefined;
+    getPrattResult(): Result[] | undefined;
+    getCustomData(): unknown | undefined;
+    getCustomName(): string | undefined;
+    getTokenValue(): string | null | undefined;
+    getTokenData(): Token | undefined;
+    clone(): Result;
+    hasErrors(): boolean;
+    withError(e: ParseError): Result;
+}
+
+declare class Parser {
+    rules: Map<string, Rule>;
+    settings: ParserSettings;
+    tokens: Token[];
+    index: number;
+    errors: ParseError[];
+    ast: Result[];
+    stats: ParseStatistics;
+    private _compiled;
+    private _ruleIndex;
+    private _laTable;
+    private _memo;
+    private _depth;
+    private _silentDepth;
+    private _rootStart;
+    private _startTime;
+    private _debugLevel;
+    private _ignoredSet;
+    lastHandledRule: string;
+    lastVisitedIndex: number;
+    ruleStack: string[];
+    constructor(rules: Rule[], settings?: ParserSettings);
+    parse(tokens: Token[]): ParseResult;
+    dispose(): void;
+    isNextToken(kind: string, extra?: string[]): boolean;
+    isPrevToken(kind: string, from?: number, extra?: string[]): boolean;
+    isPrevRule(name: string): boolean;
+    private _buildLookaheadSets;
+    private _firstOfPattern;
+    private _compilePattern;
+    private _compileToken;
+    private _compileRule;
+    private _compileSeq;
+    private _compileChoice;
+    private _compileOptional;
+    private _compileRepeat;
+    private _compilePratt;
+    private _compileConditional;
+    private _compileAction;
+    private _compileNot;
+    private _compileLookahead;
+    private _getMemo;
+    private _setMemo;
+    private _mkError;
+    private _customErrorOr;
+    private _addError;
+    private _handleFatal;
+    private _safeBuild;
+    private _span;
+    private _spanOf;
+    private _skipIgnored;
+    private _patStr;
+    private _validateGrammar;
+    private _normalizeSettings;
+    private _reset;
+}
+
+interface MiniToken {
+    kind: string;
+    value: string | null;
+}
+/**
+* Conditional context passed to predicate function.
+* Provides access to parser state for conditional decision-making.
+*/
+interface ConditionalContext {
+    parser: Parser;
+    result: Result | null;
+    index: number;
+    depth: number;
+    ruleStack: string[];
+}
+/**
+* Predicate function for conditional pattern execution.
+* Return true to continue with the pattern, false to fail.
+*/
+type ConditionalPredicate = (context: ConditionalContext) => boolean;
+/**
+* Action function executed for side effects during parsing.
+* Called during pattern execution, can access and modify parser state.
+*/
+type ActionFunction = (parser: Parser) => void;
+interface Pattern {
+    type: 'token' | 'rule' | 'repeat' | 'choice' | 'seq' | 'optional' | 'pratt' | 'conditional' | 'action' | 'not' | 'lookahead';
+    silent: boolean;
+    value?: string;
+    name?: string;
+    min?: number;
+    max?: number;
+    patterns?: Pattern[];
+    separator?: Pattern;
+    pattern?: Pattern;
+    table?: PrattTable;
+    predicate?: ConditionalPredicate;
+    fn?: ActionFunction;
+    params?: Record<string, any>;
+}
+interface PrefixHandler {
+    /** How tightly this prefix binds its right operand. */
+    bp: number;
+    parse: (parser: Parser, token: Token) => Result;
+}
+interface InfixHandler {
+    /** Precedence level - left binding power. */
+    lbp: number;
+    /** Right binding power (lbp - 1 for right-associative). Defaults to lbp. */
+    rbp?: number;
+    parse: (parser: Parser, left: Result, token: Token) => Result;
+}
+interface PrattTable {
+    prefix: Map<string, PrefixHandler>;
+    infix: Map<string, InfixHandler>;
+}
+interface ErrorHandler {
+    cond: number | ((parser: Parser, opt: {
+        failedAt: number;
+        tokenIndex: number;
+        force?: boolean;
+        prevRule?: string;
+        prevInnerRule?: string;
+    }) => boolean);
+    msg: string;
+    code?: string;
+}
+interface RecoveryStrategy {
+    type: 'skipUntil' | 'synchronize';
+    tokens?: string[];
+    token?: string;
+}
+type BuildFunction = (matches: Result, parser: Parser) => Result;
+interface Rule {
+    name: string;
+    pattern: Pattern;
+    options?: {
+        build?: BuildFunction;
+        errors?: ErrorHandler[];
+        recovery?: RecoveryStrategy;
+        ignored?: string[];
+        silent?: boolean;
+    };
+}
+type Rules = Rule[];
+interface ParseStatistics {
+    tokensProcessed: number;
+    rulesApplied: number;
+    errorsRecovered: number;
+    parseTimeMs: number;
+}
+interface ParseError {
+    msg: string;
+    code: string;
+    span: Span;
+    failedAt: number;
+    tokenIndex: number;
+    startIndex: number;
+    prevRule: string;
+    prevInnerRule?: string;
+}
+interface ParseResult {
+    ast: Result[];
+    errors: ParseError[];
+    statistics?: ParseStatistics;
+}
+type DebugLevel = 'off' | 'errors' | 'rules' | 'patterns' | 'tokens' | 'verbose';
+interface ParserSettings {
+    startRule: string;
+    errorRecovery?: {
+        mode?: 'strict' | 'resilient';
+        maxErrors?: number;
+    };
+    ignored?: string[];
+    debug?: DebugLevel;
+    maxDepth?: number;
+}
+declare const ERRORS: {
+    readonly LEXICAL_ERROR: "LEXICAL_ERROR";
+    readonly TOKEN_EXPECTED_EOF: "TOKEN_EXPECTED_EOF";
+    readonly TOKEN_MISMATCH: "TOKEN_MISMATCH";
+    readonly RULE_FAILED: "RULE_FAILED";
+    readonly BUILD_FUNCTION_FAILED: "BUILD_FUNCTION_FAILED";
+    readonly REPEAT_MIN_NOT_MET: "REPEAT_MIN_NOT_MET";
+    readonly SEQUENCE_FAILED: "SEQUENCE_FAILED";
+    readonly CUSTOM_ERROR: "CUSTOM_ERROR";
+    readonly CHOICE_ALL_FAILED: "CHOICE_ALL_FAILED";
+    readonly PRATT_NO_PREFIX: "PRATT_NO_PREFIX";
+    readonly FATAL_ERROR: "FATAL_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly RECOVERY_CUSTOM: "RECOVERY_CUSTOM";
+};
+/**
+* Global registry mapping string literals to token kinds.
+* Example: {'let': 'LET', 'if': 'IF', '{': 'LBRACE'}
+* When registered, string patterns like seq('let', 'IDENT') will work.
+*/
+declare const globalTokenMap: Record<string, string>;
+
+/**
+* Register a global token map for string shorthand patterns.
+* After registration, you can use 'let', 'if', etc. directly in patterns.
+*
+* @example
+* registerTokenMap({
+    *   'let': 'LET',
+    *   'if': 'IF',
+    *   '{': 'LBRACE',
+    *   '}': 'RBRACE',
+    *   '=': 'EQ',
+    * });
+*
+* // Now you can write:
+* seq('let', 'IDENT', '=', rule('expr'))
+*/
+declare function registerTokenMap(map: Record<string, string>): void;
+declare function parse(tokens: Token[], rules: Rules, settings?: ParserSettings): ParseResult;
+declare function createRule(name: string, pattern: Pattern, options?: Rule['options']): Rule;
+declare function token(name: string, value?: string): Pattern;
+declare function optional(pattern: Pattern): Pattern;
+declare function choice(...patterns: Pattern[]): Pattern;
+declare function repeat(pattern: Pattern, min?: number, max?: number, separator?: Pattern): Pattern;
+declare function oneOrMore(pattern: Pattern, separator?: Pattern): Pattern;
+declare function zeroOrMore(pattern: Pattern, separator?: Pattern): Pattern;
+declare function zeroOrOne(pattern: Pattern, separator?: Pattern): Pattern;
+declare function seq(...patterns: Pattern[]): Pattern;
+declare function rule(name: string): Pattern;
+declare function rule(name: string, params: Record<string, unknown>): Pattern;
+declare function silent<T extends Pattern>(pattern: T): T;
+declare function loud<T extends Pattern>(pattern: T): T;
+/**
+* Build a Pratt expression parser inline in a rule.
+*
+* @example
+* const expr = pratt({
+    *     prefix: new Map([
+        *         ['NUM',   { bp: 0, parse: (_, tok) => Result.createAsToken('passed', tok, tok.span) }],
+        *             ['MINUS', { bp: 70, parse: (p, tok) => {
+                    *                 const right = p.parse(...)   // handled via sub-rule
+                    *                 return Result.createAsPratt('passed', [right], right.span)
+                    *             }}],
+        *         ]),
+    *     infix: new Map([
+        *         ['PLUS',  { lbp: 50, parse: (_, left, tok) => ... }],
+        *         ['STAR',  { lbp: 60, parse: (_, left, tok) => ... }],
+        *         ['STAR2', { lbp: 70, rbp: 69, parse: ... }], // right-associative
+        *    ]),
+    * });
+*/
+declare function pratt(table: PrattTable): Pattern;
+/**
+* Adds conditional execution to a pattern.
+* The predicate receives parser context and decides whether to continue.
+*
+* @param pattern     - The pattern to conditionally execute
+* @param predicate   - Function that receives parser context and returns true to continue
+* @returns Conditional pattern that evaluates predicate after inner pattern matches
+*
+* @example
+* // Only match if we're not too deep in the parse tree
+* pattern.if(ctx => ctx.depth < 10)
+*
+* // Only match if next token after match is LBRACE
+* token('IF').if(ctx => ctx.parser.isNextToken('LBRACE'))
+*
+* // Inspect full parser state
+* rule('expr').if(ctx => {
+    *   return ctx.parser.errors.length === 0 && ctx.ruleStack.length < 5
+    * })
+*/
+declare function conditional(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Shorthand for conditional() - more natural syntax
+* @see conditional
+*/
+declare function when(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Method-chaining style: pattern.if(predicate)
+* Extends Pattern type with .if() method for fluent API
+*
+* @note This is implemented as a utility function, not directly on Pattern
+*       Use: conditional(pattern, predicate) or when(pattern, predicate)
+*/
+declare function ifCondition(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Action pattern - executes a side effect during parsing.
+* Useful for scope management, state tracking, and stateful parsing.
+*
+* @param fn - Function called during execution with access to parser state
+* @returns Action pattern that always succeeds
+*
+* @example
+* // Track parse state
+* seq(
+    *   token('LBRACE'),
+    *   action(p => p.symbolTable?.pushScope()),
+    *   zeroOrMore(rule('stmt')),
+    *   token('RBRACE'),
+    *   action(p => p.symbolTable?.popScope())
+    * )
+*
+* // Count custom metric
+* action(p => p.stats.customCounter = (p.stats.customCounter ?? 0) + 1)
+*/
+declare function action(fn: ActionFunction): Pattern;
+/**
+* NOT pattern - succeeds if the inner pattern FAILS.
+* Useful for negative lookahead and validation checks.
+*
+* @param pattern - The pattern to negate
+* @returns NOT pattern
+*
+* @example
+* // Match any character except EOF
+* not(token('EOF'))
+*
+* // In a choice: match IDENT that is not a keyword
+* choice(
+    *   not(choice(token('IF'), token('WHILE'), token('FOR'))),
+    *   token('IDENT')
+    * )
+*/
+declare function not(pattern: Pattern): Pattern;
+/**
+* Lookahead pattern - checks if inner pattern would match WITHOUT consuming tokens.
+* Common alias: peek()
+*
+* @param pattern - The pattern to lookahead check
+* @returns Lookahead pattern
+*
+* @example
+* // Only match expr if followed by RPAREN
+* seq(
+    *   lookahead(seq(rule('expr'), token('RPAREN'))),
+    *   rule('expr')
+    * )
+*
+* // Safe token inspection
+* seq(
+    *   token('IDENT'),
+    *   when(lookahead(token('LPAREN')), ctx => ctx.parser.isNextToken('LPAREN'))
+    * )
+*/
+declare function lookahead(pattern: Pattern): Pattern;
+/**
+* Alias for lookahead() - more concise syntax.
+* @see lookahead
+*/
+declare function peek(pattern: Pattern): Pattern;
+/** Convenience: build a PrattTable from plain objects. */
+declare function buildPrattTable(spec: {
+    prefix?: Record<string, PrefixHandler>;
+    infix?: Record<string, InfixHandler>;
+}): PrattTable;
+/**
+* Delimited list pattern - matches items separated by a delimiter.
+* Commonly used for comma-separated values, arguments, etc.
+*
+* @param item - The pattern for each list item
+* @param sep - The separator pattern (usually token(','))
+* @param options - {min?: number, trailingOk?: boolean}
+* @returns Composed pattern for delimited list
+*
+* @example
+* // Comma-separated identifiers (0+)
+* delimited(token('IDENT'), token('COMMA'))
+*
+* // Function arguments (1+ with optional trailing)
+* delimited(rule('expr'), token('COMMA'), {min: 1, trailingOk: true})
+*
+* // Array elements
+* between('[', delimited(rule('expr'), token('COMMA')), ']')
+*/
+declare function delimited(item: Pattern, sep: Pattern, options?: {
+    min?: number;
+    trailingOk?: boolean;
+}): Pattern;
+/**
+* Surrounded pattern - matches content between open and close delimiters.
+* Alias for between(open, content, close).
+*
+* @param content - The pattern for interior content
+* @param open - Opening delimiter
+* @param close - Closing delimiter
+* @returns Composed pattern: open, content, close
+*
+* @example
+* // Parenthesized expression
+* surrounded(rule('expr'), token('LPAREN'), token('RPAREN'))
+*
+* // Generic syntax with string shorthand
+* surrounded(rule('typeList'), '(', ')')
+*/
+declare function surrounded(content: Pattern, open: Pattern, close: Pattern): Pattern;
+/**
+* Between pattern - matches content between left and right patterns.
+* Alias for surrounded but with more explicit name.
+*
+* @param left - Left sentinel pattern
+* @param content - Interior content pattern
+* @param right - Right sentinel pattern
+* @returns Composed pattern: left, content, right
+*
+* @example
+* // Array literal
+* between(token('LBRACK'), delimited(rule('expr'), token('COMMA')), token('RBRACK'))
+*
+* // Function call
+* between('(', delimited(rule('param'), ','), ')')
+*/
+declare function between(left: Pattern, content: Pattern, right: Pattern): Pattern;
+declare function error(cond: ErrorHandler['cond'], msg: string, code?: string): ErrorHandler;
+declare const errorRecoveryStrategies: {
+    skipUntil(tokens: string | string[]): RecoveryStrategy;
+};
+
+export { type BuildFunction, type ConditionalContext, type ConditionalPredicate, type DebugLevel, ERRORS, type ErrorHandler, type InfixHandler, type MiniToken, type ParseError, type ParseResult, Parser, type ParserSettings, type Pattern, type PrattTable, type PrefixHandler, type RecoveryStrategy, Result, type Rule, type Rules, action, between, buildPrattTable, choice, conditional, createRule, delimited, error, errorRecoveryStrategies, globalTokenMap, ifCondition, lookahead, loud, not, oneOrMore, optional, parse, peek, pratt, registerTokenMap, repeat, rule, seq, silent, surrounded, token, when, zeroOrMore, zeroOrOne };

package/dist/index.d.ts

@@ -0,0 +1,500 @@
+import { Span, Token } from '@minelang-ts/lexer';
+export { Span, Token } from '@minelang-ts/lexer';
+
+type ResultStatus = 'unset' | 'failed' | 'passed';
+type ResultMode = 'unset' | 'token' | 'optional' | 'choice' | 'repeat' | 'seq' | 'pratt' | 'custom';
+interface TokenSource {
+    source_kind: 'token-source';
+    type: string;
+    text?: string;
+    span?: Span;
+}
+interface OptionalSource {
+    source_kind: 'optional-source';
+    result: Result | null;
+}
+interface ChoiceSource {
+    source_kind: 'choice-source';
+    atIndex: number;
+    result: Result | null;
+}
+interface RepeatSource {
+    source_kind: 'repeat-source';
+    endsWithSep: boolean;
+    result: Result[];
+}
+interface SequenceSource {
+    source_kind: 'sequence-source';
+    result: Result[];
+}
+interface PrattSource {
+    source_kind: 'pratt-source';
+    result: Result[];
+}
+interface CustomSource {
+    source_kind: 'custom-source';
+    name: string;
+    data: unknown;
+}
+type ResultSource = TokenSource | OptionalSource | ChoiceSource | RepeatSource | SequenceSource | PrattSource | CustomSource | null;
+declare class Result {
+    span: Span;
+    status: ResultStatus;
+    source: ResultSource;
+    mode: ResultMode;
+    errors: ParseError[];
+    constructor(status: ResultStatus, source: ResultSource | null, mode: ResultMode, span: Span);
+    static create(status: ResultStatus, source: ResultSource | null, mode: ResultMode, span: Span): Result;
+    static createAsToken(status: ResultStatus, source: Token | null, span: Span): Result;
+    static createAsOptional(status: ResultStatus, source: Result | null, span: Span): Result;
+    static createAsChoice(status: ResultStatus, source: Result | null, index: number, span: Span): Result;
+    static createAsRepeat(status: ResultStatus, source: Result[] | null, span: Span, endsWithSep?: boolean): Result;
+    static createAsSequence(status: ResultStatus, source: Result[] | null, span: Span): Result;
+    static createAsPratt(status: ResultStatus, source: Result[], span: Span): Result;
+    static createAsCustom(status: ResultStatus, name: string, data: unknown, span: Span): Result;
+    isPassed(): boolean;
+    isFailed(): boolean;
+    isUnset(): boolean;
+    isToken(): boolean;
+    isOptional(): boolean;
+    isChoice(): boolean;
+    isRepeat(): boolean;
+    isSequence(): boolean;
+    isPratt(): boolean;
+    isFullyPassed(): boolean;
+    isOptionalPassed(): boolean;
+    isCustom(tag?: string): boolean;
+    getTokenType(): string | undefined;
+    getTokenSpan(): Span | undefined;
+    getOptionalResult(): Result | null | undefined;
+    getChoiceIndex(): number | undefined;
+    getChoiceResult(): Result | null | undefined;
+    getRepeatCount(): number | undefined;
+    getRepeatResult(): Result[] | undefined;
+    isRepeatEndsWithSep(): boolean | undefined;
+    getSequenceCount(): number | undefined;
+    getSequenceResult(): Result[] | undefined;
+    getPrattResult(): Result[] | undefined;
+    getCustomData(): unknown | undefined;
+    getCustomName(): string | undefined;
+    getTokenValue(): string | null | undefined;
+    getTokenData(): Token | undefined;
+    clone(): Result;
+    hasErrors(): boolean;
+    withError(e: ParseError): Result;
+}
+
+declare class Parser {
+    rules: Map<string, Rule>;
+    settings: ParserSettings;
+    tokens: Token[];
+    index: number;
+    errors: ParseError[];
+    ast: Result[];
+    stats: ParseStatistics;
+    private _compiled;
+    private _ruleIndex;
+    private _laTable;
+    private _memo;
+    private _depth;
+    private _silentDepth;
+    private _rootStart;
+    private _startTime;
+    private _debugLevel;
+    private _ignoredSet;
+    lastHandledRule: string;
+    lastVisitedIndex: number;
+    ruleStack: string[];
+    constructor(rules: Rule[], settings?: ParserSettings);
+    parse(tokens: Token[]): ParseResult;
+    dispose(): void;
+    isNextToken(kind: string, extra?: string[]): boolean;
+    isPrevToken(kind: string, from?: number, extra?: string[]): boolean;
+    isPrevRule(name: string): boolean;
+    private _buildLookaheadSets;
+    private _firstOfPattern;
+    private _compilePattern;
+    private _compileToken;
+    private _compileRule;
+    private _compileSeq;
+    private _compileChoice;
+    private _compileOptional;
+    private _compileRepeat;
+    private _compilePratt;
+    private _compileConditional;
+    private _compileAction;
+    private _compileNot;
+    private _compileLookahead;
+    private _getMemo;
+    private _setMemo;
+    private _mkError;
+    private _customErrorOr;
+    private _addError;
+    private _handleFatal;
+    private _safeBuild;
+    private _span;
+    private _spanOf;
+    private _skipIgnored;
+    private _patStr;
+    private _validateGrammar;
+    private _normalizeSettings;
+    private _reset;
+}
+
+interface MiniToken {
+    kind: string;
+    value: string | null;
+}
+/**
+* Conditional context passed to predicate function.
+* Provides access to parser state for conditional decision-making.
+*/
+interface ConditionalContext {
+    parser: Parser;
+    result: Result | null;
+    index: number;
+    depth: number;
+    ruleStack: string[];
+}
+/**
+* Predicate function for conditional pattern execution.
+* Return true to continue with the pattern, false to fail.
+*/
+type ConditionalPredicate = (context: ConditionalContext) => boolean;
+/**
+* Action function executed for side effects during parsing.
+* Called during pattern execution, can access and modify parser state.
+*/
+type ActionFunction = (parser: Parser) => void;
+interface Pattern {
+    type: 'token' | 'rule' | 'repeat' | 'choice' | 'seq' | 'optional' | 'pratt' | 'conditional' | 'action' | 'not' | 'lookahead';
+    silent: boolean;
+    value?: string;
+    name?: string;
+    min?: number;
+    max?: number;
+    patterns?: Pattern[];
+    separator?: Pattern;
+    pattern?: Pattern;
+    table?: PrattTable;
+    predicate?: ConditionalPredicate;
+    fn?: ActionFunction;
+    params?: Record<string, any>;
+}
+interface PrefixHandler {
+    /** How tightly this prefix binds its right operand. */
+    bp: number;
+    parse: (parser: Parser, token: Token) => Result;
+}
+interface InfixHandler {
+    /** Precedence level - left binding power. */
+    lbp: number;
+    /** Right binding power (lbp - 1 for right-associative). Defaults to lbp. */
+    rbp?: number;
+    parse: (parser: Parser, left: Result, token: Token) => Result;
+}
+interface PrattTable {
+    prefix: Map<string, PrefixHandler>;
+    infix: Map<string, InfixHandler>;
+}
+interface ErrorHandler {
+    cond: number | ((parser: Parser, opt: {
+        failedAt: number;
+        tokenIndex: number;
+        force?: boolean;
+        prevRule?: string;
+        prevInnerRule?: string;
+    }) => boolean);
+    msg: string;
+    code?: string;
+}
+interface RecoveryStrategy {
+    type: 'skipUntil' | 'synchronize';
+    tokens?: string[];
+    token?: string;
+}
+type BuildFunction = (matches: Result, parser: Parser) => Result;
+interface Rule {
+    name: string;
+    pattern: Pattern;
+    options?: {
+        build?: BuildFunction;
+        errors?: ErrorHandler[];
+        recovery?: RecoveryStrategy;
+        ignored?: string[];
+        silent?: boolean;
+    };
+}
+type Rules = Rule[];
+interface ParseStatistics {
+    tokensProcessed: number;
+    rulesApplied: number;
+    errorsRecovered: number;
+    parseTimeMs: number;
+}
+interface ParseError {
+    msg: string;
+    code: string;
+    span: Span;
+    failedAt: number;
+    tokenIndex: number;
+    startIndex: number;
+    prevRule: string;
+    prevInnerRule?: string;
+}
+interface ParseResult {
+    ast: Result[];
+    errors: ParseError[];
+    statistics?: ParseStatistics;
+}
+type DebugLevel = 'off' | 'errors' | 'rules' | 'patterns' | 'tokens' | 'verbose';
+interface ParserSettings {
+    startRule: string;
+    errorRecovery?: {
+        mode?: 'strict' | 'resilient';
+        maxErrors?: number;
+    };
+    ignored?: string[];
+    debug?: DebugLevel;
+    maxDepth?: number;
+}
+declare const ERRORS: {
+    readonly LEXICAL_ERROR: "LEXICAL_ERROR";
+    readonly TOKEN_EXPECTED_EOF: "TOKEN_EXPECTED_EOF";
+    readonly TOKEN_MISMATCH: "TOKEN_MISMATCH";
+    readonly RULE_FAILED: "RULE_FAILED";
+    readonly BUILD_FUNCTION_FAILED: "BUILD_FUNCTION_FAILED";
+    readonly REPEAT_MIN_NOT_MET: "REPEAT_MIN_NOT_MET";
+    readonly SEQUENCE_FAILED: "SEQUENCE_FAILED";
+    readonly CUSTOM_ERROR: "CUSTOM_ERROR";
+    readonly CHOICE_ALL_FAILED: "CHOICE_ALL_FAILED";
+    readonly PRATT_NO_PREFIX: "PRATT_NO_PREFIX";
+    readonly FATAL_ERROR: "FATAL_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly RECOVERY_CUSTOM: "RECOVERY_CUSTOM";
+};
+/**
+* Global registry mapping string literals to token kinds.
+* Example: {'let': 'LET', 'if': 'IF', '{': 'LBRACE'}
+* When registered, string patterns like seq('let', 'IDENT') will work.
+*/
+declare const globalTokenMap: Record<string, string>;
+
+/**
+* Register a global token map for string shorthand patterns.
+* After registration, you can use 'let', 'if', etc. directly in patterns.
+*
+* @example
+* registerTokenMap({
+    *   'let': 'LET',
+    *   'if': 'IF',
+    *   '{': 'LBRACE',
+    *   '}': 'RBRACE',
+    *   '=': 'EQ',
+    * });
+*
+* // Now you can write:
+* seq('let', 'IDENT', '=', rule('expr'))
+*/
+declare function registerTokenMap(map: Record<string, string>): void;
+declare function parse(tokens: Token[], rules: Rules, settings?: ParserSettings): ParseResult;
+declare function createRule(name: string, pattern: Pattern, options?: Rule['options']): Rule;
+declare function token(name: string, value?: string): Pattern;
+declare function optional(pattern: Pattern): Pattern;
+declare function choice(...patterns: Pattern[]): Pattern;
+declare function repeat(pattern: Pattern, min?: number, max?: number, separator?: Pattern): Pattern;
+declare function oneOrMore(pattern: Pattern, separator?: Pattern): Pattern;
+declare function zeroOrMore(pattern: Pattern, separator?: Pattern): Pattern;
+declare function zeroOrOne(pattern: Pattern, separator?: Pattern): Pattern;
+declare function seq(...patterns: Pattern[]): Pattern;
+declare function rule(name: string): Pattern;
+declare function rule(name: string, params: Record<string, unknown>): Pattern;
+declare function silent<T extends Pattern>(pattern: T): T;
+declare function loud<T extends Pattern>(pattern: T): T;
+/**
+* Build a Pratt expression parser inline in a rule.
+*
+* @example
+* const expr = pratt({
+    *     prefix: new Map([
+        *         ['NUM',   { bp: 0, parse: (_, tok) => Result.createAsToken('passed', tok, tok.span) }],
+        *             ['MINUS', { bp: 70, parse: (p, tok) => {
+                    *                 const right = p.parse(...)   // handled via sub-rule
+                    *                 return Result.createAsPratt('passed', [right], right.span)
+                    *             }}],
+        *         ]),
+    *     infix: new Map([
+        *         ['PLUS',  { lbp: 50, parse: (_, left, tok) => ... }],
+        *         ['STAR',  { lbp: 60, parse: (_, left, tok) => ... }],
+        *         ['STAR2', { lbp: 70, rbp: 69, parse: ... }], // right-associative
+        *    ]),
+    * });
+*/
+declare function pratt(table: PrattTable): Pattern;
+/**
+* Adds conditional execution to a pattern.
+* The predicate receives parser context and decides whether to continue.
+*
+* @param pattern     - The pattern to conditionally execute
+* @param predicate   - Function that receives parser context and returns true to continue
+* @returns Conditional pattern that evaluates predicate after inner pattern matches
+*
+* @example
+* // Only match if we're not too deep in the parse tree
+* pattern.if(ctx => ctx.depth < 10)
+*
+* // Only match if next token after match is LBRACE
+* token('IF').if(ctx => ctx.parser.isNextToken('LBRACE'))
+*
+* // Inspect full parser state
+* rule('expr').if(ctx => {
+    *   return ctx.parser.errors.length === 0 && ctx.ruleStack.length < 5
+    * })
+*/
+declare function conditional(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Shorthand for conditional() - more natural syntax
+* @see conditional
+*/
+declare function when(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Method-chaining style: pattern.if(predicate)
+* Extends Pattern type with .if() method for fluent API
+*
+* @note This is implemented as a utility function, not directly on Pattern
+*       Use: conditional(pattern, predicate) or when(pattern, predicate)
+*/
+declare function ifCondition(pattern: Pattern, predicate: ConditionalPredicate): Pattern;
+/**
+* Action pattern - executes a side effect during parsing.
+* Useful for scope management, state tracking, and stateful parsing.
+*
+* @param fn - Function called during execution with access to parser state
+* @returns Action pattern that always succeeds
+*
+* @example
+* // Track parse state
+* seq(
+    *   token('LBRACE'),
+    *   action(p => p.symbolTable?.pushScope()),
+    *   zeroOrMore(rule('stmt')),
+    *   token('RBRACE'),
+    *   action(p => p.symbolTable?.popScope())
+    * )
+*
+* // Count custom metric
+* action(p => p.stats.customCounter = (p.stats.customCounter ?? 0) + 1)
+*/
+declare function action(fn: ActionFunction): Pattern;
+/**
+* NOT pattern - succeeds if the inner pattern FAILS.
+* Useful for negative lookahead and validation checks.
+*
+* @param pattern - The pattern to negate
+* @returns NOT pattern
+*
+* @example
+* // Match any character except EOF
+* not(token('EOF'))
+*
+* // In a choice: match IDENT that is not a keyword
+* choice(
+    *   not(choice(token('IF'), token('WHILE'), token('FOR'))),
+    *   token('IDENT')
+    * )
+*/
+declare function not(pattern: Pattern): Pattern;
+/**
+* Lookahead pattern - checks if inner pattern would match WITHOUT consuming tokens.
+* Common alias: peek()
+*
+* @param pattern - The pattern to lookahead check
+* @returns Lookahead pattern
+*
+* @example
+* // Only match expr if followed by RPAREN
+* seq(
+    *   lookahead(seq(rule('expr'), token('RPAREN'))),
+    *   rule('expr')
+    * )
+*
+* // Safe token inspection
+* seq(
+    *   token('IDENT'),
+    *   when(lookahead(token('LPAREN')), ctx => ctx.parser.isNextToken('LPAREN'))
+    * )
+*/
+declare function lookahead(pattern: Pattern): Pattern;
+/**
+* Alias for lookahead() - more concise syntax.
+* @see lookahead
+*/
+declare function peek(pattern: Pattern): Pattern;
+/** Convenience: build a PrattTable from plain objects. */
+declare function buildPrattTable(spec: {
+    prefix?: Record<string, PrefixHandler>;
+    infix?: Record<string, InfixHandler>;
+}): PrattTable;
+/**
+* Delimited list pattern - matches items separated by a delimiter.
+* Commonly used for comma-separated values, arguments, etc.
+*
+* @param item - The pattern for each list item
+* @param sep - The separator pattern (usually token(','))
+* @param options - {min?: number, trailingOk?: boolean}
+* @returns Composed pattern for delimited list
+*
+* @example
+* // Comma-separated identifiers (0+)
+* delimited(token('IDENT'), token('COMMA'))
+*
+* // Function arguments (1+ with optional trailing)
+* delimited(rule('expr'), token('COMMA'), {min: 1, trailingOk: true})
+*
+* // Array elements
+* between('[', delimited(rule('expr'), token('COMMA')), ']')
+*/
+declare function delimited(item: Pattern, sep: Pattern, options?: {
+    min?: number;
+    trailingOk?: boolean;
+}): Pattern;
+/**
+* Surrounded pattern - matches content between open and close delimiters.
+* Alias for between(open, content, close).
+*
+* @param content - The pattern for interior content
+* @param open - Opening delimiter
+* @param close - Closing delimiter
+* @returns Composed pattern: open, content, close
+*
+* @example
+* // Parenthesized expression
+* surrounded(rule('expr'), token('LPAREN'), token('RPAREN'))
+*
+* // Generic syntax with string shorthand
+* surrounded(rule('typeList'), '(', ')')
+*/
+declare function surrounded(content: Pattern, open: Pattern, close: Pattern): Pattern;
+/**
+* Between pattern - matches content between left and right patterns.
+* Alias for surrounded but with more explicit name.
+*
+* @param left - Left sentinel pattern
+* @param content - Interior content pattern
+* @param right - Right sentinel pattern
+* @returns Composed pattern: left, content, right
+*
+* @example
+* // Array literal
+* between(token('LBRACK'), delimited(rule('expr'), token('COMMA')), token('RBRACK'))
+*
+* // Function call
+* between('(', delimited(rule('param'), ','), ')')
+*/
+declare function between(left: Pattern, content: Pattern, right: Pattern): Pattern;
+declare function error(cond: ErrorHandler['cond'], msg: string, code?: string): ErrorHandler;
+declare const errorRecoveryStrategies: {
+    skipUntil(tokens: string | string[]): RecoveryStrategy;
+};
+
+export { type BuildFunction, type ConditionalContext, type ConditionalPredicate, type DebugLevel, ERRORS, type ErrorHandler, type InfixHandler, type MiniToken, type ParseError, type ParseResult, Parser, type ParserSettings, type Pattern, type PrattTable, type PrefixHandler, type RecoveryStrategy, Result, type Rule, type Rules, action, between, buildPrattTable, choice, conditional, createRule, delimited, error, errorRecoveryStrategies, globalTokenMap, ifCondition, lookahead, loud, not, oneOrMore, optional, parse, peek, pratt, registerTokenMap, repeat, rule, seq, silent, surrounded, token, when, zeroOrMore, zeroOrOne };

package/dist/index.js

@@ -0,0 +1,3 @@
+var h=class s{constructor(e,t,r,n){this.span={start:-99,end:-99};this.status="unset";this.source=null;this.mode="unset";this.errors=[];this.status=e,this.source=t,this.mode=r,this.span=n;}static create(e,t,r,n){return new s(e,t,r,n)}static createAsToken(e,t,r){return s.create(e,{source_kind:"token-source",type:t?.type??"unset",text:t?.text??void 0,span:r},"token",r)}static createAsOptional(e,t,r){return s.create(e,{source_kind:"optional-source",result:t},"optional",r)}static createAsChoice(e,t,r,n){return s.create(e,{source_kind:"choice-source",atIndex:r,result:t},"choice",n)}static createAsRepeat(e,t,r,n=false){return s.create(e,{source_kind:"repeat-source",endsWithSep:n,result:t??[]},"repeat",r)}static createAsSequence(e,t,r){return s.create(e,{source_kind:"sequence-source",result:t??[]},"seq",r)}static createAsPratt(e,t,r){return s.create(e,{source_kind:"pratt-source",result:t},"pratt",r)}static createAsCustom(e,t,r,n){return s.create(e,{source_kind:"custom-source",name:t,data:r},"custom",n)}isPassed(){return this.status==="passed"}isFailed(){return this.status==="failed"}isUnset(){return this.status==="unset"}isToken(){return this.mode==="token"}isOptional(){return this.mode==="optional"}isChoice(){return this.mode==="choice"}isRepeat(){return this.mode==="repeat"}isSequence(){return this.mode==="seq"}isPratt(){return this.mode==="pratt"}isFullyPassed(){return !(!this.isPassed()||this.isOptional()&&!this.isOptionalPassed())}isOptionalPassed(){return this.isOptional()&&this.source.result!==null}isCustom(e){return this.mode!=="custom"?false:e?this.source.name===e:true}getTokenType(){return this.isToken()?this.source.type:void 0}getTokenSpan(){return this.isToken()?this.source.span:void 0}getOptionalResult(){return this.isOptionalPassed()?this.source.result:void 0}getChoiceIndex(){return this.isChoice()?this.source.atIndex:void 0}getChoiceResult(){return this.isChoice()?this.source.result:void 0}getRepeatCount(){return this.isRepeat()?this.source.result.length:void 0}getRepeatResult(){return this.isRepeat()?this.source.result:void 0}isRepeatEndsWithSep(){return this.isRepeat()?this.source.endsWithSep:void 0}getSequenceCount(){return this.isSequence()?this.source.result.length:void 0}getSequenceResult(){return this.isSequence()?this.source.result:void 0}getPrattResult(){return this.isPratt()?this.source.result:void 0}getCustomData(){return this.isCustom()?this.source.data:void 0}getCustomName(){return this.isCustom()?this.source.name:void 0}getTokenValue(){if(!this.isToken())return;let e=this.source.text;return e===void 0?null:e}getTokenData(){if(!this.isToken())return;let e=this.source;return {type:e.type,text:e.text,span:e.span}}clone(){let e=new s(this.status,this.source,this.mode,this.span);return e.errors=[...this.errors],e}hasErrors(){return this.errors.length>0}withError(e){return this.errors.push(e),this}};var p={LEXICAL_ERROR:"LEXICAL_ERROR",TOKEN_EXPECTED_EOF:"TOKEN_EXPECTED_EOF",TOKEN_MISMATCH:"TOKEN_MISMATCH",RULE_FAILED:"RULE_FAILED",BUILD_FUNCTION_FAILED:"BUILD_FUNCTION_FAILED",REPEAT_MIN_NOT_MET:"REPEAT_MIN_NOT_MET",SEQUENCE_FAILED:"SEQUENCE_FAILED",CUSTOM_ERROR:"CUSTOM_ERROR",CHOICE_ALL_FAILED:"CHOICE_ALL_FAILED",PRATT_NO_PREFIX:"PRATT_NO_PREFIX",FATAL_ERROR:"FATAL_ERROR",UNKNOWN_ERROR:"UNKNOWN_ERROR",RECOVERY_CUSTOM:"RECOVERY_CUSTOM"},E={};var d=h.create("failed",null,"unset",{start:-1,end:-1}),g=class{constructor(e,t){this.tokens=[];this.index=0;this.errors=[];this.ast=[];this.stats={tokensProcessed:0,rulesApplied:0,errorsRecovered:0,parseTimeMs:0};this._compiled=new Map;this._ruleIndex=new Map;this._laTable=new Map;this._memo=new Map;this._depth=0;this._silentDepth=0;this._rootStart=0;this._startTime=0;this._debugLevel="off";this._ignoredSet=new Set;this.lastHandledRule="unknown";this.lastVisitedIndex=0;this.ruleStack=[];this.rules=new Map(e.map(i=>[i.name,i])),this.settings=this._normalizeSettings(t),this._debugLevel=this.settings.debug,this._ignoredSet=new Set(this.settings.ignored);let r=0;for(let i of this.rules.keys())this._ruleIndex.set(i,r++);let n=this._validateGrammar();if(n.length)throw new Error(`Grammar validation failed:
+  ${n.join(`
+  `)}`);this._buildLookaheadSets();for(let[i,o]of this.rules)this._compiled.set(i,this._compilePattern(o.pattern,o));}parse(e){if(this._reset(e),this._startTime=Date.now(),!e.length)return {ast:[],errors:[]};let t=e.find(a=>a.type==="error");if(t)return {ast:[],errors:[this._mkError(p.LEXICAL_ERROR,`Unexpected token '${t.text}'`,t.span,0,0,"lexer")]};let r=this.rules.get(this.settings.startRule);if(!r)throw new Error(`Start rule '${this.settings.startRule}' not found`);let n=this._compiled.get(this.settings.startRule),i=this.settings.errorRecovery.maxErrors;this.settings.errorRecovery.mode==="resilient";try{for(this._skipIgnored();this.index<this.tokens.length&&!(i>0&&this.errors.length>=i);){let a=this.index;this._rootStart=a;let u=n(!1);if(u.isPassed()){let l=r.options?.build?this._safeBuild(r.options.build,u):u;l&&this.ast.push(l);}if(this.index===a)break;this._skipIgnored();}}catch(a){this._handleFatal(a);}return this.stats.parseTimeMs=Date.now()-this._startTime,{ast:this.ast,errors:this.errors,statistics:this.stats}}dispose(){this._memo.clear(),this._compiled.clear(),this.tokens=[],this.ast=[],this.errors=[];}isNextToken(e,t){let r=new Set([...this._ignoredSet,...t??[]]);for(let n=this.index;n<this.tokens.length;n++){let i=this.tokens[n];if(i.type===e)return  true;if(!r.has(i.type))break}return  false}isPrevToken(e,t=-1,r){let n=new Set([...this._ignoredSet,...r??[]]),i=t<0?this.index:t;for(let o=i-1;o>=0;o--){let a=this.tokens[o];if(a.type===e)return  true;if(!n.has(a.type))break}return  false}isPrevRule(e){return this.lastHandledRule===e}_buildLookaheadSets(){for(let t of this.rules.keys())this._laTable.set(t,new Set);let e=true;for(;e;){e=false;for(let[t,r]of this.rules){let n=this._laTable.get(t),i=this._firstOfPattern(r.pattern);for(let o of i)n.has(o)||(n.add(o),e=true);}}}_firstOfPattern(e){let t=new Set;switch(e.type){case "token":t.add(e.name);break;case "rule":{let r=this._laTable.get(e.name);if(r)for(let n of r)t.add(n);break}case "seq":for(let r of e.patterns??[]){for(let n of this._firstOfPattern(r))t.add(n);if(r.type!=="optional")break}break;case "choice":for(let r of e.patterns??[])for(let n of this._firstOfPattern(r))t.add(n);break;case "optional":case "repeat":case "conditional":case "not":case "lookahead":if(e.pattern)for(let r of this._firstOfPattern(e.pattern))t.add(r);break;case "action":break;case "pratt":if(e.table)for(let r of e.table.prefix.keys())t.add(r);break}return t}_compilePattern(e,t){switch(e.type){case "token":return this._compileToken(e,t);case "rule":return this._compileRule(e,t);case "seq":return this._compileSeq(e,t);case "choice":return this._compileChoice(e,t);case "repeat":return this._compileRepeat(e,t);case "optional":return this._compileOptional(e,t);case "pratt":return this._compilePratt(e,t);case "conditional":return this._compileConditional(e,t);case "action":return this._compileAction(e,t);case "not":return this._compileNot(e,t);case "lookahead":return this._compileLookahead(e,t);default:throw new Error(`Unknown pattern type: ${e.type}`)}}_compileToken(e,t){let r=e.name,n=e.value;return i=>{if(this.lastHandledRule=t?.name??r,this.lastVisitedIndex=this.index,this.index>=this.tokens.length){if(i)return d;throw this._mkError(p.TOKEN_EXPECTED_EOF,`Expected '${r}', got EOF`,this._span(),0,this.index,this.lastHandledRule)}let o=this.tokens[this.index];if(o.type===r){if(n!==void 0&&o.text!==n){if(i)return d;throw this._mkError(p.TOKEN_MISMATCH,`Expected '${r}' with value '${n}', got '${o.text}'`,o.span,0,this.index,this.lastHandledRule)}return this.index++,this.stats.tokensProcessed++,h.createAsToken("passed",o,o.span)}if(i)return d;let a=this._mkError(p.TOKEN_MISMATCH,`Expected '${r}', got '${o.type}'`,o.span,0,this.index,this.lastHandledRule);throw this._customErrorOr(t,a)}}_compileRule(e,t){let r=e.name;return n=>{let i=this.rules.get(r);if(!i)throw new Error(`Rule '${r}' not found`);let o=this._compiled.get(r);if(!o)throw new Error(`Rule '${r}' not compiled`);this.ruleStack.push(r),this.stats.rulesApplied++;let u=(this._ruleIndex.get(r)??0)<<16|this.index,l=this._getMemo(u);if(l)return this.ruleStack.pop(),this.index=l.endIndex,l.result??d;let c=this.index,f=this.errors.length,m=o(n);if(!m.isFullyPassed()){if(this.index=c,this.ruleStack.pop(),n)return d;let _=this._mkError(p.RULE_FAILED,`Rule '${r}' failed`,this._span(),0,this.lastVisitedIndex,r);throw this._customErrorOr(t,_)}let R=m;if(i.options?.build){let _=this._safeBuild(i.options.build,m);_&&(R=_);}return this._setMemo(u,R,this.index,f),this.ruleStack.pop(),R}}_compileSeq(e,t){let r=(e.patterns??[]).map(n=>this._compilePattern(n,t));return n=>{let i=this.index,o=[];for(let a=0;a<r.length;a++){this._skipIgnored(t?.options?.ignored);let u=r[a](n);if(!u.isPassed()){if(this.index=i,n)return d;let l=this._mkError(p.SEQUENCE_FAILED,`Sequence failed at element ${a+1}/${r.length}`,this._span(),a,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,l)}o.push(u);}return h.createAsSequence("passed",o,this._spanOf(o))}}_compileChoice(e,t){let r=e.patterns??[],n=r.map(o=>this._firstOfPattern(o)),i=r.map(o=>this._compilePattern(o,t));return o=>{let a=this.index;if(this._silentDepth++,this.index<this.tokens.length){let c=this.tokens[this.index].type,f=-1,m=false;for(let R=0;R<n.length;R++)if(n[R].has(c)){if(f>=0){m=true;break}f=R;}if(!m&&f>=0){this._silentDepth--;let R=i[f](o);if(R.isFullyPassed())return h.createAsChoice("passed",R,f,R.span);this.index=a,this._silentDepth++;}}let u=null;for(let c=0;c<i.length;c++){this.index=a;let f=i[c](true);if(f.isFullyPassed())return this._silentDepth--,h.createAsChoice("passed",f,c,f.span);let m=this.lastVisitedIndex-a;(!u||m>u.index-a)&&(u={index:this.lastVisitedIndex,err:null,altIdx:c});}if(this._silentDepth--,this.index=a,o)return d;let l=this._mkError(p.CHOICE_ALL_FAILED,`Expected one of: ${r.map(c=>this._patStr(c)).join(" | ")}`,this._span(),u?.altIdx??0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,l)}}_compileOptional(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);return this._silentDepth--,o.isFullyPassed()?h.createAsOptional("passed",o,o.span):(this.index=i,h.createAsOptional("passed",null,this._span()))}}_compileRepeat(e,t){let r=e.min??0,n=e.max??1/0,i=this._compilePattern(e.pattern,t),o=e.separator?this._compilePattern(e.separator,t):null;return a=>{let u=[],l=false,c=this.index;for(;u.length<n&&this.index<this.tokens.length;){let f=this.index;this._silentDepth++;let m=i(true);if(this._silentDepth--,!m.isFullyPassed()){this.index=f,l=false;break}if(u.push(m),l=false,this.index===f)break;if(o&&u.length<n&&this.index<this.tokens.length){let R=this.index;this._silentDepth++;let _=o(true);if(this._silentDepth--,!_.isFullyPassed()){this.index=R;break}l=true;}}if(u.length<r){if(this.index=c,a)return d;throw this._mkError(p.REPEAT_MIN_NOT_MET,`Expected at least ${r} occurrences, got ${u.length}`,this._span(),0,this.index,this.lastHandledRule)}return h.createAsRepeat("passed",u,this._spanOf(u),l)}}_compilePratt(e,t){let r=e.table;return n=>{if(this.index>=this.tokens.length){if(n)return d;throw this._mkError(p.PRATT_NO_PREFIX,"Expected an expression",this._span(),0,this.index,"pratt")}let i=this.tokens[this.index],o=r.prefix.get(i.type);if(!o){if(n)return d;throw this._mkError(p.PRATT_NO_PREFIX,`Unexpected token '${i.type}' in expression`,i.span,0,this.index,"pratt")}this.index++;let a=o.parse(this,i);if(!a.isPassed())return n?d:a;for(;this.index<this.tokens.length&&(this._skipIgnored(),!(this.index>=this.tokens.length));){let u=this.tokens[this.index],l=r.infix.get(u.type);if(!l||l.lbp<=0||(this.index++,a=l.parse(this,a,u),!a.isPassed()))break}return a}}_compileConditional(e,t){let r=this._compilePattern(e.pattern,t),n=e.predicate;return i=>{let o=this.index,a;if(i?(this._silentDepth++,a=r(true),this._silentDepth--):a=r(false),!a.isFullyPassed())return this.index=o,i?d:a;try{let u={parser:this,result:a,index:this.index,depth:this._depth,ruleStack:[...this.ruleStack]};if(n(u))return h.createAsCustom("passed","conditional",a,a.span);{if(this.index=o,i)return d;let c=this._mkError(p.RULE_FAILED,"Conditional predicate returned false",this._span(),0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,c)}}catch(u){if(this.index=o,i)return d;let l=u instanceof Error?u.message:String(u),c=this._mkError(p.RULE_FAILED,`Conditional predicate threw: ${l}`,this._span(),0,this.lastVisitedIndex,this.lastHandledRule);throw this._customErrorOr(t,c)}}}_compileAction(e,t){let r=e.fn;return n=>{try{r(this);}catch(i){let o=i instanceof Error?i.message:String(i);throw this._mkError(p.RULE_FAILED,`Action function threw: ${o}`,this._span(),0,this.index,"action")}return h.createAsCustom("passed","action",null,this._span())}}_compileNot(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);if(this._silentDepth--,o.isFullyPassed()){if(this.index=i,n)return d;let a=this._mkError(p.RULE_FAILED,"NOT pattern failed - inner pattern matched",this._span(),0,i,this.lastHandledRule);throw this._customErrorOr(t,a)}else return this.index=i,h.createAsCustom("passed","not",null,this._span())}}_compileLookahead(e,t){let r=this._compilePattern(e.pattern,t);return n=>{let i=this.index;this._silentDepth++;let o=r(true);if(this._silentDepth--,this.index=i,o.isFullyPassed())return h.createAsCustom("passed","lookahead",null,this._span());{if(n)return d;let a=this._mkError(p.RULE_FAILED,"Lookahead pattern failed",this._span(),0,i,this.lastHandledRule);throw this._customErrorOr(t,a)}}}_getMemo(e){let t=this._memo.get(e);return t?t.errorCount!==this.errors.length?(this._memo.delete(e),null):t:null}_setMemo(e,t,r,n){this._memo.set(e,{result:t,endIndex:r,errorCount:this.errors.length});}_mkError(e,t,r,n,i,o,a){return {code:e,msg:t,span:r,failedAt:n,tokenIndex:i,startIndex:this._rootStart,prevRule:o,prevInnerRule:a??this.ruleStack.at(-1)??"unknown"}}_customErrorOr(e,t){if(!e?.options?.errors)return t;for(let r of e.options.errors){let n=false;if(typeof r.cond=="number")n=t.failedAt===r.cond;else if(typeof r.cond=="function")try{n=r.cond(this,{failedAt:t.failedAt,tokenIndex:t.tokenIndex});}catch{}if(n)return this._mkError(r.code??p.CUSTOM_ERROR,r.msg,t.span,t.failedAt,t.tokenIndex,t.prevRule,t.prevInnerRule)}return t}_addError(e){if(this._silentDepth>0)return;let t=this.settings.errorRecovery.maxErrors;t>0&&this.errors.length>=t||this.settings.errorRecovery.mode==="strict"&&this.errors.length>0||this.errors.some(r=>r.span?.start===e.span?.start)||this.errors.push(e);}_handleFatal(e){e&&typeof e=="object"&&"msg"in e&&"code"in e?this._addError(e):e instanceof Error&&this._addError(this._mkError(p.FATAL_ERROR,e.message,this._span(),0,this.index,this.lastHandledRule));}_safeBuild(e,t){try{return e(t,this)}catch(r){let n=this._mkError(p.BUILD_FUNCTION_FAILED,r instanceof Error?r.message:String(r),this._span(),0,this.index,this.lastHandledRule);return this._addError(n),t}}_span(){if(!this.tokens.length)return {start:0,end:0};if(this.index>=this.tokens.length){let e=this.tokens[this.tokens.length-1];return {start:e.span.end,end:e.span.end}}return this.tokens[this.index].span}_spanOf(e){return e.length?{start:e[0].span.start,end:e[e.length-1].span.end}:this._span()}_skipIgnored(e){let t=e?new Set([...this._ignoredSet,...e]):this._ignoredSet;for(;this.index<this.tokens.length&&t.has(this.tokens[this.index].type);)this.index++,this.stats.tokensProcessed++;}_patStr(e){switch(e.type){case "token":return e.name;case "rule":return e.name;case "seq":return `(${(e.patterns??[]).map(t=>this._patStr(t)).join(" ")})`;case "choice":return (e.patterns??[]).map(t=>this._patStr(t)).join(" | ");case "optional":return `${this._patStr(e.pattern)}?`;case "repeat":return `${this._patStr(e.pattern)}*`;case "conditional":return `${this._patStr(e.pattern)}.if(...)`;case "action":return "action(...)";case "not":return `!${this._patStr(e.pattern)}`;case "lookahead":return `lookahead(${this._patStr(e.pattern)})`;case "pratt":return "expr";default:return e.type}}_validateGrammar(){let e=[],t=new Set(this.rules.keys()),r=(n,i)=>{n.type==="rule"&&!t.has(n.name)&&e.push(`Rule '${i}' references undefined rule '${n.name}'`);for(let o of [n.pattern,...n.patterns??[]])o&&r(o,i);n.separator&&r(n.separator,i);};for(let[n,i]of this.rules)r(i.pattern,n);return this.rules.has(this.settings.startRule)||e.push(`Start rule '${this.settings.startRule}' is not defined`),e}_normalizeSettings(e){return {startRule:e?.startRule??"root",errorRecovery:{mode:e?.errorRecovery?.mode??"strict",maxErrors:e?.errorRecovery?.maxErrors??1},ignored:e?.ignored??["ws"],debug:e?.debug??"off",maxDepth:e?.maxDepth??1e3}}_reset(e){this.tokens=e,this.index=0,this.errors=[],this.ast=[],this._depth=0,this._silentDepth=0,this._rootStart=0,this.ruleStack=[],this._memo.clear(),this.stats={tokensProcessed:0,rulesApplied:0,errorsRecovered:0,parseTimeMs:0};}};function w(s){Object.assign(E,s);}function F(s,e,t){let r=new g(e,t);try{return r.parse(s)}finally{r.dispose();}}function L(s,e,t={}){return {name:s,pattern:e,options:{name:false,...t}}}function M(s,e){if(!s)throw new Error("token(): name must be a non-empty string");return {type:"token",name:s,value:e,silent:false}}function k(s){return {type:"optional",pattern:s,silent:false}}function D(...s){if(!s.length)throw new Error("choice(): at least one pattern required");return {type:"choice",patterns:s,silent:false}}function T(s,e=0,t=1/0,r){if(e<0)throw new Error("repeat(): min cannot be negative");if(t<e)throw new Error("repeat(): max cannot be less than min");return {type:"repeat",pattern:s,min:e,max:t,separator:r,silent:false}}function H(s,e){return T(s,1,1/0,e)}function x(s,e){return T(s,0,1/0,e)}function N(s,e){return O(T(s,0,1,e))}function y(...s){if(!s.length)throw new Error("seq(): at least one pattern required");return {type:"seq",patterns:s,silent:false}}function U(s,e){if(!s)throw new Error("rule(): name must be a non-empty string");return {type:"rule",name:s,params:e,silent:false}}function O(s){return {...s,silent:true}}function $(s){return {...s,silent:false}}function q(s){return {type:"pratt",table:s,silent:false}}function S(s,e){return {type:"conditional",pattern:s,predicate:e,silent:false}}function V(s,e){return S(s,e)}function B(s,e){return S(s,e)}function K(s){return {type:"action",fn:s,silent:false}}function X(s){return {type:"not",pattern:s,silent:false}}function I(s){return {type:"lookahead",pattern:s,silent:false}}function j(s){return I(s)}function W(s){return {prefix:new Map(Object.entries(s.prefix??{})),infix:new Map(Object.entries(s.infix??{}))}}function z(s,e,t){let{min:r=0,trailingOk:n=false}=t??{},i;return r===0?n?i=k(y(T(s,1,1/0),x(y(e,s)),k(e))):i=k(y(T(s,1,1/0),x(y(e,s)))):r===1?n?i=y(T(s,1,1/0),x(y(e,s)),k(e)):i=y(T(s,1,1/0),x(y(e,s))):n?i=y(T(s,r,1/0),x(y(e,s)),k(e)):i=y(T(s,r,1/0),x(y(e,s))),i}function G(s,e,t){return y(e,s,t)}function Q(s,e,t){return y(s,e,t)}function Y(s,e,t){return {cond:s,msg:e,code:t??p.RECOVERY_CUSTOM}}var J={skipUntil(s){return {type:"skipUntil",tokens:Array.isArray(s)?s:[s]}}};export{p as ERRORS,g as Parser,h as Result,K as action,Q as between,W as buildPrattTable,D as choice,S as conditional,L as createRule,z as delimited,Y as error,J as errorRecoveryStrategies,E as globalTokenMap,B as ifCondition,I as lookahead,$ as loud,X as not,H as oneOrMore,k as optional,F as parse,j as peek,q as pratt,w as registerTokenMap,T as repeat,U as rule,y as seq,O as silent,G as surrounded,M as token,V as when,x as zeroOrMore,N as zeroOrOne};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@minelang-ts/parser",
+  "version": "0.0.1",
+  "description": "Mine programming language parser.",
+  "keywords": ["mine", "programming", "language", "parser"],
+  "license": "MIT",
+  "author": {
+    "email": "maysara.elshewehy@gmail.com",
+    "name": "Maysara Elshewehy",
+    "url": "https://github.com/maysara-elshewehy"
+  },
+  "type": "module",
+  "homepage": "https://github.com/minelang-ts/parser#readme",
+  "bugs": {
+    "url": "https://github.com/minelang-ts/parser/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/minelang-ts/parser.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.3"
+  },
+  "pkg": {
+    "type": "pkg"
+  },
+  "scripts": {},
+  "peerDependencies": {
+    "bun": "^1.3.14"
+  },
+  "dependencies": {
+    "@minelang-ts/lexer": "^0.0.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.0.1",
+    "bun-plugin-dts": "^0.4.0",
+    "bun-types": "^1.3.14",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1"
+  }
+}