@pdfking/planner

Types

types

TaskDescriptor

type TaskDescriptor = Record<
  string,
  {
    input: TaskIO
    output: TaskIO
    exec: TaskExec
    props: boolean
  }
>

TrackingStatus

type TrackingStatus = {
  done: number
  name: string
  total: number | undefined
}

TrackingMessage

type TrackingMessage =
  | EnumType<TrackingEnum.START, { guid: StringGUID }>
  | EnumType<
      TrackingEnum.STOP,
      {
        guid: StringGUID
        error: EnumType<string | number> | undefined
      }
    >
  | EnumType<TrackingEnum.STATUS, { guid: StringGUID } & TrackingStatus>

TrackingCallback

type TrackingCallback = (message: TrackingMessage) => void

Executor

type Executor<TM extends TaskMap, C = unknown> = {
  plan: Plan<TM>
  execute<X>(node: AtomFunction<X>, context?: C): Promise<X>
  execute<X>(node: PlanFunction<X>, context?: C): AsyncGenerator<X>
}

Struct

type Struct = Atom | Struct[] | { [key: string]: Struct }

T

type T = { [generic]: true }

The caller's type, in the signature of a task that works on any: an operation writes T where a generic function would take a type parameter (Take: (props, input: AsyncGenerator<T>) => Promise<T>), and every plan call binds it to what that call is handed, the way a generic call would.

BatchedItem

type BatchedItem<X> = {
  batch: number
  index: number
  value: X
}

PlanFunction

type PlanFunction<X> = {
  name: string
  data: Struct
  inputs: PlanFunction<unknown>[]
  inputIO: TaskIO
  outputIO: TaskIO
  hash: StringGUID
  [phantom]?: X
}

A plan is function nodes all the way down: name is the task, inputs the nodes whose output it runs on. hash identifies what the node computes, built from the hashes of its inputs, never from the data underneath them.

AtomFunction

type AtomFunction<X> = PlanFunction<X> & { outputIO: TaskIO.ATOM }

Plan

type Plan<TM extends TaskMap> = {
  [K in keyof TM & string]: TM[K] extends (
    props: infer P,
    ...inputs: infer IS extends unknown[]
  ) => any
    ? PlanCall<TM[K], P, IS>
    : never
}

TaskMap

type TaskMap = Record<
  string,
  (props: any, ...args: any[]) => AsyncGenerator<any> | Promise<any>
>

TaskContext

type TaskContext<TM extends TaskMap, C = unknown> = {
  // opaque execution context forwarded from the `execute` call that invoked
  // this task — defined and interpreted by the hosting runtime, not here.
  // The default keeps context-agnostic tasks usable under any runtime.
  context?: C
  emit: (status: TrackingStatus) => void
  guid: StringGUID
} & Executor<TM, C>

TaskImplementation

type TaskImplementation<TM extends TaskMap, K extends keyof TM & string, C = unknown> = (
  context: TaskContext<TM, C>,
  ...args: Parameters<TM[K]>
) => ReturnType<TM[K]>

TaskImplementations

type TaskImplementations<TM extends TaskMap, C = unknown> = {
  [K in keyof TM & string]: TaskImplementation<TM, K, C>
}