mongez-collection-strings

name

mongez-collection-strings

description

Per-element string transforms on an `ImmutableCollection` — `appendString`, `prependString`, `concatString`, `replaceString`, `replaceAllString`, `removeString`, `removeAllString`, `trim` — plus type casting (`string`, `number`, `boolean`). Documents the keyed-form source mutation, the `replaceAllString` "always global regex" trap, and when to reach for `.map` instead. TRIGGER when: code calls `c.appendString`, `c.prependString`, `c.concatString`, `c.replaceString`, `c.replaceAllString`, `c.removeString`, `c.removeAllString`, `c.trim`, `c.string`, `c.number`, or `c.boolean` on an `ImmutableCollection`; user asks "how do I append / prepend / replace / strip / trim text on every item", "how to cast a collection of strings to numbers / booleans", "how to apply a string transform to one field of every object". SKIP: ad-hoc string mapping where `c.map(item => ...)` is clearer — use `mongez-collection-builtins`; single-string formatting helpers — those live in `@mongez/reinforcements` (string slugify / kebab / camel / template) and are out of scope here; `replaceAllString` with a `RegExp` value — it forces `new RegExp(s, "g")`, use `replaceString(/regex/g, ...)` instead.

Per-element string transforms

Two flavors of every transform:

c.transform(value)              // applied to each item (as a string)
c.transform(value, key)         // applied to each item's keyed value

All return a new collection. The keyed form shallow-clones each plain-object item via cloneForSet before applying the change, so the source items are not modified. (Class instances and nested object references are passed through; the clone is shallow.)

Append / prepend / concat

c.appendString(s, key?)         // item + s
c.prependString(s, key?)        // s + item
c.concatString(s, key?)         // identical to appendString for strings

collect(["Ada", "Bob"]).appendString("!");
//  ["Ada!", "Bob!"]

collect([{ name: "Ada" }]).appendString("!", "name");
//  [{ name: "Ada!" }]

Replace / remove

c.replaceString(search: string | RegExp, replacement: string, key?)
c.replaceAllString(search: string, replacement: string, key?)   // search is a string; promoted to `new RegExp(search, "g")`
c.removeString(search: string | RegExp, key?)                    // replace with ""
c.removeAllString(search: string, key?)                          // replace all with ""

collect(["aba", "aaa"]).replaceString("a", "x");
//  ["xba", "xaa"]

collect(["aba", "aaa"]).replaceAllString("a", "x");
//  ["xbx", "xxx"]

collect(["aaba"]).removeAllString("a");
//  ["b"]

replaceAllString ALWAYS does a global regex replace (the first arg is forced into new RegExp(s, "g")). If you pass a regex, that's wrong — use replaceString(/regex/g, ...) instead.

Trim

c.trim(value?: string = " ", key?: string)

collect(["  hi  ", " x "]).trim();           // ["hi", "x"]
collect(["##a##", "#b#"]).trim("#");         // ["a", "b"]

Wraps reinforcements' trim(string, chars), which strips repeated occurrences of chars from both ends.

Casting

c.string()         // each item via String(item)
c.number()         // each item via Number(item)
c.boolean()        // each item via Boolean(item)

collect([1, null, "x"]).string();       // ["1", "null", "x"]
collect(["1", "abc", ""]).number();     // [1, NaN, 0]
collect([0, 1, "", "x"]).boolean();     // [false, true, false, true]

When to reach for these vs map

For most callers the c.map(item => /* custom transform */) route is clearer:

// Equivalent (and more transparent):
collect(["Ada", "Bob"]).map(name => `${name}!`);

// vs:
collect(["Ada", "Bob"]).appendString("!");

The dedicated string helpers shine when you want a chain like:

collect(users)
  .trim(" ", "name")
  .appendString(" verified", "name")
  .replaceString(/\s+/, " ", "name");

That reads as a fluent pipeline. Otherwise stick with map.