locally - GitLite

KO | EN

gitlite — search

#javascript #golang #android #deep-learning #linux #docker #macos #java #awesome #vue #security #pytorch #mcp #ios

locally

(★ 370)

Locally is a localStorage manager that supports expirable items with timeout values and saves space by compressing them using LZW algorithm.

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - release.yml
- light.d.mts
- light.d.ts
- light.global.js
- light.global.js.map
- light.js
- light.js.map
- light.mjs
- light.mjs.map
- locally.d.mts
- locally.d.ts
- locally.global.js
- locally.global.js.map
- locally.js
- locally.js.map
- locally.mjs
- locally.mjs.map
- light.ts
- locally.ts
- browser.html
- locally-mocha.js
- locally-mocha.js.bak
- locally-mocha.ts
- node-mocha.ts
.gitignore
.releaserc.json
CHANGELOG.md
LICENSE
package-lock.json
package.json
README.md
tsconfig.browser-test.json
tsconfig.json
tsup.config.ts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/ozantunca/locally

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd locally

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm test

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Locally

[![npm version](https://badge.fury.io/js/locallyjs.svg)](https://www.npmjs.org/package/locallyjs)
[![CI](https://github.com/ozantunca/locally/actions/workflows/ci.yml/badge.svg)](https://github.com/ozantunca/locally/actions/workflows/ci.yml)

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.](#user-content-timeout-support)
- 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.](#user-content-compression)

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](#locally)
    - [Features](#features)
    - [Quick Examples](#quick-examples)
    - [Functions and Properties](#functions-and-properties)
    - [Usage](#usage)
      - [Initialization](#initialization)
      - [Light Version](#light-version)
      - [.set(key, value\[, options\])](#setkey-value-options)
        - [Timeout support](#timeout-support)
        - [Compression](#compression)
      - [.get(key)](#getkey)
      - [.remove(key)](#removekey)
      - [.clear()](#clear)
      - [.key(index)](#keyindex)
      - [.ttl(key\[, returnString\])](#ttlkey-returnstring)
      - [.persist(key)](#persistkey)
      - [.expire(key, timeout)](#expirekey-timeout)
      - [.keys(\[keyPattern\])](#keyskeypattern)
      - [.scan(keyPattern, function)](#scankeypattern-function)
      - [.length](#length)
      - [Compression](#compression-1)
    - [How Locally Works](#how-locally-works)
    - [Testing](#testing)
    - [Versioning and releases](#versioning-and-releases)

### Usage

#### Initialization

With ES modules:

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

With CommonJS:

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

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

```js
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.

```js
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:

```js
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:

```js
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:

```js
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.

```js
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;

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

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

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

You can also specify TTL with string thanks to [ms.js](https://github.com/rauchg/ms.js).

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

```js
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.

```js
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.

```js
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.

```js
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.

```js
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.

```js
store.clear();
```

#### .key(index)

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

```js
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.

```js
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.

```js
store.ttl("key");
```

#### .persist(key)

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

```js
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.

```js
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.

```js
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.

```js
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 `*`.

```js
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`.

```js
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.

```js
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:

```sh
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](https://semver.org/) and [semantic-release](https://github.com/semantic-release/semantic-release) for automated releases. Pushing to `main` or `master` runs the release workflow, which:

1. Analyzes commits using [Conventional Commits](https://www.conventionalcommits.org/)
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).