refactor: Port module to TS, Jest, ESLint (#7)

BREAKING: The main export is now a `default` export.

Author: fb55

.eslintignore

@@ -0,0 +1,3 @@
+node_modules/
+coverage/
+lib/

.eslintrc.json

@@ -0,0 +1,62 @@
+{
+    "extends": ["eslint:recommended", "prettier"],
+    "env": {
+        "node": true,
+        "es6": true
+    },
+    "rules": {
+        "eqeqeq": [2, "smart"],
+        "no-caller": 2,
+        "dot-notation": 2,
+        "no-var": 2,
+        "prefer-const": 2,
+        "prefer-arrow-callback": [2, { "allowNamedFunctions": true }],
+        "arrow-body-style": [2, "as-needed"],
+        "object-shorthand": 2,
+        "prefer-template": 2,
+        "one-var": [2, "never"],
+        "prefer-destructuring": [2, { "object": true }],
+        "capitalized-comments": 2,
+        "multiline-comment-style": [2, "starred-block"],
+        "spaced-comment": 2,
+        "yoda": [2, "never"],
+        "curly": [2, "multi-line"],
+        "no-else-return": 2
+    },
+    "overrides": [
+        {
+            "files": "*.ts",
+            "extends": [
+                "plugin:@typescript-eslint/eslint-recommended",
+                "plugin:@typescript-eslint/recommended",
+                "prettier/@typescript-eslint"
+            ],
+            "parserOptions": {
+                "sourceType": "module",
+                "project": "./tsconfig.eslint.json"
+            },
+            "rules": {
+                "@typescript-eslint/prefer-for-of": 0,
+                "@typescript-eslint/member-ordering": 0,
+                "@typescript-eslint/explicit-function-return-type": 0,
+                "@typescript-eslint/no-unused-vars": 0,
+                "@typescript-eslint/no-use-before-define": [
+                    2,
+                    { "functions": false }
+                ],
+                "@typescript-eslint/consistent-type-definitions": [
+                    2,
+                    "interface"
+                ],
+                "@typescript-eslint/prefer-function-type": 2,
+                "@typescript-eslint/no-unnecessary-type-arguments": 2,
+                "@typescript-eslint/prefer-string-starts-ends-with": 2,
+                "@typescript-eslint/prefer-readonly": 2,
+                "@typescript-eslint/prefer-includes": 2,
+                "@typescript-eslint/no-unnecessary-condition": 2,
+                "@typescript-eslint/switch-exhaustiveness-check": 2,
+                "@typescript-eslint/prefer-nullish-coalescing": 2
+            }
+        }
+    ]
+}

.github/FUNDING.yml

@@ -1,12 +1,2 @@
-# These are supported funding model platforms
-
-github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
-patreon: # Replace with a single Patreon username
-open_collective: # Replace with a single Open Collective username
-ko_fi: # Replace with a single Ko-fi username
+github: [fb55]
 tidelift: "npm/nth-check"
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-otechie: # Replace with a single Otechie username
-custom: # Replace with a single custom sponsorship URL

.gitignore

@@ -1 +1,4 @@
+.vscode/
 node_modules/
+coverage/
+lib/

.prettierignore

@@ -0,0 +1,3 @@
+node_modules/
+coverage/
+lib/

.travis.yml

@@ -1,6 +1,6 @@
 language: node_js
 arch:
-  - amd64
-  - ppc64le
+    - amd64
+    - ppc64le
 node_js:
-  - lts/*
+    - lts/*

README.md

@@ -1,6 +1,6 @@
 # nth-check [![Build Status](https://travis-ci.org/fb55/nth-check.svg)](https://travis-ci.org/fb55/nth-check)
 
-A performant nth-check parser & compiler.
+Parses and compiles CSS nth-checks to highly optimized functions.
 
 ### About
 
@@ -11,43 +11,61 @@ This module can be used to parse & compile nth-checks, as they are found in CSS
 ### API
 
 ```js
-const nthCheck = require("nth-check");
+import nthCheck, { parse, compile } from "nth-check";
 ```
 
 ##### `nthCheck(formula)`
 
-First parses, then compiles the formula.
+Parses and compiles a formula to a highly optimized function. Combination of `parse` and `compile`.
 
-##### `nthCheck.parse(formula)`
+If the formula doesn't match any elements, it returns [`boolbase`](https://github.com/fb55/boolbase)'s `falseFunc`. Otherwise, a function accepting an _index_ is returned, which returns whether or not the passed _index_ matches the formula.
 
-Parses the expression, throws a `SyntaxError` if it fails. Otherwise, returns an array containing the integer step size and the integer offset of the nth rule.
+**Note**: The nth-rule starts counting at `1`, the returned function at `0`.
 
-__Example:__
+**Example:**
 
 ```js
-nthCheck.parse("2n+3") //[2, 3]
+const check = nthCheck("2n+3");
+
+check(0); // `false`
+check(1); // `false`
+check(2); // `true`
+check(3); // `false`
+check(4); // `true`
+check(5); // `false`
+check(6); // `true`
 ```
 
-##### `nthCheck.compile([a, b])`
+##### `parse(formula)`
+
+Parses the expression, throws an `Error` if it fails. Otherwise, returns an array containing the integer step size and the integer offset of the nth rule.
+
+**Example:**
+
+```js
+parse("2n+3"); // [2, 3]
+```
+
+##### `compile([a, b])`
 
 Takes an array with two elements (as returned by `.parse`) and returns a highly optimized function.
 
-If the formula doesn't match any elements, it returns [`boolbase`](https://github.com/fb55/boolbase)'s `falseFunc`, otherwise, a function accepting an _index_ is returned, which returns whether or not a passed _index_ matches the formula. (Note: The spec starts counting at `1`, the returned function at `0`).
+**Example:**
 
-__Example:__
 ```js
-const check = nthCheck.compile([2, 3]);
-
-check(0) //false
-check(1) //false
-check(2) //true
-check(3) //false
-check(4) //true
-check(5) //false
-check(6) //true
+const check = compile([2, 3]);
+
+check(0); // `false`
+check(1); // `false`
+check(2); // `true`
+check(3); // `false`
+check(4); // `true`
+check(5); // `false`
+check(6); // `true`
 ```
 
 ---
+
 License: BSD-2-Clause
 
 ## Security contact information

compile.js

@@ -1,35 +1,67 @@
 {
-  "name": "nth-check",
-  "version": "1.0.2",
-  "description": "performant nth-check parser & compiler",
-  "main": "index.js",
-  "scripts": {
-    "test": "node test"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/fb55/nth-check"
-  },
-  "files": [
-    "compile.js",
-    "index.js",
-    "parse.js"
-  ],
-  "keywords": [
-    "nth-child",
-    "nth",
-    "css"
-  ],
-  "author": "Felix Boehm <me@feedic.com>",
-  "license": "BSD-2-Clause",
-  "bugs": {
-    "url": "https://github.com/fb55/nth-check/issues"
-  },
-  "homepage": "https://github.com/fb55/nth-check",
-  "dependencies": {
-    "boolbase": "~1.0.0"
-  },
-  "prettier": {
-    "tabWidth": 4
-  }
+    "name": "nth-check",
+    "version": "1.0.2",
+    "description": "Parses and compiles CSS nth-checks to highly optimized functions.",
+    "author": "Felix Boehm <me@feedic.com>",
+    "license": "BSD-2-Clause",
+    "sideEffects": false,
+    "funding": {
+        "url": "https://github.com/fb55/nth-check?sponsor=1"
+    },
+    "directories": {
+        "lib": "lib/"
+    },
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "files": [
+        "lib/**/*"
+    ],
+    "scripts": {
+        "test": "jest --coverage && npm run lint",
+        "coverage": "cat coverage/lcov.info | coveralls",
+        "lint": "npm run lint:es && npm run lint:prettier",
+        "lint:es": "eslint .",
+        "lint:prettier": "npm run prettier -- --check",
+        "format": "npm run format:es && npm run format:prettier",
+        "format:es": "npm run lint:es -- --fix",
+        "format:prettier": "npm run prettier -- --write",
+        "prettier": "prettier '**/*.{ts,md,json,yml}'",
+        "build": "tsc",
+        "prepare": "npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/fb55/nth-check"
+    },
+    "keywords": [
+        "nth-child",
+        "nth",
+        "css"
+    ],
+    "bugs": {
+        "url": "https://github.com/fb55/nth-check/issues"
+    },
+    "homepage": "https://github.com/fb55/nth-check",
+    "dependencies": {
+        "boolbase": "^1.0.0"
+    },
+    "devDependencies": {
+        "@types/jest": "^26.0.0",
+        "@types/node": "^14.0.5",
+        "@typescript-eslint/eslint-plugin": "^4.1.0",
+        "@typescript-eslint/parser": "^4.1.0",
+        "eslint": "^7.0.0",
+        "eslint-config-prettier": "^6.0.0",
+        "jest": "^26.0.1",
+        "prettier": "^2.1.1",
+        "ts-jest": "^26.0.0",
+        "typescript": "^4.0.2"
+    },
+    "jest": {
+        "preset": "ts-jest",
+        "testEnvironment": "node"
+    },
+    "prettier": {
+        "tabWidth": 4
+    }
 }

index.js

@@ -0,0 +1,49 @@
+export const valid: [string, [number, number]][] = [
+    ["1", [0, 1]],
+    ["2", [0, 2]],
+    ["3", [0, 3]],
+    ["5", [0, 5]],
+    [" 1 ", [0, 1]],
+    [" 5 ", [0, 5]],
+    ["+2n + 1", [2, 1]],
+    ["-1", [0, -1]],
+    ["-1n + 3", [-1, 3]],
+    ["-1n+3", [-1, 3]],
+    ["-n+2", [-1, 2]],
+    ["-n+3", [-1, 3]],
+    ["0n+3", [0, 3]],
+    ["1n", [1, 0]],
+    ["1n+0", [1, 0]],
+    ["2n", [2, 0]],
+    ["2n + 1", [2, 1]],
+    ["2n+1", [2, 1]],
+    ["3n", [3, 0]],
+    ["3n+0", [3, 0]],
+    ["3n+1", [3, 1]],
+    ["3n+2", [3, 2]],
+    ["3n+3", [3, 3]],
+    ["3n-1", [3, -1]],
+    ["3n-2", [3, -2]],
+    ["3n-3", [3, -3]],
+    ["even", [2, 0]],
+    ["n", [1, 0]],
+    ["n+2", [1, 2]],
+    ["odd", [2, 1]],
+
+    // Surprisingly, neither sizzle, qwery or nwmatcher cover these cases
+    ["-4n+13", [-4, 13]],
+    ["-2n + 12", [-2, 12]],
+];
+
+export const invalid = [
+    "-",
+    "- 1n",
+    "-1 n",
+    "2+0",
+    "2n+-0",
+    "an+b",
+    "asdf",
+    "b",
+    "expr",
+    "odd|even|x",
+];

package-lock.json

@@ -0,0 +1,39 @@
+import nthCheck, { compile } from ".";
+import { valid } from "./__fixtures__/rules";
+
+const valArray = new Array(...Array(2e3)).map((_, i) => i);
+
+/**
+ * Iterate through all possible values. This is adapted from qwery,
+ * and uses a more intuitive way to process all elements.
+ */
+function slowNth([a, b]: [number, number]): number[] {
+    if (a === 0 && b > 0) return [b - 1];
+
+    return valArray.filter((val) => {
+        for (let i = b; a > 0 ? i <= valArray.length : i >= 1; i += a) {
+            if (val === valArray[i - 1]) return true;
+        }
+        return false;
+    });
+}
+
+describe("parse", () => {
+    it("compile & run all valid", () => {
+        for (const [_, parsed] of valid) {
+            const filtered = valArray.filter(compile(parsed));
+            const iterated = slowNth(parsed);
+
+            expect(filtered).toStrictEqual(iterated);
+        }
+    });
+
+    it("parse, compile & run all valid", () => {
+        for (const [rule, parsed] of valid) {
+            const filtered = valArray.filter(nthCheck(rule));
+            const iterated = slowNth(parsed);
+
+            expect([filtered, rule]).toStrictEqual([iterated, rule]);
+        }
+    });
+});

package.json

@@ -0,0 +1,54 @@
+import { trueFunc, falseFunc } from "boolbase";
+
+/**
+ * Returns a function that checks if an elements index matches the given rule
+ * highly optimized to return the fastest solution.
+ *
+ * @param parsed A tuple [a, b], as returned by `parse`.
+ * @returns A highly optimized function that returns whether an index matches the nth-check.
+ * @example
+ * const check = nthCheck.compile([2, 3]);
+ *
+ * check(0); // `false`
+ * check(1); // `false`
+ * check(2); // `true`
+ * check(3); // `false`
+ * check(4); // `true`
+ * check(5); // `false`
+ * check(6); // `true`
+ */
+export function compile(
+    parsed: [a: number, b: number]
+): (index: number) => boolean {
+    const a = parsed[0];
+    // Subtract 1 from `b`, to convert from one- to zero-indexed.
+    const b = parsed[1] - 1;
+
+    /*
+     * When `b <= 0`, `a * n` won't be lead to any matches for `a < 0`.
+     * Besides, the specification states that no elements are
+     * matched when `a` and `b` are 0.
+     *
+     * `b < 0` here as we subtracted 1 from `b` above.
+     */
+    if (b < 0 && a <= 0) return falseFunc;
+
+    // When `a` is in the range -1..1, it matches any element (so only `b` is checked).
+    if (a === -1) return (index) => index <= b;
+    if (a === 0) return (index) => index === b;
+    // When `b <= 0` and `a === 1`, they match any element.
+    if (a === 1) return b < 0 ? trueFunc : (index) => index >= b;
+
+    /*
+     * Otherwise, modulo can be used to check if there is a match.
+     *
+     * Modulo doesn't care about the sign, so let's use `a`s absolute value.
+     */
+    const absA = Math.abs(a);
+    // Get `b mod a`, + a if this is negative.
+    const bMod = ((b % absA) + absA) % absA;
+
+    return a > 1
+        ? (index) => index >= b && index % absA === bMod
+        : (index) => index <= b && index % absA === bMod;
+}

parse.js

@@ -0,0 +1,4 @@
+declare module "boolbase" {
+    export function trueFunc(...args: unknown[]): true;
+    export function falseFunc(...args: unknown[]): false;
+}

src/__fixtures__/rules.ts

@@ -0,0 +1,31 @@
+import { parse } from "./parse";
+import { compile } from "./compile";
+
+export { parse, compile };
+
+/**
+ * Parses and compiles a formula to a highly optimized function.
+ * Combination of `parse` and `compile`.
+ *
+ * If the formula doesn't match any elements,
+ * it returns [`boolbase`](https://github.com/fb55/boolbase)'s `falseFunc`.
+ * Otherwise, a function accepting an _index_ is returned, which returns
+ * whether or not the passed _index_ matches the formula.
+ *
+ * Note: The nth-rule starts counting at `1`, the returned function at `0`.
+ *
+ * @param formula The formula to compile.
+ * @example
+ * const check = nthCheck("2n+3");
+ *
+ * check(0); // `false`
+ * check(1); // `false`
+ * check(2); // `true`
+ * check(3); // `false`
+ * check(4); // `true`
+ * check(5); // `false`
+ * check(6); // `true`
+ */
+export default function nthCheck(formula: string): (index: number) => boolean {
+    return compile(parse(formula));
+}

src/compile.spec.ts

@@ -0,0 +1,16 @@
+import { parse } from "./parse";
+import { valid, invalid } from "./__fixtures__/rules";
+
+describe("parse", () => {
+    it("parse invalid", () => {
+        for (const formula of invalid) {
+            expect(() => parse(formula)).toThrowError(Error);
+        }
+    });
+
+    it("parse valid", () => {
+        for (const [formula, result] of valid) {
+            expect(parse(formula)).toStrictEqual(result);
+        }
+    });
+});

src/compile.ts

@@ -0,0 +1,42 @@
+// Following http://www.w3.org/TR/css3-selectors/#nth-child-pseudo
+
+// [ ['-'|'+']? INTEGER? {N} [ S* ['-'|'+'] S* INTEGER ]?
+const RE_NTH_ELEMENT = /^([+-]?\d*n)?\s*(?:([+-]?)\s*(\d+))?$/;
+
+/**
+ * Parses an expression.
+ *
+ * @throws An `Error` if parsing fails.
+ * @returns An array containing the integer step size and the integer offset of the nth rule.
+ * @example nthCheck.parse("2n+3"); // returns [2, 3]
+ */
+export function parse(formula: string): [a: number, b: number] {
+    formula = formula.trim().toLowerCase();
+
+    if (formula === "even") {
+        return [2, 0];
+    } else if (formula === "odd") {
+        return [2, 1];
+    }
+
+    const parsed = formula.match(RE_NTH_ELEMENT);
+
+    if (!parsed) {
+        throw new Error(`n-th rule couldn't be parsed ('${formula}')`);
+    }
+
+    let a;
+
+    if (parsed[1]) {
+        a = parseInt(parsed[1], 10);
+        if (isNaN(a)) {
+            a = parsed[1].startsWith("-") ? -1 : 1;
+        }
+    } else a = 0;
+
+    const b =
+        (parsed[2] === "-" ? -1 : 1) *
+        (parsed[3] ? parseInt(parsed[3], 10) : 0);
+
+    return [a, b];
+}

src/declarations/boolbase.d.ts

@@ -0,0 +1,5 @@
+{
+    "extends": "./tsconfig.json",
+    "include": ["src", "test"],
+    "exclude": []
+}

src/index.ts

@@ -0,0 +1,38 @@
+{
+    "compilerOptions": {
+        /* Basic Options */
+        "target": "es5" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */,
+        "module": "commonjs" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
+        // "lib": [],                             /* Specify library files to be included in the compilation. */
+        "declaration": true /* Generates corresponding '.d.ts' file. */,
+        "declarationMap": true /* Generates a sourcemap for each corresponding '.d.ts' file. */,
+        // "sourceMap": true,                     /* Generates corresponding '.map' file. */
+        "outDir": "lib" /* Redirect output structure to the directory. */,
+        // "importHelpers": true,                 /* Import emit helpers from 'tslib'. */
+
+        /* Strict Type-Checking Options */
+        "strict": true /* Enable all strict type-checking options. */,
+
+        /* Additional Checks */
+        "noUnusedLocals": true /* Report errors on unused locals. */,
+        "noUnusedParameters": true /* Report errors on unused parameters. */,
+        "noImplicitReturns": true /* Report error when not all code paths in function return a value. */,
+        "noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */,
+
+        /* Module Resolution Options */
+        "baseUrl": "./" /* Base directory to resolve non-absolute module names. */,
+        "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+        "resolveJsonModule": true,
+
+        "paths": {
+            "*": ["src/declarations/*", "*"]
+        }
+    },
+    "include": ["src"],
+    "exclude": [
+        "**/*.spec.ts",
+        "**/__fixtures__/*",
+        "**/__tests__/*",
+        "**/__snapshots__/*"
+    ]
+}