@checkdigit/typescript-config 3.3.0 → 3.4.0-PR.36-4133

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 output to generate. Defaults to `module` (ESM). Valid values are `commonjs`, `module` or `types`.
+- `--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,200 @@
+#!/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,
+    noEmit: type2 !== "types",
+    noEmitOnError: true,
+    emitDeclarationOnly: type2 === "types",
+    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 (messages2.length > 0) {
+    throw new Error(`tsc failed ${JSON.stringify(messages2)}`);
+  }
+  if (type2 === "types") {
+    return [];
+  }
+  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 === "types", "type must be types, 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,41 +1 @@
-{
-  "name": "@checkdigit/typescript-config",
-  "version": "3.3.0",
-  "description": "Check Digit standard Typescript configuration",
-  "prettier": "@checkdigit/prettier-config",
-  "engines": {
-    "node": ">=16"
-  },
-  "peerDependencies": {
-    "@types/node": ">=16",
-    "typescript": ">=5.0.2 <5.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/checkdigit/typescript-config.git"
-  },
-  "author": "Check Digit, LLC",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/checkdigit/typescript-config/issues"
-  },
-  "homepage": "https://github.com/checkdigit/typescript-config#readme",
-  "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",
-    "ci:style": "npm run prettier"
-  },
-  "devDependencies": {
-    "@checkdigit/prettier-config": "^3.3.0",
-    "rimraf": "^4.4.0"
-  },
-  "files": [
-    "tsconfig.json",
-    "SECURITY.md"
-  ]
-}
+{"name":"@checkdigit/typescript-config","version":"3.4.0-PR.36-4133","description":"Check Digit standard Typescript configuration","prettier":"@checkdigit/prettier-config","engines":{"node":">=16"},"bin":{"builder":"./bin/builder.mjs"},"peerDependencies":{"@types/node":">=16","esbuild":"0.17.19","typescript":">=5.0.4 <5.1"},"repository":{"type":"git","url":"git+https://github.com/checkdigit/typescript-config.git"},"author":"Check Digit, LLC","license":"MIT","bugs":{"url":"https://github.com/checkdigit/typescript-config/issues"},"homepage":"https://github.com/checkdigit/typescript-config#readme","scripts":{"preversion":"npm test","postversion":"git push && git push --tags","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-types":"rimraf build-types && npx builder --type=types --outDir=build-types","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-types && 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.4.0","@types/debug":"^4.1.8","@types/jest":"^29.5.1","@types/uuid":"^9.0.1","@typescript-eslint/eslint-plugin":"^5.59.7","@typescript-eslint/parser":"^5.59.7","debug":"^4.3.4","eslint":"^8.41.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","SECURITY.md","/src/"]}

package/src/builder/builder.mts

@@ -0,0 +1,236 @@
+// 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 { PluginBuild, build } from 'esbuild';
+
+export interface BuilderOptions {
+  /**
+   * whether to produce ESM or CommonJS code
+   */
+  type: 'module' | 'commonjs' | 'types';
+
+  /**
+   * 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
+   */
+  entryPoint?: string | undefined;
+
+  /**
+   * source code
+   */
+  inDir: string;
+
+  /**
+   * build directory
+   */
+  outDir: string;
+
+  /**
+   * build file, relative to the outDir
+   */
+  outFile?: string | undefined;
+
+  /**
+   * external modules to exclude from the bundle
+   */
+  external?: string[] | undefined;
+
+  /**
+   * whether to minify output
+   */
+  minify?: boolean | undefined;
+
+  /**
+   * whether to include sourcemap
+   */
+  sourceMap?: boolean | undefined;
+}
+
+/**
+ * Recursively obtains all files in a directory
+ * @param {string} directory
+ * @returns {Promise<string[]>}
+ */
+async function getFiles(directory: string): Promise<string[]> {
+  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: RegExp) {
+  return (pluginBuild: PluginBuild) => {
+    // ignore source maps for any Javascript file that matches filter
+    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'
+          )}\n//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIiJdLCJtYXBwaW5ncyI6IkEifQ==`,
+          loader: 'default',
+        };
+      }
+      return undefined;
+    });
+  };
+}
+
+function resolveTypescriptPaths(type: 'module' | 'commonjs') {
+  const extension = type === 'module' ? 'mjs' : 'cjs';
+  return (pluginBuild: PluginBuild) => {
+    // rewrite paths based on standard node resolution
+    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 {
+        // do nothing
+      }
+      let newPath = resolved.path;
+      newPath += isDirectory ? `/index.${extension}` : `.${extension}`;
+      return { path: newPath, external: true };
+    });
+  };
+}
+
+// eslint-disable-next-line func-names,max-lines-per-function,max-statements
+export default async function ({
+  type,
+  entryPoint,
+  inDir,
+  outDir,
+  outFile,
+  external = [],
+  minify = false,
+  sourceMap,
+}: BuilderOptions): Promise<string[]> {
+  const messages: string[] = [];
+
+  assert.ok(
+    (entryPoint === undefined && outFile === undefined) || (entryPoint !== undefined && outFile !== undefined),
+    'entryPoint and outFile must both be provided'
+  );
+
+  const allSourceFiles = await getFiles(inDir);
+  const productionSourceFiles =
+    entryPoint === undefined ? allSourceFiles.filter((file) => file.endsWith('.ts')) : [path.join(inDir, entryPoint)];
+
+  /**
+   * Emit declarations using typescript compiler, if type is 'types'.  Otherwise, just compile to ensure the build is good.
+   */
+  const program = typescript.createProgram(productionSourceFiles, {
+    module: typescript.ModuleKind.ESNext,
+    moduleResolution: typescript.ModuleResolutionKind.Bundler,
+    target: typescript.ScriptTarget.ESNext,
+    declaration: true,
+    noEmit: type !== 'types',
+    noEmitOnError: true,
+    emitDeclarationOnly: type === 'types',
+    rootDir: inDir,
+    outDir,
+    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 !== undefined);
+      const { line, character } = typescript.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
+      const message = typescript.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+      messages.push(`tsc: ${diagnostic.file.fileName} (${line + 1},${character + 1}): ${message}`);
+    } else {
+      // eslint-disable-next-line no-console
+      messages.push(`tsc: ${typescript.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`);
+    }
+  }
+
+  if (messages.length > 0) {
+    throw new Error(`tsc failed ${JSON.stringify(messages)}`);
+  }
+
+  if (type === 'types') {
+    return [];
+  }
+
+  /**
+   * Emit ESM javascript using esbuild
+   */
+  const buildResult = await build({
+    entryPoints: productionSourceFiles,
+    bundle: true,
+    minify,
+    platform: 'node',
+    format: type === 'module' ? 'esm' : 'cjs',
+    sourcesContent: false,
+    sourcemap: sourceMap ? 'inline' : false,
+    ...(outFile === undefined
+      ? {
+          // individual files
+          outdir: outDir,
+          outExtension: { '.js': type === 'module' ? '.mjs' : '.cjs' },
+          plugins: [
+            {
+              name: 'resolve-typescript-paths',
+              setup: resolveTypescriptPaths(type),
+            },
+          ],
+        }
+      : {
+          // bundling
+          outfile: path.join(outDir, outFile),
+          legalComments: 'none',
+          external,
+          plugins: [
+            {
+              name: 'exclude-source-maps',
+              setup: excludeSourceMaps(/node_modules/u),
+            },
+          ],
+        }),
+  });
+
+  messages.push(...buildResult.errors.map((error) => `esbuild error: ${error.text}`));
+  messages.push(...buildResult.warnings.map((warning) => `esbuild warning: ${warning.text}`));
+  if (messages.length > 0) {
+    throw new Error(`esbuild failed ${JSON.stringify(messages)}`);
+  }
+
+  return messages;
+}

package/src/builder/index.mts

@@ -0,0 +1,44 @@
+// builder/index.mts
+
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-expect-error
+import builder from './builder.mts';
+
+const {
+  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: undefined },
+    outFile: { type: 'string', short: 'f', default: undefined },
+    external: { type: 'string', short: 'x', multiple: true, default: [] },
+    minify: { type: 'boolean', short: 'm', default: false },
+    sourceMap: { type: 'boolean', short: 's', default: false },
+  },
+});
+
+assert.ok(type === 'module' || type === 'commonjs' || type === 'types', 'type must be types, module or commonjs');
+assert.ok(inDir !== undefined, 'inDir is required');
+assert.ok(outDir !== undefined, 'outDir is required');
+
+const messages = await builder({
+  type,
+  inDir: path.join(process.cwd(), inDir),
+  outDir: path.join(process.cwd(), outDir),
+  entryPoint,
+  outFile,
+  external,
+  minify,
+  sourceMap,
+});
+if (messages.length > 0) {
+  // eslint-disable-next-line no-console
+  console.warn(JSON.stringify(messages, undefined, 2));
+  process.exit(1);
+}

package/src/test/typescript/module-directory/index.ts

@@ -0,0 +1,3 @@
+// module-directory/index.ts
+
+export default () => 'module-directory-index';

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