enforce-unique

enforce-unique is a package that helps you ensure values are unique before you assign them.

Installation

npm install enforce-unique --save

Usage

Simplest usage is just providing a value. If the same value is provided before, enforce method will throw an EnforceUniqueError.

import { EnforceUniqueError, UniqueEnforcer } from 'enforce-unique';

const arrayContainsUniqueItems: number[] = [];

const uniqueEnforcer = new UniqueEnforcer();

const pushUnique = (item: number) => {
  try {
    arrayContainsUniqueItems.push(
      uniqueEnforcer.enforce(item)
    )
  } catch (error) {
    if (error instanceof EnforceUniqueError) {
      return 'Item already exists';
    }
  }
};

pushUnique(1);

// logs 'Item already exists'
console.log(pushUnique(1));

Or you can provide a function that returns a value. enforce method will run this function until limits are exceeded and will return the generated value. If limits are exceeded it will throw an EnforceLimitError.

const uniqueEnforcerEmail = new UniqueEnforcer();

function createRandomUser() {
  const firstName = faker.person.firstName();
  const lastName = faker.person.lastName();
  const email = uniqueEnforcerEmail.enforce(() => {
    return faker.internet.email({firstName, lastName});
  });

  return {
    firstName,
    lastName,
    email,
  };
}

// You can be sure that each user in the list has unique email
const users = []

for (let i = 0; i < 100; i++) {
  users.push(createRandomUser())
}

Default limits

{
  maxTime: 50,
  maxRetries: 50,
}

Options

You can provide options object to change the defaults

const email = uniqueEnforcerEmail.enforce(
  () => {
    return faker.internet.email({firstName, lastName})
  },
  {
    maxTime: 1000,
    maxRetries: 1000,
    exclude: [1]
  },
);

maxTime

The time in milliseconds this method may take before throwing an EnforceLimitError

maxRetries

The total number of attempts to try before throwing an EnforceLimitError

exclude

Exclude specific value(s) from being returned.

Resetting

You can reset the unique enforcer instance to start over, clearing any previously stored values.

  const uniqueEnforcer = new UniqueEnforcer();

  const value1 = uniqueEnforcer.enforce('value');

  uniqueEnforcer.reset();

  // There will be no error thrown because of reset.
  const value2 = uniqueEnforcer.enforce('value');