feat(string): add strReplace + strReplaceAll, refactor internal replacements, and expand coverage

.size-limit.json

@@ -37,7 +37,7 @@
   {
     "name": "es6-zip",
     "path": "lib/dist/es6/mod/ts-utils.js",
-    "limit": "10.5 Kb",
+    "limit": "10.75 Kb",
     "gzip": true,
     "running": false
   },

docs/feature-backlog.md

@@ -0,0 +1,89 @@
+# Feature Backlog and Request Tracking
+
+This document tracks suggested additions for `@nevware21/ts-utils`.
+
+## Request RQ-2026-03-17-ADDITIONS
+
+- Request: Identify what additions could be added to ts-utils
+- Requested by: Maintainer discussion
+- Priority: High
+- Scope: Array, object, string, iterator, typing, and documentation improvements
+
+### Objective
+
+Identify practical, minification-friendly, cross-environment additions that fit the library design principles:
+
+- zero dependencies
+- ES5 compatibility for v0.x / v1.x
+- polyfill-backed behavior where needed
+- strong tree-shaking and small bundles
+
+## Suggested Additions (Proposed Only)
+
+### Language-Native Suggestions (with ECMAScript Version)
+
+The following suggestions map directly to JavaScript language / standard library features:
+
+- `strReplaceAll` wrapper/polyfill path
+	- JavaScript feature: `String.prototype.replaceAll()`
+	- Added in: **ECMAScript 2021 (ES12)**
+
+| Suggestion | JavaScript Feature | ECMAScript Version |
+| --- | --- | --- |
+| `strReplaceAll` wrapper/polyfill path | `String.prototype.replaceAll()` | ECMAScript 2021 (ES12) |
+
+Notes:
+
+- Other suggestions below are library-level utilities (not direct language features).
+- Iterator helpers are intentionally listed as utility suggestions here rather than standard-language mappings.
+
+### A. Typing Improvements (High Value)
+
+- `ReadonlyRecord<K, V>` helper type alias for API ergonomics
+- `DeepPartial<T>` utility type
+- `DeepReadonly<T>` utility type
+- `Mutable<T>` utility type for controlled writable transformations
+
+### B. Object Utilities (Medium Value)
+
+- `objPick` / `objOmit`
+- `objMapValues`
+- `objMergeIf`
+- `objDiff`
+
+Notes:
+
+- maintain plain-object safety patterns
+- avoid behavior changes to existing deep copy helpers
+
+### C. String Utilities (Medium Value)
+
+- `strTruncate` (with optional suffix)
+- `strCount` (substring occurrences)
+- `strReplaceAll` wrapper/polyfill path **(ECMAScript 2021 / ES12 language feature wrapper)**
+- `strCapitalizeWords`
+
+### D. Iterator and Collection Helpers (Medium Value)
+
+- `iterMap`, `iterFilter`, `iterTake`
+- `arrToMap` helpers with stable key selection
+- lightweight set operations for iterables
+
+### E. Reliability and Tooling (High Value)
+
+- keep bundle-size thresholds justified with measured report
+- require test parity for polyfill vs native behavior
+- ensure newly exported functions are reflected in README utility matrix
+
+## Acceptance Criteria for this Request
+
+- [x] Identify additions by category
+- [x] Prioritize additions by value and fit
+- [ ] Create follow-up issue list for proposed items
+- [ ] Add ownership and target milestone per item
+
+## Next Actions
+
+1. Open GitHub issues for sections A-D candidates.
+2. Add milestone tags for upcoming releases.
+3. Keep this document focused on proposed additions only.

lib/src/array/with.ts

@@ -11,6 +11,7 @@ import { _unwrapFunctionWithPoly } from "../internal/unwrapFunction";
 import { isArrayLike } from "../helpers/base";
 import { getLength } from "../helpers/length";
 import { arrSlice } from "./slice";
+import { throwRangeError } from "../helpers/throw";
 
 /**
  * The arrWith() method is the copying version of using the bracket notation to change the value
@@ -60,7 +61,7 @@ export function polyArrWith<T>(theArray: ArrayLike<T>, index: number, value: T):
     let result: T[];
 
     if (!isArrayLike(theArray)) {
-        throw new RangeError("Invalid array");
+        throwRangeError("Invalid array");
     }
 
     const len = getLength(theArray);
@@ -73,7 +74,7 @@ export function polyArrWith<T>(theArray: ArrayLike<T>, index: number, value: T):
 
     // Check bounds
     if (idx < 0 || idx >= len) {
-        throw new RangeError("Index out of bounds");
+        throwRangeError("Index out of bounds");
     }
 
     // Create a copy and set value

lib/src/helpers/encode.ts

@@ -10,6 +10,7 @@ import { EMPTY, NULL_VALUE, TO_STRING, UNDEF_VALUE } from "../internal/constants
 import { asString } from "../string/as_string";
 import { strCamelCase } from "../string/conversion";
 import { strPadStart } from "../string/pad";
+import { strReplace } from "../string/replace";
 import { strRepeat } from "../string/repeat";
 import { strSubstr } from "../string/substring";
 import { strUpper } from "../string/upper_lower";
@@ -79,7 +80,7 @@ let _base64Cache: { [key: string]: number };
  */
 /*#__NO_SIDE_EFFECTS__*/
 export function normalizeJsName(jsName: string, camelCase?: boolean): string {
-    let result = asString(jsName).replace(INVALID_JS_NAME, "_");
+    let result = strReplace(asString(jsName), INVALID_JS_NAME, "_");
 
     return !isUndefined(camelCase) ? strCamelCase(result, !camelCase) : result;
 }
@@ -129,7 +130,7 @@ export function encodeAsJson<T>(value: T, format?: boolean | number): string {
 
     if (isString(value)) {
         // encode if a character is not an alpha, numeric, space or some special characters
-        result = DBL_QUOTE + value.replace(/[^\w .,\-!@#$%\^&*\(\)_+={}\[\]:;|<>?]/g, (match) => {
+        result = DBL_QUOTE + strReplace(value, /[^\w .,\-!@#$%\^&*\(\)_+={}\[\]:;|<>?]/g, (match) => {
             if(match === DBL_QUOTE || match === "\\") {
                 return "\\" + match;
             }
@@ -184,7 +185,7 @@ export function encodeAsHtml(value: string) {
         "'": "#39"
     });
 
-    return asString(value).replace(/[&<>"']/g, match => "&" + _htmlEntityCache[match] + ";");
+    return strReplace(asString(value), /[&<>"']/g, match => "&" + _htmlEntityCache[match] + ";");
 }
 
 /**
@@ -273,7 +274,7 @@ export function encodeAsBase64Url(value: string): string {
     let encoded = encodeAsBase64(value);
 
     if (encoded) {
-        encoded = encoded.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+        encoded = strReplace(strReplace(strReplace(encoded, /\+/g, "-"), /\//g, "_"), /=/g, "");
     }
 
     return encoded || EMPTY;
@@ -304,7 +305,7 @@ export function decodeBase64Url(value: string): string {
             result = result + strRepeat("=", pad);
         }
 
-        result = decodeBase64(result.replace(/-/g, "+").replace(/_/g, "/")) || EMPTY;
+        result = decodeBase64(strReplace(strReplace(result, /-/g, "+"), /_/g, "/")) || EMPTY;
     }
 
     return result || value || EMPTY;

lib/src/helpers/regexp.ts

@@ -8,6 +8,7 @@
 
 import { EMPTY } from "../internal/constants";
 import { asString } from "../string/as_string";
+import { strReplace } from "../string/replace";
 
 const MATCH_ANY = "(.*)";
 const MATCH_SINGLE = "(.)";
@@ -27,7 +28,7 @@ const MATCH_SINGLE = "(.)";
 function _createRegExp(value: string, escapeRgx: RegExp, replaceFn: (value: string) => string, ignoreCase: boolean, fullMatch?: boolean) {
     // eslint-disable-next-line security/detect-non-literal-regexp
     return new RegExp(
-        (fullMatch ? "^" : EMPTY) + replaceFn(value.replace(escapeRgx, "\\$1")) + (fullMatch ? "$" : EMPTY),
+        (fullMatch ? "^" : EMPTY) + replaceFn(strReplace(value, escapeRgx, "\\$1")) + (fullMatch ? "$" : EMPTY),
         ignoreCase ? "i" : "");
 }
 
@@ -70,7 +71,7 @@ function _createRegExp(value: string, escapeRgx: RegExp, replaceFn: (value: stri
 /*#__NO_SIDE_EFFECTS__*/
 export function createWildcardRegex(value: string, ignoreCase?: boolean, fullMatch?: boolean) {
     return _createRegExp(asString(value), /([-+|^$#\.\?{}()\[\]\\\/\"\'])/g, (value: string) => {
-        return value.replace(/\*/g, MATCH_ANY);
+        return strReplace(value, /\*/g, MATCH_ANY);
     }, !!ignoreCase, fullMatch);
 }
 
@@ -120,7 +121,7 @@ export function createWildcardRegex(value: string, ignoreCase?: boolean, fullMat
 /*#__NO_SIDE_EFFECTS__*/
 export function createFilenameRegex(value: string, ignoreCase?: boolean, fullMatch?: boolean) {
     return _createRegExp(asString(value), /([-+|^$#\.{}()\\\/\[\]\"\'])/g, (value: string) => {
-        return value.replace(/(\\\\|\\\/|\*|\?)/g, function (_all, g1) {
+        return strReplace(value, /(\\\\|\\\/|\*|\?)/g, function (_all, g1) {
             if (g1 == "\\/" || g1 == "\\\\") {
                 return "[\\\\\\/]{1}";
             }
@@ -195,7 +196,7 @@ export function createFilenameRegex(value: string, ignoreCase?: boolean, fullMat
 export function makeGlobRegex(value: string, ignoreCase?: boolean, fullMatch?: boolean) {
     return _createRegExp(asString(value), /([-+|^$#\.{}()\\\/\[\]\"\'])/g, (value: string) => {
         //"**\/*\.txt"
-        return value.replace(/(\*\*\\[\\\/]|\\\\|\\\/|\*\*|\*|\?)/g, function (_all, g1) {
+        return strReplace(value, /(\*\*\\[\\\/]|\\\\|\\\/|\*\*|\*|\?)/g, function (_all, g1) {
             if (g1 == "**\\/" || g1 == "**\\\\") {
                 return "(.*[\\\\\\/])*";
             }

lib/src/index.ts

@@ -128,6 +128,8 @@ export { strContains, strIncludes, polyStrIncludes } from "./string/includes";
 export { strIndexOf, strLastIndexOf } from "./string/index_of";
 export { strIsNullOrWhiteSpace, strIsNullOrEmpty } from "./string/is_null_or";
 export { strPadEnd, strPadStart } from "./string/pad";
+export { strReplace } from "./string/replace";
+export { strReplaceAll } from "./string/replace_all";
 export { strRepeat } from "./string/repeat";
 export { strSlice } from "./string/slice";
 export { strStartsWith } from "./string/starts_with";

lib/src/polyfills.ts

@@ -18,6 +18,7 @@ import { polyStrPadEnd, polyStrPadStart } from "./string/pad";
 import { makePolyFn } from "./internal/poly_helpers";
 import { polyStrSubstr } from "./string/substring";
 import { polyStrIncludes } from "./string/includes";
+import { polyStrReplaceAll } from "./string/replace_all";
 import { polyObjFromEntries } from "./polyfills/object/objFromEntries";
 import { polyObjGetOwnPropertyDescriptors, _polyObjGetOwnPropertySymbols, _polyObjGetOwnPropertyNames } from "./polyfills/object/objGetOwnProperty";
 import { polyObjPreventExtensions } from "./polyfills/object/objPreventExtensions";
@@ -58,7 +59,8 @@ import { polyArrWith } from "./array/with";
         "trimEnd": polyStrTrimEnd,
         "trimRight": polyStrTrimEnd,
         "substr": polyStrSubstr,
-        "includes": polyStrIncludes
+        "includes": polyStrIncludes,
+        "replaceAll": polyStrReplaceAll
     };
 
     const arrayClsPolyfills = {
@@ -104,4 +106,4 @@ import { polyArrWith } from "./array/with";
     });
 })();
 
-export { polyArrAt, polyArrFill, polyArrWith };
+export { polyArrAt, polyArrFill, polyArrWith, polyStrReplaceAll };

lib/src/polyfills/trim.ts

@@ -8,14 +8,17 @@
 
 import { EMPTY } from "../internal/constants";
 import { _throwIfNullOrUndefined } from "../internal/throwIf";
+import { asString } from "../string/as_string";
+import { strReplace } from "../string/replace";
 
 /*#__NO_SIDE_EFFECTS__*/
 function _createTrimFn(exp: RegExp): (value: string) => string {
     return function _doTrim(value: string): string {
         _throwIfNullOrUndefined(value);
+        value = asString(value);
 
-        if (value && value.replace) {
-            value = value.replace(exp, EMPTY);
+        if (value) {
+            value = strReplace(value, exp, EMPTY);
         }
 
         return value;

lib/src/string/conversion.ts

@@ -8,6 +8,7 @@
 
 import { EMPTY } from "../internal/constants";
 import { asString } from "./as_string";
+import { strReplace } from "./replace";
 import { strTrim } from "./trim";
 import { strLower, strUpper } from "./upper_lower";
 
@@ -22,7 +23,7 @@ import { strLower, strUpper } from "./upper_lower";
  */
 /*#__NO_SIDE_EFFECTS__*/
 function _convertCase<T>(value: T, newPrefix: string, upperWord?: boolean): string {
-    return strTrim(asString(value)).replace(/((_|\W)+(\w){0,1}|([a-z])([A-Z]))/g,
+    return strReplace(strTrim(asString(value)), /((_|\W)+(\w){0,1}|([a-z])([A-Z]))/g,
         (_match, _g1, _g2, wordStart, upperPrefix, upperLetter) => {
             let convertMatch = wordStart || upperLetter|| EMPTY;
             if (upperWord) {
@@ -53,7 +54,7 @@ function _convertCase<T>(value: T, newPrefix: string, upperWord?: boolean): stri
  */
 /*#__NO_SIDE_EFFECTS__*/
 export function strLetterCase<T>(value: T): string {
-    return asString(value).replace(/(_|\b)\w/g, strUpper);
+    return strReplace(asString(value), /(_|\b)\w/g, strUpper);
 }
 
 /**
@@ -92,7 +93,7 @@ export function strLetterCase<T>(value: T): string {
 export function strCamelCase<T>(value: T, upperFirst?: boolean): string {
     let result = _convertCase(value, "", true);
 
-    return result.replace(/^\w/, upperFirst ? strUpper : strLower);
+    return strReplace(result, /^\w/, upperFirst ? strUpper : strLower);
 }
 
 /**

lib/src/string/is_null_or.ts

@@ -8,6 +8,7 @@
 
 import { isNullOrUndefined, isString } from "../helpers/base";
 import { EMPTY } from "../internal/constants";
+import { strReplace } from "./replace";
 
 /**
  * This method checks if the string `value` is null, undefined, an empty string or only contains
@@ -19,7 +20,7 @@ import { EMPTY } from "../internal/constants";
 /*#__NO_SIDE_EFFECTS__*/
 export function strIsNullOrWhiteSpace(value: string): boolean {
     if (isString(value)) {
-        return value.replace(/[\s\t\r\n\f]+/g, EMPTY) === EMPTY;
+        return strReplace(value, /[\s\t\r\n\f]+/g, EMPTY) === EMPTY;
     }
 
     return isNullOrUndefined(value)

lib/src/string/replace.ts

@@ -0,0 +1,29 @@
+/*
+ * @nevware21/ts-utils
+ * https://github.com/nevware21/ts-utils
+ *
+ * Copyright (c) 2026 NevWare21 Solutions LLC
+ * Licensed under the MIT license.
+ */
+
+import { StrProto } from "../internal/constants";
+import { _unwrapFunction } from "../internal/unwrapFunction";
+
+/**
+ * The strReplace() method returns a new string with one, some, or all matches of a pattern replaced
+ * by a replacement.
+ * @function
+ * @since 0.14.0
+ * @group String
+ * @param value - The string value to search and replace within.
+ * @param searchValue - The value to search for. Can be a string or regular expression.
+ * @param replaceValue - The replacement string or replacer function.
+ * @returns A new string with one, some, or all matches replaced.
+ * @example
+ * ```ts
+ * strReplace("a-b-a", "a", "x");         // "x-b-a"
+ * strReplace("a1b2", /\d/g, "#");        // "a#b#"
+ * strReplace("hello", /[aeiou]/, "*");    // "h*llo"
+ * ```
+ */
+export const strReplace: (value: string, searchValue: string | RegExp, replaceValue: string | ((substring: string, ...args: any[]) => string)) => string = (/*#__PURE__*/_unwrapFunction("replace", StrProto as any));