@mablock/status 0.0.1

package/README.zh-CN.md

@@ -0,0 +1,333 @@
+# @mablock/status
+
+[English](./README.md) | 简体中文
+
+一个零运行时依赖的 TypeScript 库，提供 Abseil 风格的 `Status` 和 `StatusOr<T>` 错误处理。
+
+这个包遵循 Abseil 的核心约束：
+
+- `Status` 表示成功或带消息、payload 的规范错误，不保存业务值。
+- `StatusOr<T>` 只包含一个 `T` 类型的值或一个非 OK 的 `Status`。
+- 不含值的 OK `Status` 不能转换成 `StatusOr<T>`。
+
+本项目受 Abseil 启发，但与 Google 无关联，也不由 Google 维护。
+
+## 安装
+
+```bash
+npm install @mablock/status
+```
+
+包内同时提供 ESM、CommonJS 和 TypeScript 类型声明。在 Node.js 中使用时需要 Node.js 18 或更高版本。
+
+## 基本用法：把错误逐层传到顶层
+
+推荐的基本流程是：
+
+1. 叶子函数成功时返回普通业务值 `T`，失败时返回 `failure(status)`。
+2. 每个中间层执行 `yield* ensureOk(ret)`。遇到失败时，当前层立即停止并把原始错误返回给调用方。
+3. 上层继续通过 `ensureOk` 传递错误，错误可以一级一级返回。
+4. 最顶层只需要调用一次 `hasError(ret)` 处理错误，不需要 `else`。
+
+```ts
+import {
+  type StatusOr,
+  statusDo,
+  ensureOk,
+  hasError,
+  failure,
+  NotFoundError,
+} from "@mablock/status";
+
+interface User {
+  id: number;
+  name: string;
+}
+
+interface Profile {
+  user: User;
+  label: string;
+}
+
+function findUser(id: number): User {
+  if (id === 404)
+    return failure(NotFoundError(`User ${id} not found`));
+  return { id, name: "Ada" };
+}
+
+function loadProfile(id: number): StatusOr<Profile> {
+  return statusDo(function* () {
+    var ret = findUser(id);
+    yield* ensureOk(ret);
+
+    return {
+      user: ret,
+      label: `${ret.name}#${ret.id}`,
+    };
+  });
+}
+
+function prepareProfile(id: number): StatusOr<string> {
+  return statusDo(function* () {
+    var ret = loadProfile(id);
+    const profile = yield* ensureOk(ret);
+
+    return `Profile: ${profile.label}`;
+  });
+}
+
+var ret = prepareProfile(404);
+if (hasError(ret)) {
+  console.error(ret.status().toString());
+  return;
+}
+
+console.log(ret.value());
+```
+
+`ensureOk` 不会把失败结果变成业务值。在 `statusDo` 内部，它会中断当前 Generator，并保留原始错误状态。下一层可以再次使用 `ensureOk` 继续向上传递，直到最顶层通过 `hasError` 统一处理。
+
+如果顶层直接调用返回业务值的函数，写法更短：
+
+```ts
+var ret = findUser(404);
+if (hasError(ret)) {
+  console.error(ret.status().toString());
+  return;
+}
+
+console.log(ret.name);
+```
+
+## Status
+
+没有返回值的操作可以使用 `Status` 表示执行结果：
+
+```ts
+import {
+  type Status,
+  OkStatus,
+  InvalidArgumentError,
+} from "@mablock/status";
+
+function validatePort(port: number): Status {
+  if (!Number.isInteger(port) || port < 1 || port > 65_535)
+    return InvalidArgumentError(`Invalid port: ${port}`);
+  return OkStatus();
+}
+
+const status = validatePort(8080);
+if (!status.ok()) console.error(status.code(), status.message());
+```
+
+默认构造函数和 `OkStatus()` 都会创建 OK 状态。为 OK 状态传入消息时，消息会按照 Abseil 语义被丢弃。
+
+### 规范错误码
+
+以下 16 个错误构造函数对应 gRPC 和 Abseil 的规范错误码：
+
+- `CancelledError(message?, payloads?)`
+- `UnknownError(message?, payloads?)`
+- `InvalidArgumentError(message?, payloads?)`
+- `DeadlineExceededError(message?, payloads?)`
+- `NotFoundError(message?, payloads?)`
+- `AlreadyExistsError(message?, payloads?)`
+- `PermissionDeniedError(message?, payloads?)`
+- `ResourceExhaustedError(message?, payloads?)`
+- `FailedPreconditionError(message?, payloads?)`
+- `AbortedError(message?, payloads?)`
+- `OutOfRangeError(message?, payloads?)`
+- `UnimplementedError(message?, payloads?)`
+- `InternalError(message?, payloads?)`
+- `UnavailableError(message?, payloads?)`
+- `DataLossError(message?, payloads?)`
+- `UnauthenticatedError(message?, payloads?)`
+
+### Payload
+
+`Status` 可以保存以 URI 或 type URL 为键的字符串或二进制 `Uint8Array` payload：
+
+```ts
+import { NotFoundError } from "@mablock/status";
+
+const status = NotFoundError("User not found");
+status.setPayload(
+  "type.googleapis.com/google.rpc.ErrorInfo",
+  "USER_DISABLED",
+);
+
+if (status.hasPayload("type.googleapis.com/google.rpc.ErrorInfo")) {
+  const payload = status.getPayload(
+    "type.googleapis.com/google.rpc.ErrorInfo",
+  );
+  console.log(payload);
+}
+```
+
+### 更新 Status
+
+`status.update(other)` 保留遇到的第一个非 OK 状态，与 `absl::Status::Update` 的行为一致：
+
+```ts
+import {
+  OkStatus,
+  NotFoundError,
+  CancelledError,
+} from "@mablock/status";
+
+const status = OkStatus();
+status.update(NotFoundError("First error"));
+status.update(CancelledError("Second error"));
+
+console.log(status.code()); // StatusCode.NOT_FOUND
+```
+
+## StatusOr<T>
+
+需要在成功时返回值的操作可以使用 `StatusOr<T>`：
+
+```ts
+import {
+  StatusOr,
+  statusOr,
+  statusOrError,
+  NotFoundError,
+} from "@mablock/status";
+
+interface User {
+  id: number;
+  name: string;
+}
+
+function findUser(id: number): StatusOr<User> {
+  if (id === 404)
+    return statusOrError(NotFoundError(`User ${id} was not found`));
+  return statusOr({ id, name: "Ada" });
+}
+
+const result = findUser(42);
+if (result.ok()) {
+  console.log(result.value().name);
+} else {
+  console.error(result.status().toString());
+}
+```
+
+C++ 可以从错误 `Status` 隐式构造 `StatusOr<T>`，TypeScript 没有对应的隐式转换。请使用 `statusOrError(error)` 或 `StatusOr.fromStatus(error)`。
+
+`StatusOr.fromStatus(OkStatus())` 会抛出 `RangeError`，因为成功结果必须包含一个值。
+
+### 转换结果
+
+```ts
+const displayName = findUser(42)
+  .transform((user) => user.name)
+  .valueOr("unknown");
+
+const message = findUser(404).match({
+  ok: (user) => `Found ${user.name}`,
+  err: (status) => `Failed: ${status}`,
+});
+```
+
+可用方法包括：
+
+- `value()`：返回内部值；非 OK 时抛出 `StatusError`。
+- `valueOr(defaultValue)`：返回内部值或指定的默认值。
+- `valueOrCompute(fn)`：根据失败的 `Status` 计算默认值。
+- `transform(fn)`：成功时将 `T` 映射为 `U`。
+- `andThen(fn)`：成功时将 `T` 映射为 `StatusOr<U>`。
+- `match({ ok, err })`：分别处理成功和失败结果。
+- `StatusOr.all([a, b, c])`：将多个结果合并成一个元组结果。
+
+## Generator 流水线
+
+`statusDo` 和 `statusDoAsync` 使用标准 Generator 提供类似 `ASSIGN_OR_RETURN` 的控制流：
+
+```ts
+import {
+  type StatusOr,
+  statusDo,
+  statusOr,
+  statusOrError,
+  InvalidArgumentError,
+  ensureOk,
+} from "@mablock/status";
+
+function parseNumber(input: string): StatusOr<number> {
+  const value = Number(input);
+  if (Number.isNaN(value))
+    return statusOrError(
+      InvalidArgumentError(`Invalid number: ${input}`),
+    );
+  return statusOr(value);
+}
+
+const result = statusDo(function* () {
+  const left = yield* ensureOk(parseNumber("20"));
+
+  const rightOr = parseNumber("22");
+  yield* ensureOk(rightOr);
+  const right = rightOr.value();
+
+  return left + right;
+});
+```
+
+流水线会在第一个错误处停止并关闭 Generator，因此 `finally` 清理逻辑仍会执行。
+
+## Failure sentinel
+
+`failure(status)` 创建一个携带原始非 OK 状态的 Proxy，同时让函数的成功返回类型保持为 `T`。如果没有检查就读取失败 Proxy 的业务属性，会抛出 `StatusError`。中间层使用 `ensureOk`，顶层边界使用 `hasError`。
+
+### Proxy 属性访问
+
+使用 `asProxy` 包装 `StatusOr<T>` 后，可以直接访问 `T` 中与 `StatusOr` 不冲突的属性：
+
+```ts
+import { asProxy, statusOr } from "@mablock/status";
+
+const proxy = asProxy(statusOr({ id: 1, name: "Ada" }));
+console.log(proxy.name); // "Ada"
+console.log(proxy.ok()); // true
+```
+
+## JavaScript 错误转换
+
+原生 JavaScript 异常可以转换为规范 `Status`：
+
+```ts
+import { fromError, tryCatch, tryCatchAsync } from "@mablock/status";
+
+const status = fromError(new TypeError("Invalid argument"));
+console.log(status.code()); // StatusCode.INVALID_ARGUMENT
+
+const syncResult = tryCatch(() => JSON.parse(rawText));
+
+const asyncResult = await tryCatchAsync(async () => fetchUserData());
+```
+
+## 状态判断
+
+包内提供用于判断具体错误状态的类型守卫：
+
+```ts
+import {
+  isOk,
+  hasError,
+  isNotFound,
+  isInvalidArgument,
+} from "@mablock/status";
+
+if (isOk(result)) {
+  // result 已完成类型收窄
+}
+
+if (isNotFound(statusOr)) {
+  // 处理未找到错误
+}
+```
+
+## 许可证
+
+Apache-2.0