Locally

Locally is a localStorage manager that supports expirable items with timeout values and saves space by compressing them using LZW algorithm. W3C specification suggest 5MB of quota for every origin. Even though it's not a must, browsers tend to stay around that number thus giving our site an exhaustible storage in the long run. Locally's TTL support will take care of that. Locally works much like a caching software (e.g. Redis).

Features

• Defining timeout for values to ensure some values will expire in time.
• Type checking store and return Number, String, Boolean, Array, Object, Date, RegExp and Function values in their given forms.
• A much simpler API than originial localStorage while keeping all it's functions intact.
• Compression via LZW algorithm.

Locally is installable via npm:

• npm install locallyjs

Quick Examples

store.set("example", {
  property1: "value1",
  property2: "value2",
});

store.get("example"); // { property1: "value1", property2: "value2" }

store.expire("example", 1000);

setTimeout(function () {
  store.get("example"); // null
}, 1001);

Functions and Properties

• Locally
  • Features
  • Quick Examples
  • Functions and Properties
  • Usage
    • Initialization
    • Light Version
    • .set(key, value[, options])
      • Timeout support
      • Compression
    • .get(key)
    • .remove(key)
    • .clear()
    • .key(index)
    • .ttl(key[, returnString])
    • .persist(key)
    • .expire(key, timeout)
    • .keys([keyPattern])
    • .scan(keyPattern, function)
    • .length
    • Compression
  • How Locally Works
  • Testing
  • Versioning and releases

Usage

Initialization

With ES modules:

import { Store } from "locallyjs";
const store = new Store();

With CommonJS:

const { Store } = require("locallyjs");
const store = new Store();

In the browser with a script tag (IIFE build), the global is window.Locally:

const Store = window.Locally.Store;
const store = new Store();

If compression for all values is wanted to be done as default, Locally can be initialized to indicate that.

var store = new Store({ compress: true });

Locally will compress all current and upcoming values. If you have compressed values but want to decompress them all and continue uncompressed, Locally will perform decompression on all currently compressed values once it's initialized as:

var store = new Store();

Light Version

Since version v0.3.3 locally has a light version that does not support compression and ms module for those who don't want these features and want to save size:

import { Store } from "locallyjs/light";
const store = new Store();

Or with CommonJS: const { Store } = require("locallyjs/light");

.set(key, value[, options])

Assigns a value to given key. key is a string. Basic usage is as follows:

store.set("key", "value");

Value can be anything. If it's a String, Number, Boolean, Array, Object, Date, RegExp or Function, .get() will return the value in it's correct type instead of a string.

store.set("key", new Date());

store.get("key") instanceof Date; // true

Timeout support

Time To Live (TTL) values can be given to keys so that defined values will be removed after given milliseconds. TTL can be included in options parameter;

store.set("key", "value", {
  ttl: 1000,
}); // TTL is 1000 milliseconds

or can be given as the third parameter as a shorthand;

store.set("key", "value", 1000);

You can also specify TTL with string thanks to ms.js.

store.set("key", "value", "5s");
store.set("key", "value", "2m");
store.set("key", "value", "1 hour");

Compression

You can tell .set() to compress given value.

store.set("key", "value to be compressed", { compress: true });

store.get("key"); // 'value to be compressed'
store.get("key").length; // 22
localStorage.getItem("key").length; // < 22

.get(key)

Returns the corresponding value of given key.

store.set("key", "value");

store.get("key"); // "value"
store.get("nokey"); // null

.get() can have it's first parameter as an array. In which case .get() will return an array of values assigned to given array of keys.

store.set("key1", "value1");
store.set("key2", "value2");
store.set("key3", "value3");

store.get(["key1", "key2", "key3"]); // ["value1", "value2", "value3"]

.remove(key)

.remove() removes a value from localStorage using given key.

store.set("key", "value");

store.remove("key");

store.get("key"); // null

.remove() can have it's first parameter as an array. In which case .remove() will remove an array of values assigned to given array of keys.

store.set("key1", "value1");
store.set("key2", "value2");
store.set("key3", "value3");

store.remove(["key1", "key2", "key3"]);
store.get(["key1", "key2", "key3"]); // []

.clear()

It will wipe out all values from localStorage.

store.clear();

.key(index)

Returns key at the given index. Similar to same function of native localStorage.

store.key(0); // "key"

.ttl(key[, returnString])

Returns timeout for given key. If second parameter is true .ttl() will return a logical reply using ms module.

store.set("key", "value", 1000);

store.ttl("key"); // <= 1000
store.ttl("key", true); // '1s'

It will return -1 if the value has no TTL and persists or -2 if there is no value associated with the key.

store.ttl("key");

.persist(key)

Remove timeout of given key, making the value non-expiring.

store.set("key", "value", 1000);

store.persist("key");

store.ttl("key"); // null

.expire(key, timeout)

Adds timeout to key, making it expiring if it wasn't, or updating it's timeout value.

store.set("key", "value");
store.expire("key", 1000);

setTimeout(function () {
  store.get("key"); // null
}, 1001);

.keys([keyPattern])

Queries given string among keys and returns the one that includes that string.

store.set("key1", "value1");
store.set("key2", "value2");
store.set("somekey1", "somevalue1");
store.set("somekey2", "somevalue2");
store.set("something different", "different value");

store.keys("key"); // ["key1", "key2", "somekey1", "somekey2"]

keyPattern can also be a RegExp, in which case that RegExp will be used when querying.

store.set("key1", "value1");
store.set("key2", "value2");
store.set("somekey1", "somevalue1");
store.set("somekey2", "somevalue2");
store.set("something different", "different value");

store.keys(/^key.*/); // ["key1", "key2"]

.keys() will return all values if keyPattern is not present or is *.

store.set("key1", "value1");
store.set("key2", "value2");
store.set("somekey1", "somevalue1");
store.set("somekey2", "somevalue2");
store.set("something different", "different value");

store.keys(); // ["key1", "key2", "somekey1", "somekey2", "something different"]
store.keys("*"); // ["key1", "key2", "somekey1", "somekey2", "something different"]

.scan(keyPattern, function)

Queries using keyPattern and runs function for values associated with keys matching keyPattern. keyPattern can be String or RegExp.

store.set("key1", "value1");
store.set("key2", "value2");

store.scan(/key/, function (value, key) {
  console.log(key, " : ", value);
});

.length

Similar to length property of native localStorage, .length is an integer that represents number of keys Locally is holding at anytime.

store.length; // 0

store.set("key1", "value1");
store.set("key2", "value2");

store.length; // 2

Compression

Locally by default does not compress values unless it's told to do otherwise. It can be configured to compress all values by giving parameter on initialization, or an extra parameter can be given to .set() so that .set() will compress only that value.

How Locally Works

Locally holds an extra object in localStorage called locally-config to save TTL and type information. It automatically updates config on page load using current values in localStorage to make sure it doesn't miss any value added to localStorage without using Locally.

Testing

After cloning the repo and running npm install, run:

npm test

To run browser tests, open test/browser.html in your browser after building with npm run build.

Versioning and releases

This project uses Semantic Versioning and semantic-release for automated releases. Pushing to main or master runs the release workflow, which:

1. Analyzes commits using Conventional Commits
2. Chooses the next version (patch / minor / major) from commit types
3. Updates CHANGELOG.md and package.json, creates a Git tag and GitHub release
4. Publishes to npm (if NPM_TOKEN is set in the repo secrets)

Commit message format (determines version bump):

• fix: or fix(scope): → patch (e.g. 1.0.0 → 1.0.1)
• feat: or feat(scope): → minor (e.g. 1.0.0 → 1.1.0)
• BREAKING CHANGE: in footer or feat!: / fix!: → major (e.g. 1.0.0 → 2.0.0)

To enable npm publish: add an NPM_TOKEN secret (Automation token from npmjs.com) in the repo’s GitHub Settings → Secrets and variables → Actions.

Manual version bumps are still available: npm run version:patch, version:minor, version:major (run tests, bump version, create tag; no automated publish).