ESM support & various other compat improvements (#100)

* update eslint config

* run eslint --fix + fix other linting issues

* added & fixed consistent-type-* lints

* migrated source code to esm

* made tests run using tsx/esm import

* removed hard unstable dep on fetch-h2... now defaults to plain fetch by default

* removed hard unstable dep on events... now uses minimal event emitter implementaiton

* added dual support for cjs & esm

* use tslib

* update examples to work with latest version of astra-db-ts

* fixed node10 & node16:cjs type resolution issues

* update examples to reflect new compat changes

* update some http options documentation

* update readme

Author: toptobes

README.md

@@ -14,10 +14,10 @@
 - [High-level architecture](#high-level-architecture)
   - [Options hierarchy](#options-hierarchy)
 - [Datatypes](#datatypes)
-[Non-astra support](#non-astra-support)
-- [Non-standard environment support](#non-standard-environment-support)
-  - [HTTP/2 with minification](#http2-with-minification)
-  - [Browser support](#browser-support)
+- [Non-astra support](#non-astra-support)
+- [Browser support](#browser-support)
+- [Using HTTP/2](#using-http2)
+- [Examples](#examples)
 
 ## Quickstart
 
@@ -315,78 +315,43 @@ as necessary, depending on the Data API backend. Tokens may even be omitted if n
 
 (See `examples/non-astra-backends` for a full example of this in action.)
 
-## Non-standard environment support
+## Browser support
 
-`astra-db-ts` is designed first and foremost to work in Node.js environments. 
-
-However, it will work in edge runtimes and other non-node environments as well, though it may use the native `fetch` API for HTTP
-requests, as opposed to `fetch-h2` which provides extended HTTP/2 and HTTP/1.1 support for performance.
-
-By default, it'll attempt to use `fetch-h2` if available, and fall back to `fetch` if not available in that environment.
-You can explicitly force the fetch implementation when instantiating the client:
+`astra-db-ts` is designed to work in server-side environments, but it can technically work in the browser as well.
 
-```typescript
-import { DataAPIClient } from '@datastax/astra-db-ts';
+However, if, for some reason, you really want to use this in a browser, you may need to install the `events` polyfill,
+and possibly set up a CORS proxy (such as [CORS Anywhere](https://github.com/Rob--W/cors-anywhere)) to forward requests to the Data API.
 
-const client = new DataAPIClient('*TOKEN*', {
-  httpOptions: { client: 'fetch' },
-});
-```
+But keep in mind that this may be very insecure, especially if you're hardcoding sensitive data into your client-side
+code, as it's trivial for anyone to inspect the code and extract the token (through XSS attacks or otherwise).
 
-There are four different behaviours for setting the client:
-- Not setting the `httpOptions` at all
-  - This will attempt to use `fetch-h2` if available, and fall back to `fetch` if not available
-- `client: 'default'` or `client: undefined` (or unset)
-  - This will attempt to use `fetch-h2` if available, and throw an error if not available
-- `client: 'fetch'`
-  - This will always use the native `fetch` API
-- `client: 'custom'`
-  - This will allow you to pass a custom `Fetcher` implementation to the client
+See [`examples/browser`](./examples/browser) for a full example of browser usage in action, and steps on how to use `astra-db-ts` in your own browser application.
 
-On some environments, such as Cloudflare Workers, you may additionally need to use the events
-polyfill for the client to work properly (i.e. `npm i events`). Cloudflare's node-compat won't
-work here.
+## Using HTTP/2
 
-Check out the `examples/` subdirectory for some non-standard runtime examples with more info.
+`astra-db-ts` uses the native `fetch` API by default, but it can also work with `HTTP/2` using the `fetch-h2` module.
 
-### HTTP/2 with minification
+However, due to compatability reasons, `fetch-h2` is no longer dynamically imported by default, and must be provided to the client manually.
 
-Due to the variety of different runtimes JS can run in, `astra-db-ts` does its best to be as flexible as possible.
-Unfortunately however, because we need to dynamically require the `fetch-h2` module to test whether it works, the
-dynamic import often breaks in minified environments, even if the runtime properly supports HTTP/2.
+Luckily, it is only a couple of easy steps to get `HTTP/2` working in your project:
 
-There is a simple workaround however, consisting of the following steps, if you really want to use HTTP/2:
-1. Install `fetch-h2` as a dependency (`npm i fetch-h2`)
-2. Import the `fetch-h2` module in your code as `fetchH2` (i.e. `import * as fetchH2 from 'fetch-h2'`)
-3. Set the `httpOptions.fetchH2` option to the imported module when instantiating the client
+1. Install `fetch-h2` by running `npm i fetch-h2`.
+2. Provide `fetch-h2` to the client.
 
-```typescript
-import { DataAPIClient } from '@datastax/astra-db-ts';
+```ts
 import * as fetchH2 from 'fetch-h2';
+// or `const fetchH2 = require('fetch-h2');`
 
-const client = new DataAPIClient('*TOKEN*', {
-  httpOptions: { fetchH2 },
+const client = new DataAPIClient({
+  httpOptions: {
+    client: 'fetch-h2',
+    fetchH2: fetchH2,
+  },
 });
 ```
 
-This way, the dynamic import is avoided, and the client will work in minified environments.
-
-Note this is not required if you don't explicitly need HTTP/2 support, as the client will default 
-to the native fetch implementation instead if importing fails. 
-
-(But keep in mind this defaulting will only happen if `httpOptions` is not set at all).
+See the [using HTTP/2 example](./examples/using-http2) for a full example of this in action, and more information on how to use `astra-db-ts` with `HTTP/2`.
 
-(See `examples/http2-when-minified` for a full example of this workaround in action.)
-
-### Browser support
-
-`astra-db-ts` is designed to work in server-side environments, but it can technically work in the browser as well.
-
-However, if, for some reason, you really want to use this in a browser, you may need to install the `events` polyfill,
-and possibly set up a CORS proxy (such as [CORS Anywhere](https://github.com/Rob--W/cors-anywhere)) to forward requests 
-to the Data API.
-
-But keep in mind that this may be very insecure, especially if you're hardcoding sensitive data into your client-side
-code, as it's trivial for anyone to inspect the code and extract the token (through XSS attacks or otherwise).
+## Examples
 
-(See `examples/browser` for a full example of browser usage in action.)
+Check out the [examples](./examples) directory for more examples on how to use `astra-db-ts` in your own projects.

api-extractor.jsonc

@@ -45,7 +45,7 @@
    *
    * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
    */
-  "mainEntryPointFilePath": "dist/index.d.ts",
+  "mainEntryPointFilePath": "dist/esm/index.d.ts",
 
   /**
    * A list of NPM package names whose exports should be treated as part of this package.
@@ -110,7 +110,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
      */
-//     "tsconfigFilePath": "tsconfig.build.json",
+     "tsconfigFilePath": "<projectFolder>/etc/tsconfig.esm.json"
     /**
      * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
      * The object must conform to the TypeScript tsconfig schema:

eslint.config.mjs

@@ -6,23 +6,39 @@ import ts from 'typescript-eslint';
 
 export default ts.config(
   {
-    ignores: ['dist/**/*', 'examples/**/*'],
-  },
-  js.configs.recommended,
-  ...ts.configs.recommended,
-  {
+    files: ['src/**/*.ts', 'tests/**/*.ts'],
+    extends: [
+      js.configs.recommended,
+      ...ts.configs.recommendedTypeChecked,
+      ...ts.configs.stylisticTypeChecked,
+    ],
     languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
       globals: globals.node,
     },
     rules: {
       // We are *way* past this point lmao
       '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
 
       // Only way I can do indentation in ts-doc
       'no-irregular-whitespace': 'off',
 
-      // sorry.
+      // no.
+      '@typescript-eslint/restrict-template-expressions': 'off',
+
+      // sorry :(
       '@typescript-eslint/no-unused-expressions': 'off',
+      '@typescript-eslint/consistent-type-assertions': 'off',
+      '@typescript-eslint/prefer-nullish-coalescing': 'off',
+      '@typescript-eslint/no-empty-function': 'off',
 
       // Makes underscore variables not throw a fit
       '@typescript-eslint/no-unused-vars': ['error', {
@@ -40,10 +56,22 @@ export default ts.config(
       // Linting
       'semi': 'error',
       'comma-dangle': ['error', 'always-multiline'],
+
+      '@typescript-eslint/consistent-type-exports': 'error',
+      '@typescript-eslint/consistent-type-imports': 'error',
+    },
+  },
+  {
+    // Laxer rules for test files
+    files: ['tests/**/*.ts'],
+    rules: {
+      '@typescript-eslint/no-magic-numbers': 'off',
+      '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/no-implied-eval': 'off',
     },
   },
   {
-    // disable type-aware linting on JS files
+    // Disable type-aware linting on JS files
     files: ['**/*.*js'],
     ...ts.configs.disableTypeChecked,
     rules: { 'no-undef': 'off' },