{"id":26297004,"url":"https://github.com/ahmedalatawi/browser-storage-utilities","last_synced_at":"2026-02-12T05:35:00.094Z","repository":{"id":104203652,"uuid":"258868148","full_name":"ahmedalatawi/Browser-Storage-Utilities","owner":"ahmedalatawi","description":"A front-end library that provides utility methods to facilitate CRUD operations to data stored in the browser, and more!","archived":false,"fork":false,"pushed_at":"2022-06-26T07:04:24.000Z","size":110,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-09T12:09:01.927Z","etag":null,"topics":["angular","browser","browser-storage","chrome","firefox","ie","javascript","localstorage","npm","npm-module","npm-package","package-json","prototype","react","safari","sessionstorage","stackblitz","storage","typescript","vue"],"latest_commit_sha":null,"homepage":"https://stackblitz.com/edit/angular-storage-utilities-example","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/ahmedalatawi.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":"2020-04-25T20:30:56.000Z","updated_at":"2023-12-18T02:40:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb25dbfd-833d-42fc-b749-41827bdb3744","html_url":"https://github.com/ahmedalatawi/Browser-Storage-Utilities","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmedalatawi%2FBrowser-Storage-Utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmedalatawi%2FBrowser-Storage-Utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmedalatawi%2FBrowser-Storage-Utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahmedalatawi%2FBrowser-Storage-Utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahmedalatawi","download_url":"https://codeload.github.com/ahmedalatawi/Browser-Storage-Utilities/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253248454,"owners_count":21877905,"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":["angular","browser","browser-storage","chrome","firefox","ie","javascript","localstorage","npm","npm-module","npm-package","package-json","prototype","react","safari","sessionstorage","stackblitz","storage","typescript","vue"],"created_at":"2025-03-15T05:20:13.858Z","updated_at":"2026-02-12T05:35:00.064Z","avatar_url":"https://github.com/ahmedalatawi.png","language":"TypeScript","funding_links":["https://paypal.me/ahmedalatawi?locale.x=en_US"],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/AhmedAlatawi/Browser-Storage-Utilities.svg?branch=master)](https://travis-ci.org/AhmedAlatawi/Browser-Storage-Utilities)\n[![Coverage Status](https://coveralls.io/repos/github/AhmedAlatawi/Browser-Storage-Utilities/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/AhmedAlatawi/Browser-Storage-Utilities?branch=master\u0026service=github)\n[![npm version](https://badge.fury.io/js/browser-storage-utilities.svg)](https://badge.fury.io/js/browser-storage-utilities)\n[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/AhmedAlatawi/Browser-Storage-Utilities/issues)\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://paypal.me/ahmedalatawi?locale.x=en_US)\n\n### [Live example in Angular](https://stackblitz.com/edit/angular-storage-utilities-example) :movie_camera:\n\n## Browser Storage Utilities :hammer_and_pick:\n\n:fire: StorageUtilities is a front-end library that provides handy methods to facilitate CRUD operations to data stored in the browser. It also allows global/class level settings to easily, and consistently, manage the state of the stored data. \n\nStorageUtilities provides optional expiry/TTL (Time To Live) functionality to allow temporary data storage. It also allows subscribers to be notified of any state changes to stored data.\n\nThe internal implementation relys on the web storage objects `localStorage` and `sessionStorage`, as well as the methods they provide `setItem/getItem/removeItem/clear`\n\n### :pencil2: Key Goals\n* Simplify CRUD operations to stored data in `localStorage` \u0026 `sessionStorage`\n* Allow global/class level settings for consistency \n* Support expiry/TTL (Time To Live) feature\n* Provide state change notifications to subscribers\n* Can be easily used in any front-end JavaScript codebase application\n\n### :arrow_down: Installation \n```sh\nnpm install browser-storage-utilities --save\n```\n### Usage :bulb:\n### TypeScript\n```typescript\nimport { StorageUtilities } from 'browser-storage-utilities';\n\nexport class UserStorageService extends StorageUtilities \u003cUser\u003e {\n    ...\n\n    constructor() {\n        super({ /* global settings (optional) */ });\n    }\n\n}\n```\n### The settings interface :checkered_flag:\n```typescript\nexport interface IStorageSettings {\n    keyPrefix? : string; // prefixes all items' keys prior to being stored, e.g. 'user-'\n    type? : StorageTypes; // localStorage (default) / sessionStorage\n    setExpiryMilliseconds? : number; // time to live (TTL), e.g. 5000ms\n    setReturnType? : StorageReturnTypes; // the item(s) to be returned as a Promise or Observable\n    notifiedOfStateChanges? : boolean; // for subscriber(s) to be notified of any storage state changes\n}\n```\n**Note: :bulb:** Some of these settings **(type, setExpiryMilliseconds, and setReturnType)** can be applied per method as well, which always take precedence over global settings:\n ```typescript\n // set globally\n...\nconstructor() {\n    super({ keyPrefix: 'user-', setExpiryMilliseconds: 5000, notifiedOfStateChanges: true, setReturnType: StorageReturnTypes.Promise, type: StorageTypes.SESSION });\n...\n\n// set per method\nthis.userStorageService.addUser('123', user, 5000, StorageTypes.SESSION);\n\n// return item\nconst storedUser = this.userStorageService.getUser('123', StorageTypes.SESSION);\nconsole.log('storedUser: ', storedUser); // user data\n\n// return item as a Promise\nconst storedUserPromise = this.userStorageService.getUser('123', StorageTypes.SESSION, StorageReturnTypes.Promise);\n\nstoredUserPromise.then(user =\u003e {\n   console.log('user: ', user); //user data\n})\n```\n\n### Default settings :pushpin:\n```typescript\nexport const defaultSettings: IStorageSettings = {\n    keyPrefix: '',\n    type: StorageTypes.LOCAL // set to localStorage by default\n};\n```\n### Example :rocket:\n```typescript\nimport { StorageUtilities, StorageTypes } from 'browser-storage-utilities';\n\nexport class UserStorageService extends StorageUtilities \u003cUser\u003e {\n\n    constructor() {\n        super({ keyPrefix: 'user-', notifiedOfStateChanges: true, type: StorageTypes.SESSION });\n    }\n\n    addUser(id: string, user: User, expiry? : number, storageType? : StorageTypes): void {\n        this.addItem(id, user, expiry, storageType);\n    }\n\n    getUser(id: string, storageType? : StorageTypes): User {\n        return this.getItem(id, storageType);\n    }\n\n    updateUserProperty(id: string, propName: string, newValue: any, storageType ? : StorageTypes): User {\n        return this.updateItemProperty(id, propName, newValue, storageType);\n    }\n\n    removeUserProperty(id: string, propName: string, storageType? : StorageTypes): User {\n        return this.updateItemProperty(id, propName, newValue, storageType);\n    }\n\n    removeUser(id: string, storageType? : StorageTypes): void {\n        this.removeItem(id, storageType);\n    }\n\n    removeUsers(ids: string[], storageType? : StorageTypes): void {\n        this.removeItems(ids, storageType);\n    }\n\n}\n```\n\n### Subscribe to storage state changes :dart:\n```typescript\nimport { IStorageNotifier } from 'browser-storage-utilities';\n\n...\n\nthis.userStorageService.storageStateChanged.subscribe((userData: IStorageNotifier \u003cUser\u003e ) =\u003e {\n    if (userData) {\n        console.log('storage: ', userData.storage); // localStorage or sessionStorage\n        console.log('oldValue: ', userData.oldValue); // previous data\n        console.log('newValue: ', userData.newValue); // current data\n    }\n});\n```\n### Store data with a 5 second expiry (TTL) :hourglass_flowing_sand:\n```typescript\n...\n\nthis.userStorageService.addUser('123', user, 5000);\n/* \nlocalStorage: {\n  expiry: 1590853867699,\n  value: {\n    id: '123',\n    firstName: 'John',\n    lastName: 'Doe',\n    ...\n  }\n}\n*/\n\n// if expiry time has elapsed, item is removed from storage, and null will be returned.\nconst storedUser = this.userStorageService.getUser('123');\n\nconsole.log('storedUser: ', storedUser); // null\n```\n\n### :page_facing_up: Settings API\n\n| Methods | Description |\n| --- | --- |\n| `static get defaultSettings(): IStorageSettings` | Returns default settings applied to StorageUtilities | \n| `static get currentSettings(): IStorageSettings` | Returns current settings applied to StorageUtilities |\n| `static set customSettings(settings: IStorageSettings)` | Sets custom settings to be applied to StorageUtilities. They will always overwrite default settings |\n| `static resetSettings(): void` | Resets to default settings applied to StorageUtilities |\n\n### :page_facing_up: Core methods API\n\n| Methods | Description |\n| --- | --- |\n`addItem(key: string, item: T, expiry?: number, storageType?: StorageTypes): void` | Adds the item to Storage with its key. The item is added to `localStorage` by default, or `sessionStorage` if specified by `@param storageType`. The item can be added with an expiry time (in milliseconds). This is to add a TTL (Time to live) to invalidate item after the expiry time elapses. \n| `getItem(key: string, storageType?: StorageTypes, returnType?: StorageReturnTypes): T` | Returns the item stored in Storage by its key. If item is not found, or it has an expiry time which has elapsed, `null` will be returned. The item can be returned as a `Promise` or `Observable` if `@param returnType` is specified. The item is returned from `localStorage` by default, or `sessionStorage` as specified by `@param storageType`. \n| `updateItemProperty(key: string, propName: string, newValue: any, storageType?: StorageTypes): T` | Updates the value of a specific property for the stored item. The property can be of any type. If the property doesn't exist, a new property will be created. If the item is not found by key, or has expired, `null` will be returned, or updated item will be returned otherwise.\n| `removeItemProperty(key: string, propName: string, storageType?: StorageTypes): T` | Removes the item's specified property. If the item is not found by key, or has expired, `null` will be returned, or updated item will be returned otherwise. \n| `removeItem(key: string, storageType?: StorageTypes): void` | Removes item from Storage by its key. The item is removed from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`.\n| `removeItems(keys: string[], storageType?: StorageTypes): void` | Removes items from Storage by their keys. The items are removed from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`.\n| `clearStorage(storageType?: StorageTypes): void` | Removes all items from storage. The items are removed from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`. |\n\n### :page_facing_up: Additional methods API\n| Methods | Description |\n| --- | --- |\n| `getStorageState(): Observable\u003cIStorageNotifier\u003cT\u003e\u003e` | Returns storage state as an `Observable` of type `IStorageNotifier\u003cT\u003e`. All subscribers will be notified when state changes. | \n| `getStorageItems(storageType?: StorageTypes, returnType?: StorageReturnTypes): StorageItem\u003cT\u003e[]` | Returns an `Array` of all storage items. The items are returned from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`. The items can be returned as a `Promise` or `Observable` if `@param returnType` is specified. |\n| `getStorageValues(storageType?: StorageTypes, returnType?: StorageReturnTypes): T[]` | Returns an `Array` of all storage values. The values are returned from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`. The values can be returned as a `Promise` or `Observable` if `@param returnType` is specified. |\n| `getStorageKeys(storageType?: StorageTypes, returnType?: StorageReturnTypes): string[]` | Returns an `Array` of all storage keys. The keys are returned from `localStorage` by default, or `sessionStorage` if specified by `@param storageType`. The keys can be returned as a `Promise` or `Observable` if `@param returnType` is specified. |\n\n### Author :books:\n[Ahmed Alatawi](https://github.com/AhmedAlatawi)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmedalatawi%2Fbrowser-storage-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahmedalatawi%2Fbrowser-storage-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahmedalatawi%2Fbrowser-storage-utilities/lists"}