milkio 1.3.74 → 1.3.75
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/cache/index.d.ts +83 -0
- package/index.d.ts +1 -0
- package/index.js +319 -3
- package/package.json +1 -1
- package/world/index.d.ts +13 -0
package/cache/index.d.ts
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* milkio 进程内缓存:KV、Memo、Bloom 三种模型。
|
|
3
|
+
*
|
|
4
|
+
* 设计要点:
|
|
5
|
+
*
|
|
6
|
+
* 1. 没有序列化。值原样存放在 Map 里,可以存对象、Date、类实例。
|
|
7
|
+
*
|
|
8
|
+
* 2. 过期有两条路径:
|
|
9
|
+
* - 惰性过期:读命中后发现已过期,立即删除并当作未命中(保证正确性);
|
|
10
|
+
* - 主动清理:请求末尾触发,按表级 intervalMs 节流,每批只取 16 条,
|
|
11
|
+
* 本批过期比例达到 25% 才继续下一批,单次总耗时不超过 16ms。
|
|
12
|
+
* 没有定时器:serverless 在请求之间会冻结 CPU,定时器不可靠。
|
|
13
|
+
*
|
|
14
|
+
* 3. 容量由 maxEntries 硬约束,写入时立即淘汰最旧的一条(LRU),
|
|
15
|
+
* 所以主动清理只负责回收内存,不负责防止无限增长。
|
|
16
|
+
*
|
|
17
|
+
* 4. 内存水位来自 createWorld 的 memoryLimitBytes。只有运行时能读到可信的
|
|
18
|
+
* heapUsed(Node 进程 / Node worker)才参与判断;浏览器 Worker 与
|
|
19
|
+
* EdgeOne/Cloudflare 等 isolate 环境自动跳过,其余能力不受影响。
|
|
20
|
+
*/
|
|
21
|
+
export type MilkioCacheOptions = {
|
|
22
|
+
/** 条目过期毫秒;永不过期必须显式传 null */
|
|
23
|
+
expireMs: number | null;
|
|
24
|
+
/** 本表条目数上限,超出时写入即淘汰最旧(LRU) */
|
|
25
|
+
maxEntries: number;
|
|
26
|
+
/** 本表主动清理间隔毫秒,最小 128 */
|
|
27
|
+
intervalMs: number;
|
|
28
|
+
};
|
|
29
|
+
export type MilkioKVCache<T> = {
|
|
30
|
+
/** 未命中返回 undefined(与 drizzle relational query 的 findFirst 对齐) */
|
|
31
|
+
get(key: string): T | undefined;
|
|
32
|
+
set(key: string, value: T): T;
|
|
33
|
+
/** key 不存在或已过期时写入并返回 true;否则不写入返回 false */
|
|
34
|
+
setIfAbsent(key: string, value: T): boolean;
|
|
35
|
+
has(key: string): boolean;
|
|
36
|
+
delete(key: string): void;
|
|
37
|
+
/** 读取并删除 */
|
|
38
|
+
pull(key: string): T | undefined;
|
|
39
|
+
clear(): void;
|
|
40
|
+
size(): number;
|
|
41
|
+
};
|
|
42
|
+
export type MilkioMemoCache<T> = {
|
|
43
|
+
/** 无 key 时内部固定使用 "$" */
|
|
44
|
+
run(loader: () => Promise<T>): Promise<T>;
|
|
45
|
+
run(key: string, loader: () => Promise<T>): Promise<T>;
|
|
46
|
+
delete(key?: string): void;
|
|
47
|
+
clear(): void;
|
|
48
|
+
size(): number;
|
|
49
|
+
};
|
|
50
|
+
export type MilkioBloomFilter = {
|
|
51
|
+
add(value: string): void;
|
|
52
|
+
/** 有假阳性:返回 true 只代表“可能存在” */
|
|
53
|
+
mightContain(value: string): boolean;
|
|
54
|
+
clear(): void;
|
|
55
|
+
estimatedCount(): number;
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* 读取当前 isolate 的堆占用。
|
|
59
|
+
* Node 进程、node:worker_threads、Node 实验性 Web Worker 都能读;
|
|
60
|
+
* Bun 的 process.memoryUsage().heapUsed 返回 0,浏览器 Worker 没有 process,
|
|
61
|
+
* 因此以“有限正数”作为可信判据,其余情况返回 null 让调用方降级。
|
|
62
|
+
*/
|
|
63
|
+
export declare function readHeapUsedBytes(): number | null;
|
|
64
|
+
/** createWorld 初始化时调用,设置全局内存水位 */
|
|
65
|
+
export declare function __configureMilkioCache(options: {
|
|
66
|
+
memoryLimitBytes?: number;
|
|
67
|
+
}): void;
|
|
68
|
+
/**
|
|
69
|
+
* 请求末尾的缓存维护入口(由 execute 的 finales 最后一项调用)。
|
|
70
|
+
*
|
|
71
|
+
* 热路径成本:遍历所有缓存表做一次时间戳比较。表数量按“一个复杂工程最多 100 张”
|
|
72
|
+
* 设计,实测 100 个表约 87ns/请求。
|
|
73
|
+
*/
|
|
74
|
+
export declare function __cacheTick(): void;
|
|
75
|
+
/** 定义 KV 缓存 */
|
|
76
|
+
export declare function defineMilkioKVCache<T>(options: MilkioCacheOptions): MilkioKVCache<T>;
|
|
77
|
+
/** 定义 Memo 缓存(闭包结果缓存,loader 必须是 async) */
|
|
78
|
+
export declare function defineMilkioMemoCache<T>(options: MilkioCacheOptions): MilkioMemoCache<T>;
|
|
79
|
+
/** 定义布隆过滤器(无 TTL、无逐出,位图整体固定大小) */
|
|
80
|
+
export declare function defineMilkioBloomFilter(options: {
|
|
81
|
+
expectedEntries: number;
|
|
82
|
+
falsePositiveRate: number;
|
|
83
|
+
}): MilkioBloomFilter;
|
package/index.d.ts
CHANGED