百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
L

locally

> 编程语言
开源

Locally 是一个本地存储管理器,支持具有超时值的过期项,并通过使用 LZW 算法进行压缩来节省空间。

370 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

Locally 是一个本地存储管理器,支持具有超时值的过期项,并通过使用 LZW 算法进行压缩来节省空间。

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

javascript
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:

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

With CommonJS:

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

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

javascript
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.

javascript
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:

javascript
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:

javascript
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:

javascript
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.

javascript
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;

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

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

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

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

javascript
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.

javascript
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.

javascript
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.

javascript
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.

javascript
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.

javascript
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.

javascript
store.clear();

.key(index)

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

javascript
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.

javascript
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.

javascript
store.ttl("key");

.persist(key)

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

javascript
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.

javascript
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.

javascript
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.

javascript
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 *.

javascript
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.

javascript
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.

javascript
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:

bash
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).

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

TypeScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言