feat(@unimolecule/canon): ✨ generate d.ts for status-codes

Author: i7eo

.changeset/sparkly-clouds-think.md

@@ -0,0 +1,5 @@
+---
+"@unimolecule/canon": patch
+---
+
+generate d.ts for status-codes

internal/cache/AGENTS.md

@@ -0,0 +1,32 @@
+# Cache Package Instructions
+
+## Scope
+
+`@unimolecule/cache` owns the shared cache contract and default in-memory implementation.
+
+## Boundary Rules
+
+- Keep this package runtime-neutral enough for shared packages, Node-like runtimes, and web-compatible runtimes.
+- Do not add Redis, Cloudflare KV, R2, D1, or app-specific storage clients here.
+- Platform-specific cache stores belong in the application layer and should extend the shared `Cache` contract.
+- Reuse JSON helpers from `@unimolecule/utils` for serialization boundaries.
+
+## Implementation Rules
+
+- Keep the `Cache` base contract small and explicit.
+- TTL values are always milliseconds.
+- `maxSize` values are always bytes.
+- Preserve key-prefix normalization behavior.
+- Keep implementation helpers in `utils.ts` and shared public types in `types.ts`.
+- Prefer fail-fast errors for unimplemented methods or invalid cache values.
+
+## Documentation
+
+- README must describe this as a library package: contract, memory driver, inputs/outputs, examples, and runtime notes.
+- Include examples for default factory usage, direct `MemoryCache` usage, and custom store implementation when behavior changes.
+
+## Verification
+
+- Run `pnpm -F @unimolecule/cache test` for behavior changes.
+- Run `pnpm -F @unimolecule/cache build` for export or build changes.
+- Run `pnpm -F @unimolecule/cache lint` after broad TypeScript or Markdown edits.

internal/cache/README.md

@@ -0,0 +1,160 @@
+# @shamt/cache
+
+<p><strong>English</strong> | <a href="./README.zh-CN.md">中文</a></p>
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Design and Architecture](#design-and-architecture)
+- [Inputs and Outputs](#inputs-and-outputs)
+- [Usage](#usage)
+- [Implementation Notes](#implementation-notes)
+
+## Overview
+
+`@shamt/cache` defines the shared cache abstraction for the workspace and provides the default in-memory implementation. It is designed to stay runtime-neutral enough for shared packages, Node-like runtimes, and web-compatible runtimes.
+
+The package currently includes:
+
+- `Cache`: abstract cache contract.
+- `MemoryCache`: LRU-based in-memory cache implementation.
+- `createCache`: factory that creates the default `MemoryCache`.
+- Utility functions for cache key normalization and value serialization.
+
+Platform-specific stores such as Redis and Cloudflare KV should live in the application layer and extend the same `Cache` contract.
+
+## Design and Architecture
+
+`@shamt/cache` separates the cache contract from concrete runtime storage:
+
+- The `Cache` base class stores the backing client in `this.store` and declares the core cache methods every implementation must provide: `set`, `get`, `del`, and `has`.
+- Lifecycle methods such as `connect` and `dispose` are implementation-specific and are not part of the base `Cache` contract.
+- Base methods throw `CacheMethodNotImplementedError` by default, so missing implementations fail early during development.
+- TTL values passed into the package are always handled as milliseconds.
+- Values are serialized at the cache boundary with JSON helpers from `@unimolecule/utils`, making the memory driver behave closer to string-based stores such as Redis and KV.
+- Keys can be namespaced with a prefix. `MemoryCache` defaults to `cache:`;
+  non-empty prefixes are normalized to end with `:`, and an empty prefix disables
+  namespacing.
+
+`MemoryCache` uses `lru-cache` for eviction, TTL, and max-size accounting. It is suitable for local development, tests, short-lived in-process caching, and runtime-neutral default behavior.
+
+## Inputs and Outputs
+
+Inputs:
+
+- Logical cache keys as strings.
+- JSON-serializable values.
+- Per-write options, such as `{ ttl }`.
+- Store-level options, such as `{ ttl, keyPrefix, maxSize }`.
+
+Outputs:
+
+- Write methods return `Promise<void>`.
+- Read methods return `Promise<T | undefined>`.
+- Existence checks return `Promise<boolean>`.
+- Invalid TTL values, non-serializable values, or missing required methods throw errors.
+
+Units:
+
+- `ttl` is always in milliseconds.
+- `maxSize` is always in bytes.
+- `keyPrefix` defaults to `cache:` for `MemoryCache` and `createCache`.
+
+## Usage
+
+Use the default factory:
+
+```ts
+import { createCache } from "@shamt/cache";
+
+const cache = createCache({
+  ttl: 60_000,
+  keyPrefix: "shop",
+});
+
+await cache.set("settings", { currency: "USD" });
+
+const settings = await cache.get<{ currency: string }>("settings");
+const exists = await cache.has("settings");
+
+await cache.del("settings");
+```
+
+Use `MemoryCache` directly:
+
+```ts
+import { MemoryCache } from "@shamt/cache";
+
+const cache = new MemoryCache({
+  ttl: 5 * 60_000,
+  keyPrefix: "session",
+  maxSize: 1024 * 1024,
+});
+
+await cache.connect();
+await cache.set("offline:shop.myshopify.com", {
+  accessToken: "token",
+});
+
+const session = await cache.get<{ accessToken: string }>(
+  "offline:shop.myshopify.com",
+);
+
+await cache.dispose();
+```
+
+Implement a platform-specific store:
+
+```ts
+import {
+  Cache,
+  deserializeCacheValue,
+  serializeCacheValue,
+  type CacheSetOptions,
+} from "@shamt/cache";
+
+interface RedisClient {
+  set: (key: string, value: string, options?: { px: number }) => Promise<void>;
+  get: (key: string) => Promise<string | null>;
+  del: (key: string) => Promise<void>;
+  exists: (key: string) => Promise<number>;
+  quit: () => Promise<void>;
+}
+
+class RedisCache extends Cache<RedisClient> {
+  async connect() {
+    // Open Redis connection.
+  }
+
+  override async set<T>(key: string, value: T, options: CacheSetOptions = {}) {
+    const ttl = this.resolveTtl(options.ttl);
+    await this.store.set(
+      key,
+      serializeCacheValue(value),
+      ttl === undefined ? undefined : { px: ttl },
+    );
+  }
+
+  override async get<T>(key: string): Promise<T | undefined> {
+    return deserializeCacheValue<T>((await this.store.get(key)) ?? undefined);
+  }
+
+  override async del(key: string) {
+    await this.store.del(key);
+  }
+
+  override async has(key: string) {
+    return (await this.store.exists(key)) > 0;
+  }
+
+  async dispose() {
+    await this.store.quit();
+  }
+}
+```
+
+## Implementation Notes
+
+`@shamt/cache` currently only includes the memory driver. This avoids forcing Redis, Cloudflare KV, or other platform SDKs into the shared package dependency graph, keeping the package easier to reuse in node, web, and serverless/isolate environments.
+
+Applications can choose runtime-specific stores at the application layer while still reusing the same `Cache` abstraction.

internal/cache/README.zh-CN.md

@@ -0,0 +1,158 @@
+# @shamt/cache
+
+<p><a href="./README.md">English</a> | <strong>中文</strong></p>
+
+## 目录
+
+- [介绍](#介绍)
+- [设计与架构](#设计与架构)
+- [输入与输出](#输入与输出)
+- [使用方式](#使用方式)
+- [实现说明](#实现说明)
+
+## 介绍
+
+`@shamt/cache` 定义 workspace 共享的 cache 抽象，并提供默认的内存实现。这个包希望保持足够 runtime-neutral，方便在共享包、Node-like runtime、以及 web-compatible runtime 中使用。
+
+当前包内包含：
+
+- `Cache`: 抽象 cache contract。
+- `MemoryCache`: 基于 LRU 的内存 cache 实现。
+- `createCache`: 创建默认 `MemoryCache` 的工厂函数。
+- cache key 规范化、value 序列化等工具函数。
+
+Redis、Cloudflare KV 等平台相关 store 不放在这个包内，应该由应用层自行实现并继承同一个 `Cache` contract。
+
+## 设计与架构
+
+`@shamt/cache` 将 cache contract 与具体运行时存储分离：
+
+- `Cache` 基类把底层客户端保存在 `this.store`，并声明所有实现类必须具备的核心 cache 方法：`set`、`get`、`del`、`has`。
+- `connect`、`dispose` 等生命周期方法属于具体实现自己的能力，不放在 `Cache` 基类 contract 中。
+- 基类方法默认抛出 `CacheMethodNotImplementedError`，让未实现的方法在开发阶段尽早暴露。
+- 包内传入的 TTL 均按毫秒处理。
+- value 在 cache 边界统一使用 `@unimolecule/utils` 的 JSON helper 序列化，让 memory driver 的行为更接近 Redis、KV 这类字符串存储。
+- key 可以使用 prefix 做命名空间隔离。`MemoryCache` 默认使用 `cache:`；非空 prefix 会被规范化为以 `:` 结尾，空字符串会关闭命名空间。
+
+`MemoryCache` 使用 `lru-cache` 负责淘汰、TTL 与 max-size 统计。它适合本地开发、测试、短生命周期进程内缓存，以及 runtime-neutral 的默认行为。
+
+## 输入与输出
+
+输入：
+
+- 字符串形式的逻辑 cache key。
+- JSON-serializable value。
+- 单次写入选项，例如 `{ ttl }`。
+- store 级配置，例如 `{ ttl, keyPrefix, maxSize }`。
+
+输出：
+
+- 写操作返回 `Promise<void>`。
+- 读取操作返回 `Promise<T | undefined>`。
+- 存在性检查返回 `Promise<boolean>`。
+- TTL 非法、value 无法序列化、实现类缺少必需方法时抛出错误。
+
+单位：
+
+- `ttl` 始终为毫秒。
+- `maxSize` 始终为字节。
+- `MemoryCache` 和 `createCache` 的 `keyPrefix` 默认是 `cache:`。
+
+## 使用方式
+
+使用默认工厂函数：
+
+```ts
+import { createCache } from "@shamt/cache";
+
+const cache = createCache({
+  ttl: 60_000,
+  keyPrefix: "shop",
+});
+
+await cache.set("settings", { currency: "USD" });
+
+const settings = await cache.get<{ currency: string }>("settings");
+const exists = await cache.has("settings");
+
+await cache.del("settings");
+```
+
+直接使用 `MemoryCache`：
+
+```ts
+import { MemoryCache } from "@shamt/cache";
+
+const cache = new MemoryCache({
+  ttl: 5 * 60_000,
+  keyPrefix: "session",
+  maxSize: 1024 * 1024,
+});
+
+await cache.connect();
+await cache.set("offline:shop.myshopify.com", {
+  accessToken: "token",
+});
+
+const session = await cache.get<{ accessToken: string }>(
+  "offline:shop.myshopify.com",
+);
+
+await cache.dispose();
+```
+
+实现平台相关 store：
+
+```ts
+import {
+  Cache,
+  deserializeCacheValue,
+  serializeCacheValue,
+  type CacheSetOptions,
+} from "@shamt/cache";
+
+interface RedisClient {
+  set: (key: string, value: string, options?: { px: number }) => Promise<void>;
+  get: (key: string) => Promise<string | null>;
+  del: (key: string) => Promise<void>;
+  exists: (key: string) => Promise<number>;
+  quit: () => Promise<void>;
+}
+
+class RedisCache extends Cache<RedisClient> {
+  async connect() {
+    // Open Redis connection.
+  }
+
+  override async set<T>(key: string, value: T, options: CacheSetOptions = {}) {
+    const ttl = this.resolveTtl(options.ttl);
+    await this.store.set(
+      key,
+      serializeCacheValue(value),
+      ttl === undefined ? undefined : { px: ttl },
+    );
+  }
+
+  override async get<T>(key: string): Promise<T | undefined> {
+    return deserializeCacheValue<T>((await this.store.get(key)) ?? undefined);
+  }
+
+  override async del(key: string) {
+    await this.store.del(key);
+  }
+
+  override async has(key: string) {
+    return (await this.store.exists(key)) > 0;
+  }
+
+  async dispose() {
+    await this.store.quit();
+  }
+}
+```
+
+## 实现说明
+
+`@shamt/cache` 当前只内置 memory driver。这样可以避免把 Redis、Cloudflare KV 或其他平台 SDK 强行带入共享包依赖图，保证这个包在 node、web、serverless/isolate 等环境中更容易复用。
+
+应用层可以根据部署 runtime 选择自己的 store，但仍然复用同一个 `Cache` 抽象。

internal/cache/build.config.ts

@@ -0,0 +1,13 @@
+import process from "node:process";
+import { defineConfig } from "tsdown";
+
+export default defineConfig([
+  {
+    entry: ["./src/index.ts"],
+    format: ["esm", "cjs"],
+    platform: "node",
+    dts: true,
+    tsconfig: "./tsconfig.json",
+    watch: process.env.NODE_ENV === "development",
+  },
+]);