MagicString

🧵 An expressive and chainable library for advanced string manipulations. Supports appending, prepending, trimming, quoting, and path formatting with customizable whitespace handling. Makes advanced String manipulations a piece of cake. 🦥

📃 Table of Contents

- Features
- Usage
- API
- StringValue
- constructor()
- value
- length
- isEmpty()
- clear()
- append()
- appendIf()
- appendSingleQuoted()
- appendQuoted()
- trimAll()
- trim()
- trimOn()
- trimOff()
- trimStart()
- trimEnd()
- path()
- prepend()
- toLowerCase()
- toUpperCase()
- replace()
- insert()
- substring()
- scramble()
- Examples
- Changelog
- Support
- License
- Related
- Author

🤖 Features

- 🪄 Chainable API - build complex string transformations step‑by‑step
- ➕ Append & prepend - add text anywhere with ease
- 🧹 Whitespace control - trim, normalize, or toggle trimming on/off
- 🗨 Smart quoting - wrap values in single or double quotes automatically
- 📂 Path‑safe formatting - auto‑quote paths with spaces
- 🔄 Case transforms - switch to upper or lower case instantly
- 🪢 Conditional append - add only when extra values exist
- ✂️ Substring & insert - extract or inject text at any position
- 🧩 Replace - swap substrings with precision
- 🎲 Scramble - randomize characters for fun or obfuscation (powered by ScRaMbLe)
- 🧼 Array support - join string arrays into clean, single string
- ⚡ Lightweight & dependency‑free - minimal footprint, maximum utility

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

``bash
pnpm add @igorskyflyer/magic-string
`

`bash
yarn add @igorskyflyer/magic-string
`

`bash
npm i @igorskyflyer/magic-string
`

🤹🏼 API

All string-related methods use a common string type that can either be a string or a string array. StringValue defined as:

$3

---

$3

Creates a new instance of MagicString.

initialValue - Optional, the initial value to assign to the accumulator.

> ℹ️ NOTE
>
> The value is assigned to the accumulator as-is, no processing is performed.
>

---

$3

Gets the accumulator value.

Returns the accumulator as a string.

---

$3

Gets the length of the accumulator.

Returns the length of the accumulator.

---

$3

Checks if the accumulator is empty.

Returns true if the accumulator is empty, false otherwise.

---

$3

Clears the accumulator.

Returns the current instance of MagicString.

---

$3

Appends a value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

$3

Conditionally appends values to the accumulator only if the primary value is followed by other non-empty values.

This method checks if the provided rest values are non-empty before appending them.

Supports passing multiple string values as rest parameters or a single array of strings.

value - The primary value to append.

rest - Additional values to check and append.

Returns the current instance of MagicString.

---

$3

Appends a single-quoted value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

$3

Appends a double-quoted value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

$3

Trims all whitespace in the accumulator.

Returns the current instance of MagicString.

---

$3

Trims only leading and trailing whitespace from the accumulator.

Returns the current instance of MagicString.

---

$3

Enables trimming of values before adding them to the accumulator.

Returns the current instance of MagicString.

---

$3

Disables trimming of values before adding them to the accumulator.

Returns the current instance of MagicString.

---

$3

Trims only leading whitespace from the accumulator.

Returns the current instance of MagicString.

---

$3

Trims only trailing whitespace from the accumulator.

Returns the current instance of MagicString.

---

$3

Appends a value representing a path to the accumulator, wrapping it in double quotes if necessary.

value - The path value to append.

Returns the current instance of MagicString.

---

$3

Prepends a value to the accumulator.

value - The value to prepend.

Returns the current instance of MagicString.

---

$3

Converts the accumulator to lower case.

Returns the current instance of MagicString.

---

$3

Converts the accumulator to upper case.

Returns the current instance of MagicString.

---

$3

Replaces occurrences of a substring in the accumulator with a new substring.

searchValue - The substring to search for.

replaceValue - The substring to replace with.

Returns the current instance of MagicString.

---

$3

Inserts a value at a specified index in the accumulator.

If the index is negative or zero, the value is prepended.

If the index is greater than or equal to the length of the current accumulator, the value is appended.

value - The value to insert.

index - The position at which to insert the value.

Returns the current instance of MagicString.

---

$3

Extracts a substring from the accumulator between specified indices.

start - The starting index of the substring.

end - The ending index of the substring (optional).

Returns the current instance of MagicString.

---

$3

Scrambles (rearranges characters randomly) of the current accumulator.

Requires that the current accumulator value has a length > 3.

Returns the current instance of MagicString.

🗒️ Examples

example.ts
`ts
import { MagicString } from '@igorskyflyer/magic-string'


console.log(
new MagicString()
.append('Hello')
.appendSingleQuoted('world')
.appendQuoted('this is a test')
.prepend('Start: ')
.trimAll()
.path('/usr/local/bin')
.toUpperCase()
.path('/usr/local/my file.txt"') // intentional stray quote
.toLowerCase()
.toUpperCase()
.trimOn()
.append(' Trimmed ')
.trimOff()
.append(' Not trimmed')
.trim().value
)

// prints 'START: HELLO \'WORLD\' "THIS IS A TEST" /USR/LOCAL/BIN "/USR/LOCAL/MY FILE.TXT" Trimmed Not trimmed'
``

📝 Changelog

📑 The changelog is available here, CHANGELOG.md.

🪪 License

Licensed under the MIT license which is available here, MIT license.

💖 Support

I work hard for every project, including this one and your support means a lot to me!


Consider buying me a coffee. ☕









Thank you for supporting my efforts! 🙏😊

🧬 Related

@igorskyflyer/extendable-string

> _🦀 ExtendableString allows you to create strings on steroids that have custom transformations applied to them, unlike common, plain strings. 🪀_

@igorskyflyer/str-is-in

> _🧵 Provides ways of checking whether a String is present in an Array of Strings using custom Comparators. 🔍_

@igorskyflyer/normalized-string

> _💊 NormalizedString provides you with a String type with consistent line-endings, guaranteed. 📮_

@igorskyflyer/astro-escaped-component

> _🏃🏻‍♂️‍➡️ An Astro component that holds only HTML-encoded content. 📜_

@igorskyflyer/strip-html

> _🥞 Removes HTML code from the given string. Can even extract text-only from the given an HTML string. ✨_

👨🏻‍💻 Author