fatigue-kit 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present fatigue-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# fatigue-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [简体中文](./README.zh-CN.md)
+
+> Zero-dependency frequency capping for Web, mini-programs, React Native and Node.js.
+
+`fatigue-kit` answers one question: **should this popup / toast / guide / coupon be shown now?**
+Compose simple rules, back them by any storage, and get an atomic, testable answer — synchronously — in every JS runtime.
+
+## Features
+
+- **Composable rules** — calendar day / week / month (custom cutoff), sliding window, cooldown, lifetime cap. Stack any number of rules; the strictest wins.
+- **Atomic `tryConsume`** — check and count in one synchronous step, so double triggers can never double-fire.
+- **Every environment, on demand** — zero-dependency core with storage adapters as subpath exports: `localStorage`, `sessionStorage`, React Native `AsyncStorage`, WeChat / Alipay mini-programs, Node.js file. Bundlers ship only what you import.
+- **Testable** — inject the clock, inject the storage, inspect and seed records.
+- **Small & safe** — ~3 kB gzip core, versioned self-pruning record format, corrupt storage degrades instead of throwing.
+
+## Install
+
+```sh
+npm install fatigue-kit
+```
+
+## Quick start (Web)
+
+```ts
+import { createFatigue } from 'fatigue-kit'
+import { localStorageAdapter } from 'fatigue-kit/adapters/local-storage'
+
+const fatigue = createFatigue({ storage: localStorageAdapter() })
+
+const result = fatigue.tryConsume('coupon-popup', [
+  { max: 1, every: 'day' }, // once per calendar day
+  { max: 3, window: '7d' }, // at most 3 times in any rolling 7 days
+  { cooldown: '4h' }, // at least 4 hours between two showings
+])
+
+if (result.allowed) {
+  showCouponPopup()
+}
+```
+
+## Environments
+
+| Environment | Adapter | Import |
+| --- | --- | --- |
+| Web / H5 (persistent) | `localStorageAdapter()` | `fatigue-kit/adapters/local-storage` |
+| Web / H5 (per tab visit) | `sessionStorageAdapter()` | `fatigue-kit/adapters/session-storage` |
+| React Native | `asyncStorageAdapter(AsyncStorage)` | `fatigue-kit/adapters/async-storage` |
+| WeChat mini-program | `weappAdapter()` | `fatigue-kit/adapters/weapp` |
+| Alipay mini-program | `alipayAdapter()` | `fatigue-kit/adapters/alipay` |
+| Node.js (persistent) | `fileAdapter('./state.json')` | `fatigue-kit/adapters/node-file` |
+| Tests / SSR / default | `memoryAdapter()` (built in) | — |
+
+Anything with three synchronous functions is a valid adapter:
+
+```ts
+import type { SyncStorage } from 'fatigue-kit'
+const custom: SyncStorage = { get(key) { … }, set(key, value) { … }, remove(key) { … } }
+```
+
+### React Native
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { AppState } from 'react-native'
+import { createFatigue } from 'fatigue-kit'
+import { asyncStorageAdapter } from 'fatigue-kit/adapters/async-storage'
+
+const handle = asyncStorageAdapter(AsyncStorage)
+await handle.ready // hydrate the cache once
+
+const fatigue = createFatigue({ storage: handle.storage })
+
+AppState.addEventListener('change', (state) => {
+  if (state === 'background') handle.flush() // don't lose the last writes
+})
+```
+
+### Mini-programs
+
+Enable **构建 npm** in the devtools, then `require('fatigue-kit/adapters/weapp')` — CommonJS subpaths are shipped for exactly this. No `DOM` assumptions anywhere in the core.
+
+## API
+
+### `createFatigue(options?)`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `storage` | `memoryAdapter()` | Any `SyncStorage` |
+| `clock` | system time | `{ now(): number }`, inject in tests |
+| `namespace` | `'fatigue-kit'` | Prefix for storage keys |
+| `maxHits` | `100` | Hits kept per record; older ones are pruned |
+
+### Methods
+
+- `tryConsume(key, rules)` — atomically check and consume. Returns `{ allowed, remaining, nextAvailableAt?, deniedBy? }`. `remaining` describes the state **after** the call: `remaining === 0` means "that was the last allowed consumption". `peek` reports the current state.
+- `peek(key, rules)` — same result, without consuming.
+- `reset(key?)` — forget one key, or all keys (needs `storage.keys()`).
+- `exportRecord(key)` / `importRecord(key, record)` — inspect and seed records (migrations, debugging).
+
+### Rules
+
+| Rule | Meaning |
+| --- | --- |
+| `{ max: 1, every: 'day' }` | Once per calendar day (local time) |
+| `{ max: 1, every: 'day', cutoff: '04:00' }` | Calendar day that starts at 04:00 |
+| `{ max: 3, window: '7d' }` | At most 3 in any rolling 7 days |
+| `{ cooldown: '4h' }` | At least 4 hours between two occurrences |
+| `{ max: 5 }` | At most 5 times, ever |
+| `every: 'week'` / `'month'` / `'year'`, `weekStartsOn` | Calendar periods |
+
+Durations accept `'45s' / '30m' / '12h' / '7d'` or milliseconds. Calendar math uses local date components, so DST transitions never shift a boundary.
+
+## Migrating legacy records
+
+Coming from a legacy `{ times, date, duration, todayCount }` store?
+
+```ts
+import { migrateLegacyRecord } from 'fatigue-kit/legacy'
+
+const migrated = migrateLegacyRecord(rawLegacyValue)
+if (migrated) {
+  fatigue.importRecord(key, migrated.record)
+  // Keep the old "cooldown after last show" behaviour:
+  const rules = [{ max: 1, window: '7d' }]
+  if (migrated.cooldownMs !== null) rules.push({ cooldown: migrated.cooldownMs })
+}
+```
+
+## Testing your rules
+
+```ts
+import { createFatigue } from 'fatigue-kit'
+const clock = { current: 0, now: () => clock.current }
+const fatigue = createFatigue({ storage: memoryAdapter(), clock })
+fatigue.tryConsume('popup', [{ max: 1, every: 'day' }])
+clock.current = Number.MAX_SAFE_INTEGER // travel to the end of time
+expect(fatigue.peek('popup', [{ max: 1, every: 'day' }]).allowed).toBe(true)
+```
+
+## Known limitations (v1)
+
+- Reads are atomic within one JS context; **cross-tab / cross-process** races are last-write-wins (a `BroadcastChannel`-based mode is on the roadmap).
+- Calendar rules use device local time; IANA timezone support is planned.
+- The RN adapter needs a `flush()` call on app-background to guarantee durability.
+
+## Roadmap
+
+- `@fatigue-kit/react` — `useFatigue()` hook bindings
+- Group budgets — "all marketing popups together, max 3 per day", with priorities
+- Cross-tab consistency, IANA timezone support, debug inspector
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Design decisions and the full migration plan (中文): [docs/design.zh-CN.md](./docs/design.zh-CN.md).
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,160 @@
+# fatigue-kit
+
+[English](./README.md) | 简体中文
+
+> 零依赖的前端频控（疲劳度控制）库，覆盖 Web、小程序、React Native 和 Node.js。
+
+`fatigue-kit` 只回答一个问题：**这个弹窗 / toast / 引导 / 优惠，现在能不能出？**
+用可组合的规则 + 可替换的存储，在所有 JS 运行时里给出同步、原子的答案。
+
+## 特性
+
+- **规则可组合** —— 自然日 / 周 / 月（可设日界线）、滑动窗口、冷却、终身上限。任意叠加，以最严为准。
+- **原子 `tryConsume`** —— 检查与计数在同一步同步完成，连续触发不会双弹。
+- **全环境、按需加载** —— 零依赖核心，存储适配器按子路径引入：`localStorage`、`sessionStorage`、React Native `AsyncStorage`、微信 / 支付宝小程序、Node.js 文件。bundler 只打包你 import 的部分。
+- **可测试** —— 时钟可注入、存储可注入，记录可检查、可灌入。
+- **小而稳** —— 核心 gzip 约 3 kB；记录格式带版本号并自动修剪；存储损坏时优雅降级而不是抛错。
+
+## 安装
+
+```sh
+npm install fatigue-kit
+```
+
+## 快速开始（Web）
+
+```ts
+import { createFatigue } from 'fatigue-kit'
+import { localStorageAdapter } from 'fatigue-kit/adapters/local-storage'
+
+const fatigue = createFatigue({ storage: localStorageAdapter() })
+
+const result = fatigue.tryConsume('coupon-popup', [
+  { max: 1, every: 'day' }, // 每个自然日最多 1 次
+  { max: 3, window: '7d' }, // 任意滚动 7 天内最多 3 次
+  { cooldown: '4h' }, // 两次之间至少间隔 4 小时
+])
+
+if (result.allowed) {
+  showCouponPopup()
+}
+```
+
+## 环境支持
+
+| 环境 | 适配器 | 引入路径 |
+| --- | --- | --- |
+| Web / H5（持久） | `localStorageAdapter()` | `fatigue-kit/adapters/local-storage` |
+| Web / H5（每次访问） | `sessionStorageAdapter()` | `fatigue-kit/adapters/session-storage` |
+| React Native | `asyncStorageAdapter(AsyncStorage)` | `fatigue-kit/adapters/async-storage` |
+| 微信小程序 | `weappAdapter()` | `fatigue-kit/adapters/weapp` |
+| 支付宝小程序 | `alipayAdapter()` | `fatigue-kit/adapters/alipay` |
+| Node.js（持久） | `fileAdapter('./state.json')` | `fatigue-kit/adapters/node-file` |
+| 测试 / SSR / 默认 | `memoryAdapter()`（内置） | — |
+
+只要实现三个同步函数，就是合法的适配器：
+
+```ts
+import type { SyncStorage } from 'fatigue-kit'
+const custom: SyncStorage = { get(key) { … }, set(key, value) { … }, remove(key) { … } }
+```
+
+### React Native
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import { AppState } from 'react-native'
+import { createFatigue } from 'fatigue-kit'
+import { asyncStorageAdapter } from 'fatigue-kit/adapters/async-storage'
+
+const handle = asyncStorageAdapter(AsyncStorage)
+await handle.ready // 一次性预载缓存
+
+const fatigue = createFatigue({ storage: handle.storage })
+
+AppState.addEventListener('change', (state) => {
+  if (state === 'background') handle.flush() // 别丢掉最后的写入
+})
+```
+
+### 小程序
+
+在开发者工具里开启 **构建 npm**，然后 `require('fatigue-kit/adapters/weapp')` —— CommonJS 子路径就是为这个场景发的。核心代码不做任何 `DOM` 假设。
+
+## API
+
+### `createFatigue(options?)`
+
+| 选项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `storage` | `memoryAdapter()` | 任意 `SyncStorage` 实现 |
+| `clock` | 系统时间 | `{ now(): number }`，测试时注入 |
+| `namespace` | `'fatigue-kit'` | 存储 key 前缀 |
+| `maxHits` | `100` | 每条记录保留的最大命中数，更旧的会被修剪 |
+
+### 方法
+
+- `tryConsume(key, rules)` —— 原子地检查并消费。返回 `{ allowed, remaining, nextAvailableAt?, deniedBy? }`。`remaining` 描述**本次调用之后**的状态：`remaining === 0` 表示"刚才是最后一次"；`peek` 返回当前状态。
+- `peek(key, rules)` —— 结果相同，但不消费。
+- `reset(key?)` —— 清除一个 key，或不传参数清除全部（需要 `storage.keys()`）。
+- `exportRecord(key)` / `importRecord(key, record)` —— 读取与灌入记录（迁移、调试用）。
+
+### 规则
+
+| 规则 | 含义 |
+| --- | --- |
+| `{ max: 1, every: 'day' }` | 每个自然日（本地时间）最多 1 次 |
+| `{ max: 1, every: 'day', cutoff: '04:00' }` | 从凌晨 4 点起算的"业务日" |
+| `{ max: 3, window: '7d' }` | 任意滚动 7 天内最多 3 次 |
+| `{ cooldown: '4h' }` | 两次之间至少间隔 4 小时 |
+| `{ max: 5 }` | 终身最多 5 次 |
+| `every: 'week'` / `'month'` / `'year'`、`weekStartsOn` | 日历周期 |
+
+时长支持 `'45s' / '30m' / '12h' / '7d'` 或毫秒数。日历运算全部基于本地日期分量，夏令时切换不会移动边界。
+
+## 迁移旧数据
+
+从旧版 `{ times, date, duration, todayCount }` 存储迁移？
+
+```ts
+import { migrateLegacyRecord } from 'fatigue-kit/legacy'
+
+const migrated = migrateLegacyRecord(rawLegacyValue)
+if (migrated) {
+  fatigue.importRecord(key, migrated.record)
+  // 保持旧的"最后一次展示后冷却 N 天"行为：
+  const rules = [{ max: 1, window: '7d' }]
+  if (migrated.cooldownMs !== null) rules.push({ cooldown: migrated.cooldownMs })
+}
+```
+
+## 测试你的规则
+
+```ts
+import { createFatigue } from 'fatigue-kit'
+const clock = { current: 0, now: () => clock.current }
+const fatigue = createFatigue({ storage: memoryAdapter(), clock })
+fatigue.tryConsume('popup', [{ max: 1, every: 'day' }])
+clock.current = Number.MAX_SAFE_INTEGER // 时间旅行到世界末日
+expect(fatigue.peek('popup', [{ max: 1, every: 'day' }]).allowed).toBe(true)
+```
+
+## 已知限制（v1）
+
+- 读取在单个 JS 上下文内原子；**跨 tab / 跨进程**是 last-write-wins（基于 `BroadcastChannel` 的方案在路线图上）。
+- 日历规则跟随设备本地时间；IANA 时区支持在计划中。
+- RN 适配器需要在退后台时调用一次 `flush()` 才能保证写入落盘。
+
+## 路线图
+
+- `@fatigue-kit/react` —— `useFatigue()` Hook 绑定
+- 分组预算 —— "所有营销弹窗合计每天最多 3 个"，带优先级仲裁
+- 跨 tab 一致性、IANA 时区支持、调试面板
+
+## 参与贡献
+
+见 [CONTRIBUTING.md](./CONTRIBUTING.md)。完整设计决策与迁移计划见 [docs/design.zh-CN.md](./docs/design.zh-CN.md)。
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/adapters/alipay.cjs

@@ -0,0 +1,52 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/adapters/alipay.ts
+function alipayAdapter(options = {}) {
+  var _a, _b;
+  const client = (_a = options.client) != null ? _a : typeof my !== "undefined" && my !== null ? my : void 0;
+  if (client === void 0) {
+    throw new Error(
+      "[fatigue-kit] alipayAdapter: no `my` global found. Pass `{ client }` explicitly when not running inside Alipay."
+    );
+  }
+  const onError = (_b = options.onError) != null ? _b : ((error) => {
+    console.warn("[fatigue-kit] alipay storage operation failed:", error);
+  });
+  return {
+    get(key) {
+      try {
+        const response = client.getStorageSync({ key });
+        const data = response == null ? void 0 : response.data;
+        return typeof data === "string" && data.length > 0 ? data : null;
+      } catch (error) {
+        onError(error);
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        client.setStorageSync({ key, data: value });
+      } catch (error) {
+        onError(error);
+      }
+    },
+    remove(key) {
+      try {
+        client.removeStorageSync({ key });
+      } catch (error) {
+        onError(error);
+      }
+    },
+    keys() {
+      var _a2, _b2;
+      try {
+        return (_b2 = (_a2 = client.getStorageInfoSync) == null ? void 0 : _a2.call(client).keys) != null ? _b2 : [];
+      } catch (error) {
+        onError(error);
+        return [];
+      }
+    }
+  };
+}
+
+
+exports.alipayAdapter = alipayAdapter;
+//# sourceMappingURL=alipay.cjs.map

package/dist/adapters/alipay.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/fatigue-kit/fatigue-kit/dist/adapters/alipay.cjs","../../src/adapters/alipay.ts"],"names":["_a","_b"],"mappings":"AAAA;ACmBO,SAAS,aAAA,CAAc,QAAA,EAAgC,CAAC,CAAA,EAAgB;AAnB/E,EAAA,IAAA,EAAA,EAAA,EAAA;AAoBC,EAAA,MAAM,OAAA,EAAA,CAAS,GAAA,EAAA,OAAA,CAAQ,MAAA,EAAA,GAAR,KAAA,EAAA,GAAA,EAAmB,OAAO,GAAA,IAAO,YAAA,GAAe,GAAA,IAAO,KAAA,EAAO,GAAA,EAAK,KAAA,CAAA;AAClF,EAAA,GAAA,CAAI,OAAA,IAAW,KAAA,CAAA,EAAW;AACzB,IAAA,MAAM,IAAI,KAAA;AAAA,MACT;AAAA,IACD,CAAA;AAAA,EACD;AACA,EAAA,MAAM,QAAA,EAAA,CACL,GAAA,EAAA,OAAA,CAAQ,OAAA,EAAA,GAAR,KAAA,EAAA,GAAA,EAAA,CACC,CAAC,KAAA,EAAA,GAAmB;AACpB,IAAA,OAAA,CAAQ,IAAA,CAAK,gDAAA,EAAkD,KAAK,CAAA;AAAA,EACrE,CAAA,CAAA;AACD,EAAA,OAAO;AAAA,IACN,GAAA,CAAI,GAAA,EAAK;AACR,MAAA,IAAI;AACH,QAAA,MAAM,SAAA,EAAW,MAAA,CAAO,cAAA,CAAe,EAAE,IAAI,CAAC,CAAA;AAC9C,QAAA,MAAM,KAAA,EAAO,SAAA,GAAA,KAAA,EAAA,KAAA,EAAA,EAAA,QAAA,CAAU,IAAA;AACvB,QAAA,OAAO,OAAO,KAAA,IAAS,SAAA,GAAY,IAAA,CAAK,OAAA,EAAS,EAAA,EAAI,KAAA,EAAO,IAAA;AAAA,MAC7D,EAAA,MAAA,CAAS,KAAA,EAAO;AACf,QAAA,OAAA,CAAQ,KAAK,CAAA;AACb,QAAA,OAAO,IAAA;AAAA,MACR;AAAA,IACD,CAAA;AAAA,IACA,GAAA,CAAI,GAAA,EAAK,KAAA,EAAO;AACf,MAAA,IAAI;AACH,QAAA,MAAA,CAAO,cAAA,CAAe,EAAE,GAAA,EAAK,IAAA,EAAM,MAAM,CAAC,CAAA;AAAA,MAC3C,EAAA,MAAA,CAAS,KAAA,EAAO;AACf,QAAA,OAAA,CAAQ,KAAK,CAAA;AAAA,MACd;AAAA,IACD,CAAA;AAAA,IACA,MAAA,CAAO,GAAA,EAAK;AACX,MAAA,IAAI;AACH,QAAA,MAAA,CAAO,iBAAA,CAAkB,EAAE,IAAI,CAAC,CAAA;AAAA,MACjC,EAAA,MAAA,CAAS,KAAA,EAAO;AACf,QAAA,OAAA,CAAQ,KAAK,CAAA;AAAA,MACd;AAAA,IACD,CAAA;AAAA,IACA,IAAA,CAAA,EAAO;AAxDT,MAAA,IAAAA,GAAAA,EAAAC,GAAAA;AAyDG,MAAA,IAAI;AACH,QAAA,OAAA,CAAOA,IAAAA,EAAAA,CAAAD,IAAAA,EAAA,MAAA,CAAO,kBAAA,EAAA,GAAP,KAAA,EAAA,KAAA,EAAA,EAAAA,GAAAA,CAAA,IAAA,CAAA,MAAA,CAAA,CAA8B,IAAA,EAAA,GAA9B,KAAA,EAAAC,IAAAA,EAAsC,CAAC,CAAA;AAAA,MAC/C,EAAA,MAAA,CAAS,KAAA,EAAO;AACf,QAAA,OAAA,CAAQ,KAAK,CAAA;AACb,QAAA,OAAO,CAAC,CAAA;AAAA,MACT;AAAA,IACD;AAAA,EACD,CAAA;AACD;ADjBA;AACE;AACF,sCAAC","file":"/home/runner/work/fatigue-kit/fatigue-kit/dist/adapters/alipay.cjs","sourcesContent":[null,"import type { SyncStorage } from '../types'\n\n/** Alipay mini-program storage API (object arguments, values wrapped in `{ data }`). */\nexport interface AlipayStorageLike {\n\tgetStorageSync(options: { key: string }): unknown\n\tsetStorageSync(options: { key: string; data: string }): void\n\tremoveStorageSync(options: { key: string }): void\n\tgetStorageInfoSync?(): { keys?: string[] }\n}\n\nexport interface AlipayAdapterOptions {\n\t/** Defaults to the `my` global; inject explicitly in tests or abstractions. */\n\tclient?: AlipayStorageLike\n\tonError?: (error: unknown) => void\n}\n\ndeclare const my: AlipayStorageLike | undefined\n\n/** Alipay mini-program adapter backed by `my.getStorageSync` & friends. */\nexport function alipayAdapter(options: AlipayAdapterOptions = {}): SyncStorage {\n\tconst client = options.client ?? (typeof my !== 'undefined' && my !== null ? my : undefined)\n\tif (client === undefined) {\n\t\tthrow new Error(\n\t\t\t'[fatigue-kit] alipayAdapter: no `my` global found. Pass `{ client }` explicitly when not running inside Alipay.',\n\t\t)\n\t}\n\tconst onError =\n\t\toptions.onError ??\n\t\t((error: unknown) => {\n\t\t\tconsole.warn('[fatigue-kit] alipay storage operation failed:', error)\n\t\t})\n\treturn {\n\t\tget(key) {\n\t\t\ttry {\n\t\t\t\tconst response = client.getStorageSync({ key }) as { data?: unknown } | null | undefined\n\t\t\t\tconst data = response?.data\n\t\t\t\treturn typeof data === 'string' && data.length > 0 ? data : null\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t\treturn null\n\t\t\t}\n\t\t},\n\t\tset(key, value) {\n\t\t\ttry {\n\t\t\t\tclient.setStorageSync({ key, data: value })\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t}\n\t\t},\n\t\tremove(key) {\n\t\t\ttry {\n\t\t\t\tclient.removeStorageSync({ key })\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t}\n\t\t},\n\t\tkeys() {\n\t\t\ttry {\n\t\t\t\treturn client.getStorageInfoSync?.().keys ?? []\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t\treturn []\n\t\t\t}\n\t\t},\n\t}\n}\n"]}

package/dist/adapters/alipay.d.cts

@@ -0,0 +1,28 @@
+import { SyncStorage } from '../index.cjs';
+
+/** Alipay mini-program storage API (object arguments, values wrapped in `{ data }`). */
+interface AlipayStorageLike {
+    getStorageSync(options: {
+        key: string;
+    }): unknown;
+    setStorageSync(options: {
+        key: string;
+        data: string;
+    }): void;
+    removeStorageSync(options: {
+        key: string;
+    }): void;
+    getStorageInfoSync?(): {
+        keys?: string[];
+    };
+}
+interface AlipayAdapterOptions {
+    /** Defaults to the `my` global; inject explicitly in tests or abstractions. */
+    client?: AlipayStorageLike;
+    onError?: (error: unknown) => void;
+}
+/** Alipay mini-program adapter backed by `my.getStorageSync` & friends. */
+declare function alipayAdapter(options?: AlipayAdapterOptions): SyncStorage;
+
+export { alipayAdapter };
+export type { AlipayAdapterOptions, AlipayStorageLike };

package/dist/adapters/alipay.d.ts

@@ -0,0 +1,28 @@
+import { SyncStorage } from '../index.js';
+
+/** Alipay mini-program storage API (object arguments, values wrapped in `{ data }`). */
+interface AlipayStorageLike {
+    getStorageSync(options: {
+        key: string;
+    }): unknown;
+    setStorageSync(options: {
+        key: string;
+        data: string;
+    }): void;
+    removeStorageSync(options: {
+        key: string;
+    }): void;
+    getStorageInfoSync?(): {
+        keys?: string[];
+    };
+}
+interface AlipayAdapterOptions {
+    /** Defaults to the `my` global; inject explicitly in tests or abstractions. */
+    client?: AlipayStorageLike;
+    onError?: (error: unknown) => void;
+}
+/** Alipay mini-program adapter backed by `my.getStorageSync` & friends. */
+declare function alipayAdapter(options?: AlipayAdapterOptions): SyncStorage;
+
+export { alipayAdapter };
+export type { AlipayAdapterOptions, AlipayStorageLike };

package/dist/adapters/alipay.js

@@ -0,0 +1,52 @@
+// src/adapters/alipay.ts
+function alipayAdapter(options = {}) {
+  var _a, _b;
+  const client = (_a = options.client) != null ? _a : typeof my !== "undefined" && my !== null ? my : void 0;
+  if (client === void 0) {
+    throw new Error(
+      "[fatigue-kit] alipayAdapter: no `my` global found. Pass `{ client }` explicitly when not running inside Alipay."
+    );
+  }
+  const onError = (_b = options.onError) != null ? _b : ((error) => {
+    console.warn("[fatigue-kit] alipay storage operation failed:", error);
+  });
+  return {
+    get(key) {
+      try {
+        const response = client.getStorageSync({ key });
+        const data = response == null ? void 0 : response.data;
+        return typeof data === "string" && data.length > 0 ? data : null;
+      } catch (error) {
+        onError(error);
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        client.setStorageSync({ key, data: value });
+      } catch (error) {
+        onError(error);
+      }
+    },
+    remove(key) {
+      try {
+        client.removeStorageSync({ key });
+      } catch (error) {
+        onError(error);
+      }
+    },
+    keys() {
+      var _a2, _b2;
+      try {
+        return (_b2 = (_a2 = client.getStorageInfoSync) == null ? void 0 : _a2.call(client).keys) != null ? _b2 : [];
+      } catch (error) {
+        onError(error);
+        return [];
+      }
+    }
+  };
+}
+export {
+  alipayAdapter
+};
+//# sourceMappingURL=alipay.js.map

package/dist/adapters/alipay.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/alipay.ts"],"sourcesContent":["import type { SyncStorage } from '../types'\n\n/** Alipay mini-program storage API (object arguments, values wrapped in `{ data }`). */\nexport interface AlipayStorageLike {\n\tgetStorageSync(options: { key: string }): unknown\n\tsetStorageSync(options: { key: string; data: string }): void\n\tremoveStorageSync(options: { key: string }): void\n\tgetStorageInfoSync?(): { keys?: string[] }\n}\n\nexport interface AlipayAdapterOptions {\n\t/** Defaults to the `my` global; inject explicitly in tests or abstractions. */\n\tclient?: AlipayStorageLike\n\tonError?: (error: unknown) => void\n}\n\ndeclare const my: AlipayStorageLike | undefined\n\n/** Alipay mini-program adapter backed by `my.getStorageSync` & friends. */\nexport function alipayAdapter(options: AlipayAdapterOptions = {}): SyncStorage {\n\tconst client = options.client ?? (typeof my !== 'undefined' && my !== null ? my : undefined)\n\tif (client === undefined) {\n\t\tthrow new Error(\n\t\t\t'[fatigue-kit] alipayAdapter: no `my` global found. Pass `{ client }` explicitly when not running inside Alipay.',\n\t\t)\n\t}\n\tconst onError =\n\t\toptions.onError ??\n\t\t((error: unknown) => {\n\t\t\tconsole.warn('[fatigue-kit] alipay storage operation failed:', error)\n\t\t})\n\treturn {\n\t\tget(key) {\n\t\t\ttry {\n\t\t\t\tconst response = client.getStorageSync({ key }) as { data?: unknown } | null | undefined\n\t\t\t\tconst data = response?.data\n\t\t\t\treturn typeof data === 'string' && data.length > 0 ? data : null\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t\treturn null\n\t\t\t}\n\t\t},\n\t\tset(key, value) {\n\t\t\ttry {\n\t\t\t\tclient.setStorageSync({ key, data: value })\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t}\n\t\t},\n\t\tremove(key) {\n\t\t\ttry {\n\t\t\t\tclient.removeStorageSync({ key })\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t}\n\t\t},\n\t\tkeys() {\n\t\t\ttry {\n\t\t\t\treturn client.getStorageInfoSync?.().keys ?? []\n\t\t\t} catch (error) {\n\t\t\t\tonError(error)\n\t\t\t\treturn []\n\t\t\t}\n\t\t},\n\t}\n}\n"],"mappings":";AAmBO,SAAS,cAAc,UAAgC,CAAC,GAAgB;AAnB/E;AAoBC,QAAM,UAAS,aAAQ,WAAR,YAAmB,OAAO,OAAO,eAAe,OAAO,OAAO,KAAK;AAClF,MAAI,WAAW,QAAW;AACzB,UAAM,IAAI;AAAA,MACT;AAAA,IACD;AAAA,EACD;AACA,QAAM,WACL,aAAQ,YAAR,aACC,CAAC,UAAmB;AACpB,YAAQ,KAAK,kDAAkD,KAAK;AAAA,EACrE;AACD,SAAO;AAAA,IACN,IAAI,KAAK;AACR,UAAI;AACH,cAAM,WAAW,OAAO,eAAe,EAAE,IAAI,CAAC;AAC9C,cAAM,OAAO,qCAAU;AACvB,eAAO,OAAO,SAAS,YAAY,KAAK,SAAS,IAAI,OAAO;AAAA,MAC7D,SAAS,OAAO;AACf,gBAAQ,KAAK;AACb,eAAO;AAAA,MACR;AAAA,IACD;AAAA,IACA,IAAI,KAAK,OAAO;AACf,UAAI;AACH,eAAO,eAAe,EAAE,KAAK,MAAM,MAAM,CAAC;AAAA,MAC3C,SAAS,OAAO;AACf,gBAAQ,KAAK;AAAA,MACd;AAAA,IACD;AAAA,IACA,OAAO,KAAK;AACX,UAAI;AACH,eAAO,kBAAkB,EAAE,IAAI,CAAC;AAAA,MACjC,SAAS,OAAO;AACf,gBAAQ,KAAK;AAAA,MACd;AAAA,IACD;AAAA,IACA,OAAO;AAxDT,UAAAA,KAAAC;AAyDG,UAAI;AACH,gBAAOA,OAAAD,MAAA,OAAO,uBAAP,gBAAAA,IAAA,aAA8B,SAA9B,OAAAC,MAAsC,CAAC;AAAA,MAC/C,SAAS,OAAO;AACf,gBAAQ,KAAK;AACb,eAAO,CAAC;AAAA,MACT;AAAA,IACD;AAAA,EACD;AACD;","names":["_a","_b"]}

package/dist/adapters/async-storage.cjs

@@ -0,0 +1,93 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/adapters/async-storage.ts
+var DEFAULT_NAMESPACE = "fatigue-kit";
+var DEFAULT_FLUSH_DELAY = 50;
+function asyncStorageAdapter(client, options = {}) {
+  var _a, _b, _c;
+  const namespace = (_a = options.namespace) != null ? _a : DEFAULT_NAMESPACE;
+  const flushDelay = (_b = options.flushDelay) != null ? _b : DEFAULT_FLUSH_DELAY;
+  const onError = (_c = options.onError) != null ? _c : ((error) => {
+    console.warn("[fatigue-kit] async storage operation failed:", error);
+  });
+  const indexKey = `${namespace}:__index__`;
+  const cache = /* @__PURE__ */ new Map();
+  const pending = /* @__PURE__ */ new Map();
+  const index = /* @__PURE__ */ new Set();
+  let indexDirty = false;
+  let timer = null;
+  const safe = async (operation) => {
+    try {
+      return await operation();
+    } catch (error) {
+      onError(error);
+      return null;
+    }
+  };
+  const ready = (async () => {
+    const rawIndex = await safe(() => client.getItem(indexKey));
+    if (rawIndex !== null) {
+      try {
+        for (const key of JSON.parse(rawIndex)) index.add(key);
+      } catch (e) {
+      }
+    }
+    await Promise.all(
+      [...index].map(async (key) => {
+        cache.set(key, await safe(() => client.getItem(key)));
+      })
+    );
+  })();
+  async function flush() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    const writes = [...pending];
+    pending.clear();
+    await Promise.all(
+      writes.map(
+        ([key, value]) => value === null ? safe(() => client.removeItem(key)) : safe(() => client.setItem(key, value))
+      )
+    );
+    if (indexDirty) {
+      indexDirty = false;
+      await safe(() => client.setItem(indexKey, JSON.stringify([...index])));
+    }
+  }
+  function schedule() {
+    if (timer !== null) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, flushDelay);
+  }
+  const storage = {
+    get: (key) => {
+      var _a2;
+      return (_a2 = cache.get(key)) != null ? _a2 : null;
+    },
+    set: (key, value) => {
+      cache.set(key, value);
+      pending.set(key, value);
+      if (!index.has(key)) {
+        index.add(key);
+        indexDirty = true;
+      }
+      schedule();
+    },
+    remove: (key) => {
+      cache.delete(key);
+      pending.set(key, null);
+      if (index.has(key)) {
+        index.delete(key);
+        indexDirty = true;
+      }
+      schedule();
+    },
+    keys: () => [...index]
+  };
+  return { storage, ready, flush };
+}
+
+
+exports.asyncStorageAdapter = asyncStorageAdapter;
+//# sourceMappingURL=async-storage.cjs.map

package/dist/adapters/async-storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/fatigue-kit/fatigue-kit/dist/adapters/async-storage.cjs","../../src/adapters/async-storage.ts"],"names":["_a"],"mappings":"AAAA;AC6BA,IAAM,kBAAA,EAAoB,aAAA;AAC1B,IAAM,oBAAA,EAAsB,EAAA;AAqBrB,SAAS,mBAAA,CACf,MAAA,EACA,QAAA,EAAsC,CAAC,CAAA,EACjB;AAtDvB,EAAA,IAAA,EAAA,EAAA,EAAA,EAAA,EAAA;AAuDC,EAAA,MAAM,UAAA,EAAA,CAAY,GAAA,EAAA,OAAA,CAAQ,SAAA,EAAA,GAAR,KAAA,EAAA,GAAA,EAAqB,iBAAA;AACvC,EAAA,MAAM,WAAA,EAAA,CAAa,GAAA,EAAA,OAAA,CAAQ,UAAA,EAAA,GAAR,KAAA,EAAA,GAAA,EAAsB,mBAAA;AACzC,EAAA,MAAM,QAAA,EAAA,CACL,GAAA,EAAA,OAAA,CAAQ,OAAA,EAAA,GAAR,KAAA,EAAA,GAAA,EAAA,CACC,CAAC,KAAA,EAAA,GAAmB;AACpB,IAAA,OAAA,CAAQ,IAAA,CAAK,+CAAA,EAAiD,KAAK,CAAA;AAAA,EACpE,CAAA,CAAA;AACD,EAAA,MAAM,SAAA,EAAW,CAAA,EAAA;AACH,EAAA;AACE,EAAA;AACF,EAAA;AACG,EAAA;AACiC,EAAA;AAErC,EAAA;AACR,IAAA;AACU,MAAA;AACE,IAAA;AACF,MAAA;AACN,MAAA;AACR,IAAA;AACD,EAAA;AAEe,EAAA;AACR,IAAA;AACF,IAAA;AACC,MAAA;AACQ,QAAA;AACJ,MAAA;AAER,MAAA;AACD,IAAA;AACc,IAAA;AACF,MAAA;AACA,QAAA;AACV,MAAA;AACF,IAAA;AACE,EAAA;AAEY,EAAA;AACA,IAAA;AACA,MAAA;AACL,MAAA;AACT,IAAA;AACgB,IAAA;AACF,IAAA;AACA,IAAA;AACN,MAAA;AAAgB,QAAA;AAIvB,MAAA;AACD,IAAA;AACgB,IAAA;AACF,MAAA;AACF,MAAA;AACZ,IAAA;AACD,EAAA;AAES,EAAA;AACM,IAAA;AACN,IAAA;AACC,MAAA;AACG,MAAA;AACC,IAAA;AACd,EAAA;AAE6B,EAAA;AACjB,IAAA;AA3HbA,MAAAA;AA2HgB,MAAA;AAAkB,IAAA;AACrB,IAAA;AACA,MAAA;AACE,MAAA;AACD,MAAA;AACA,QAAA;AACV,QAAA;AACD,MAAA;AACS,MAAA;AACV,IAAA;AACS,IAAA;AACK,MAAA;AACD,MAAA;AACE,MAAA;AACP,QAAA;AACN,QAAA;AACD,MAAA;AACS,MAAA;AACV,IAAA;AACgB,IAAA;AACjB,EAAA;AAEkB,EAAA;AACnB;ADzDoB;AACA;AACA","file":"/home/runner/work/fatigue-kit/fatigue-kit/dist/adapters/async-storage.cjs","sourcesContent":[null,"import type { SyncStorage } from '../types'\n\n/**\n * Minimal interface shared by `@react-native-async-storage/async-storage` and\n * most RN-compatible storage libraries. Pass your storage instance directly.\n */\nexport interface AsyncStorageLike {\n\tgetItem(key: string): Promise<string | null>\n\tsetItem(key: string, value: string): Promise<void>\n\tremoveItem(key: string): Promise<void>\n}\n\nexport interface AsyncStorageAdapter {\n\t/** Synchronous view over the async backend. Only use it once `ready` resolved. */\n\tstorage: SyncStorage\n\t/** Resolves once the in-memory cache has been hydrated from the backend. */\n\tready: Promise<void>\n\t/** Persist pending writes now. Also runs automatically, debounced. */\n\tflush(): Promise<void>\n}\n\nexport interface AsyncStorageAdapterOptions {\n\t/** Must match the `namespace` of the fatigue instance. Default `'fatigue-kit'`. */\n\tnamespace?: string\n\t/** Debounce window for background flushes, ms. Default `50`. */\n\tflushDelay?: number\n\tonError?: (error: unknown) => void\n}\n\nconst DEFAULT_NAMESPACE = 'fatigue-kit'\nconst DEFAULT_FLUSH_DELAY = 50\n\n/**\n * React Native (and any async backend) adapter.\n *\n * The core engine is synchronous for atomicity, so this adapter hydrates all\n * known keys once up front (`ready`), serves reads from memory, and writes back\n * in debounced batches. An index key keeps track of which keys belong to\n * fatigue-kit. Call `flush()` from an `AppState` \"background\" listener so the\n * last writes survive an app kill.\n *\n * ```ts\n * import AsyncStorage from '@react-native-async-storage/async-storage'\n * const handle = asyncStorageAdapter(AsyncStorage)\n * await handle.ready\n * const fatigue = createFatigue({ storage: handle.storage })\n * AppState.addEventListener('change', (state) => {\n *   if (state === 'background') handle.flush()\n * })\n * ```\n */\nexport function asyncStorageAdapter(\n\tclient: AsyncStorageLike,\n\toptions: AsyncStorageAdapterOptions = {},\n): AsyncStorageAdapter {\n\tconst namespace = options.namespace ?? DEFAULT_NAMESPACE\n\tconst flushDelay = options.flushDelay ?? DEFAULT_FLUSH_DELAY\n\tconst onError =\n\t\toptions.onError ??\n\t\t((error: unknown) => {\n\t\t\tconsole.warn('[fatigue-kit] async storage operation failed:', error)\n\t\t})\n\tconst indexKey = `${namespace}:__index__`\n\tconst cache = new Map<string, string | null>()\n\tconst pending = new Map<string, string | null>()\n\tconst index = new Set<string>()\n\tlet indexDirty = false\n\tlet timer: ReturnType<typeof setTimeout> | null = null\n\n\tconst safe = async <T>(operation: () => Promise<T>): Promise<T | null> => {\n\t\ttry {\n\t\t\treturn await operation()\n\t\t} catch (error) {\n\t\t\tonError(error)\n\t\t\treturn null\n\t\t}\n\t}\n\n\tconst ready = (async () => {\n\t\tconst rawIndex = await safe(() => client.getItem(indexKey))\n\t\tif (rawIndex !== null) {\n\t\t\ttry {\n\t\t\t\tfor (const key of JSON.parse(rawIndex) as string[]) index.add(key)\n\t\t\t} catch {\n\t\t\t\t// Corrupt index: start empty; keys re-register on their next write.\n\t\t\t}\n\t\t}\n\t\tawait Promise.all(\n\t\t\t[...index].map(async (key) => {\n\t\t\t\tcache.set(key, await safe(() => client.getItem(key)))\n\t\t\t}),\n\t\t)\n\t})()\n\n\tasync function flush(): Promise<void> {\n\t\tif (timer !== null) {\n\t\t\tclearTimeout(timer)\n\t\t\ttimer = null\n\t\t}\n\t\tconst writes = [...pending]\n\t\tpending.clear()\n\t\tawait Promise.all(\n\t\t\twrites.map(([key, value]) =>\n\t\t\t\tvalue === null\n\t\t\t\t\t? safe(() => client.removeItem(key))\n\t\t\t\t\t: safe(() => client.setItem(key, value)),\n\t\t\t),\n\t\t)\n\t\tif (indexDirty) {\n\t\t\tindexDirty = false\n\t\t\tawait safe(() => client.setItem(indexKey, JSON.stringify([...index])))\n\t\t}\n\t}\n\n\tfunction schedule(): void {\n\t\tif (timer !== null) return\n\t\ttimer = setTimeout(() => {\n\t\t\ttimer = null\n\t\t\tvoid flush()\n\t\t}, flushDelay)\n\t}\n\n\tconst storage: SyncStorage = {\n\t\tget: (key) => cache.get(key) ?? null,\n\t\tset: (key, value) => {\n\t\t\tcache.set(key, value)\n\t\t\tpending.set(key, value)\n\t\t\tif (!index.has(key)) {\n\t\t\t\tindex.add(key)\n\t\t\t\tindexDirty = true\n\t\t\t}\n\t\t\tschedule()\n\t\t},\n\t\tremove: (key) => {\n\t\t\tcache.delete(key)\n\t\t\tpending.set(key, null)\n\t\t\tif (index.has(key)) {\n\t\t\t\tindex.delete(key)\n\t\t\t\tindexDirty = true\n\t\t\t}\n\t\t\tschedule()\n\t\t},\n\t\tkeys: () => [...index],\n\t}\n\n\treturn { storage, ready, flush }\n}\n"]}