xdb-driver 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2026 Firr, The Creator.
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,663 @@
+# Node.js XDB Driver
+
+> A high-performance TypeScript driver for the XDB NoSQL database engine
+
+[![npm version](https://img.shields.io/npm/v/node-xdb-driver.svg)](https://www.npmjs.com/package/node-xdb-driver)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+## 📋 Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Usage Examples](#usage-examples)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Testing](#testing)
+- [XDB Server Setup](#xdb-server-setup)
+- [Architecture](#architecture)
+- [Contributing](#contributing)
+- [License](#license)
+
+## 🎯 Overview
+
+Node.js XDB Driver is a modern TypeScript client library for interacting with the XDB database engine—a lightweight, high-performance NoSQL database written in C. It provides a Promise-based API for seamless integration with Node.js applications while maintaining type safety through TypeScript.
+
+The driver handles TCP communication with the XDB server, manages connection state, buffers streaming data, and provides comprehensive error reporting with helpful diagnostics.
+
+## ✨ Features
+
+- **Type-Safe API**: Full TypeScript support with generics for compile-time type checking
+- **Promise-Based**: Modern async/await syntax for all operations
+- **Connection Management**: Automatic connection pooling and error recovery
+- **Stream Buffering**: Handles TCP packet fragmentation transparently
+- **Error Diagnostics**: Helpful error messages when the server is unavailable
+- **Zero Dependencies**: Lightweight implementation using only Node.js built-ins
+- **Production Ready**: Thoroughly tested and used in production environments
+
+## 📦 Prerequisites
+
+Before using Node.js XDB Driver, ensure you have:
+
+| Requirement | Version | Purpose                                                      |
+| ----------- | ------- | ------------------------------------------------------------ |
+| Node.js     | 14.0+   | JavaScript runtime                                           |
+| npm or pnpm | Latest  | Package manager                                              |
+| XDB Server  | 1.0+    | Database backend (see [XDB Server Setup](#xdb-server-setup)) |
+
+## 🚀 Installation
+
+### Via npm
+
+```bash
+npm install xdb-driver
+```
+
+### Via pnpm
+
+```bash
+pnpm add xdb-driver
+```
+
+### Via yarn
+
+```bash
+yarn add xdb-driver
+```
+
+## ⚡ Quick Start
+
+### Basic Connection
+
+```typescript
+import { XDBClient } from 'xdb-driver';
+
+const db = new XDBClient({ host: '127.0.0.1', port: 8080 });
+
+try {
+    await db.connect();
+    console.log('Connected to XDB');
+} catch (error) {
+    console.error('Connection failed:', error);
+}
+```
+
+### CRUD Operations
+
+```typescript
+import { XDBClient } from 'xdb-driver';
+
+interface User {
+    username: string;
+    email: string;
+    active: boolean;
+}
+
+const db = new XDBClient();
+await db.connect();
+
+// Insert a document
+const createResult = await db.insert<User>('users', {
+    username: 'alice',
+    email: 'alice@example.com',
+    active: true,
+});
+
+console.log(`Document created with ID: ${createResult.data?._id}`);
+
+// Find documents
+const users = await db.find<User>('users', { active: true });
+console.log(`Found ${users.data?.length} active users`);
+
+// Count documents
+const count = await db.count('users');
+console.log(`Total users: ${count.data?.count}`);
+
+// Delete a document
+await db.delete('users', createResult.data?._id);
+
+// Close connection
+await db.close();
+```
+
+## 📚 API Reference
+
+### Constructor
+
+```typescript
+new XDBClient(options?: XDBConnectionOptions)
+```
+
+**Parameters:**
+
+- `options.host` (string, default: `'127.0.0.1'`) - XDB server hostname
+- `options.port` (number, default: `8080`) - XDB server port
+
+### Methods
+
+#### `connect(): Promise<void>`
+
+Establishes a connection to the XDB server.
+
+```typescript
+await db.connect();
+```
+
+**Throws:** Error if connection fails
+
+---
+
+#### `insert<T>(collection: string, data: T): Promise<XDBResponse<InsertResult>>`
+
+Inserts a new document into a collection.
+
+**Parameters:**
+
+- `collection` (string) - Collection name
+- `data` (T) - Document data to insert
+
+**Returns:** Promise with inserted document including auto-generated `_id`
+
+**Example:**
+
+```typescript
+const result = await db.insert('users', { name: 'Alice', email: 'alice@example.com' });
+console.log(result.data?._id); // Auto-generated ID
+```
+
+---
+
+#### `find<T>(collection: string, query?: Record<string, any>, limit?: number): Promise<XDBResponse<T[]>>`
+
+Queries documents in a collection with optional filtering.
+
+**Parameters:**
+
+- `collection` (string) - Collection name
+- `query` (object, optional) - Filter criteria (exact match semantics)
+- `limit` (number, optional) - Maximum number of results to return
+
+**Returns:** Promise with array of matching documents
+
+**Example:**
+
+```typescript
+const admins = await db.find('users', { role: 'admin' }, 10);
+console.log(`Found ${admins.data?.length} admins`);
+```
+
+---
+
+#### `count(collection: string, query?: Record<string, any>): Promise<XDBResponse<CountResult>>`
+
+Returns the count of documents matching a query.
+
+**Parameters:**
+
+- `collection` (string) - Collection name
+- `query` (object, optional) - Filter criteria
+
+**Returns:** Promise with count
+
+**Example:**
+
+```typescript
+const result = await db.count('users', { active: true });
+console.log(`Active users: ${result.data?.count}`);
+```
+
+---
+
+#### `delete(collection: string, id: string): Promise<XDBResponse<void>>`
+
+Deletes a document by ID.
+
+**Parameters:**
+
+- `collection` (string) - Collection name
+- `id` (string) - Document ID to delete
+
+**Returns:** Promise that resolves when deletion is complete
+
+**Example:**
+
+```typescript
+await db.delete('users', 'a1b2c3d4e5f6g7h8');
+```
+
+---
+
+#### `close(): Promise<void>`
+
+Gracefully closes the connection to the server.
+
+```typescript
+await db.close();
+```
+
+### Types
+
+#### `XDBConnectionOptions`
+
+```typescript
+interface XDBConnectionOptions {
+    host?: string; // Default: '127.0.0.1'
+    port?: number; // Default: 8080
+}
+```
+
+#### `XDBResponse<T>`
+
+```typescript
+interface XDBResponse<T = any> {
+    status: 'ok' | 'error';
+    message: string;
+    data?: T;
+}
+```
+
+#### `XDBAction`
+
+```typescript
+type XDBAction = 'insert' | 'find' | 'delete' | 'count' | 'exit';
+```
+
+## 💡 Usage Examples
+
+### Type-Safe Operations
+
+```typescript
+import { XDBClient } from 'xdb-driver';
+
+interface Product {
+    name: string;
+    price: number;
+    inStock: boolean;
+}
+
+const db = new XDBClient({ host: 'localhost', port: 8080 });
+
+async function productDemo() {
+    await db.connect();
+
+    // Insert with type safety
+    const product = await db.insert<Product>('products', {
+        name: 'Laptop',
+        price: 999.99,
+        inStock: true,
+    });
+
+    // Find with type inference
+    const results = await db.find<Product>('products', { inStock: true });
+    results.data?.forEach((item) => {
+        console.log(`${item.name}: $${item.price}`);
+    });
+
+    await db.close();
+}
+
+productDemo().catch(console.error);
+```
+
+### Error Handling
+
+```typescript
+const db = new XDBClient({ host: '127.0.0.1', port: 8080 });
+
+try {
+    await db.connect();
+} catch (error: any) {
+    if (error.code === 'ECONNREFUSED') {
+        console.error('XDB server is not running. Please start it first.');
+    } else {
+        console.error('Connection error:', error.message);
+    }
+}
+```
+
+### Batch Operations
+
+```typescript
+const db = new XDBClient();
+await db.connect();
+
+// Insert multiple documents
+const ids = [];
+for (const user of userData) {
+    const result = await db.insert('users', user);
+    if (result.data?._id) {
+        ids.push(result.data._id);
+    }
+}
+
+// Query all inserted documents
+const insertedUsers = await db.find('users', {});
+console.log(`Inserted ${insertedUsers.data?.length} users`);
+
+await db.close();
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+While not required, you can configure the XDB server address via environment variables:
+
+```bash
+export XDB_HOST=127.0.0.1
+export XDB_PORT=8080
+```
+
+### Programmatic Configuration
+
+```typescript
+const db = new XDBClient({
+    host: process.env.XDB_HOST || 'localhost',
+    port: parseInt(process.env.XDB_PORT || '8080'),
+});
+```
+
+## 🚨 Error Handling
+
+The driver provides detailed error messages for common issues:
+
+### Connection Errors
+
+```typescript
+try {
+    await db.connect();
+} catch (error) {
+    console.error(error);
+    // Output if server is down:
+    // [ERROR] Could not connect to XDB at 127.0.0.1:8080
+    // [HINT] Is the XDB server running?
+}
+```
+
+### Response Errors
+
+```typescript
+const result = await db.find('users', {});
+
+if (result.status === 'error') {
+    console.error(`Operation failed: ${result.message}`);
+}
+```
+
+### Query Semantics
+
+- **Exact Matching**: Queries require exact field matches (no regex or partial matching)
+- **Null Handling**: Missing fields in documents do not match query filters
+- **Pagination**: Use `limit` parameter to control result set size
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+Generate coverage report:
+
+```bash
+npm run test:coverage
+```
+
+### Writing Tests
+
+```typescript
+import { XDBClient } from '../src';
+
+describe('XDBClient', () => {
+    let db: XDBClient;
+
+    beforeAll(async () => {
+        db = new XDBClient();
+        await db.connect();
+    });
+
+    afterAll(async () => {
+        await db.close();
+    });
+
+    it('should insert a document', async () => {
+        const result = await db.insert('test', { value: 42 });
+        expect(result.status).toBe('ok');
+        expect(result.data?._id).toBeDefined();
+    });
+
+    it('should find documents', async () => {
+        const result = await db.find('test', { value: 42 });
+        expect(result.data).toBeInstanceOf(Array);
+    });
+});
+```
+
+## 🗄️ XDB Server Setup
+
+The Node.js XDB Driver requires a running XDB server. Follow these steps to set up the backend:
+
+### Prerequisites
+
+| Requirement   | Version | Description                        |
+| ------------- | ------- | ---------------------------------- |
+| GCC           | 7.0+    | C compiler with C99 support        |
+| GNU Make      | 3.81+   | Build automation tool              |
+| POSIX Threads | -       | For concurrent connection handling |
+
+### Supported Platforms
+
+- Linux (Ubuntu 20.04+, Debian, Fedora, etc.)
+- macOS (with Homebrew-installed GCC)
+- Other POSIX-compliant systems
+
+### Installation Steps
+
+#### 1. Clone the XDB Repository
+
+```bash
+git clone https://github.com/firrthecreator/XDB.git
+cd XDB
+```
+
+#### 2. Verify Dependencies
+
+Ensure the following files exist:
+
+- `third_party/cJSON/cJSON.h`
+- `third_party/cJSON/cJSON.c`
+
+The cJSON library is included in the repository.
+
+#### 3. Compile the Project
+
+```bash
+make
+```
+
+This command will:
+
+- Create the `bin/` and `data/` directories
+- Compile all source files with optimizations
+- Link the executable to `bin/xdb`
+
+#### 4. Clean Build Artifacts (Optional)
+
+To remove compiled files and start fresh:
+
+```bash
+make clean
+```
+
+#### 5. Start the Server
+
+```bash
+./bin/xdb
+```
+
+The database server will start listening on `localhost:8080`.
+
+**Expected Output:**
+
+```
+[08:17:43] [INFO] Initialized new database instance.
+[08:17:43] [INFO] Server listening on 0.0.0.0:8080
+```
+
+#### 6. Run Unit Tests (Optional)
+
+Verify the server is built correctly:
+
+```bash
+make test
+```
+
+**Expected Output:**
+
+```
+XDB Unit Test Suite
+[TEST] test_query_exact_match             PASS
+[TEST] test_crud_workflow                 PASS
+Summary: 2 Run, 0 Failed
+```
+
+### Server Configuration
+
+By default, XDB listens on:
+
+- **Host:** `0.0.0.0` (all interfaces)
+- **Port:** `8080`
+
+To modify these settings, edit `src/server.c` and recompile:
+
+```bash
+make clean
+make
+```
+
+### XDB API
+
+The XDB server accepts JSON commands over TCP. For complete API documentation, see the [API Documentation](https://github.com/firrthecreator/XDB#api-documentation) in the XDB repository.
+
+**Quick Reference:**
+
+```bash
+# Connect to server
+telnet localhost 8080
+
+# Insert a document
+{"action": "insert", "collection": "users", "data": {"name": "Alice"}}
+
+# Find documents
+{"action": "find", "collection": "users", "query": {"name": "Alice"}}
+
+# Delete a document
+{"action": "delete", "collection": "users", "id": "uuid-here"}
+
+# Count documents
+{"action": "count", "collection": "users"}
+
+# Close connection
+{"action": "exit"}
+```
+
+## 🏗️ Architecture
+
+### Design Principles
+
+The Node.js XDB Driver follows these architectural principles:
+
+1. **Modularity**: Clean separation between connection, request handling, and response parsing
+2. **Promise-Based**: Modern async/await support for intuitive control flow
+3. **Type Safety**: Full TypeScript support with generic types for compile-time validation
+4. **Error Resilience**: Graceful handling of network errors with helpful diagnostics
+
+### Project Structure
+
+```
+src/
+├── index.ts              # Public API exports
+├── xdb-client.ts         # Main client implementation
+└── types/
+    └── definitions.ts    # TypeScript type definitions
+
+examples/
+└── app.ts               # Usage example
+
+tests/
+└── xdb-client.spec.ts   # Test suite
+```
+
+### Component Overview
+
+- **XDBClient**: Main entry point, handles connection lifecycle and API operations
+- **Type Definitions**: Strict contracts for requests, responses, and configuration
+- **Stream Handler**: Manages TCP packet buffering and JSON deserialization
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+### Code Style
+
+- Use TypeScript for all code
+- Follow the existing code conventions
+- Use 4-space indentation
+- Use meaningful variable and function names
+
+### Testing
+
+- Add tests for new features
+- Ensure all tests pass before submitting PR
+
+```bash
+npm test
+```
+
+### Commits
+
+Use descriptive commit messages:
+
+```
+feat: Add support for batch operations
+fix: Handle connection timeouts gracefully
+docs: Update API documentation
+test: Add integration tests
+```
+
+### Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: Amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## 🔗 Resources
+
+- **GitHub Repository**: [github.com/firrthecreator/node-xdb-driver](https://github.com/firrthecreator/node-xdb-driver)
+- **XDB Server**: [github.com/firrthecreator/XDB](https://github.com/firrthecreator/XDB)
+- **npm Package**: [npmjs.com/package/node-xdb-driver](https://www.npmjs.com/package/node-xdb-driver)
+
+## 👨‍💻 Author
+
+**Firr, The Creator** - [GitHub](https://github.com/firrthecreator)
+
+---
+
+**Node.js XDB Driver** © 2026. Built with ❤️ by Firr, The Creator.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file index.ts
+ * @brief Public API exports for the Node.js XDB Driver.
+ */
+export { XDBClient } from './xdb-client';
+export * from './types/definitions';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * @file index.ts
+ * @brief Public API exports for the Node.js XDB Driver.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XDBClient = void 0;
+var xdb_client_1 = require("./xdb-client");
+Object.defineProperty(exports, "XDBClient", { enumerable: true, get: function () { return xdb_client_1.XDBClient; } });
+__exportStar(require("./types/definitions"), exports);

package/dist/types/definitions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file definitions.ts
+ * @brief Core type definitions and interfaces for the Node.js XDB Driver.
+ * Defines the contract for requests, responses, and internal queue handling.
+ */
+/**
+ * @brief Supported actions by the XDB Server.
+ */
+export type XDBAction = 'insert' | 'find' | 'delete' | 'count' | 'exit';
+/**
+ * @brief Configuration options for the client connection.
+ */
+export interface XDBConnectionOptions {
+    host?: string;
+    port?: number;
+}
+/**
+ * @brief Standard request structure sent to the C server.
+ */
+export interface XDBRequest {
+    action: XDBAction;
+    collection?: string;
+    data?: Record<string, any>;
+    query?: Record<string, any>;
+    limit?: number;
+    id?: string;
+}
+/**
+ * @brief Standard response structure received from the C server.
+ * @template T The type of data expected in the response.
+ */
+export interface XDBResponse<T = any> {
+    status: 'ok' | 'error';
+    message: string;
+    data?: T;
+}
+/**
+ * @brief Internal interface for managing the Promise queue.
+ * Used to map asynchronous server responses back to the correct caller.
+ */
+export interface ResponseResolver {
+    resolve: (value: XDBResponse | PromiseLike<XDBResponse>) => void;
+    reject: (reason?: any) => void;
+}

package/dist/types/definitions.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * @file definitions.ts
+ * @brief Core type definitions and interfaces for the Node.js XDB Driver.
+ * Defines the contract for requests, responses, and internal queue handling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/xdb-client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file xdb-client.ts
+ * @brief Main Implementation of the XDB Database Client.
+ * Handles TCP persistence, stream buffering, command dispatching,
+ * and user-friendly error reporting.
+ */
+import { XDBResponse, XDBConnectionOptions } from './types/definitions';
+/**
+ * @class XDBClient
+ * @brief A persistent TCP client for interacting with the XDB Server.
+ * Encapsulates the raw socket operations and provides a Promise-based API.
+ */
+export declare class XDBClient {
+    private socket;
+    private isConnected;
+    private responseQueue;
+    private streamBuffer;
+    private readonly host;
+    private readonly port;
+    /**
+     * @brief Initializes the XDB Client instance.
+     * @param options Configuration object containing host and port.
+     */
+    constructor(options?: XDBConnectionOptions);
+    /**
+     * @brief Establishes a connection to the XDB Server.
+     * * Sets up event listeners for data streaming and error handling.
+     * * Checks for 'ECONNREFUSED' to provide a helpful hint if the server is down.
+     * * @returns Promise<void> Resolves when connection is successful.
+     */
+    connect(): Promise<void>;
+    /**
+     * @brief Processes raw TCP stream data.
+     * * Splits the stream by newline characters to reconstruct distinct JSON objects.
+     * * Handles packet fragmentation (partial JSONs) by buffering incomplete data.
+     * @param chunk Raw string data from the socket.
+     */
+    private handleStreamData;
+    /**
+     * @brief Internal helper to send commands to the server.
+     * * Wraps the request in a Promise and pushes the resolver to the queue.
+     * @param payload The request object.
+     * @returns Promise<XDBResponse<T>> The server's response.
+     */
+    private sendCommand;
+    /**
+     * @brief Inserts a document into a specific collection.
+     * @param collection Target collection name.
+     * @param data JSON object to insert.
+     */
+    insert<T extends Record<string, any> = Record<string, any>>(collection: string, data: T): Promise<XDBResponse<T & {
+        _id: string;
+    }>>;
+    /**
+     * @brief Finds documents matching a query filter.
+     * @param collection Target collection name.
+     * @param query Filter criteria (default: match all).
+     * @param limit Max number of results (0 for unlimited).
+     */
+    find<T extends Record<string, any> = Record<string, any>>(collection: string, query?: object, limit?: number): Promise<XDBResponse<T[]>>;
+    /**
+     * @brief Deletes a document by its ID.
+     * @param collection Target collection name.
+     * @param id The unique _id string of the document.
+     */
+    delete(collection: string, id: string): Promise<XDBResponse<null>>;
+    /**
+     * @brief Counts the total number of documents in a collection.
+     * @param collection Target collection name.
+     */
+    count(collection: string): Promise<XDBResponse<{
+        count: number;
+    }>>;
+    /**
+     * @brief Terminates the session and closes the socket.
+     */
+    close(): Promise<void>;
+}

package/dist/xdb-client.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * @file xdb-client.ts
+ * @brief Main Implementation of the XDB Database Client.
+ * Handles TCP persistence, stream buffering, command dispatching,
+ * and user-friendly error reporting.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XDBClient = void 0;
+const net = __importStar(require("net"));
+/**
+ * @class XDBClient
+ * @brief A persistent TCP client for interacting with the XDB Server.
+ * Encapsulates the raw socket operations and provides a Promise-based API.
+ */
+class XDBClient {
+    /**
+     * @brief Initializes the XDB Client instance.
+     * @param options Configuration object containing host and port.
+     */
+    constructor(options = {}) {
+        this.isConnected = false;
+        this.responseQueue = [];
+        this.streamBuffer = '';
+        this.host = options.host || '127.0.0.1';
+        this.port = options.port || 8080;
+        this.socket = new net.Socket();
+    }
+    /**
+     * @brief Establishes a connection to the XDB Server.
+     * * Sets up event listeners for data streaming and error handling.
+     * * Checks for 'ECONNREFUSED' to provide a helpful hint if the server is down.
+     * * @returns Promise<void> Resolves when connection is successful.
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            this.socket.connect(this.port, this.host, () => {
+                this.isConnected = true;
+                console.log(`[INFO] Connected to XDB at ${this.host}:${this.port}`);
+                resolve();
+            });
+            // Handle incoming data stream
+            this.socket.on('data', (chunk) => {
+                this.handleStreamData(chunk.toString());
+            });
+            // Handle socket errors
+            this.socket.on('error', (err) => {
+                this.isConnected = false;
+                // Check if the connection was refused (Server not running)
+                if (err.code === 'ECONNREFUSED') {
+                    console.error(`\n\x1b[31m[ERROR] Could not connect to XDB at ${this.host}:${this.port}\x1b[0m`);
+                    console.error(`\x1b[33m[HINT] Is the XDB server running?\x1b[0m`);
+                    console.error(`       Please start the server first (e.g., \x1b[36m./bin/server\x1b[0m)\n`);
+                }
+                // If it's a connection error during init, reject the promise
+                if (this.responseQueue.length === 0) {
+                    reject(err);
+                }
+                else {
+                    // Otherwise, reject the current pending command
+                    const resolver = this.responseQueue.shift();
+                    if (resolver)
+                        resolver.reject(err);
+                }
+            });
+            this.socket.on('close', () => {
+                this.isConnected = false;
+                // We only log if this was a clean exit, not an error-induced close
+                if (this.responseQueue.length === 0) {
+                    // Optional: console.log('[INFO] Connection closed.');
+                }
+            });
+        });
+    }
+    /**
+     * @brief Processes raw TCP stream data.
+     * * Splits the stream by newline characters to reconstruct distinct JSON objects.
+     * * Handles packet fragmentation (partial JSONs) by buffering incomplete data.
+     * @param chunk Raw string data from the socket.
+     */
+    handleStreamData(chunk) {
+        this.streamBuffer += chunk;
+        // Split by newline (the protocol delimiter)
+        const lines = this.streamBuffer.split('\n');
+        // The last element is either an empty string (if exact split)
+        // or an incomplete JSON fragment. Keep it in the buffer.
+        this.streamBuffer = lines.pop() || '';
+        for (const line of lines) {
+            if (line.trim() === '')
+                continue;
+            const resolver = this.responseQueue.shift();
+            if (resolver) {
+                try {
+                    const json = JSON.parse(line);
+                    resolver.resolve(json);
+                }
+                catch (error) {
+                    resolver.reject(new Error(`Critical: Malformed JSON received. Raw: ${line}`));
+                }
+            }
+        }
+    }
+    /**
+     * @brief Internal helper to send commands to the server.
+     * * Wraps the request in a Promise and pushes the resolver to the queue.
+     * @param payload The request object.
+     * @returns Promise<XDBResponse<T>> The server's response.
+     */
+    sendCommand(payload) {
+        return new Promise((resolve, reject) => {
+            if (!this.isConnected) {
+                return reject(new Error('Client is not connected to XDB Server.'));
+            }
+            this.responseQueue.push({ resolve, reject });
+            // Append newline as required by the server's protocol
+            const message = JSON.stringify(payload) + '\n';
+            this.socket.write(message);
+        });
+    }
+    // Public API Methods
+    /**
+     * @brief Inserts a document into a specific collection.
+     * @param collection Target collection name.
+     * @param data JSON object to insert.
+     */
+    async insert(collection, data) {
+        return this.sendCommand({ action: 'insert', collection, data });
+    }
+    /**
+     * @brief Finds documents matching a query filter.
+     * @param collection Target collection name.
+     * @param query Filter criteria (default: match all).
+     * @param limit Max number of results (0 for unlimited).
+     */
+    async find(collection, query = {}, limit = 0) {
+        return this.sendCommand({ action: 'find', collection, query, limit });
+    }
+    /**
+     * @brief Deletes a document by its ID.
+     * @param collection Target collection name.
+     * @param id The unique _id string of the document.
+     */
+    async delete(collection, id) {
+        return this.sendCommand({ action: 'delete', collection, id });
+    }
+    /**
+     * @brief Counts the total number of documents in a collection.
+     * @param collection Target collection name.
+     */
+    async count(collection) {
+        return this.sendCommand({ action: 'count', collection });
+    }
+    /**
+     * @brief Terminates the session and closes the socket.
+     */
+    async close() {
+        if (this.isConnected) {
+            await this.sendCommand({ action: 'exit' });
+            this.socket.end();
+        }
+    }
+}
+exports.XDBClient = XDBClient;

package/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "xdb-driver",
+    "version": "1.0.0",
+    "description": "A High-performance Node.js driver for the XDB Database Engine",
+    "author": "Firr, The Creator.",
+    "license": "MIT",
+    "keywords": [
+        "database",
+        "tcp",
+        "driver",
+        "xdb",
+        "node.js",
+        "nosql"
+    ],
+    "packageManager": "pnpm@10.27.0",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "homepage": "https://github.com/firrthecreator/node-xdb-driver#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/firrthecreator/node-xdb-driver.git"
+    },
+    "bugs": {
+        "url": "https://github.com/firrthecreator/node-xdb-driver/issues"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "dev": "ts-node examples/app.ts",
+        "build": "tsc",
+        "format": "prettier --write \"src/**/*.ts\" \"examples/**/*.ts\" \"tests/**/*.ts\"",
+        "format:check": "prettier --check \"src/**/*.ts\" \"examples/**/*.ts\" \"tests/**/*.ts\"",
+        "clean": "rm -rf dist coverage",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage",
+        "prepublishOnly": "pnpm run clean && pnpm run format:check && pnpm run test && pnpm run build"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.0",
+        "@types/node": "^22.0.0",
+        "jest": "^29.7.0",
+        "prettier": "^3.5.0",
+        "ts-jest": "^29.2.0",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.7.0"
+    }
+}