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

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",