@jvs-milkdown/ctx 1.0.0

package/src/plugin/ctx.ts

@@ -0,0 +1,136 @@
+import type { Container, Slice, SliceType } from '../context'
+import type { Meta } from '../inspector'
+import type { Clock, TimerType } from '../timer'
+
+import { Inspector } from '../inspector'
+
+/// The ctx object that can be accessed in plugin and action.
+export class Ctx {
+  /// @internal
+  readonly #container: Container
+  /// @internal
+  readonly #clock: Clock
+  /// @internal
+  readonly #meta?: Meta
+  /// @internal
+  readonly #inspector?: Inspector
+
+  /// Create a ctx object with container and clock.
+  constructor(container: Container, clock: Clock, meta?: Meta) {
+    this.#container = container
+    this.#clock = clock
+    this.#meta = meta
+    if (meta) this.#inspector = new Inspector(container, clock, meta)
+  }
+
+  /// Get metadata of the ctx.
+  get meta() {
+    return this.#meta
+  }
+
+  /// Get the inspector of the ctx.
+  get inspector() {
+    return this.#inspector
+  }
+
+  /// Produce a new ctx with metadata.
+  /// The new ctx will link to the same container and clock with the current ctx.
+  /// If the metadata is empty, it will return the current ctx.
+  readonly produce = (meta?: Meta) => {
+    if (meta && Object.keys(meta).length)
+      return new Ctx(this.#container, this.#clock, { ...meta })
+
+    return this
+  }
+
+  /// Add a slice into the ctx.
+  readonly inject = <T>(sliceType: SliceType<T>, value?: T) => {
+    const slice = sliceType.create(this.#container.sliceMap)
+    if (value != null) slice.set(value)
+
+    this.#inspector?.onInject(sliceType)
+
+    return this
+  }
+
+  /// Remove a slice from the ctx.
+  readonly remove = <T, N extends string = string>(
+    sliceType: SliceType<T, N> | N
+  ) => {
+    this.#container.remove(sliceType)
+    this.#inspector?.onRemove(sliceType)
+    return this
+  }
+
+  /// Add a timer into the ctx.
+  readonly record = (timerType: TimerType) => {
+    timerType.create(this.#clock.store)
+    this.#inspector?.onRecord(timerType)
+    return this
+  }
+
+  /// Remove a timer from the ctx.
+  readonly clearTimer = (timerType: TimerType) => {
+    this.#clock.remove(timerType)
+    this.#inspector?.onClear(timerType)
+    return this
+  }
+
+  /// Check if the ctx has a slice.
+  readonly isInjected = <T, N extends string = string>(
+    sliceType: SliceType<T, N> | N
+  ) => this.#container.has(sliceType)
+
+  /// Check if the ctx has a timer.
+  readonly isRecorded = (timerType: TimerType) => this.#clock.has(timerType)
+
+  /// Get a slice from the ctx.
+  readonly use = <T, N extends string = string>(
+    sliceType: SliceType<T, N> | N
+  ): Slice<T, N> => {
+    this.#inspector?.onUse(sliceType)
+    return this.#container.get(sliceType)
+  }
+
+  /// Get a slice value from the ctx.
+  readonly get = <T, N extends string>(sliceType: SliceType<T, N> | N) =>
+    this.use(sliceType).get()
+
+  /// Get a slice value from the ctx.
+  readonly set = <T, N extends string>(
+    sliceType: SliceType<T, N> | N,
+    value: T
+  ) => this.use(sliceType).set(value)
+
+  /// Update a slice value from the ctx by a callback.
+  readonly update = <T, N extends string>(
+    sliceType: SliceType<T, N> | N,
+    updater: (prev: T) => T
+  ) => this.use(sliceType).update(updater)
+
+  /// Get a timer from the ctx.
+  readonly timer = (timer: TimerType) => this.#clock.get(timer)
+
+  /// Resolve a timer from the ctx.
+  readonly done = (timer: TimerType) => {
+    this.timer(timer).done()
+    this.#inspector?.onDone(timer)
+  }
+
+  /// Start a timer from the ctx.
+  readonly wait = (timer: TimerType) => {
+    const promise = this.timer(timer).start()
+    this.#inspector?.onWait(timer, promise)
+    return promise
+  }
+
+  /// Start a list of timers from the ctx, the list is stored in a slice in the ctx.
+  /// This is equivalent to
+  ///
+  /// ```typescript
+  /// Promise.all(ctx.get(slice).map(x => ctx.wait(x))).
+  /// ```
+  readonly waitTimers = async (slice: SliceType<TimerType[]>) => {
+    await Promise.all(this.get(slice).map((x) => this.wait(x)))
+  }
+}

package/src/plugin/index.ts

@@ -0,0 +1,2 @@
+export * from './ctx'
+export * from './types'

package/src/plugin/types.ts

@@ -0,0 +1,43 @@
+import type { Meta } from '../inspector'
+import type { Ctx } from './ctx'
+
+/// @internal
+export type Cleanup = () => void | Promise<void>
+
+/// @internal
+export type RunnerReturnType = void | Promise<void> | Cleanup | Promise<Cleanup>
+
+/// @internal
+export type CtxRunner = () => RunnerReturnType
+
+/// The type of the plugin.
+///
+/// ```typescript
+/// // A full plugin example
+/// const plugin1 = (ctx: Ctx) => {
+///   // setup
+///   return async () => {
+///     // run
+///     return async () => {
+///       // cleanup
+///     }
+///   }
+/// }
+///
+/// // A plugin doesn't need to return a cleanup function
+/// const plugin2 = (ctx: Ctx) => {
+///   // setup
+///   return async () => {
+///     // run
+///   }
+/// }
+///
+/// // A plugin doesn't need to be async
+/// const plugin3 = (ctx: Ctx) => {
+///   // setup
+///   return () => {
+///     // run
+///   }
+/// }
+/// ```
+export type MilkdownPlugin = { meta?: Meta } & ((ctx: Ctx) => CtxRunner)

package/src/timer/clock.spec.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { Clock } from './clock'
+import { TimerType } from './timer'
+
+describe('timing/clock', () => {
+  it('createClock', () => {
+    const clock = new Clock()
+    const timer = new TimerType('timer')
+    const timerNotRegistered = new TimerType('not')
+
+    timer.create(clock.store)
+
+    expect(clock.get(timer)).toBe(clock.store.get(timer.id))
+    expect(() => clock.get(timerNotRegistered)).toThrow()
+  })
+
+  it('remove', () => {
+    const clock = new Clock()
+    const timer = new TimerType('timer')
+    timer.create(clock.store)
+    expect(clock.get(timer)).toBe(clock.store.get(timer.id))
+
+    clock.remove(timer)
+    expect(() => clock.get(timer)).toThrow()
+  })
+})

package/src/timer/clock.ts

@@ -0,0 +1,29 @@
+import { timerNotFound } from '@jvs-milkdown/exception'
+
+import type { Timer, TimerType } from './timer'
+
+/// @internal
+export type TimerMap = Map<symbol, Timer>
+
+/// Container is a map of timers.
+export class Clock {
+  /// @internal
+  readonly store: TimerMap = new Map()
+
+  /// Get a timer from the clock by timer type.
+  get = (timer: TimerType) => {
+    const meta = this.store.get(timer.id)
+    if (!meta) throw timerNotFound(timer.name)
+    return meta
+  }
+
+  /// Remove a timer from the clock by timer type.
+  remove = (timer: TimerType) => {
+    this.store.delete(timer.id)
+  }
+
+  // Check if the clock has a timer by timer type.
+  has = (timer: TimerType) => {
+    return this.store.has(timer.id)
+  }
+}

package/src/timer/index.ts

@@ -0,0 +1,2 @@
+export * from './clock'
+export * from './timer'

package/src/timer/timer.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+
+import { TimerType } from './timer'
+
+describe('timing/timing', () => {
+  it('createTimer', async () => {
+    const timerType = new TimerType('timer')
+    const map = new Map()
+    const timer = timerType.create(map)
+    setTimeout(() => {
+      timer.done()
+    }, 10)
+
+    await expect(timer.start()).resolves.toBeUndefined()
+
+    // should still can be waited after it's resolved
+    await expect(timer.start()).resolves.toBeUndefined()
+  })
+
+  it('timeout', async () => {
+    const timerType = new TimerType('timer', 10)
+    const map = new Map()
+    const timer = timerType.create(map)
+
+    await expect(timer.start()).rejects.toStrictEqual(
+      new Error('Timing timer timeout.')
+    )
+  })
+})

package/src/timer/timer.ts

@@ -0,0 +1,109 @@
+import type { TimerMap } from './clock'
+
+export type TimerStatus = 'pending' | 'resolved' | 'rejected'
+
+/// Timer is a promise that can be resolved by calling done.
+export class Timer {
+  /// The type of the timer.
+  readonly type: TimerType
+
+  /// @internal
+  #promise: Promise<void> | null = null
+  /// @internal
+  #listener: EventListener | null = null
+  /// @internal
+  readonly #eventUniqId: symbol
+  /// @internal
+  #status: TimerStatus = 'pending'
+
+  /// @internal
+  constructor(clock: TimerMap, type: TimerType) {
+    this.#eventUniqId = Symbol(type.name)
+    this.type = type
+    clock.set(type.id, this)
+  }
+
+  /// The status of the timer.
+  /// Can be `pending`, `resolved` or `rejected`.
+  get status() {
+    return this.#status
+  }
+
+  /// Start the timer, which will return a promise.
+  /// If the timer is already started, it will return the same promise.
+  /// If the timer is not resolved in the timeout, it will reject the promise.
+  start = () => {
+    this.#promise ??= new Promise((resolve, reject) => {
+      this.#listener = (e: Event) => {
+        if (!(e instanceof CustomEvent)) return
+
+        if (e.detail.id === this.#eventUniqId) {
+          this.#status = 'resolved'
+          this.#removeListener()
+          e.stopImmediatePropagation()
+          resolve()
+        }
+      }
+
+      this.#waitTimeout(() => {
+        if (this.#status === 'pending') this.#status = 'rejected'
+
+        this.#removeListener()
+        reject(new Error(`Timing ${this.type.name} timeout.`))
+      })
+
+      this.#status = 'pending'
+      addEventListener(this.type.name, this.#listener)
+    })
+
+    return this.#promise
+  }
+
+  /// Resolve the timer.
+  done = () => {
+    const event = new CustomEvent(this.type.name, {
+      detail: { id: this.#eventUniqId },
+    })
+    dispatchEvent(event)
+  }
+
+  /// @internal
+  #removeListener = () => {
+    if (this.#listener) removeEventListener(this.type.name, this.#listener)
+  }
+
+  /// @internal
+  #waitTimeout = (ifTimeout: () => void) => {
+    setTimeout(() => {
+      ifTimeout()
+    }, this.type.timeout)
+  }
+}
+
+/// Timer type can be used to create timers in different clocks.
+export class TimerType {
+  /// The unique id of the timer type.
+  readonly id: symbol
+  /// The name of the timer type.
+  readonly name: string
+  /// The timeout of the timer type.
+  readonly timeout: number
+
+  /// Create a timer type with a name and a timeout.
+  /// The name should be unique in the clock.
+  constructor(name: string, timeout = 3000) {
+    this.id = Symbol(`Timer-${name}`)
+    this.name = name
+    this.timeout = timeout
+  }
+
+  /// Create a timer with a clock.
+  create = (clock: TimerMap): Timer => {
+    return new Timer(clock, this)
+  }
+}
+
+/// Create a timer type with a name and a timeout.
+/// This is equivalent to `new TimerType(name, timeout)`.
+export const createTimer = (name: string, timeout = 3000) =>
+  new TimerType(name, timeout)