referral-codes v3.0.0

Referral Code Generator

Generate unique, random, and hard to guess coupon / voucher codes. Use cases: promo codes, loyalty coupons, gift vouchers, in-app purchases, referral links

This library originates from voucher-code-generator.

I re-wrote this library using the same API, but with more modern syntax and more performant constructs.

Installation

Install with yarn:

$ yarn add referral-codes

Install with npm:

$ npm install -save referral-codes

Usage

Generate 5 codes, each 8 characters long:

referralCodes.generate({
  length: 8,
  count: 5,
});

Sample result: ["FR6bwx1q", "ByamOdWV", "7roFwfQs", "rmWlwvll", "pgih5eAB"]

Charset

Default charset is alphanumeric (numbers and letters). However, you can specify your own charset:

referralCodes.generate({
  length: 6,
  count: 3,
  charset: '0123456789',
});

Sample result: ["386525", "676442", "019075"]

You can also use one of the predefined charsets by calling referralCodes.charset(name).

Constants for these defaults can also be used to avoid issues with misspellings and help with intellisense

For example:

referralCodes.generate({
  length: 5,
  count: 4,
  charset: referralCodes.charset('alphabetic'),
});

or

referralCodes.generate({
  length: 5,
  count: 4,
  charset: referralCodes.charset(referralCodes.Charset.ALPHABETIC),
});

Result: ["odghy", "kZEYc", "eOTCl", "wVCzD"]

Prefix and Postfix

You can optionally surround each generated code with a prefix and/or postfix.

For instance:

referralCodes.generate({
  prefix: 'promo-',
  postfix: '-2015',
});

Result: ["promo-WZ4x1t3U-2015"]

Pattern

Codes may follow a specified pattern. Use hash (#) as a placeholder for random characters. Note that if pattern is specified then length is ignored.

Example:

referralCodes.generate({
  pattern: '##-###-##',
});

Result: ["P7-ofW-Ka"]

Infeasible configs

There exist some configs that are not feasible. For example it's not possible to generate 1500 codes if you want your codes to be 2 characters long and consisting only of numbers. Referral code generator detects such cases and throws an error "Not possible to generate requested number of codes.".

try {
    referralCodes.generate({
        count: 1500,
        length: 2,
        charset: "0123456789"
    })
catch (e) {
    console.log("Sorry, not possible.");
}

Config reference

Testing

Install dependencies:

$ yarn

Run tests:

$ yarn test

Benchmarks

Benchmarks were run using the benchmark library on a 2019 Macbook Pro 2.6Ghz 6-Core Intel i7 with 32GB 2667MHz RAM

with 10 codes x 212,877 ops/sec ±1.81% (84 runs sampled)
with 100 codes x 24,421 ops/sec ±1.50% (86 runs sampled)
with 1000 codes x 2,278 ops/sec ±1.50% (84 runs sampled)

Run benchmarks:

$ yarn benchmark

License

Code released under the MIT license.