@iap/storage

浏览器存储工具，支持 localStorage、sessionStorage 和 Cookie，具备可选 AES 加密、智能序列化与向后兼容数据迁移能力。

所有 API 均为独立函数导出，支持 tree-shaking——只引入 storage 相关函数时，session、cookie 模块不会被打包进来。

特性

• 支持 localStorage、sessionStorage、Cookie 三种存储类型
• 支持 string、number、boolean、object 类型的读写与自动序列化
• 可选加密：通过适配器接入任意 AES 加密库，key 和 value 均加密存储（localStorage / sessionStorage）
• 向后兼容迁移：启用加密后自动将旧明文数据迁移为加密格式
• 零外部依赖：加密和 logger 均通过适配器接口注入
• 完整 TypeScript 类型支持
• 支持 tree-shaking，按需引入

安装

pnpm add @iap/storage
Copy

快速开始

import { setStorage, getStorage, setSession, getSession, setCookie, getCookie } from '@iap/storage'

// localStorage
setStorage('user', { id: 1, name: 'Alice' })
const user = getStorage('user')  // { id: 1, name: 'Alice' }

// sessionStorage
setSession('step', 2)
const step = getSession('step')  // 2（number）

// Cookie
setCookie('token', 'abc123', { maxAge: 86400 })
const token = getCookie('token')  // 'abc123'
Copy

注入加密适配器

在应用入口调用一次 configure()，storage 和 session 共享同一份配置。

import { configure } from '@iap/storage'
import Encrypt, { AESHelper } from '@iap/encryptor'
import { logger } from '@iap/logger'

configure({
  encrypt: {
    isEncrypted: Encrypt.isEncrypted,
    encrypt: (data) => AESHelper.EncryptWeb(data, Encrypt.DATA_KEY),
    decrypt: (data) => AESHelper.DecryptWeb(data, Encrypt.DATA_KEY),
  },
  logger,
})
Copy

API 参考

configure(config)

在应用入口调用一次，注入加密适配器和/或 logger，storage 和 session 共享。

configure({
  encrypt?: EncryptAdapter
  logger?: LoggerAdapter
})
Copy

localStorage

setStorage(key, value)

写入值，支持 string、number、boolean、object。

setStorage('name', 'Alice')
setStorage('age', 18)
setStorage('active', true)
setStorage('profile', { role: 'admin' })
Copy

getStorage(key, def?)

读取值，key 不存在时返回 def（默认 ''）。

getStorage('name')           // 'Alice'
getStorage('profile')        // { role: 'admin' }
getStorage('missing', null)  // null
Copy

removeStorage(key?)

删除指定 key；不传则清空整个 localStorage。

removeStorage('name')
removeStorage()
Copy

clearStorage()

清空 localStorage，等价于 removeStorage()。

hasStorage(key)

检查 key 是否存在，返回 boolean。

hasKeySwitch(key)

当 key 对应的值等于 '1' 时返回 true，适用于功能开关。

setStorage('feature_x', '1')
hasKeySwitch('feature_x')  // true
Copy

sessionStorage

setSession(key, value)

写入值到 sessionStorage。

getSession(key, def?)

读取值，具备自动类型推断：

• 纯数字字符串 → number
• 'true' / 'false' → boolean
• 普通字符串 → string
• 对象 → object

setSession('count', 5)
getSession('count')  // 5（number）

setSession('flag', true)
getSession('flag')   // true（boolean）
Copy

removeSession(key?)

删除指定 key；不传则清空整个 sessionStorage。

Cookie

Cookie 仅支持浏览器端（基于 document.cookie）。

setCookie(key, value, options?)

写入一个 Cookie。

setCookie('token', 'abc123')
setCookie('token', 'abc123', { maxAge: 86400 * 7 })       // 7 天后过期
setCookie('token', 'abc123', { expires: 3600 })            // 1 小时后过期（秒数）
setCookie('token', 'abc123', { expires: new Date('2026-01-01') })  // 指定日期
setCookie('sid', 'xyz', { path: '/', secure: true, sameSite: 'lax' })
Copy

CookieOptions

getCookie(key, def?)

读取 Cookie 值，key 不存在时返回 def（默认 null）。

getCookie('token')           // 'abc123'
getCookie('missing')         // null
getCookie('missing', '')     // ''
Copy

hasCookie(key)

检查 Cookie 是否存在，返回 boolean。

hasCookie('token')  // true
Copy

removeCookie(key, options?)

删除一个 Cookie（将 expires 设为过去时间）。path 和 domain 须与写入时一致，否则删除无效。

removeCookie('token')
removeCookie('token', { path: '/admin' })
Copy

supportCookie()

检查当前环境是否支持 Cookie（浏览器端返回 true）。

Tree-shaking

按需引入，未使用的模块不会进入 bundle：

// 只引入 localStorage，session 和 cookie 模块不打包
import { setStorage, getStorage } from '@iap/storage'

// 只引入 Cookie
import { setCookie, getCookie } from '@iap/storage'
Copy

加密与数据迁移

启用加密（isEncrypted: true）时，适用于 localStorage 和 sessionStorage：

• key 和 value 均加密存储
• 向后兼容：首次读取旧明文数据时自动迁移为加密格式并删除明文副本

Cookie 不支持加密，始终以明文存储。

类型导出

import type {
  StorageType,     // 'storage' | 'session' | 'cookie'
  EncryptAdapter,  // 加密适配器接口
  LoggerAdapter,   // Logger 适配器接口
  StorageConfig,   // configure() 参数类型
  CookieOptions,   // setCookie / removeCookie 配置项
} from '@iap/storage'
Copy