v1.0.0: Add JS/TS configuration exports; switch Babel plugins

⚠️ BREAKING CHANGES (if using lint rules):
- Transition from deprecated `@babel/plugin-syntax-import-assertions`
  to the new `@babel/plugin-syntax-import-attributes` and enable option
  `deprecatedAssertSyntax` for backward compatibility with import
  assertions. Since this is a peer dependency, consumers must switch
  plugins to match.

🌎 External changes:
- Export JavaScript configuration as `configuration/javascript`.
- Export TypeScript configuration as `configuration/typescript` now that
  microsoft/TypeScript#48665 has been fixed.
- Update README with instructions on how to consume Babel, ESLint,
  JavaScript, rollup.js, and TypeScript configurations.

🏠 Internal changes:
- Clean up `package.json` scripts and remove `engines` field.

🧹 Chores:
- Upgrade dependencies.

Author: nchevsky

README.md

@@ -1,31 +1,112 @@
 # Overview
 
-`bitumen` is a collection of utility classes, types, and opinionated configurations for Babel, ESLint, rollup.js, and TypeScript.
+`bitumen` is a collection of classes, types, utilities, and opinionated configuration for Babel, ESLint, rollup.js, and TypeScript.
 
 # Supported Environments
 
-- Client-side use: Last two versions of Chrome, Edge, Firefox, or Safari
-- Server-side use: Node.js v14+
+- Client side: Last two versions of Chrome, Edge, Firefox (+ ESR), and Safari
+- Server side: Maintained versions of Node.js
 
-# Installation
+# Usage
+
+## Configuration
+
+### Babel
 
-💡 Install the package as a runtime dependency.
+#### Option 1: 📍 `package.json`
 
-```shell
-$ npm install bitumen
+```json
+{
+  "babel": {
+    "extends": "bitumen/configuration/babel"
+  }
+}
 ```
 
-# Usage
+#### Option 2: 📍 `babel.config.cjs`
+
+```js
+const base = require('bitumen/configuration/babel');
+
+module.exports = {
+  ...base,
+  // custom configuration and overrides
+};
+```
+
+### ESLint
+
+📍 `.eslintrc.cjs`
+
+```js
+const base = require('bitumen/configuration/eslint');
+const react = require('bitumen/configuration/eslint-react');
+
+module.exports = {
+  ...base,
+  ...react,
+  // custom configuration and overrides
+};
+```
+
+### rollup.js
+
+📍 `rollup.config.js`
+
+```js
+import configure from 'bitumen/configuration/rollup';
+
+import packageJson from './package.json';
+
+export default configure(packageJson);
+```
+
+`configure()` returns a configuration object which:
+- Reads entry points from `package.json`'s `exports` field (no conditionals, null targets, or patterns).
+- Writes distributable output to `DIST_PATH`, mirroring the directory structure of `BUILD_PATH`.
+- Writes CommonJS modules to `.cjs` files and ES modules to `.js` files.
+- Excludes Jest directories `__mocks__`, `__tests__` from the output.
+- Copies Sass stylesheets (`.scss`) from `SRC_PATH` to `DIST_PATH`.
+- Copies TypeScript type declarations (`.d.ts`) from `BUILD_PATH` to `DIST_PATH`, giving them a `.d.ts` extension for ECMAScript and a `.d.cts` extension for CommonJS.
+
+The following environment variables must be set at runtime:
+
+- `BUILD_PATH`: Where Babel and `tsc` write their `.js` and `.d.ts` files.
+- `DIST_PATH`: Where rollup.js is to write its distributable output.
+- `FORMAT`: Type of modules to output; either _'es'_ (ES) or _'cjs'_ (CommonJS).
+- `SRC_PATH`: Where the original source code is located.
+
+### TypeScript
+
+📍 `jsconfig.json`
+
+```json
+{
+  "extends": "bitumen/configuration/javascript"
+}
+```
+
+📍 `tsconfig.json`
+
+```json
+{
+  "extends": "bitumen/configuration/typescript",
+  // `exclude`, `files`, and `include` paths must be set locally;
+  // see https://github.com/microsoft/TypeScript/issues/45050
+  "include": ["./src/"]
+}
+```
+
+## Library
 
 `bitumen` exposes named exports from the following entry points:
 
 - `collections`
-- `configuration`
 - `mixins`
 - `types`
 - `utils`
 
-For example, to implement the `SortedSet` class from the `collections` entry point:
+For example, to implement `SortedSet` from `collections`:
 ```js
 import {SortedSet} from 'bitumen/collections';
 
@@ -34,12 +115,9 @@ const set = new SortedSet();
 
 # Type Declarations
 
-TypeScript type declarations are included to aid in writing type-safe code—even in JavaScript projects. 🚀
+For proper module and type resolution, use the following project settings:
 
-## Importing in Visual Studio Code
-
-### JavaScript Projects
-📍 `jsconfig.json` (create as needed)
+📍 `jsconfig.json`
 ```jsonc
 {
   "compilerOptions": {
@@ -50,7 +128,6 @@ TypeScript type declarations are included to aid in writing type-safe code—eve
 }
 ```
 
-### TypeScript Projects
 📍 `tsconfig.json`
 ```jsonc
 {
@@ -59,3 +136,5 @@ TypeScript type declarations are included to aid in writing type-safe code—eve
   }
 }
 ```
+
+💡 `bitumen`'s [JavaScript and TypeScript configurations](#typescript) are already set up this way.

babel.config.cjs

@@ -5,10 +5,9 @@
 
 module.exports = {
   plugins: [
-    '@babel/plugin-syntax-import-assertions'
-  ].concat(
-    process.env.ENV == 'jest' ? [['replace-import-extension', {extMapping: {'.js': '', '.jsx': ''}}]] : []
-  ),
+    ['@babel/plugin-syntax-import-attributes', {deprecatedAssertSyntax: true}],
+    process.env.ENV == 'jest' && ['replace-import-extension', {extMapping: {'.js': '', '.jsx': ''}}]
+  ].filter(Boolean),
   presets: [
     ['@babel/preset-env', {
       corejs: 3,
@@ -23,7 +22,7 @@ module.exports = {
       useBuiltIns: 'usage'
     }],
     ['@babel/preset-typescript', {
-      allowDeclareFields: true // will be enabled by default in Babel 8
+      allowDeclareFields: true // TODO: will be enabled by default in Babel 8
     }]
   ]
 };