fatigue-kit 0.0.0-stage → 0.2.0

package/dist/types-hDxN5bc3.d.ts

@@ -0,0 +1,89 @@
+/** Injectable clock so tests can freeze or accelerate time. */
+interface Clock {
+    now(): number;
+}
+/**
+ * Duration: a millisecond number, or a string like `'45s'`, `'30m'`, `'12h'`, `'7d'`.
+ */
+type Duration = number | string;
+/** At most `max` occurrences within a sliding window. */
+interface SlidingWindowRule {
+    max: number;
+    window: Duration;
+}
+/** At most `max` occurrences per calendar period, evaluated in device local time. */
+interface CalendarRule {
+    max: number;
+    every: 'day' | 'week' | 'month' | 'year';
+    /** Period boundary offset in local time, `'HH:mm'`. Default `'00:00'`. */
+    cutoff?: string;
+    /** First weekday: `0` = Sunday … `6` = Saturday. Default `1` (Monday). */
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+}
+/** Two occurrences must be at least `cooldown` apart. */
+interface CooldownRule {
+    cooldown: Duration;
+}
+/** At most `max` occurrences, ever. */
+interface LifetimeRule {
+    max: number;
+}
+type FatigueRule = SlidingWindowRule | CalendarRule | CooldownRule | LifetimeRule;
+interface ConsumeResult {
+    allowed: boolean;
+    /**
+     * How many more times the key may be consumed under the strictest count-based
+     * rule. `Infinity` when no count-based rule applies (e.g. a cooldown-only key).
+     */
+    remaining: number;
+    /** Earliest timestamp (ms) at which the key may be consumed again. Absent while allowed. */
+    nextAvailableAt?: number;
+    /** The first rule that caused the denial. */
+    deniedBy?: FatigueRule;
+}
+/**
+ * A synchronous string key-value store. Every built-in adapter implements this,
+ * and so can yours — this is the only contract `createFatigue` relies on.
+ */
+interface SyncStorage {
+    get(key: string): string | null | undefined;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    /**
+     * Optional: list all keys known to this storage.
+     * Enables `fatigue.reset()` without a key.
+     */
+    keys?(): string[];
+}
+/** Serialized fatigue record. `hits` are ascending timestamps in ms. */
+interface FatigueRecord {
+    /** Record format version. */
+    v: number;
+    hits: number[];
+    /** Total consumption count, ever. Survives pruning. */
+    lifetime: number;
+}
+interface FatigueOptions {
+    /** Backing storage. Defaults to an in-memory store. */
+    storage?: SyncStorage;
+    /** Clock. Defaults to the real system time. */
+    clock?: Clock;
+    /** Prefix for storage keys. Default `'fatigue-kit'`. */
+    namespace?: string;
+    /** Maximum hits kept per record; older ones are pruned on write. Default `100`. */
+    maxHits?: number;
+}
+interface Fatigue {
+    /** Atomically check the rules and, when allowed, consume one occurrence. */
+    tryConsume(key: string, rules: FatigueRule | FatigueRule[]): ConsumeResult;
+    /** Check the rules without consuming. */
+    peek(key: string, rules: FatigueRule | FatigueRule[]): ConsumeResult;
+    /** Drop one key, or every key when omitted (requires `storage.keys`). */
+    reset(key?: string): void;
+    /** Read the raw record of a key. `null` when absent. */
+    exportRecord(key: string): FatigueRecord | null;
+    /** Overwrite the record of a key (used for migrations and debugging). */
+    importRecord(key: string, record: Partial<FatigueRecord>): void;
+}
+
+export type { CalendarRule as C, Duration as D, FatigueOptions as F, LifetimeRule as L, SyncStorage as S, Fatigue as a, Clock as b, ConsumeResult as c, CooldownRule as d, FatigueRecord as e, FatigueRule as f, SlidingWindowRule as g };

package/dist/web-GiaS0cnX.d.cts

@@ -0,0 +1,8 @@
+interface WebStorageAdapterOptions {
+    /** Underlying `Storage`. Defaults to the platform global, resolved lazily. */
+    storage?: Storage;
+    /** Called when the underlying storage throws (quota, private mode, …). */
+    onError?: (error: unknown) => void;
+}
+
+export type { WebStorageAdapterOptions as W };

package/dist/web-GiaS0cnX.d.ts

@@ -0,0 +1,8 @@
+interface WebStorageAdapterOptions {
+    /** Underlying `Storage`. Defaults to the platform global, resolved lazily. */
+    storage?: Storage;
+    /** Called when the underlying storage throws (quota, private mode, …). */
+    onError?: (error: unknown) => void;
+}
+
+export type { WebStorageAdapterOptions as W };

package/package.json

@@ -1,6 +1,134 @@
 {
   "name": "fatigue-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Zero-dependency frequency capping (疲劳度控制) for popups, toasts and guides — one composable API across Web, mini-programs, React Native and Node.js.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/global/index.global.js",
+  "jsdelivr": "./dist/global/index.global.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./legacy": {
+      "types": "./dist/legacy.d.ts",
+      "import": "./dist/legacy.js",
+      "require": "./dist/legacy.cjs"
+    },
+    "./adapters/memory": {
+      "types": "./dist/adapters/memory.d.ts",
+      "import": "./dist/adapters/memory.js",
+      "require": "./dist/adapters/memory.cjs"
+    },
+    "./adapters/local-storage": {
+      "types": "./dist/adapters/local-storage.d.ts",
+      "import": "./dist/adapters/local-storage.js",
+      "require": "./dist/adapters/local-storage.cjs"
+    },
+    "./adapters/session-storage": {
+      "types": "./dist/adapters/session-storage.d.ts",
+      "import": "./dist/adapters/session-storage.js",
+      "require": "./dist/adapters/session-storage.cjs"
+    },
+    "./adapters/async-storage": {
+      "types": "./dist/adapters/async-storage.d.ts",
+      "import": "./dist/adapters/async-storage.js",
+      "require": "./dist/adapters/async-storage.cjs"
+    },
+    "./adapters/weapp": {
+      "types": "./dist/adapters/weapp.d.ts",
+      "import": "./dist/adapters/weapp.js",
+      "require": "./dist/adapters/weapp.cjs"
+    },
+    "./adapters/alipay": {
+      "types": "./dist/adapters/alipay.d.ts",
+      "import": "./dist/adapters/alipay.js",
+      "require": "./dist/adapters/alipay.cjs"
+    },
+    "./adapters/node-file": {
+      "types": "./dist/adapters/node-file.d.ts",
+      "import": "./dist/adapters/node-file.js",
+      "require": "./dist/adapters/node-file.cjs"
+    },
+    "./global": "./dist/global/index.global.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src test",
+    "format": "biome check --write src test",
+    "size": "size-limit",
+    "changeset": "changeset",
+    "prepublishOnly": "npm run build"
+  },
+  "size-limit": [
+    {
+      "name": "core",
+      "path": "dist/index.js",
+      "import": "{ createFatigue }",
+      "limit": "3.5 kB"
+    },
+    {
+      "name": "web adapter",
+      "path": "dist/adapters/local-storage.js",
+      "import": "{ localStorageAdapter }",
+      "limit": "4 kB"
+    },
+    {
+      "name": "weapp adapter",
+      "path": "dist/adapters/weapp.js",
+      "import": "{ weappAdapter }",
+      "limit": "4 kB"
+    }
+  ],
+  "keywords": [
+    "frequency-capping",
+    "fatigue",
+    "疲劳度",
+    "popup",
+    "toast",
+    "rate-limit",
+    "cooldown",
+    "mini-program",
+    "weapp",
+    "react-native",
+    "storage"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SoraYama/fatigue-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SoraYama/fatigue-kit/issues"
+  },
+  "homepage": "https://github.com/SoraYama/fatigue-kit#readme",
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@changesets/changelog-github": "^1.0.1",
+    "@changesets/cli": "^2.29.0",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@types/node": "26.6.5",
+    "size-limit": "^11.2.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}