feat: compile as ES Module (#431)

* feat: compile as ES Module

* update CI workflows to newer node

* release workflow to newer node

* update yarn version to 3.3.1

* explicitly set yarnPath

* fix: frozen-lockfile to immutable

* replace isomorphic-fetch with cross-fetch

* fix: done() called only once

* update jest + fix a few tests

* Add .js to local imports as per https://github.com/microsoft/TypeScript/issues/16577\#issuecomment-754941937

* prettier write

* example for adding it in the browser

* github workflows to one version (hashes may change when changing node version, due to yarn patches)

* update package.json

* Update yarn lock

* fix: graphql subscription tests don't leak handles

* Node tests for graphql subscriptions are now working

* Don't try to make WebSocket tests work in two environments

After struggling for a long while with trying to "shim" isomorphic-ws
to work normally in a jest environment, it is easier to just run this
test only in a Node environment.

Here are the issues why this test fails in JSDOM:

1. Imports fail

The statement `import WebSocket from 'isomorphic-ws';` is passed to the
Jest module resolver, which utilises `ts-jest-resolver` (in our case) to
find the right file to load. Sadly, it will always load the "main"
module of a node package.

2. isomorphic-ws "browser" option is ESM for some reason

If we use jest.config.cjs "resolver" field [1] to define a custom script,
we will be able to modify the "main" field by patching package.json in
memory. This works fine, however isomorphic-ws's browser version is an
ES Module for some reason, even if the package.json > "type" is
"commonjs".

3. Something inside jest doesn't want me to hack it to support ESM

If I override the package.json even harder to also change the "type" to
"module" just for isomorphic-ws, Jest doesn't respect it

4. ts-jest doesn't want to change the ESM imports to CJS imports

Since... we told it to not change ESM imports to CJS imports, it will
not.

[1]: https://jestjs.io/docs/configuration#resolver-string

* prettier write

* follow flags in tsconfig

---------

Co-authored-by: karl <[email protected]>

Author: Johannes Kadak

.eslintrc.json

@@ -2,15 +2,34 @@
   "env": {
     "browser": true
   },
-  "extends": ["eslint:recommended", "@qminder", "prettier"],
+  "plugins": ["import", "@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "prettier",
+    "plugin:import/recommended",
+    "plugin:import/typescript"
+  ],
+  "parser": "@typescript-eslint/parser",
   "parserOptions": {
+    "ecmaVersion": 2020,
     "sourceType": "module"
   },
+  "settings": {
+    "import/resolver": {
+      "typescript": {}
+    }
+  },
+  "rules": {
+    "import/namespace": "off",
+    "no-unused-vars": "off",
+    "import/no-named-as-default": "off"
+  },
   "overrides": [
     {
-      "files": ["*.test.ts"],
+      "files": ["*.test.ts", "test/unit/jestSetupFile.ts"],
       "env": {
-        "jest": true
+        "jest": true,
+        "node": true
       },
       "rules": {
         "func-names": "off"

.gitattributes

@@ -0,0 +1,2 @@
+.yarn/releases/*.cjs binary
+.yarn/plugins/@yarnpkg/*.cjs binary

.github/workflows/code-coverage.yml

@@ -10,8 +10,9 @@ jobs:
       - uses: actions/checkout@master
       - uses: actions/setup-node@v3
         with:
-          node-version: 14.x
-      - run: yarn install --frozen-lockfile
+          node-version: 16.x
+          cache: 'yarn'
+      - run: yarn install --immutable
       - run: yarn jest --coverage
       - uses: codecov/codecov-action@v3
         with:

.github/workflows/push.yml

@@ -2,43 +2,71 @@ on: push
 name: Test on push
 jobs:
   test:
-    strategy:
-      matrix:
-        node-version: [12.x, 14.x, 15.x, 16.x]
-    name: Test on NodeJS ${{ matrix.node-version }}
+    name: Test (JSDOM)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@master
       - uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 16.x
+          cache: 'yarn'
       - name: Install Deps
-        run: yarn install --frozen-lockfile
+        run: yarn install --immutable
       - name: Run tests (browser)
         run: yarn test
+  test_node:
+    name: Test (Node.js)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'yarn'
+      - name: Install Deps
+        run: yarn install --immutable
       - name: Run tests (node)
         run: yarn test-node
+  test_pack:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'yarn'
+      - name: Install Deps
+        run: yarn install --immutable
       - name: Build the package
         run: yarn pack
   prettier:
     name: Check prettier
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@master
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'yarn'
       - name: Install Deps
         run: |
-          yarn install --frozen-lockfile
+          yarn install --immutable
       - name: Prettier check
         run: |
           yarn run lint-prettier
   eslint:
     name: Check eslint
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@master
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16.x
+          cache: 'yarn'
       - name: Install Deps
         run: |
-          yarn install --frozen-lockfile
+          yarn install --immutable
       - name: Eslint check
         run: |
           yarn run lint-eslint

.github/workflows/release.yml

@@ -12,11 +12,12 @@ jobs:
       - uses: actions/checkout@master
       - uses: actions/setup-node@v3
         with:
-          node-version: 12.x
+          node-version: 16.x
+          cache: 'yarn'
           always-auth: true
           registry-url: https://registry.npmjs.org
       - name: Install Deps
-        run: yarn install --frozen-lockfile --ignore-scripts
+        run: yarn install --immutable --ignore-scripts
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       - name: Build Library

.gitignore

@@ -34,3 +34,10 @@ graphql.config.json
 .idea
 
 build
+
+.yarn/*
+!.yarn/releases
+!.yarn/plugins
+!.yarn/sdks
+!.yarn/versions
+.pnp.*

.yarn/releases/yarn-3.3.1.cjs

@@ -0,0 +1,2 @@
+nodeLinker: node-modules
+yarnPath: .yarn/releases/yarn-3.3.1.cjs

.yarnrc.yml

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Qminder API in browser</title>
+  </head>
+  <body>
+    <label for="apikey">API key:</label><input type="password" id="apikey" />
+    <button id="load-button">Load locations</button>
+    <div id="output"></div>
+    <script type="module" src="dist/main.out.js"></script>
+  </body>
+</html>

examples/browser/index.html

@@ -0,0 +1,15 @@
+import * as Qminder from '../../build/qminder-api.js';
+
+const buttonEl = document.getElementById('load-button');
+const outputEl = document.getElementById('output');
+const apiKeyEl = document.getElementById('apikey');
+
+buttonEl.addEventListener('click', async () => {
+  Qminder.setKey(apiKeyEl.value);
+  const locations = await Qminder.locations.list();
+  for (const location of locations) {
+    const div = document.createElement('div');
+    div.textContent = location.name;
+    outputEl.appendChild(div);
+  }
+});

examples/browser/main.js

@@ -0,0 +1,7 @@
+export default {
+  mode: 'production',
+  entry: './main.js',
+  output: {
+    filename: '[name].out.js',
+  },
+};

examples/browser/webpack.config.js

@@ -1,5 +1,6 @@
 module.exports = {
-  preset: 'ts-jest',
+  preset: 'ts-jest/presets/default-esm',
+  resolver: 'ts-jest-resolver',
   testEnvironment: 'jsdom',
   setupFilesAfterEnv: ['jest-sinon', '<rootDir>/test/unit/jestSetupFile.ts'],
   moduleFileExtensions: ['js', 'ts'],

jest.config.js renamed to jest.config.cjs

@@ -26,43 +26,53 @@
   "bugs": "https://github.com/Qminder/javascript-api/issues",
   "author": "Qminder <[email protected]> (https://www.qminder.com)",
   "license": "Apache-2.0",
+  "type": "module",
   "engines": {
-    "node": ">=10.0"
+    "node": ">=14.0"
   },
   "browserslist": [
     "last 2 major versions"
   ],
+  "exports": {
+    ".": {
+      "import": "./build/qminder-api.js",
+      "types": "./build/qminder-api.d.ts"
+    }
+  },
   "main": "build/qminder-api.js",
-  "types": "build/qminder-api.d.ts",
   "repository": "Qminder/javascript-api",
   "devDependencies": {
     "@babel/core": "7.20.12",
     "@babel/preset-env": "7.20.2",
-    "@qminder/eslint-config": "0.0.3",
     "@types/jest": "26.0.24",
     "@types/node": "18.11.18",
     "@types/sinon": "10.0.13",
-    "@typescript-eslint/eslint-plugin": "4.33.0",
-    "@typescript-eslint/parser": "4.33.0",
-    "eslint": "7.32.0",
+    "@typescript-eslint/eslint-plugin": "^5.49.0",
+    "@typescript-eslint/parser": "^5.49.0",
+    "eslint": "^8.32.0",
     "eslint-config-prettier": "8.6.0",
-    "eslint-plugin-import": "2.27.5",
-    "jest": "26.6.3",
+    "eslint-import-resolver-typescript": "^3.5.3",
+    "eslint-plugin-import": "^2.27.5",
+    "graphql": "15.8.0",
+    "graphql-tag": "2.12.6",
+    "jest": "^29.4.0",
+    "jest-environment-jsdom": "^29.4.0",
     "jest-sinon": "1.0.4",
     "prettier": "2.8.3",
     "rxjs": "7.8.0",
     "sinon": "15.0.1",
-    "ts-jest": "26.5.6",
+    "ts-jest": "^29.0.5",
+    "ts-jest-resolver": "^2.0.0",
+    "ts-loader": "^9.4.2",
     "typedoc": "0.22.17",
     "typescript": "4.9.5",
-    "graphql": "15.8.0",
-    "graphql-tag": "2.12.6"
+    "webpack": "^5.75.0",
+    "webpack-cli": "^5.0.1"
   },
   "dependencies": {
-    "@types/isomorphic-fetch": "^0.0.36",
     "@types/ws": "^8.0.0",
+    "cross-fetch": "^3.1.5",
     "es6-promise": "^4.1.1",
-    "isomorphic-fetch": "^3.0.0",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.0.0"
   },
@@ -74,5 +84,6 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
-  }
+  },
+  "packageManager": "[email protected]"
 }

package.json

@@ -6,4 +6,4 @@ set -e
 #
 
 rm -rf build
-tsc --declaration --outDir build --module commonjs --target es2017 --moduleResolution node --esModuleInterop true ./src/qminder-api.ts
+yarn run tsc -p .

scripts/build.sh

@@ -1,6 +1,6 @@
-import fetch from 'isomorphic-fetch';
-import { GraphQLApiError } from './util/errors';
-import { ClientError } from './model/ClientError';
+import fetch from 'cross-fetch';
+import { GraphQLApiError } from './util/errors.js';
+import { ClientError } from './model/ClientError.js';
 
 type HTTPMethod =
   | 'GET'
@@ -139,9 +139,6 @@ class ApiBase {
    */
   constructor() {
     this.fetch = fetch;
-    if (typeof (fetch as any).default === 'function') {
-      this.fetch = (fetch as any).default as Function;
-    }
     this.setServer('api.qminder.com');
   }
 

src/api-base.ts

@@ -1,4 +1,4 @@
-import Location from './Location';
+import Location from './Location.js';
 /**
  * Represents a single user picture.
  * The 'medium' sized user picture is available if the user has an image.

src/model/User.ts

@@ -1,4 +1,4 @@
-import { ID } from './ID';
+import { ID } from './ID.js';
 /**
  * A Webhook is a URL that Qminder sends automatic POST requests into, in order to notify
  * downstream listeners about various events such as ticket creation or location changes.

src/model/Webhook.ts

@@ -1,22 +1,22 @@
 // Import data structures
-import Desk from './model/Desk';
-import Device from './model/Device';
-import Line from './model/Line';
-import Location from './model/Location';
-import Ticket from './model/Ticket';
-import User from './model/User';
-import Webhook from './model/Webhook';
-import { ClientError } from './model/ClientError';
+import Desk from './model/Desk.js';
+import Device from './model/Device.js';
+import Line from './model/Line.js';
+import Location from './model/Location.js';
+import Ticket from './model/Ticket.js';
+import User from './model/User.js';
+import Webhook from './model/Webhook.js';
+import { ClientError } from './model/ClientError.js';
 
 // Import services
-import ApiBase from './api-base';
-import DeviceService from './services/DeviceService';
-import LineService from './services/LineService';
-import LocationService from './services/LocationService';
-import TicketService from './services/TicketService';
-import UserService from './services/UserService';
-import WebhooksService from './services/WebhooksService';
-import GraphQLService, { ConnectionStatus } from './services/GraphQLService';
+import ApiBase from './api-base.js';
+import DeviceService from './services/DeviceService.js';
+import LineService from './services/LineService.js';
+import LocationService from './services/LocationService.js';
+import TicketService from './services/TicketService.js';
+import UserService from './services/UserService.js';
+import WebhooksService from './services/WebhooksService.js';
+import GraphQLService, { ConnectionStatus } from './services/GraphQLService.js';
 
 // Export all data structures
 export {

src/qminder-api.ts

@@ -1,6 +1,6 @@
-import ApiBase from '../api-base';
-import Device from '../model/Device';
-import { extractId, IdOrObject } from '../util/id-or-object';
+import ApiBase from '../api-base.js';
+import Device from '../model/Device.js';
+import { extractId, IdOrObject } from '../util/id-or-object.js';
 
 /**
  * DeviceService allows the developer to manage devices such as iPads that have the Qminder