Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thiagodp/better-randstr

🌞 Fully customizable random string generator. Test your applications better!
https://github.com/thiagodp/better-randstr

better custom customizable generate generation length rand rand-str random randstr str string unicode utf

Last synced: about 2 months ago
JSON representation

🌞 Fully customizable random string generator. Test your applications better!

Host: GitHub
URL: https://github.com/thiagodp/better-randstr
Owner: thiagodp
License: mit
Created: 2018-07-06T11:51:50.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2022-01-03T01:05:47.000Z (almost 3 years ago)
Last Synced: 2024-10-28T15:32:44.358Z (about 2 months ago)
Topics: better, custom, customizable, generate, generation, length, rand, rand-str, random, randstr, str, string, unicode, utf
Language: TypeScript
Homepage:
Size: 276 KB
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: readme.md
- License: LICENSE

Awesome Lists containing this project

README

        # better-randstr

[![Build Status](https://travis-ci.com/thiagodp/better-randstr.svg?branch=master)](https://travis-ci.com/thiagodp/better-randstr)

[![npm version](https://badge.fury.io/js/better-randstr.svg)](https://badge.fury.io/js/better-randstr)

> 🌞 Fully-customizable random string generator. Useful for testing applications, etc.

- Works with browsers, [NodeJS](https://nodejs.org/) and [DenoJS](https://deno.land/) (JavaScript 6+ and TypeScript)

- No external dependencies

- Unit-tested

- Semantic Versioning

- It can be used with your preferred pseudo-random generator (PRNG).

## Install

```bash

npm i better-randstr

```

## Declaration

### Browser

Global:

```html

<script>console.log( randstr() );

```

ESM:

```html

import { randstr } from 'https://unpkg.com/better-randstr/index.esm.js';

console.log( randstr() );

```

### NodeJS

```javascript

const { randstr } = require('better-randstr');

console.log( randstr() );

```

### Deno

```typescript

import { randstr } from 'https://unpkg.com/better-randstr/index.esm.js';

console.log( randstr() );

```

## Usage Examples

```javascript

// Default:

// - Up to 100 characters

// - No control characters

// - ASCII + ISO (UTF-8)

randstr();

// => ;Þë?Ç¡m{îU4I0_%L*qV

// Using a customized function as random function, instead of Math.random()

const myRandomFunc = /* a function that returns a number between 0 and 1 */ ;

randstr( { random: myRandomFunc } );

// => cy¦¼Óé6Lcy

// Exactly 10 characters

randstr( { length: 10 } );

// => »²y+iÀëC#Ù

// At least 10 characters

randstr( { length: [ 10 ] } );

// => ü¢ ß~å¿Û¿\ÓÜtÈ["ª9¡.:`i¡{ã«?®Q=>?v&ëÿ2"Âë

// At most 10 characters

randstr( { length: [ 0, 10 ] } );

// => È¹t×úÓ¯ÖÃj

// Between 2 and 60 characters

randstr( { length: [ 2, 60 ] } );

// => ZÔýÛÏaæ»û_Eâo9¨§:Çu!ÕÄø|FNß¨j)1n¦Í:

// Exactly 10 characters, with only the specified characters

randstr( { length: 10, chars: 'ABC123' } );

// => A31AAB3AB1

// Exactly 10 characters, only characters in the range, no control characters

randstr( { length: 10, chars: [ 32, 127 ] } ); // ASCII range

// => EA*bY7{*cL

// Exactly 10 characters, between 'A' and 'Z'

randstr( { length: 10, chars: [ 'A'.charCodeAt( 0 ), 'Z'.charCodeAt( 0 ) ] } );

// => SPQJNORXXR

// Exactly 10 characters, only numbers

const NUMBERS = require( 'better-randstr' ).NUMBERS;

randstr( { length: 10, chars: NUMBERS } ) // same as passing '0123456789'

// => 7450625283

// Exactly 10 characters, alfanumeric

const ALPHA_NUMERIC = require( 'better-randstr' ).ALPHA_NUMERIC;

randstr( { length: 10, chars: ALPHA_NUMERIC } );

// => s1wMa7QVmg

// Exactly 10 characters, all characters in ASCII/ISO (UTF-8) except the specified

randstr( { length: 10, acceptable: function( chr ) {

    return '%#&$'.indexOf( chr ) < 0; // acceptable if not found

} } );

// => ´NvÄ~]¿Gº]

// Exactly 10 characters, escaping quotes and single-quotes

randstr( { length: 10, replacer: function( chr ) {

    switch ( chr ) {

        case '"': return '\\"';

        case "'": return "\\'";

    }

    return chr;

} } );

// => ñ;}éÔÝf«\'

// Include control characters

randstr( { includeControlChars: true } );

// => x@HA$÷°GÝ³:^Ê%¼¤®ý±#Sh+Ò+Å|

// Wider range than UTF-8 - control characters not avoided!

randstr( { chars: [ 32, 1000 ] } );

// => r΅4ƹǭ̻ɍĿΠsɊQȍάĠĲȤċƳȭɧĄƹĜʋ͏Ʒȥĭ˟͢"Ȓǭ̼Ζ˂̀ƖǛ̚3&΃ƏϧȷɥŃ

```

See [example.js](examples/example.js)

## API

```typescript

function randstr( options: Options ): string;

```

where `Options` is :

```typescript

{

    /**

     * Random function to be used. By default, it assumes `Math.random()`.

     *

     * The function does not expect arguments and must return a number between 0 and 1.

     */

    random?: function () => number;

    /**

     * Length or length range. By default, it assumes `[ 0, 100 ]`.

     *

     * - Number: Minimum and maximum length will be equal to the provided number. Example: `{ length: 20 }`.

     * - One-length array: Maximum will be a random number greater than or equal to the minimum. Example: `{ length: [ 2 ] }`.

     * - Two-length array: Minimum and maximum length will assume the provided numbers. Example: `{ length: [ 0, 50 ] }`.

     */

    length?: number | number[];

    /**

     * Allowed characters or byte range. By default, it assumes `[32, 255]`

     * which is a range containing the first printable ASCII character (`32`)

     * and the last ISO character (`255`).

     *

     * For example, `"0123456789"`, which gives the same result as

     * `['0'.charCodeAt(0), '9'.charCodeAt(0)]`.

     */

    chars?: string | number[];

    /**

     * Function that evaluates whether the generated character is acceptable.

     * By default, it is `undefined`.

     * The function expects a character and returns a boolean.

     */

    acceptable?: function ( string ) => boolean;

    /**

     * Function that replaces a character by other character or characters.

     * By default, it is `undefined`.

     * You may use it for escaping or replacing certain characters, for example.

     */

    replacer?: function ( string ) => string;

    /**

     * Whether is desired to include control characters. By default, it is `false`.

     */

    includeControlChars?: boolean;

}

```

## See also

- [one-wise](https://github.com/thiagodp/one-wise) - One-wise combinatorial testing generator

- [seedrandom](https://github.com/davidbau/seedrandom) - Predictive PRNG

- [spec-pattern](https://github.com/thiagodp/spec-pattern) - Build complex validation rules or filters easily.

## License

[MIT](LICENSE) © [Thiago Delgado Pinto](https://github.com/thiagodp)