### AxioDB Quick Start: Hello World

Source: https://github.com/nexoral/axiodb/blob/main/README.md

A quick start example demonstrating how to create an AxioDB instance with the GUI enabled, create a database and collection, insert data, and retrieve it. Ensure Node.js v20.0.0+ is installed.

```javascript
// npm install axiodb
const { AxioDB } = require('axiodb');

// Create AxioDB instance with built-in GUI
const db = new AxioDB({ GUI: true }); // Enable GUI at localhost:27018

// Create database and collection
const myDB = await db.createDB('HelloWorldDB');
const collection = await myDB.createCollection('greetings', false);

// Insert and retrieve data - Hello World! 👋
await collection.insert({ message: 'Hello, Developer! 👋' });
const result = await collection.findAll();
console.log(result[0].message); // Hello, Developer! 👋
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Navigate to the GUI directory, install dependencies using npm, and start the development server. The development server runs at http://localhost:5173.

```bash
# Navigate to GUI directory
cd GUI

# Install dependencies
npm install

# Start development server
npm run dev
```

--------------------------------

### Install and Run Documentation Locally

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Navigate to the 'Document' directory, install dependencies, and start the development server for the AxioDB documentation website.

```bash
cd Document
npm install
npm run dev
```

--------------------------------

### AxioDB Hello World

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

A quick start example demonstrating how to create an AxioDB instance, set up a database and collection, insert a document, and retrieve it. The GUI option starts a web interface at localhost:27018.

```javascript
const { AxioDB } = require('axiodb');

// Create AxioDB instance with built-in GUI
const db = new AxioDB({ GUI: true }); // GUI at localhost:27018

// Create database and collection
const myDB = await db.createDB('HelloWorldDB');
const collection = await myDB.createCollection('greetings');

// Insert and retrieve data
await collection.insert({ message: 'Hello, Developer! 👋' });
const result = await collection.findAll();
console.log(result[0].message); // Hello, Developer! 👋
```

--------------------------------

### Install Dependencies

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Command to install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Development Commands

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Run specific test files or start the local documentation development server.

```bash
# Development
node Test/modules/crud.test.js  # Run specific test
cd Document && npm run dev      # Docs site (localhost:5173)
```

--------------------------------

### AxioDB Transaction Example

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Demonstrates how to use transactions with savepoints and automatic commit/rollback in AxioDB. Ensure you have a collection object to start a session.

```javascript
const session = collection.startSession();
await session.withTransaction(async (tx) => {
  await tx.insert({ name: 'Alice', balance: 1000 });
  await tx.update({ name: 'Bob' }, { $inc: { balance: -100 } });
  // Auto-commits on success, auto-rollbacks on error
});
```

--------------------------------

### AxioDB E-Commerce Product Catalog Example

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

An example demonstrating the creation of an e-commerce product catalog using AxioDB. It includes schema definition, collection creation, product insertion, and querying.

```javascript
const { AxioDB, SchemaTypes } = require('axiodb');
const db = new AxioDB();

const shopDB = await db.createDB('ecommerce');

const productSchema = {
  name: SchemaTypes.string().required(),
  price: SchemaTypes.number().required().min(0),
  category: SchemaTypes.string().required(),
  inStock: SchemaTypes.boolean().required(),
};

const products = await shopDB.createCollection('products', true, productSchema);

// Add products
await products.insert({
  name: 'Laptop',
  price: 999.99,
  category: 'Electronics',
  inStock: true,
});

// Query products
const electronics = await products
  .query({ category: 'Electronics', inStock: true })
  .Sort({ price: 1 })
  .exec();
```

--------------------------------

### Install Latest AxioDB Version

Source: https://github.com/nexoral/axiodb/blob/main/SECURITY.md

Install the latest version of AxioDB to ensure you have the most up-to-date security patches and features.

```bash
npm install axiodb@latest
```

--------------------------------

### Example Test for Insert Operation

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

A JavaScript example demonstrating how to write a test for an insert operation. It checks for success and logs the result.

```javascript
// Test for insert operation
const testInsert = async () => {
  const collection = await db.createCollection('test', false);
  const result = await collection.insert({ name: 'Test User' });

  if (result.success) {
    console.log('✓ Insert test passed');
  } else {
    console.error('✗ Insert test failed');
  }
};
```

--------------------------------

### Example Bug Report

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

An example of a detailed bug report including environment, steps to reproduce, expected and actual behavior, and a code snippet demonstrating the issue.

```javascript
const collection = await db.createCollection('test', true, schema, true, 'short');
```

--------------------------------

### JSDoc Example for Insert Method

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Document public methods using JSDoc, including parameters, return types, potential errors, and a clear usage example.

```typescript
/**
 * Creates a new document in the collection.
 *
 * @param {object} document - The document to insert
 * @returns {Promise<SuccessInterface | ErrorInterface>} Insert result with documentId
 * @throws {Error} If document validation fails
 *
 * @example
 * const result = await collection.insert({ name: 'John', age: 30 });
 * console.log(result.documentId); // Auto-generated ID
 */
async insert(document: object): Promise<SuccessInterface | ErrorInterface> {
  // ...
}
```

--------------------------------

### Troubleshoot AxioDB Container Startup Issues

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Commands to help diagnose why an AxioDB Docker container might not be starting. This includes checking container logs and verifying if a port is already in use.

```bash
# Check container logs\
docker logs axiodb-server\
\
# Check if port is already in use\
netstat -tulpn | grep :27018
```

--------------------------------

### AxioDB NPM Package Usage Example

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Demonstrates creating an AxioDB instance, creating a database and a collection with schema validation, and inserting a document using the AxioDB NPM package in a Node.js application.

```javascript
const { AxioDB, SchemaTypes } = require("axiodb");

// Create a single AxioDB instance
const db = new AxioDB();

const main = async () => {
  // Create database and collection
  const database = await db.createDB("myApp");
  const collection = await database.createCollection("users", true, {
    name: SchemaTypes.string().required(),
    email: SchemaTypes.string().required().email(),
    age: SchemaTypes.number().min(0).max(120),
  });

  // Insert document
  const result = await collection.insert({
    name: "John Doe",
    email: "john@example.com",
    age: 30,
  });

  console.log(result);
};

main();
```

--------------------------------

### Conventional Commits: Feature Example

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Example of a 'feat' type commit message for adding a new feature. Includes subject, body, and footer referencing an issue.

```bash
feat(core): add support for bulk delete operations

Added DeleteMany method to allow efficient deletion of multiple
documents matching a query. Includes caching invalidation.

Closes #123
```

--------------------------------

### TypeScript Function Example

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

An example of an asynchronous TypeScript function with JSDoc comments, demonstrating how to insert a document into a collection.

```typescript
/**
 * Inserts a document into the collection
 * @param data - The document data to insert
 * @returns Promise resolving to operation result
 */
async insert(data: object): Promise<SuccessInterface | ErrorInterface> {
  // Implementation
}
```

--------------------------------

### Install AxioDB NPM Package

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Installs the latest version of the AxioDB NPM package using npm. This package is recommended for Node.js applications for better performance and direct integration.

```bash
npm install axiodb@latest --save
```

--------------------------------

### Conventional Commits: Fix Example

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Example of a 'fix' type commit message for resolving a bug. Includes subject, body, and footer referencing a fix.

```bash
fix(encryption): resolve key length validation issue

Fixed encryption key validation to properly check AES-256 requirements.
Minimum key length is now enforced at 32 bytes.

Fixes #456
```

--------------------------------

### AxioDBCloud TCP Remote Access Example

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Connects to the AxioDB server via TCP remote access using the AxioDBCloud client. Creates a database and a collection, then inserts a document.

```javascript
const { AxioDBCloud } = require('axiodb');

const db = new AxioDBCloud('axiodb://localhost:27019');
await db.connect();

const database = await db.createDB('myDatabase');
const collection = await database.createCollection('users');
const result = await collection.insert({ name: 'John', age: 30 });
```

--------------------------------

### Enable Encryption with Auto-Generated Key

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Use this snippet to create a collection with automatic AES-256 encryption enabled. No additional setup is required.

```javascript
const encrypted = await database.createCollection(
  'sensitiveData',
  true,
  schema,
  true  // Enable encryption
);
```

--------------------------------

### AxioDB Aggregation Pipeline

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Perform complex data processing using aggregation pipelines. This example matches documents, groups them by department, sorts by count, and limits the results.

```javascript
const stats = await collection
  .aggregate([
    { $match: { age: { $gt: 20 } } },
    { $group: { _id: '$department', count: { $sum: 1 } } },
    { $sort: { count: -1 } },
    { $limit: 10 },
  ])
  .exec();
```

--------------------------------

### Run AxioDB Container on Different Ports

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

If the default ports (27018, 27019) are already in use, you can map them to different host ports when running the Docker container. This example maps them to 8080 and 8081.

```bash
# Use a different port\
docker run -d --name axiodb-server -p 8080:27018 -p 8081:27019 theankansaha/axiodb
```

--------------------------------

### AxioDB Bulk Update Many

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Update multiple documents that match a specific query using UpdateMany. This example updates the 'bonus' field for all documents where 'department' is 'Sales'.

```javascript
// Update many
await collection
  .update({ department: 'Sales' })
  .UpdateMany({ bonus: 1000 });
```

--------------------------------

### AxioDB Schema Validation

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Define schemas for collections to enforce data consistency and structure. This example shows how to define a product schema with required fields, type constraints, and value ranges.

```javascript
const { SchemaTypes } = require('axiodb');

const productSchema = {
  name: SchemaTypes.string().required().max(100),
  price: SchemaTypes.number().required().min(0),
  inStock: SchemaTypes.boolean().required(),
  tags: SchemaTypes.array(),
  metadata: SchemaTypes.object(),
};

const products = await db.createDB('shop')
  .then(db => db.createCollection('products', true, productSchema));
```

--------------------------------

### Build and Preview Production Build

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Build the project for production and then preview the production build. These commands are used for deploying the GUI.

```bash
# Build for production
npm run build

# Preview production build
npm run preview
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Steps to clone the AxioDB repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR-USERNAME/AxioDB.git
cd AxioDB
```

--------------------------------

### Register and Login User

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Demonstrates how to insert a new user into the 'users' collection and how to query for a user by username.

```javascript
// Register user
await users.insert({
  username: 'johndoe',
  email: 'john@example.com',
  passwordHash: hashedPassword,
  createdAt: new Date(),
});

// Login
const user = await users
  .query({ username: 'johndoe' })
  .exec();
```

--------------------------------

### Create Databases and Collections

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Demonstrates how to create new databases and collections, including encrypted ones with custom keys.

```javascript
const { AxioDB } = require("axiodb");
const db = new AxioDB();

const userDB = await db.createDB("MyDB");

// Create basic collection
const userCollection = await userDB.createCollection("Users");

// Create encrypted collection with custom key
const secureCollection = await userDB.createCollection(
  "SecureUsers",
  true,
  "mySecretKey",
);

await userCollection.insert({
  name: "John Doe",
  email: "john.doe@example.com",
  age: 30,
});

const results = await userCollection
  .query({ age: { $gt: 25 } })
  .Limit(10)
  .Sort({ age: 1 })
  .exec();
console.log(results);
```

--------------------------------

### Build and Run AxioDB Docker Image from Source

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Instructions for cloning the AxioDB repository, building the Docker image locally, and running the container. This is useful for development or custom builds.

```bash
# Clone the repository\
git clone https://github.com/nexoral/AxioDB.git\
cd AxioDB/Docker\
\
# Build the Docker image\
docker build -t axiodb:latest .\
\
# Run the container\
docker run -d --name axiodb-server -p 27018:27018 -p 27019:27019 axiodb:latest
```

--------------------------------

### Run Tests

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Command to execute the project's test suite.

```bash
npm test
```

--------------------------------

### Check Node.js and npm Versions

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Verify that your Node.js and npm versions meet the minimum requirements for building the GUI. Ensure Node.js is version 20.0.0 or higher, and npm is version 6.0.0 or higher.

```bash
node --version  # Should be >= 20.0.0
npm --version   # Should be >= 6.0.0
```

--------------------------------

### Common Build and Test Commands

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Execute build, test, and linting tasks using npm scripts. Run specific test suites or individual test files as needed.

```bash
# Build & Test
npm run build              # TypeScript → lib/ (MANDATORY)
npm test                   # All tests (separate processes)
npm test crud              # CRUD tests only
npm test transaction       # Transaction tests only
npm test read              # Read optimization tests
npm run lint               # ESLint
```

--------------------------------

### AxioDB Bulk Delete Many

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Delete multiple documents that match a specific query using deleteMany. This example deletes all documents where 'status' is 'inactive'.

```javascript
// Delete many
await collection
  .delete({ status: 'inactive' })
  .deleteMany();
```

--------------------------------

### AxioDB Schema Validation

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Define strict schemas using SchemaTypes to prevent invalid data from being inserted into collections. This example defines a schema for email and age.

```javascript
// Define strict schemas to prevent bad data
const schema = {
  email: SchemaTypes.string().required().email(),
  age: SchemaTypes.number().min(0).max(150),
};
```

--------------------------------

### Build and Test Commands

Source: https://github.com/nexoral/axiodb/blob/main/CLAUDE.md

Common npm commands for building, testing, and linting the AxioDB project. Includes commands for running specific test modules.

```bash
npm run build    # TypeScript → lib/ (MANDATORY after changes)
npm test        # Run all tests (separate processes)
npm run lint    # ESLint check

# Test specific module
npm test crud | transaction | read
node Test/modules/crud.test.js
```

--------------------------------

### Build Project

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Command to build the project, likely compiling TypeScript to JavaScript.

```bash
npm run build
```

--------------------------------

### Create Single AxioDB Instance

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Instantiate AxioDB once for your entire application. This instance will manage all databases and collections.

```javascript
const { AxioDB } = require('axiodb');
const db = new AxioDB(); // Single instance for entire app
```

--------------------------------

### Initialize AxioDB with TCP Enabled (Node.js)

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Initializes an AxioDB instance locally, disabling the GUI but enabling TCP remote access on the default port. Specify a custom root name and data path if needed.

```javascript
const { AxioDB } = require('axiodb');
const db = new AxioDB({ GUI: false, RootName: 'MyDB', CustomPath: '.', TCP: true }); // Enable TCP on port 27019
```

--------------------------------

### AxioDB Query Operators

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

AxioDB supports MongoDB-style query operators for filtering data. Examples include comparison operators like $gt, $lt, $ne, and logical operators like $in, $regex.

```javascript
// Comparison
{ age: { $gt: 25 } }           // Greater than
{ age: { $gte: 25 } }          // Greater than or equal
{ age: { $lt: 50 } }           // Less than
{ age: { $lte: 50 } }          // Less than or equal
{ age: { $ne: 30 } }           // Not equal

// Logical
{ age: { $in: [25, 30, 35] } } // In array
{ name: { $regex: 'John' } }   // Regex match

// Examples
const young = await collection.query({ age: { $lt: 30 } }).exec();
const specific = await collection.query({ age: { $in: [25, 30, 35] } }).exec();
const johns = await collection.query({ name: { $regex: 'John' } }).exec();
```

--------------------------------

### Run AxioDB Docker Container with Environment Variables

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Use this command to run the AxioDB Docker container, exposing the necessary ports and setting environment variables for configuration. Ensure the container name is unique.

```bash
docker run -d \
  --name axiodb-server \
  -p 27018:27018 \
  -p 27019:27019 \
  -e AXIODB_PORT=27018 \
  -e AXIODB_HOST=0.0.0.0 \
  theankansaha/axiodb
```

--------------------------------

### Configure AxioDB Data Persistence with Volumes

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Ensure data persistence by mounting a local directory as a volume to the container's data directory. This command maps the current directory's 'axiodb-data' folder to '/app' inside the container.

```bash
docker run -d \
  --name axiodb-server \
  -p 27018:27018 \
  -p 27019:27019 \
  -v "$(pwd)/axiodb-data":/app \
  theankansaha/axiodb
```

--------------------------------

### Troubleshoot Development Server Issues

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

If the development server encounters issues, try clearing the cache, reinstalling dependencies, and restarting the server. This process ensures a clean environment.

```bash
rm -rf node_modules .vite
npm install
npm run dev
```

--------------------------------

### Run AxioDB Docker with Data Persistence

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Runs the AxioDB Docker container and mounts a named volume 'axiodb-data' to the '/app' directory inside the container for data persistence.

```bash
# Mount a volume to persist data
docker run -d \
  --name axiodb-server \
  -p 27018:27018 \
  -p 27019:27019 \
  -v axiodb-data:/app \
  theankansaha/axiodb
```

--------------------------------

### Create AxioDB Databases

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Create databases to organize your collections. Databases can be created with default schema validation or disabled.

```javascript
// Create database with schema validation (default)
const mainDB = await db.createDB('MainDatabase');

// Create database without schema validation
const logsDB = await db.createDB('LogsDatabase', false);
```

--------------------------------

### Create a Database via AxioDB API

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Use this curl command to create a new database in AxioDB. Ensure the AxioDB server is running and accessible via localhost on port 27018.

```bash
curl -X POST http://localhost:27018/api/database/create \
  -H "Content-Type: application/json" \
  -d '{"name": "myDatabase"}'
```

--------------------------------

### Enable GUI in AxioDB Application

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Enable the GUI when creating an AxioDB instance. The GUI will be available at localhost:27018. You can also specify a custom database path.

```javascript
const { AxioDB } = require('axiodb');

// Enable GUI when creating AxioDB instance
const db = new AxioDB({ GUI: true });  // GUI available at localhost:27018

// With custom database path
const db = new AxioDB({ GUI: true, RootName: "MyDB", CustomPath: "./custom/path" });
```

--------------------------------

### Run AxioDB Docker with Custom Ports

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Runs the AxioDB Docker container, mapping custom host ports for HTTP and TCP services. Access the HTTP GUI via http://localhost:8080 and connect AxioDBCloud via axiodb://localhost:8081.

```bash
# Run on different host ports (e.g., 8080 for HTTP, 8081 for TCP)
docker run -d \
  --name axiodb-server \
  -p 8080:27018 \
  -p 8081:27019 \
  theankansaha/axiodb

# Access HTTP GUI via http://localhost:8080
# Connect AxioDBCloud via axiodb://localhost:8081
```

--------------------------------

### Run Specific Test File

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Command to run a specific test file using Node.js.

```bash
node ./Test/run.js
```

--------------------------------

### Enable Built-in Web GUI

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Enable the built-in web GUI by setting the 'GUI' option to true when creating an AxioDB instance. The GUI will be accessible at localhost:27018.

```javascript
// Enable GUI when creating instance
const db = new AxioDB({ GUI: true });  // GUI at localhost:27018
```

--------------------------------

### AxioDB Encryption Best Practice: Environment Variables

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Avoid hardcoding encryption keys. Use environment variables for security when creating collections with custom encryption keys.

```javascript
const collection = await db.createCollection(
  'data',
  true,
  schema,
  true,
  process.env.AXIODB_ENCRYPTION_KEY
);
```

--------------------------------

### Enable Encryption with Custom Key

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Create a collection with AES-256 encryption using a custom key. It is recommended to use environment variables for security.

```javascript
const encrypted = await database.createCollection(
  'sensitiveData',
  true,
  schema,
  true,
  process.env.ENCRYPTION_KEY  // Custom key
);
```

--------------------------------

### Run AxioDB Server with Docker

Source: https://github.com/nexoral/axiodb/blob/main/README.md

This command pulls the AxioDB Docker image and runs it in detached mode, exposing the GUI and remote access ports. It also mounts a volume for persistent data storage.

```bash
# Pull and run the AxioDB Docker container
docker run -d \
  --name axiodb-server \
  -p 27018:27018 \
  -p 27019:27019 \
  -v axiodb-data:/app \
  theankansaha/axiodb

# Ports:
# 27018 - HTTP GUI Dashboard
# 27019 - TCP Remote Access (AxioDBCloud)
# Volume: /app is the main data directory
```

--------------------------------

### Check Port Availability (Linux/macOS)

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Use this command to check if port 27018 is available on Linux or macOS systems. This is useful for troubleshooting GUI startup issues.

```bash
# Linux/macOS
lsof -i :27018
```

--------------------------------

### Create Feature Branch

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Commands to create a new branch for feature development.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Check Port Availability (Windows)

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Use this command to check if port 27018 is available on Windows systems. This is useful for troubleshooting GUI startup issues.

```bash
# Windows
netstat -ano | findstr :27018
```

--------------------------------

### Create a Collection via AxioDB API

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Use this curl command to create a new collection within a specified database. The request includes the database name, collection name, and schema definition.

```bash
curl -X POST http://localhost:27018/api/collection/create \
  -H "Content-Type: application/json" \
  -d '{
    "database": "myDatabase",
    "name": "users",
    "schema": {
      "name": {"type": "string", "required": true},
      "email": {"type": "string", "required": true}
    }
  }'
```

--------------------------------

### Implement Dual-Write Pattern for Indexes

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Ensure data is written to both memory cache and disk for speed and durability. This pattern involves writing to an index cache and a file manager simultaneously.

```typescript
// ALWAYS write to BOTH memory (speed) AND disk (durability)
await this.indexCache.set(indexKey, data, TTL);
await this.fileManager.writeFile(indexPath, JSON.stringify(data));

// Cold start: reload from disk
const diskData = await this.fileManager.readFile(indexPath);
this.indexCache.set(indexKey, JSON.parse(diskData), TTL);
```

--------------------------------

### Vite Configuration for GUI

Source: https://github.com/nexoral/axiodb/blob/main/GUI/README.md

Vite configuration for the GUI, specifying the React plugin, server port, and host. This file is located at vite.config.ts.

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    host: true
  }
})
```

--------------------------------

### Batch Operations with Promise.all

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Perform multiple asynchronous operations in parallel using `Promise.all` for significant performance gains. Avoid sequential loops for independent operations.

```typescript
// ✅ GOOD: Parallel with Promise.all
const results = await Promise.all(documents.map(d => this.insert(d)));
```

```typescript
// ❌ BAD: Sequential
for (const doc of documents) {
  await this.insert(doc);  // Slow!
}
```

--------------------------------

### AxioDB Docker Compose Configuration

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Define and run multi-container Docker applications using Docker Compose. This configuration sets up the AxioDB service, maps ports, and configures data persistence with volumes.

```yaml
version: "3.8"\
\
services: \
  axiodb: \
    image: theankansaha/axiodb \
    container_name: axiodb-server \
    ports: \
      - "27018:27018"  # HTTP API & GUI \
      - "27019:27019"  # TCP Remote Access \
    volumes: \
      - axiodb-data:/app \
    restart: unless-stopped \
\
volumes: \
  axiodb-data:
```

--------------------------------

### Lint Code

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Command to run ESLint for code formatting and linting checks.

```bash
npm run lint
```

--------------------------------

### Implement Singleton Pattern for AxioDB

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Enforce a single instance of the AxioDB class to manage the database. This pattern requires tests to run in separate child processes.

```typescript
export class AxioDB {
  private static _instance: AxioDB;

  constructor() {
    if (AxioDB._instance) {
      throw new Error("Only one instance of AxioDB is allowed.");
    }
    AxioDB._instance = this;
  }
}
```

--------------------------------

### Build Project After Code Changes

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Always run 'npm run build' immediately after any code modification to ensure TypeScript errors are caught before production. This is a mandatory step.

```bash
npm run build  # MANDATORY after EVERY code change
```

--------------------------------

### Create Fix Branch

Source: https://github.com/nexoral/axiodb/blob/main/CONTRIBUTING.md

Commands to create a new branch for bug fixes.

```bash
git checkout -b fix/bug-description
```

--------------------------------

### Connect to AxioDBCloud Client

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Establishes a connection to a remote AxioDB instance using the AxioDBCloud client. This allows using the same API as the embedded mode by specifying the remote server's address.

```javascript
const { AxioDBCloud } = require('axiodb');

// Connect to remote AxioDB (same API as embedded!)
const client = new AxioDBCloud("axiodb://localhost:27019");
await client.connect();

// Use exactly like embedded AxioDB
const db = await client.createDB("ProductionDB");
const users = await db.createCollection("Users");

// All operations work identically
await users.insert({ name: "Alice", role: "admin" });
const results = await users.query({ role: "admin" })
  .Limit(10)
  .Sort({ createdAt: -1 })
  .exec();

await client.disconnect();
```

--------------------------------

### Create AxioDB Collections

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Create collections within a database to store documents. Collections can be basic, encrypted with an auto-generated key, or encrypted with a custom key.

```javascript
// Create basic collection
const users = await mainDB.createCollection('users');

// Create encrypted collection with auto-generated key
const secureUsers = await mainDB.createCollection('secureUsers', true);

// Create encrypted collection with custom key
const vaultUsers = await mainDB.createCollection('vaultUsers', true, 'mySecretKey123');
```

--------------------------------

### AxioDB Singleton Pattern

Source: https://github.com/nexoral/axiodb/blob/main/GEMINI.md

Ensures only one instance of AxioDB can be created per application. Throws an error if a second instance is attempted.

```typescript
export class AxioDB {
  private static _instance: AxioDB;
  constructor() {
    if (AxioDB._instance) throw new Error("Only one instance allowed");
    AxioDB._instance = this;
  }
}
```

--------------------------------

### Dual-Write Pattern for Indexes

Source: https://github.com/nexoral/axiodb/blob/main/GEMINI.md

Writes data to both an in-memory cache for speed and to disk for durability. Includes a Time-To-Live (TTL) for cache entries.

```typescript
// Write to memory (speed) + disk (durability)
await this.indexCache.set(key, data, TTL);
await this.fileManager.writeFile(path, JSON.stringify(data));
```

--------------------------------

### AxioDB Methods

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Methods for managing databases within AxioDB.

```APIDOC
## AxioDB

### `createDB(dbName: string, schemaValidation: boolean = true): Promise<Database>`

Creates a new database with the specified name. Schema validation is enabled by default.

### `deleteDatabase(dbName: string): Promise<SuccessInterface | ErrorInterface>`

Deletes an existing database by its name.
```

--------------------------------

### Define User Schema and Create Collection

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Defines the schema for user data including username, email, and password hash. Creates an encrypted collection named 'users' using the provided encryption key.

```javascript
const userSchema = {
  username: SchemaTypes.string().required().min(3).max(20),
  email: SchemaTypes.string().required().email(),
  passwordHash: SchemaTypes.string().required(),
  createdAt: SchemaTypes.date(),
};

const users = await authDB.createCollection(
  'users',
  true,
  userSchema,
  true,  // Encrypted
  process.env.USER_ENCRYPTION_KEY
);
```

--------------------------------

### Database Methods

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Methods for managing collections within a database.

```APIDOC
## Database

### `createCollection(name: string, isEncrypted?: boolean, encryptionKey?: string): Promise<Collection>`

Creates a new collection within the database. Can be configured as encrypted with a custom key.

### `deleteCollection(name: string): Promise<SuccessInterface | ErrorInterface>`

Deletes a collection by its name.

### `getCollectionInfo(): Promise<SuccessInterface>`

Retrieves information about the collections within the database.
```

--------------------------------

### Transaction (Session) Methods

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Methods for managing and executing ACID transactions.

```APIDOC
## Transaction (Session)

### `startSession(options?: { timeout?: number }): Session`

Starts a new transaction session with optional timeout.

### `session.withTransaction(callback: Function): Promise<any>`

Executes a callback function within a transaction.

### `session.startTransaction(): Transaction`

Begins a new transaction.

### `transaction.insert(document: object): Transaction`

Inserts a document within the current transaction.

### `transaction.update(query: object, update: object): Transaction`

Updates documents matching the query within the current transaction.

### `transaction.delete(query: object): Transaction`

Deletes documents matching the query within the current transaction.

### `transaction.savepoint(name: string): Transaction`

Creates a savepoint within the transaction.

### `transaction.rollbackToSavepoint(name: string): Transaction`

Rolls back the transaction to a specified savepoint.

### `transaction.commit(): Promise<SuccessInterface>`

Commits the transaction.

### `transaction.rollback(): Promise<void>`

Rolls back the entire transaction.
```

--------------------------------

### Implement DRY Principle with Helper Classes

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Extract reusable logic into helper classes or modules to avoid repetition across different files. Import and use these helpers where needed.

```typescript
// If same logic appears in 2+ files → Extract to Helper/

// ✅ GOOD
// Helper/QueryMatcher.helper.ts
export class QueryMatcher {
  static matchDocument(doc: any, query: any): boolean { }
  static filterDocuments(docs: any[], query: any) {
    return docs.filter(d => this.matchDocument(d, query));
  }
}

// Import in Reader.operation.ts and Update.operation.ts
import { QueryMatcher } from '../Helper/QueryMatcher.helper';
const filtered = QueryMatcher.filterDocuments(documents, query);
```

--------------------------------

### Restrict AxioDB Data Directory Permissions

Source: https://github.com/nexoral/axiodb/blob/main/SECURITY.md

Secure your AxioDB data by restricting file system access to the data directory. Use chmod to set appropriate permissions.

```bash
# Linux/macOS
chmod 700 ./AxioDB
```

--------------------------------

### File-Per-Document Storage Structure

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Organize data using a file-per-document storage pattern, where each document is stored in its own file within a collection directory. Index files are stored in a sub-directory.

```plaintext
{RootPath}/
└── {DatabaseName}/
    └── {CollectionName}/
        ├── {documentId}.axiodb
        ├── {documentId2}.axiodb
        └── indexes/
            └── {indexName}.json
```

--------------------------------

### AxioDB Resource Cleanup: Delete Database

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Clean up unused resources by deleting temporary databases. This is essential for maintaining a clean and efficient database environment.

```javascript
// Delete unused databases
await db.deleteDatabase('tempDB');
```

--------------------------------

### AxioDB Error Handling

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Implement try-catch blocks to handle potential errors during database operations like insertion. Log errors to the console for debugging.

```javascript
try {
  await collection.insert({ name: 'User' });
} catch (error) {
  console.error('Insert failed:', error);
}
```

--------------------------------

### Insert a Document via AxioDB API

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Use this curl command to insert a document into a specified collection. The document must conform to the collection's schema.

```bash
curl -X POST http://localhost:27018/api/operation/insert \
  -H "Content-Type: application/json" \
  -d '{
    "database": "myDatabase",
    "collection": "users",
    "data": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'
```

--------------------------------

### Run AxioDB Docker Container

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Pulls and runs the AxioDB Docker container in detached mode. Maps default ports for REST API and TCP access.

```bash
docker run -d \
  --name axiodb-server \
  -p 27018:27018 \
  -p 27019:27019 \
  theankansaha/axiodb
```

--------------------------------

### Avoid Hardcoding Encryption Keys

Source: https://github.com/nexoral/axiodb/blob/main/SECURITY.md

Never hardcode encryption keys directly in your code. Use environment variables to securely manage sensitive information like encryption keys.

```javascript
const collection = await db.createCollection('data', true, schema, true, 'myKey123');
```

```javascript
const collection = await db.createCollection(
  'data',
  true,
  schema,
  true,
  process.env.AXIODB_ENCRYPTION_KEY
);
```

--------------------------------

### Reader Methods

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Methods for refining and executing queries.

```APIDOC
## Reader

### `Limit(limit: number): Reader`

Limits the number of documents returned by the query.

### `Skip(skip: number): Reader`

Skips a specified number of documents in the query results.

### `Sort(sort: object): Reader`

Sorts the query results based on the provided object.

### `setCount(count: boolean): Reader`

Specifies whether to return the count of matching documents.

### `setProject(project: object): Reader`

Specifies which fields to include or exclude in the query results.

### `exec(): Promise<SuccessInterface | ErrorInterface>`

Executes the query and returns the results.

### `findOne(): Promise<SuccessInterface | ErrorInterface>`

Executes the query and returns a single document.
```

--------------------------------

### Create Encrypted Collection

Source: https://github.com/nexoral/axiodb/blob/main/SECURITY.md

Enable AES-256 encryption for sensitive collections by passing true as the fourth argument and providing an encryption key. It is recommended to use environment variables for keys.

```javascript
const sensitiveCollection = await db.createCollection(
  'users',
  true,
  schema,
  true,
  process.env.ENCRYPTION_KEY
);
```

--------------------------------

### AxioDB Fast Lookups with documentId

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Utilize documentId for O(1) lookups when using the InMemoryCache. This allows for extremely fast retrieval of specific documents.

```javascript
// O(1) lookup with InMemoryCache
const user = await collection.query({ documentId: 'ABC123' }).exec();
```

--------------------------------

### AxioDB Bulk Insert Many

Source: https://github.com/nexoral/axiodb/blob/main/LEARN.md

Efficiently insert multiple documents into a collection using the insertMany operation. Provide an array of document objects.

```javascript
// Insert many
await collection.insertMany([
  { name: 'User 1', age: 25 },
  { name: 'User 2', age: 30 },
  { name: 'User 3', age: 35 },
]);
```

--------------------------------

### Query Documents via AxioDB API

Source: https://github.com/nexoral/axiodb/blob/main/Docker/README.md

Use this curl command to query documents from a collection based on specified criteria. You can also set a limit for the number of returned documents.

```bash
curl -X POST http://localhost:27018/api/operation/query \
  -H "Content-Type: application/json" \
  -d '{
    "database": "myDatabase",
    "collection": "users",
    "query": {"name": "John Doe"},
    "limit": 10
  }'
```

--------------------------------

### O(1) Lookups with Map

Source: https://github.com/nexoral/axiodb/blob/main/AGENTS.md

Use `Map` data structures for efficient key-value lookups, providing O(1) time complexity. Avoid array `find` methods which have O(n) complexity for large datasets.

```typescript
// ✅ GOOD: O(1)
const map = new Map<string, Document>();
const found = map.get(id);
```

```typescript
// ❌ BAD: O(n)
const found = documents.find(d => d.id === id);
```

--------------------------------

### Collection Methods

Source: https://github.com/nexoral/axiodb/blob/main/README.md

Methods for performing CRUD operations and querying data within a collection.

```APIDOC
## Collection

### `insert(document: object): Promise<SuccessInterface | ErrorInterface>`

Inserts a single document into the collection.

### `insertMany(documents: object[]): Promise<SuccessInterface | ErrorInterface>`

Inserts multiple documents into the collection.

### `query(query: object): Reader`

Initiates a query operation on the collection. Returns a Reader object for further refinement.

### `update(query: object): Updater`

Initiates an update operation on documents matching the query. Returns an Updater object.

### `delete(query: object): Deleter`

Initiates a delete operation on documents matching the query. Returns a Deleter object.

### `aggregate(pipeline: object[]): Aggregation`

Performs an aggregation operation on the collection using a pipeline.

### `startSession(options?: SessionOptions): Session`

Starts a new transaction session.

### `createIndex(fieldName: string): Promise<SuccessInterface>`

Creates an index on a specified field within the collection.

### `dropIndex(indexName: string): Promise<SuccessInterface | ErrorInterface>`

Drops an index from the collection by its name.
```

--------------------------------

### Update AxioDB Package

Source: https://github.com/nexoral/axiodb/blob/main/SECURITY.md

Regularly update the AxioDB package to the latest version to incorporate security fixes and improvements.

```bash
npm update axiodb
```