@checkdigit/typescript-config 3.3.0 → 3.4.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2021-2022 Check Digit, LLC
+Copyright (c) 2021-2023 Check Digit, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,22 +6,78 @@ Copyright (c) 2022-2023 [Check Digit, LLC](https://checkdigit.com)
 
 ### Introduction
 
-This module contains the standard Check Digit Typescript configuration.
+This module contains the standard Check Digit Typescript configuration, along with our standard build tool `builder`.
 
-- requires Node 16 or above
-- emits ES2022
+### Typescript Configuration
+
+- currently requires Node 16 or above.
+- emits `esnext`, with the default libraries, to avoid down-leveling. It is intended that application spec tests pick
+  up any issues with using newer features unavailable in a particular environment. Browsers and NodeJS are fast moving
+  targets, and can add language features at any time.
 - uses the `module` type of `commonjs`.
-- all compiler options set for maximum strictness
+- all compiler options set for maximum strictness.
+
+### Builder
+
+`builder` is a command line tool that generates either commonjs or esm modules, from Typescript source. It is intended
+to be used when publishing a package to NPM, or to bundle a package for deployment. It uses `tsc` for generating
+types, and `esbuild` for generating code.
+
+#### Options
+
+- `--type` the type of module to generate. Defaults to `module` (ESM). Valid values are `commonjs` and `module`.
+- `--entryPoint` the entry point for the bundle, relative to the inDir. if not provided, the files in the inDir will
+  be processed as individual unbundled files.
+- `--inDir` the input source code directory.
+- `--outDir` the output directory.
+- `--outFile` the output file, relative to `--outDir`. This is provided for single-file bundles, along with `--entryPoint`.
+- `--external` external modules to exclude from the bundle. Built-in `node` modules are automatically excluded.
+  A wildcard `*` can be used to exclude multiple external modules.
+- `--minify` whether to minify the output.
+- `--sourceMap` whether to include inline sourcemap.
+
+#### Examples
+
+```
+# build commonjs .cjs files from Typescript source
+npx builder --type=commonjs --outDir=build-cjs
+
+# build single-file commonjs .cjs bundle from Typescript source
+npx builder --type=commonjs --entryPoint=index.ts --outDir=build-cjs-bundle --outFile=index.cjs
+
+# build ESM .mjs files from Typescript source
+npx builder --type=module --outDir=build-esm
+
+# build single-file ESM .mjs bundle from Typescript source
+npx builder --type=module --outDir=build-esm-bundle --entryPoint=index.ts --outFile=index.mjs
+```
+
+### Tests
+
+This module includes a number of integration-style tests, to ensure that a specific version of Typescript will interoperate
+with `builder`, in addition to libraries and frameworks used by Check Digit:
+
+- Jest and `ts-jest`
+- ESLint and `@typescript-eslint/eslint-plugin`
+- Built-in `node:test` runner
+- prettier
+- tsc
+- esbuild
+
+We do this to ensure that Typescript upgrades do not break these dependencies. New major versions of Typescript are not immediately
+supported by projects such as ts-jest, eslint, prettier, etc. Our policy is to wait until these projects fully support
+the new version of Typescript, and/or without emitting warnings during these tests, before publishing.
 
-#### A note about versioning
+### A note about versioning
 
 Strict semver is a little complicated, as Typescript itself does not adhere to semver. So our "best effort" policy is:
 
-- Each new target (e.g. `ES2019` to `ES2020`) will result in a new major version of this module. We coordinate this
-  with whatever the latest LTS version of Node is currently supported by Amazon Lambda, Google Cloud Functions
+- Each update to the minimum Node target (e.g. Node 16 to Node 18) will result in a new major version of this module.
+  We coordinate this with whatever the latest LTS version of Node is currently supported by Amazon Lambda, Google Cloud Functions
   and Azure Functions.
-- Each new major version of Typescript (e.g. `4.2.x` to `4.3.x`) will result in a new minor version of this module.
-- Each new minor update of Typescript (e.g. `4.3.1` to `4.3.2`) will result in a new patch version of this module.
+- Each new "major" version of Typescript (e.g. `4.2.x` to `4.3.x`) will result in a new minor version of this module.
+- A new minor update of Typescript (e.g. `4.3.1` to `4.3.2`) _may_ result in a patch, in
+  a situation where a specific need or issue requires setting a new minimum version of Typescript.
 
 Bear in mind, any update of Typescript can potentially break your build. But hopefully in a way that's useful.
 
@@ -31,7 +87,8 @@ Bear in mind, any update of Typescript can potentially break your build. But hop
 npm add -D @checkdigit/typescript-config
 ```
 
-Note: you do not need to explicitly install Typescript itself, as it comes in as a peer dependency of `@checkdigit/typescript-config`.
+Note: you do not need to explicitly install Typescript itself, as the most recent supported version comes in as a
+peer dependency of `@checkdigit/typescript-config`.
 
 Make sure your project's `tsconfig.json` extends `@checkdigit/typescript-config`.
 

package/bin/builder.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// src/builder/index.mts
+import { strict as assert2 } from "node:assert";
+import path2 from "node:path";
+import { parseArgs } from "node:util";
+
+// src/builder/builder.mts
+import { strict as assert } from "node:assert";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import typescript from "typescript";
+import { build } from "esbuild";
+async function getFiles(directory) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map((entry) => {
+      const result = path.resolve(directory, entry.name);
+      return entry.isDirectory() ? getFiles(result) : result;
+    })
+  );
+  return files.flat();
+}
+function excludeSourceMaps(filter) {
+  return (pluginBuild) => {
+    pluginBuild.onLoad({ filter }, async (args) => {
+      if (args.path.endsWith(".js") || args.path.endsWith(".mjs") || args.path.endsWith(".cjs")) {
+        return {
+          contents: `${await fs.readFile(
+            args.path,
+            "utf8"
+          )}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIiJdLCJtYXBwaW5ncyI6IkEifQ==`,
+          loader: "default"
+        };
+      }
+      return void 0;
+    });
+  };
+}
+function resolveTypescriptPaths(type2) {
+  const extension = type2 === "module" ? "mjs" : "cjs";
+  return (pluginBuild) => {
+    pluginBuild.onResolve({ filter: /.*/u }, async (resolved) => {
+      if (resolved.kind === "entry-point" || !resolved.path.startsWith(".") || resolved.path.endsWith(".js")) {
+        return { external: resolved.kind !== "entry-point" };
+      }
+      let isDirectory = false;
+      try {
+        const stats = await fs.lstat(path.join(resolved.resolveDir, resolved.path));
+        isDirectory = stats.isDirectory();
+      } catch {
+      }
+      let newPath = resolved.path;
+      newPath += isDirectory ? `/index.${extension}` : `.${extension}`;
+      return { path: newPath, external: true };
+    });
+  };
+}
+async function builder_default({
+  type: type2,
+  entryPoint: entryPoint2,
+  inDir: inDir2,
+  outDir: outDir2,
+  outFile: outFile2,
+  external: external2 = [],
+  minify: minify2 = false,
+  sourceMap: sourceMap2
+}) {
+  const messages2 = [];
+  assert.ok(
+    entryPoint2 === void 0 && outFile2 === void 0 || entryPoint2 !== void 0 && outFile2 !== void 0,
+    "entryPoint and outFile must both be provided"
+  );
+  const allSourceFiles = await getFiles(inDir2);
+  const productionSourceFiles = entryPoint2 === void 0 ? allSourceFiles.filter((file) => file.endsWith(".ts")) : [path.join(inDir2, entryPoint2)];
+  const program = typescript.createProgram(productionSourceFiles, {
+    module: typescript.ModuleKind.ESNext,
+    moduleResolution: typescript.ModuleResolutionKind.Bundler,
+    target: typescript.ScriptTarget.ESNext,
+    declaration: true,
+    noEmitOnError: true,
+    emitDeclarationOnly: true,
+    rootDir: inDir2,
+    outDir: outDir2,
+    noLib: false,
+    skipLibCheck: true,
+    strict: true,
+    preserveConstEnums: true,
+    noImplicitReturns: true,
+    noUnusedLocals: true,
+    noUnusedParameters: true,
+    alwaysStrict: true,
+    verbatimModuleSyntax: false,
+    noFallthroughCasesInSwitch: true,
+    forceConsistentCasingInFileNames: true,
+    emitDecoratorMetadata: true,
+    experimentalDecorators: true,
+    resolveJsonModule: true,
+    esModuleInterop: true,
+    noUncheckedIndexedAccess: true,
+    noPropertyAccessFromIndexSignature: true,
+    allowUnusedLabels: false,
+    allowUnreachableCode: false,
+    noImplicitOverride: true,
+    useUnknownInCatchVariables: true,
+    exactOptionalPropertyTypes: true
+  });
+  const emitResult = program.emit();
+  const allDiagnostics = typescript.sortAndDeduplicateDiagnostics([
+    ...typescript.getPreEmitDiagnostics(program),
+    ...emitResult.diagnostics
+  ]);
+  for (const diagnostic of allDiagnostics) {
+    if (diagnostic.file) {
+      assert.ok(diagnostic.start !== void 0);
+      const { line, character } = typescript.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
+      const message = typescript.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+      messages2.push(`tsc: ${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`);
+    } else {
+      messages2.push(`tsc: ${typescript.flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`);
+    }
+  }
+  if (emitResult.emitSkipped) {
+    throw new Error(`TypeScript compilation failed ${JSON.stringify(messages2)}`);
+  }
+  const buildResult = await build({
+    entryPoints: productionSourceFiles,
+    bundle: true,
+    minify: minify2,
+    platform: "node",
+    format: type2 === "module" ? "esm" : "cjs",
+    sourcesContent: false,
+    sourcemap: sourceMap2 ? "inline" : false,
+    ...outFile2 === void 0 ? {
+      // individual files
+      outdir: outDir2,
+      outExtension: { ".js": type2 === "module" ? ".mjs" : ".cjs" },
+      plugins: [
+        {
+          name: "resolve-typescript-paths",
+          setup: resolveTypescriptPaths(type2)
+        }
+      ]
+    } : {
+      // bundling
+      outfile: path.join(outDir2, outFile2),
+      legalComments: "none",
+      external: external2,
+      plugins: [
+        {
+          name: "exclude-source-maps",
+          setup: excludeSourceMaps(/node_modules/u)
+        }
+      ]
+    }
+  });
+  messages2.push(...buildResult.errors.map((error) => `esbuild error: ${error.text}`));
+  messages2.push(...buildResult.warnings.map((warning) => `esbuild warning: ${warning.text}`));
+  if (messages2.length > 0) {
+    throw new Error(`esbuild failed ${JSON.stringify(messages2)}`);
+  }
+  return messages2;
+}
+
+// src/builder/index.mts
+var {
+  values: { type, inDir, outDir, entryPoint, outFile, external, minify, sourceMap }
+} = parseArgs({
+  options: {
+    type: { type: "string", short: "t", default: "module" },
+    inDir: { type: "string", short: "i", default: "src" },
+    outDir: { type: "string", short: "o", default: "build" },
+    entryPoint: { type: "string", short: "e", default: void 0 },
+    outFile: { type: "string", short: "f", default: void 0 },
+    external: { type: "string", short: "x", multiple: true, default: [] },
+    minify: { type: "boolean", short: "m", default: false },
+    sourceMap: { type: "boolean", short: "s", default: false }
+  }
+});
+assert2.ok(type === "module" || type === "commonjs", "type must be module or commonjs");
+assert2.ok(inDir !== void 0, "inDir is required");
+assert2.ok(outDir !== void 0, "outDir is required");
+var messages = await builder_default({
+  type,
+  inDir: path2.join(process.cwd(), inDir),
+  outDir: path2.join(process.cwd(), outDir),
+  entryPoint,
+  outFile,
+  external,
+  minify,
+  sourceMap
+});
+if (messages.length > 0) {
+  console.warn(JSON.stringify(messages, void 0, 2));
+  process.exit(1);
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@checkdigit/typescript-config",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Check Digit standard Typescript configuration",
   "prettier": "@checkdigit/prettier-config",
   "engines": {
     "node": ">=16"
   },
+  "bin": {
+    "builder": "./bin/builder.mjs"
+  },
   "peerDependencies": {
     "@types/node": ">=16",
-    "typescript": ">=5.0.2 <5.1"
+    "esbuild": "0.17.19",
+    "typescript": ">=5.0.4 <5.1"
   },
   "repository": {
     "type": "git",
@@ -23,16 +27,167 @@
   "scripts": {
     "preversion": "npm test",
     "postversion": "git push && git push --tags",
-    "prettier": "prettier --list-different .",
-    "prettier:fix": "prettier --write .",
-    "test": "npm run ci:compile && npm run ci:test && npm run ci:style",
-    "ci:compile": "tsc --noEmit",
-    "ci:test": "tsc && node build/index.js | grep -q 'complete' && rimraf build",
+    "prepare": "npm run build-builder",
+    "lint:fix": "eslint -f unix --ext .ts,.mts src --fix",
+    "lint": "eslint -f unix --ext .ts,.mts src",
+    "prettier": "prettier --ignore-path .gitignore --list-different .",
+    "prettier:fix": "prettier --ignore-path .gitignore --write .",
+    "test": "npm run ci:compile && npm run ci:test && npm run ci:lint && npm run ci:style",
+    "build-builder": "esbuild src/builder/index.mts --bundle --platform=node --format=esm --external:typescript --external:esbuild --outfile=build-builder/builder.mjs && mkdir -p bin && { echo '#!/usr/bin/env node'; cat build-builder/builder.mjs; } > bin/builder.mjs && chmod +x bin/builder.mjs",
+    "build-cjs": "rimraf build-cjs && npx builder --type=commonjs --outDir=build-cjs",
+    "build-cjs-bundle": "rimraf build-cjs-bundle && npx builder --type=commonjs --entryPoint=test/index.test.ts --outDir=build-cjs-bundle --outFile=test/index.test.cjs --minify --sourceMap",
+    "build-cjs-bundle-no-external": "rimraf build-cjs-bundle-no-external && npx builder --type=commonjs --external=./node_modules/* --entryPoint=test/index.test.ts --outDir=build-cjs-bundle-no-external --outFile=test/index.test.cjs",
+    "build-esm": "rimraf build-esm && npx builder --type=module --outDir=build-esm",
+    "build-esm-bundle": "rimraf build-esm-bundle && npx builder --type=module --outDir=build-esm-bundle --entryPoint=test/index.test.ts --outFile=test/index.test.mjs",
+    "build-esm-bundle-no-external": "rimraf build-esm-bundle-no-external && npx builder --type=module --external=./node_modules/* --outDir=build-esm-bundle-no-external --entryPoint=test/index.test.ts --outFile=test/index.test.mjs --minify",
+    "test-jest-esm": "NODE_OPTIONS=\"--experimental-vm-modules\" jest --coverage=false src/*.mts src/*/*.mts src/*/*/*.mts",
+    "test-jest-cjs": "jest --coverage=false src/*.ts src/*/*.ts src/*/*/*.ts",
+    "test-cjs": "node --test build-cjs/test/index.test.cjs",
+    "test-cjs-bundle": "node --test build-cjs-bundle/test/index.test.cjs",
+    "test-cjs-bundle-no-external": "node --test build-cjs-bundle-no-external/test/index.test.cjs",
+    "test-esm": "node --test build-esm/test/index.test.mjs",
+    "test-esm-bundle": "echo \"node --test build-esm-bundle/test/index.test.mjs\"",
+    "test-esm-bundle-no-external": "node --test build-esm-bundle-no-external/test/index.test.mjs",
+    "ci:test": "npm run test-jest-cjs && npm run test-jest-esm && npm run test-cjs && npm run test-cjs-bundle && npm run test-cjs-bundle-no-external && npm run test-esm && npm run test-esm-bundle && npm run test-esm-bundle-no-external",
+    "ci:compile": "npm run build-builder && npm run build-cjs && npm run build-cjs-bundle && npm run build-cjs-bundle-no-external && npm run build-esm && npm run build-esm-bundle && npm run build-esm-bundle-no-external",
+    "ci:lint": "npm run lint",
     "ci:style": "npm run prettier"
   },
   "devDependencies": {
-    "@checkdigit/prettier-config": "^3.3.0",
-    "rimraf": "^4.4.0"
+    "@checkdigit/prettier-config": "^3.4.0",
+    "@types/debug": "^4.1.7",
+    "@types/jest": "^29.5.1",
+    "@types/uuid": "^9.0.1",
+    "@typescript-eslint/eslint-plugin": "^5.59.6",
+    "@typescript-eslint/parser": "^5.59.6",
+    "debug": "^4.3.4",
+    "eslint": "^8.40.0",
+    "eslint-config-prettier": "^8.8.0",
+    "get-port": "^6.1.2",
+    "got": "^11.8.6",
+    "jest": "^29.5.0",
+    "rimraf": "^5.0.1",
+    "ts-jest": "^29.1.0",
+    "uuid": "^9.0.0"
+  },
+  "eslintConfig": {
+    "parser": "@typescript-eslint/parser",
+    "plugins": [
+      "@typescript-eslint"
+    ],
+    "parserOptions": {
+      "project": "./tsconfig.json"
+    },
+    "extends": [
+      "eslint:all",
+      "plugin:@typescript-eslint/recommended",
+      "plugin:@typescript-eslint/recommended-requiring-type-checking",
+      "plugin:@typescript-eslint/strict",
+      "prettier"
+    ],
+    "rules": {
+      "@typescript-eslint/non-nullable-type-assertion-style": "error",
+      "capitalized-comments": "off",
+      "one-var": "off",
+      "sort-keys": "off",
+      "sort-imports": "off",
+      "func-style": [
+        "error",
+        "declaration",
+        {
+          "allowArrowFunctions": true
+        }
+      ],
+      "no-magic-numbers": [
+        "error",
+        {
+          "ignore": [
+            0,
+            1,
+            2
+          ]
+        }
+      ],
+      "no-undefined": "off",
+      "no-ternary": "off"
+    },
+    "overrides": [
+      {
+        "files": [
+          "*.spec.mts",
+          "*.test.mts",
+          "*.spec.ts",
+          "*.test.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/non-nullable-type-assertion-style": "off",
+          "@typescript-eslint/ban-types": "off",
+          "@typescript-eslint/require-await": "off",
+          "@typescript-eslint/consistent-type-definitions": "off",
+          "@typescript-eslint/ban-ts-comment": "off",
+          "@typescript-eslint/no-unnecessary-condition": "off",
+          "@typescript-eslint/consistent-indexed-object-style": "off",
+          "@typescript-eslint/no-unused-vars": "off",
+          "@typescript-eslint/no-unsafe-member-access": "off",
+          "line-comment-position": "off",
+          "no-inline-comments": "off",
+          "no-param-reassign": "off",
+          "id-length": "off",
+          "no-magic-numbers": "off",
+          "func-names": "off",
+          "no-duplicate-imports": "off",
+          "symbol-description": "off",
+          "no-invalid-this": "off",
+          "max-lines-per-function": "off",
+          "max-lines": "off",
+          "max-statements": "off",
+          "no-await-in-loop": "off"
+        }
+      }
+    ]
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "mjs",
+      "cjs",
+      "ts",
+      "mts",
+      "json",
+      "node"
+    ],
+    "extensionsToTreatAsEsm": [
+      ".mts"
+    ],
+    "transform": {
+      "^.+\\.mts$": [
+        "ts-jest",
+        {
+          "isolatedModules": true,
+          "diagnostics": false,
+          "useESM": true
+        }
+      ],
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "isolatedModules": true,
+          "diagnostics": false,
+          "useESM": false
+        }
+      ]
+    },
+    "collectCoverageFrom": [
+      "<rootDir>/src/**",
+      "!<rootDir>/src/**/*.spec.mts",
+      "!<rootDir>/src/**/*.test.mts",
+      "!<rootDir>/src/**/*.spec.ts",
+      "!<rootDir>/src/**/*.test.ts"
+    ],
+    "testMatch": [
+      "<rootDir>/src/**/*.spec.ts",
+      "<rootDir>/src/**/*.spec.mts"
+    ]
   },
   "files": [
     "tsconfig.json",

package/tsconfig.json

@@ -1,8 +1,7 @@
 {
   "compilerOptions": {
-    "module": "commonjs",
-    "target": "es2022",
-    "lib": ["esnext", "dom", "webworker"],
+    "module": "NodeNext",
+    "target": "esnext",
     "sourceMap": true,
     "inlineSources": true,
     "outDir": "build",
@@ -28,6 +27,7 @@
     "noUncheckedIndexedAccess": true,
     "noPropertyAccessFromIndexSignature": true,
     "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
     "noImplicitOverride": true,
     "useUnknownInCatchVariables": true,
     "exactOptionalPropertyTypes": true