{"id":24430689,"url":"https://github.com/KBismark/cachestorage","last_synced_at":"2025-10-01T01:31:09.610Z","repository":{"id":272696592,"uuid":"917465165","full_name":"KBismark/cache-local-storage","owner":"KBismark","description":"A better way to save data locally on the browser. Think about using the browser's cache system as your local storage in your applications. ","archived":false,"fork":false,"pushed_at":"2025-01-16T03:23:38.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-16T04:29:33.853Z","etag":null,"topics":["cache-storage","javascript","localstorage","typescript","web-development"],"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/KBismark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-01-16T03:17:02.000Z","updated_at":"2025-01-16T03:23:39.000Z","dependencies_parsed_at":"2025-01-16T04:39:37.498Z","dependency_job_id":null,"html_url":"https://github.com/KBismark/cache-local-storage","commit_stats":null,"previous_names":["kbismark/cache-local-storage"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fcache-local-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fcache-local-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fcache-local-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KBismark%2Fcache-local-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KBismark","download_url":"https://codeload.github.com/KBismark/cache-local-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234808936,"owners_count":18890086,"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":["cache-storage","javascript","localstorage","typescript","web-development"],"created_at":"2025-01-20T14:57:32.628Z","updated_at":"2025-10-01T01:31:09.604Z","avatar_url":"https://github.com/KBismark.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/@codigex%2Fcachestorage.svg?icon=si%3Anpm\u0026icon_color=%23f4f0f0)](https://badge.fury.io/js/@codigex%2Fcachestorage)\n[![Downloads](https://img.shields.io/npm/dt/@codigex%2Fcachestorage)](https://www.npmjs.com/package/@codigex%2Fcachestorage)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n# Cache Local Storage\nA better way to save data locally on the browser. Think about using the browser's cache system as your local storage space in your applications.     \n\n\n## Why Cache Local Storage?\nIf browsers can cache resources like images, javascript files, and many more, why not use it to store your application data? \nCache Local Storage is a library that helps you store and retrieve data in the browser's cache system. Compared to local storage or session storage, It has a larger storage capacity and also asynchronous. It also provides features like schema validation, compression, and encryption. No need for server interverntion to cache data, it is all done on the client side. Store, retrieve, update, and delete data with ease. \n\n\nUse Cache Local Storage to store data like user settings, user preferences, user data, and many more. It is a great way to store data that should persist even when the browser is closed.    \n\n\n## Features\n- **Schema Validation**: Validate data before storing it.  *Optional*\n- **Compression**: Compress data before storing it. *Optional*\n- **Encryption**: Encrypt data before storing it. *Optional*\n- **Cache Duration**: Set a duration for how long data should be stored. Defaults to a year.\n- **More Persistent**: Data is stored in the browser's cache system which is more persistent than local storage.\n- **Larger Storage Capacity**:  Set a maximum size for the storage. Defaults to 50MB.   \n \n\n## Installation\n```bash\nnpm install @codigex/cachestorage\n```    \n\n\n## How to use\nFirst, import the library and initialize it with options. Then you can store, retrieve, update, and delete data with ease.    \n\n\n```js\nimport CacheLocalStorage from '@codigex/cachestorage';\n\n// Initialize storage with options\nconst storage = new CacheLocalStorage({\n  maxSize: 100 * 1024 * 1024, // 100MB - Default is 50MB\n  namespace: \"my-app\",\n  cacheDuration: 86400, // 1 day - Default is 1 year\n});\n\n```    \n\n\n### Storing data without schema validation\n\n```js\n\n// Store user data without schema validation\nasync function storeUser(user) {\n    const result = await storage.setItem(user.id, user);\n    if (result.success) {\n        console.log(\"User stored:\", result.data);\n    } else {\n        console.error(\"Storage failed:\", result.error);\n    }\n}\n\n```\n\n### Getting data       \n\n```js\n// Retrieve user data\nasync function getUser(userId) {\n    const result = await storage.getItem(userId);\n    return  result.data || null;\n}\n\n```\n\n### Updating data\nUpdate data in the cache. Uses `setItem` internally.    \n\n```js\n\n// Update fields in user data\nasync function updateUserName(userId, newName) {\n    const result = await storage.updateItem(userId, { name: newName });\n    if (result.success) {\n        console.log(\"User updated:\", result.data);\n    } else {\n        console.error(\"Update failed:\", result.error);\n    }\n}\n\n```\n\n### Check storage stats\nYou can check the storage stats to know how much space is used and how much is available.    \n\n```js\n\n// Check storage stats\nasync function checkStorage() {\n  const stats = await storage.getStats();\n  console.log(`Storage usage: ${stats.percentUsed.toFixed(2)}%`);\n  console.log(`Available: ${(stats.available / 1024 / 1024).toFixed(2)}MB`);\n}\n\n```\n\n### Basic usage\n```js\n\n// Example usage\nasync function example() {\n    const user = {\n        id: \"dXNlcjoxMjM0NTY3ODkw\",\n        name: \"John Doe\",\n        email: \"john@example.com\",\n    };\n\n    await storeUser(user); // Store user data\n\n    const storedUser = await getUser(user.id); // Retrieve user data\n    if (storedUser) {\n        console.log(\"Retrieved user: \", storedUser);\n    }else{\n        console.log(\"No user found\");\n    }\n\n    await updateUserName(user.id, \"James Season\"); // Update user data\n    await checkStorage();\n}\n\n\n```\n\n\n\n## Usage with more advanced features\nYou can use schema validation, compression, and encryption with Cache Local Storage.    \n\n```js\nimport CacheLocalStorage from '@codigex/cachestorage';\n\n// Initialize storage with options\nconst storage = new CacheLocalStorage({\n  maxSize: 100 * 1024 * 1024, // 100MB\n  namespace: \"my-app\",\n  cacheDuration: 86400, // 1 day - Default is 1 year\n  compression: { enabled: true, level: 9 }, // Set compression configs - optional\n  encryptionKey: \"0123456789abcdef0123456789abcdef\", // 32 or 64 bytes key for encryption - optional\n});\n\n\n// Initialize schema for validation - optional\nconst userSchema = {\n    id: {\n        type: \"string\",\n        required: true,\n        validate: (value) =\u003e value.length \u003e 0,\n    },\n    name: {\n        type: \"string\",\n        required: true,\n        validate: (value) =\u003e value.length \u003e 0,\n    },\n    email: {\n        type: \"string\",\n        required: true,\n        validate: (value) =\u003e /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(value),\n    },\n};\n\n// Store user data with schema validation \nasync function storeUser(user) {\n    const result = await storage.setItem(user.id, user, userSchema);\n    if (result.success) {\n        console.log(\"User stored:\", result.data);\n    } else {\n        console.error(\"Storage failed:\", result.error);\n    }\n}\n\n\n// Retrieve user data\nasync function getUser(userId) {\n    const result = await storage.getItem(userId);\n    return  result.data || null;\n}\n\n\n// Update fields in user data\nasync function updateUserName(userId, newName) {\n    const result = await storage.updateItem(userId, { name: newName }, userSchema);\n    if (result.success) {\n        console.log(\"User updated:\", result.data);\n    } else {\n        console.error(\"Update failed:\", result.error);\n    }\n}\n\n\n\nasync function example() {\n    const user = {\n        id: \"dXNlcjoxMjM0NTY3ODkw\",\n        name: \"John Doe\",\n        email: \"john@example.com\",\n    };\n\n    try {\n        await storeUser(user);\n    } catch (error) {\n        console.error(\"Error storing user: \", error);\n    }\n\n    try {\n        const storedUser = await getUser(user.id);\n        if (storedUser) {\n            console.log(\"Retrieved user: \", storedUser);\n        }else{\n            console.log(\"No user found\");\n        }\n    } catch (error) {\n        console.error(\"Error retrieving user: \", error);\n    }\n\n    try {\n        await updateUserName(user.id, \"James Season\");\n    } catch (error) {\n        console.error(\"Error updating user: \", error);\n    }\n}\n\n\nexample();\n\n```\n\n\n\n## API\n### CacheLocalStorage\n- **constructor(options: CacheLocalStorageOptions): CacheLocalStorage** - Initialize Cache Local Storage with options.    \n\n- **setItem(key: string, data: any, schema?: Schema): Promise\u003cStorageResult\u003e** - Store data in cache.    \n    - **key**: string - The key to store the data with.    \n    - **data**: any - The data to store.    \n    - **schema**: Schema - The schema to validate the data with. *Optional*    \n\n- **getItem(key: string): Promise\u003cStorageResult\u003e** - Retrieve data from cache.    \n    - **key**: string - The key to retrieve the data with.    \n\n- **updateItem(key: string, data: any, schema?: Schema): Promise\u003cStorageResult\u003e** - Update data in cache. Uses `setItem` internally.    \n    - **key**: string - The key to update the data with.      \n    - **data**: any - The data to update.    \n    - **schema**: Schema - The schema to validate the data with. *Optional*    \n\n- **removeItem(key: string): Promise\u003cStorageResult\u003e** - Remove data from cache.    \n    - **key**: string - The key to remove the data with.    \n\n- **clear(): Promise\u003cStorageResult\u003e** - Clear all data from cache.    \n\n- **getStats(): Promise\u003cStorageStats\u003e** - Get storage stats.    \n\n- **getCompressionStats(key: string): Promise\u003cCompressionMetaData | null\u003e** - Get compression stats.    \n\n\n\n\n## Limitations\n- **Storage Capacity**: Cache Local Storage is limited by the browser's cache system.     \n\n- **Data Persistence**: Browser cache can be cleared by the user or the browser.    \n\n- **Data Security**: Data stored in the browser cache is not secure. It is recommended not to store anything sensitive on the user browser. However, if you still do, then enable encryption.    \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKBismark%2Fcachestorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKBismark%2Fcachestorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKBismark%2Fcachestorage/lists"}