Locally 是一个本地存储管理器,支持具有超时值的过期项,并通过使用 LZW 算法进行压缩来节省空间。
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).
Number, String, Boolean, Array, Object, Date, RegExp and Function values in their given forms.Locally is installable via npm:
npm install locallyjsstore.set("example", {
property1: "value1",
property2: "value2",
});
store.get("example"); // { property1: "value1", property2: "value2" }
store.expire("example", 1000);
setTimeout(function () {
store.get("example"); // null
}, 1001);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();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");
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; // trueTime 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 millisecondsor 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");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; // < 22Returns 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() 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"]); // []It will wipe out all values from localStorage.
store.clear();Returns key at the given index. Similar to same function of native localStorage.
store.key(0); // "key"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");Remove timeout of given key, making the value non-expiring.
store.set("key", "value", 1000);
store.persist("key");
store.ttl("key"); // nullAdds 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);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"]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);
});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; // 2Locally 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.
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.
After cloning the repo and running npm install, run:
npm testTo run browser tests, open test/browser.html in your browser after building with npm run build.
This project uses Semantic Versioning and semantic-release for automated releases. Pushing to main or master runs the release workflow, which:
CHANGELOG.md and package.json, creates a Git tag and GitHub releaseNPM_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).
暂无开放 Issues,或尚未同步最近议题。