ls-proxy

ls-proxy

Wrapper around localStorage to easily store JSON objects.

Supports:

• Storing any type that can be serialized
• Runtime valdiation (eg. type checking)
• Deeply nested objects

Why to use?

If you want to store client-side data for your website, the way to do it is with localStorage. However, there is at least one siginificant downside: you can only store strings in localStorage keys.

The best way to get around this is by storing a stringified JSON object in a key, but doing this manually or having to call a function that does it for you any time you change an object would be annoying.

This library solves these problems using JS proxies. It also has great IDE support thanks to it being written in TypeScript. You can also use it with vanilla JS with the Webpacked file (ls-proxy.user.js or ls-proxy.min.user.js), which is useful to test it in the browser, when not using a JS bundler, or while writing UserScripts.

Here's all it takes to store a stringifed JSON object in localStorage and automatically change it:

import { storeObject } from 'ls-proxy'

const someInfo = storeObject(
  // The localStorage key to save data under
  'someInfo',
  // The object to store
  {
    aString: 'Hello, World!',
    aNumber: 123,
    aBoolean: true,
    aList: [1, '2', 3],
  },
)

someInfo.aNumber = 42 // Updates localStorage
console.log(someInfo.aList) // Reads from localStorage

The method above stores an entire serialized object in localStorage, meaning the entire object has to be stringified/parsed whenever a single key is affected. The method below stores each key individually instead:

import { storeSeparate } from 'ls-proxy'

const someInfo = storeObject(
  // The object to store
  {
    aString: 'Hello, World!',
    aNumber: 123,
    aBoolean: true,
    aList: [1, '2', 3],
  },
  // Optional; prefixes the stored keys with this ID
  { id: 'someInfo' },
)

someInfo.aNumber = 42 // Updates localStorage
console.log(someInfo.aList) // Reads from localStorage

Documentation

Documentation for the main branch is hosted at https://ls-proxy.adamts.me. Documentation can be built from a cloned repository by running yarn doc.

Examples are located in examples.

storeObject vs storeSeparate

storeSeparate will generally be faster than storeObject since there's less data being serialized/deserialized with each get/set, but there are still reasons to use storeObject. For example, if you want to use validate and modify (see documentation for config options), and you need the entire object for context. This can be the case if you need another key's value to validate the object, or if you want to modify multiple keys with a single set/get.

Use

In a Node project

To use in a Node project, add ls-proxy as a dependency.

# npm
npm install ls-proxy

# yarn
yarn add ls-proxy

You can then import and use functions:

import { storeObject } from 'ls-proxy'

const myObj = storeObject('myObj', {
  name: 'John',
  age: 21,
})

myObj.name = 'Joe'
myObj.age++

In a normal UserScript

In a UserScript that isn't built with some build tool, you can @require the library:

// @require     https://gitlab.com/MysteryBlokHed/ls-proxy/-/raw/main/ls-proxy.user.js

You can replace main with a specific release tag like v0.1.0 to require a specific version:

// @require     https://gitlab.com/MysteryBlokHed/ls-proxy/-/raw/v0.1.0/ls-proxy.user.js

Each release tag also has a minified version of the script available, which can be used by changing the file extension to .min.user.js:

// @require     https://gitlab.com/MysteryBlokHed/ls-proxy/-/raw/v0.1.0/ls-proxy.min.user.js

Functions are available on the global LSProxy object:

const { storeObject } = LSProxy

const myObj = storeObject('myObj', {
  name: 'John',
  age: 21,
})

myObj.name = 'Joe'
myObj.age++

Type declarations

The types included with the npm package still work when the library is @require'd. Just add the types as a dev dependency for a Node project or install them globally. With the package installed, include the following reference line somewhere in your TypeScript source file:

/// <reference types="ls-proxy" />

Building

Setup

Building this project requires Node.js and Yarn. To install dependencies, run:

yarn install

Build

To build the project, run:

yarn build

To automatically build when a source file is modified, run:

yarn dev

Built JS files and type declarations will be placed in the lib/ directory, and the UserScript will be placed in the root. The package.json file is configured to publish files in the lib/ directory to npm.

Test

To test the project, run:

yarn test

This project uses Jest for tests.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

This project was created from a template licensed under the MIT license (LICENSE or http://opensource.org/licenses/MIT).