{"_id":"@aevumdb/node-driver","name":"@aevumdb/node-driver","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aevumdb/node-driver","version":"1.0.0","description":"Official high-performance Node.js driver for AevumDB NoSQL database. 100% API coverage, TypeScript-native, and optimized for high-concurrency environments.","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./errors":{"types":"./dist/errors/aevum-error.d.ts","import":"./dist/errors/aevum-error.mjs","require":"./dist/errors/aevum-error.js"},"./types":{"types":"./dist/types/index.d.ts","import":"./dist/types/index.mjs","require":"./dist/types/index.js"}},"keywords":["aevumdb","nosql","database","driver","nodejs","typescript","performance","connection-pooling","async-await","rbac","schema-validation"],"author":{"name":"AevumDB Team"},"license":"SEE LICENSE IN LICENSE","repository":{"type":"git","url":"git+https://github.com/aevumdb/aevum-node.git"},"bugs":{"url":"https://github.com/aevumdb/aevum-node/issues"},"homepage":"https://github.com/aevumdb/aevum-node#readme","devDependencies":{"@eslint/js":"^9.0.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","eslint":"^9.14.0","globals":"^15.9.0","jest":"^29.5.0","prettier":"^3.2.0","ts-jest":"^29.1.0","ts-node":"^10.9.0","tsup":"^8.0.0","typescript":"^5.3.0","typescript-eslint":"^8.5.0"},"engines":{"node":">=16.0.0"},"scripts":{"build":"tsup src/index.ts src/errors/aevum-error.ts src/types/index.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts --format cjs,esm --dts --watch","lint":"eslint . --fix","lint:check":"eslint .","format":"prettier --write 'src/**/*.ts' 'examples/**/*.ts' 'tests/**/*.ts'","format:check":"prettier --check 'src/**/*.ts' 'examples/**/*.ts' 'tests/**/*.ts'","test":"jest --coverage","test:watch":"jest --watch","typecheck":"tsc --noEmit"},"_id":"@aevumdb/node-driver@1.0.0","_integrity":"sha512-Go/7GyOZRAGc+EPs2e6tsSgWO8fMRw4mDga1WXRseUwsgKcQZ2VUPH1TW66T0gNmoxRHbLtD0JVN3d5wSEdDEg==","_resolved":"/tmp/43217dfa59cbc13c148224ce74051ba2/aevumdb-node-driver-1.0.0.tgz","_from":"file:aevumdb-node-driver-1.0.0.tgz","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Go/7GyOZRAGc+EPs2e6tsSgWO8fMRw4mDga1WXRseUwsgKcQZ2VUPH1TW66T0gNmoxRHbLtD0JVN3d5wSEdDEg==","shasum":"4aa8b915b4618b6b39f7fc832e69abbe4305d8e0","tarball":"https://registry.npmjs.org/@aevumdb/node-driver/-/node-driver-1.0.0.tgz","fileCount":18,"unpackedSize":88491,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDUwQTKGZgsUI2+LJuVCeqZcVN8FFDEcp5j8QXCGOWXgwIgTX1vcHwmgnG+EvtMFAvGaNiK1S3Z0KTMHoI4GPrEr9I="}]},"_npmUser":{"name":"f0xptr","email":"f0xptr.ext@gmail.com"},"directories":{},"maintainers":[{"name":"f0xptr","email":"f0xptr.ext@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/node-driver_1.0.0_1773224482109_0.04982302390685378"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T10:21:22.031Z","1.0.0":"2026-03-11T10:21:22.239Z","modified":"2026-03-11T10:21:22.473Z"},"maintainers":[{"name":"f0xptr","email":"f0xptr.ext@gmail.com"}],"description":"Official high-performance Node.js driver for AevumDB NoSQL database. 100% API coverage, TypeScript-native, and optimized for high-concurrency environments.","homepage":"https://github.com/aevumdb/aevum-node#readme","keywords":["aevumdb","nosql","database","driver","nodejs","typescript","performance","connection-pooling","async-await","rbac","schema-validation"],"repository":{"type":"git","url":"git+https://github.com/aevumdb/aevum-node.git"},"author":{"name":"AevumDB Team"},"bugs":{"url":"https://github.com/aevumdb/aevum-node/issues"},"license":"SEE LICENSE IN LICENSE","readme":"# AevumDB Node.js Driver\n\n[![npm version](https://img.shields.io/npm/v/@aevumdb/node-driver)](https://www.npmjs.com/package/@aevumdb/node-driver)\n[![npm downloads](https://img.shields.io/npm/dm/@aevumdb/node-driver)](https://www.npmjs.com/package/@aevumdb/node-driver)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)\n[![License](https://img.shields.io/badge/License-AEVUMDB%20Community-green)](LICENSE)\n\nOfficial high-performance Node.js driver for **AevumDB** NoSQL database with **100% API coverage**.\n\n-   **100% Feature Complete**: Provides full support for all CRUD, query, admin, and schema operations.\n-   **TypeScript First**: Designed with TypeScript from the ground up, offering full type safety and comprehensive JSDoc documentation.\n-   **High Performance**: Includes advanced features like connection pooling for efficient handling of concurrent operations.\n-   **Async/Await**: Utilizes a modern, Promise-based API for clean and readable asynchronous code.\n-   **Production Ready**: Built with comprehensive error handling and logging mechanisms for robust production deployments.\n\n## Quick Start\n\nGet started with the AevumDB Node.js Driver quickly.\n\n### Installation\n\nInstall the driver using `npm` or `pnpm`:\n\n```bash\nnpm install @aevumdb/node-driver\n# or\npnpm add @aevumdb/node-driver\n```\n\n### Basic Usage\n\nConnect to your AevumDB instance and perform basic CRUD operations.\n\n```typescript\nimport { AevumClient } from '@aevumdb/node-driver';\n\nasync function main() {\n  const client = new AevumClient({\n    host: '127.0.0.1',\n    port: 55001,\n    apiKey: 'root', // Use a secure API key in production\n    poolSize: 10, // Configure connection pooling for high concurrency\n  });\n\n  try {\n    await client.connect();\n    console.log('Connected to AevumDB');\n\n    // Insert a document\n    const result = await client.insert('users', {\n      name: 'John Doe',\n      email: 'john@example.com',\n      age: 30,\n    });\n    console.log('Created user:', result.data?._id);\n\n    // Query documents\n    const users = await client.find('users', { age: { $gte: 21 } }, { limit: 10 });\n    console.log('Found users:', users.data?.length, 'document(s)');\n\n    // Update documents\n    const updated = await client.update(\n      'users',\n      { email: 'john@example.com' },\n      { age: 31 }\n    );\n    console.log('Updated documents:', updated.data?.updated_count);\n\n    // Delete documents\n    const deleted = await client.delete('users', { email: 'john@example.com' });\n    console.log('Deleted documents:', deleted.data?.deleted_count);\n  } catch (error: any) {\n    console.error('Operation failed:', error.message);\n  } finally {\n    await client.disconnect();\n    console.log('Disconnected from AevumDB');\n  }\n}\n\nmain();\n```\n\n## Documentation\n\nExplore the full capabilities of the AevumDB Node.js Driver with our comprehensive documentation:\n\n-   [API Reference](docs/API.md) - Detailed documentation of all client methods and operations.\n-   [Connection & Pooling Guide](docs/CONNECTION.md) - Learn about managing connections and configuring connection pools.\n-   [Error Handling Guide](docs/ERRORS.md) - Understand error classes and best practices for robust error handling.\n-   [Examples](examples/) - Browse runnable code examples to see the driver in action.\n-   [Best Practices](docs/BEST_PRACTICES.md) - Discover recommendations for performance, security, and application design patterns.\n-   [Support](SUPPORT.md) - Find information on how to get help and contribute.\n\n## Features\n\nThe AevumDB Node.js Driver provides a rich set of features for interacting with your database.\n\n### CRUD Operations\n\nThe driver offers a complete set of CRUD (Create, Read, Update, Delete) operations.\n\n| Operation | Description | Read-Only | Read-Write | Admin |\n|-----------|-------------|-----------|------------|-------|\n| `insert()` | Inserts a new document into a collection. | No | Yes | Yes |\n| `find()` | Queries documents with filtering, sorting, and pagination. | Yes | Yes | Yes |\n| `update()` | Modifies existing documents based on a query. | No | Yes | Yes |\n| `delete()` | Removes documents matching a specified query. | No | Yes | Yes |\n| `count()` | Counts documents that match a given filter. | Yes | Yes | Yes |\n\n### Admin Operations\n\nLeverage administrative functionalities for database management.\n\n| Operation    | Description                             |\n|--------------|-----------------------------------------|\n| `setSchema()` | Enables JSON Schema validation for a collection. |\n| `createUser()` | Creates new database users with role-based access control. |\n\n### Query Operators\n\nA powerful set of operators for building flexible query filters.\n\n```typescript\n// Comparison operators for numerical or comparable values\n{ age: { $gt: 25 } }        // Greater than\n{ age: { $gte: 25 } }       // Greater than or equal to\n{ age: { $lt: 60 } }        // Less than\n{ age: { $lte: 60 } }       // Less than or equal to\n{ age: { $eq: 30 } }        // Equal to\n{ age: { $ne: 30 } }        // Not equal to\n\n// Array operators for checking membership in array fields\n{ tags: { $in: ['admin', 'moderator'] } }  // Value is present in the array\n{ tags: { $nin: ['banned'] } }              // Value is not present in the array\n\n// Implicit AND logic: Multiple conditions are combined with a logical AND\n{ age: { $gte: 21 }, status: 'active' } // Equivalent to: age >= 21 AND status = 'active'\n```\n\n### Role-Based Access Control (RBAC)\n\nSecure your application with fine-grained access control by creating users with specific roles.\n\n```typescript\nimport { AevumClient, AevumUserRole } from '@aevumdb/node-driver';\n\nconst admin = new AevumClient({ apiKey: 'admin-master-key' }); // Connect with an admin key\nawait admin.connect();\n\n// Create a read-only user for analytics\nawait admin.createUser('analytics-key', AevumUserRole.READ_ONLY);\n\n// Create a read-write user for general application operations\nawait admin.createUser('app-user', AevumUserRole.READ_WRITE);\n\n// Create another admin user for backup purposes\nawait admin.createUser('admin-backup', AevumUserRole.ADMIN);\n\nawait admin.disconnect();\n```\n\n### Schema Validation\n\nEnforce data integrity and consistency using JSON Schemas for your collections.\n\n```typescript\nimport { AevumClient } from '@aevumdb/node-driver';\n\nasync function main() {\n  const client = new AevumClient({ apiKey: 'root' });\n  await client.connect();\n\n  const schema = {\n    type: 'object',\n    properties: {\n      name: { type: 'string', minLength: 1 },\n      email: { type: 'string', format: 'email' },\n      age: { type: 'integer', minimum: 0, maximum: 150 },\n    },\n    required: ['name', 'email'],\n    additionalProperties: true,\n  };\n\n  await client.setSchema('users', schema);\n  console.log('Schema set for users collection.');\n\n  // Valid insert (conforms to schema)\n  await client.insert('users', {\n    name: 'Jane Doe',\n    email: 'jane@example.com',\n    age: 28,\n  });\n  console.log('Valid document inserted.');\n\n  // Invalid insert (will fail schema validation)\n  try {\n    await client.insert('users', {\n      name: 'John',\n      age: 'invalid', // 'age' should be an integer\n    });\n  } catch (error: any) {\n    console.error('Insert failed due to schema validation (expected):', error.message);\n  } finally {\n    await client.disconnect();\n  }\n}\n\nmain();\n```\n\n### Connection Pooling\n\nOptimize performance and resource utilization for high-concurrency environments.\n\n```typescript\nimport { AevumClient } from '@aevumdb/node-driver';\n\nasync function main() {\n  // Single connection (default if poolSize is 0 or omitted)\n  const singleClient = new AevumClient({\n    host: '127.0.0.1',\n    port: 55001,\n    poolSize: 0,\n  });\n  await singleClient.connect();\n  console.log('Single connection client connected.');\n  await singleClient.disconnect();\n\n  // Connection pool (recommended for high concurrency)\n  const pooledClient = new AevumClient({\n    host: '127.0.0.1',\n    port: 55001,\n    poolSize: 10, // 10 concurrent connections\n    connectTimeout: 5000, // 5 seconds connection timeout\n    queryTimeout: 10000, // 10 seconds per-query timeout\n  });\n\n  await pooledClient.connect();\n  console.log('Pooled client connected.');\n\n  // Get current connection pool statistics\n  const stats = pooledClient.getPoolStats();\n  if (stats) {\n    console.log(`Pool Stats: Available: ${stats.available}, In use: ${stats.inUse}, Waiting: ${stats.waiting}`);\n  }\n\n  await pooledClient.disconnect();\n  console.log('Pooled client disconnected.');\n}\n\nmain();\n```\n\n### Error Handling\n\nImplement robust error handling to build resilient applications.\n\n```typescript\nimport {\n  AevumClient,\n  AevumError,\n  AevumConnectionError,\n  AevumAuthError,\n  AevumOperationError,\n  AevumTimeoutError,\n  AevumValidationError,\n} from '@aevumdb/node-driver';\n\nasync function main() {\n  const client = new AevumClient({ apiKey: 'invalid-key' }); // Use an invalid key for demonstration\n\n  try {\n    await client.insert('users', { name: 'John' });\n    console.log('Document inserted (this should not happen with invalid key).');\n  } catch (error: any) {\n    if (error instanceof AevumConnectionError) {\n      console.error('Error: Connection failed -', error.message);\n    } else if (error instanceof AevumAuthError) {\n      console.error('Error: Authentication failed -', error.message);\n    } else if (error instanceof AevumTimeoutError) {\n      console.error('Error: Request timeout -', error.message);\n    } else if (error instanceof AevumValidationError) {\n      console.error('Error: Validation failed -', error.message);\n    } else if (error instanceof AevumOperationError) {\n      console.error(`Error: AevumDB Operation Failed [${error.code}] -`, error.message);\n    } else if (error instanceof AevumError) {\n      console.error(`Error: Generic AevumDB Error [${error.code}] -`, error.message);\n    } else {\n      console.error('Error: Unexpected error -', error);\n    }\n  } finally {\n    await client.disconnect();\n  }\n}\n\nmain();\n```\n\n## Development\n\nInstructions for setting up and working with the driver's source code.\n\n### Build\n\nCompile the TypeScript source code:\n\n```bash\npnpm build\n```\n\n### Tests\n\nRun unit and integration tests:\n\n```bash\npnpm test           # Run all tests with coverage report\npnpm test:watch     # Run tests in watch mode for development\n```\n\n### Linting & Formatting\n\nEnsure code quality and consistency:\n\n```bash\npnpm lint           # Automatically fix ESLint issues\npnpm lint:check     # Check for ESLint issues without fixing\npnpm format         # Automatically format code using Prettier\npnpm format:check   # Check formatting issues without applying changes\n```\n\n### Type Checking\n\nVerify TypeScript types:\n\n```bash\npnpm typecheck\n```\n\n## Contributing\n\nWe welcome contributions from the community! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) guide for detailed guidelines on how to get involved.\n\n## License\n\nCopyright (c) 2026 Ananda Firmansyah. Licensed under the [AEVUMDB COMMUNITY LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-49210fc58f7e38e93206947740ad9b29"}