{"id":24158158,"url":"https://github.com/darkguy2008/h5webstorage-ngx","last_synced_at":"2025-03-02T01:26:51.102Z","repository":{"id":57260054,"uuid":"329431869","full_name":"darkguy2008/h5webstorage-ngx","owner":"darkguy2008","description":"HTML5 WebStorage API for Angular 11+","archived":false,"fork":false,"pushed_at":"2021-01-13T21:50:27.000Z","size":167,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-12T14:19:51.311Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/darkguy2008.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}},"created_at":"2021-01-13T21:07:51.000Z","updated_at":"2021-01-13T21:50:29.000Z","dependencies_parsed_at":"2022-08-25T02:41:39.166Z","dependency_job_id":null,"html_url":"https://github.com/darkguy2008/h5webstorage-ngx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkguy2008%2Fh5webstorage-ngx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkguy2008%2Fh5webstorage-ngx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkguy2008%2Fh5webstorage-ngx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkguy2008%2Fh5webstorage-ngx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkguy2008","download_url":"https://codeload.github.com/darkguy2008/h5webstorage-ngx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241446205,"owners_count":19964136,"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":[],"created_at":"2025-01-12T14:19:53.833Z","updated_at":"2025-03-02T01:26:51.077Z","avatar_url":"https://github.com/darkguy2008.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# h5webstorage-ngx\n\nThis is a library I forked from https://github.com/SirDarquan/h5webstorage to make it work on the latest Angular versions. For some reason, when I forked and built it as-is, the differences between the old Angular compiler it was using and the newest one as of date (v11) made it crash when looking for an \"id\" property to be returned when calling the modules from the `imports` section inside the main ngModule.\n\nPlus, I also wanted to fix a couple bugs. Most notably, one of the bugs I wanted to fix was that when setting a variable as undefined (to delete/erase it) it wasn't removing it from the Local Storage, so I patched that as well. Now, when you set one of the variables denoted with @StorageProperty as undefined, they'll be cleared from the storage.\n\nThis is the first library I fork and publish, so sorry there's no testing (I dislike TDD) or other similar stuff. Hey, it works and it has a custom patch, that's enough for me. Don't expect much maintenance, but the original library didn't have much anyways, so up to you.\n\nOriginal README.md files below:\n\n---\n\nThis library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 11.0.6.\n\n## Code scaffolding\n\nRun `ng generate component component-name --project h5webstorage-ngx` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project h5webstorage-ngx`.\n\u003e Note: Don't forget to add `--project h5webstorage-ngx` or else it will be added to the default project in your `angular.json` file. \n\n## Build\n\nRun `ng build h5webstorage-ngx` to build the project. The build artifacts will be stored in the `dist/` directory.\n\n## Publishing\n\nAfter building your library with `ng build h5webstorage-ngx`, go to the dist folder `cd dist/h5webstorage-ngx` and run `npm publish`.\n\n## Running unit tests\n\nRun `ng test h5webstorage-ngx` to execute the unit tests via [Karma](https://karma-runner.github.io).\n\n## Further help\n\nTo get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.\n\n---\n\n# Original h5webstorage's README.md below\n\n# h5webstorage [![npm version][]][nvl] [![Build Status][]][bsl] [![Test Coverage][]][tcl] [![Code Climate][]][ccl] \n#### Html5 WebStorage API for Angular2\n[![Sauce Test Status](https://saucelabs.com/browser-matrix/SirDarquan.svg)](https://saucelabs.com/u/SirDarquan)\n- [Use](#use)\n- [Overview](#overview)\n  - [LocalStorage](#localstorage) (service)\n  - [SessionStorage](#sessionstorage) (service)\n  - [@StorageProperty](#storageproperty) (decorator)\n  - [ConfigureStorage](#configurestorage) (function)\n  \n## Use\n1. Download the library:\n\n  `npm install h5webstorage --save`\t\n2.  Import the module and the providers into your top level module:\n\n  ```typescript\n\timport {WebStorageModule} from \"h5webstorage\";\n  ```\n3. Register the module:\n\n  ```typescript\n\t@NgModule({\n\t\t...\n\t\timports:[WebStorageModule.forRoot()],\n\t})\n  ```\n4. Inject the service into your class and use:\n\n  ```typescript\n\timport {LocalStorage, StorageProperty} from 'h5webstorage';\n\t@Component({})\n\tclass MyComponent{\n\t\t@StorageProperty() public SomeValue: string = null;\t//This will expose a specific value in localStorage as property of this class\n\t\tconstructor(private localStorage: LocalStorage){\n\t\t\t...\t\n\t\t}\n\t}\n  ```\n\t\t\n## Overview\nThe [angular2-localStorage][] project is what inspired this project with\nits use of a decorator to access the values in the storage area. \nUnfortunately, the implementation was difficult to test do to the use of\nhard references to static classes. The intention of this project was to \ndetermine if a higly testable version of webstorage access was possible.\n\nThere is an example application that shows the various ways to use the \nwebstorage APIs but overall the classes were designed to work just like\nthe native storage objects. In fact, the `BaseStorage` object implements\nthe Storage interface to give it nearly one-to-one compatibility. The \nLocalStorage/SessionStorage objects were meant to be used as you would the native\nlocalStorage/sessionStorage objects. Here's a quick example:\n```typescript\n\tconstructor(private localStorage: LocalStorage){\n\t\tthis.localStorage[\"firstKey\"] = \"This value will appear in storage\";\n\t\tthis.localStorage.setItem(\"secondKey\", \"This will also\");\n\t\tvar retrieved = this.localStorage[\"storedKey\"]; //if there is a value in storage it would be retrieved\n\t\tconsole.log(retrieved); \t\n\t}\n```\nThere is one minor exception: Native storage objects can use a number index\nwhile the wrappers can't. I've never actually seen them used this way so I\ncan't imagine it's a widely used feature and I'm OK with that missing piece.\n\nFinally, the storage objects are bound both ways, so if a change occurs in\nstorage, the WebStorage objects receives the change and the application is\nimmediately updated.\n \n\n### LocalStorage\nThe `LocalStorage` object is the service that uses the [localStorage][] object\nas its backing. To keep the library testable, the native localStorage object\nis injected. Normally this would mean importing two items from the library\nand placing them both in the providers array which you can do if you \nwant to but to simplify this common scenario, the `LOCAL_STORAGE_PORVIDER`\nwas created which does this job for you.\n\n### SessionStorage\nThe `SessionStorage` object is just like the `LocalStorage` object except\nfor using the native [sessionStorage][] object for backing. There is also a\n`SESSION_STORAGE_PROVIDER` to simplify registration.\n\n### @StorageProperty\n`StorageProperty` is a decorator used to simplifiy access to the stored values.\nIt accepts an object with the following properties:\n- __storageKey {string}__: an alternate name for the key in storage\n- __storage {'Local'|'Session'}__: a string that determines which backing to associate the field with.\n\tLocal is the default\n- __readOnly {boolean}__: specifies if the property allows writes. Default is false;\n\n**Note**: In order to use the `@StorageProperty` decorator, you **MUST**\ninject the storage service and make it a field of the class. Here an \nexample showing the scenario this library was best designed for: creating a \nstrongly typed representation of your storage.\n```typescript\n\timport {LocalStorage} from 'h5webstorage';\n\t@Injectable()\n\tclass MyStorageService{\n\t\t@StorageProperty() public SomeValue: string = null;\t//This will expose a specific value in localStorage as a property of this class\n\t\t@StorageProperty({ storageKey: 'storageName', storage: 'Session'}) public FriendlyName: string = null;\t//This will expose the 'storageName' value in sessionStorage as the 'FriendlyName' property\n\t\t@StorageProperty({readOnly: true}) public Manager: string; // Since it is readonly and initialization value isn't necessary\n\t\tconstructor(private localStorage: LocalStorage, sessionStorage: SessionStorage){\t//notice LocalStorage and SessionStorage is injected even though they aren't used directly\n\t\t\t...\t\n\t\t}\n\t}\n```\nThe `@StorageProperty` decorator syncs the stored value automatically and will even be updated is the value in storage is changed by \nanother source (like through DevTools or the same app in a different tab). That type of change will also cause a change detection to\noccur, so if the property is bound to a template, the updated value will be visible immediately. You can also do calculations on it in\nthe ngOnChanges method.\nBe aware that in essence, the property __IS__ the value in storage. So if the value is an object and properties are referenced in code, \ndeleting the stored value is like setting a variable to null and exceptions can occur.\n\n### ConfigureStorage\nThe `ConfigureStorage` function creates a provider which allows you to \ninject configuration options for the storage object(s) to be used. \nOne thing to remember is that the ConfigureStorage provider will only \ninject into new instances of LocalStorage/SessionStorage. So if you inject \n`LocalStorage` into the root component and only provide `ConfigureStorage`\nin a sub-component, it will never be used. But inversely, if the Root\ncomponent contains the `ConfigureStorage` provider, then all sub-components\nthat inject `LocalStorage`/`SessionStorage` will have the options configured.\nHere's an example of `ConfigureStorage` being used:\n```typescript\nimport {ConfigureStorage} from \"h5webstorage\";\n@Component({\n\tproviders:[ConfigureStorage({ prefix: \"myPrefix-\" })]\t\n})\nclass myClass{}\n```\n\n#### - prefix\nThe storage key prefix has some handy uses. With the angular2\ninjector hierarchy, the root component can inject a LocalStorage object\nthat can 'see' all the available keys. Then a sub-component can inject\nanother LocalStorage object that can only see keys that start with a\nspecific prefix. This technique is used in the example app included to\nallow use to have multiple to do lists.\n\n#### - serializeOnException\nThe h5webstorage library expects to control the localStorage and sessionStorage \nobjects completely and idealy, that meansany values ever stored was done so by \nthe library. In reality, that's not always the case. There may be values from a\nprevious implementation before h5webstorage began to be used and the format of\nthose values may not be compatible. By default, the library resets those values\nto null to start clean but that may not always be the desireable result.\nThis property aims to help ease these types of transitions. For example, if \nyour previous implementation generally used string and integer values, the\nintegers will load without a problem using the default transformer but if the\nstrings don't have quotes around them they will not load. All that is actually\nneeded at this point is to have that value serialized and it can then be used as-is.\n\nThis property can be used in conjunction with a custom transformer to load data \nexactly the way you want. But with more power comes more responibility, so be\ncautious.  \n\n### Providers\nThis library was designed with great configurability in mind but that normally \ncomes at the price of simplicity. Fortunately, [angular2][]'s injector system\nallows us to make some shortcuts.\n\n#### LOCAL_STORAGE_OBJECT and SESSION_STORAGE_OBJECT\nThese are the tokens used to inject the `localStorage` and `sessionStorage` native objects into\nthe `LocalStorage` and `SessionStorage` objects respectivly. Using this, it is possible to have \n`LocalStorage` and `SessionStorage` store its data in other places like for a cookie fallback.\n\n#### SERDES_OBJECT\nThis is the SERializer/DESerializer object used to transform the values between storage and memory. By\ndefault, this is the [JSON][] object in the browser but can be replaced by pretty much anything. There\nare two (2) methods that must be implemented: stringify and parse. This can be used to have a transparent\nencryption layer for the stored values or whatever.   \n\n## Testing\nTestability was the reason this library was built in the first place. Not only is testing the library\nitself easy because of its modularity, testing an application that uses the library is just as simple.\nHere's an example using Jasmine:\n```typescript\ndescribe(\"My test suite\", ()=\u003e{\n\n\tbeforeEach(()=\u003e{\n\t\tTestBed.configureTestingModule({\n\t\t\tproviders:[\n\t\t\t\t{provide: LOCAL_STORAGE_OBJECT, useValue: {\"myVariable\": \"something\"}},\n\t\t\t\tLocalStorage,\n\t\t\t\tMyClass\n\t\t\t]\n\t\t})\n\t})\n\tit(\"should set myVariable\", inject([MyClass, LocalStorage],(sut: MyClass, ls: LocalStorage)=\u003e{\n\t\texpect(ls[\"myVariable\"]).toBe('something');\n\t\tsut.doSomething();\n\t\texpect(ls[\"myVariable\"]).toBe('something else');\n\t}); \n});\n``` \nWith the example above, you can verify that the logic of the class places the correct value in storage\nor performs the correct actions based on what it finds in storage.\n\n## Angular-CLI, AOT and Universal\nWith the tooling update, h5webstorage is fully angular-cli compliant and can be used in AOT scenarions,\nunlike the previous iterations. In theory, h5webstorage can also be used in Angular Universal scenarios\nas well but until there is a confirmed case of someone needing to do this, it'll remain a theory. \n\n\n[angular2-localStorage]: https://github.com/marcj/angular2-localStorage\n[localStorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage\n[sessionStorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage\n[Test Coverage]: https://codeclimate.com/github/SirDarquan/h5webstorage/badges/coverage.svg\n[tcl]: https://codeclimate.com/github/SirDarquan/h5webstorage/coverage\n[Build Status]: https://travis-ci.org/SirDarquan/h5webstorage.svg?branch=master\n[bsl]: https://travis-ci.org/SirDarquan/h5webstorage\n[Code Climate]: https://codeclimate.com/github/SirDarquan/h5webstorage/badges/gpa.svg\n[ccl]: https://codeclimate.com/github/SirDarquan/h5webstorage\n[angular2]: https://angular.io\n[angular universal]: https://universal.angular.io/\n[JSON]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON\n[nvl]: https://www.npmjs.com/package/h5webstorage\n[npm version]: https://badge.fury.io/js/h5webstorage.svg","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkguy2008%2Fh5webstorage-ngx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkguy2008%2Fh5webstorage-ngx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkguy2008%2Fh5webstorage-ngx/lists"}