@iap/storage

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

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

特性

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

安装

pnpm add @iap/storage
Copy

快速开始

import { setStorage, getStorage, setSession, getSession } 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）
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。

Tree-shaking

只使用 localStorage 时，session 模块不会被打包：

// 只引入 storage 相关，session.ts 不会进入 bundle
import { setStorage, getStorage } from '@iap/storage'
Copy

加密与数据迁移

启用加密（isEncrypted: true）时：

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

类型导出

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