feat/migrate to esm only with shared tsconfig (#21)

* chore: add vitest.config.ts with snapshotFormat

Prevent truncation of large snapshots by setting
`snapshotFormat.maxOutputLength` to `Number.MAX_SAFE_INTEGER`.

* chore: migrate typedoc workflow to shared reusable workflow

Replace the hand-written TypeDoc deploy steps with the shared
`zakodium/workflows/.github/workflows/typedoc.yml@typedoc-v1`
reusable workflow.

* chore: ignore .claude in .gitignore

* test: flatten tests to top-level test() calls

Remove the outer `describe` wrappers that only mirrored the filename
and switch from `it` to `test` so each assertion sits at the top level
of its file.

* feat!: migrate package to ESM TypeScript

- Set `"type": "module"` and replace `"main"` / `"module"` / `"types"`
  with a single `"exports"` entry
- Drop the CJS dual-build; single `lib/` output via tsconfig.build.json
- Extend `@zakodium/tsconfig` and pin TypeScript to 5.x
- Local imports use `.ts` extensions; types use `import type`
- Add `override` modifier in test subclass
- Drop `lib-esm` from .gitignore and from eslint ignores

BREAKING CHANGE: package is now ESM-only; consumers using
require() must migrate to import, or run Node.js >= 20.19,
>= 22.12, or any 24.x or later.

* chore: address feedback

* chore: fix typescript

Author: lpatiny

.github/workflows/typedoc.yml

@@ -1,32 +1,15 @@
-name: Deploy TypeDoc on GitHub pages
+name: TypeDoc
 
 on:
   workflow_dispatch:
   release:
     types: [published]
 
-env:
-  NODE_VERSION: 20.x
-  ENTRY_FILE: 'src/index.ts'
-
 jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-      - name: Install dependencies
-        run: npm install
-      - name: Build documentation
-        uses: zakodium/typedoc-action@v2
-        with:
-          entry: ${{ env.ENTRY_FILE }}
-      - name: Deploy to GitHub pages
-        uses: JamesIves/github-pages-deploy-action@releases/v4
-        with:
-          token: ${{ secrets.BOT_TOKEN }}
-          branch: gh-pages
-          folder: docs
-          clean: true
+  typedoc:
+    # Documentation: https://github.com/zakodium/workflows#typedoc
+    uses: zakodium/workflows/.github/workflows/typedoc.yml@typedoc-v1
+    with:
+      entry: 'src/index.ts'
+    secrets:
+      github-token: ${{ secrets.BOT_TOKEN }}

.gitignore

@@ -37,6 +37,5 @@ jspm_packages
 .node_repl_history
 
 lib
-
-lib-esm
 docs
+.claude

eslint.config.mjs

@@ -1,4 +1,4 @@
 import { defineConfig, globalIgnores } from 'eslint/config';
 import ts from 'eslint-config-cheminfo-typescript/base';
 
-export default defineConfig(globalIgnores(['coverage', 'lib', 'lib-esm']), ts);
+export default defineConfig(globalIgnores(['coverage', 'lib']), ts);

package.json

@@ -2,28 +2,27 @@
   "name": "ml-regression-base",
   "version": "4.0.1",
   "description": "Base class for regression modules",
-  "main": "./lib/index.js",
-  "module": "./lib-esm/index.js",
-  "types": "./lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
   "sideEffects": false,
   "files": [
-    "src",
     "lib",
-    "lib-esm"
+    "src"
   ],
   "scripts": {
     "check-types": "tsc --noEmit",
-    "clean": "rimraf lib lib-esm",
+    "clean": "rimraf lib",
     "eslint": "eslint src",
     "eslint-fix": "npm run eslint -- --fix",
     "prepack": "npm run tsc",
     "prettier": "prettier --check src",
     "prettier-write": "prettier --write src",
-    "test": "npm run test-only && npm run eslint && npm run prettier && npm run check-types",
+    "test": "npm run test-only && npm run check-types && npm run eslint && npm run prettier",
     "test-only": "vitest run --coverage",
-    "tsc": "npm run clean && npm run tsc-cjs && npm run tsc-esm",
-    "tsc-cjs": "tsc --project tsconfig.cjs.json",
-    "tsc-esm": "tsc --project tsconfig.esm.json"
+    "tsc": "npm run clean && npm run tsc-build",
+    "tsc-build": "tsc --project tsconfig.build.json"
   },
   "repository": {
     "type": "git",
@@ -41,7 +40,9 @@
     "is-any-array": "^3.0.0"
   },
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
+    "@zakodium/tsconfig": "^1.0.5",
     "eslint": "^9.39.4",
     "eslint-config-cheminfo-typescript": "^22.0.0",
     "prettier": "^3.8.3",

src/BaseRegression.ts

@@ -1,14 +1,15 @@
 import type { NumberArray } from 'cheminfo-types';
 import { isAnyArray } from 'is-any-array';
 
-import { checkArrayLength } from './checkArrayLength';
+import { checkArrayLength } from './checkArrayLength.ts';
 
 export interface RegressionScore {
   r: number;
   r2: number;
   chi2: number;
   rmsd: number;
 }
+
 export class BaseRegression {
   constructor() {
     if (new.target === BaseRegression) {
@@ -55,15 +56,15 @@ export class BaseRegression {
    * Return the correlation coefficient of determination (r) and chi-square.
    * @param x - explanatory variable
    * @param y - response variable
-   * @return - Object with further statistics.
+   * @returns Object with further statistics.
    */
   score(x: NumberArray, y: NumberArray): RegressionScore {
     checkArrayLength(x, y);
 
     const n = x.length;
     const y2: number[] = new Array(n);
     for (let i = 0; i < n; i++) {
-      y2[i] = this._predict(x[i]);
+      y2[i] = this._predict(x[i] as number);
     }
 
     let xSum = 0;
@@ -74,15 +75,17 @@ export class BaseRegression {
     let ySquared = 0;
     let xY = 0;
     for (let i = 0; i < n; i++) {
-      xSum += y2[i];
-      ySum += y[i];
-      xSquared += y2[i] * y2[i];
-      ySquared += y[i] * y[i];
-      xY += y2[i] * y[i];
-      if (y[i] !== 0) {
-        chi2 += ((y[i] - y2[i]) * (y[i] - y2[i])) / y[i];
+      const yi = y[i] as number;
+      const y2i = y2[i] as number;
+      xSum += y2i;
+      ySum += yi;
+      xSquared += y2i * y2i;
+      ySquared += yi * yi;
+      xY += y2i * yi;
+      if (yi !== 0) {
+        chi2 += ((yi - y2i) * (yi - y2i)) / yi;
       }
-      rmsd += (y[i] - y2[i]) * (y[i] - y2[i]);
+      rmsd += (yi - y2i) * (yi - y2i);
     }
 
     const r =

src/__tests__/BaseRegression.test.ts

@@ -1,6 +1,6 @@
-import { describe, expect, it } from 'vitest';
+import { expect, test } from 'vitest';
 
-import { BaseRegression } from '..';
+import { BaseRegression } from '../index.ts';
 
 class NoPredict extends BaseRegression {}
 class Basic extends BaseRegression {
@@ -9,82 +9,86 @@ class Basic extends BaseRegression {
     super();
     this.factor = factor;
   }
-  _predict(x: number) {
+  override _predict(x: number) {
     return x * this.factor;
   }
 }
 
-describe('base regression', () => {
-  it('should not be directly constructable', () => {
-    expect(() => {
-      // eslint-disable-next-line no-new
-      new BaseRegression();
-    }).toThrow(/BaseRegression must be subclassed/);
-  });
+test('should not be directly constructable', () => {
+  expect(() => {
+    // eslint-disable-next-line no-new
+    new BaseRegression();
+  }).toThrow(/BaseRegression must be subclassed/);
+});
 
-  it('should throw if _predict is not implemented', () => {
-    const reg = new NoPredict();
-    expect(() => {
-      reg.predict(0);
-    }).toThrow(/_predict must be implemented/);
-  });
+test('should throw if _predict is not implemented', () => {
+  const reg = new NoPredict();
 
-  it('should do a basic prediction', () => {
-    const basic = new Basic(2);
-    expect(basic.predict(1)).toBe(2);
-    expect(basic.predict(2)).toBe(4);
-    expect(basic.predict([2, 3])).toStrictEqual([4, 6]);
-  });
+  expect(() => {
+    reg.predict(0);
+  }).toThrow(/_predict must be implemented/);
+});
+
+test('should do a basic prediction', () => {
+  const basic = new Basic(2);
+
+  expect(basic.predict(1)).toBe(2);
+  expect(basic.predict(2)).toBe(4);
+  expect(basic.predict([2, 3])).toStrictEqual([4, 6]);
+});
+
+test('should throw on invalid value', () => {
+  const basic = new Basic(2);
 
-  it('should throw on invalid value', () => {
-    const basic = new Basic(2);
-    expect(() => {
-      // @ts-expect-error testing invalid input
-      basic.predict();
-    }).toThrow(/must be a number or array/);
+  expect(() => {
+    // @ts-expect-error testing invalid input
+    basic.predict();
+  }).toThrow(/must be a number or array/);
+});
+
+test('should implement dummy predictor functions', () => {
+  const basic = new Basic(2);
+  basic.train(); // should not throw
+
+  expect(basic.toString()).toBe('');
+  expect(basic.toLaTeX()).toBe('');
+});
+
+test('should implement a scoring function', () => {
+  const basic = new Basic(2);
+
+  expect(basic.score([1, 2], [2, 4])).toStrictEqual({
+    r: 1,
+    r2: 1,
+    chi2: 0,
+    rmsd: 0,
   });
+  expect(basic.score([1, 2], [2, 4.1]).rmsd).toBe(0.0707106781186545);
 
-  it('should implement dummy predictor functions', () => {
-    const basic = new Basic(2);
-    basic.train(); // should not throw
-    expect(basic.toString()).toBe('');
-    expect(basic.toLaTeX()).toBe('');
+  expect(basic.score([1, 2], [0.5, 2])).toStrictEqual({
+    r: 1,
+    r2: 1,
+    chi2: 6.5,
+    rmsd: 1.7677669529663689,
   });
 
-  it('should implement a scoring function', () => {
-    const basic = new Basic(2);
-    expect(basic.score([1, 2], [2, 4])).toStrictEqual({
-      r: 1,
-      r2: 1,
-      chi2: 0,
-      rmsd: 0,
-    });
-    expect(basic.score([1, 2], [2, 4.1]).rmsd).toBe(0.0707106781186545);
-
-    expect(basic.score([1, 2], [0.5, 2])).toStrictEqual({
-      r: 1,
-      r2: 1,
-      chi2: 6.5,
-      rmsd: 1.7677669529663689,
-    });
-
-    expect(basic.score([1, 2], [0, 1])).toStrictEqual({
-      r: 1,
-      r2: 1,
-      chi2: 9,
-      rmsd: 2.5495097567963922,
-    });
+  expect(basic.score([1, 2], [0, 1])).toStrictEqual({
+    r: 1,
+    r2: 1,
+    chi2: 9,
+    rmsd: 2.5495097567963922,
   });
+});
 
-  it('should throw error if inputs are not arrays or has different length', () => {
-    const basic = new Basic(2);
-    expect(() => {
-      // @ts-expect-error testing invalid input
-      basic.score(1, 2);
-    }).toThrow('x and y must be arrays');
+test('should throw error if inputs are not arrays or has different length', () => {
+  const basic = new Basic(2);
 
-    expect(() => {
-      basic.score([1, 2], [2]);
-    }).toThrow('x and y arrays must have the same length');
-  });
+  expect(() => {
+    // @ts-expect-error testing invalid input
+    basic.score(1, 2);
+  }).toThrow('x and y must be arrays');
+
+  expect(() => {
+    basic.score([1, 2], [2]);
+  }).toThrow('x and y arrays must have the same length');
 });

src/__tests__/checkArrayLength.test.ts

@@ -1,34 +1,34 @@
-import { describe, expect, it } from 'vitest';
+import { expect, test } from 'vitest';
 
-import { checkArrayLength } from '..';
+import { checkArrayLength } from '../index.ts';
 
-describe('checkArrayLength', () => {
-  it('throws on different Length', () => {
-    const expected = /x and y arrays must have the same length/;
-    expect(() => checkArrayLength([], [1])).toThrow(expected);
-    expect(() => checkArrayLength([1], [])).toThrow(expected);
-    expect(() => checkArrayLength([1], [1, 2])).toThrow(expected);
-  });
+test('throws on different Length', () => {
+  const expected = /x and y arrays must have the same length/;
 
-  it('throws if not arrays', () => {
-    const expected = /x and y must be arrays/;
-    // @ts-expect-error testing invalid input
-    expect(() => checkArrayLength(null, [1])).toThrow(expected);
-    // @ts-expect-error testing invalid input
-    expect(() => checkArrayLength([], null)).toThrow(expected);
-    // @ts-expect-error testing invalid input
-    expect(() => checkArrayLength()).toThrow(expected);
-    // @ts-expect-error testing invalid input
-    expect(() => checkArrayLength(42, [])).toThrow(expected);
-    // @ts-expect-error testing invalid input
-    expect(() => checkArrayLength([1, 2, 3, 4, 5], 'hello')).toThrow(expected);
-  });
+  expect(() => checkArrayLength([], [1])).toThrow(expected);
+  expect(() => checkArrayLength([1], [])).toThrow(expected);
+  expect(() => checkArrayLength([1], [1, 2])).toThrow(expected);
+});
+
+test('throws if not arrays', () => {
+  const expected = /x and y must be arrays/;
+
+  // @ts-expect-error testing invalid input
+  expect(() => checkArrayLength(null, [1])).toThrow(expected);
+  // @ts-expect-error testing invalid input
+  expect(() => checkArrayLength([], null)).toThrow(expected);
+  // @ts-expect-error testing invalid input
+  expect(() => checkArrayLength()).toThrow(expected);
+  // @ts-expect-error testing invalid input
+  expect(() => checkArrayLength(42, [])).toThrow(expected);
+  // @ts-expect-error testing invalid input
+  expect(() => checkArrayLength([1, 2, 3, 4, 5], 'hello')).toThrow(expected);
+});
 
-  it('correct result', () => {
-    expect(checkArrayLength([1, 2], [2, 3])).toBeUndefined();
-    expect(
-      checkArrayLength(new Float64Array([1, 2]), new Float64Array([2, 3])),
-    ).toBeUndefined();
-    expect(checkArrayLength([1, 2], new Float64Array([2, 3]))).toBeUndefined();
-  });
+test('correct result', () => {
+  expect(checkArrayLength([1, 2], [2, 3])).toBeUndefined();
+  expect(
+    checkArrayLength(new Float64Array([1, 2]), new Float64Array([2, 3])),
+  ).toBeUndefined();
+  expect(checkArrayLength([1, 2], new Float64Array([2, 3]))).toBeUndefined();
 });