https://github.com/igorskyflyer/npm-magic-string
🧵 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. 🦥
https://github.com/igorskyflyer/npm-magic-string
accumulator append back-end igorskyflyer javascript js magic magic-string manipulation prepend string trim ts typescript
Last synced: about 1 month ago
JSON representation
🧵 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. 🦥
- Host: GitHub
- URL: https://github.com/igorskyflyer/npm-magic-string
- Owner: igorskyflyer
- License: mit
- Created: 2024-07-30T21:55:47.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-04T19:59:46.000Z (over 1 year ago)
- Last Synced: 2025-03-07T13:40:40.024Z (11 months ago)
- Topics: accumulator, append, back-end, igorskyflyer, javascript, js, magic, magic-string, manipulation, prepend, string, trim, ts, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@igor.dvlpr/magic-string
- Size: 70.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
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](#-features)
- [Usage](#-usage)
- [API](#-api)
- [StringValue](#type-stringvalue--string--string)
- [constructor()](#constructorinitialvalue-stringvalue)
- [value](#value-string)
- [length](#length-number)
- [isEmpty()](#isempty-boolean)
- [clear()](#clear)
- [append()](#appendvalue-stringvalue)
- [appendIf()](#appendifvalue-stringvalue-rest-stringvalue)
- [appendSingleQuoted()](#appendsinglequotedvalue-stringvalue)
- [appendQuoted()](#appendquotedvalue-stringvalue)
- [trimAll()](#trimall)
- [trim()](#trim)
- [trimOn()](#trimon)
- [trimOff()](#trimoff)
- [trimStart()](#trimstart)
- [trimEnd()](#trimend)
- [path()](#pathvalue-stringvalue)
- [prepend()](#prependvalue-stringvalue)
- [toLowerCase()](#tolowercase)
- [toUpperCase()](#touppercase)
- [replace()](#replacesearchvalue-string-replacevalue-string)
- [insert()](#insertvalue-stringvalue-index-number)
- [substring()](#substringstart-number-end-number)
- [scramble()](#scramble)
- [Examples](#️-examples)
- [Changelog](#-changelog)
- [Support](#-support)
- [License](#-license)
- [Related](#-related)
- [Author](#-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](https://www.npmjs.com/package/@igorskyflyer/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:
### `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.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](https://github.com/igorskyflyer/npm-magic-string/blob/main/CHANGELOG.md).
## 🪪 License
Licensed under the MIT license which is available here, [MIT license](https://github.com/igorskyflyer/npm-magic-string/blob/main/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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@igorskyflyer/str-is-in)
> _🧵 Provides ways of checking whether a String is present in an Array of Strings using custom Comparators. 🔍_
[@igorskyflyer/normalized-string](https://www.npmjs.com/package/@igorskyflyer/normalized-string)
> _💊 NormalizedString provides you with a String type with consistent line-endings, guaranteed. 📮_
[@igorskyflyer/astro-escaped-component](https://www.npmjs.com/package/@igorskyflyer/astro-escaped-component)
> _🏃🏻♂️➡️ An Astro component that holds only HTML-encoded content. 📜_
[@igorskyflyer/strip-html](https://www.npmjs.com/package/@igorskyflyer/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*](https://github.com/igorskyflyer/)).