Merge pull request GregRos#64 from sp3ctum/feature/strict-linting

refactor!: add stronger typing and linting, fix some minor bugs

.github/workflows/pr.yaml

@@ -9,19 +9,19 @@ jobs:
         strategy:
             matrix:
                 node-version:
-                    - 16.x
+                    - 18.x
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v4
             - name: Use Node.js ${{ matrix.node-version }}
-              uses: actions/setup-node@v2
+              uses: actions/setup-node@v3
               with:
-                  node-version: "16"
-                  cache: npm
-                  registry-url: https://registry.npmjs.org
-            - run: npm install
-            - run: npm run build
-            - run: npm run lint:check
-            - run: npm test
+                  node-version: "18"
+                  cache: yarn
+                  registry-url: "https://registry.yarnpkg.com"
+            - run: yarn install --immutable
+            - run: yarn build
+            - run: yarn lint:check
+            - run: yarn test
             - name: Coveralls
               uses: coverallsapp/github-action@master
               with:

.github/workflows/push.yaml

@@ -23,24 +23,24 @@ jobs:
         strategy:
             matrix:
                 node-version:
-                    - 16.x
+                    - 18.x
         steps:
-            - uses: actions/checkout@v2
+            - uses: actions/checkout@v4
             - name: Use Node.js ${{ matrix.node-version }}
-              uses: actions/setup-node@v2
+              uses: actions/setup-node@v3
               with:
-                  node-version: "16"
-                  cache: npm
-                  registry-url: https://registry.npmjs.org
-            - run: npm install
-            - run: npm run build
-            - run: npm run lint:check
-            - run: npm test
+                  node-version: "18"
+                  cache: yarn
+                  registry-url: "https://registry.yarnpkg.com"
+            - run: yarn install --immutable
+            - run: yarn build
+            - run: yarn lint:check
+            - run: yarn test
             - name: Coveralls
               uses: coverallsapp/github-action@master
               with:
                   github-token: ${{ secrets.GITHUB_TOKEN }}
-            - run: node_modules/.bin/typedoc --out docs
+            - run: yarn run docs
             - name: Setup Pages
               uses: actions/configure-pages@v3
             - name: Upload artifact
@@ -51,6 +51,6 @@ jobs:
               id: deployment
               uses: actions/deploy-pages@v2
             - name: publish
-              run: npm publish
+              run: yarn publish
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -87,3 +87,5 @@ jspm_packages
 # Optional REPL history
 .node_repl_history
 
+.yarnrc.yml
+.yarn

.nvmrc

@@ -0,0 +1 @@
+18

documentation/development.md

@@ -5,6 +5,9 @@ This project is using [Yarn](https://yarnpkg.com/) as a package manager. The rec
 Common development commands:
 
 ```sh
+# use the correct version of node (defined in .nvmrc)
+nvm use
+
 # install dependencies
 yarn
 
@@ -13,4 +16,8 @@ yarn build
 
 # test (remember to build first to make sure the code is up to date)
 yarn build && yarn test
+
+# quality checks
+yarn lint:check
+yarn lint:fix
 ```

package.json

@@ -30,7 +30,7 @@
         "test": "nyc node ./dist/test/runner.js",
         "build": "rm -rf dist/ && tsc",
         "rebuild": "shx rm -rf dist/ && tsc",
-        "docs": "node dist/generate-docs/run.js",
+        "docs": "typedoc --out docs",
         "do-publish": "yarn run build; node dist/publish.js; cd .tmp/publish; yarn publish",
         "eslint": "eslint 'src/**/*.ts'",
         "eslint:fix": "eslint --fix src/**/*.ts",
@@ -57,29 +57,27 @@
     },
     "devDependencies": {
         "@gregros/eslint-config": "^0.4.0",
-        "@types/jasmine": "^3.3.0",
-        "@types/lodash": "^4.14.104",
-        "@types/node": "^10.12.9",
-        "@typescript-eslint/eslint-plugin": "6.5.0",
-        "@typescript-eslint/parser": "6.5.0",
-        "eslint": "8.48.0",
-        "globby": "^9.2.0",
-        "jasmine": "^3.3.0",
-        "jasmine-core": "^3.3.0",
-        "jasmine-spec-reporter": "^4.2.1",
+        "@types/jasmine": "^5.1.1",
+        "@types/lodash": "^4.14.200",
+        "@types/node": "^20.8.10",
+        "@typescript-eslint/eslint-plugin": "^6.9.1",
+        "@typescript-eslint/parser": "^6.9.1",
+        "eslint": "^8.52.0",
+        "jasmine": "^5.1.0",
+        "jasmine-core": "^5.1.1",
+        "jasmine-spec-reporter": "^7.0.0",
         "npm-run-all": "^4.1.5",
         "nyc": "^13.1.0",
         "prettier": "3.0.3",
-        "shelljs": "^0.8.3",
+        "shelljs": "^0.8.5",
         "shx": "^0.3.4",
-        "source-map": "^0.7.3",
-        "source-map-support": "^0.5.9",
+        "source-map": "^0.7.4",
+        "source-map-support": "^0.5.21",
         "ts-node": "^10.9.1",
-        "typedoc": "^0.25.0",
+        "typedoc": "^0.25.3",
         "typedoc-plugin-internal-external": "^2.2.0",
         "typescript": "^5.2.2"
     },
-    "optionalDependencies": {},
     "typesVersions": {
         "*": {
             "combinators": [
@@ -102,5 +100,5 @@
         "sourceMap": true
     },
     "sideEffects": false,
-    "packageManager": "yarn@1.22.19"
+    "packageManager": "yarn@4.0.0"
 }

src/lib/errors.ts

@@ -12,7 +12,7 @@ import { ParjsFailure } from "./internal/result";
  * A parent class for all errors thrown by Parjs.
  */
 export abstract class ParjsError extends Error {
-    name = this.constructor.name;
+    override name = this.constructor.name;
 }
 
 /**

src/lib/internal/combinators/backtrack.ts

@@ -13,8 +13,8 @@ import { defineCombinator } from "./combinator";
  * and yields the result.
  */
 export function backtrack<T>(): ParjsCombinator<T, T> {
-    return defineCombinator(source => {
-        return new (class Backtrack extends ParjserBase {
+    return defineCombinator<T, T>(source => {
+        return new (class Backtrack extends ParjserBase<T> {
             type = "backtrack";
             expecting = source.expecting;
 

src/lib/internal/combinators/between.ts

@@ -1,8 +1,8 @@
 /** @module parjs/combinators */ /** */
 import { ImplicitParjser, ParjsCombinator } from "../../index";
+import { ScalarConverter } from "../scalar-converter";
 import { defineCombinator } from "./combinator";
 import { qthen, thenq } from "./then";
-import { ScalarConverter } from "../scalar-converter";
 
 /**
  * Applies `pre`, the source parser, and then `post`. Yields the result of
@@ -11,22 +11,21 @@ import { ScalarConverter } from "../scalar-converter";
  * @param post The parser to proceed the source.
  */
 export function between<T>(
-    pre: ImplicitParjser<any>,
-    post: ImplicitParjser<any>
+    pre: ImplicitParjser<unknown>,
+    post: ImplicitParjser<unknown>
 ): ParjsCombinator<T, T>;
 /**
  * Applies the `surrounding` parser, followed by the source parser, and then
  * another instance of `surrounding`. Yields the result of the source parser.
  * @param surrounding The parser to apply before and after the source.
  */
-export function between<T>(surrounding: ImplicitParjser<any>): ParjsCombinator<T, T>;
-export function between<T>(
-    implPre: ImplicitParjser<any>,
-    implPost?: ImplicitParjser<any>
+export function between<T>(surrounding: ImplicitParjser<unknown>): ParjsCombinator<T, T>;
+export function between<T, TPre, TPost = TPre>(
+    implPre: ImplicitParjser<TPre>,
+    implPost?: ImplicitParjser<TPost>
 ): ParjsCombinator<T, T> {
-    implPost = implPost || implPre;
     const pre = ScalarConverter.convert(implPre);
-    const post = ScalarConverter.convert(implPost);
+    const post = implPost ? ScalarConverter.convert(implPost) : pre;
     return defineCombinator(source => {
         return pre.pipe(qthen(source), thenq(post));
     });

src/lib/internal/combinators/combinator.ts

@@ -8,10 +8,12 @@ import { ScalarConverter } from "../scalar-converter";
  * Represents the given function as a Parjs combinator.
  * @param f The combinator function.
  */
-export function defineCombinator<E>(f: (act: ParjserBase & Parjser<E>) => Parjser<any>) {
-    return (x: ImplicitParjser<any>) => {
+export function defineCombinator<A, B>(
+    f: (act: ParjserBase<A> & Parjser<A>) => Parjser<B>
+): ParjsCombinator<A, B> {
+    return (x: ImplicitParjser<A>) => {
         const resolved = ScalarConverter.convert(x);
-        return f(resolved as ParjserBase);
+        return f(resolved as ParjserBase<A>);
     };
 }
 
@@ -146,6 +148,7 @@ export function pipe<T, T1, T2, T3, T4, T5, T6>(
     cmb6: ParjsCombinator<T5, T6>
 ): Parjser<T6>;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function pipe(source: any, ...funcs: ((x: any) => any)[]) {
     let last = ScalarConverter.convert(source);
     for (const func of funcs) {

src/lib/internal/combinators/each.ts

@@ -14,10 +14,9 @@ import { ParjserBase } from "../parser";
  * Applies `action` to each result emitted by the source parser and emits its results unchanged.
  * @param action
  */
-export function each<T>(action: ParjsProjection<T, void>): ParjsCombinator<T, T>;
-export function each(action: any) {
-    return defineCombinator(source => {
-        return new (class extends ParjserBase {
+export function each<T>(action: ParjsProjection<T, void>): ParjsCombinator<T, T> {
+    return defineCombinator<T, T>(source => {
+        return new (class extends ParjserBase<T> {
             type = "each";
             expecting = source.expecting;
 
@@ -26,7 +25,7 @@ export function each(action: any) {
                 if (!ps.isOk) {
                     return;
                 }
-                action(ps.value, ps.userState);
+                action(ps.value as T, ps.userState);
             }
         })();
     });

src/lib/internal/combinators/exactly.ts

@@ -13,15 +13,13 @@ import { ParjserBase } from "../parser";
  * Applies the source parser exactly `count` times, and yields all the results in an array.
  * @param count The number of times to apply the source parser.
  */
-export function exactly<T>(count: number): ParjsCombinator<T, T[]>;
-
-export function exactly(count: number) {
-    return defineCombinator(source => {
-        return new (class Exactly extends ParjserBase {
+export function exactly<T>(count: number): ParjsCombinator<T, T[]> {
+    return defineCombinator<T, T[]>(source => {
+        return new (class Exactly extends ParjserBase<T[]> {
             type = "exactly";
             expecting = source.expecting;
             _apply(ps: ParsingState): void {
-                const arr = [] as any[];
+                const arr = [] as unknown[];
                 for (let i = 0; i < count; i++) {
                     source.apply(ps);
                     if (!ps.isOk) {

src/lib/internal/combinators/flatten.ts

@@ -6,21 +6,13 @@ import { map } from "./map";
 /**
  * The type of an arbitrarily nested array or a non-array element.
  */
-export type NestedArray<T> =
-    | T
-    | T[]
-    | T[][]
-    | T[][][]
-    | T[][][][]
-    | T[][][][][]
-    | T[][][][][][]
-    | T[][][][][][][][];
+export type NestedArray<T> = T | NestedArray<T>[];
 
-function flattenNestedArrays(arr: unknown[] | unknown) {
+function flattenNestedArrays<T>(arr: NestedArray<T>): T[] {
     if (!Array.isArray(arr)) {
         return [arr];
     }
-    const items = [] as any[];
+    const items = [] as T[];
     for (const item of arr) {
         if (Array.isArray(item)) {
             items.push(...flattenNestedArrays(item));

src/lib/internal/combinators/later.ts

@@ -22,16 +22,16 @@ export interface DelayedParjser<T> extends Parjser<T> {
  * another parser by calling the parser's `init` function.
  */
 export function later<T>(): DelayedParjser<T> {
-    return new (class Late extends ParjserBase {
+    return new (class Late extends ParjserBase<T> implements DelayedParjser<T> {
         type = "later";
-        _resolved!: ParjserBase;
+        _resolved!: ParjserBase<T>;
         get expecting() {
             return !this._resolved ? "unbound delayed parser" : this._resolved.expecting;
         }
 
         init(resolved: Parjser<T>) {
             if (this._resolved) Issues.delayedParserAlreadyInit();
-            this._resolved = resolved as ParjserBase;
+            this._resolved = resolved as ParjserBase<T>;
         }
 
         _apply(ps: ParsingState): void {