https://github.com/igorskyflyer/npm-scramble
๐ Scrambles (rearranges randomly) Strings and Arrays. ๐
https://github.com/igorskyflyer/npm-scramble
algorithm array back-end fisher-yates-shuffle igorskyflyer javascript js node random scramble shuffle string ts typescript
Last synced: 5 months ago
JSON representation
๐ Scrambles (rearranges randomly) Strings and Arrays. ๐
- Host: GitHub
- URL: https://github.com/igorskyflyer/npm-scramble
- Owner: igorskyflyer
- License: mit
- Created: 2024-08-03T23:04:00.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-04T20:10:49.000Z (almost 2 years ago)
- Last Synced: 2025-03-07T09:37:33.895Z (over 1 year ago)
- Topics: algorithm, array, back-end, fisher-yates-shuffle, igorskyflyer, javascript, js, node, random, scramble, shuffle, string, ts, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@igor.dvlpr/scramble
- Size: 38.1 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
ScRaMbLe
๐ Scrambles (rearranges randomly) Strings and Arrays. ๐
## ๐ Table of Contents
- [Features](#-features)
- [Usage](#-usage)
- [API](#-api)
- [scrambleString()](#scramblestringinput-string-options-istringoptions-string)
- [scrambleArray()](#scramblearrayarraytypeinput-arraytype-arraytype)
- [Examples](#๏ธ-examples)
- [Changelog](#-changelog)
- [Support](#-support)
- [License](#-license)
- [Related](#-related)
- [Author](#-author)
## ๐ค Features
- ๐ฏ Scrambles words while keeping first and last letters intact for readability
- ๐งฉ Shuffles array elements with a proven Fisher Yates algorithm
- โ๏ธ Optional whitespace trimming before scrambling text
- ๐ก๏ธ Validates inputs and throws clear, descriptive errors
- โก Zero dependencies for lightweight, fast execution
- ๐ Pure functions that donโt mutate original data
- ๐ง Works with any array type thanks to TypeScript generics
- ๐ Well-documented with clear parameter and return descriptions
- ๐งช Perfect for games, puzzles, mock data, and creative text effects
## ๐ต๐ผ Usage
Install it by executing any of the following, depending on your preferred package manager:
```bash
pnpm add @igorskyflyer/scramble
```
```bash
yarn add @igorskyflyer/scramble
```
```bash
npm i @igorskyflyer/scramble
```
## ๐คน๐ผ API
### `scrambleString(input: string, options?: IStringOptions): string`
*Scrambles the characters of each word in a given string.*
`input` - The string to be scrambled.
> โน๏ธ **NOTE**
>
> Since `Fisher-Yates` algorithm is used for scrambling, a length of > 3 is needed for a word to be able to get scrambled.
>
`options` - Options for scrambling, **optional**.
`options` are defined via an interface `IStringOptions`:
```ts
interface IStringOptions {
trimWhitespace?: boolean
}
```
`trimWhitespace`, if true all whitespace is removed from the input string prior to scrambling its contents.
Returns the scrambled string.
Will throw an error if the input is not a string.
---
### `scrambleArray(input: ArrayType[]): ArrayType[]`
*Scrambles the elements of an array.*
`input` - The array to be scrambled.
Returns the scrambled array.
Will throw an error if the input is not an array.
## ๐๏ธ Examples
`example.mts`
```ts
import { scrambleString, scrambleArray } from '@igorskyflyer/scramble'
// these are just sample outputs
// since each invocation reorders
// elements randomly
console.log(scrambleString(
'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
)) // returns 'Leorm isupm dloor sit aetm, ccotnsueetr asdincipig eitl.'
console.log(scrambleString(
'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', { trimWhitespace: true }
)) // returns 'Lpetssgerodcsctcmuaunelrteiisoomirlait,toindmipe.'
console.log(scrambleArray([1, 2, 3, 4, 5, 6, 7, 8])) // [5, 7, 1, 4, 2, 8, 3, 6]
```
## ๐ Changelog
๐ The changelog is available here, [CHANGELOG.md](https://github.com/igorskyflyer/npm-scramble/blob/main/CHANGELOG.md).
## ๐ชช License
Licensed under the MIT license which is available here, [MIT license](https://github.com/igorskyflyer/npm-scramble/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/uarray](https://www.npmjs.com/package/@igorskyflyer/uarray)
> _๐ Provides UArray, an Array type that supports negative indices/indexes, just wrap your regular JavaScript array with UArray() and you are all set! ๐_
[@igorskyflyer/magic-string](https://www.npmjs.com/package/@igorskyflyer/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. ๐ฆฅ_
[@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. โจ_
[@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/duoscribi](https://www.npmjs.com/package/@igorskyflyer/duoscribi)
> _โ DรบรถScrรญbรฎ allows you to convert letters with diacritics to regular letters. ๐ค_
## ๐จ๐ปโ๐ป Author
Created by **Igor Dimitrijeviฤ** ([*@igorskyflyer*](https://github.com/igorskyflyer/)).