Skip to content

Commit 23c9387

Browse files
rockyshi1993rockyshi1993
committed
build: add CHANGELOG, README, CI workflow, docs site and fix CJS build config
Build fixes: - tsconfig.cjs.json: standalone config (no extends), noEmitOnError:false, fixes TS5069 - scripts/build-cjs.mjs: post-build patch replacing import.meta.url with __filename for CJS runtime compatibility Documentation: - CHANGELOG.md: v1.0.0 full release notes - README.md: publication-quality docs (installation, quickstart, module reference, API, testing) - website/: Rspress docs site (index, getting-started, api-reference guides) CI: - .github/workflows/ci.yml: unit-test job (Node 18/20/22 matrix, coverage gate) + integration-test job (Redis 7 service) Dependencies: - package.json: add rspress ^1.47.1, docs:dev/build/preview scripts - package-lock.json: fresh lockfile (removed stale lockfile that caused npm arborist Invalid Version bug)
1 parent a9e293d commit 23c9387

13 files changed

Lines changed: 11054 additions & 11 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, "feat/**", "fix/**"]
6+
pull_request:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
# ────────────────────────────────────────────────────────────────────────────
15+
# Job 1: 单元测试 + 覆盖率门禁
16+
# ────────────────────────────────────────────────────────────────────────────
17+
unit-test:
18+
name: Unit Tests & Coverage
19+
runs-on: ubuntu-latest
20+
21+
strategy:
22+
matrix:
23+
node-version: [18, 20, 22]
24+
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Node.js ${{ matrix.node-version }}
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: ${{ matrix.node-version }}
33+
cache: npm
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Type check
39+
run: npm run typecheck
40+
41+
- name: Run unit tests with coverage
42+
run: npm run test:coverage
43+
44+
- name: Build (ESM + CJS + types)
45+
run: npm run build
46+
47+
# ────────────────────────────────────────────────────────────────────────────
48+
# Job 2: 集成测试（依赖 Redis 服务，可选）
49+
# 仅在 unit-test 全部通过后运行
50+
# ────────────────────────────────────────────────────────────────────────────
51+
integration-test:
52+
name: Integration Tests (Redis)
53+
runs-on: ubuntu-latest
54+
needs: unit-test
55+
56+
services:
57+
redis:
58+
image: redis:7-alpine
59+
ports:
60+
- 6379:6379
61+
options: >-
62+
--health-cmd "redis-cli ping"
63+
--health-interval 10s
64+
--health-timeout 5s
65+
--health-retries 5
66+
67+
steps:
68+
- name: Checkout
69+
uses: actions/checkout@v4
70+
71+
- name: Setup Node.js 20
72+
uses: actions/setup-node@v4
73+
with:
74+
node-version: 20
75+
cache: npm
76+
77+
- name: Install dependencies
78+
run: npm ci
79+
80+
- name: Run integration tests
81+
run: npm run test:integration
82+
env:
83+
REDIS_URL: redis://localhost:6379

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,9 @@ dist
134134
.yarn/build-state.yml
135135
.yarn/install-state.gz
136136
.pnp.*
137+
138+
# Rspress build output
139+
doc_build/
140+
141+
# Test coverage output
142+
coverage/

‎CHANGELOG.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
---
9+
10+
## [1.0.0] - 2026-03-22
11+
12+
首个正式发布版本。零运行时依赖的 Node.js 多层缓存库，统一工作区所有项目的缓存基础设施。
13+
14+
### Added（新增）
15+
16+
#### 核心类型与接口（`cache-hub`）
17+
- 新增 `CacheLike` 接口：定义统一缓存契约，覆盖 `get / set / del / exists / has / clear / keys / getMany / setMany / delMany / delPattern / getStats / destroy` 共 13 个方法
18+
- 新增 `CacheStats` 类型：统一统计信息结构（`hits / misses / sets / deletes / evictions / memoryUsage / hitRate`）
19+
- 新增 `MemoryCacheOptions` 配置类型
20+
21+
#### MemoryCache（`cache-hub`）
22+
- 基于 ES6 `Map` 实现的 O(1) LRU 淘汰引擎
23+
- TTL 支持：惰性过期（`get` 时判断）+ 可选周期清理（`cleanupInterval`）
24+
- 双重容量限制：`maxEntries`（条目数）+ `maxMemory`（字节估算）
25+
- 批量操作：`getMany / setMany / delMany`
26+
- 模式删除：`delPattern(pattern)`（`*` 通配符 → 正则）
27+
- 统计信息：`hits / misses / evictions / hitRate` 等，可通过 `enableStats` 开关
28+
- 标签索引：`enableTags=true` 时维护 `tagIndex`，支持 `invalidateByTag(tag)`
29+
- `enabled` 开关：`false` 时 `get` 返回 `undefined`，`set` 不写入
30+
- `destroy()`：清理周期定时器并清空缓存
31+
32+
#### stableStringify（`cache-hub/stringify`）
33+
- `stableStringify(value, options?)`：对象键字母排序、`NaN` 固定输出 `"__NaN__"`、循环引用输出 `"[CIRCULAR]"`
34+
- `RegExp` / `Date` 特殊处理，数组保序
35+
- `customSerializer` 插件钩子：支持 BSON ObjectId 等自定义类型扩展
36+
37+
#### readThrough（`cache-hub/read-through`）
38+
- `readThrough(cache, ttlMs, key, fetcher)`：缓存命中直返，未命中执行 fetcher 并写缓存
39+
- 并发去重（in-flight map）：相同 key 的并发请求共享同一 Promise
40+
- `ttl ≤ 0` 时直接执行 fetcher 不写缓存
41+
- 内置溢出保护（INFLIGHT_MAX_SIZE = 10000，超限清理最旧 10%）
42+
- 内置超时清理（INFLIGHT_TIMEOUT_MS = 300000ms，防止内存泄漏）
43+
- `undefined` 不写缓存，`null` 视为有效空值
44+
45+
#### MultiLevelCache（`cache-hub/multi-level`）
46+
- L1（本地）+ L2（远端）双层缓存，均接受 `CacheLike` 接口
47+
- 写策略：`'both'`（同步双写）/ `'local-first-async-remote'`（本地优先异步写远端）
48+
- 远端命中回填本地（`backfillOnRemoteHit`，默认开启，可关闭）
49+
- 远端操作超时保护（`remoteTimeoutMs`，默认 50ms，超时降级不报错）
50+
- 可选分布式失效广播回调（`publish?: (keys: string[]) => void`）
51+
52+
#### RedisCacheAdapter（`cache-hub/redis`）
53+
- `createRedisCacheAdapter(urlOrInstance)`：将 ioredis 实例包装为 `CacheLike`
54+
- 支持 URL 字符串初始化（自动创建 ioredis 连接）或传入已有实例
55+
- `delPattern / keys` 使用 SCAN 游标迭代，禁止 `KEYS` 命令（防阻塞）
56+
- `close()`：仅关闭自己创建的连接（外部传入的连接不关闭）
57+
- 超长 key（> 512 字节）自动 SHA-256 压缩，`pattern` 超长时截断并 `console.warn`
58+
- JSON 序列化存储，支持 `null` 作为有效缓存值
59+
60+
#### FunctionCache / withCache（`cache-hub/function-cache`）
61+
- `withCache(fn, options)`：装饰器，自动缓存异步函数返回值
62+
- 键生成：`namespace:fnName:stableStringify(args)`，超长键自动 SHA-256 压缩
63+
- 并发去重：相同参数的并发调用共享同一 Promise
64+
- 条件缓存：`condition(result)` 返回 `false` 时不写缓存
65+
- `FunctionCache` 类：支持 `register / execute / invalidate / getStats`，适合多函数统一管理
66+
- Per-function TTL / keyBuilder / condition 配置，可覆盖全局默认值
67+
68+
#### DistributedCacheInvalidator（`cache-hub/distributed`）
69+
- `DistributedCacheInvalidator`：基于 Redis Pub/Sub 的跨实例缓存失效广播
70+
- 自动过滤自身发出的消息（`instanceId` 隔离）
71+
- 支持监听多个本地缓存实例（`watchedCaches`）
72+
- 支持 `redisUrl` 字符串或已有 ioredis 连接两种初始化方式
73+
- `invalidate(keys)` / `close()` 生命周期管理
74+
- `getStats()` 返回发布/接收消息计数
75+
76+
### Build（构建）
77+
- ESM + CJS 双格式产出（`dist/esm/` + `dist/cjs/` + `dist/types/`）
78+
- 多入口按需导入：`cache-hub`、`cache-hub/redis`、`cache-hub/multi-level`、`cache-hub/function-cache`、`cache-hub/distributed`、`cache-hub/stringify`、`cache-hub/read-through`
79+
- CJS 产物兼容性修补：`import.meta.url` → `__filename`（`scripts/build-cjs.mjs`）
80+
- 零运行时依赖（`dependencies: {}`），ioredis 为可选 peerDependency（`>=5.0.0`）
81+
82+
### Tests（测试）
83+
- 440 个单元测试，全部通过，全维度覆盖率 100%（Statements / Branches / Functions / Lines）
84+
- 30 个集成测试（`test/integration/redis.integration.test.ts`），需本地 Redis 连接
85+
- 支持 `npm test`（单元）、`npm run test:integration`（集成，需 Redis）
86+
- 支持 `REDIS_URL` 环境变量自定义 Redis 地址，`SKIP_INTEGRATION=true` 跳过集成测试
87+
88+
---
89+
90+
## 格式说明
91+
92+
- **Added**：新功能
93+
- **Changed**：现有功能的非破坏性变更
94+
- **Fixed**：Bug 修复
95+
- **Deprecated**：已弃用功能（将在未来版本移除）
96+
- **Removed**：已移除功能（Major 版本）
97+
- **Security**：安全修复

0 commit comments

Comments
 (0)