zexson_toolkit/README.md

Zexson Toolkit is a powerful encryption and tokenization library developed by Zexson Team. It offers proprietary encryption algorithms, high-security random token generation, and advanced object comparison features. It includes many advanced security func

<p align="center">
  <a align="center" href="https://zexson.vercel.app/" target="_blank">
    <img  align="center" src="https://cdn.discordapp.com/icons/1268182421732327445/8ac3744f5a6d308691ec51f54bcd9fb4.webp?size=4096" alt="Zexson Team Logo" width="120"/>
  </a>
</p>

<h1 align="center">zexson_toolkit by Zexson Team</h1>

<p align="center">
  <a align="center" href="https://zexson.vercel.app/" target="_blank"><strong>Zexson Team Website</strong></a>
</p>
<p align="center">
  <img src="https://img.shields.io/npm/l/zexson_toolkit" alt="License"/>
  <img src="https://img.shields.io/npm/v/zexson_toolkit" alt="Version"/>
  <img src="https://img.shields.io/npm/dt/zexson_toolkit" alt="Downloads"/>
  <img src="https://img.shields.io/npm/dm/zexson_toolkit" alt="Downloads"/>
  <a href="https://discord.gg/VFYRarPZDT" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
  <a href="https://kofe.al/en/@signor-p" target="_blank">
    <img src="https://img.shields.io/badge/Donate-Kofe.al-ff3f59.svg" alt="Donate via">
  </a>
</p>
<p align="center">
  A high-performance encryption, token generation, and string manipulation library built by the  
  <a href="https://zexson.vercel.app/" target="_blank"><strong>Zexson Team</strong></a>, featuring advanced security, customizable algorithms, and high-entropy randomness.
</p>

---


## 🚀 Features of `zexson_toolkit`

- **🔐 Secure Encryption & Decryption**  
  - Custom encryption algorithm with dynamic random padding  
  - Base64 encoding with character shifting for added security  
  - Key-based encryption for controlled access  

- **🔑 Token Generation**  
  - Flexible token creation with customizable length and character sets  
  - Multiple predefined character sets for various use cases  
  - High-entropy random generation for strong security  

- **📝 Advanced String Comparison**  
  - Supports both case-sensitive and case-insensitive comparison  
  - Secure comparison of encrypted strings  
  - Detailed result analysis for accurate matching

---


## 📦 Installation

Install the package via npm:

```bash
npm install zexson_toolkit
```

---


## 🔧 Usage

### Crypt Example Function

```typescript
import { cryptExample } from 'zexson_toolkit'
cryptExample('zexson_toolkit','zexson_team')
```

### Basic Encryption/Decryption

```typescript
import { encrypt, decrypt } from 'zexson_toolkit'

// Basic encryption
const encrypted = encrypt("sensitive data")
const decrypted = decrypt(encrypted)
```

### Advanced Encryption with Options

```typescript
import { encrypt } from 'zexson_toolkit'

// Custom encryption with options
const encrypted = encrypt("sensitive data", {
  key: 'customKey'
})
```

### Token Generation

```typescript
import { tokenGenerator } from 'zexson_toolkit'

// Generate a token with specified length and character set
const token = tokenGenerator(16, 'defaultSet')
```

### String Comparison

```typescript
import { isEqual } from 'zexson_toolkit'

// Compare strings with options
const result = isEqual("text1", "text2", {
  caseSensitive: false,
  key: "customKey",
  log: true
})
```

### Base64 Encoding/Decoding

```typescript
import { base64Encode, base64Decode } from 'zexson_toolkit'

// Encode a string
const encoded = base64Encode("example string", "customKey")

// Decode a string
const decoded = base64Decode(encoded, "customKey")
```

### Object Encryption/Decryption

```typescript
import { encryptObject, decryptObject } from 'zexson_toolkit'

// Encrypt an object
const data = { username: "JohnDoe", password: "12345" }
const encryptedData = encryptObject(data, "my-secret-key")

// Decrypt an object
const decryptedData = decryptObject(encryptedData, "my-secret-key")
```

### Advanced Object Encryption/Decryption Examples

```typescript
import { encryptBody, decryptBody } from 'zexson_toolkit'

// Encrypt an object with the encryptBody function
const data = { username: "JohnDoe", password: "12345" }
const encryptedData = encryptBody(data, "my-secret-key")

// Decrypt the object with the decryptBody function
const decryptedData = decryptBody(encryptedData, "my-secret-key")

// Advanced encryption with complex data structure
const complexData = { 
  username: "JohnDoe", 
  password: "12345", 
  about: { gender: 'male', age: 12 }, 
  hobbies: ['football', 'basketball', { football: true, basketball: false }] 
}
const encryptedComplexData = encryptBody(complexData, "my-secret-key")
const decryptedComplexData = decryptBody(encryptedComplexData, "my-secret-key")
```

## 🔍 Object Comparison with `isEquals`

The `isEquals` function deeply compares two objects or arrays for equality, with optional type checking and schema validation.

---


### 🛠 Basic Usage

```typescript
import { isEquals } from 'zexson_toolkit'

const obj1 = { name: "John", age: 30 }
const obj2 = { name: "John", age: 30 }

console.log(isEquals(obj1, obj2)) // true
```

---


### 🔄 Nested Object Comparison

```typescript
import { isEquals } from 'zexson_toolkit'

const obj1 = { name: "John", details: { city: "New York", zip: 10001 } }
const obj2 = { name: "John", details: { city: "New York", zip: 10001 } }

console.log(isEquals(obj1, obj2)) // true
```

---


### 🔢 Type Checking Comparison

```typescript
import { isEquals } from 'zexson_toolkit'

const obj1 = { name: "John", age: 25 }
const obj2 = { name: "Jane", age: 30 }

console.log(isEquals(obj1, obj2, { checkType: true })) // true
```

---


### 📑 Array Comparison

```typescript
import { isEquals } from 'zexson_toolkit'

const arr1 = [1, 2, 3, 4]
const arr2 = [1, 2, 3, 4]

console.log(isEquals(arr1, arr2)) // true
```

---


### 🚀 Complex Object and Array Comparison

```typescript
import { isEquals } from 'zexson_toolkit'

const obj1 = {
  name: "Alice",
  age: 28,
  hobbies: ["reading", "gaming"],
  address: { city: "Paris", zip: 75000 }
}

const obj2 = {
  name: "Alice",
  age: 28,
  hobbies: ["reading", "gaming"],
  address: { city: "Paris", zip: 75000 }
}

console.log(isEquals(obj1, obj2)) // true
```

---


### ❌ Different Object Structures

```typescript
import { isEquals } from 'zexson_toolkit'

const obj1 = { name: "John", age: 30 }
const obj2 = { name: "John", age: 30, gender: "male" }

console.log(isEquals(obj1, obj2)) // false
```

---


### 🏗 Schema-Based Object Comparison

The `isEquals` function now supports schema validation for strict structural comparisons.

```typescript
import { isEquals, encryptObject, decryptObject } from 'zexson_toolkit'

const schema = {
    name: 'string',
    age: 'number',
    status: { type: 'string', enum: ['active', 'inactive'] },
    hobbies: {
        type: 'array',
        items: { type: 'string', enum: ['reading', 'gaming', 'sports'] }
    },
    address: {
        type: 'object',
        properties: {
            city: 'string',
            zip: 'number'
        }
    }
};

const obj1 = {
    name: "Alice",
    age: 28,
    status: "active",
    hobbies: [],
    address: { city: "Paris", zip: 75000 }
};

const eObj1 = encryptObject(obj1);

const obj2 = {
    name: "Bob",
    age: 30,
    status: "inactive",
    hobbies: ["reading", "gaming", "sports"],
    address: { city: "London", zip: 12345 }
};

const eObj2 = encryptObject(obj2);

console.log(isEquals(obj1, obj2, { checkType: true, schema })) // true
console.log(decryptObject(eObj1), decryptObject(eObj2))
```

### 🦄 Schema-Based Single Object Comparison

```typescript
import { isEquals } from 'zexson_toolkit'

const schema: SchemaType = {
    name: 'string',
    age: 'number',
    status: { type: 'string', enum: ['active', 'inactive'] },
    hobbies: {
        type: 'array',
        items: { type: 'string', enum: ['reading', 'gaming', 'sports'] }
    }
}
const obj1 = {
    name: 'John',
    age: 30,
    status: 'inactive',
    hobbies: ['gaming']
};
const obj2 = {
    name: 'John1',
    age: 20,
    status: 'active',
    hobbies: ['gaming']
};
console.log(isEquals(obj2, undefined, { schema })) // true
```

---

### Secure Key Management Recommendations

For optimal security, it’s crucial to manage and store cryptographic keys carefully. Here’s a simple guide to help you maintain the integrity and security of your keys:

1. **Store keys in environment variables**:
   - Place your cryptographic keys in a `.env` file. This file should not be included in your version control system (e.g., Git).
   - Example:
     ```plaintext
     ENCRYPTION_KEY=my-secret-key
     ```

2. **Use dotenv for secure key management**:
   - Install `dotenv` if you haven't already:
     ```bash
     npm install dotenv
     ```
   - Load your environment variables in your application using `dotenv`:
     ```typescript
     require('dotenv').config() || import * as dotenv from 'dotenv'; dotenv.config()
     const encryptionKey = process.env.ENCRYPTION_KEY
     ```
   - This ensures that the key is only accessible within your application's runtime, not hard-coded directly in the codebase.

3. **Rotate keys regularly**:
   - Regularly update your encryption keys to prevent potential unauthorized access. Document key rotations in your system for audit purposes.

4. **Limit key permissions**:
   - Restrict access to keys by limiting the permissions of the `.env` file and ensuring only authorized personnel can modify it.
   - Avoid placing keys directly in source code, as this can expose them in version history and logs.

5. **Encrypt sensitive data**:
   - Whenever storing sensitive data, encrypt it with the appropriate keys to prevent unauthorized access if it’s compromised.

---


## 📚 Available Functions

### Encryption Functions
- `encrypt(data: string, options?: EncryptOptions): Promise<string>`
- `decrypt(data: string, options?: DecryptOptions): Promise<string>`
- `base64Encode(data: string, key?: string): string`
- `base64Decode(data: string, key?: string): string`

### Token Generation
- `tokenGenerator(length: number, type: CharacterSetType): string`

### String Comparison
- `isEqual(text1: string, text2: string, options?: IsEqualOptions): Promise<{ isEqual: boolean, method?: string }>`
  
### Object Encryption Functions
- `encryptObject(object: EncryptableObject, secretKey?: string): EncryptableObject`
- `decryptObject(object: EncryptableObject, secretKey?: string): EncryptableObject`

---


## 🤝 Contributing

Contributions are welcome! Here’s how you can contribute:

1. Submit issues to report bugs or suggest features.
2. Create pull requests to improve the toolkit.
3. Share ideas to enhance functionality.

---


## 📫 Connect with Us

- [Our Website](https://zexson.vercel.app)
- [Our YouTube Channel](https://www.youtube.com/@ZexsonStudio)
- [My GitHub](https://github.com/SignorMassimo)
- [Zexson Team Instagram](https://www.instagram.com/zexsonteam)
- [Contact us for support](https://www.instagram.com/_signor_p_)

---


# 📄 License Information

This project is licensed under the MIT License. The MIT License is a permissive open-source license that allows users to freely use, modify, distribute, and sublicense the software, subject to certain conditions. For a full description of the terms and conditions under which this project can be used, modified, and distributed, please refer to the LICENSE file included in the project. By using, modifying, or distributing this project, you agree to abide by the terms outlined in the MIT License.

---


### Why Choose zexson_toolkit?

- Clean and well-documented codebase.
- Regular updates and active maintenance.
- Tailored for developers needing advanced cryptographic utilities.

---

### Made with ❤️ for you by Zexson Team.
---