@d3vtool/secid/README.md

Generate a fast, secure, and compact unique identifier (ID) for use in modern applications, providing small, URL friendly, and collision resistant values.

# `secid` - Secure and Unique ID Generator

`secid` is a lightweight library for creating secure, unique identifiers that are designed to be collision resistant and safe. It offers a simple API for generating unique IDs for a wide range of use cases such as unique URL-safe id and more, also it is compatible with both browser and Node.js environments.

- [**Use Cases**](#use-cases)
- [**Customization**](#customization)
- [**Performance Considerations**](#performance-considerations)
- [**Why Use `secid`**](#why-use-secid)

## Install

```bash
npm install secid
```

## Usage

### Basic Usage: Generate a Secure ID

```js
import { SecId } from "secid";

const id = SecId.generate();
console.log(id);  // Example output: 'eXfgJ1T74m8rZyw2'
```

This generates a secure, random identifier. It is suitable for most applications requiring unique identifiers.

---


## Use Cases

### 1. **Unique User Identifiers (UIDs)**

For applications that require user registration or identification, you can use `SecId` to generate a unique ID for each user.

```js
import { SecId } from "secid";

const userId = SecId.generate();
console.log(`New user ID: ${userId}`);
```

- **Scenario**: Assign unique IDs to users in your app to differentiate between them without exposing sensitive information.

---


### 2. **Session Tokens**

Use `SecId` to generate secure session tokens that can be used to authenticate and authorize users in your application.

```js
import { SecId } from "secid";

const sessionToken = SecId.generate();
console.log(`Generated session token: ${sessionToken}`);
```

- **Scenario**: When a user logs in, generate a unique session token that expires or is revoked after a certain period.

---


### 3. **API Keys for External Services**

If you need to generate API keys to securely interact with external services, `SecId` can be used to generate random, hard-to-guess keys.

```js
import { SecId } from "secid";

const apiKey = SecId.generate();
console.log(`Generated API Key: ${apiKey}`);
```

- **Scenario**: Assign an API key to a user when they sign up for your service, ensuring that it's unique and hard to guess.

---


### 4. **File or Object Identifiers**

When storing files or objects (e.g., images, documents), use `SecId` to generate unique identifiers that link to each file.

```js
import { SecId } from "secid";

const fileId = SecId.generate();
console.log(`Generated file ID: ${fileId}`);
```

- **Scenario**: Generate IDs for uploaded files to easily reference and retrieve them from your database or storage service.

---


### 5. **Database Primary Keys**

For databases that require unique primary keys (such as in NoSQL databases), `SecId` can be used to generate identifiers for records or entities.

```js
import { SecId } from "secid";

const recordId = SecId.generate();
console.log(`Generated record ID: ${recordId}`);
```

- **Scenario**: Generate primary keys for database records, ensuring they are globally unique and secure.

---


### 6. **Unique Transaction IDs**

If you're building an e-commerce or financial application, you may need unique transaction IDs for each order, payment, or transfer.

```js
import { SecId } from "secid";

const transactionId = SecId.generate();
console.log(`Generated transaction ID: ${transactionId}`);
```

- **Scenario**: Generate secure transaction identifiers that can be used to track and reference payments.

---


### 7. **Tracking and Analytics IDs**

When tracking user behavior or generating event logs, you may want to assign unique identifiers to each event or user session.

```js
import { SecId } from "secid";

const eventId = SecId.generate();
console.log(`Generated event ID: ${eventId}`);
```

- **Scenario**: Generate IDs for individual user events (such as page views, clicks, etc.) for analytics tracking.

---


### 8. **Order or Invoice Numbers**

In e-commerce platforms, you can use `SecId` to generate unique order numbers or invoice IDs for each transaction.

```js
import { SecId } from "secid";

const orderNumber = SecId.generate();
console.log(`Generated order number: ${orderNumber}`);
```

- **Scenario**: Assign a unique ID to each order, ensuring that every transaction is easily identifiable and traceable.

---


### 9. **URLs for Shortened Links**

Generate secure and random URL slugs for shortened links. You can use `SecId` to create short but unique URLs for your web service.

```js
import { SecId } from "secid";

const shortUrlSlug = SecId.generate();
console.log(`Generated short URL slug: ${shortUrlSlug}`);
```

- **Scenario**: Use the ID as a part of the URL path for shortened links or redirects.

---


### 10. **Distributed Systems – Unique IDs for Multiple Servers**

In distributed systems, you need to ensure that IDs are unique across multiple servers or instances. `SecId` can provide secure unique IDs across all nodes in the system.

```js
import { SecId } from "secid";

const uniqueDistributedId = SecId.generate();
console.log(`Generated distributed system ID: ${uniqueDistributedId}`);
```

- **Scenario**: Generate unique identifiers in microservices architectures or when working with multiple servers to avoid collisions.

---


### 11. **Tracking Items in Inventory Management**

In inventory systems, each item can be assigned a unique ID using `SecId` to ensure every product is distinct and traceable.

```js
import { SecId } from "secid";

const inventoryItemId = SecId.generate();
console.log(`Generated inventory item ID: ${inventoryItemId}`);
```

- **Scenario**: Assign unique IDs to each item in the inventory to track stock levels and transactions.

---


## Customization

### Custom Length and Alphabet

By default, `SecId` generates IDs with a predefined length and set of characters. If you need to customize the length or the alphabet, you can pass options to the `generate` method.

```js
import { SecId } from "secid";

const customId = SecId.generate(
  12,  // Customize the length  [ Default: 23 ]
  'ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'  // Customize the character set
);
console.log(`Generated custom ID: ${customId}`);
```

---


## Performance Considerations

- `SecId` generates IDs asynchronously using cryptographically secure random values.
- The library is optimized for performance, ensuring IDs are generated quickly even under heavy load.
- For applications that require extremely high throughput, consider benchmarking `SecId` with your use case.

---


## Why Use `secid`?

- **Security**: IDs are generated with a cryptographically secure random function.
- **Uniqueness**: Built to avoid collisions, ensuring each ID is globally unique.
- **Performance**: Optimized to generate IDs with low latency.
- **Customizable**: You can adjust the ID length, character set, and more.
- **Lightweight**: Small package size and minimal dependencies.

---


## License

MIT License. See [License](License) for more details.