Merge pull request GregRos#78 from sp3ctum/feature/small-improvements

Feature: small improvements

jest.config.ts

@@ -2,8 +2,6 @@ import path from "path";
 import { Config } from "jest";
 
 const config: Config = {
-    preset: "ts-jest",
-    collectCoverage: true,
     setupFilesAfterEnv: [path.join(__dirname, "src", "test", "helpers", "jest-setup.ts")],
     testPathIgnorePatterns: ["dist"],
     transform: {

package.json

@@ -65,14 +65,13 @@
         "@typescript-eslint/parser": "6.9.1",
         "eslint": "8.54.0",
         "eslint-plugin-jest": "27.6.0",
-        "jest": "29.7.0",
+        "jest": "30.0.0-alpha.2",
         "npm-run-all": "4.1.5",
         "prettier": "3.0.3",
         "shelljs": "0.8.5",
         "shx": "0.3.4",
         "source-map": "0.7.4",
         "source-map-support": "0.5.21",
-        "ts-jest": "29.1.1",
         "ts-node": "10.9.1",
         "typedoc": "0.25.3",
         "typedoc-plugin-internal-external": "2.2.0",

src/lib/internal/combinators/or.ts

@@ -3,12 +3,12 @@
  */
 /** */
 
-import { ParsingState } from "../state";
-import { ResultKind } from "../result";
 import { ParjsCombinator } from "../..";
+import { ParjserBase } from "../parser";
+import { ResultKind } from "../result";
 import { ImplicitParjser, ScalarConverter } from "../scalar-converter";
+import { ParsingState } from "../state";
 import { defineCombinator } from "./combinator";
-import { ParjserBase } from "../parser";
 
 /**
  * Applies the source parser. If it fails softly, will try to apply the
@@ -20,7 +20,7 @@ import { ParjserBase } from "../parser";
  *
  * @param alt1 The first alternative parser to apply.
  */
-export function or<T1, T2>(alt1: ImplicitParjser<T2>): ParjsCombinator<T1, T1 | T2>;
+export function or<const T1, const T2>(alt1: ImplicitParjser<T2>): ParjsCombinator<T1, T1 | T2>;
 
 /**
  * Applies the source parser. If it fails softly, will try to apply the
@@ -33,7 +33,7 @@ export function or<T1, T2>(alt1: ImplicitParjser<T2>): ParjsCombinator<T1, T1 |
  * @param alt1 The first alternative parser to apply.
  * @param alt2 The second alternative parser to apply.
  */
-export function or<T1, T2, T3>(
+export function or<const T1, const T2, const T3>(
     alt1: ImplicitParjser<T2>,
     alt2: ImplicitParjser<T3>
 ): ParjsCombinator<T1, T1 | T2 | T3>;
@@ -50,7 +50,7 @@ export function or<T1, T2, T3>(
  * @param alt2 The second alternative parser to apply.
  * @param alt3 The third alternative parser to apply.
  */
-export function or<T1, T2, T3, T4>(
+export function or<const T1, const T2, const T3, const T4>(
     alt1: ImplicitParjser<T2>,
     alt2: ImplicitParjser<T3>,
     alt3: ImplicitParjser<T4>
@@ -69,7 +69,7 @@ export function or<T1, T2, T3, T4>(
  * @param alt3 The third alternative parser to apply.
  * @param alt4 The fourth alternative parser to apply.
  */
-export function or<T1, T2, T3, T4, T5>(
+export function or<const T1, const T2, const T3, const T4, const T5>(
     alt1: ImplicitParjser<T2>,
     alt2: ImplicitParjser<T3>,
     alt3: ImplicitParjser<T4>,

src/lib/internal/combinators/recover.ts

@@ -3,12 +3,12 @@
  */
 /** */
 
-import { ParsingState, UserState } from "../state";
-import { FailureInfo, ResultKind, SuccessInfo } from "../result";
 import { ParjsCombinator } from "../../";
+import { FailureInfo, ResultKind, SuccessInfo } from "../result";
+import { ParsingState, UserState } from "../state";
 
-import { defineCombinator } from "./combinator";
 import { ParjserBase } from "../parser";
+import { defineCombinator } from "./combinator";
 
 /**
  * Information about the failure.
@@ -40,7 +40,7 @@ export type RecoveryFunction<T> = (
 /**
  * Reduces Hard failures to Soft ones and behaves in the same way on success.
  */
-export function recover<T>(recoverFunction: RecoveryFunction<T>): ParjsCombinator<unknown, T> {
+export function recover<T>(recoverFunction: RecoveryFunction<T>): ParjsCombinator<T, T> {
     return defineCombinator<unknown, T>(source => {
         return new (class Soft extends ParjserBase<T> {
             type = "recover";

src/lib/internal/parjser.ts

@@ -3,8 +3,8 @@
  */ /** */
 
 import { FailureInfo, ParjsResult } from "./result";
-import { UserState } from "./state";
 import { ImplicitParjser } from "./scalar-converter";
+import { UserState } from "./state";
 
 /**
  * A combinator or operator that takes a source parser that returns a new parser
@@ -57,15 +57,18 @@ export interface Parjser<T> {
      * this parser, feeding the result of one into the input of the next.
      * @param cmb1 The single combinator to apply.
      */
-    pipe<T1>(cmb1: ParjsCombinator<T, T1>): Parjser<T1>;
+    pipe<const T1>(cmb1: ParjsCombinator<T, T1>): Parjser<T1>;
 
     /**
      * The chaining or piping operator. Applies a sequence of combinators to
      * this parser, feeding the result of one into the input of the next.
      * @param cmb1 The first combinator to apply.
      * @param cmb2 The second combinator to apply.
      */
-    pipe<T1, T2>(cmb1: ParjsCombinator<T, T1>, cmb2: ParjsCombinator<T1, T2>): Parjser<T2>;
+    pipe<const T1, const T2>(
+        cmb1: ParjsCombinator<T, T1>,
+        cmb2: ParjsCombinator<T1, T2>
+    ): Parjser<T2>;
 
     /**
      * The chaining or piping operator. Applies a sequence of combinators to
@@ -74,7 +77,7 @@ export interface Parjser<T> {
      * @param cmb2 The second combinator to apply.
      * @param cmb3 The third combinator to apply.
      */
-    pipe<T1, T2, T3>(
+    pipe<const T1, const T2, const T3>(
         cmb1: ParjsCombinator<T, T1>,
         cmb2: ParjsCombinator<T1, T2>,
         cmb3: ParjsCombinator<T2, T3>
@@ -88,7 +91,7 @@ export interface Parjser<T> {
      * @param cmb3 The third combinator to apply.
      * @param cmb4 The fourth combinator to apply.
      */
-    pipe<T1, T2, T3, T4>(
+    pipe<const T1, const T2, const T3, const T4>(
         cmb1: ParjsCombinator<T, T1>,
         cmb2: ParjsCombinator<T1, T2>,
         cmb3: ParjsCombinator<T2, T3>,
@@ -104,7 +107,7 @@ export interface Parjser<T> {
      * @param cmb4 The fourth combinator to apply.
      * @param cmb5 The fifth combinator to apply.
      */
-    pipe<T1, T2, T3, T4, T5>(
+    pipe<const T1, const T2, const T3, const T4, const T5>(
         cmb1: ParjsCombinator<T, T1>,
         cmb2: ParjsCombinator<T1, T2>,
         cmb3: ParjsCombinator<T2, T3>,
@@ -122,7 +125,7 @@ export interface Parjser<T> {
      * @param cmb5 The fifth combinator to apply.
      * @param cmb6 The sixth combinator to apply.
      */
-    pipe<T1, T2, T3, T4, T5, T6>(
+    pipe<const T1, const T2, const T3, const T4, const T5, const T6>(
         cmb1: ParjsCombinator<T, T1>,
         cmb2: ParjsCombinator<T1, T2>,
         cmb3: ParjsCombinator<T2, T3>,

src/lib/internal/parser.ts

@@ -3,13 +3,18 @@
  */
 /** */
 
+import clone from "lodash/clone";
+import defaults from "lodash/defaults";
+import { ScalarConverter } from ".";
+import { ParserDefinitionError } from "../errors";
+import { ParjsCombinator, Parjser } from "./parjser";
 import {
+    ErrorLocation,
     ParjsFailure,
     ParjsResult,
-    ResultKind,
     ParjsSuccess,
-    Trace,
-    ErrorLocation
+    ResultKind,
+    Trace
 } from "./result";
 import {
     BasicParsingState,
@@ -18,12 +23,6 @@ import {
     UNINITIALIZED_RESULT,
     UserState
 } from "./state";
-import defaults from "lodash/defaults";
-import { ParserDefinitionError } from "../errors";
-import { ParjsCombinator, Parjser } from "./parjser";
-import { pipe } from "./combinators/combinator";
-import clone from "lodash/clone";
-import { ScalarConverter } from ".";
 
 function getErrorLocation(ps: ParsingState) {
     const endln = /\r\n|\n|\r/g;
@@ -61,7 +60,7 @@ export abstract class ParjserBase<TValue> implements Parjser<TValue> {
     expects(expecting: string): Parjser<TValue> {
         const copy = clone(this);
         copy.expecting = expecting;
-        return copy as Parjser<TValue>;
+        return copy;
     }
     /**
      * Apply the parser to the given state.
@@ -94,7 +93,7 @@ export abstract class ParjserBase<TValue> implements Parjser<TValue> {
             if (ps.reason == null) {
                 throw new ParserDefinitionError(this.type, "a failure must have a reason");
             }
-            ps.stack.push(this as unknown as Parjser<unknown>);
+            ps.stack.push(this);
         } else {
             ps.stack = [];
         }
@@ -162,9 +161,9 @@ export abstract class ParjserBase<TValue> implements Parjser<TValue> {
         let last: any = ScalarConverter.convert(this);
 
         for (const cmb of combinators) {
-            last = pipe(last, cmb as ParjsCombinator<unknown, unknown>);
+            last = (cmb as ParjsCombinator<unknown, unknown>)(last);
         }
 
-        return last as unknown as Parjser<T6>;
+        return last as Parjser<T6>;
     }
 }

src/lib/internal/parsers/char-types.ts

@@ -29,7 +29,7 @@ export function anyChar(): Parjser<string> {
 }
 
 /**
- * Returns a parser that parses a single ASCII inline space.
+ * Returns a parser that parses a single space (`[ \t]`).
  */
 export function space(): Parjser<string> {
     return charWhere(x => isSpace(x) || { reason: "expecting a space" });

src/lib/internal/parsers/string-of.ts

@@ -12,10 +12,11 @@ import { Parjser } from "../parjser";
  * Returns a parser that will parse any of the strings in `strs` and yield
  * the text that was parsed. If it can't, it will fail softly without consuming
  * input.
- * @param strs A set of string options to parse.
+ * @param strs A set of string options to parse. In typescript, you can also use
+ * a constant tuple if you pass it in using the spread operator (`...`).
  */
-export function anyStringOf(...strs: string[]): Parjser<string> {
-    return new (class StringOf extends ParjserBase<string> {
+export function anyStringOf<T extends string>(...strs: T[]): Parjser<T> {
+    return new (class StringOf extends ParjserBase<T> {
         type = "anyStringOf";
         expecting = `expecting any of ${strs.map(x => `'${x}'`).join(", ")}`;
 

src/lib/internal/parsers/string.ts

@@ -13,8 +13,8 @@ import { Parjser } from "..";
  * that was parsed. If it can't, it will fail softly without consuming input.
  * @param str The string to parse.
  */
-export function string(str: string): Parjser<string> {
-    return new (class ParseString extends ParjserBase<string> {
+export function string<T extends string>(str: T): Parjser<T> {
+    return new (class ParseString extends ParjserBase<T> {
         expecting = `expecting '${str}'`;
         type = "string";
         _apply(ps: ParsingState): void {

src/lib/internal/scalar-converter.ts

@@ -5,8 +5,8 @@
 
 import { Parjser } from "./parjser";
 
-import { string } from "./parsers/string";
 import { regexp } from "./parsers/regexp";
+import { string } from "./parsers/string";
 
 /**
  * A {@link Parjser} or a literal value convertible to a {@link Parjser}.

src/lib/internal/state.ts

@@ -3,7 +3,7 @@
  */
 /** */
 import { ResultKind } from "./result";
-import { Parjser } from "./parjser";
+import { ParjserBase } from ".";
 
 /**
  * Container type for user state data.
@@ -41,7 +41,7 @@ export interface ParsingState {
     /**
      * A stack that indicates entered parsers. Should not be modified by user code.
      */
-    stack: Parjser<unknown>[];
+    stack: ParjserBase<unknown>[];
 
     /**
      * If the result is a failure, this field will indicate the reason for the failure.
@@ -74,7 +74,7 @@ export interface ParsingState {
     atMost(kind: ResultKind): boolean | undefined;
 }
 
-function worseThan(a: ResultKind, b: ResultKind) {
+function worseThan(a: ResultKind, b: ResultKind): boolean | undefined {
     if (a === ResultKind.Ok) {
         return b === ResultKind.Ok;
     }
@@ -130,8 +130,6 @@ export class BasicParsingState<TValue> implements ParsingState {
     }
 }
 
-// tslint:disable:naming-convention
-
 /**
  * A unique object value indicating the reuslt of a failed parser.
  */

src/lib/internal/trace-visualizer.ts

@@ -7,6 +7,7 @@ import { Trace } from "./result";
 import { NumHelpers } from "./functions/helpers";
 import repeat from "lodash/repeat";
 import defaults from "lodash/defaults";
+import { ParjserBase } from "./parser";
 
 /**
  * A set of arguments for the trace visualizer.
@@ -50,19 +51,25 @@ function newTraceVisualizer(pAgs: Partial<TraceVisualizerArgs>) {
         linesAround.push(errorMarked);
         const linesVisualization = linesAround.join("\n");
 
+        const stack = trace.stackTrace
+            .map(x => {
+                const base = x as ParjserBase<unknown>;
+                return `${base.expecting} (${x.type})`;
+            })
+            .filter(x => x)
+            .join("\n");
         const fullVisualization = `${trace.kind} failure at Ln ${trace.location.line + 1} Col ${
             trace.location.column + 1
         }
 ${linesVisualization}
-Stack: ${trace.stackTrace
-            .map(x => x.type)
-            .filter(x => x)
-            .join(" < ")}
+
+Stack:
+${stack}
 `;
         return fullVisualization;
     };
     visualizer.configure = newTraceVisualizer;
-    return visualizer as TraceVisualizer;
+    return visualizer;
 }
 
 /**