Contents

• About
• Features
• Installation
• Documentation
  • Tree
  • Import
  • Constructors
  • Methods
  • Types

About

Short yet unique IDs.

Features

• Short yet unique IDs
• The possibility of collision is impossible
• Suitable for distributed systems
• Suitable for sorting and database indexes
• Snowflake IDs can be generated, each one is timestamp based
• Increment IDs can be generated, increasing each time they are generated
• Symbolic IDs can be generated, similar to YouTube's video identities

Installation

You can install it as follows.

# NPM
npm add uuniq

# PNPM
pnpm add uuniq

# Yarn
yarn add uuniq

# Bun
bun add uuniq

# Deno
deno add uuniq

Documentation

Tree

Briefly as follows.

uuniq
│
├── new Snowflake(options?)
│   │
│   ├── generate()
│   └── resolve(id)
│
└── new Increment(options)
    │
    └── generate()

uuniq/types
│
├── type SnowflakeOptions
├── type SnowflakeResolve
└── type IncrementOptions

Import

Briefly as follows.

import { Snowflake, Increment } from 'uuniq';

Constructors

new Snowflake(options?)

Snowflake IDs are timestamp based identifiers. Each ID consists of numbers that are quite unique from the previous ones. Unique IDs can be generated in distributed systems by specifying Place IDs.

Parameter	Type	Default	Description
options?	SnowflakeOptions	snowflake_options	Constructor's options.

Example:

const snowflake = new Snowflake();

new Increment(options)

Increment IDs that increase each time they are generated. Sequences are kept in the database. You can create a free database from MongoDB Cloud. Storing sequences requires tools that include set(key, value) and get(key). We recommend Keyv. Sequences can be parsed by specifying Place IDs.

Parameter	Type	Default	Description
options	IncrementOptions	increment_options	Constructor's options.

Example:

import Keyv from 'keyv';
import KeyvMongo from '@keyv/mongo';

const uuniq_store = new Keyv(new KeyvMongo('mongodb+srv://...@...mongodb.net/app', { collection: 'uuniq' }));

const increment = new Increment({ store: uuniq_store });

Methods

Snowflake.generate()

Generate Snowflake IDs.

Parameter	Type	Default	Description

returns String

Example:

const numeric_snowflake = new Snowflake({ format: 'numeric', place_id: 0 });
const symbolic_snowflake = new Snowflake({ format: 'symbolic', place_id: 1 });

numeric_snowflake.generate(); // '102604921389056'
numeric_snowflake.generate(); // '102604921389057'

symbolic_snowflake.generate(); // 'T8Qu56ki'
symbolic_snowflake.generate(); // 'T8Qu56kj'

Snowflake.resolve(id)

Resolve the previously generated Snowflake ID. For this, the format, epoch and place_id values ​​in the Constructor must be correct.

Parameter	Type	Default	Description
id	String		ID to be resolved.

returns SnowflakeResolve

Example:

const numeric_snowflake = new Snowflake({ format: 'numeric', place_id: 0 });
const symbolic_snowflake = new Snowflake({ format: 'symbolic', place_id: 1 });

numeric_snowflake.resolve('102604921389056');
/*
  {
    created_at: '2025-03-14T11:35:07.409Z',
    place_id: 0,
    sequence: 0
  }
*/

symbolic_snowflake.resolve('T8Qu56ki');
/*
  {
    created_at: '2025-03-14T11:36:05.528Z',
    place_id: 0,
    sequence: 0
  }
*/

Increment.generate()

Generate Increment IDs that increase each time they are generated.

Parameter	Type	Default	Description

returns Promise

Example:

const numeric_increment = new Increment({ format: 'numeric', place_id: 0, store: uuniq_store });
const symbolic_increment = new Increment({ format: 'symbolic', place_id: 1, store: uuniq_store });

await numeric_increment.generate(); // '10000001'
await numeric_increment.generate(); // '10000002'

await symbolic_increment.generate(); // 'fxSL'
await symbolic_increment.generate(); // 'fxSM'

Types

Type
SnowflakeOptions
SnowflakeResolve
IncrementOptions