{"id":26450995,"url":"https://github.com/crazywolf132/smalldb","last_synced_at":"2025-03-18T16:07:04.464Z","repository":{"id":280517957,"uuid":"856683269","full_name":"crazywolf132/smalldb","owner":"crazywolf132","description":"Your Tiny, Type-Safe, JSON-Powered Sidekick for Go!","archived":false,"fork":false,"pushed_at":"2024-09-13T02:24:48.000Z","size":7,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-12T19:31:31.926Z","etag":null,"topics":["database","go","json","key-value-store","lightweight","lightweight-database"],"latest_commit_sha":null,"homepage":"","language":"Go","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/crazywolf132.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-09-13T02:23:32.000Z","updated_at":"2024-09-13T02:26:33.000Z","dependencies_parsed_at":"2025-03-03T22:04:54.186Z","dependency_job_id":"18588bdd-e5e9-4194-b5cc-b1cbe269c844","html_url":"https://github.com/crazywolf132/smalldb","commit_stats":null,"previous_names":["crazywolf132/smalldb"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazywolf132%2Fsmalldb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazywolf132%2Fsmalldb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazywolf132%2Fsmalldb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazywolf132%2Fsmalldb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crazywolf132","download_url":"https://codeload.github.com/crazywolf132/smalldb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244257251,"owners_count":20424131,"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","go","json","key-value-store","lightweight","lightweight-database"],"created_at":"2025-03-18T16:07:03.876Z","updated_at":"2025-03-18T16:07:04.453Z","avatar_url":"https://github.com/crazywolf132.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# smalldb 🚀\n\n**Your Tiny, Type-Safe, JSON-Powered Sidekick for Go!**\n\n---\n\nAre you tired of overcomplicating your Go applications with heavyweight databases for simple data storage? Do you yearn for a lightweight, easy-to-use, and fun solution to handle your data needs? Look no further! Introducing **`smalldb`**, your new best friend for simple, efficient, and type-safe data storage.\n\n---\n\n## 🌟 What is smalldb?\n\n`smalldb` is a **lightweight**, **generic**, **file-based** key-value store for Go applications. It leverages the power of **Go's generics** to provide **type-safe**, **thread-safe**, and **easy-to-use** data storage without the overhead of a full-fledged database system.\n\n---\n\n## 🎯 Why smalldb?\n\nIn a world dominated by complex databases, sometimes all you need is a simple, reliable place to store your data. Maybe you're building a CLI tool, a small web service, or a prototype app. You don't need the hassle of setting up and maintaining a database server. You need something small. You need `smalldb`.\n\n### **Real-World Problems It Solves:**\n\n- **Simplicity**: No more wrestling with database drivers or ORM configurations.\n- **Portability**: Data stored in human-readable JSON files—easy to debug and transfer.\n- **Performance**: Minimal overhead for applications that require quick data access without concurrency bottlenecks.\n- **Type Safety**: Compile-time checks prevent bugs, making your code safer and more reliable.\n- **Rapid Development**: Perfect for prototypes, demos, or small projects where setup time is crucial.\n\n---\n\n## 🚀 Features\n\n- **🔒 Type Safety with Generics**: Enjoy the peace of mind that comes with compile-time type checking.\n- **🧘 Simplified API**: Intuitive methods for common operations—no ceremony, just results.\n- **⚡ Thread-Safe**: Concurrency handled gracefully with support for multiple readers.\n- **💾 Atomic Transactions**: Perform multiple operations atomically to maintain data integrity.\n- **📄 Human-Readable Storage**: Data stored in JSON—easy to read, edit, and manage.\n- **📦 Minimal Dependencies**: A lean library that won't bloat your project.\n- **✨ Fun to Use**: Because coding should bring joy!\n\n---\n\n## 🛠️ Installation\n\nReady to embrace simplicity? Install `smalldb` with a single command:\n\n```bash\ngo get github.com/crazywolf132/smalldb\n```\n\n---\n\n## 🎓 Getting Started\n\n### **Step 1: Import smalldb**\n\n```go\nimport \"github.com/crazywolf132/smalldb\"\n```\n\n### **Step 2: Define Your Data Type**\n\nCreate a struct that represents the data you want to store.\n\n```go\ntype User struct {\n    Name string\n    Age  int\n}\n```\n\n### **Step 3: Open the Database**\n\nInitialize your `smalldb` instance, specifying your data type.\n\n```go\ndb, err := smalldb.Open[User](\"path/to/db.json\")\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n---\n\n## 📖 Usage Guide\n\n### **Storing Data Made Simple**\n\n```go\n// Create a new user.\nalice := User{Name: \"Alice\", Age: 30}\n\n// Store the user in the database.\nif err := db.Set(\"user:1001\", alice); err != nil {\n    log.Fatal(err)\n}\n```\n\n### **Retrieving Your Data**\n\n```go\n// Retrieve the user from the database.\nuser, exists := db.Get(\"user:1001\")\nif !exists {\n    fmt.Println(\"User not found!\")\n} else {\n    fmt.Printf(\"Hello, %s! You are %d years old.\\n\", user.Name, user.Age)\n}\n```\n\n### **Updating Data**\n\n```go\n// Update the user's age.\nuser.Age = 31\nif err := db.Set(\"user:1001\", user); err != nil {\n    log.Fatal(err)\n}\n```\n\n### **Deleting Data**\n\n```go\n// Remove the user from the database.\nif err := db.Delete(\"user:1001\"); err != nil {\n    log.Fatal(err)\n}\n```\n\n### **Atomic Transactions**\n\nNeed to perform multiple operations atomically? We've got you covered!\n\n```go\nerr := db.Transaction(func(tx *smalldb.Tx[User]) error {\n    // Create two new users.\n    tx.Set(\"user:1002\", User{Name: \"Bob\", Age: 25})\n    tx.Set(\"user:1003\", User{Name: \"Charlie\", Age: 28})\n\n    // Delete an existing user.\n    tx.Delete(\"user:1004\")\n\n    // Commit the transaction.\n    return nil\n})\nif err != nil {\n    log.Fatal(err)\n}\n```\n\n---\n\n## 🌐 Real-World Applications\n\n- **Configuration Storage**: Store and manage application settings effortlessly.\n- **Caching Layer**: Implement a simple caching mechanism for your app.\n- **Session Management**: Keep track of user sessions in a lightweight manner.\n- **Prototype Development**: Quickly iterate on ideas without database setup overhead.\n- **Education**: Perfect for learning and teaching Go's concurrency and generics.\n\n---\n\n## 💡 Tips and Tricks\n\n- **Custom Types**: Use any serializable type—structs, slices, maps, you name it!\n- **Data Inspection**: Since data is stored in JSON, you can easily inspect and edit it with any text editor.\n- **Concurrency Control**: Read-heavy applications benefit from concurrent reads—thanks to `sync.RWMutex`.\n- **Error Handling**: Always check for errors to handle unexpected situations gracefully.\n- **Backups**: Copy the JSON file for a quick backup of your data.\n\n---\n\n## 🤔 FAQs\n\n**Q: Is `smalldb` suitable for production use?**\n\nA: Absolutely! While it's designed for simplicity, `smalldb` is thread-safe and reliable for applications that fit its use case.\n\n**Q: Can I store complex nested data structures?**\n\nA: Yes! As long as your data types are serializable to JSON, you can store them in `smalldb`.\n\n**Q: What happens if multiple goroutines try to write at the same time?**\n\nA: Write operations are synchronized using a mutex to prevent data races, ensuring data integrity.\n\n**Q: How large can the database get?**\n\nA: Since `smalldb` loads the entire database into memory, it's best suited for smaller datasets. If you're dealing with gigabytes of data, consider a different solution.\n\n**Q: Can I use `smalldb` in a web application?**\n\nA: Yes! It's perfect for small web services, APIs, or microservices where a full database might be overkill.\n\n---\n\n## 🛡️ Safety First!\n\n`smalldb` handles concurrency and data integrity with care, but remember:\n\n- **Backup Regularly**: Keep copies of your data, especially before major changes.\n- **Validate Your Data**: Ensure the data you're storing is correct and sanitized.\n- **Handle Errors**: Don't ignore errors—handle them appropriately to prevent surprises.\n\n---\n\n## 🚧 Under the Hood\n\nCurious about how `smalldb` works its magic? Here's a peek:\n\n- **Generics**: Utilizes Go's generics to enforce type safety at compile time.\n- **Mutex Locks**: Manages concurrent access with `sync.RWMutex`, allowing multiple readers and single writers.\n- **JSON Storage**: Serializes data to JSON for easy storage and retrieval.\n- **Atomic Transactions**: Provides a transactional interface to perform multiple operations atomically.\n\n---\n\n## 🌈 Contributing\n\nWe welcome contributions! Whether it's fixing bugs, adding features, or improving documentation, your help is appreciated.\n\n1. **Fork the Repository**\n2. **Create a Feature Branch**\n3. **Commit Your Changes**\n4. **Push to Your Fork**\n5. **Submit a Pull Request**\n\n---\n\n## 📜 License\n\n`smalldb` is licensed under the **MIT License**—because sharing is caring!\n\n---\n\n## 🙌 Acknowledgments\n\nA big thank you to the Go community for making such an amazing language, and to all the developers who inspire simplicity and elegance in code.\n\n---\n\n## ⭐ Star Us!\n\nIf you find `smalldb` useful, give us a star on GitHub! It helps others discover the project and motivates us to keep improving.\n\n---\n\n## 🚀 Let's Keep It Small and Simple!\n\nIn a world full of complexity, `smalldb` is here to remind us that sometimes, less is more. So go ahead—embrace simplicity, write cleaner code, and make your data storage woes a thing of the past!\n\n---\n\nHappy Coding! 🎉","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrazywolf132%2Fsmalldb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrazywolf132%2Fsmalldb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrazywolf132%2Fsmalldb/lists"}