@igor.dvlpr/magic-string

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.

💖 Support further development

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! 🙏😊



@igorskyflyer

📃 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
• License
• Related
• Author

---

🤖 Features

• 🗣️ expressive and chainable
• 📃 with many string manipulation methods
• 👽 increases productiveness

🕵🏼 Usage

Install it by executing:

npm i '@igor.dvlpr/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:

type StringValue = string | string[]

---

constructor(initialValue?: StringValue)

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.

---

value: string

Gets the accumulator value.

Returns the accumulator as a string.

---

length: number

Gets the length of the accumulator.

Returns the length of the accumulator.

---

isEmpty(): boolean

Checks if the accumulator is empty.

Returns true if the accumulator is empty, false otherwise.

---

clear()

Clears the accumulator.

Returns the current instance of MagicString.

---

append(value: StringValue)

Appends a value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

appendIf(value: StringValue, ...rest: StringValue[])

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.

---

appendSingleQuoted(value: StringValue)

Appends a single-quoted value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

appendQuoted(value: StringValue)

Appends a double-quoted value to the accumulator.

value - The value to append.

Returns the current instance of MagicString.

---

trimAll()

Trims all whitespace in the accumulator.

Returns the current instance of MagicString.

---

trim()

Trims only leading and trailing whitespace from the accumulator.

Returns the current instance of MagicString.

---

trimOn()

Enables trimming of values before adding them to the accumulator.

Returns the current instance of MagicString.

---

trimOff()

Disables trimming of values before adding them to the accumulator.

Returns the current instance of MagicString.

---

trimStart()

Trims only leading whitespace from the accumulator.

Returns the current instance of MagicString.

---

trimEnd()

Trims only trailing whitespace from the accumulator.

Returns the current instance of MagicString.

---

path(value: StringValue)

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.

---

prepend(value: StringValue)

Prepends a value to the accumulator.

value - The value to prepend.

Returns the current instance of MagicString.

---

toLowerCase()

Converts the accumulator to lower case.

Returns the current instance of MagicString.

---

toUpperCase()

Converts the accumulator to upper case.

Returns the current instance of MagicString.

---

replace(searchValue: string, replaceValue: string)

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.

---

insert(value: StringValue, index: number)

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.

---

substring(start: number, end?: number)

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.

---

scramble()

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.mts

import { MagicString } from '@igor.dvlpr/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.

---

🧬 Related

@igor.dvlpr/extendable-string

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

@igor.dvlpr/str-is-in

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

@igor.dvlpr/normalized-string

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

@igor.dvlpr/astro-escaped-component

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

@igor.dvlpr/strip-html

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

---

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).