keystamp/README.md

A tiny, fast, and collision-resistant unique ID generator for JavaScript, React.js, Node.js, and Express.js, inspired by MiniQid.

# Keystamp

![Keystamp Logo](./src/keystaplogo.png)

`keystamp` is a simple and easy-to-use library for generating unique IDs in Node.js. You can customize the length, add prefixes or suffixes, and choose from different character sets.

## Features

- Generate unique IDs with customizable length.
- Add prefixes or suffixes to your IDs.
- Choose from different character sets:
  - Alphanumeric (letters and numbers)
  - Numbers only
  - Hexadecimal
  - Lowercase letters
  - Uppercase letters
  - Symbols
  - Binary (0 and 1)
  - Custom character sets
- Ensures IDs are unique.

## Installation

First, install the package using npm:

```bash
npm install keystamp
```

## How to Use

Here’s how you can use `keystamp` to generate unique IDs:

### 1. Import the Library

```javascript
const keystamp = require("keystamp");
```

### 2. Generate a Simple ID

```javascript
const id = keystamp();
console.log(id); // Example output: "1a2b3c4d5e6f7g8h9i0jklmn"
```

### 3. Customize the ID

You can customize the ID by passing options:

```javascript
const customId = keystamp({
  prefix: "user_", // Add a prefix to the ID
  suffix: "_end", // Add a suffix to the ID
  length: 16, // Set the length of the ID
  type: "binary", // you can use more options >> "alphanumeric", "hex",
  //  "lowercase","uppercase", "symbols", "binary", "custom"
});
console.log(customId); // Example output: "user_10011001_end"
```

### 4. Use a Custom Character Set

You can define your own character set:

```javascript
const customCharsetId = keystamp({
  length: 8,
  type: "custom",
  customCharset: "ABC123", // Use only these characters
});
console.log(customCharsetId); // Example output: "A1B2C3A1"
```

### 5. Combine Multiple Character Sets

You can combine multiple character sets using the `+` operator:

example : "custom+symbols+lowercase"

```javascript
const customCharsetId = keystamp({
  length: 40,
  type: "custom+symbols", // OR >> lowercase+symbols ,binary+uppercase,
  // uppercase+binary+symbols and more... this is your choice
  customCharset: "ABC123", 
});
console.log(customCharsetId); // Example output: " &:+/$<₹#<_AC/"+&/_;A,C;=)>B|<-#3:2$`,|>1 "
```

## Options

Here are the options you can use with `keystamp`:

| Option          | Type    | Default   | Description                                                                 |
|------------------|---------|-----------|-----------------------------------------------------------------------------|
| `prefix`         | String  | `""`      | A string to add at the beginning of the ID.                                 |
| `suffix`         | String  | `""`      | A string to add at the end of the ID.                                       |
| `length`         | Number  | `24`      | The total length of the generated ID (excluding prefix and suffix).         |
| `type`           | String  | `"hex"`   | The character set to use. Options: `"alphanumeric"`, `"numeric"`, `"hex"`, `"lowercase"`, `"uppercase"`, `"symbols"`, `"binary"`, `"custom"`. |
| `customCharset`  | String  | `""`      | A custom character set to use when `type` is `"custom"`.                    |

## Character Set Types

| Type            | Description                                                   |
|------------------|---------------------------------------------------------------|
| `alphanumeric`   | Letters (A-Z, a-z) and numbers (0-9).                         |
| `numeric`        | Numbers (0-9).                                                |
| `hex`            | Hexadecimal characters (0-9, a-f).                            |
| `lowercase`      | Lowercase letters (a-z).                                      |
| `uppercase`      | Uppercase letters (A-Z).                                      |
| `symbols`        | Symbols (`!@#$%^&*()-_=+[]{}|;:,.<>?/`~"₹`).                  |
| `binary`         | Binary digits (0, 1).                                         |
| `custom`         | A custom character set defined by the `customCharset` option. |


## Why Use Keystamp?

- **Beginner-Friendly**: Easy to use with simple options.
- **Customizable**: Generate IDs exactly how you need them.
- **Unique IDs**: Ensures no duplicate IDs are generated.