pallas-db/README.md

All in the name

# PallasDB

**PallasDB** is a database management library supporting SQLite, PostgreSQL, MySQL, JSON files, and in-memory storage, focusing on simple key-value operations with nested key support.

---

## Installation

```bash
npm install pallas-db
```

---

## Creating an Instance

```typescript
// IF ESM
import { PallasDB } from 'pallas-db';
// IF CommonJS
const { PallasDB } = require("pallas-db");

// SQLite Example
const db = new PallasDB({
  dialect: 'sqlite',
  filePath: './database.sqlite', // Path for SQLite
  tables: ['users', 'settings'], // List of tables
  enableVerbose: true, // For logging
});

// PostgreSQL Example
const pgDb = new PallasDB({
  dialect: 'postgres',
  login: {
    host: 'localhost',
    port: 5432,
    username: 'myuser',
    password: 'mypassword'
  },
  tables: ['users', 'settings'],
});

// MySQL Example
const mysqlDb = new PallasDB({
  dialect: 'mysql',
  login: {
    host: 'localhost',
    port: 3306,
    username: 'myuser',
    password: 'mypassword'
  },
  tables: ['users', 'settings'],
});

// Memory Example (New!)
const memoryDb = new PallasDB({
  dialect: 'memory',
  tables: ['users', 'settings'],
  enableVerbose: true,
});

// JSON File Example (New!)
const jsonDb = new PallasDB({
  dialect: 'json',
  filePath: './data/database.json', // Optional, defaults to ./database.json
  tables: ['users', 'settings'],
  enableVerbose: true,
});
```

---

## Methods

### 1. **`get(key: string, defaultValue?: any): Promise<any>`**
Retrieve a value by its key.
```typescript
const value = await db.get('settings.language', 'en');
```

### 2. **`set(key: string, value: any): Promise<void>`**
Set a value by its key.
```typescript
await db.set('settings.language', 'en');
```

### 3. **`add(key: string, amount: number): Promise<void>`**
Increment a numeric value by the specified amount.
```typescript
await db.add('stats.score', 10);
```

### 4. **`sub(key: string, amount: number): Promise<void>`**
Decrement a numeric value by the specified amount.
```typescript
await db.sub('stats.score', 5);
```

### 5. **`delete(key: string): Promise<void>`**
Remove a key and its value.
```typescript
await db.delete('settings.language');
```

### 6. **`has(key: string): Promise<boolean>`**
Check if a key exists.
```typescript
const exists = await db.has('settings.language');
```

### 7. **`all(): Promise<Array<{ id: string; value: any }>>`**
Retrieve all data from the current table.
```typescript
const records = await db.all();
```

### 8. **`push(key: string, element: any): Promise<void>`**
Add an element to an array.
```typescript
await db.push('users.favorites', 'new-item');
```

### 9. **`pull(key: string, element: any): Promise<void>`**
Remove an element from an array.
```typescript
await db.pull('users.favorites', 'unwanted-item');
```

### 10. **`cache(key: string, value: any, time: number): Promise<void>`**
Set a temporary value that expires after the specified time.
```typescript
await db.cache('temp.key', 'value', 5000); // Deletes after 5 seconds
```

### 11. **`deleteAll(): Promise<void>`**
Remove all records from the current table.
```typescript
await db.deleteAll();
```

### 12. **`table(name: string): PallasDB`**
Switch to another table.
```typescript
const settingsTable = db.table('settings');
```

### 13. **`repair(): Promise<void>`**
Clean up invalid or corrupted data from the database.
```typescript
await db.repair();
```

### 14. **`forceSync(): Promise<void>`**
Force synchronization of database tables (recreates them).
```typescript
await db.forceSync();
```

### 15. **`getMemoryStats(): { [tableName: string]: number } | null`** *(Memory & JSON dialects)*
Get statistics about usage for each table.
```typescript
const stats = db.getMemoryStats();
console.log(stats); // { users: 5, settings: 3 }
```

---

## Example Usage

```typescript
// Set nested data
await db.set('users.anais', { age: 19, role: 'admin' });

// Get nested data
const user = await db.get('users.anais');
console.log(user.age); // 19

// Increment a nested numeric value
await db.add('users.anais.age', 1);

// Delete a nested property
await db.delete('users.anais.role');

// Work with arrays
await db.set('users.anais.hobbies', ['reading', 'coding']);
await db.push('users.anais.hobbies', 'gaming');
await db.pull('users.anais.hobbies', 'reading');

// Switch between tables
const settingsTable = db.table('settings');
await settingsTable.set('theme', 'dark');

// Check existence
if (await db.has('users.anais.email')) {
  console.log('Email exists!');
}

// Get all records
const allUsers = await db.all();
console.log(allUsers);
```

---

## Supported Dialects

| Dialect | Description | Use Case |
|---------|-------------|----------|
| **sqlite** | Lightweight file-based database | Development, small applications |
| **postgres** | PostgreSQL database | Production applications, complex queries |
| **mysql** | MySQL database | Web applications, legacy systems |
| **memory** | In-memory storage using Maps | Testing, caching, temporary data |
| **json** | JSON file-based storage | Configuration files, simple persistence, human-readable data |

---

## Features

✅ **Nested Keys**: Support for dot notation (`key.subkey.value`)  
✅ **Multiple Dialects**: SQLite, PostgreSQL, MySQL, Memory, and JSON  
✅ **Type Safety**: Full TypeScript support  
✅ **Automatic Validation**: Built-in data validation  
✅ **Array Operations**: Push/pull operations for arrays  
✅ **Temporary Storage**: Cache with automatic expiration  
✅ **Database Repair**: Automatic cleanup of invalid data  
✅ **Table Switching**: Easy switching between tables  
✅ **File-based Storage**: JSON and SQLite file persistence  
✅ **Human-readable**: JSON files can be manually edited  

---

## Configuration Options

```typescript
interface PallasDBOptions {
  dialect: 'postgres' | 'sqlite' | 'mysql' | 'memory' | 'json';
  login?: {
    host?: string;
    port?: number;
    username?: string;
    password?: string;
  };
  filePath?: string; // SQLite and JSON only
  tables: string[];
  enableVerbose?: boolean;
}
```

---

## Memory & JSON Dialect Benefits

The **memory** and **JSON** dialects offer several advantages:

### Memory Dialect
- **Ultra-fast performance**: No I/O operations
- **Perfect for testing**: No database setup required
- **Development friendly**: Quick prototyping and debugging
- **Session persistence**: Data survives between requests (within same process)

### JSON Dialect
- **Human-readable**: Files can be manually edited
- **Version control friendly**: Easy to track changes with git
- **No dependencies**: Works without database servers
- **Cross-platform**: JSON files work everywhere
- **Backup friendly**: Simple file copying for backups

```typescript
// Memory dialect example
const memDb = new PallasDB({
  dialect: 'memory',
  tables: ['cache', 'sessions'],
  enableVerbose: true
});

await memDb.set('user.session', { token: 'abc123', expires: Date.now() });
const stats = memDb.getMemoryStats(); // { cache: 0, sessions: 1 }

// JSON dialect example
const jsonDb = new PallasDB({
  dialect: 'json',
  filePath: './config/app-data.json',
  tables: ['settings', 'users']
});

await jsonDb.set('settings.theme', 'dark');
// Creates/updates: ./config/app-data.json
```

---

## License

This project is licensed under the MIT License.