Referral Codes

https://github.com/zack37/referral-codes
Admin
A high-performance JavaScript library for generating unique, random, and customizable referral,...
Tokens:15,695
Snippets:116
Trust Score:5.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install Dependencies for Testing

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Install dependencies for testing.

```sh
$ yarn
```

--------------------------------

### Install with Yarn

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Install the referral-codes package using the Yarn package manager.

```sh
$ yarn add referral-codes
```

--------------------------------

### Basic usage of generate() with defaults

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Shows how to import and call generate() with default options (length: 8, count: 1). The example requests 5 codes and logs them to the console.

```ts
import { generate } from 'referral-codes';

const codes = generate({ length: 8, count: 5 });
console.log(codes); // e.g. ["FR6bwx1q", "ByamOdWV", "7roFwfQs", "rmWlwvll", "pgih5eAB"]
```

--------------------------------

### Install with npm

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Install the referral-codes package using npm. Note: the -save flag is deprecated in modern npm versions.

```sh
$ npm install -save referral-codes
```

--------------------------------

### generate(config)

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Documentation for the generate function, including parameters, return type, errors, and examples.

```APIDOC
## `generate(config)` — generate unique codes

### Description
Generates an array of unique referral codes based on the provided configuration. The function validates the configuration, checks feasibility, and returns exactly the requested number of unique codes.

### Method
Function call

### Endpoint
`generate(config: Config): string[]`

### Parameters
#### Function Parameters
- **`config`** (`Config`) - Required (per type) - Options object; every field is optional. Defaults: `count: 1`, `length: 8`, `charset: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'`, `prefix: ''`, `postfix: ''`, `pattern: '#'.repeat(length)`.

### Return Type
`string[]` — an array of exactly `count` unique codes. Uniqueness is enforced via a `Set`; the loop redraws whenever a collision occurs. Order is insertion order of first successful draw.

### Throws
- **`Error`** with message `'Not possible to generate requested number of codes.'` when `charset.length ** (number of '#' placeholders in pattern) < count`.

### Examples

Basic call — defaults (`length: 8`, `count: 1`):

```ts
import { generate } from 'referral-codes';

const codes = generate({ length: 8, count: 5 });
console.log(codes); // e.g. ["FR6bwx1q", "ByamOdWV", "7roFwfQs", "rmWlwvll", "pgih5eAB"]
```

Error handling — infeasible configuration:

```ts
import { generate } from 'referral-codes';

try {
  // Only 12^2 = 144 distinct 2-char codes exist; 1500 are requested.
  generate({ count: 1500, length: 2, charset: '0123456789' });
} catch (error) {
  if (
    error instanceof Error &&
    error.message === 'Not possible to generate requested number of codes.'
  ) {
    console.log('Sorry, not possible.');
  }
}
```

Non-trivial options — pattern, prefix, postfix, named charset:

```ts
import { Charset, generate } from 'referral-codes';

const codes = generate({
  count: 3,
  pattern: '##-###-##', // length is ignored when pattern is set
  charset: Charset.NUMBERS,
  prefix: 'P-',
  postfix: '-X',
});
console.log(codes); // e.g. ["P-32-198-07-X", "P-41-205-99-X", "P-86-110-43-X"]
```

### Edge Behaviors
- `count: 0` → returns `[]` (feasibility holds, loop never runs).
- Pattern with zero `#` placeholders → feasible only for `count ≤ 1`; with `count: 1` returns a single fixed code, e.g. `generate({ count: 1, pattern: 'FIXED' })` → `['FIXED']`.
- `prefix`/`postfix` are prepended/appended after pattern expansion, so they do not affect uniqueness or the feasibility calculation (only `#` positions count).
```

--------------------------------

### Configurations that trigger the generation error

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Concrete configurations that trigger the error because the feasible space is smaller than the requested count. The first example is also the README example. Each throws an Error with the message 'Not possible to generate requested number of codes.'.

```javascript
generate({ count: 1500, length: 2, charset: '0123456789' })
```

```javascript
generate({ count: 1000, length: 5, charset: 'abc' })
```

```javascript
generate({ count: 2, pattern: 'FIXED' })
```

--------------------------------

### Error handling for infeasible configuration

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Demonstrates catching the error thrown when the requested number of codes exceeds the possible distinct codes. The example requests 1500 codes with length 2 and numeric charset, which only allows 144 distinct codes.

```ts
import { generate } from 'referral-codes';

try {
  // Only 12^2 = 144 distinct 2-char codes exist; 1500 are requested.
  generate({ count: 1500, length: 2, charset: '0123456789' });
} catch (error) {
  if (
    error instanceof Error &&
    error.message === 'Not possible to generate requested number of codes.'
  ) {
    console.log('Sorry, not possible.');
  }
}
```

--------------------------------

### Pre-check feasibility with canGenerate

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Avoid the throw by pre-checking feasibility with the same predicate used internally: count must be <= charset.length ** number of '#' placeholders in the pattern. The example checks canGenerate before calling generate.

```ts
import { generate } from 'referral-codes';

function canGenerate(charset: string, pattern: string, count: number): boolean {
  const placeholders = [...pattern].filter((c) => c === '#').length;
  return charset.length ** placeholders >= count;
}

if (canGenerate('0123456789', '##', 5)) {
  const codes = generate({ pattern: '##', charset: '0123456789', count: 5 });
}
```

--------------------------------

### Error - "Not possible to generate requested number of codes."

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Documentation for the sole error-throwing code path in the referral-codes library, describing the error message, trigger conditions, and examples.

```APIDOC
## Error - "Not possible to generate requested number of codes."

### Description
Thrown when the requested configuration admits fewer distinct codes than requested. The feasibility predicate is `charset.length ** (number of '#' placeholders in pattern) < count`.

### Trigger Condition
- `charset.length ** (number of '#' placeholders in pattern) < count`

### Examples of Configs That Trigger
- `generate({ count: 1500, length: 2, charset: '0123456789' })`
- `generate({ count: 1000, length: 5, charset: 'abc' })`
- `generate({ count: 2, pattern: 'FIXED' })`

### Examples of Configs That Do Not Trigger
- `generate({ count: 5, length: 2 })`
- `generate({ count: 1, pattern: 'FIXED' })`
- `generate({ count: 0 })`
- `generate({ count: 2, length: 1, charset: 'ab' })`
```

--------------------------------

### charset

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Resolves a Charset name to its character string. Use this to get the character set for a given charset name.

```APIDOC
## charset

### Description
Resolves a Charset name to its character string. Use this to get the character set for a given charset name.

### Method
Function

### Signature
`charset(name: Charset): string`

### Parameters
- **name** (Charset) - Required - The charset name (e.g., `Charset.NUMBERS`).

### Returns
- **string** - The character string corresponding to the charset.

### Example
```js
import { charset, Charset } from 'referral-codes';
const chars = charset(Charset.ALPHANUMERIC);
```
```

--------------------------------

### Run Benchmarks

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Run the benchmark suite.

```sh
$ yarn benchmark
```

--------------------------------

### Import Charset, generate, and Config from 'referral-codes'

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

Shows how to import the two exported types and the generate function from the package root.

```typescript
import { Charset, generate } from 'referral-codes';
import type { Config } from 'referral-codes';
```

--------------------------------

### Run Tests

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Run the test suite.

```sh
$ yarn test
```

--------------------------------

### Non-trivial options: pattern, prefix, postfix, named charset

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Shows how to use pattern, prefix, postfix, and a named charset (Charset.NUMBERS) together. The length option is ignored when pattern is set.

```ts
import { Charset, generate } from 'referral-codes';

const codes = generate({
  count: 3,
  pattern: '##-###-##', // length is ignored when pattern is set
  charset: Charset.NUMBERS,
  prefix: 'P-',
  postfix: '-X',
});
console.log(codes); // e.g. ["P-32-198-07-X", "P-41-205-99-X", "P-86-110-43-X"]
```

--------------------------------

### Generate Codes with Prefix and Postfix

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate a code with a prefix and postfix. Sample result: ["promo-WZ4x1t3U-2015"]

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

--------------------------------

### generate(config: Config): string[]

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

The `generate` function accepts a `Config` object and returns an array of generated referral codes.

```APIDOC
## `generate(config: Config): string[]`

### Description
Generates an array of unique referral codes based on the provided configuration.

### Parameters
- **config** (`Config`) - Required - The configuration options for code generation.

### Returns
- **string[]** - An array of generated referral codes.
```

--------------------------------

### generateOne(config)

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Documentation for the generateOne function, which builds a single referral code.

```APIDOC
## `generateOne(config)` — build a single code

### Description
Generates a single referral code by replacing `#` placeholders in a pattern with random characters from a charset, then wrapping the result with a prefix and postfix.

### Method
Function call

### Endpoint
`generateOne(config)`

### Parameters
#### Function Parameters
- **pattern** (string) - Required - Code template; every `#` character is replaced with a random character drawn from `charset`; every non-`#` character is copied verbatim
- **charset** (string) - Required - Character pool used to fill `#` placeholders (a plain string of characters, e.g. `'0123456789'`)
- **prefix** (string) - Required - Text prepended to the finished code
- **postfix** (string) - Required - Text appended to the finished code

### Request Example
```ts
import { Charset, charset, generateOne } from 'referral-codes';

const code = generateOne({
  pattern: '##-####-##',
  charset: charset(Charset.ALPHANUMERIC),
  prefix: 'promo-',
  postfix: '-2024',
});
console.log(code); // e.g. "promo-7f-K3x9-sL-2024"
```

### Response
#### Success Response
- **return** (string) - `prefix` + the pattern with `#` placeholders replaced + `postfix`. Example: `{ pattern: '##-###-##', charset: 'abc', prefix: 'X-', postfix: '-Y' }` → e.g. `'X-ca-bab-bc-Y'`.

#### Response Example
```ts
// Example output
"promo-7f-K3x9-sL-2024"
```

### Throws
Never throws. Note that with an empty `pattern` the code body is `''` and the result is just `` `${prefix}${postfix}` ``.
```

--------------------------------

### Benchmark Results

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Benchmark results from running the benchmark library on a 2019 Macbook Pro 2.6Ghz 6-Core Intel i7 with 32GB 2667MHz RAM.

```text
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)
```

--------------------------------

### generateOne

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Builds a single code from a fully-resolved config. Useful when you need just one code.

```APIDOC
## generateOne

### Description
Builds a single code from a fully-resolved config. Useful when you need just one code.

### Method
Function

### Signature
`generateOne(config: Config): string`

### Parameters
- **config** (Config) - Required - Fully-resolved configuration object.

### Returns
- **string** - A single generated code.

### Example
```js
import { generateOne } from 'referral-codes';
const code = generateOne({ length: 10 });
```
```

--------------------------------

### generateOne implementation and parameter type

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

The generateOne function builds a single code from a pattern, charset, prefix, and postfix. It replaces each '#' placeholder with a random character from the charset and prepends/appends the prefix/postfix. The inline-expanded parameter type shows the required shape of the config object.

```ts
export const generateOne = ({
  pattern,
  charset,
  prefix,
  postfix,
}: Required<
  Pick<Config, 'pattern' | 'charset' | 'prefix' | 'postfix'>
>): string => {
  // Uses for_of loop for performance reasons
  let code = '';
  for (const p of pattern) {
    const c = p === placeholder ? randomElement(charset) : p;
    code += c;
  }

  return `${prefix}${code}${postfix}`;
};
```

```ts
{
  pattern: string;
  charset: string;
  prefix: string;
  postfix: string;
}
```

--------------------------------

### Using Charset enum with generate()

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Shows how to use the Charset enum with generate() to avoid string literals. Generates 5 codes of length 5 using the alphabetic character set.

```ts
import { Charset, generate } from 'referral-codes';

const codes = generate({
  count: 5,
  length: 5,
  charset: Charset.ALPHABETIC,
});
```

--------------------------------

### Generate Codes with Predefined Charset (Constant)

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate codes using the predefined 'alphabetic' charset via the Charset constant. Sample result: ["odghy", "kZEYc", "eOTCl", "wVCzD"]

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

--------------------------------

### Charset enum and charset() function

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Documentation for the Charset enum and the charset() function from the referral-codes library.

```APIDOC
## `Charset` (enum)

String-valued enum; the declared value of each member is its string name.

| Member | Value | Resolved character set |
|--------|-------|------------------------|
| `Charset.NUMBERS` | `'numbers'` | `'0123456789'` |
| `Charset.ALPHABETIC` | `'alphabetic'` | `'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'` |
| `Charset.ALPHANUMERIC` | `'alphanumeric'` | `'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'` |

**Used by:** `charset(name)` (accepted as argument); intended to be passed through to `generate({ charset })` to avoid misspellings; see [types.md](../types.md).

**Example — avoid string literals:**

```ts
import { Charset, generate } from 'referral-codes';

const codes = generate({
  count: 5,
  length: 5,
  charset: Charset.ALPHABETIC,
});
```
```

```APIDOC
## `charset(name)` — resolve a charset name

### Description
Resolves a `Charset` enum member to its corresponding character pool string. This function is intended to be used with `generate({ charset })` to avoid misspellings.

### Method
Function call

### Endpoint
`charset(name: Charset): string`

### Parameters
- `name` (Charset) - Required - A member of the `Charset` enum: `'numbers'`, `'alphabetic'`, or `'alphanumeric'`.

### Return Type
`string` — the character pool for the given name:
- `charset(Charset.NUMBERS)` → `'0123456789'`
- `charset(Charset.ALPHABETIC)` → `'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'`
- `charset(Charset.ALPHANUMERIC)` → `'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'`

### Throws
Never throws. **Caveat:** the runtime performs no validation of `name`. Because the parameter is typed as `Charset` but JavaScript callers can pass any string, an unrecognized name (e.g. `charset('klingon')`) returns `undefined` at runtime — the declared `string` return type is not enforced. TypeScript callers are protected at compile time.

### Examples
Basic usage:

```ts
import { Charset, charset, generate } from 'referral-codes';

const letters = charset(Charset.ALPHABETIC);
const codes = generate({ length: 5, count: 4, charset: letters });
console.log(codes); // e.g. ["odghy", "kZEYc", "eOTCl", "wVCzD"]
```

Enum vs. string equivalence:

```ts
import { Charset, charset } from 'referral-codes';

charset(Charset.NUMBERS) === charset('numbers'); // true — both '0123456789'
```
```

--------------------------------

### Generate Codes with Predefined Charset (String)

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate codes using the predefined 'alphabetic' charset via the charset() method. Sample result: ["odghy", "kZEYc", "eOTCl", "wVCzD"]

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

--------------------------------

### Basic charset() usage

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Basic usage of charset() to obtain a character pool and pass it to generate(). The output is an array of random codes, e.g. ["odghy", "kZEYc", "eOTCl", "wVCzD"].

```ts
import { Charset, charset, generate } from 'referral-codes';

const letters = charset(Charset.ALPHABETIC);
const codes = generate({ length: 5, count: 4, charset: letters });
console.log(codes); // e.g. ["odghy", "kZEYc", "eOTCl", "wVCzD"]
```

--------------------------------

### Configurations that do not throw the generation error

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Configurations that do not throw, derived from the same feasibility predicate. They are feasible and return the expected codes: ['FIXED'] for the second, [] for the third, and the fourth retries until both codes are drawn.

```javascript
generate({ count: 5, length: 2 })
```

```javascript
generate({ count: 1, pattern: 'FIXED' })
```

```javascript
generate({ count: 0 })
```

```javascript
generate({ count: 2, length: 1, charset: 'ab' })
```

--------------------------------

### Generate Codes with Pattern

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate a code following a pattern where '#' is a placeholder for random characters. Note: if pattern is specified, length is ignored. Sample result: ["P7-ofW-Ka"]

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

--------------------------------

### referralCodes.charset(name)

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Returns a predefined charset string by name, which can be used as the `charset` option in `generate`.

```APIDOC
## referralCodes.charset(name)

### Description
Returns the predefined charset string for the given name. Useful for specifying a charset without misspelling.

### Method
Function call

### Endpoint
referralCodes.charset(name)

### Parameters
- **name** (string) - Required - The name of the predefined charset. Possible values: `"numbers"`, `"alphabetic"`, `"alphanumeric"`.

### Request Example
```js
referralCodes.charset('alphabetic')
```

### Response
#### Success Response
Returns the charset string corresponding to the given name.

#### Response Example
```js
"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
```
```

--------------------------------

### Handle Infeasible Configurations

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Handle infeasible configurations. The generator throws an error "Not possible to generate requested number of codes." when the requested count cannot be generated with the given length and charset.

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

--------------------------------

### createConfig defaulting and precedence logic

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/configuration.md

Internal normalizer that fills missing configuration fields with defaults using nullish coalescing. Explicit `null` is treated as absent, but falsy values like `0` and `''` are preserved; the default pattern is derived from `length` only when `pattern` is not set.

```ts
const createConfig = (config: Config = {}): Required<Config> => ({
  count: config.count ?? 1,
  length: config.length ?? 8,
  charset: config.charset ?? charset(Charset.ALPHANUMERIC),
  prefix: config.prefix ?? '',
  postfix: config.postfix ?? '',
  pattern: config.pattern ?? placeholder.repeat(config.length ?? 8),
});
```

--------------------------------

### generate(config) function implementation

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

The core implementation of the generate function. It validates the config, checks feasibility, and generates unique codes using a Set to avoid duplicates. Throws an error if the requested number of codes cannot be generated.

```ts
export const generate = (config: Config): string[] => {
  const validatedConfig = createConfig(config);
  const { charset, count, pattern } = validatedConfig;

  if (!isFeasible(charset, pattern, count)) {
    throw new Error('Not possible to generate requested number of codes.');
  }

  const codes = new Set<string>();
  while (codes.size < count) {
    codes.add(generateOne(validatedConfig));
  }

  return [...codes];
};
```

--------------------------------

### Config

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

The `Config` type alias defines the options for generating referral codes. It is accepted by the `generate` function and a sub-shape is accepted by `generateOne`.

```APIDOC
## `Config` — generation options (type alias)

### Description
Defines the configuration options for generating referral codes. All fields are optional and defaults are applied at runtime.

### Type
```ts
export type Config = {
  length?: number;
  count?: number;
  charset?: string;
  prefix?: string;
  postfix?: string;
  pattern?: string;
};
```

### Fields
- **length** (`number`) - Optional - Number of characters in each generated code body (excludes `prefix`/`postfix`). Default `8`. **Ignored when `pattern` is set.**
- **count** (`number`) - Optional - Number of unique codes to generate. Default `1`.
- **charset** (`string`) - Optional - Character pool the random characters are drawn from. Default: `'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'`.
- **prefix** (`string`) - Optional - Text prepended to every generated code. Default `''`.
- **postfix** (`string`) - Optional - Text appended to every generated code. Default `''`.
- **pattern** (`string`) - Optional - Code template in which every `#` is replaced with a random character. Default `'#'.repeat(length)`.
```

--------------------------------

### generateOne with fixed pattern and custom charset

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Non-trivial usage: a fixed pattern without placeholders returns the pattern unchanged, and a custom charset constrains the output characters. The second call with a binary charset produces only binary digits.

```ts
import { generateOne } from 'referral-codes';

generateOne({ pattern: 'FIXED', charset: 'xyz', prefix: '', postfix: '' });
// => "FIXED" (unchanged, no placeholders)

generateOne({ pattern: '##', charset: '01', prefix: 'b', postfix: 'e' });
// => "b01e", "b11e", "b00e", ... only binary digits
```

--------------------------------

### Config type

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Options object accepted by generate. It defines the parameters for code generation.

```APIDOC
## Config type

### Description
Options object accepted by generate. It defines the parameters for code generation.

### Properties
- **length** (number) - Optional - Length of each code.
- **count** (number) - Optional - Number of codes to generate.
- **charset** (Charset | string) - Optional - Character set to use.
- **prefix** (string) - Optional - Prefix for each code.
- **suffix** (string) - Optional - Suffix for each code.
- **pattern** (string) - Optional - Pattern for code generation.

### Example
```js
const config = { length: 10, count: 5, charset: Charset.ALPHANUMERIC };
```
```

--------------------------------

### Basic generateOne call

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Basic usage of generateOne with an alphanumeric charset and a pattern with placeholders. The result is a string like 'promo-7f-K3x9-sL-2024'.

```ts
import { Charset, charset, generateOne } from 'referral-codes';

const code = generateOne({
  pattern: '##-####-##',
  charset: charset(Charset.ALPHANUMERIC),
  prefix: 'promo-',
  postfix: '-2024',
});
console.log(code); // e.g. "promo-7f-K3x9-sL-2024"
```

--------------------------------

### Generate Codes with Default Settings

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate 5 codes, each 8 characters long. The default charset is alphanumeric. Sample result: ["FR6bwx1q", "ByamOdWV", "7roFwfQs", "rmWlwvll", "pgih5eAB"]

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

--------------------------------

### referralCodes.generate(options)

Source: https://github.com/zack37/referral-codes/blob/master/README.md

The main function to generate referral codes with configurable options such as length, count, charset, prefix, postfix, and pattern.

```APIDOC
## referralCodes.generate(options)

### Description
Generates a list of unique, random, and hard to guess coupon/voucher codes based on the provided configuration options.

### Method
Function call

### Endpoint
referralCodes.generate(options)

### Parameters
#### Options Object
- **length** (number) - Optional - Number of characters in a generated code (excluding prefix and postfix). Default: 8.
- **count** (number) - Optional - Number of codes to generate. Default: 1.
- **charset** (string) - Optional - Characters that can appear in the code. Default: alphanumeric.
- **prefix** (string) - Optional - A text appended before the code. Default: "".
- **postfix** (string) - Optional - A text appended after the code. Default: "".
- **pattern** (string) - Optional - A pattern for codes where hashes (`#`) will be replaced with random characters. If specified, `length` is ignored. Default: "########".

### Request Example
```js
referralCodes.generate({
  length: 8,
  count: 5,
});
```

### Response
#### Success Response
Returns an array of generated code strings.

#### Response Example
```js
["FR6bwx1q", "ByamOdWV", "7roFwfQs", "rmWlwvll", "pgih5eAB"]
```

### Error Handling
Throws an error `"Not possible to generate requested number of codes."` when the requested configuration is infeasible (e.g., count too high for the given length and charset).
```

--------------------------------

### ERROR - Not possible to generate requested number of codes.

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Documentation for the error thrown by the generate function and related error behavior.

```APIDOC
## ERROR [Error] Not possible to generate requested number of codes.

### Description
This error is thrown by the `generate` function when the requested number of codes cannot be generated given the charset and pattern constraints.

### Thrown By
`generate`

### Thrown When
When the combination of charset length, pattern placeholders, and requested count makes generation impossible.

### How to Catch
Use `try/catch` around the `generate` call, then check the error message.

### Example
```ts
import { generate } from 'referral-codes';

try {
  const codes = generate({
    count: 1500,
    length: 2,
    charset: '0123456789',
  });
  console.log(codes);
} catch (error) {
  if (
    error instanceof Error &&
    error.message === 'Not possible to generate requested number of codes.'
  ) {
    console.error('Sorry, not possible.');
  } else {
    throw error;
  }
}
```

### Discriminator
- The error is a plain `Error` instance. No custom class or `error.code`, `error.name` other than `'Error'` is available.

### Pre-check Alternative
Avoid the exception by checking feasibility before calling `generate`:
```ts
import { generate } from 'referral-codes';

function canGenerate(charset: string, pattern: string, count: number): boolean {
  const placeholders = [...pattern].filter((c) => c === '#').length;
  return charset.length ** placeholders >= count;
}

if (canGenerate('0123456789', '##', 5)) {
  const codes = generate({ pattern: '##', charset: '0123456789', count: 5 });
}
```

### Non-Existent Errors (Explicitly)
- No validation errors for unknown `Config` fields — extra keys are silently ignored.
- No errors from `charset(name)` — invalid names return `undefined`.
- No errors from `generateOne` — never throws.
- No asynchronous errors — all functions are synchronous.
- No HTTP/network errors — no I/O.
```

--------------------------------

### charset(name: Charset): string

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

The `charset` function accepts a `Charset` member and returns the corresponding character pool string.

```APIDOC
## `charset(name: Charset): string`

### Description
Returns the character pool string associated with the given `Charset` member.

### Parameters
- **name** (`Charset`) - Required - The charset member whose pool is to be returned.

### Returns
- **string** - The resolved character pool (e.g., `'0123456789'` for `Charset.NUMBERS`).
```

--------------------------------

### referralCodes.Charset

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Constants for the predefined charsets, providing a safer way to specify charsets in the generate function.

```APIDOC
## referralCodes.Charset

### Description
An enum-like object containing constants for the predefined charsets. Use these constants to avoid misspellings and improve intellisense.

### Method
Constant

### Endpoint
referralCodes.Charset

### Properties
- **NUMBERS** (string) - The numbers charset: `"0123456789"`.
- **ALPHABETIC** (string) - The alphabetic charset: `"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"`.
- **ALPHANUMERIC** (string) - The alphanumeric charset: `"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"`.

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

--------------------------------

### generate

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Generates an array of unique codes from a Config object. This is the primary function for creating multiple codes at once.

```APIDOC
## generate

### Description
Generates an array of unique codes from a Config object. This is the primary function for creating multiple codes at once.

### Method
Function

### Signature
`generate(config: Config): string[]`

### Parameters
- **config** (Config) - Required - Options object for code generation.

### Returns
- **string[]** - An array of unique code strings.

### Example
```js
import { generate } from 'referral-codes';
const codes = generate({ length: 10, count: 5 });
```
```

--------------------------------

### Generate Codes with Custom Charset

Source: https://github.com/zack37/referral-codes/blob/master/README.md

Generate codes using a custom charset of only numbers. Sample result: ["386525", "676442", "019075"]

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

--------------------------------

### Catch generate error with try/catch

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Use try/catch to handle the synchronous Error thrown by generate when the requested number of codes cannot be generated. The only reliable discriminator is the exact message string 'Not possible to generate requested number of codes.'; there is no error.code or custom error class.

```ts
import { generate } from 'referral-codes';

try {
  const codes = generate({
    count: 1500,
    length: 2,
    charset: '0123456789',
  });
  console.log(codes);
} catch (error) {
  if (
    error instanceof Error &&
    error.message === 'Not possible to generate requested number of codes.'
  ) {
    console.error('Sorry, not possible.');
  } else {
    throw error; // re-throw unexpected errors
  }
}
```

--------------------------------

### Config type definition for generate options

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/configuration.md

Defines the optional configuration fields accepted by the `generate` function. All fields are optional; `count`, `length`, `charset`, `prefix`, `postfix`, and `pattern` control code generation behavior.

```ts
export type Config = {
  length?: number;
  count?: number;
  charset?: string;
  prefix?: string;
  postfix?: string;
  pattern?: string;
};
```

--------------------------------

### Charset enum

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Predefined charset names: NUMBERS, ALPHABETIC, ALPHANUMERIC. Use these as values for the charset option in Config.

```APIDOC
## Charset enum

### Description
Predefined charset names: NUMBERS, ALPHABETIC, ALPHANUMERIC. Use these as values for the charset option in Config.

### Members
- **NUMBERS** - Numeric characters (0-9).
- **ALPHABETIC** - Alphabetic characters (A-Z, a-z).
- **ALPHANUMERIC** - Alphanumeric characters (A-Z, a-z, 0-9).

### Example
```js
import { Charset } from 'referral-codes';
const config = { charset: Charset.ALPHANUMERIC };
```
```

--------------------------------

### Enum vs. string equivalence for charset()

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Demonstrates that passing the enum member and its string value to charset() are equivalent, both returning '0123456789'.

```ts
import { Charset, charset } from 'referral-codes';

charset(Charset.NUMBERS) === charset('numbers'); // true — both '0123456789'
```

--------------------------------

### isFeasible feasibility check for code count

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/configuration.md

Performs the only cross-field validation: checks whether `charset.length ** placeholderCount` is at least `count`. If not, `generate` throws `Error('Not possible to generate requested number of codes.')`; negative lengths and other invalid inputs are not validated elsewhere.

```ts
const isFeasible = (
  charset: string,
  pattern: string,
  count: number,
): boolean => {
  return charset.length ** size((x) => x === placeholder, pattern) >= count;
};
```

--------------------------------

### Inline shape accepted by generateOne

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

The inline-expanded shape accepted by the private generateOne function, which requires pattern, charset, prefix, and postfix.

```typescript
{
  pattern: string;
  charset: string;
  prefix: string;
  postfix: string;
}
```

--------------------------------

### Private Sizeable type

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/types.md

A private type used only by the internal size helper; not part of the public API.

```typescript
type Sizeable<T> = Iterable<T> & ArrayLike<T>;
```

--------------------------------

### charset() function definition

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Resolves a Charset enum member to its character pool string. Never throws, but performs no runtime validation; passing an unrecognized string returns undefined.

```ts
export const charset = (name: Charset): string => charsets[name];
```

--------------------------------

### Charset enum definition

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/api-reference/index.md

Defines the Charset enum with string values 'numbers', 'alphabetic', and 'alphanumeric'. Use it to avoid misspellings when passing a charset to generate().

```ts
export enum Charset {
  NUMBERS = 'numbers',
  ALPHABETIC = 'alphabetic',
  ALPHANUMERIC = 'alphanumeric',
}
```

--------------------------------

### Test assertion for the generation error message

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Test assertion verifying that generate throws an Error with the exact message 'Not possible to generate requested number of codes.' for an infeasible configuration. Located in test/index.test.js.

```javascript
t.throws(() => generate(config), { message: 'Not possible to generate requested number of codes.' })
```

--------------------------------

### Trigger condition for code generation error

Source: https://github.com/zack37/referral-codes/blob/master/_autodocs/errors.md

Mathematical condition that triggers the error. When the character pool size raised to the power of the number of placeholder positions is less than the requested count, generate throws an Error with the message 'Not possible to generate requested number of codes.'.

```text
charset.length ** (number of '#' placeholders in pattern) < count
```
Tokens:
Raw