@dpaskhin/unique
v0.2.0
Published
Ensures unique values by rejecting duplicates.
Downloads
236
Maintainers
Readme
@dpaskhin/unique
@dpaskhin/unique is a TypeScript library that ensures the uniqueness of generated values. It wraps any function to reject duplicate values and generate new ones until a unique result is produced. Useful for cases where you need unique random values or want to prevent repeated results.
Installation
To install @dpaskhin/unique, run:
npm install --save-dev @dpaskhin/unique
Features
- Generate unique values based on the output of any function.
- Supports
custom
stores orglobal
storage for uniqueness tracking. - Configurable
retry
andtimeout
options. stringifier
support for custom handling of complex objects during uniqueness checks.- Simple and easy-to-use API with full TypeScript support.
Usage
Basic Example
Here’s a quick example using @dpaskhin/unique with a custom function:
import { unique } from '@dpaskhin/unique';
const randomNumber = () => Math.floor(Math.random() * 100);
const uniqueRandomNumber = unique(randomNumber, [], { maxRetries: 5 });
console.log(uniqueRandomNumber); // Outputs a unique random number each time
Example with Faker.js
@dpaskhin/unique works well with libraries like Faker.js for generating unique random data.
import { unique } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
const uniqueName = unique(faker.person.firstName, ['male'], { maxRetries: 10 });
console.log(uniqueName); // Outputs a unique first name
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();
console.log(unique(Math.random, [], { store: scopedStore })); // Outputs a unique random number
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);
console.log(uniqueRandomValue1, uniqueRandomValue2); // Outputs two unique random values
// 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, {
exclude: [0.5, 0.6], // Prevents these values from being returned
});
console.log(createUniqueRandom()); // Outputs a unique random number, excluding 0.5 and 0.6
Stringifier for Complex Objects
The stringifier option allows you to handle complex objects by converting them into strings for uniqueness checks. This is useful when generating objects or other non-primitive types.
import { uniqueFactory } from '@dpaskhin/unique';
import { faker } from '@faker-js/faker';
const createUser = () => ({
name: faker.person.firstName(),
age: faker.number.int({ min: 18, max: 100 }),
});
const createUniqueUser = uniqueFactory(createUser, {
// Here can be any function that takes the return value of the createUser function and converts it to a string.
stringifier: value => JSON.stringify(value),
});
const user1 = createUniqueUser();
const user2 = createUniqueUser();
console.log(user1, user2); // Outputs two unique users
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<ReturnType>): A list of values to exclude from the result set. These values will not be returned by the unique generator.
- stringifier (function): An optional function to stringify a result before storing it. Useful for comparing complex data types, such as objects.
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 uniqueAddress = uniqueFactory(faker.location.city, { maxRetries: 5 });
console.log(uniqueAddress()); // Outputs a unique city name
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<ReturnType>): A list of values to exclude from the result set. These values will not be returned by the unique generator.
- stringifier (function): An optional function to stringify a result before storing it. Useful for comparing complex data types, such as objects.
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(),
},
]);
console.log(uniqueEmail); // Outputs a unique email address
Best Practices
- Avoid using the global store when local uniqueness is required, as it may lead to unexpected results due to shared state.
- Use the stringifier option for objects or complex data types to ensure uniqueness based on content rather than reference.
- Configure Max Retries and Timeouts: Customize maxRetries and maxTime based on the expected uniqueness and complexity of generated values.
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.