@planet-matrix/mobius-model 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @planet-matrix/mobius-model
 
+## 0.10.1
+
+### Patch Changes
+
+- d7c33d7: Add `dist` to `.npmignore`.
+
+## 0.10.0
+
+### Minor Changes
+
+- 6f99535: Add service model.
+- 9520154: Add tagged error capabilities to exception model.
+
 ## 0.9.0
 
 ### Minor Changes

package/oxlint.config.ts

@@ -1,6 +1,5 @@
-import { defineConfig } from "oxlint"
 import { Lint } from "@planet-matrix/mobius-mono"
 
-const config: Lint.OxlintConfig = defineConfig(Lint.defineOxlintConfig({}))
+const config: Lint.OxlintConfig = Lint.defineOxlintConfig({})
 
 export default config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet-matrix/mobius-model",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Mobius model.",
   "keywords": [
     "mobius",
@@ -59,6 +59,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
+    "typescript": "^6.0.2",
     "ua-parser-js": "^2.0.9",
     "html-to-image": "^1.11.13",
     "undici": "^7.24.6",
@@ -77,14 +78,13 @@
     "openai": "^6.33.0"
   },
   "devDependencies": {
-    "@planet-matrix/mobius-mono": "0.8.0",
+    "@planet-matrix/mobius-mono": "0.10.1",
     "@types/bun": "^1.3.11",
+    "@typescript/native-preview": "^7.0.0-dev.20260329.1",
     "oxlint": "^1.57.0",
     "oxlint-tsgolint": "^0.18.1",
-    "typescript": "^6.0.2",
-    "@typescript/native-preview": "^7.0.0-dev.20260329.1",
-    "vite": "^8.0.3",
     "vitest": "^4.1.2",
+    "vite": "^8.0.3",
     "drizzle-kit": "^0.31.10"
   },
   "peerDependencies": {},

package/scripts/build.ts

@@ -1,53 +1,3 @@
-import { $, build } from "bun"
+import { Build } from "@planet-matrix/mobius-mono"
 
-// ensure the outdir is existing and cleaned up before building
-console.log("Cleaning and preparing ./dist directory...")
-await $`rm -rf dist`
-
-// console.log("Building TypeScript declarations...")
-// await $`bun run tsgo --noEmit false`
-
-console.log("Building the library with Bun...")
-const builtOutput = await build({
-  banner: "// Enjoy using Example Library!",
-  bytecode: false,
-  conditions: [],
-  define: {},
-  drop: [],
-  emitDCEAnnotations: false,
-  entrypoints: ["./src/index.ts"],
-  env: "PUBLIC_*",
-  external: [],
-  footer: "// Made with ♥ by the Planet Matrix team!",
-  format: "esm",
-  ignoreDCEAnnotations: false,
-  loader: {},
-  minify: {
-    identifiers: true,
-    keepNames: false,
-    syntax: true,
-    whitespace: true,
-  },
-  naming: {
-    entry: '[dir]/[name].[ext]',
-    chunk: '[name]-[hash].[ext]',
-    asset: '[name]-[hash].[ext]',
-  },
-  outdir: "./dist",
-  packages: "bundle",
-  plugins: [],
-  // publicPath: undefined,
-  // root: undefined,
-  sourcemap: "linked",
-  splitting: true,
-  target: "bun",
-  throw: false,
-  tsconfig: "./tsconfig.json",
-})
-
-if (builtOutput.success === false) {
-  console.error('Build failed:', builtOutput.logs);
-  throw new Error('Build process failed.');
-} else {
-  console.log("Build completed successfully.");
-}
+await Build.Library.build({})

package/src/basic/promise.ts

@@ -6,16 +6,16 @@ import { isPlainObject } from "./is.ts"
  * @example
  * ```
  * // Expect: 6
- * const example1 = await promiseThen((value: number) => value * 2, Promise.resolve(3))
+ * const example1 = await promiseThen(Promise.resolve(3), (value: number) => value * 2)
  * // Expect: "ok!"
- * const example2 = await promiseThen((value: string) => `${value}!`, Promise.resolve("ok"))
+ * const example2 = await promiseThen(Promise.resolve("ok"), (value: string) => `${value}!`)
  * ```
  */
 export const promiseThen = async <V, R>(
-  doSomething: (value: V) => R | PromiseLike<R>,
   target: Promise<V>,
+  doSomething: (value: V) => R | PromiseLike<R>,
 ): Promise<R> => {
-  return await target.then(doSomething)
+  return await target.then((value) => doSomething(value))
 }
 
 /**
@@ -24,16 +24,16 @@ export const promiseThen = async <V, R>(
  * @example
  * ```
  * // Expect: "fallback"
- * const example1 = await promiseCatch(() => "fallback", Promise.reject(new Error("x")))
+ * const example1 = await promiseCatch(Promise.reject(new Error("x")), () => "fallback")
  * // Expect: 3
- * const example2 = await promiseCatch(() => 0, Promise.resolve(3))
+ * const example2 = await promiseCatch(Promise.resolve(3), () => 0)
  * ```
  */
 export const promiseCatch = async <V, R>(
-  doSomething: (reason: unknown) => R | PromiseLike<R>,
   target: Promise<V>,
+  doSomething: (reason: unknown) => R | PromiseLike<R>,
 ): Promise<V | R> => {
-  return await target.catch(doSomething)
+  return await target.catch((reason: unknown) => doSomething(reason))
 }
 
 /**
@@ -43,25 +43,54 @@ export const promiseCatch = async <V, R>(
  * ```
  * let cleaned = false
  * // Expect: 10
- * const example1 = await promiseFinally(() => { cleaned = true }, Promise.resolve(10))
+ * const example1 = await promiseFinally(Promise.resolve(10), () => { cleaned = true })
  * // Expect: true
  * const example2 = cleaned
  * ```
  */
 export const promiseFinally = async <V>(
-  doSomething: () => void,
   target: Promise<V>,
+  doSomething: () => void,
 ): Promise<V> => {
-  return await target.finally(doSomething)
+  return await target.finally(() => doSomething())
+}
+
+export interface PromiseDeferred<V> {
+  promise: Promise<V>
+  resolve: (value: V) => void
+  reject: (reason: unknown) => void
+}
+/**
+ * Create a deferred promise with external resolve and reject functions.
+ *
+ * @example
+ * ```
+ * const deferred = promiseDeferred<number>()
+ * // Expect: typeof deferred.resolve === "function"
+ * const example1 = typeof deferred.resolve
+ * deferred.resolve(42)
+ * const example2 = await deferred.promise
+ * // Expect: 42
+ * ```
+ */
+export const promiseDeferred = <V>(): PromiseDeferred<V> => {
+  let externalResolve!: (value: V) => void
+  let externalReject!: (reason: unknown) => void
+  const promise = new Promise<V>((resolve, reject) => {
+    externalResolve = resolve
+    externalReject = reject
+  })
+  return { promise, resolve: externalResolve, reject: externalReject }
 }
 
-const INTERNAL_PROMISE_FAIL_RESULT_TYPE: symbol = Symbol("fail")
+const INTERNAL_PROMISE_FAIL_RESULT_TYPE: unique symbol = Symbol("fail")
+type InternalPromiseFailResultType = typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
 
 /**
  * 表示标准化的 Promise 失败结果。
  */
 export interface PromiseFailResult {
-  __type__: typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
+  __type__: InternalPromiseFailResultType
   reason: unknown
 }
 
@@ -75,14 +104,23 @@ export interface PromiseIndexedFailResult extends PromiseFailResult {
 /**
  * 根据拒因构造标准化的 Promise 失败结果。
  */
-export const promiseConstructFailResult = (reason: unknown): PromiseFailResult => {
+export const promiseCreateFailResult = (reason: unknown): PromiseFailResult => {
   return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
 }
 /**
  * 判断目标值是否为标准化的 Promise 失败结果。
  */
-export const isPromiseFailResult = (target: unknown): target is PromiseFailResult => {
-  return isPlainObject(target) && target["__type__"] === INTERNAL_PROMISE_FAIL_RESULT_TYPE
+export const promiseIsFailResult = (target: unknown): target is PromiseFailResult => {
+  if (isPlainObject(target) === false) {
+    return false
+  }
+  if ("__type__" in target === false) {
+    return false
+  }
+  if (target["__type__"] !== INTERNAL_PROMISE_FAIL_RESULT_TYPE) {
+    return false
+  }
+  return true
 }
 /**
  * 用作 `Promise.catch` 的 `onrejected` 回调，并返回标准化失败结果。
@@ -98,9 +136,8 @@ export const promiseFilterSuccessResults = <V>(
   results: Array<V | PromiseFailResult>,
 ): V[] => {
   const filtered = results.filter(result => {
-    return isPromiseFailResult(result) === false
+    return promiseIsFailResult(result) === false
   })
-  // oxlint-disable-next-line no-unsafe-type-assertion
   return filtered as V[]
 }
 /**
@@ -112,7 +149,7 @@ export const promiseFilterFailResults = <V>(
   const filtered = results.reduce<PromiseIndexedFailResult[]>((
     accumulatedResults, currentResult, index
   ) => {
-    if (isPromiseFailResult(currentResult)) {
+    if (promiseIsFailResult(currentResult)) {
       accumulatedResults.push({ ...currentResult, index })
     }
     return accumulatedResults
@@ -131,8 +168,10 @@ interface PromiseQueueRestPromiseMakerContext<V, S = unknown> {
   previousResult: V | PromiseFailResult
   state: S
 }
-type PromiseQueueFirstPromiseMaker<T, S = unknown> = (context: PromiseQueueFirstPromiseMakerContext<S>) => Promise<T>
-type PromiseQueueRestPromiseMaker<T, S = unknown> = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
+type PromiseQueueFirstPromiseMaker<T, S = unknown>
+  = (context: PromiseQueueFirstPromiseMakerContext<S>) => Promise<T>
+type PromiseQueueRestPromiseMaker<T, S = unknown>
+  = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
 type PromiseQueuePromiseMakers<T, S = unknown> = [
   PromiseQueueFirstPromiseMaker<T, S>,
   ...Array<PromiseQueueRestPromiseMaker<T, S>>
@@ -155,7 +194,7 @@ export interface PromiseQueueOptions {
  * // Expect: [1, 2]
  * const example1 = await promiseQueue<number>([
  *   async () => 1,
- *   async ({ previousResult }) => (isPromiseFailResult(previousResult) ? 0 : previousResult + 1),
+ *   async ({ previousResult }) => (promiseIsFailResult(previousResult) ? 0 : previousResult + 1),
  * ])
  * ```
  */
@@ -169,7 +208,6 @@ export const promiseQueue = async <T, S = unknown>(
   let context: PromiseQueueFirstPromiseMakerContext<S> | PromiseQueueRestPromiseMakerContext<T, S> = {
     index: 0,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
 
@@ -205,18 +243,20 @@ export const promiseQueue = async <T, S = unknown>(
 }
 
 interface PromiseRetryFirstPromiseMakerContext<S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: false
   state: S
 }
 interface PromiseRetryRestPromiseMakerContext<T, S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: true
   previousResult: T | PromiseFailResult
   state: S
 }
 type PromiseRetryPromiseMaker<T, S = unknown> = (
-  context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S>
+  context:
+    | PromiseRetryFirstPromiseMakerContext<S>
+    | PromiseRetryRestPromiseMakerContext<T, S>
 ) => Promise<T>
 
 /**
@@ -228,9 +268,10 @@ export interface PromiseRetryOptions {
    */
   breakTime?: number
   /**
+   * `0` 表示仅执行首次尝试，不进行额外重试。
    * @default Infinity
    */
-  maxTryTimes?: number
+  maxTryIndex?: number | undefined
 }
 /**
  * Retry while the predicate indicates the result is not acceptable.
@@ -257,34 +298,33 @@ export const promiseRetryWhile = async <T, S = unknown>(
 ): Promise<T | PromiseFailResult> => {
   const {
     breakTime = 0,
-    maxTryTimes = Infinity,
+    maxTryIndex = Infinity,
   } = options ?? {}
 
-  if (maxTryTimes < 1) {
-    throw new Error("`maxTryTimes` must be greater than 0.")
+  if (maxTryIndex < 0) {
+    throw new Error("`maxTryIndex` must be greater than or equal to 0.")
   }
 
-  let time = 1
+  let index = 0
   // oxlint-disable-next-line no-accumulating-spread
   let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
   let result = await promiseMaker(context).catch(promiseCatchToFailResult)
 
   while (
-    (isPromiseFailResult(result) || (await predicate(result)))
-    && time < maxTryTimes
+    (promiseIsFailResult(result) || (await predicate(result)))
+    && index < maxTryIndex
   ) {
-    time = time + 1
+    index = index + 1
     // oxlint-disable-next-line no-loop-func
     result = await new Promise<T | PromiseFailResult>((resolve) => {
       setTimeout(() => {
         context = {
           ...context,
-          time,
+          index,
           hasPreviousResult: true,
           previousResult: result,
         }
@@ -315,40 +355,39 @@ export const promiseRetryWhile = async <T, S = unknown>(
  * @see {@link promiseRetryWhile}
  */
 export const promiseRetryUntil = async <T, S = unknown>(
-  predicate: (value: T, time: number) => boolean | Promise<boolean>,
+  predicate: (value: T, index: number) => boolean | Promise<boolean>,
   promiseMaker: PromiseRetryPromiseMaker<T, S>,
   options?: PromiseRetryOptions | undefined,
 ): Promise<T | PromiseFailResult> => {
   const {
     breakTime = 0,
-    maxTryTimes = Infinity,
+    maxTryIndex = Infinity,
   } = options ?? {}
 
-  if (maxTryTimes < 1) {
-    throw new Error("`maxTryTimes` must be greater than 0.")
+  if (maxTryIndex < 0) {
+    throw new Error("`maxTryIndex` must be greater than or equal to 0.")
   }
 
-  let time = 1
+  let index = 0
   // oxlint-disable-next-line no-accumulating-spread
   let context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
   let result = await promiseMaker(context).catch(promiseCatchToFailResult)
 
   while (
-    (isPromiseFailResult(result) || !(await predicate(result, time)))
-    && time < maxTryTimes
+    (promiseIsFailResult(result) || !(await predicate(result, index)))
+    && index < maxTryIndex
   ) {
-    time = time + 1
+    index = index + 1
     // oxlint-disable-next-line no-loop-func
     result = await new Promise<T | PromiseFailResult>((resolve) => {
       setTimeout(() => {
         context = {
           ...context,
-          time,
+          index,
           hasPreviousResult: true,
           previousResult: result
         }
@@ -362,13 +401,14 @@ export const promiseRetryUntil = async <T, S = unknown>(
 
 /**
  * Start periodic asynchronous execution and return a function to stop it.
+ * Rejected runs are logged and ignored to avoid unhandled promise rejections.
  *
  * @example
  * ```
  * const records: number[] = []
- * const stop = promiseInterval(10, async (time) => {
- *   records.push(time)
- *   return time
+ * const stop = promiseInterval(10, async (index) => {
+ *   records.push(index)
+ *   return index
  * })
  * // Later: stop()
  * // Expect: typeof stop === "function"
@@ -377,13 +417,15 @@ export const promiseRetryUntil = async <T, S = unknown>(
  */
 export const promiseInterval = <T>(
   interval: number,
-  promiseMaker: (time: number) => Promise<T>,
+  promiseMaker: (index: number) => Promise<T>,
 ): (() => void) => {
-  let time = 1
+  let index = 0
 
   const intervalID = setInterval(() => {
-    void promiseMaker(time)
-    time = time + 1
+    void promiseMaker(index).catch((error: unknown) => {
+      console.error("[promiseInterval] unexpected error occurred:", error)
+    })
+    index = index + 1
   }, interval)
 
   return () => {
@@ -392,18 +434,20 @@ export const promiseInterval = <T>(
 }
 
 interface PromiseForeverFirstPromiseMakerContext<S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: false
   state: S
 }
 interface PromiseForeverRestPromiseMakerContext<T, S = unknown> {
-  time: number
+  index: number
   hasPreviousResult: true
   previousResult: T | PromiseFailResult
   state: S
 }
 type PromiseForeverPromiseMaker<T, S = unknown> = (
-  context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+  context:
+    | PromiseForeverFirstPromiseMakerContext<S>
+    | PromiseForeverRestPromiseMakerContext<T, S>
 ) => Promise<T>
 
 /**
@@ -414,60 +458,80 @@ export interface PromiseForeverOptions {
    * @default 0
    */
   breakTime?: number | undefined
-  onRejected?: ((time: number, result: PromiseFailResult) => void) | undefined
+  onRejected?: ((index: number, result: PromiseFailResult) => void) | undefined
+}
+export interface PromiseForeverResult {
+  index: number
+  isStopped: boolean
+  stop: () => void
 }
 /**
  * Continuously execute an async maker forever with optional delay and rejection hook.
  *
+ * - 至少会执行一次，`stop()` 可以用来提前停止后续执行。
+ * - `index` 从 `0` 开始，表示当前执行轮次。
+ * - 如果某一轮结束后已经排入了下一轮的定时器，调用 `stop()` 不会取消那一轮；
+ *   它只会阻止后续继续排入新的轮次。
+ *
  * @example
  * ```
  * let times = 0
- * promiseForever(async () => {
+ * const controller = promiseForever(async () => {
  *   times = times + 1
  *   return times
  * }, { breakTime: 0 })
- * // Expect: no return value
- * const example1 = promiseForever(async () => 1)
+ * controller.stop()
+ * // Expect: typeof controller.stop === "function"
+ * const example1 = typeof controller.stop
  * ```
  */
 export const promiseForever = <T, S = unknown>(
   promiseMaker: PromiseForeverPromiseMaker<T, S>,
   options?: PromiseForeverOptions | undefined,
-): void => {
+): PromiseForeverResult => {
   const {
     breakTime = 0,
     onRejected,
   } = options ?? {}
 
-  let time = 1
+  let index = 0
   let context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S> = {
-    time,
+    index,
     hasPreviousResult: false,
-    // oxlint-disable-next-line no-unsafe-type-assertion
     state: undefined as unknown as S
   }
+  const foreverResult: PromiseForeverResult = {
+    index,
+    isStopped: false,
+    stop: () => {
+      foreverResult.isStopped = true
+    }
+  }
 
   const handlePromise = (result: T | PromiseFailResult): void => {
-    time = time + 1
     setTimeout(() => {
+      index = index + 1
       context = {
         ...context,
-        time,
+        index,
         hasPreviousResult: true,
         previousResult: result
       }
+      foreverResult.index = index
       runPromise(context)
     }, breakTime)
   }
   const runPromise = (
-    context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
+    context:
+      | PromiseForeverFirstPromiseMakerContext<S>
+      | PromiseForeverRestPromiseMakerContext<T, S>
   ): void => {
     void promiseMaker(context)
       .catch((error: unknown) => {
         const failedResult = promiseCatchToFailResult(error)
         if (onRejected !== undefined) {
           try {
-            onRejected(time, failedResult)
+            onRejected(index, failedResult)
           }
           catch {
             // omit exceptions from execution of `onRejected`
@@ -478,8 +542,14 @@ export const promiseForever = <T, S = unknown>(
         }
         return failedResult
       })
-      .then(result => handlePromise(result))
+      .then(result => {
+        if (foreverResult.isStopped === false) {
+          handlePromise(result)
+        }
+      })
   }
 
   runPromise(context)
+
+  return foreverResult
 }

package/src/drizzle/pagination.ts

@@ -70,7 +70,6 @@ export const decodeCursor = <Model, Key extends keyof Model = keyof Model>(
       const key = orderBy[index]!.key
       return { ...acc, [key]: value }
     }, {})
-  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
   return decoded as DecodedCursor<Model, Key>
 }
 
@@ -164,7 +163,6 @@ export const buildCursorBasedPagination = <Table extends AnyPgTableWithColumns,
   type Model = InferModelFromPgTableWithColumns<Table>
 
   const decodeCursorResult = decodeCursor({
-    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
     modelForType: {} as Model,
     cursor,
     orderBy,

package/src/event/class-event-proxy.ts

@@ -66,7 +66,6 @@ export class ClassEventProxy<Target, Events extends EventsConstraint<Events>> {
 
     if (proxySubscriberEntry === undefined) {
       const managedSubscribers = new Map<Events[K], SubscriberEntry<Events, K>>()
-      // oxlint-disable-next-line no-unsafe-type-assertion
       const proxySubscriber = ((...args: Parameters<Events[K]>) => {
         const managedSubscriberEntries = [...managedSubscribers.values()]
         for (const managedSubscriberEntry of managedSubscriberEntries) {
@@ -196,7 +195,6 @@ export class ClassEventProxy<Target, Events extends EventsConstraint<Events>> {
 
     const events = Object.keys(proxySubscriberEntryMap)
     for (const event of events) {
-      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
       this.removeSubscribersOfEvent(target, event as keyof Events)
     }
     this.subscribers.delete(target)

package/src/event/instance-event-proxy.ts

@@ -58,7 +58,6 @@ export class InstanceEventProxy<Events extends EventsConstraint<Events>> {
 
     if (proxySubscriberEntry === undefined) {
       const managedSubscribers = new Map<Events[K], SubscriberEntry<Events, K>>()
-      // oxlint-disable-next-line no-unsafe-type-assertion
       const proxySubscriber = ((...args: Parameters<Events[K]>) => {
         const managedSubscriberEntries = [...managedSubscribers.values()]
         for (const managedSubscriberEntry of managedSubscriberEntries) {
@@ -168,7 +167,6 @@ export class InstanceEventProxy<Events extends EventsConstraint<Events>> {
     const events = Object.keys(this.subscribers)
 
     for (const event of events) {
-      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
       this.removeSubscribersOfEvent(event as keyof Events)
     }
     this.subscribers = {}