@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

# 🚀 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

---


## ⚙️ System Requirements

| Requirement    | Version            |
|----------------|--------------------|
| **Node.js**    | ≥ 19.x             |
| **npm**        | ≥ 9.x (recommended)|
| **OS**         | Windows, macOS, Linux |

---


# 📜 API Specifications

## 🔧 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`                   |
| `sessionPolicy`           | "default", "strict", or "replace" session strategies | `"default"`             |

### Password Management

| Key                  | Description                                                                                  | Default                                    |
|----------------------|----------------------------------------------------------------------------------------------|--------------------------------------------|
| `passwordRequirements` | Object defining the password policy                                                         | `{ minLength: 8, requireLetter: true, requireNumber: true, requireSymbol: false }` |
| └ `minLength`        | Minimum number of characters required                                                        | `8`                                        |
| └ `requireLetter`    | Requires at least one letter (a-z or A-Z)                                                    | `true`                                     |
| └ `requireNumber`    | Requires at least one numeric digit (0-9)                                                    | `true`                                     |
| └ `requireSymbol`    | Requires at least one symbol (e.g., `!@#$%^&*`)                                               | `false`                                    |
| └ `customValidator`  | Optional custom function `(password) => boolean` for advanced password checks                | `null`                                     |
| `lockingCombinations`         | Password hash complexity      | `10`        |

### 🌍 Geo Lookup Configuration

| Key                  | Description                                                                 | Default  |
|----------------------|-----------------------------------------------------------------------------|----------|
| `enableGeo`          | Enable geo lookups on login/session events                                  | `false`  |
| `enableGeoDebug`     | If `true`, logs which geo service succeeded or failed during lookup         | `false`  |
| `geoServices`        | Array of additional geo lookup functions `(ip) => geoData | null`           | `[]`     |
| `ipgeolocationKey`   | API key for ipgeolocation.io (enables provider if set)                      | `null`   |
| `ipinfoToken`        | API token for ipinfo.io (enables provider if set)                           | `null`   |

### 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[]`                    |

### Guest Session Configurations

| Key                         | Description                                                                 | Default                          |
|-----------------------------|-----------------------------------------------------------------------------|----------------------------------|
| `allowGuestSessions`        | Enables or disables guest session support.                                  | `true`                           |
| `guestInactivityThreshold`  | Duration of inactivity (in ms) before considering a guest account stale.  | `7 * 24 * 60 * 60 * 1000` (1w)   |
| `cleanupGuestInterval`      | Interval (in ms) to check for inactive guest accounts.                      | `5 * 60 * 1000` (5m)             |
| `guestActivityTrackers`     | Array of custom functions to execute on guest activity updates.             | `[]`                             |
| `generateGuestID`           | Function to generate guest user IDs.                                        | `() => "guest-" + UUID` |

### Cleanup & Locking

| Key                           | Description                                          | Default     |
|--------------------------------|------------------------------------------------------|-------------|
| `vaultID`                      | ID for this vault instance                          | `null`      |
| `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

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")
     .whereRecord("id", "value")                         // Filters root record data by key-value pairs
     .where({ key: "value" })                         // Filters record data 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 |
| `whereRecord(criteria)` | Filters records by matching key-value pairs. Accepts both object and parameter inputs. | ✅ Sync |
| `where(criteria)` | Filters records' data by matching key-value pairs. Accepts both object and parameter inputs. | ✅ 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.

---


### 👤 User Registration & Authentication

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `registerUser(email, password, actionInfo, clientAuth)` | Registers a new user. `. | ⚙️ Async |
| `registerGuestUser(req, metadata, actionInfo, clientAuth)` | Registers a temporary guest user. `. | ⚙️ Async |
| `loginGuestUser(accountID, req, actionInfo, clientAuth)` | Logs in a guest user and creates a session. `. | ⚙️ Async |
| `loginUser(email, password, req, actionInfo, clientAuth)` | Logs in a user and creates a session. `. | ⚙️ Async |
| `resumeUserSession(accountID, req, actionInfo, clientAuth)` | Resumes session from account ID (used for guest linking or session carryover). | ⚙️ Async |
| `upgradeGuestUser(accountID, email, password, actionInfo, clientAuth)` | Converts a guest account to a full registered user. | ⚙️ Async |

---


### 🛰️ Session Management

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `logoutUser(token, actionInfo, clientAuth)` | Logs out a user by invalidating their session token. | ✅ Sync |
| `extendUserSession(token, ms, actionInfo, clientAuth)` | Extends an active session's duration. | ✅ Sync |
| `cleanupExpiredAuthTokens(actionInfo, clientAuth)` | Cleans up expired tokens and invalid sessions. | ✅ Sync |
| `cleanupInactiveGuests(actionInfo, clientAuth)` | Removes or deactivates inactive guest accounts. | ⚙️ Async |

---


### 🔑 Password & Magic Link Recovery

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `updateUserPassword(userID, newPassword, actionInfo, clientAuth)` | Updates a user's password. | ⚙️ Async |
| `requestUserPasswordReset(email, actionInfo, clientAuth)` | Sends a password reset token. | ⚙️ Async |
| `resetUserPassword(token, newPassword, actionInfo, clientAuth)` | Resets password using a valid token. | ⚙️ Async |
| `requestUserStellarLink(email, type, actionInfo, clientAuth)` | Sends a Stellar link (magic link or code) for login or verification. | ⚙️ Async |
| `consumeUserStellarToken(token, type, req, actionInfo, clientAuth)` | Consumes a Stellar link/token to verify user and return session. | ⚙️ Async |

---


### 👥 Guest Account Management

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `registerGuestUser(req, metadata, actionInfo, clientAuth)` | Registers a guest session with optional request/metadata. | ⚙️ Async |
| `trackGuestActivity(userID, timestamp, actionInfo, clientAuth)` | Updates guest user's `lastActiveAt` timestamp. | ⚙️ Async |
| `upgradeGuestUser(accountID, email, password, actionInfo, clientAuth)` | Promotes a guest to a full registered account. | ⚙️ Async |
| `cleanupInactiveGuests(actionInfo, clientAuth)` | Cleans up inactive or stale guest users based on threshold. | ⚙️ Async |

---


### 🔁 User Lifecycle Management

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `updateUser(accountID, updatedMetadata, accountType, actionInfo, clientAuth)` | Updates a user by Account ID. Does not allow for password updates. | ⚙️ Async |
| `deleteUser(userID, reason, actionInfo, clientAuth)` | Soft-deletes a user by ID. | ⚙️ Async |
| `deleteUserByAccountID(accountID, reason, actionInfo, clientAuth)` | Soft-deletes a user using their account ID. | ⚙️ Async |
| `reactivateUser(userID, actionInfo, clientAuth)` | Reactivates a previously deleted user. | ⚙️ Async |
| `reactivateUserByAccountID(accountID, actionInfo, clientAuth)` | Reactivates a deleted user by account ID. | ⚙️ Async |

---


### 📊 User & Session Querying

| Method | Description | Sync/Async |
|--------|-------------|------------|
| `getUserByAccountID(accountID, filter, accountType, actionInfo)` | Retrieves a user by account id. If a certain account type (default ~ guest). | ⚙️ Async |
| `getUser(userID, filter, accountType, actionInfo)` | Retrieves a user by id. If a certain account type (default ~ guest). | ⚙️ Async |
| `getUserSession(sessionID, actionInfo)` | Retrieves a session by id. | ⚙️ Async |
| `listSessions(userID, filters, includeInactive, actionInfo)` | Lists sessions for a specific user. | ⚙️ Async |
| `listAllSessions(filters, includeInactive, actionInfo)` | Lists all sessions across users. | ⚙️ Async |
| `listUsers(filters, options, actionInfo)` | Lists users based on filters and options (pagination, includes). | ⚙️ Async |
| `listUserActivity(options, actionInfo)` | Lists recent activity, including filtering by active, inactive, or recently seen users. | ⚙️ Async |

### 🧩 Internal Validation & Utility Methods

The following utility methods get utilized internally across authentication-related flows. You may call them directly for validation, diagnostics, or extension purposes.

| Method                         | Description                                                                                   | Sync/Async |
|--------------------------------|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `validEmail(email)`      | Determines if an input email follows proper email address format.                             | ✅ Sync |
| `satisfiesPasswordStrength(password)` | Validates whether the password meets the defined `passwordRequirements`.                   |  ✅ Sync |
| `extractSessionMetadata(req)`  | Extracts metadata (IP, fingerprint, user agent, etc.) from the request object .               | ✅ Sync  |
| `lookupUserGeo(ip)`                | Performs geo-IP lookup using built-in and custom geo services   .                             | ⚙️ Async |

---


## 🎧 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. | ✅ Sync |
| `matchesPath(listenerPath, nodePath)` | Checks if an emitted node path matches a listener's wildcard path. | ✅ Sync |

---


## 🌌 StarVault Events

StarVault emits real-time events that let you react to data and authentication lifecycle changes across your app. These include both **record-level events** and **auth lifecycle events**.

You can listen to them at multiple levels of granularity:

- 🔁 **Global listeners** (across all collections and records)
- 📁 **Collection-level listeners** (any record in a collection)
- 🧾 **Record-specific listeners** (a specific record path)

---


###  🔔 Emitted Record Events (StarVault Core)

| Event    | Description                             | Emitted Path            |
|----------|-----------------------------------------|--------------------------|
| `create` | Fires on record creation.                 | `collectionName/recordID`   |
| `update` | An existing record  updated           | `collectionName/recordID`   |
| `delete` | A record got deleted (soft or hard)      | `collectionName/recordID`   |

---


### 🔐 Emitted Auth Lifecycle Events (StarAuth)

| Event               | Description                                               |
|---------------------|-----------------------------------------------------------|
| `guest:upgraded`    | A guest account successfully upgraded to a full user  |
| `guest:updated`    | A guest account successfully updated  |
| `user:updated`    | A user account successfully updated  |
| `session:resumed`   | A user session resumed from a valid token             |
| `user:guestExpired` | A guest account expired due to inactivity                 |
| `user:deleted`      | A user account got marked for deletion                     |
| `user:reactivated`  | A previously deleted user got reactivated                 |

---


###  🪐 Global Listener (All Changes Across Vault)

```js
vault.listen("create", "*", (path, data) => {
     console.log("Created:", path, data);
});

vault.listen("update", "*", (path, data) => {
     console.log("Updated:", path, data);
});

vault.listen("delete", "*", (path, data) => {
     console.log("Deleted:", path, data);
});
```

---


###  📂 Collection-Level Listener

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

vault.listen("update", "inventory/*", (path, data) => {
     console.log("Inventory updated:", path, data);
});
```

---


###  🧍 Record-Specific Listener

```js
vault.listen("update", "orders/12345", (path, data) => {
     console.log("Order updated:", data);
});

vault.listen("delete", "accounts/user-abc", (path, data) => {
     console.log("User deleted:", data);
});
```

---


###  🎯 Advanced Wildcard Usage

```js
// Match nested logs by year
vault.listen("update", "logs/*/2025/*", (path, data) => {
     console.log("Log updated:", path);
});
```

---


###  🧠 Listening to StarAuth Lifecycle Events

Use `.on()` to subscribe to StarAuth-specific events:

```js
vault.on("guest:upgraded", (info) => {
     console.log("Guest upgraded:", info);
});

vault.on("user:deleted", (info) => {
     console.log("User deleted:", info);
});

vault.on("user:reactivated", (info) => {
     console.log("User reactivated:", info);
});
```

---


These event hooks power real-time dashboards, activity tracking, notifications, and custom automation — all deeply integrated with StarVault's reactive system.

---


## ✨ 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", "*", (path, data) => {
     console.log("[CREATE - ANY] Path:", path, data);
});

vault.listen("create", "users/*", (path, data) => {
     console.log("[CREATE - users] Path:", path, data);
});

vault.listen("update", "users/*", (path, data) => {
     console.log("[UPDATE - users] Path:", path, data);
});

// Listen for updates to a specific user record (e.g., user ID '001')
vault.listen("update", "users/user-001", (path, data) => {
     console.log("[UPDATE - users/user-001] Path:", path, data);
});

vault.listen("delete", "users/*", (path, data) => {
     console.log("[DELETE - users] Path:", path, data);
});

vault.listen("delete", "logs/*/2025", (path, data) => {
     console.log("[DELETE - logs/*/2025] Path:", path, data);
});

// Listen for a specific log record inside a structured path (e.g., logs/server1/2025/log-99)
vault.listen("create", "logs/server1/2025/log-99", (path, data) => {
     console.log("[CREATE - logs/server1/2025/log-99] Path:", path, data);
});

// Listen to everything happening in 'auth-sessions'
vault.listen("create", "auth-sessions", (path, data) => {
     console.log("[CREATE - auth-sessions] Path:", path, data);
});

vault.listen("update", "auth-sessions", (path, data) => {
     console.log("[UPDATE - auth-sessions] Path:", path, data);
});

vault.listen("delete", "auth-sessions", (path, data) => {
     console.log("[DELETE - auth-sessions] Path:", path, data);
});
```

---


## 🌐 Wildcard Collection Queries

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

---


## 👥 Registering Users (Guest and Normal)

```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 === "star-vault-demo",
          authOptions : {
               allowGuestSessions : true,
               generateGuestID : () =>  "guest-" + Math.floor(Math.random() * 1000000)
          }
     }
);

// Register a full user
const userResult = await vault.registerUser("nova@example.com", "strongpassword123", { source : "site" }, { token : "star-vault-demo" });
console.log("Registered user:", userResult);

// Register a guest user
const guestResult = await vault.registerGuestUser({ ip : "127.0.0.1" }, { referrer : "home" }, { source : "guest-form" }, { token : "star-vault-demo" });
console.log("Registered guest:", guestResult);
```

---


## 📋 Listing Users and Sessions

```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 === "star-vault-demo"
     }
);

// List all users
const users = await vault.listUsers({}, { limit : 25 }, { token : "star-vault-demo" });
console.log("All users:", users);

// List all sessions (including inactive and deleted)
const sessions = await vault.listAllSessions({ includeDeleted : "only" }, true, { token : "star-vault-demo" });
console.log("All sessions:", sessions);

// List sessions for a specific user
const userSessions = await vault.listSessions("user-001", { device : "mobile" }, false, { token : "star-vault-demo" });
console.log("Sessions for user-001:", userSessions);

// List recent user activity (active and inactive)
const activity = await vault.listUserActivity({
     includeInactive : true,
     onlyMostRecent : true
}, { token : "star-vault-demo" });

console.log("User activity:", activity);
```

---


## ✨ License

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

---


## 🚀 Transform Data into Action

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