# randexp

> Create random strings that match a given regular expression.

Latest version **0.5.3** (published 2018-07-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install randexp
pnpm add randexp
yarn add randexp
bun add randexp
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2018-07-21 |
| First published | 2011-12-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 2 |
| Unpacked size | 13.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1866 |
| Author | fent |
| Maintainers | fent |
| Keywords | regex, regexp, regular expression, random, test |

## Links

- npm: https://www.npmjs.com/package/randexp
- Repository: https://github.com/fent/randexp.js
- Homepage: http://fent.github.io/randexp.js/
- Issues: https://github.com/fent/randexp.js/issues
- npm.io page: https://npm.io/package/randexp

## Dependencies (2)

- [ret](https://npm.io/package/ret.md) ^0.2.0
- [drange](https://npm.io/package/drange.md) ^1.0.2

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 0.5.3 (latest) — 2018-07-21
- 0.4.9 — 2018-02-27
- 0.5.2 — 2018-02-23
- 0.4.8 — 2018-02-15
- 0.5.1 — 2018-02-11
- 0.5.0 — 2018-02-10
- 0.4.7 — 2018-02-10
- 0.4.6 — 2017-08-10
- 0.4.5 — 2017-03-03
- 0.4.4 — 2016-12-05
- 0.4.3 — 2016-07-18
- 0.4.2 — 2015-12-02
- 0.4.1 — 2015-09-27
- 0.4.0 — 2014-09-19
- 0.3.4 — 2014-06-28
- … 5 more at https://npm.io/package/randexp/versions

## README

# randexp.js

randexp will generate a random string that matches a given RegExp Javascript object.

[![Build Status](https://secure.travis-ci.org/fent/randexp.js.svg)](http://travis-ci.org/fent/randexp.js)
[![Dependency Status](https://david-dm.org/fent/randexp.js.svg)](https://david-dm.org/fent/randexp.js)
[![codecov](https://codecov.io/gh/fent/randexp.js/branch/master/graph/badge.svg)](https://codecov.io/gh/fent/randexp.js)

# Usage

```js
const RandExp = require('randexp');

// supports grouping and piping
new RandExp(/hello+ (world|to you)/).gen();
// => hellooooooooooooooooooo world

// sets and ranges and references
new RandExp(/<([a-z]\w{0,20})>foo<\1>/).gen();
// => <m5xhdg>foo<m5xhdg>

// wildcard
new RandExp(/random stuff: .+/).gen();
// => random stuff: l3m;Hf9XYbI [YPaxV>U*4-_F!WXQh9>;rH3i l!8.zoh?[utt1OWFQrE ^~8zEQm]~tK

// ignore case
new RandExp(/xxx xtreme dragon warrior xxx/i).gen();
// => xxx xtReME dRAGON warRiOR xXX

// dynamic regexp shortcut
new RandExp('(sun|mon|tue|wednes|thurs|fri|satur)day', 'i');
// is the same as
new RandExp(new RegExp('(sun|mon|tue|wednes|thurs|fri|satur)day', 'i'));
```

If you're only going to use `gen()` once with a regexp and want slightly shorter syntax for it

```js
const randexp = require('randexp').randexp;

randexp(/[1-6]/); // 4
randexp('great|good( job)?|excellent'); // great
```

If you miss the old syntax

```js
require('randexp').sugar();

/yes|no|maybe|i don't know/.gen(); // maybe
```

# Motivation

Regular expressions are used in every language, every programmer is familiar with them. Regex can be used to easily express complex strings. What better way to generate a random string than with a language you can use to express the string you want?

Thanks to [String-Random](http://search.cpan.org/~steve/String-Random-0.22/lib/String/Random.pm) for giving me the idea to make this in the first place and [randexp](https://github.com/benburkert/randexp) for the sweet `.gen()` syntax.

# Default Range

The default generated character range includes printable ASCII. In order to add or remove characters,
a `defaultRange` attribute is exposed. you can `subtract(from, to)` and `add(from, to)`
```js
const randexp = new RandExp(/random stuff: .+/);
randexp.defaultRange.subtract(32, 126);
randexp.defaultRange.add(0, 65535);
randexp.gen();
// => random stuff: 湐箻ໜ䫴␩⶛㳸長���邓蕲뤀쑡篷皇硬剈궦佔칗븛뀃匫鴔事좍ﯣ⭼ꝏ䭍詳蒂䥂뽭
```

You can also change the default range by changing `RandExp.prototype.defaultRange`.

# Custom PRNG

The default randomness is provided by `Math.random()`. If you need to use a seedable or cryptographic PRNG, you
can override `RandExp.prototype.randInt` or `randexp.randInt` (where `randexp` is an instance of `RandExp`). `randInt(from, to)` accepts an inclusive range and returns a randomly selected number within that range.

# Infinite Repetitionals

Repetitional tokens such as `*`, `+`, and `{3,}` have an infinite max range. In this case, randexp looks at its min and adds 100 to it to get a useable max value. If you want to use another int other than 100 you can change the `max` property in `RandExp.prototype` or the RandExp instance.

```js
const randexp = new RandExp(/no{1,}/);
randexp.max = 1000000;
```

With `RandExp.sugar()`

```js
const regexp = /(hi)*/;
regexp.max = 1000000;
```

# Bad Regular Expressions

There are some regular expressions which can never match any string.

* Ones with badly placed positionals such as `/a^/` and `/$c/m`. Randexp will ignore positional tokens.

* Back references to non-existing groups like `/(a)\1\2/`. Randexp will ignore those references, returning an empty string for them. If the group exists only after the reference is used such as in `/\1 (hey)/`, it will too be ignored.

* Custom negated character sets with two sets inside that cancel each other out. Example: `/[^\w\W]/`. If you give this to randexp, it will return an empty string for this set since it can't match anything.


# Projects based on randexp.js


## JSON-Schema Faker

Use generators to populate JSON Schema samples. See: [jsf on github](https://github.com/json-schema-faker/json-schema-faker/) and [jsf demo page](http://json-schema-faker.js.org/).


# Install

### Node.js

    npm install randexp

### Browser

Download the [minified version](https://github.com/fent/randexp.js/releases) from the latest release.


# Tests

Tests are written with [mocha](https://mochajs.org)

```bash
npm test
```

# Integration with TypeScript

RandExp includes TypeScript definitions.

```typescript
import * as RandExp from "randexp";
const randexp = new RandExp(/[a-z]{6}/);
randexp.gen();
```

Use dtslint to check the definition file.

    npm install -g dtslint
    npm run dtslint

---
_Source: https://npm.io/package/randexp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._