@lachlanmcdonald/mock-storage

mock-storage is a implementation of Web Storage API (e.g. localStorage), primarily intended for use in development/testing in non-browser environments where the API is not available.

mock-storage intends to be side-effect compatible with browser environments, with support for utilising internal methods on the Web Storage instances. This allows mock-storage to be used in environments where you may not have complete control or visibility over how your storage is being accessed.

Usage

There are two distinct ways to utilise this module:

const { createStorage } = require('@lachlanmcdonald/mock-storage');
const storage = createStorage();

const { Storage } = require('@lachlanmcdonald/mock-storage');
const storage = new Storage();

createStorage()

createStorage() will return a new Storage instance that is proxied in such a way as to be as close to browser implementations as possible. This instance supports both the Storage Interface and utilising JavaScript's internal methods on a Storage instance:

Method	Behaviour
Object.keys()	Returns all keys set on the instance
Object.entries()	Returns an array of key/value pairs set on the instance
Object.values()	Returns an array of values set on the instance
instance[key]	Behaves the same as getItem() except for existing methods or properties
instance[key] = value	Behaves the same as setItem()
delete instance[key]	Behaves the same as removeItem()
Object.defineProperty() Object.defineProperties()	Behaves the same as setItem()
{...instance}	Outputs an object of key/value pairs set on the instance
Object.preventExtensions()	Will throw a TypeError.
Object.setPrototypeOf()	Will fail and return false.
Object.isExtensible()	Will always return true.
Object.getOwnPropertyNames()	Returns all keys set on the instance.
instance['length']	Will return the number of keys set on the instance (even if a key of length has been added to the storage.)

new Storage()

new Storage() initialises a new Storage object that is not proxied. As such, this instance only implements the Storage Interface:

• Storage.key()
• Storage.getItem()
• Storage.setItem()
• Storage.removeItem()
• Storage.clear()
• Storage.length

Implementation notes

• The property __unsafeInternalStore on Storage instances is reserved. Manipulate this key outside of using the Storage Interface will result in errors.
• This implementation is intended for non-browser environments, and as such, does not fire storage events or throw SecurityError exceptions. This module is not intended as a browser polyfill.
• Storage instances do not have a quote limit and will not throw QuotaExceededError exceptions.
• The configurable, enumerable, writeable properties are ignored when calling defineProperty() on a proxied Storage object. This appears to match browser implementations of this behaviour.
• As there is no trap for Object.freeze(), calling Object.freeze() will throw the TypeError "Cannot prevent extensions", instead of the expected "Cannot freeze".
• As there is no trap for Object.seal(), calling Object.seal() will throw the TypeError "Cannot prevent extensions", instead of the expected "Cannot seal".

Tests

npm run build
npm test