https://github.com/jelhan/ember-local-storage-decorator
Decorator for Ember.js to read and persist data in localStorage
https://github.com/jelhan/ember-local-storage-decorator
ember ember-addon hacktoberfest
Last synced: 7 months ago
JSON representation
Decorator for Ember.js to read and persist data in localStorage
- Host: GitHub
- URL: https://github.com/jelhan/ember-local-storage-decorator
- Owner: jelhan
- License: mit
- Created: 2020-12-22T16:32:22.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2025-04-01T11:27:19.000Z (8 months ago)
- Last Synced: 2025-04-28T21:58:14.811Z (7 months ago)
- Topics: ember, ember-addon, hacktoberfest
- Language: JavaScript
- Homepage:
- Size: 585 KB
- Stars: 23
- Watchers: 2
- Forks: 3
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
Ember Local Storage Decorator
==============================================================================
Decorator to use `localStorage` in Ember Octane.
Compatibility
------------------------------------------------------------------------------
* Ember.js v3.28 or above
* Ember CLI v3.28 or above
* Node.js v14 or above
Installation
------------------------------------------------------------------------------
```
ember install ember-local-storage-decorator
```
Usage
------------------------------------------------------------------------------
```js
import localStorage from 'ember-local-storage-decorator';
import Component from '@glimmer/component';
export default class MyComponent extends Component {
@localStorage foo
}
```
Decorate a class property with `@localStorage` to bind it to `localStorage`.
It will attach a getter to read the value from `localStorage` and a setter
to write changes to `localStorage`.
```js
const Klass = class {
@localStorage foo;
}
const klass = new Klass();
klass.foo = 'baz';
window.localStorage.getItem('foo'); // '"baz"'
```
You may specify another key to be used in local storage as an argument to the
decorator.
```js
const Klass = class {
@localStorage('bar') foo;
};
const klass = new Klass();
klass.foo = 'baz';
window.localStorage.getItem('bar'); // '"baz"'
```
The value is stored as a JSON string in `localStorage`. Therefore only values
which can be serialized to JSON are supported.
Objects (and arrays) are deep frozen to avoid leaking state. Getter returns a
frozen copy after setting a value.
```js
window.localStorage.setItem('foo', [{ a: 'b' }]);
const Klass = class {
@localStorage foo;
};
const klass = new Klass();
Object.isFrozen(klass.foo); // true
Object.isFrozen(klass.foo[0]); // true
const newValue = {};
klass.foo = newValue;
Object.isFrozen(klass.foo); // true
Object.isFrozen(newValue); // false
```
It observes changes caused by other classes or by other instances:
```js
const KlassA = class {
@localStorage foo;
};
const KlassB = class {
@localStorage foo;
}
const klassA = new KlassA();
const klassB = new KlassB();
klassA.foo = 'bar';
klassB.foo; // 'bar'
window.dispatchEvent(
new StorageEvent('storage', { key: 'foo', newValue: 'baz', oldValue: 'bar' })
);
klassA.foo; // 'baz'
klassB.foo; // 'baz'
```
Due to limitations of `localStorage` direct changes of the value bypassing
`@localStorage` decorator can not be observed. Therefore you _should not_
manipulate the `localStorage` directly.
## Testing
`window.localStorage` is a global state, which is shared between test runs.
The decorator uses a global cache, which is also shared between instances.
Both are not reset automatically between test jobs.
To avoid leaking state between test jobs it's recommended to clear the cache
of `@localStorage` decorator before each test. A `clearLocalStorageCache`
helper function is exported from `ember-local-storage-decorator` to do so.
Additionally `window.localStorage` should be either cleared before each test
run or mocked.
```js
import { module, test } from 'qunit';
import { setupRenderingTest } from 'ember-qunit';
import { clearLocalStorageCache } from 'ember-local-storage-decorator';
module('Integration | Component | my-component', function (hooks) {
setupRenderingTest(hooks);
hooks.beforeEach(function () {
clearLocalStorageCache();
window.localStorage.clear();
});
});
```
`@localStorage` decorator performs some initialization work when a property
is decorated. This includes picking up the current value from local storage
and adding it to its internal cache. Manual changes to local storage _after_
a property has been decorated are _not_ picked up. As class instances are
often shared between test jobs, you need to manual reinitialize a local
storage key in tests.
```js
import { initalizeLocalStorageKey } from 'ember-local-storage-decorator';
test('some code relying on a value in local storage', function() {
window.localStorage.setItem('foo', 'bar');
initalizeLocalStorageKey('foo');
});
```
Contributing
------------------------------------------------------------------------------
See the [Contributing](CONTRIBUTING.md) guide for details.
License
------------------------------------------------------------------------------
This project is licensed under the [MIT License](LICENSE.md).