TypeScript String Operations

Warnings

• breaking Methods and properties starting with an uppercase letter (e.g., `String.Format`, `String.Join`) were marked as deprecated in v1.5.0 and are scheduled for removal in future versions.
  Fix: Migrate to the new lowercase-prefixed named function exports like `formatString`, `joinString`, `isNullOrWhiteSpace`, and `emptyString`.
• breaking The `String` class, which overrides the native JavaScript `String` object when imported, was deprecated in v1.5.0 and will be removed in the next major release.
  Fix: Avoid importing `String` (e.g., `import { String } from 'typescript-string-operations'`). Instead, use direct named imports for individual utility functions and constants.
• gotcha Version 1.5.0 updated to use the latest TypeScript version, which might cause compatibility issues or require environment checks for projects using older TypeScript versions.
  Fix: Ensure your project's TypeScript version is compatible with the version used by `typescript-string-operations` v1.5.0 or newer. Review compiler options and update your `tsconfig.json` if necessary.
• gotcha Prior to its deprecation, importing the `String` class (e.g., `import { String } from 'typescript-string-operations'`) would override the native `String` object, potentially leading to conflicts or unexpected behavior with other libraries or native string methods.
  Fix: It is strongly recommended to use the individual named function exports (`formatString`, `isNullOrWhiteSpace`, etc.) even in older versions if possible, to avoid global object modification. If upgrading to v1.5.0+, ensure the `String` class import is removed.

Install

• npm install typescript-string-operations npm
• yarn add typescript-string-operations yarn
• pnpm add typescript-string-operations pnpm

Imports

• StringBuilder
  wrong:

  const StringBuilder = require('typescript-string-operations').StringBuilder;

  correct:

  import { StringBuilder, formatString, isNullOrWhiteSpace, joinString, emptyString } from 'typescript-string-operations';

  This is the primary ESM import pattern. Using `require()` for CommonJS might work in some transpiled environments but is not the idiomatic TypeScript approach for this library.
• String (deprecated class)

  import { String } from 'typescript-string-operations';

  This import provides a class that overrides the native `String` object. It is deprecated since v1.5.0 and will be removed in the next major release. Usage is `String.format()`, `String.isNullOrWhiteSpace()`, etc.
• formatString
  wrong:

  import { String } from 'typescript-string-operations'; String.format(...);

  correct:

  import { formatString } from 'typescript-string-operations';

  Since v1.5.0, individual named functions like `formatString` are the recommended way to use the library's features, moving away from the deprecated `String` class.

Quickstart

Demonstrates installation, importing key functions and the StringBuilder class, and basic usage of `emptyString`, `isNullOrWhiteSpace`, `formatString` (with indexed arguments and object specifiers), `joinString` (with variadic arguments, arrays, and objects), and `StringBuilder` methods.

import { StringBuilder, emptyString, joinString, formatString, isNullOrWhiteSpace } from 'typescript-string-operations';

// 1. Using emptyString
console.log('Empty String:', emptyString); // Output: Empty String:

// 2. Using isNullOrWhiteSpace
const value1 = null;
const value2 = '';
const value3 = '   ';
const value4 = 'Hello';
console.log(`isNullOrWhiteSpace(${JSON.stringify(value1)}):`, isNullOrWhiteSpace(value1)); // Output: true
console.log(`isNullOrWhiteSpace(${JSON.stringify(value2)}):`, isNullOrWhiteSpace(value2)); // Output: true
console.log(`isNullOrWhiteSpace(${JSON.stringify(value3)}):`, isNullOrWhiteSpace(value3)); // Output: true
console.log(`isNullOrWhiteSpace(${JSON.stringify(value4)}):`, isNullOrWhiteSpace(value4)); // Output: false

// 3. Using formatString with indexed arguments
const userId = '2db5da20-1c5d-4f1a-8fd4-b41e34c8c5b5';
const formattedImageName = formatString("image_{0}.jpg", userId);
console.log('Formatted Image Name:', formattedImageName); // Output: image_2db5da20-1c5d-4f1a-8fd4-b41e34c8c5b5.jpg

// 4. Using formatString with specifiers and objects
interface Fruit {
    type: string;
    color: string;
    shippingDate: Date;
    amount: number;
}

const fruit: Fruit = {
    type: "apple",
    color: "RED",
    shippingDate: new Date(2018, 1, 1),
    amount: 10000
};

const fruitDescription = formatString("The {type:U} is {color:L} shipped on {shippingDate:s} with an amount of {amount:n}", fruit);
console.log('Fruit Description:', fruitDescription); // Output: The APPLE is red shipped on 2018-01-01T00:00:00 with an amount of 10.000

// 5. Using joinString
const joinedFruits = joinString("; ", "Apple", "Banana", "Orange");
console.log('Joined Fruits (args):', joinedFruits); // Output: Apple; Banana; Orange

const fruitArray = ['Mango', 'Pineapple'];
const joinedFruitArray = joinString(", ", fruitArray);
console.log('Joined Fruits (array):', joinedFruitArray); // Output: Mango, Pineapple

const objectToJoin = { Name: "Foo", Value: "Bar", ID: "123" };
const joinedObject = joinString('.', objectToJoin);
console.log('Joined Object:', joinedObject); // Output: Foo.Bar.123

// 6. Using StringBuilder
const sb = new StringBuilder();
sb.Append('Hello').Append(' ').AppendLine('World!');
sb.AppendFormat('The answer is {0}.', 42);
console.log('StringBuilder Output:\n', sb.ToString());
/* Expected Output:
Hello World!
The answer is 42.
*/