{"id":15097596,"url":"https://github.com/fastuptime/stardb","last_synced_at":"2025-03-27T16:20:03.400Z","repository":{"id":228025623,"uuid":"772987937","full_name":"fastuptime/stardb","owner":"fastuptime","description":"🌟 StarDB: Easy and Reliable Persistent JSON/YAML Rest API and Data Management","archived":false,"fork":false,"pushed_at":"2024-03-16T16:58:36.000Z","size":22,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T19:45:56.595Z","etag":null,"topics":["database","db","easy-to-use","fastdb","json","jsondb","node-json","nodejs","stardb"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastuptime.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-16T12:37:24.000Z","updated_at":"2024-03-16T14:06:28.000Z","dependencies_parsed_at":"2024-03-16T13:39:29.945Z","dependency_job_id":"40d354aa-1b3a-4624-9d3f-859f174fe783","html_url":"https://github.com/fastuptime/stardb","commit_stats":null,"previous_names":["fastuptime/stardb"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastuptime%2Fstardb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastuptime%2Fstardb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastuptime%2Fstardb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastuptime%2Fstardb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastuptime","download_url":"https://codeload.github.com/fastuptime/stardb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245878929,"owners_count":20687297,"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","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":["database","db","easy-to-use","fastdb","json","jsondb","node-json","nodejs","stardb"],"created_at":"2024-09-25T16:23:51.410Z","updated_at":"2025-03-27T16:20:03.374Z","avatar_url":"https://github.com/fastuptime.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 🌟 StarDB: Easy and Reliable Persistent JSON/YAML Rest API and Data Management\n\n### 🔥 What's New in Version 1.2.0: API Support!\nStarDB can now work with RESTful APIs in addition to JSON and YAML files. The API makes your database files accessible remotely and provides a secure key-based authentication system.\n\n```js\n// Example usage with API\nconst restFullAPI = new API({\n    port: 3000,\n    auth: true,\n    db: 'starDB.json', // Default is 'starDB.json'\n    authKeys: [\n        'key1',\n        'key2',\n        'key3'\n    ],\n});\n```\n\n### 🚀 What's New in Version 1.1.0: YAML Support!\nStarDB now supports the YAML file format in addition to JSON. You can store your data in YAML format for better readability and flexibility.\n\n```js\n// Example usage with YAML\nconst db = new StarDB('data.yaml');\n```\n\n**Introduction**\n\nStarDB is a lightweight and asynchronous module that offers a simple and reliable solution for storing and managing JSON/YAML data persistently in Node.js. It simplifies the file-based data storage process with a familiar key-value interface and is an excellent choice for applications requiring persistent yet flexible data management. Additionally, it can work with RESTful APIs, making your database files remotely accessible and providing a secure key-based authentication system.\n\n**Features:**\n\n* **Easy to Use:** The intuitive API makes working with JSON and YAML data quick and straightforward.\n* **Reliability:** Database files are stored and managed in a robust format that prevents data loss.\n* **Speed:** Database queries are fast and efficient, compatible with asynchronous operations.\n* **Flexibility:** JSON and YAML support allows you to store complex data structures.\n* **RESTful API Support:** Makes your database files remotely accessible and provides a secure key-based authentication system.\n* **Extensibility:** You can add custom modules and plugins for advanced functionality.\n\n**🚀 Installation:**\n\nTo install StarDB from the npm registry, use:\n\n```bash\nnpm install stardb\n```\n\n**📘 Usage:**\n\n1. **Import the Module:**\n\n```javascript\nconst { StarDB, API } = require('stardb');\n```\n\n2. **Create an Instance:**\n\n```javascript\nconst db = new StarDB('data.json'); // Replace 'data.json' with your desired file name\n// or\nconst db = new StartDB('data.yaml'); // Replace 'data.yaml' with your desired file name\n```\n\nCreates an instance of StarDB associated with the specified file ('data.json' in this example). StarDB will automatically create the file if it doesn't exist.\n\n3. **CRUD Operations:**\n\nStarDB provides methods for common CRUD (Create, Read, Update, Delete) operations on your JSON/YAML data:\n\n* **`set(key, value)`:** Stores a key-value pair in the database.\n* **`get(key)`:** Retrieves the value associated with a key.\n* **`delete(key)`:** Removes the specified key and its value from the database.\n* **`push(key, value)`:** Adds a value to an array stored under the specified key (creates the array if it doesn't exist).\n* **`pop(key)`:** Removes and returns the last element from an array stored under the specified key.\n* **`shift(key)`:** Removes and returns the first element from an array stored under the specified key.\n* **`unshift(key, value)`:** Adds a value to the beginning of an array stored under the specified key (creates the array if it doesn't exist).\n* **`deleteByIndex(key, index)`:** Deletes the item at the specified index from an array stored under the specified key.\n* **`updateByIndex(key, index, value)`:** Updates the value at the specified index in an array stored under the specified key.\n\n4. **Search and Transformation:**\n\n* **`find(key, value)`:** Finds the first item in the database associated with the provided value for the specified key.\n* **`filter(key, value)`:** Returns a new array containing all items in the database associated with the provided value for the specified key.\n* **`map(key, callback)`:** Applies a callback function to each item stored under the specified key and returns a new array of transformed items.\n\n5. **Additional Methods:**\n\n* **`fetchAll()`:** Retrieves the entire contents of the database as a plain JavaScript object.\n* **`deleteAll(access = false)`:** Deletes all data from the database (requires `access` permission for security).\n* **`destroy(access = false)`:** Permanently deletes the database file (requires `access` permission for security).\n* **`has(key)`:** Checks if a key exists in the database.\n\n6. **Using the RESTful API 🎯:**\n\n```javascript\nconst restFullAPI = new API({\n    port: 3000,\n    auth: true,\n    db: 'starDB.json', // Default is 'starDB.json'\n    authKeys: [\n        'key1',\n        'key2',\n        'key3'\n    ],\n});\n\n// Start the API\n\nrestFullAPI.start();\n```\n\n1. **Adding Data (POST Request)**:\n\n    For example, let's add a key-value pair by sending a POST request to the `/set/:key` route. We'll set the key as \"name\" and the value as \"John Doe\".\n\n    ```bash\n    curl -X POST -H \"Content-Type: application/json\" -d '{\"value\": \"John Doe\"}' http://localhost:3001/set/name\n    ```\n\n    This request will add the key \"name\" with the value \"John Doe\" to StarDB.\n\n2. **Retrieving Data (GET Request)**:\n\n    To retrieve the data we added, let's send a GET request to the `/get/:key` route. We'll use \"name\" as the key again.\n\n    ```bash\n    curl http://localhost:3001/get/name\n    ```\n\n    This request will return the value associated with the \"name\" key.\n\n3. **Updating Data (POST Request)**:\n\n    To update the value of an existing key, we can send a POST request to the `/set/:key` route again. Let's update the value of the \"name\" key to \"Jane Doe\".\n\n    ```bash\n    curl -X POST -H \"Content-Type: application/json\" -d '{\"value\": \"Jane Doe\"}' http://localhost:3001/set/name\n    ```\n\n    This request will update the value of the \"name\" key to \"Jane Doe\".\n\n4. **Deleting Data (DELETE Request)**:\n\n    To delete a key-value pair, we can send a DELETE request to the `/delete/:key` route. Let's delete the \"name\" key.\n\n    ```bash\n    curl -X DELETE http://localhost:3001/delete/name\n    ```\n\n    This request will delete the \"name\" key and its value from the database.\n\n**📚 Example Usage:**\n\n```javascript\nconst { StarDB, API } = require('stardb');\n\n// Example usage with JSON\n\nconst db = new StarDB('data.json');\n\n//\n\n Adding data\ndb.set('name', 'John Doe');\n\n// Retrieving data\nconsole.log(db.get('name')); // John Doe\n\n// Updating data\ndb.set('name', 'Jane Doe');\n\n// Deleting data\ndb.delete('name');\n\n// Adding to an array\ndb.push('fruits', 'apple');\ndb.push('fruits', 'banana');\n\n// Retrieving from an array\nconsole.log(db.pop('fruits')); // banana\n\n// Deleting from an array\ndb.deleteByIndex('fruits', 0);\n\n// Adding to the beginning of an array\ndb.unshift('fruits', 'orange');\n\n// Retrieving from the beginning of an array\nconsole.log(db.shift('fruits')); // orange\n\n// Updating an array\ndb.updateByIndex('fruits', 0, 'grape');\n\n```\n\n**🛠️ Error Handling:**\n\nStarDB provides informative error messages for various potential issues, such as invalid file access, key authentication, and data storage errors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastuptime%2Fstardb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastuptime%2Fstardb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastuptime%2Fstardb/lists"}