# sels

> Safe & expirable localStorage

Latest version **2.5.1** (published 2021-12-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install sels
pnpm add sels
yarn add sels
bun add sels
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.5.1 |
| Published | 2021-12-09 |
| First published | 2021-04-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 20.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | Vlad Ivanov |
| Maintainers | yungvldai |
| Keywords | localstorage |

## Links

- npm: https://www.npmjs.com/package/sels
- Repository: https://github.com/yungvldai/sels
- Homepage: https://github.com/yungvldai/sels#readme
- Issues: https://github.com/yungvldai/sels/issues
- npm.io page: https://npm.io/package/sels

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 2.5.1 (latest) — 2021-12-09
- 2.5.0 — 2021-12-09
- 2.3.0 — 2021-08-25
- 2.2.0 — 2021-07-06
- 2.1.2 — 2021-06-21
- 2.1.1 — 2021-05-24
- 2.1.0 — 2021-05-23
- 2.0.5 — 2021-05-22
- 2.0.4 — 2021-05-22
- 2.0.3 — 2021-05-17
- 2.0.2 — 2021-05-17
- 2.0.1 — 2021-05-17
- 1.1.0 — 2021-05-01
- 1.0.5 — 2021-05-01
- 1.0.4 — 2021-05-01
- … 4 more at https://npm.io/package/sels/versions

## README

# sels 🍪➡️🗄
sels - safe expirable **localStorage**

[![npm](https://img.shields.io/npm/v/sels?color=cc3534)](https://www.npmjs.com/package/sels)
[![Tests](https://github.com/yungvldai/sels/actions/workflows/main.yml/badge.svg)](https://github.com/yungvldai/sels/actions/workflows/main.yml)
[![LICENSE](https://img.shields.io/github/license/yungvldai/sels?color=yellow)](https://github.com/yungvldai/sels/blob/master/LICENSE)
![Package size](https://img.shields.io/github/size/yungvldai/sels/.size/index.min.js)

Using cookies for client-only purposes is irrational and unsafe. There is no point in using cookies if the data is not intended to be sent to the server. In this case, you need to use localStorage. However, localStorage may not be available (then an error will be generated), and there is no expiry mechanism in localStorage.

*This library solves both problems*

## Installing and usage

```bash
npm i sels
```

```js
import sels from 'sels';

sels.set('key', 'value');
```

или

```html
<script src="https://cdn.jsdelivr.net/npm/sels@latest/index.min.js"></script>
```
```js
Sels.set('key', 'value');
```

## Breaking changes ⚠️

 - The method `get` version 1.x.x has been renamed to `asyncGet` (see description below)

## Types & interfaces

```ts
interface RecordOptions {
  maxAge?: number
  expires?: string | Date
}

type RecordValue = string | boolean | number;
```

## Methods

`set(key: string, value: RecordValue, options?: RecordOptions): boolean` - adds or modifies a record in **localStorage**. `value` will be cast to string. 
Before write, the ability to write will be checked, if the recording failed, it will return `false`, else `true`.

`asyncGet(key: string): Promise` - reads a record from **localStorage**. Checks readability before reading. If it fails, the Promise will be rejected with an error value, otherwise the Promise will be resolved with the read value. Promise will resolve with value `null`, if the specified key is not found.

`get(key: string): string | null` - reads a record from **localStorage**. Checks readability before reading. If the read failed, it will return `null`, otherwise the key value will be returned. If the key is not found, it will also return `null`.

`remove(key: string)` - removes record from **localStorage**. Before deleting, it checks if deletion is possible. It will return `true`, if deletion is successful, else `false`. 
If the key is not found, but there is no error, it will return `true` anyway.

`clear()` - completely cleans **localStorage**, it will return `true`, if successful, else `false`.

## Fields

`Sels` also exports value `isAvailable: boolean` - availability of **localStorage**.

## Options 

The `set` method takes a third (optional) parameter - `options`. If nothing is passed, the record will be eternal.

 - `maxAge` is needed to indicate the number of seconds - the lifetime of the record. After this time expires, the record will no longer be available.
 - `expires` is needed to specify a date string or object `Date`, after which the record should become inaccessible. 
The date can be passed as a string (e.g. *ISO string* or `12-31-2021`). [`Date.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse) will be used for parsing.
You can also specify a Jira-like period, for example, `1w 2d 3h`, so the record will stop being read after 1 week (7 days) + 2 days + 3 hours. Supported units: `y`, `m`, `w`, `d`, `h` (year, month, week, day, hour).

## Translations

 - [🇷🇺 Русский](https://github.com/yungvldai/sels/blob/master/translations/ru/README.md)
 - [🇺🇸 English (this)](https://github.com/yungvldai/sels/blob/master/README.md)

---
_Source: https://npm.io/package/sels · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._