@dpaskhin/unique
v1.0.0
Published
Ensures unique values by rejecting duplicates.
Downloads
204
Maintainers
Readme
@dpaskhin/unique
@dpaskhin/unique is a TypeScript library for generating unique values. It ensures no duplicates by rejecting repeats and retrying until a new result is found. Ideal for ensuring non-repeated random values.
Installation
To install @dpaskhin/unique, run:
npm install --save-dev @dpaskhin/unique
Features
- Generate unique values based on the output of any function or plain value.
- Supports
custom
stores orglobal
storage for uniqueness tracking. - Configurable
retry
andtimeout
options. stringifier
support for custom handling of complex objects during uniqueness checks.- ~600B gzipped.
Usage
Basic Example
Here’s a quick example using @dpaskhin/unique:
import { unique } from '@dpaskhin/unique';
// Outputs a unique random number each time
console.log(unique(Math.random));
console.log(unique(Math.random));
console.log(unique(Math.random));
Example with Faker.js
@dpaskhin/unique works well with libraries like Faker.js for generating unique random data.
import { unique, uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
// Outputs a unique first name each time
console.log(unique(faker.person.firstName));
console.log(unique(faker.person.firstName));
console.log(unique(faker.person.firstName));
// ----------------------------------------
const createUniqueUser = uniqueFactory(() => ({
firstName: faker.person.firstName(),
lastName: faker.person.lastName(),
age: faker.number.int({ min: 18, max: 100 }),
}));
// Each output user is structurally unique
console.log(createUniqueUser());
console.log(createUniqueUser());
console.log(createUniqueUser());
Custom Store
You can provide your own store to isolate uniqueness checks. This ensures that uniqueness is tracked within the scope of your application.
import { unique } from '@dpaskhin/unique';
const scopedStore = new Set();
// Outputs a unique random number
console.log(unique(Math.random, [], { store: scopedStore }));
Global Store
If you don’t provide a custom store, the library will use the GLOBAL_STORE by default. This can be useful if you want to track unique values across different parts of your application.
import { unique, GLOBAL_STORE } from '@dpaskhin/unique';
// Use the global store for uniqueness checks
const uniqueRandomValue1 = unique(Math.random);
const uniqueRandomValue2 = unique(Math.random);
// Outputs two unique random values
console.log(uniqueRandomValue1, uniqueRandomValue2);
// Clear the global store when needed
GLOBAL_STORE.clear();
Excluding Specific Values
You can also provide an exclude list to prevent specific values from being considered during uniqueness checks.
import { uniqueFactory } from '@dpaskhin/unique';
const createUniqueRandom = uniqueFactory(Math.random, {
// Prevents these values from being returned
exclude: [0.5, 0.6],
});
// Outputs a unique random number, excluding 0.5 and 0.6
console.log(createUniqueRandom());
Stringifier for Complex Objects or other non-primitive types
The stringifier option allows you to handle complex objects by converting them into strings for uniqueness checks.
By default, JSON.stringify
is used as the stringifier.
import { uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
import JsonMarshal from 'json-marshal';
const createUniqueUser = uniqueFactory(
() => ({
name: faker.person.firstName(),
age: faker.number.int({ min: 18, max: 100 }),
}),
{
// Here can be any function that takes the return value of the function provided above and converts it to a string.
// Or just omit it, JSON.stringify will be used instead.
stringifier: JsonMarshal.stringify,
}
);
const user1 = createUniqueUser();
const user2 = createUniqueUser();
// Outputs two unique users
console.log(user1, user2);
API Reference
uniqueFactory(fn, options)
Creates a function that ensures unique results based on the provided function fn.
Parameters
- fn - The function used to generate values.
- options - Optional. An object containing configuration options:
- store (Set): A custom store to track unique values. Defaults to a new Set.
- maxRetries (number): The maximum number of retries to generate a unique value before throwing an error. Defaults to 50.
- maxTime (number): The maximum time (in milliseconds) to attempt generating a unique value before throwing an error. Defaults to 50ms.
- exclude (Array): A list of values to exclude from the result set. These values will not be returned by the unique generator.
- stringifier (function): A function to stringify a result before storing it. Defaults to JSON.stringify.
Returns
A function that generates unique values based on fn with the same signature.
Example
import { uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
const createUniqueUser = uniqueFactory(() => ({
name: faker.person.firstName(),
age: faker.number.int({ min: 18, max: 100 }),
}));
// Outputs a unique user each time
console.log(createUniqueUser());
console.log(createUniqueUser());
console.log(createUniqueUser());
unique(fn, args, options)
Generates a unique value by running fn and ensuring uniqueness via either a provided or global store.
Parameters
- fn - The function used to generate values.
- args - Optional. An array of arguments to be passed to fn.
- options - Optional. An object containing configuration options:
- store (Set): A custom store to track unique values. By default, the GLOBAL_STORE is used.
- maxRetries (number): The maximum number of retries to generate a unique value before throwing an error. Defaults to 50.
- maxTime (number): The maximum time (in milliseconds) to attempt generating a unique value before throwing an error. Defaults to 50ms.
- exclude (Array): A list of values to exclude from the result set. These values will not be returned by the unique generator.
- stringifier (function): A function to stringify a result before storing it. Defaults to JSON.stringify.
Returns
A unique value generated by fn.
Example
import { unique } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
const uniqueEmail = unique(faker.internet.email, [
{
firstName: faker.person.firstName(),
lastName: faker.person.lastName(),
},
]);
// Outputs a unique email
console.log(uniqueEmail);
unique(value, options)
Ensures a plain value is unique by checking against either a provided or global store.
Parameters
- value - The plain value (non-functional) to ensure uniqueness for.
- options - Optional. An object containing configuration options:
- store (Set): A custom store to track unique values. By default, the GLOBAL_STORE is used.
- exclude (Array): A list of values to exclude. These values will not be added to the store or returned.
- stringifier (function): A function to stringify the value before storing it. Defaults to JSON.stringify.
Returns
The unique value provided.
Example
import { unique } from '@dpaskhin/unique';
// Each time outputs a unique ID string or throws an error
console.log(unique(window.crypto.randomUUID()));
console.log(unique(window.crypto.randomUUID()));
console.log(unique(window.crypto.randomUUID()));
Best Practices
- Avoid using the global store when local uniqueness is required, as it may lead to unexpected results due to shared state.
- Configure Max Retries and Timeouts: Customize maxRetries and maxTime based on the expected uniqueness and complexity of generated values.
- Avoid using plain values and prefer generating functions for flexibility and retries.
License
@dpaskhin/unique is licensed under the MIT License.
Contributing
Contributions are welcome! If you have ideas or improvements, feel free to submit a pull request.