@planet-matrix/mobius-model 0.6.0 → 0.9.0

package/src/request/request/base.ts

@@ -0,0 +1,250 @@
+import type { BuildEvents } from "#Source/event/index.ts"
+import { EventManager } from "#Source/event/index.ts"
+import { isError, errorIsNetworkError, errorStringify } from "#Source/basic/index.ts"
+
+import type { BaseFetch, FetchResponseType, FetchFactory } from "../fetch/index.ts"
+import { generalFetch } from "../fetch/index.ts"
+import type {
+  Resource,
+  ResourceOutput,
+  ResourceSuccessOutput,
+  ResourceErrorOutput,
+  ResourceSuccessData,
+  ResourceErrorData,
+  ResourcePatchOutput,
+} from "./resource.ts"
+
+/**
+ * 描述请求执行过程中会派发的标准事件集合。
+ */
+export type BaseRequestEvents<R extends Resource> = BuildEvents<{
+  output: (output: ResourceOutput<R>) => void
+  successOutput: (successOutput: ResourceSuccessOutput<R>) => void
+  successData: (successData: ResourceSuccessData<R>) => void
+  errorOutput: (errorOutput: ResourceErrorOutput<R>) => void
+  errorData: (errorData: ResourceErrorData<R>) => void
+  patchOutput: (patchOutput: ResourcePatchOutput<R>) => void
+}>
+
+/**
+ * 实际执行请求动作的选项。
+ *
+ * 该类型会根据资源声明中 `input.query` 与 `input.body` 是否可选，
+ * 自动收紧当前路径对应请求选项里的必填性。
+ */
+export type RequestOptions<Path, R extends Resource>
+  = {
+    baseUrl: Extract<R, { path: Path }>["baseUrl"]
+    path: Extract<R, { path: Path }>["path"]
+    method: Extract<R, { path: Path }>["method"]
+    headers?: Record<string, string> | undefined
+    responseType?: FetchResponseType | undefined
+    timeout?: number | undefined
+    abortSignal?: AbortSignal | undefined
+  } & (
+    undefined extends Extract<R, { path: Path }>["input"]["query"]
+    ? { query?: Extract<R, { path: Path }>["input"]["query"] | undefined }
+    : { query: Extract<R, { path: Path }>["input"]["query"] }
+  ) & (
+    undefined extends Extract<R, { path: Path }>["input"]["body"]
+    ? { body?: Extract<R, { path: Path }>["input"]["body"] | undefined }
+    : { body: Extract<R, { path: Path }>["input"]["body"] }
+  ) & {
+    onOutput?: ((output: ResourceOutput<Extract<R, { path: Path }>>) => void) | undefined
+    onSuccessOutput?: ((successOutput: ResourceSuccessOutput<Extract<R, { path: Path }>>) => void) | undefined
+    onSuccessData?: ((successData: ResourceSuccessData<Extract<R, { path: Path }>>) => void) | undefined
+    onErrorOutput?: ((errorOutput: ResourceErrorOutput<Extract<R, { path: Path }>>) => void) | undefined
+    onErrorData?: ((errorData: ResourceErrorData<Extract<R, { path: Path }>>) => void) | undefined
+    onPatchOutput?: ((patchOutput: ResourcePatchOutput<Extract<R, { path: Path }>>) => void) | undefined
+  }
+
+/**
+ * 实际执行请求动作的结果。
+ */
+export type RequestResult<Path, R extends Resource>
+  = ResourceOutput<Extract<R, { path: Path }>>
+  | ResourcePatchOutput<Extract<R, { path: Path }>>
+
+/**
+ * 表示请求失败时的错误归类。
+ */
+export type ErrorKind = "network" | "unknown"
+
+/**
+ * 生成补丁输出时可使用的上下文。
+ */
+export type GeneratePatchOutputContext = {
+  type: "error"
+  errorKind: ErrorKind
+  error: Error
+}
+
+/**
+ * 构造专用请求类的选项。
+ */
+export interface BaseRequestOptions<R extends Resource> {
+  /**
+   * 自定义请求执行器工厂；未提供时使用默认的通用运行时分派实现。
+   */
+  fetchFactory?: FetchFactory | undefined
+
+  /**
+   * 在真正发起请求前，对标准化请求选项做最后一次统一调整。
+   */
+  modifyRequestOptions?: ((options: RequestOptions<R["path"], R>) => RequestOptions<R["path"], R>) | undefined
+
+  /**
+   * 在请求失败时生成仍可被上层继续消费的补丁输出。
+   */
+  generatePatchOutput: (context: GeneratePatchOutputContext) => ResourcePatchOutput<R>
+}
+
+/**
+ * 基于资源声明组织请求、输出分类与失败补丁的抽象请求类。
+ *
+ * `Resource` 类型参数应传入资源声明的联合类型或元组成员联合。
+ * 默认实现假定 JSON 输出可通过 `status` 字段区分为 `success` 与 `error`，
+ * 并通过 `data` 字段提取真正的成功数据或错误数据；若资源输出不满足这组约定，
+ * 则应由子类覆写对应的分类与提取方法。
+ */
+export abstract class BaseRequest<R extends Resource = Resource> {
+  protected options: BaseRequestOptions<R>
+
+  /**
+   * 对外暴露请求生命周期事件的事件管理器。
+   */
+  event: EventManager<BaseRequestEvents<R>>
+
+  constructor(options: BaseRequestOptions<R>) {
+    this.options = options
+    this.event = new EventManager()
+  }
+
+  /**
+   * 判断当前输出是否应被视为成功输出。
+   */
+  protected isSuccessDataResponse(response: ResourceOutput<R>): boolean {
+    return response['status'] === "success"
+  }
+
+  /**
+   * 从成功输出中提取成功数据。
+   */
+  protected extractSuccessData(response: ResourceSuccessOutput<R>): ResourceSuccessData<R> {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return response['data'] as ResourceSuccessData<R>
+  }
+
+  /**
+   * 判断当前输出是否应被视为错误输出。
+   */
+  protected isErrorDataResponse(response: ResourceOutput<R>): boolean {
+    return response['status'] === "error"
+  }
+
+  /**
+   * 从错误输出中提取错误数据。
+   */
+  protected extractErrorData(response: ResourceErrorOutput<R>): ResourceErrorData<R> {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return response['data'] as ResourceErrorData<R>
+  }
+
+  /**
+   * 按资源路径约束执行一次请求，并在成功或失败时派发对应事件。
+   */
+  async request<Path extends R["path"]>(
+    options: RequestOptions<Path, R>,
+  ): Promise<RequestResult<Path, R>> {
+    const { fetchFactory, modifyRequestOptions } = this.options
+
+    const preparedOptions = modifyRequestOptions !== undefined
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      ? modifyRequestOptions(options as RequestOptions<R["path"], R>)
+      : options
+
+    const {
+      responseType = "json",
+      onOutput,
+      onSuccessOutput,
+      onSuccessData,
+      onErrorOutput,
+      onErrorData,
+      onPatchOutput,
+    } = preparedOptions
+
+    try {
+      type FetchInput = {
+        query: Extract<R, { path: Path }>["input"]["query"]
+        body: Extract<R, { path: Path }>["input"]["body"]
+      }
+      type FetchOutput = {
+        [K in typeof responseType]: {
+          type: K
+          data: ResourceOutput<Extract<R, { path: Path }>>
+        }
+      }[typeof responseType]
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      const preparedFetch = (fetchFactory ?? generalFetch)(preparedOptions) as BaseFetch<FetchInput, FetchOutput>
+
+      if (responseType === "json") {
+        const json = await preparedFetch.getJson()
+        onOutput?.(json)
+        this.event.emit("output", json)
+
+        // do we have a better way to consume the success data?
+        if (this.isSuccessDataResponse(json)) {
+          onSuccessOutput?.(json)
+          this.event.emit("successOutput", json)
+          const successData = this.extractSuccessData(json)
+          onSuccessData?.(successData)
+          this.event.emit("successData", successData)
+        }
+
+        if (this.isErrorDataResponse(json)) {
+          onErrorOutput?.(json)
+          this.event.emit("errorOutput", json)
+          const errorData = this.extractErrorData(json)
+          onErrorData?.(errorData)
+          this.event.emit("errorData", errorData)
+        }
+
+        return json
+      }
+
+      throw new Error("Unsupported response type, please use \"json\" or improve implementation of BaseRequest.")
+    }
+    catch (exception) {
+      if (errorIsNetworkError(exception)) {
+        const patchOutput = this.options.generatePatchOutput({
+          type: "error",
+          errorKind: "network",
+          error: exception
+        })
+        onPatchOutput?.(patchOutput)
+        this.event.emit("patchOutput", patchOutput)
+        return patchOutput
+      }
+      else if (isError(exception)) {
+        const patchOutput = this.options.generatePatchOutput({
+          type: "error",
+          errorKind: "unknown",
+          error: exception
+        })
+        onPatchOutput?.(patchOutput)
+        this.event.emit("patchOutput", patchOutput)
+        return patchOutput
+      }
+      else {
+        const patchOutput = this.options.generatePatchOutput({
+          type: "error",
+          errorKind: "unknown",
+          error: new Error(errorStringify(exception))
+        })
+        onPatchOutput?.(patchOutput)
+        this.event.emit("patchOutput", patchOutput)
+        return patchOutput
+      }
+    }
+  }
+}

package/src/request/request/general.ts

@@ -0,0 +1,64 @@
+import type { ResourcePatchOutput } from "./resource.ts"
+import type { BaseRequestOptions, GeneratePatchOutputContext } from "./base.ts"
+import { BaseRequest } from "./base.ts"
+
+/**
+ * 描述适用于通用 `{ status, data }` 输出结构的资源声明。
+ */
+export interface GeneralResource {
+  baseUrl: string
+  path: string
+  method: "get" | "post"
+  input: {
+    query?: Record<string, unknown> | undefined
+    body?: Record<string, unknown> | undefined
+  }
+  successData: Record<string, unknown>
+  errorData: Record<string, unknown>
+}
+
+/**
+ * 把通用资源声明补齐为 `BaseRequest` 可直接消费的完整资源契约。
+ */
+export type GeneralResourceToResource<R extends GeneralResource> = R & {
+  output: { status: "success", data: R["successData"] } | { status: "error", data: R["errorData"] }
+  successOutput: { status: "success", data: R["successData"] }
+  errorOutput: { status: "error", data: R["errorData"] }
+  patchOutput: { status: "unknown", data: GeneratePatchOutputContext }
+}
+
+/**
+ * 构造通用请求类的选项。
+ *
+ * 该类型会沿用 `BaseRequestOptions` 的配置能力，只是由 `GeneralRequest`
+ * 自动补齐失败时的补丁输出生成逻辑。
+ */
+export interface GeneralRequestOptions<R extends GeneralResource>
+  extends Omit<BaseRequestOptions<GeneralResourceToResource<R>>, "generatePatchOutput"> {
+}
+
+/**
+ * 面向通用 `{ status, data }` 输出结构的请求实现。
+ *
+ * `GeneralRequest` 仅适用于返回结构严格符合特定情况的目标资源，特定情况指：
+ *
+ * 1. 业务结果仅包含成功（success）和错误（error）两种状态。
+ * 2. 业务结果通过一个名为 `status` 的字段区分状态，并通过一个名为 `data` 的字段承载数据：
+ *    `{ status: "success" | "error", data: Record<string, unknown> }`。
+ */
+export class GeneralRequest<R extends GeneralResource = GeneralResource>
+  extends BaseRequest<GeneralResourceToResource<R>> {
+  constructor(options: GeneralRequestOptions<R>) {
+    const generatePatchOutput = (context: GeneratePatchOutputContext): ResourcePatchOutput<GeneralResourceToResource<R>> => {
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      return {
+        status: "unknown",
+        data: context
+      } as ResourcePatchOutput<GeneralResourceToResource<R>>
+    }
+    super({
+      ...options,
+      generatePatchOutput
+    })
+  }
+}

package/src/request/request/index.ts

@@ -0,0 +1,3 @@
+export type * from "./resource.ts"
+export * from "./base.ts"
+export * from "./general.ts"

package/src/request/request/resource.ts

@@ -0,0 +1,68 @@
+/**
+ * 描述一个远程资源契约。
+ *
+ * 这个接口用于把某一路径、方法、输入、输出、成功数据、错误数据与失败补丁输出
+ * 收束为一份可长期维护的类型层声明，供 `BaseRequest` 及其派生实现消费。
+ */
+export interface Resource {
+  baseUrl: string
+  path: string
+  method: "get" | "post"
+  input: {
+    query?: Record<string, unknown> | undefined
+    body?: Record<string, unknown> | undefined
+  }
+  output: Record<string, unknown>
+
+  successOutput: Record<string, unknown>
+  successData: Record<string, unknown>
+  errorOutput: Record<string, unknown>
+  errorData: Record<string, unknown>
+
+  patchOutput: Record<string, unknown>
+}
+
+/**
+ * 提取资源声明中的基础 URL 类型。
+ */
+export type ResourceBaseUrl<R extends Resource> = R["baseUrl"]
+
+/**
+ * 提取资源声明中的路径类型。
+ */
+export type ResourcePath<R extends Resource> = R["path"]
+
+/**
+ * 提取资源声明中的请求方法类型。
+ */
+export type ResourceMethod<R extends Resource> = R["method"]
+
+/**
+ * 提取资源声明中的完整输出类型。
+ */
+export type ResourceOutput<R extends Resource> = R["output"]
+
+/**
+ * 提取资源声明中的成功输出类型。
+ */
+export type ResourceSuccessOutput<R extends Resource> = R["successOutput"]
+
+/**
+ * 提取资源声明中的错误输出类型。
+ */
+export type ResourceErrorOutput<R extends Resource> = R["errorOutput"]
+
+/**
+ * 提取资源声明中的成功数据类型。
+ */
+export type ResourceSuccessData<R extends Resource> = R["successData"]
+
+/**
+ * 提取资源声明中的错误数据类型。
+ */
+export type ResourceErrorData<R extends Resource> = R["errorData"]
+
+/**
+ * 提取资源声明中的补丁输出类型。
+ */
+export type ResourcePatchOutput<R extends Resource> = R["patchOutput"]

package/src/result/README.md

@@ -0,0 +1,4 @@
+# Result
+
+@see https://github.com/supermacro/neverthrow
+@see https://better-result.dev/introduction

package/src/result/controller.ts

@@ -0,0 +1,54 @@
+import type { Either } from "./either.ts"
+import { Left, Right } from "./either.ts"
+
+export class Controller<L, R> {
+  static isLeft<L, R>(target: unknown): target is Left<L, R> {
+    return Left.isLeft(target)
+  }
+
+  static isRight<L, R>(target: unknown): target is Right<L, R> {
+    return Right.isRight(target)
+  }
+
+  private promise: Promise<Either<L, R>>
+  private resolve: (value: Either<L, R>) => void
+
+  constructor() {
+    let _resolve: (value: Either<L, R>) => void
+    this.promise = new Promise((resolve) => {
+      _resolve = resolve
+    })
+    this.resolve = _resolve!
+  }
+
+  get value(): Promise<Either<L, R>> {
+    return this.promise
+  }
+
+  async returnRight(value: R): Promise<Right<L, R>> {
+    const right = new Right<L, R>(value)
+    this.resolve(right)
+    return await Promise.resolve(right)
+  }
+
+  async returnLeft(value: L): Promise<Left<L, R>> {
+    const left = new Left<L, R>(value)
+    this.resolve(left)
+    return await Promise.resolve(left)
+  }
+
+  // oxlint-disable-next-line require-await
+  async throw(value: L): Promise<void> {
+    const left = new Left<L, R>(value)
+    this.resolve(left)
+    // oxlint-disable-next-line typescript/only-throw-error
+    throw left
+  }
+}
+
+type ExtractLeft<E> = E extends Either<infer L, infer _> ? L : never
+type ExtractRight<E> = E extends Either<infer _, infer R> ? R : never
+export const controllerFromEitherType = <E extends Either<unknown, unknown>>(
+): Controller<ExtractLeft<E>, ExtractRight<E>> => {
+  return new Controller<ExtractLeft<E>, ExtractRight<E>>()
+}

package/src/result/either.ts

@@ -0,0 +1,193 @@
+
+// oxlint-disable-next-line typescript/no-explicit-any
+type AnyEither = Either<any, any>
+type GetRight<Eithers> = Eithers extends []
+  ? []
+  : (
+    Eithers extends [infer AssumeEither, ...infer xs]
+    ? (
+      AssumeEither extends Either<unknown, infer Right>
+      ? [Right, ...GetRight<xs>]
+      : never
+    )
+    : never
+  )
+type GetLeft<Eithers> = Eithers extends []
+  ? []
+  : (
+    Eithers extends [infer AssumeEither, ...infer xs]
+    ? (
+      AssumeEither extends Either<infer Left, unknown>
+      ? [Left, ...GetLeft<xs>]
+      : never
+    )
+    : never
+  )
+type TupleToUnion<Tuple> = Tuple extends unknown[] ? Tuple[number] : never
+
+export abstract class Either<L, R> {
+  static left<L, R>(value: L): Either<L, R> {
+    return new Left(value)
+  }
+
+  static right<L, R>(value: R): Either<L, R> {
+    return new Right(value)
+  }
+
+  static pure<L, R>(value: R): Either<L, R> {
+    return new Right(value)
+  }
+
+  static lift<NewR, Eithers extends AnyEither[]>(
+    eithers: [...Eithers],
+    map: (eitherRights: GetRight<Eithers>) => NewR,
+  ): Either<TupleToUnion<GetLeft<Eithers>>, NewR> {
+    const firstLeft = eithers.find(either => either.isLeft())
+    if (firstLeft !== undefined) {
+      return firstLeft as Either<TupleToUnion<GetLeft<Eithers>>, NewR>
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const rights = eithers.map(either => {
+      // oxlint-disable-next-line typescript/no-unsafe-return
+      return either.assertRight().getRight()
+    }) as GetRight<Eithers>
+    const newRightValue = map(rights)
+    return Either.pure(newRightValue)
+  }
+
+  abstract map<NewR>(map: (value: R) => NewR): Either<L, NewR>
+  abstract mapLeft<NewL>(map: (value: L) => NewL): Either<NewL, R>
+  abstract bind<NewR>(bind: (value: R) => Either<L, NewR>): Either<L, NewR>
+
+  abstract isLeft(): this is Left<L, R>
+  abstract isRight(): this is Right<L, R>
+  abstract getValue(): L | R
+
+  abstract assertLeft(): Left<L, R>
+  abstract assertRight(): Right<L, R>
+
+  abstract match<X>(onLeft: (value: L) => X, onRight: (value: R) => X): X
+
+  abstract mplus(either: Either<L, R>): Either<L, R>
+}
+export class Left<L, R> extends Either<L, R> {
+  static isLeft<L, R>(target: unknown): target is Left<L, R> {
+    return target instanceof Left
+  }
+
+  private value: L
+
+  constructor(value: L) {
+    super()
+    this.value = value
+  }
+
+  map<NewR>(_map: (value: R) => NewR): Either<L, NewR> {
+    return new Left(this.value)
+  }
+
+  mapLeft<NewL>(map: (value: L) => NewL): Either<NewL, R> {
+    return new Left(map(this.value))
+  }
+
+  bind<NewR>(_map: (value: R) => Either<L, NewR>): Either<L, NewR> {
+    return new Left(this.value)
+  }
+
+  isLeft(): this is Left<L, R> {
+    return true
+  }
+
+  isRight(): this is Right<L, R> {
+    return false
+  }
+
+  getLeft(): L {
+    return this.value
+  }
+
+  getValue(): L | R {
+    return this.value
+  }
+
+  assertLeft(): this {
+    return this
+  }
+
+  assertRight(): Right<L, R> {
+    throw new Error("Assert failed")
+  }
+
+  match<X>(onLeft: (value: L) => X, _onRight: (value: R) => X): X {
+    return onLeft(this.value)
+  }
+
+  mplus(either: Either<L, R>): Either<L, R> {
+    return either
+  }
+}
+
+export class Right<L, R> extends Either<L, R> {
+  static isRight<L, R>(target: unknown): target is Right<L, R> {
+    return target instanceof Right
+  }
+
+  private value: R
+
+  constructor(value: R) {
+    super()
+    this.value = value
+  }
+
+  map<NewR>(map: (value: R) => NewR): Either<L, NewR> {
+    return new Right(map(this.value))
+  }
+
+  mapLeft<NewL>(_map: (value: L) => NewL): Either<NewL, R> {
+    return new Right(this.value)
+  }
+
+  bind<NewR>(map: (value: R) => Either<L, NewR>): Either<L, NewR> {
+    return map(this.value)
+  }
+
+  isLeft(): this is Left<L, R> {
+    return false
+  }
+
+  isRight(): this is Right<L, R> {
+    return true
+  }
+
+  getRight(): R {
+    return this.value
+  }
+
+  getValue(): L | R {
+    return this.value
+  }
+
+  assertLeft(): Left<L, R> {
+    throw new Error("Assert failed")
+  }
+
+  assertRight(): this {
+    return this
+  }
+
+  match<X>(_onLeft: (value: L) => X, onRight: (value: R) => X): X {
+    return onRight(this.value)
+  }
+
+  mplus(_either: Either<L, R>): Either<L, R> {
+    return this
+  }
+}
+
+export type TupleOfEither<Left, Right> = [undefined, Right] | [Left, undefined]
+export const eitherToTuple = <L, R>(either: Either<L, R>): TupleOfEither<L, R> => {
+  const left = either.isLeft() ? either.getLeft() : undefined
+  const right = either.isRight() ? either.getRight() : undefined
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return [left, right] as TupleOfEither<L, R>
+}

package/src/result/index.ts

@@ -0,0 +1,2 @@
+export * from "./either.ts"
+export * from "./controller.ts"