{"id":19478949,"url":"https://github.com/ankansaha/axiodb","last_synced_at":"2025-07-30T14:41:16.432Z","repository":{"id":258822773,"uuid":"865573974","full_name":"AnkanSaha/AxioDB","owner":"AnkanSaha","description":"A fast, lightweight, and scalable open-source DBMS for modern apps. Supports JSON-based data storage, simple APIs, and secure data management. Ideal for projects needing efficient and flexible database solutions.","archived":false,"fork":false,"pushed_at":"2025-07-27T16:16:15.000Z","size":2665,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-29T11:43:44.003Z","etag":null,"topics":["algorithms","data-structures","database","javascript","json","nodejs","nosql"],"latest_commit_sha":null,"homepage":"https://axiodb.site","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AnkanSaha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"AnkanSaha","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-09-30T18:50:58.000Z","updated_at":"2025-07-27T16:16:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"1e9e7b15-2241-4c76-aaaa-445e8f181ad4","html_url":"https://github.com/AnkanSaha/AxioDB","commit_stats":null,"previous_names":["ankansaha/axiodb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AnkanSaha/AxioDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnkanSaha%2FAxioDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnkanSaha%2FAxioDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnkanSaha%2FAxioDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnkanSaha%2FAxioDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AnkanSaha","download_url":"https://codeload.github.com/AnkanSaha/AxioDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AnkanSaha%2FAxioDB/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267883850,"owners_count":24160234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithms","data-structures","database","javascript","json","nodejs","nosql"],"created_at":"2024-11-10T19:52:09.927Z","updated_at":"2025-07-30T14:41:16.403Z","avatar_url":"https://github.com/AnkanSaha.png","language":"TypeScript","funding_links":["https://github.com/sponsors/AnkanSaha"],"categories":[],"sub_categories":[],"readme":"# AxioDB: A NoSQL DBMS\n\n[![npm version](https://badge.fury.io/js/axiodb.svg)](https://badge.fury.io/js/axiodb)\n[![CodeQL](https://github.com/AnkanSaha/AxioDB/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/AnkanSaha/AxioDB/actions/workflows/github-code-scanning/codeql)\n[![Socket Security](https://socket.dev/api/badge/npm/package/axiodb)](https://socket.dev/npm/package/axiodb)\n[![Push to Registry](https://github.com/AnkanSaha/AxioDB/actions/workflows/Push.yml/badge.svg?branch=main)](https://github.com/AnkanSaha/AxioDB/actions/workflows/Push.yml)\n\nAxioDB is a blazing-fast, lightweight, and scalable open-source Database Management System (DBMS) tailored for modern applications. It supports `.axiodb` file-based data storage, offers intuitive APIs, and ensures secure data management. AxioDB is the ultimate solution for developers seeking efficient, flexible, and production-ready database solutions.\n\n👉 **[Official Documentation](https://axiodb.site/)**: Access the full power of AxioDB with detailed guides, examples, and API references.\n\n## 🌐 Table of Contents\n\n- [🚀 Features](#-features)\n- [⚠️ Current Limitations](#-current-limitations)\n- [🔮 Future Plans](#-future-plans)\n- [📦 Installation](#-installation)\n- [🛠️ Usage](#-usage)\n- [🌟 Advanced Features](#-advanced-features)\n- [📖 API Reference](#-api-reference)\n- [🔒 Security](#-security)\n- [🤝 Contributing](#-contributing)\n- [📜 License](#-license)\n- [🙌 Acknowledgments](#-acknowledgments)\n\n## 🚀 Current Featured Features\n\n- **Advanced Schema Validation:** Define robust schemas to ensure data consistency and integrity, with the flexibility to disable validation when needed.\n- **Chainable Query Methods:** Leverage powerful methods like `.query()`, `.Sort()`, `.Limit()`, and `.Skip()` for seamless data filtering.\n- **Optimized Node.js Streams:** Handle massive datasets effortlessly with high-performance read/write operations.\n- **Encryption-First Design:** Protect sensitive data with optional AES-256 encryption for collections.\n- **Aggregation Pipelines:** Perform advanced data operations like `$match`, `$sort`, `$group`, and more with MongoDB-like syntax.\n- **InMemoryCache Mechanism:** Accelerate query execution by caching frequently accessed data, reducing query response time significantly.\n- **Plug-and-Play Setup:** No additional database server required—install and start building instantly.\n- **Tree-like Structure:** Store data in a tree-like structure for efficient data retrieval and management.\n- **Auto Indexing on documentId:** Automatically create index on documentId for faster queries.\n- **Single Instance Architecture:** For data consistency and security, you can initialize only one AxioDB instance with the `new` keyword. Under this single instance, you can create unlimited databases, collections, and documents.\n- **Web-Based GUI Dashboard:** When you create an AxioDB instance and run your project, it automatically starts a web-based GUI on `localhost:27018` for visual database management (currently under development).\n\n---\n\n## ⚠️ Current Limitations\n\nWhile AxioDB offers many powerful features, there are some limitations to consider:\n\n- **No Built-in Relation Tools:** Unlike ODMs such as Mongoose, AxioDB doesn't provide built-in tools for managing document relations. While MongoDB-like NoSQL databases naturally don't enforce relations at the database level, AxioDB currently requires manual handling of references between collections.\n\n- **Not Optimized for Heavy Workloads:** The database may not perform optimally with rapid data input/output scenarios or extremely large datasets (10M+ documents).\n\n- **Single-Thread Operations:** Operations are performed on the main thread which can impact application performance during complex queries.\n\n- **Limited Query Complexity:** Some advanced query patterns found in mature databases are not yet implemented.\n\n- **No Built-in Replication:** Currently lacks distributed data replication capabilities for high availability setups.\n\nWe're actively working to address these limitations in future releases.\n\n---\n\n## 🔮 Future Plans\n\nWe're committed to continuously enhancing AxioDB with cutting-edge features:\n\n- **Inbuilt Web-Based GUI Dashboard:** Provide a user-friendly, web-based interface similar to PhpMyAdmin for managing databases, collections, and data visually.\n- **Data Export and Import Mechanisms:** Enable seamless export and import of data in various formats like JSON, CSV, and more.\n- **Advanced Indexing:** Implement multi-level indexing for lightning-fast queries.\n- **Replication and Sharding:** Introduce support for distributed data replication and sharding for high availability and scalability.\n- **Improved Query Optimization:** Enhance query performance with advanced optimization techniques.\n- **Data Backup and Restore:** Implement robust backup and restore mechanisms for data safety.\n- **Comprehensive Documentation:** Expand tutorials, examples, and API references for developers.\n\n---\n\n## 📦 Installation\n\nInstall AxioDB via npm:\n\n```bash\nnpm install axiodb@latest --save\n```\n\n---\n\n## 🛠️ Usage\n\n\u003e **Important Note:** AxioDB uses a single instance architecture. You should initialize only one AxioDB instance with the `new` keyword, under which you can create unlimited databases, collections, and documents. This design ensures data consistency and security across your application.\n\n### Collection Creation Options\n\nWhen creating collections, you need to specify these parameters in the `createCollection` method:\n\n```javascript\n// Signature of createCollection method:\ncreateCollection(\n  name: string,           // Name of the collection (required)\n  isSchemaNeeded: boolean, // Whether schema validation is needed (required)\n  schema?: object | any,  // Schema definition (required if isSchemaNeeded is true, empty {} if false)\n  isEncrypted?: boolean,  // Whether to encrypt the collection (default: false)\n  encryptionKey?: string  // Custom encryption key (optional, system generates one if not provided)\n)\n```\n\nExamples:\n\n```javascript\n// Create collection with schema validation\nconst collection1 = await db1.createCollection(\"testCollection\", true, schema);\n\n// Create collection without schema validation\nconst collection2 = await db1.createCollection(\"testCollection2\", false);\n\n// Create an encrypted collection with schema validation and default encryption key\nconst collection3 = await db1.createCollection(\n  \"testCollection3\",\n  true,\n  schema,\n  true,\n);\n\n// Create an encrypted collection with schema validation and custom encryption key\nconst collection4 = await db1.createCollection(\n  \"testCollection4\",\n  true,\n  schema,\n  true,\n  \"myCustomKey\",\n);\n\n// Create an encrypted collection without schema validation (using empty object for schema)\nconst collection5 = await db1.createCollection(\n  \"testCollection5\",\n  false,\n  {},\n  true,\n);\n\n// Create an encrypted collection without schema and with custom key\nconst collection6 = await db1.createCollection(\n  \"testCollection6\",\n  false,\n  {},\n  true,\n  \"myCustomKey\",\n);\n```\n\n### CommonJS Example\n\n```javascript\nconst { AxioDB, SchemaTypes } = require(\"axiodb\");\n\n// Create a single AxioDB instance for your entire application\n// This will also start the Web GUI on localhost:27018 (currently under development)\nconst db = new AxioDB();\n\nconst main = async () =\u003e {\n  // Create multiple databases under the single instance\n  const db1 = await db.createDB(\"testDB\");\n  const db2 = await db.createDB(\"testDB2\", false);\n\n  // Define a schema\n  const schema = {\n    name: SchemaTypes.string().required(),\n    age: SchemaTypes.number().required().min(1).max(100),\n    email: SchemaTypes.string().required().email(),\n  };\n\n  // Create collections with and without schema validation\n  const collectionNoSchema = await db1.createCollection(\n    \"testCollection2\",\n    false,\n  );\n  const collectionExplicitSchema = await db1.createCollection(\n    \"testCollection3\",\n    true,\n    schema,\n  );\n  const collectionWithEncryption = await db1.createCollection(\n    \"testCollection4\",\n    schema,\n    true,\n    \"myKey\",\n  );\n\n  // Insert data\n  const saveStatus = await collection.insert({\n    name: \"Ankan\",\n    age: 21,\n    email: \"ankan@example.com\",\n  });\n  console.log(saveStatus);\n\n  // Query data\n  const totalDocuments = await collection\n    .query({})\n    .Limit(1)\n    .Skip(0)\n    .Sort({ name: 1 })\n    .setCount(true)\n    .setProject({ name: 1, age: 1 })\n    .exec();\n  console.log(totalDocuments);\n\n  const FastDocument = await collection\n    .query({ documentId: \"S4ACDVS6SZ4S6VS\" })\n    .exec(); // By using documentId you can get the document in Lightning Fast Speed, no matter how many documents are in the collection (Tested with 1000000+ documents)\n  console.log(FastDocument);\n\n  const ArrayFirstDocument = await collection\n    .query({ documentId: [\"S4ACDVS6SZ4S6VS\", \"VESV61Z6VS16VSE6V1S\"] })\n    .exec(); // query using an array of documentId to get multiple documents in lightning fast speed, no matter how many documents are in the collection (Tested with 1000000+ documents)\n  console.log(ArrayFirstDocument);\n\n  // Update data\n  const updatedDocuments = await collection\n    .update({ name: { $regex: \"Ankan\" } })\n    .UpdateOne({ name: \"Ankan Saha\", age: 22 });\n  console.log(updatedDocuments);\n\n  // Delete data\n  const deletedDocuments = await collection\n    .delete({ name: { $regex: \"Ankan\" } })\n    .deleteOne();\n  console.log(deletedDocuments);\n\n  // Aggregation\n  const response = await collection\n    .aggregate([\n      { $match: { age: { $gt: 20 }, name: { $regex: \"Ankan\" } } },\n      { $group: { _id: \"$age\", count: { $sum: 1 } } },\n      { $sort: { count: -1 } },\n      { $project: { _id: 0, age: \"$_id\", count: 1 } },\n      { $limit: 10 },\n      { $skip: 0 },\n    ])\n    .exec();\n  console.log(response);\n};\n\nmain();\n```\n\n---\n\n### ES6 Example\n\n```javascript\nimport { AxioDB, SchemaTypes } from \"axiodb\";\n\nconst main = async () =\u003e {\n  const db = new AxioDB();\n\n  // Create a database with schema validation (default)\n  const db1 = await db.createDB(\"testDB\");\n\n  // Create a database without schema validation\n  const db2 = await db.createDB(\"testDB2\", false);\n\n  // Define a schema\n  const schema = {\n    name: SchemaTypes.string().required(),\n    age: SchemaTypes.number().required().min(1).max(100),\n    email: SchemaTypes.string().required().email(),\n  };\n\n  // Create collections with and without schema validation\n  const collectionNoSchema = await db1.createCollection(\n    \"testCollection2\",\n    false,\n  );\n  const collectionExplicitSchema = await db1.createCollection(\n    \"testCollection3\",\n    true,\n    schema,\n  );\n  const collectionWithEncryption = await db1.createCollection(\n    \"testCollection4\",\n    schema,\n    true,\n    \"myKey\",\n  );\n\n  // Insert data\n  const saveStatus = await collection.insert({\n    name: \"Ankan\",\n    age: 21,\n    email: \"ankan@example.com\",\n  });\n  console.log(saveStatus);\n\n  // Query data\n  const totalDocuments = await collection\n    .query({})\n    .Limit(1)\n    .Skip(0)\n    .Sort({ name: 1 })\n    .setCount(true)\n    .setProject({ name: 1, age: 1 })\n    .exec();\n  console.log(totalDocuments);\n\n  const FastDocument = await collection\n    .query({ documentId: \"S4ACDVS6SZ4S6VS\" })\n    .exec(); // By using documentId you can get the document in Lightning Fast Speed, no matter how many documents are in the collection (Tested with 1000000+ documents)\n  console.log(FastDocument);\n\n  const ArrayFirstDocument = await collection\n    .query({ documentId: [\"S4ACDVS6SZ4S6VS\", \"VESV61Z6VS16VSE6V1S\"] })\n    .exec(); // query using an array of documentId to get multiple documents in lightning fast speed, no matter how many documents are in the collection (Tested with 1000000+ documents)\n  console.log(ArrayFirstDocument);\n\n  // Update data\n  const updatedDocuments = await collection\n    .update({ name: { $regex: \"Ankan\" } })\n    .UpdateOne({ name: \"Ankan Saha\", age: 22 });\n  console.log(updatedDocuments);\n\n  // Delete data\n  const deletedDocuments = await collection\n    .delete({ name: { $regex: \"Ankan\" } })\n    .deleteOne();\n  console.log(deletedDocuments);\n\n  // Aggregation\n  const response = await collection\n    .aggregate([\n      { $match: { age: { $gt: 20 }, name: { $regex: \"Ankan\" } } },\n      { $group: { _id: \"$age\", count: { $sum: 1 } } },\n      { $sort: { count: -1 } },\n      { $project: { _id: 0, age: \"$_id\", count: 1 } },\n      { $limit: 10 },\n      { $skip: 0 },\n    ])\n    .exec();\n  console.log(response);\n};\n\nmain();\n```\n\n---\n\n## 🌟 Advanced Features\n\n### 1. **Creating Multiple Databases and Collections**\n\n```javascript\nconst { AxioDB, SchemaTypes } = require(\"axiodb\");\n\nconst db = new AxioDB();\n\nconst setup = async () =\u003e {\n  const schema = {\n    name: SchemaTypes.string().required().max(15),\n    age: SchemaTypes.number().required().min(18),\n  };\n\n  const DB1 = await db.createDB(\"DB1\");\n  const collection1 = await DB1.createCollection(\n    \"collection1\",\n    schema,\n    true,\n    \"secretKey\",\n  );\n\n  // Insert data\n  for (let i = 0; i \u003c 300; i++) {\n    await collection1.insert({ name: `User${i}`, age: i + 18 });\n  }\n\n  // Query data\n  const results = await collection1\n    .query({})\n    .Sort({ age: -1 })\n    .Limit(10)\n    .exec();\n  console.log(\"Query Results:\", results);\n\n  // Delete collection\n  await DB1.deleteCollection(\"collection1\");\n};\n\nsetup();\n```\n\n---\n\n### 2. **Aggregation Pipelines**\n\nPerform advanced operations like filtering, sorting, grouping, and projecting data.\n\n```javascript\nconst aggregationResult = await collection1\n  .aggregate([\n    { $match: { name: { $regex: \"User\" } } },\n    { $project: { name: 1, age: 1 } },\n    { $sort: { age: -1 } },\n    { $limit: 10 },\n  ])\n  .exec();\n\nconsole.log(\"Aggregation Result:\", aggregationResult);\n```\n\n---\n\n### 3. **Encryption**\n\nEnable encryption for sensitive data by providing a secret key during collection creation.\n\n```javascript\nconst encryptedCollection = await DB1.createCollection(\n  \"secureCollection\",\n  schema,\n  true,\n  \"mySecretKey\",\n);\n\n// Insert encrypted data\nawait encryptedCollection.insert({ name: \"Encrypted User\", age: 25 });\n\n// Query encrypted data\nconst encryptedResult = await encryptedCollection.query({ age: 25 }).exec();\nconsole.log(\"Encrypted Query Result:\", encryptedResult);\n```\n\n---\n\n### 4. **Update and Delete Operations**\n\n#### Update Documents\n\n```javascript\n// Update a single document\nawait collection1\n  .update({ age: 20 })\n  .UpdateOne({ name: \"Updated User\", gender: \"Male\" });\n\n// Update multiple documents\nawait collection1\n  .update({ name: { $regex: \"User\" } })\n  .UpdateMany({ isActive: true });\n```\n\n#### Delete Documents\n\n```javascript\n// Delete a single document\nawait collection1.delete({ name: \"User1\" }).deleteOne();\n\n// Delete multiple documents\nawait collection1.delete({ age: { $lt: 25 } }).deleteMany();\n```\n\n---\n\n## 📖 API Reference\n\n### AxioDB\n\n- **`createDB(dbName: string, schemaValidation: boolean = true): Promise\u003cDatabase\u003e`**  \n  Creates a new database. The optional `schemaValidation` parameter (default: true) determines whether schema validation will be enforced for collections in this database.\n\n- **`deleteDatabase(dbName: string): Promise\u003cSuccessInterface | ErrorInterface\u003e`**  \n  Deletes a database.\n\n### Database\n\n- **`createCollection(name: string, schema: object, crypto?: boolean, key?: string): Promise\u003cCollection\u003e`**  \n  Creates a collection with an optional schema and encryption.\n\n- **`deleteCollection(name: string): Promise\u003cSuccessInterface | ErrorInterface\u003e`**  \n  Deletes a collection.\n\n- **`getCollectionInfo(): Promise\u003cSuccessInterface\u003e`**  \n  Retrieves information about all collections.\n\n### Collection\n\n- **`createCollection(name: string, schemaOrBoolean: object | boolean, schemaOrEmpty?: object, crypto?: boolean, key?: string): Promise\u003cCollection\u003e`**  \n  Creates a collection with optional schema validation and encryption. The parameters are flexible:\n  - If the second parameter is a schema object, schema validation is enabled\n  - If the second parameter is a boolean, it determines whether schema validation is enabled\n  - For collections without schema but with encryption, pass `false, {}, true` as parameters\n  - The encryption key parameter is optional - if not provided, a default key will be generated\n\n- **`insert(data: object): Promise\u003cSuccessInterface | ErrorInterface\u003e`**  \n  Inserts a document into the collection.\n\n- **`query(query: object): Reader`**  \n  Queries documents in the collection.\n\n- **`aggregate(pipeline: object[]): Aggregation`**  \n  Performs aggregation operations.\n\n### Reader\n\n- **`Limit(limit: number): Reader`**  \n  Sets a limit on the number of documents.\n\n- **`Skip(skip: number): Reader`**  \n  Skips a number of documents.\n\n- **`Sort(sort: object): Reader`**  \n  Sorts the query results.\n\n- **`exec(): Promise\u003cSuccessInterface | ErrorInterface\u003e`**  \n  Executes the query.\n\n---\n\n## 🔒 Security\n\nAxioDB prioritizes data security with features like:\n\n- Optional encryption for collections.\n- Secure `.axiodb` file-based storage.\n- InMemoryCache for faster and more secure query handling.\n  For vulnerabilities, please refer to the [SECURITY.md](SECURITY.md) file.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! Whether it's code improvements, documentation updates, bug reports, or feature suggestions, your input helps make AxioDB better. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on how to get started.\n\n---\n\n## 📜 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙌 Acknowledgments\n\nSpecial thanks to all contributors and supporters of AxioDB. Your feedback and contributions make this project better!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankansaha%2Faxiodb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankansaha%2Faxiodb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankansaha%2Faxiodb/lists"}