# xy-storage

> 本地缓存解决方案

Latest version **4.0.0** (published 2025-11-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install xy-storage
pnpm add xy-storage
yarn add xy-storage
bun add xy-storage
```

## Health

**Score 60/100 (C)** — status: stable.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-11-17 |
| First published | 2021-04-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 0 |
| Unpacked size | 23.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | mengxianghan |
| Maintainers | mengxianghan |
| Keywords | storage, localStorage, sessionStorage, cookie |

## Links

- npm: https://www.npmjs.com/package/xy-storage
- Repository: https://github.com/mengxianghan/xy-storage
- Homepage: https://github.com/mengxianghan/xy-storage#readme
- Issues: https://github.com/mengxianghan/xy-storage/issues
- npm.io page: https://npm.io/package/xy-storage

## 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

- 4.0.0 (latest) — 2025-11-17
- 3.1.1 — 2024-07-09
- 3.1.0 — 2023-05-16
- 3.0.2 — 2023-03-30
- 3.0.1 — 2023-02-18
- 3.0.0 — 2022-06-30
- 2.0.2 — 2021-07-26
- 2.0.1 — 2021-07-09
- 2.0.0 — 2021-07-03
- 1.0.5 — 2021-05-31
- 1.0.4 — 2021-04-11
- 1.0.3 — 2021-04-11

## README

# xy-storage

基于 `localStoage` `sessionStorage` `js-cookie` 的本地缓存

## 安装

如果使用 `cookie`，需要安装 `js-cookie`

1. NPM 方式（推荐）

```shell
pnpm add xy-storage js-cookie
```

2. CDN 方式

```html
<script src="https://cdn.jsdelivr.net/npm/js-cookie@3.0.5/dist/js.cookie.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/xy-storage/dist/index.global.js"></script>
```

## 使用方法

### 1. 导入函数

```typescript
import {
  createCookie, 
  createLocalStorage, 
  createSessionStorage
} from "xy-storage";
```

### 2. 创建实例

```typescript
const cookie = createCookie({
  namespace: 'example_',
  attrs: {
    expires: 7,
    path: '',
    domain: 'example.com',
    sameSite: 'strict',
  }
})

const local = createLocalStorage({
  namespace: 'example_',
  attrs: {
    expires: 7,
  }
})

const session = createSessionStorage({
  namespace: 'example_'
})
```

### 3. 使用

#### setItem

设置缓存

```typescript
cookie.setItem(
  'test',
  1,
  {
    expires: 7,
    domain: 'example.com',
  }
)

local.setItem(
  'test', 
  2,
  {
    expires: 7,
  }
)

session.setItem('test', 3)
```

#### getItem

获取缓存

```typescript
cookie.getItem('test') // 1

local.getItem('test') // 2

session.getItem('test') // 3
```

#### removeItem

删除缓存

```typescript
cookie.removeItem('test')

local.removeItem('test')

session.removeItem('test')
```

#### clear

清空缓存，`cookie` 不支持 `clear` 方法

```typescript
local.clear()

session.clear()
```

## API 文档

### 创建函数

#### createCookie

```typescript
declare function createCookie(
  options: CookieOptions,
)
```

- options: 配置
  - namespace: 命名空间
  - attrs: 属性
    - expires: 过期时间
    - path: 路径
    - domain: 域
    - sameSite: 同域
- 更多参数，请查看 [js-cookie](https://www.npmjs.com/package/js-cookie)

#### createLocalStorage

```typescript
declare function createLocalStorage(
  options: LocalStorageOptions
)
```

- options: 配置
  - namespace: 命名空间
  - attrs: 属性
    - expires: 过期时间

#### createSessionStorage

```typescript
declare function createSessionStorage(
  options: SessionStorageOptions
)
```

- options: 配置
    - namespace: 命名空间
    - attrs: 属性
        - expires: 过期时间

### 方法

#### setItem
```text
setItem(
  name: string,
  value: any,
  attrs?: CookieAttrs | WebStorageAttrs
)
```
- name: 键
- value: 值
- attrs: 属性，可选

#### getItem

```text
getItem(
  name: string,
  defaultValue?: any
): any
```
- name: 键
- defaultValue: 未获取到值时的返回值，可选

#### removeItem
```text
removeItem(name: string)
```
- name: 键

#### clear
```text
clear()
```
删除所有缓存，仅适用于 `local` 和 `session`

## 类型定义

```typescript
import type {
  BaseStorageOptions, 
  CookieAttrs, 
  CookieOptions, 
  LocalStorageOptions, 
  SessionStorageOptions, 
  WebStorageAttrs, 
  WebStorageOptions
} from 'xy-storage'
```

## 依赖

[js-cookie](https://www.npmjs.com/package/js-cookie)

## 参考文档

[js-cookie](https://www.npmjs.com/package/js-cookie)

[sessionStorage](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/sessionStorage)

[localStorage](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/localStorage)

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