@trap_stevo/star-vault/README.md

Unleash the future of data management with the ultimate platform for secure, scalable, and dynamic data operations. Power the next generation of applications by combining advanced encryption, revolutionary real-time querying, and seamless synchronization

# 🚀 @trap\_stevo/star-vault

**Unleash the future of data management** with the ultimate platform for secure, scalable, and dynamic data operations. Power the next generation of applications by combining advanced encryption, revolutionary real-time querying, and seamless synchronization to create an ecosystem where data transforms into action.

---


## 🌌 Features

- 🔐 **Optional Encryption** – Secure sensitive data at rest
- ⚙️ **Sharded Storage Engine** – Efficiently scales writes across shards
- 🧠 **In-Memory Caching** – High-speed read layer with `StarCache`
- 📜 **Write-Ahead Logging** – Resilient logs with rotation and retention policies
- 🔍 **Advanced Query Engine** – Chainable and expressive queries with filtering, search, sorting, and spatial support
- 🚀 **Real-Time Event Emission** – Listen to data changes with fine-grained control
- 🛡️ **Authentication Layer** – Optional handler to authorize every operation
- 🌠 **Collection Wildcards** – Seamlessly operate across multiple collections

---


# 📜 API Specification

## 🔧 Constructor

Use these parameters when initializing `StarVault`.

```js
new StarVault(dbPath, logPath, shardCount, maxLogSize, logRetention, options)
```

### Core Parameters

| Key           | Description                                                                 | Default      |
|---------------|------------------------------------------------------------------------------|--------------|
| `dbPath`      | Root directory for all collection data; each collection is stored in sharded files. | **Required** |
| `logPath`     | Directory where write-ahead logs (WAL) are stored for durability and replay. | **Required** |
| `shardCount`  | Number of shards used per collection. More shards improve concurrency.       | `4`          |
| `maxLogSize`  | Max size of each WAL file before rotation. Accepts values like `"100MB"`.    | `"869MB"`    |
| `logRetention`| Duration to retain old WAL files. Accepts values like `"1w"` or `"30d"`.     | `"1w"`       |

### `options` Object

| Key               | Description                                                                 | Default               |
|-------------------|-----------------------------------------------------------------------------|------------------------|
| `enableEncryption`| Enables encryption for data at rest.                         | `false`                |
| `vaultPath`       | Path to the vault metadata file used for encryption.                        | `"./star-vault.json"`  |
| `masterKey`       | Master encryption key for vault encryption. Must securely generate/store.| `null`                 |
| `authHandler`     | Custom function that receives `clientAuth` and returns `true`/`false`.      | `null`                 |
| `authOptions`     | Configuration object passed to internal `StarAuth` for authentication.      | `{}`                   |
| `dirMode`         | UNIX permission mode for directories (e.g., `0o700`).                       | `0o700`                |
| `fileMode`        | UNIX permission mode for files (e.g., `0o600`).                             | `0o600`                |

---


## 🔐 authOptions (StarAuth Configuration)

Pass this object under the `options.authOptions` key when creating your `StarVault` instance.

### Collection Settings

| Key                   | Description                                | Default             |
|----------------------|--------------------------------------------|---------------------|
| `collection`          | User collection name                        | `"auth-users"`      |
| `sessionCollection`   | Session tracking collection                 | `"auth-sessions"`   |
| `resetCollection`     | Password reset token collection             | `"auth-resets"`     |
| `stellarCollection`   | Magic link / code token collection          | `"stellar-auths"`   |

### Session Behavior

| Key                        | Description                                             | Default                  |
|---------------------------|---------------------------------------------------------|--------------------------|
| `tokenExpiry`             | Token lifetime in seconds                              | `3600` (1 hour)          |
| `lockoutDuration`       | Lock duration after failed login attempts              | `900000` (15 minutes)    |
| `maxLoginAttempts`        | Max allowed failures before lockout                    | `5`                      |
| `sessionValidationFields` | Fields to check for session hijack                     | `["ip", "fingerprint"]`  |
| `strictSessionValidation` | Reject session if mismatch in validation fields        | `true`                   |
| `enableSuspiciousCheck`   | Compare geo/IP with previous sessions                  | `true`                   |
| `enableGeo`               | Enable geo lookups on login                            | `false`                  |
| `sessionPolicy`           | "default", "strict", or "replace" session strategies | `"default"`             |

### Stellar Login

| Key                        | Description                                     | Default         |
|---------------------------|-------------------------------------------------|-----------------|
| `stellarRequestCooldown`| Minimum delay between stellar requests          | `60000` (1 min) |
| `generateStellarCode`     | Function to generate a stellar numeric code     | 6-digit default |

### Hooks & Extensions

| Key                  | Description                                          |
|----------------------|------------------------------------------------------|
| `onSuspiciousSession`| `(currentSession, pastSession) => void`              |
| `handleHijack`       | `(session, field, expected, actual) => void`         |
| `onCleanup`          | `({ result, timestamp, vaultID }) => void`           |
| `tagSession`         | `(session, userData) => string[]`                    |

### Cleanup & Locking

| Key                           | Description                                          | Default     |
|--------------------------------|------------------------------------------------------|-------------|
| `vaultID`                      | ID for this vault instance                          | `null`      |
| `lockingCombinations`         | Password hash complexity via @trap_stevo/encryped-lock      | `10`        |
| `autoCleanupInterval`       | How often to auto-clean expired tokens              | `null`      |
| `expiredSessionCleanupInterval`    | Interval for cleaning expired sessions   | `null`  |
| `cleanupExpiredTokensActionInfo` | Metadata for cleanup activity                  | `{}`        |
| `cleanupExpiredTokensClientAuth` | Auth context used for cleanup calls           | `null`      |
| `cleanupExpiredSessionsActionInfo` | Metadata for session cleanup             | `{}`    |
| `cleanupExpiredSessionsClientAuth` | Auth context used during session cleanup | `null`  |

---


## 📦 Core Methods

These are the primary database interaction methods.

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `create(collection, data, actionInfo = {}, clientAuth = null)` | Creates a new record in the specified collection. Returns the created record object. | ✅ Sync |
| `update(collection, id, updates, actionInfo = {}, clientAuth = null)` | Updates an existing record by ID. Setting record data properties to undefined removes them respectively. Returns the updated record. Throws error if not found. | ✅ Sync |
| `unset(collection, id, dotPaths = [], actionInfo = {}, clientAuth = null)` | Removes specific nested fields using dot notation (e.g., "profile.stats.xp"). Returns updated record. | ✅ Sync |
| `deleteCollection(collection, actionInfo = {}, clientAuth = null)` | Deletes an entire collection. Returns `{ wholeCollection: true, deleted: true/false }`. | ✅ Sync |
| `deleteRecord(collection, id, actionInfo = {}, clientAuth = null)` | Deletes a specific record by ID. Returns `{ id, deleted: true/false }`. | ✅ Sync |
| `delete(collection, id, actionInfo = {}, clientAuth = null)` | Soft-deletes a record by filtering it out and overwriting the collection. Returns `{ id, deleted: true }`. | ✅ Sync |

---


## 🔍 Query Engine

Chainable query builder for filtering and searching collection data.

```js
vault.query("collection")
     .where({ key: "value" })                         // Filters by key-value pairs
     .search("field", "text")                         // Text search within a specific field
     .recent("timestamp", "7d")                       // Gets records from the last 7 days
     .near("location", { lat: 0, lng: 0 }, 50)        // Geospatial filter within 50 units
     .sort({ name: 1 })                               // Sorts by a field (1 = asc, -1 = desc)
     .select(["id", "name"])                          // Selects specific fields
     .limit(10)                                       // Limits results
     .offset(0)                                       // Skips first N records
     .filterBy(record => record.active)              // Filters with custom function
     .execute(exactCollection = false)                // Run the query with optional strict collection matching
```

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `query(collection)` | Begins a query on the specified collection. Returns a chainable builder. | ✅ Sync |
| `where(criteria)` | Filters records by matching key-value pairs. | ✅ Sync |
| `search(field, text)` | Performs a text search within a specified field. | ✅ Sync |
| `recent(field, duration)` | Filters records based on recency (e.g., `"7d"` = 7 days). | ✅ Sync |
| `near(field, center, radius)` | Filters based on proximity to a location object `{ lat, lng }`. | ✅ Sync |
| `sort(criteria)` | Sorts the results by one or more fields. | ✅ Sync |
| `select(fields)` | Selects only the specified fields for output. | ✅ Sync |
| `limit(number)` | Restricts the number of records returned. | ✅ Sync |
| `offset(number)` | Skips a number of records (used for pagination). | ✅ Sync |
| `filterBy(fn)` | Filters using a custom function on each record. | ✅ Sync |
| `callback(fn)` | Adds a side effect or transformation hook before execution. | ✅ Sync |
| `execute(exactCollection = false)` | Run the query. If `true`, match only the exact collection name; otherwise, include related subcollections. | ✅ Sync |
| `getByID(collection, id)` | Shortcut to retrieve a single record by ID. | ✅ Sync |
| `range(min, max)` | Static helper to return an inclusive array of numbers in a range. | ✅ Sync |

---


## 🛡️ Authentication

All methods below require `authOptions` configuration and are used for session/user management.

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `registerUser(email, password, actionInfo, clientAuth)` | Registers a new user. Returns `{ success, token, user }`. | ⚙️ Async |
| `loginUser(email, password, req, actionInfo, clientAuth)` | Logs in a user and creates a session. Returns `{ token, user }` or throws error on failure. | ⚙️ Async |
| `logoutUser(token, actionInfo, clientAuth)` | Logs out the user by invalidating the token. Returns success boolean. | ✅ Sync |
| `extendUserSession(token, ms, actionInfo, clientAuth)` | Extends the current session's expiration. Returns updated session info. | ✅ Sync |
| `deactivateOtherSessions(userID, currentSessionID, actionInfo, clientAuth)` | Deactivates all sessions for a user except the current one. Used with `sessionPolicy: "replace"`. | ⚙️ Async |
| `requestUserPasswordReset(email, actionInfo, clientAuth)` | Sends a password reset email/token. Returns success status. | ✅ Sync |
| `resetUserPassword(token, newPassword, actionInfo, clientAuth)` | Resets the password for the user with the token. Returns success or throws on error. | ✅ Sync |
| `requestUserStellarLink(email, type, actionInfo, clientAuth)` | Sends a link-based login or action email. Returns token or success response. | ✅ Sync |
| `consumeUserStellarToken(token, type, req, actionInfo, clientAuth)` | Consumes a stellar auth token to finalize an action. Returns user/session info. | ✅ Sync |
| `cleanupExpiredTokens(actionInfo, clientAuth)` | Clears expired sessions and tokens. Returns count of cleaned items. | ✅ Sync |
| `cleanupExpiredSessions(actionInfo, clientAuth)` | Marks expired sessions as inactive. Returns updated session list. | ✅ Sync |

---


## 🎧 Event Listening

Used for reactive, event-driven architecture patterns.

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `listen(event, nodePath, callback)` | Registers a callback for a specific event (`create`, `update`, `delete`) at a given path. | ✅ Sync |
| `emit(event, nodePath, data)` | Triggers callbacks for listeners whose paths match the emitted path. | ✅ Sync |

---


## 🌌 Collection & Path Matching

Utilities for dynamic collection operations and wildcard paths.

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `getMatchingCollections(basePath)` | Resolves wildcard-based paths like `logs/*/2025` to real collection names. Returns string array. | ✅ Sync |
| `matchesPath(listenerPath, nodePath)` | Checks if an emitted node path matches a listener's wildcard path. Returns boolean. | ✅ Sync |

---


## ✨ Getting Started

### Installation

```bash
npm install @trap_stevo/star-vault
```

### Basic Usage

```js
const StarVault = require("@trap_stevo/star-vault");

const vault = new StarVault(
     "./data",
     "./logs",
     4,
     "869MB",
     "1w",
     {
          enableEncryption : true,
          masterKey : "supersecretkey",
          authHandler : (auth) => auth.token === "valid-token"
     }
);

vault.create("users", { id : "001", name : "Nova" }, { source : "init" }, { token : "valid-token" });
```

---


## 📈 Querying

```js
const results = vault.query("users")
     .where({ role : "admin" })
     .sort({ name : 1 })
     .select(["id", "name"])
     .limit(10)
     .execute();
```

---


## 🎧 Listening to Changes

```js
vault.listen("create", "users/*", (path, data) => {
     console.log("New user created:", path, data);
});
```

---


## 🌐 Wildcard Collection Queries

```js
vault.query("logs/*/2025")
     .recent("timestamp", "7d")
     .execute();
```

---


## ✨ License

See License in [LICENSE.md](./LICENSE.md)

---


## 🚀 Transform Data into Action

StarVault transcends traditional data systems—offering a full-fledged database engine and cosmic foundation that propels secure, reactive, and intelligent data-driven architectures.