{"id":24818936,"url":"https://github.com/ganesh-sharmaz/storagebuddy","last_synced_at":"2025-04-12T00:53:16.169Z","repository":{"id":280878437,"uuid":"943469810","full_name":"Ganesh-Sharmaz/StorageBuddy","owner":"Ganesh-Sharmaz","description":"StorageBuddy- A simple and powerful React library written in TypeScript to manage LocalStorage, SessionStorage, and Cookies with a single, easy-to-use API. Save, retrieve, and clear data seamlessly in your web apps! 🚀 #React #JavaScript #TypeScript #WebStorage #Cookies","archived":false,"fork":false,"pushed_at":"2025-03-06T16:24:54.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-12T00:52:58.005Z","etag":null,"topics":["browser-storage","cookies","data-persistence","developer-tools","frontend-library","localstorage","react-library","sessionstorage","storage-management","typescript","typescript-project"],"latest_commit_sha":null,"homepage":"","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/Ganesh-Sharmaz.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":"2025-03-05T18:54:57.000Z","updated_at":"2025-03-09T19:24:44.000Z","dependencies_parsed_at":"2025-03-05T20:20:20.433Z","dependency_job_id":"493a3736-0947-4d6e-ba8d-f2ad616dd66a","html_url":"https://github.com/Ganesh-Sharmaz/StorageBuddy","commit_stats":null,"previous_names":["ganesh-sharmaz/storagebuddy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ganesh-Sharmaz%2FStorageBuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ganesh-Sharmaz%2FStorageBuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ganesh-Sharmaz%2FStorageBuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ganesh-Sharmaz%2FStorageBuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ganesh-Sharmaz","download_url":"https://codeload.github.com/Ganesh-Sharmaz/StorageBuddy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501882,"owners_count":21114682,"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":["browser-storage","cookies","data-persistence","developer-tools","frontend-library","localstorage","react-library","sessionstorage","storage-management","typescript","typescript-project"],"created_at":"2025-01-30T17:55:26.641Z","updated_at":"2025-04-12T00:53:16.150Z","avatar_url":"https://github.com/Ganesh-Sharmaz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StorageBuddy\n\n![npm](https://img.shields.io/npm/v/storagebuddy)\n![Bundle Size](https://img.shields.io/bundlephobia/minzip/storagebuddy)\n![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n\u003e A lightweight, zero-dependency TypeScript library that provides a unified API for managing browser storage mechanisms.\n\nStorageBuddy simplifies working with `localStorage`, `sessionStorage`, and `cookies` through a single, intuitive interface. It handles all the complexity of data serialization, storage management, and expiration handling so you can focus on building your application.\n\n## ✨ Highlights\n\n- **Unified API** - Consistent methods across all storage types\n- **Type Safety** - Full TypeScript support with generic type inference\n- **Automatic JSON Handling** - No manual parsing or stringifying\n- **Zero Dependencies** - Lightweight and bloat-free\n- **Browser-Optimized** - Designed for client-side applications\n\n## 📦 Installation\n\nChoose your preferred package manager:\n\n```bash\n# npm\nnpm install storagebuddy\n\n# yarn\nyarn add storagebuddy\n\n# pnpm\npnpm add storagebuddy\n```\n\n## 🚀 Quick Start\n\n```typescript\nimport useStash from \"storagebuddy\";\n\n// Initialize StorageBuddy\nconst stash = useStash();\n\n// Store data in different storage types\nstash.set(\"local\", \"user\", { name: \"Ganesh Sharma\", age: 23 });\nstash.set(\"session\", \"theme\", \"dark\");\nstash.set(\"cookie\", \"token\", \"123abc\", 7); // Expires in 7 days\n\n// Retrieve data with type safety\nconst user = stash.get\u003c{ name: string; age: number }\u003e(\"local\", \"user\");\nconsole.log(user.name); // \"Ganesh Sharma\"\n\n// Remove specific items\nstash.remove(\"session\", \"theme\");\n\n// Clear all data for a storage type\nstash.clear(\"local\");\n```\n\n## 📖 Detailed Usage Guide\n\n### Storage Types\n\nStorageBuddy supports three storage mechanisms:\n\n- `\"local\"` - Uses `localStorage` (persists across browser sessions)\n- `\"session\"` - Uses `sessionStorage` (persists until browser/tab is closed)\n- `\"cookie\"` - Uses document cookies (configurable expiration)\n\n### Setting Values\n\n```typescript\n// Basic usage\nstash.set(\"local\", \"username\", \"ganesh\");\n\n// Store complex objects (automatically serialized)\nstash.set(\"local\", \"settings\", {\n  darkMode: true,\n  fontSize: 16,\n  notifications: {\n    email: true,\n    push: false\n  }\n});\n\n// Store in session storage\nstash.set(\"session\", \"currentPage\", \"/dashboard\");\n\n// Store cookies with expiration (in days)\nstash.set(\"cookie\", \"auth\", \"token123\", 7); // Expires in 7 days\nstash.set(\"cookie\", \"visitor\", \"true\", 365); // Expires in 1 year\nstash.set(\"cookie\", \"popup\", \"seen\", 0.5); // Expires in 12 hours\n```\n\n### Retrieving Values\n\n```typescript\n// Basic retrieval\nconst username = stash.get\u003cstring\u003e(\"local\", \"username\");\n\n// Retrieve with type safety for complex objects\ninterface UserSettings {\n  darkMode: boolean;\n  fontSize: number;\n  notifications: {\n    email: boolean;\n    push: boolean;\n  };\n}\n\nconst settings = stash.get\u003cUserSettings\u003e(\"local\", \"settings\");\nconsole.log(settings.darkMode); // true\nconsole.log(settings.notifications.email); // true\n\n// Retrieve from different storage types\nconst currentPage = stash.get\u003cstring\u003e(\"session\", \"currentPage\");\nconst authToken = stash.get\u003cstring\u003e(\"cookie\", \"auth\");\n\n// Handling non-existent values (returns null)\nconst nonExistent = stash.get(\"local\", \"nonExistentKey\");\nif (nonExistent === null) {\n  console.log(\"Value doesn't exist\");\n}\n```\n\n### Removing Values\n\n```typescript\n// Remove a single item\nstash.remove(\"local\", \"username\");\nstash.remove(\"session\", \"currentPage\");\nstash.remove(\"cookie\", \"auth\");\n```\n\n### Clearing Storage\n\n```typescript\n// Clear all localStorage items\nstash.clear(\"local\");\n\n// Clear all sessionStorage items\nstash.clear(\"session\");\n\n// Clear all cookies\nstash.clear(\"cookie\");\n```\n\n## 🛠️ API Reference\n\n### `useStash()`\n\nCreates a new StorageBuddy instance.\n\n**Returns**: StorageBuddy instance with the following methods:\n\n### `set(type, key, value, expiryDays?)`\n\nStores a value in the specified storage type.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `type` | `\"local\"` \\| `\"session\"` \\| `\"cookie\"` | Storage mechanism to use |\n| `key` | `string` | Key to store the value under |\n| `value` | `any` | Value to store (automatically serialized) |\n| `expiryDays` | `number` (optional) | Days until expiration (cookies only) |\n\n**Returns**: `void`\n\n### `get\u003cT\u003e(type, key)`\n\nRetrieves a value from the specified storage type.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `type` | `\"local\"` \\| `\"session\"` \\| `\"cookie\"` | Storage mechanism to use |\n| `key` | `string` | Key to retrieve |\n\n**Returns**: `T | null` - The stored value (parsed if JSON) or null if not found\n\n### `remove(type, key)`\n\nRemoves a value from the specified storage type.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `type` | `\"local\"` \\| `\"session\"` \\| `\"cookie\"` | Storage mechanism to use |\n| `key` | `string` | Key to remove |\n\n**Returns**: `void`\n\n### `clear(type)`\n\nClears all values from the specified storage type.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `type` | `\"local\"` \\| `\"session\"` \\| `\"cookie\"` | Storage mechanism to clear |\n\n**Returns**: `void`\n\n## 🧪 Advanced Usage\n\n### Type Safety with TypeScript\n\nStorageBuddy works seamlessly with TypeScript to provide type safety:\n\n```typescript\n// Define your types\ninterface User {\n  id: number;\n  name: string;\n  roles: string[];\n}\n\n// Type-safe storage and retrieval\nstash.set(\"local\", \"currentUser\", {\n  id: 123,\n  name: \"Ganesh\",\n  roles: [\"admin\", \"developer\"]\n} as User);\n\nconst user = stash.get\u003cUser\u003e(\"local\", \"currentUser\");\n// User is now fully typed\nconsole.log(user?.roles.includes(\"admin\")); // true\n```\n\n### Browser Compatibility\n\nStorageBuddy works in all modern browsers:\n\n| Browser | Version |\n|---------|---------|\n| Chrome | 42+ |\n| Firefox | 38+ |\n| Safari | 9+ |\n| Edge | 12+ |\n| Opera | 29+ |\n\n### Error Handling\n\nStorageBuddy includes built-in error handling:\n\n```typescript\ntry {\n  const result = stash.get(\"local\", \"complexData\");\n  // Use result\n} catch (error) {\n  console.error(\"Storage operation failed:\", error);\n}\n```\n\n## 🎯 Use Cases\n\n### User Preferences\n\n```typescript\n// Save user preferences\nstash.set(\"local\", \"preferences\", {\n  theme: \"dark\",\n  fontSize: \"medium\",\n  notifications: true\n});\n\n// Retrieve preferences when needed\nconst prefs = stash.get(\"local\", \"preferences\");\napplyTheme(prefs.theme);\n```\n\n### Authentication\n\n```typescript\n// Store auth token as a cookie with expiration\nfunction login(username, password) {\n  // Authenticate with API...\n  const token = \"jwt-token-from-server\";\n  stash.set(\"cookie\", \"authToken\", token, 7); // Expires in 7 days\n}\n\n// Check if user is logged in\nfunction isLoggedIn() {\n  return stash.get(\"cookie\", \"authToken\") !== null;\n}\n\n// Logout\nfunction logout() {\n  stash.remove(\"cookie\", \"authToken\");\n}\n```\n\n### Form Persistence\n\n```typescript\n// Save form data as user types\nformElement.addEventListener(\"input\", (e) =\u003e {\n  const formData = getFormValues();\n  stash.set(\"session\", \"draftForm\", formData);\n});\n\n// Restore form data when page loads\nwindow.addEventListener(\"load\", () =\u003e {\n  const savedForm = stash.get(\"session\", \"draftForm\");\n  if (savedForm) {\n    populateForm(savedForm);\n  }\n});\n```\n\n## 🔮 Roadmap\n\nStorageBuddy is actively maintained, with the following features planned:\n\n1. **🔐 Encryption Support**\n   - Add optional encryption for sensitive data\n   - AES-256 encryption for secure storage\n\n2. **📡 Storage Event Listeners**\n   - Support for listening to storage changes across tabs\n   - Custom event system for real-time updates\n\n3. **⏱️ Advanced Expiration Options**\n   - Custom expiration units (hours, minutes, seconds)\n   - Support for absolute expiration timestamps\n\n4. **🧰 Storage Utilities**\n   - Batch operations for improved performance\n   - Storage quota management and monitoring\n\n5. **🧩 Plugin System**\n   - Extensible architecture for custom storage adapters\n   - Support for third-party storage mechanisms\n\n## 🤝 Contributing\n\nContributions are always welcome! Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\nPlease make sure to update tests as appropriate and adhere to the code style.\n\n## 📜 License\n\nStorageBuddy is [MIT licensed](LICENSE).\n\n## 💬 Community \u0026 Support\n\n- **GitHub Issues**: Report bugs or request features\n- **Twitter**: Follow [@GaneshSharma](https://x.com/Ganesh_Sharmazz) for updates\n- **Discord**: Join our [community channel](https://discord.gg/channel)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with ❤️ by \u003ca href=\"https://github.com/Ganesh_Sharmaz\"\u003eGanesh Sharma\u003c/a\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fganesh-sharmaz%2Fstoragebuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fganesh-sharmaz%2Fstoragebuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fganesh-sharmaz%2Fstoragebuddy/lists"}