Fix ES2015 built-in type errors in consumers by adding lib reference directive to published declarations (#558)

Consumers using `"lib": ["ES5", "DOM"]` (or omitting `lib` entirely) get
TypeScript errors like `Cannot find name 'Symbol'` / `Cannot find name
'Iterator'` because the package's published `.d.ts` file references
ES2015 built-ins without declaring that dependency to TypeScript.

## Root Cause

The bundled declaration file (`lib/dist/types/ts-utils.d.ts`) exposes
ES2015 types such as `Symbol`, `Iterator<T>`, `Iterable<T>`,
`IterableIterator<T>`, and `Promise<T>` in its public API surface.
Without a `/// <reference lib="es2015" />` directive in the published
file, consumers must manually add `"lib": ["ES2015"]` to their own
`tsconfig.json` — otherwise TypeScript cannot resolve these types.

## Changes

- **`lib/src/index.ts`** and **`lib/src/polyfills.ts`** — adds `///
<reference lib="es2015" />` to the source entry points so TypeScript
includes the directive in generated `.d.ts` files and validates against
ES2015 types at build time
- **`lib/scripts/setTsReferences.js`** — new post-processing script that
prepends `/// <reference lib="es2015" />` to the api-extractor bundled
output (`lib/dist/types/ts-utils.d.ts`); this is required because
api-extractor strips `/// <reference lib="..." />` directives from its
rollup
- **`package.json`** — updates the `dtsgen` script to `api-extractor run
--local --verbose && node lib/scripts/setTsReferences.js` so the
post-processing runs automatically as part of every build
- **`lib/tsconfig.base.json`** — adds `"lib": ["ES2015", "DOM"]`;
propagates to both the ES5 and ES6 build configs via `extends`
- **`lib/test/tsconfig.test.json`**,
**`lib/test/tsconfig.test.karma.json`**,
**`lib/test/tsconfig.worker.karma.json`** — add `"lib": ["ES2015",
"DOM"]`
- **`lib/test/tsconfig.test.esnext.json`** — adds `"lib": ["ESNext",
"DOM"]`
- **`CHANGELOG.md`** — adds bug fix entry for v0.13.0

The net effect is that consumers who import from `@nevware21/ts-utils`
automatically get the ES2015 type definitions included by TypeScript —
no change to their own `tsconfig.json` is required.

`DOM` is included alongside `ES2015` in all tsconfig files because the
public API exports types like `Window`, `Document`, `Navigator`, and
`History` (from `helpers/environment.ts`), which require the DOM lib to
resolve.

This does not change the JavaScript runtime target or emit.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: nev21 <82737406+nev21@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Changelog
 
+### Bug Fixes
+
+- [#565](https://github.com/nevware21/ts-utils/issues/565) Fixed compilation errors for consumers using ES5-only TypeScript lib settings.
+  - Added `/// <reference lib="es2015" />` directive to the published `.d.ts` declaration file so that consumers with `"lib": ["ES5", "DOM"]` (or no explicit `lib`) can compile without "Cannot find name 'Symbol'" / "Cannot find name 'Iterator'" errors.
+  - The fix includes a post-processing step (`lib/scripts/setTsReferences.js`) that adds the reference directive to the api-extractor bundled output, since api-extractor strips `/// <reference lib="..." />` from its rollup.
+  - Also added `"lib": ["ES2015", "DOM"]` to the library build and test tsconfig files for consistent compile-time validation.
+
 ### Features
 
 - Added comprehensive encoding and decoding functions for multiple formats:

lib/scripts/setTsReferences.js

@@ -0,0 +1,41 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2022-2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+"use strict";
+
+/**
+ * Post-processing script to add TypeScript lib reference directives to the bundled
+ * declaration file generated by api-extractor.
+ *
+ * The api-extractor tool strips `/// <reference lib="..." />` directives from the
+ * bundled output. These directives are required so that consumers using ES5-only lib
+ * settings in their tsconfig (e.g. `"lib": ["ES5", "DOM"]`) can compile code that
+ * references the package's type declarations without encountering "Cannot find name"
+ * errors for ES2015 built-ins such as Symbol, Iterator, Iterable, etc.
+ */
+
+var fs = require("fs");
+var path = require("path");
+
+var bundledDtsFile = path.resolve(__dirname, "../dist/types/ts-utils.d.ts");
+var referenceDirective = "/// <reference lib=\"es2015\" />";
+
+if (!fs.existsSync(bundledDtsFile)) {
+    console.error("ERROR: Bundled d.ts file not found: " + bundledDtsFile);
+    process.exit(1);
+}
+
+var content = fs.readFileSync(bundledDtsFile, "utf8");
+var newLine = content.indexOf("\r\n") !== -1 ? "\r\n" : "\n";
+
+if (content.indexOf(referenceDirective) === -1) {
+    fs.writeFileSync(bundledDtsFile, referenceDirective + newLine + content, "utf8");
+    console.log("Added '" + referenceDirective + "' to " + path.relative(process.cwd(), bundledDtsFile));
+} else {
+    console.log("Reference directive already present in " + path.relative(process.cwd(), bundledDtsFile));
+}

lib/src/index.ts

@@ -6,6 +6,8 @@
  * Licensed under the MIT license.
  */
 
+/// <reference lib="es2015" />
+
 export { arrAppend } from "./array/append";
 export { ArrPredicateCallbackFn, ArrPredicateCallbackFn2, ArrMapCallbackFn, ArrFlatMapCallbackFn, ArrFromMapFn } from "./array/callbacks";
 export { arrAt } from "./array/at";

lib/src/polyfills.ts

@@ -6,6 +6,8 @@
  * Licensed under the MIT license.
  */
 
+/// <reference lib="es2015" />
+
 import { arrForEach } from "./array/forEach";
 import { ArrCls, ArrProto, ObjClass, StrProto } from "./internal/constants";
 import { polyIsArray, polyArrIncludes, polyArrFind, polyArrFindIndex, polyArrFindLastIndex, polyArrFindLast, polyArrFrom } from "./polyfills/array";

lib/test/tsconfig.test.esnext.json

@@ -6,6 +6,7 @@
         "module": "commonjs",
         "moduleResolution": "node",
         "target": "ESNext",
+        "lib": ["ESNext", "DOM"],
         "forceConsistentCasingInFileNames": true,
         "importHelpers": true,
         "noEmitHelpers": false,

lib/test/tsconfig.test.json

@@ -6,6 +6,7 @@
         "module": "commonjs",
         "moduleResolution": "node",
         "target": "es5",
+        "lib": ["ES2015", "DOM"],
         "forceConsistentCasingInFileNames": true,
         "importHelpers": true,
         "noEmitHelpers": false,

lib/test/tsconfig.test.karma.json

@@ -6,6 +6,7 @@
         "module": "commonjs",
         "moduleResolution": "node",
         "target": "es5",
+        "lib": ["ES2015", "DOM"],
         "forceConsistentCasingInFileNames": true,
         "importHelpers": true,
         "noEmitHelpers": false,

lib/test/tsconfig.worker.karma.json

@@ -6,6 +6,7 @@
         "module": "es6",
         "moduleResolution": "node",
         "target": "es5",
+        "lib": ["ES2015", "DOM"],
         "forceConsistentCasingInFileNames": true,
         "importHelpers": true,
         "noEmitHelpers": false,

lib/tsconfig.base.json

@@ -6,6 +6,7 @@
         "module": "es6",
         "moduleResolution": "node",
         "target": "es5",
+        "lib": ["ES2015", "DOM"],
         "forceConsistentCasingInFileNames": true,
         "importHelpers": true,
         "noEmitHelpers": false,

package.json

@@ -185,7 +185,7 @@
         "prep-release": "npm run cleanBuild && npm run npm-pack",
         "npm-pack": "copyfiles README.md LICENSE lib && cd lib && npm pack",
         "npm-publish": "publish-npm",
-        "dtsgen": "api-extractor run --local --verbose",
+        "dtsgen": "api-extractor run --local --verbose && node lib/scripts/setTsReferences.js",
         "size": "size-limit",
         "size-save": "size-limit --clean-dir --save-bundle build/size",
         "size-check": "node lib/test/bundle-size-check.js",