@highstate/contract 0.7.2 → 0.7.4

package/src/component.ts

@@ -0,0 +1,361 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+
+import type { Entity } from "./entity"
+import type { ArgumentValue, ArgumentValueSchema, Meta } from "./types"
+import {
+  type Static,
+  type TObject,
+  type TOptional,
+  type TSchema,
+  OptionalKind,
+} from "@sinclair/typebox"
+import { isNonNullish, mapValues, pickBy } from "remeda"
+import { Ajv } from "ajv"
+import { boundaryInput, type InstanceInput } from "./instance"
+import { type OptionalUndefinedFields, type OptionalEmptyRecords } from "./utils"
+import { registerInstance } from "./evaluation"
+
+const ajv = new Ajv()
+
+// Argument
+export type ComponentArgument = {
+  schema: ArgumentValueSchema
+  required: boolean
+  meta: Meta
+}
+
+type ComponentArgumentFullOptions = Meta & {
+  schema: ArgumentValueSchema
+  required?: boolean
+}
+
+export type ComponentArgumentOptions = ArgumentValueSchema | ComponentArgumentFullOptions
+
+export type ComponentArgumentOptionsToSchema<T extends ComponentArgumentOptions> = T extends TSchema
+  ? T
+  : T["required"] extends false
+    ? TOptional<T["schema"]>
+    : T["schema"]
+
+type ComponentArgumentMapToValue<T extends Record<string, ComponentArgumentOptions>> = {
+  [K in keyof T]: Static<ComponentArgumentOptionsToSchema<T[K]>>
+}
+
+// Input
+export type ComponentInput = {
+  type: string
+  required: boolean
+  multiple: boolean
+  meta: Meta
+}
+
+type ComponentInputFullOptions = Meta & {
+  entity: Entity
+  required?: boolean
+  multiple?: boolean
+}
+
+export type ComponentInputOptions = Entity | ComponentInputFullOptions
+
+type ComponentInputOptionsToOutputRef<T extends ComponentInputOptions> = T extends Entity
+  ? InstanceInput<T["type"]>
+  : T extends ComponentInputFullOptions
+    ? T["required"] extends false
+      ? T["multiple"] extends true
+        ? InstanceInput<T["entity"]["type"]>[] | undefined
+        : InstanceInput<T["entity"]["type"]> | undefined
+      : T["multiple"] extends true
+        ? InstanceInput<T["entity"]["type"]>[]
+        : InstanceInput<T["entity"]["type"]>
+    : never
+
+export type ComponentInputSpec = [entity: Entity, required: boolean, multiple: boolean]
+
+export type ComponentInputOptionsToSpec<T extends ComponentInputOptions> = T extends Entity
+  ? [T, true, false] // [Entity, required, multiple]
+  : T extends ComponentInputFullOptions
+    ? T["required"] extends false
+      ? T["multiple"] extends true
+        ? [T["entity"], false, true]
+        : [T["entity"], false, false]
+      : T["multiple"] extends true
+        ? [T["entity"], true, true]
+        : [T["entity"], true, false]
+    : never
+
+export type ComponentInputOptionsMapToSpecMap<T extends Record<string, ComponentInputOptions>> =
+  T extends Record<string, never>
+    ? Record<string, never>
+    : { [K in keyof T]: ComponentInputOptionsToSpec<T[K]> }
+
+type ComponentInputMapToValue<T extends Record<string, ComponentInputOptions>> =
+  OptionalUndefinedFields<{
+    [K in keyof T]: ComponentInputOptionsToOutputRef<T[K]>
+  }>
+
+type ComponentInputMapToReturnType<T extends Record<string, ComponentInputOptions>> =
+  T extends Record<string, never> ? void : ComponentInputMapToValue<T>
+
+// Params & Options
+export type ComponentParams<
+  TArgs extends Record<string, ComponentArgumentOptions>,
+  TInputs extends Record<string, ComponentInputOptions>,
+> = {
+  id: string
+  name: string
+  args: ComponentArgumentMapToValue<TArgs>
+  inputs: ComponentInputMapToValue<TInputs>
+}
+
+export type InputComponentParams<
+  TArgs extends Record<string, ArgumentValue>,
+  TInputs extends Record<string, unknown>,
+> = {
+  name: string
+} & OptionalEmptyRecords<{
+  args: TArgs
+  inputs: TInputs
+}>
+
+export type ComponentOptions<
+  TArgs extends Record<string, ComponentArgumentOptions>,
+  TInputs extends Record<string, ComponentInputOptions>,
+  TOutputs extends Record<string, ComponentInputOptions>,
+> = {
+  type: string
+  meta?: ComponentMeta
+
+  args?: TArgs
+  inputs?: TInputs
+  outputs?: TOutputs
+
+  create: (params: ComponentParams<TArgs, TInputs>) => ComponentInputMapToReturnType<TOutputs>
+}
+
+// Models
+export type ComponentMeta = Meta & {
+  primaryIcon?: string
+  primaryIconColor?: string
+  secondaryIcon?: string
+  secondaryIconColor?: string
+  category?: string
+  defaultNamePrefix?: string
+}
+
+export type ComponentModel = {
+  /**
+   * The type of the component.
+   */
+  type: string
+
+  /**
+   * The record of the argument schemas.
+   */
+  args: Record<string, ComponentArgument>
+
+  /**
+   * The record of the input schemas.
+   */
+  inputs: Record<string, ComponentInput>
+
+  /**
+   * The record of the output schemas.
+   */
+  outputs: Record<string, ComponentInput>
+
+  /**
+   * The extra metadata of the component.
+   */
+  meta: ComponentMeta
+
+  /**
+   * The hash of the component definition.
+   */
+  definitionHash: string
+}
+
+type InputSpecToOutputRef<T extends ComponentInputSpec> = T[1] extends true
+  ? T[2] extends true
+    ? InstanceInput<T[0]["type"]>[]
+    : InstanceInput<T[0]["type"]>
+  : T[2] extends true
+    ? InstanceInput<T[0]["type"]>[] | undefined
+    : InstanceInput<T[0]["type"]> | undefined
+
+export type OutputRefMap<TInputs extends Record<string, ComponentInputSpec>> =
+  TInputs extends Record<string, [string, never, never]>
+    ? Record<string, never>
+    : { [K in keyof TInputs]: InputSpecToOutputRef<TInputs[K]> }
+
+export const originalCreate = Symbol("originalCreate")
+
+export type Component<
+  TArgs extends Record<string, ArgumentValue> = Record<string, never>,
+  TInputs extends Record<string, ComponentInputSpec> = Record<string, never>,
+  TOutputs extends Record<string, ComponentInputSpec> = Record<string, never>,
+> = {
+  /**
+   * The non-generic model of the component.
+   */
+  model: ComponentModel
+
+  /**
+   * The entities used in the inputs or outputs of the component.
+   */
+  entities: Map<string, Entity>
+
+  /**
+   * Creates the component at the evaluation time.
+   */
+  (context: InputComponentParams<TArgs, OutputRefMap<TInputs>>): OutputRefMap<TOutputs>
+
+  /**
+   * The original create function.
+   *
+   * Used to calculate the definition hash.
+   */
+  [originalCreate]: (params: InputComponentParams<any, any>) => any
+}
+
+export type ArgumentOptionsMapToStatic<T extends Record<string, ComponentArgumentOptions>> =
+  T extends Record<string, never>
+    ? Record<string, never>
+    : Static<TObject<{ [K in keyof T]: ComponentArgumentOptionsToSchema<T[K]> }>>
+
+export function defineComponent<
+  TArgs extends Record<string, ComponentArgumentOptions> = Record<string, never>,
+  TInputs extends Record<string, ComponentInputOptions> = Record<string, never>,
+  TOutputs extends Record<string, ComponentInputOptions> = Record<string, never>,
+>(
+  options: ComponentOptions<TArgs, TInputs, TOutputs>,
+): Component<
+  ArgumentOptionsMapToStatic<TArgs>,
+  ComponentInputOptionsMapToSpecMap<TInputs>,
+  ComponentInputOptionsMapToSpecMap<TOutputs>
+> {
+  function create(params: InputComponentParams<any, any>): any {
+    const { name, args, inputs } = params
+    const id = `${options.type}:${name}`
+
+    validateArgs(id, create.model as ComponentModel, args ?? {})
+
+    const flatInputs = mapValues(pickBy(inputs ?? {}, isNonNullish), inputs => [inputs].flat(2))
+
+    return registerInstance(
+      create.model as ComponentModel,
+      {
+        id,
+        type: options.type,
+        name,
+        args: args ?? {},
+        inputs: mapValues(flatInputs, inputs => inputs.map(input => input[boundaryInput] ?? input)),
+        resolvedInputs: flatInputs,
+      },
+      () => {
+        const markedInputs = mapValues(flatInputs, (inputs, key) => {
+          const result = inputs.map(input => ({
+            ...input,
+            [boundaryInput]: { instanceId: id, output: key },
+          }))
+
+          return (create.model as ComponentModel).inputs?.[key]?.multiple === false
+            ? result[0]
+            : result
+        })
+
+        const outputs: Record<string, InstanceInput[]> =
+          options.create({
+            id,
+            name,
+            args: (args as any) ?? {},
+            inputs: markedInputs as any,
+          }) ?? {}
+
+        return mapValues(pickBy(outputs, isNonNullish), outputs => [outputs].flat(2))
+      },
+    )
+  }
+
+  create.entities = new Map<string, Entity>()
+  const mapInput = createInputMapper(create.entities)
+
+  create.model = {
+    type: options.type,
+    args: mapValues(options.args ?? {}, mapArgument),
+    inputs: mapValues(options.inputs ?? {}, mapInput),
+    outputs: mapValues(options.outputs ?? {}, mapInput),
+    meta: options.meta ?? {},
+  }
+
+  create[originalCreate] = options.create
+
+  return create as any
+}
+
+export function isComponent(value: unknown): value is Component {
+  return typeof value === "function" && "model" in value
+}
+
+export function mapArgument(value: ComponentArgumentOptions) {
+  if ("schema" in value) {
+    return {
+      schema: value.schema,
+      required: value.required ?? (!value.schema[OptionalKind] && !value.schema.default),
+      meta: {
+        displayName: value.displayName,
+        description: value.description,
+        color: value.color,
+      },
+    }
+  }
+
+  return {
+    schema: value,
+    required: !value[OptionalKind] && !value.default,
+    meta: {},
+  }
+}
+
+export function createInputMapper(entities: Map<string, Entity>) {
+  return (value: ComponentInputOptions) => {
+    if ("entity" in value) {
+      entities.set(value.entity.type, value.entity)
+
+      return {
+        type: value.entity.type,
+        required: value.required ?? true,
+        multiple: value.multiple ?? false,
+        meta: {
+          displayName: value.displayName,
+          description: value.description,
+          color: value.color,
+        },
+      }
+    }
+
+    entities.set(value.type, value)
+
+    return {
+      type: value.type,
+      required: true,
+      multiple: false,
+      meta: {},
+    }
+  }
+}
+
+function validateArgs(instanceId: string, model: ComponentModel, args: Record<string, unknown>) {
+  for (const [key, argModel] of Object.entries(model.args)) {
+    const value = args[key]
+    if (!value && argModel.required) {
+      throw new Error(`Missing required argument "${key}" for instance "${instanceId}"`)
+    }
+
+    if (value && !ajv.validate(argModel.schema, value)) {
+      throw new Error(`Invalid argument "${key}" for instance "${instanceId}": ${ajv.errorsText()}`)
+    }
+  }
+}

package/src/entity.ts

@@ -0,0 +1,54 @@
+import type { TAnySchema, TSchema } from "@sinclair/typebox"
+import type { Meta } from "./types"
+import type { PartialKeys } from "./utils"
+
+/**
+ * The entity is some abstract object which can be passed from one component to another through their inputs and outputs.
+ * Every entity must have a type.
+ * Every component inputs and outputs will reference such types and only entities of the same type can be passed.
+ */
+export type Entity<TType extends string = string, TEntitySchema extends TSchema = TSchema> = {
+  /**
+   * The static type of the entity.
+   */
+  type: TType
+
+  /**
+   * The JSON schema of the entity value.
+   */
+  schema: TEntitySchema
+
+  /**
+   * The extra metadata of the entity.
+   */
+  meta: Meta
+
+  /**
+   * The hash of the entity definition.
+   */
+  definitionHash: string
+}
+
+export type EntityOptions<TType extends string, TSchema extends TAnySchema> = Omit<
+  PartialKeys<Entity<TType, TSchema>, "meta">,
+  "definitionHash"
+>
+
+export function defineEntity<TType extends string, TSchema extends TAnySchema>(
+  options: EntityOptions<TType, TSchema>,
+): Entity<TType, TSchema> {
+  return {
+    meta: {},
+    ...options,
+  } as Entity<TType, TSchema>
+}
+
+export function isEntity(value: unknown): value is Entity {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    "schema" in value &&
+    "meta" in value
+  )
+}

package/src/evaluation.ts

@@ -0,0 +1,60 @@
+import type { ComponentModel } from "./component"
+import { mapValues } from "remeda"
+import { boundaryInput, type InstanceInput, type InstanceModel } from "./instance"
+import { isUnitModel } from "./unit"
+
+export type CompositeInstance = {
+  instance: InstanceModel
+  children: InstanceModel[]
+}
+
+const compositeInstances: Map<string, CompositeInstance> = new Map()
+let currentCompositeInstance: CompositeInstance | null = null
+
+export function resetEvaluation(): void {
+  compositeInstances.clear()
+  currentCompositeInstance = null
+}
+
+export function getCompositeInstances(): CompositeInstance[] {
+  return Array.from(compositeInstances.values())
+}
+
+export function registerInstance<T>(
+  component: ComponentModel,
+  instance: InstanceModel,
+  fn: () => T,
+): T {
+  if (currentCompositeInstance) {
+    instance.parentId = currentCompositeInstance.instance.id
+    currentCompositeInstance.children.push(instance)
+  }
+
+  let previousParentInstance: CompositeInstance | null = null
+  if (!isUnitModel(component)) {
+    previousParentInstance = currentCompositeInstance
+    currentCompositeInstance = { instance, children: [] }
+    compositeInstances.set(currentCompositeInstance.instance.id, currentCompositeInstance)
+  }
+
+  try {
+    const outputs = fn() as Record<string, InstanceInput[]>
+
+    instance.resolvedOutputs = outputs
+    instance.outputs = mapValues(outputs ?? {}, outputs =>
+      outputs.map(output => output[boundaryInput] ?? output),
+    )
+
+    // mark all outputs with the boundary input of the instance
+    return mapValues(outputs, (outputs, outputKey) =>
+      outputs.map(output => ({
+        ...output,
+        [boundaryInput]: { instanceId: instance.id, output: outputKey },
+      })),
+    ) as T
+  } finally {
+    if (previousParentInstance) {
+      currentCompositeInstance = previousParentInstance
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export {
+  type InstanceInput,
+  type HubInput,
+  type InstanceModel,
+  type Position,
+  getInstanceId,
+  parseInstanceId,
+  findInput,
+  findRequiredInput,
+} from "./instance"
+export { getCompositeInstances, resetEvaluation, type CompositeInstance } from "./evaluation"
+export { type Entity, defineEntity, isEntity } from "./entity"
+export {
+  type Component,
+  type ComponentModel,
+  type ComponentMeta,
+  type ComponentArgument,
+  type ComponentInput,
+  type ComponentInputSpec,
+  defineComponent,
+  isComponent,
+  originalCreate,
+} from "./component"
+export { type Unit, type UnitModel, type UnitSource, defineUnit, isUnitModel } from "./unit"
+export { type RequiredKeys, type PartialKeys, text, trimIndentation } from "./utils"
+export { type ArgumentValue, type ArgumentValueSchema } from "./types"
+export { type Static } from "@sinclair/typebox"
+
+import { Type as BaseType, type TLiteral, type TUnion } from "@sinclair/typebox"
+
+type MapToLiteral<T extends readonly string[]> = {
+  [K in keyof T]: T[K] extends string ? TLiteral<T[K]> : never
+}
+
+function StringEnum<T extends string[]>(values: [...T]): TUnion<MapToLiteral<T>> {
+  return Type.Union(values.map(value => Type.Literal(value))) as TUnion<MapToLiteral<T>>
+}
+
+export const Type = {
+  ...BaseType,
+  StringEnum,
+} as typeof BaseType & { StringEnum: typeof StringEnum }

package/src/instance.ts

@@ -0,0 +1,165 @@
+declare const type: unique symbol
+
+export type InstanceInput<TType extends string = string> = {
+  [type]?: TType
+  [boundaryInput]?: InstanceInput
+  instanceId: string
+  output: string
+}
+
+export const boundaryInput = Symbol("boundaryInput")
+
+export type HubInput = {
+  hubId: string
+}
+
+export type Position = {
+  x: number
+  y: number
+}
+
+export type InstanceModel = {
+  /**
+   * The id of the instance unique within the project.
+   *
+   * The format is `${instanceType}:${instanceName}`.
+   */
+  id: string
+
+  /**
+   * The type of the instance.
+   */
+  type: string
+
+  /**
+   * The name of the instance.
+   *
+   * Must be unique within instances of the same type in the project.
+   */
+  name: string
+
+  /**
+   * The static arguments passed to the instance.
+   */
+  args?: Record<string, unknown>
+
+  /**
+   * The direct instances passed as inputs to the instance.
+   */
+  inputs?: Record<string, InstanceInput[]>
+
+  /**
+   * The resolved unit inputs for the instance.
+   *
+   * Only for computed composite instances.
+   */
+  resolvedInputs?: Record<string, InstanceInput[]>
+
+  /**
+   * The inputs passed to the instance from the hubs.
+   *
+   * Only for designer-first instances.
+   */
+  hubInputs?: Record<string, HubInput[]>
+
+  /**
+   * The inputs injected to the instance from the hubs.
+   *
+   * While `hubInputs` allows to pass hubs to distinct inputs,
+   * `injectionInputs` allows to pass hubs to the instance as a whole filling all inputs with matching types.
+   *
+   * Only for designer-first instances.
+   */
+  injectionInputs?: HubInput[]
+
+  /**
+   * The position of the instance on the canvas.
+   *
+   * Only for designer-first instances.
+   */
+  position?: Position
+
+  /**
+   * The id of the top level parent instance.
+   *
+   * Only for child instances of the composite instances.
+   */
+  parentId?: string
+
+  /**
+   * The direct instance inputs and same-level children outputs returned by the instance as outputs.
+   *
+   * Only for computed composite instances.
+   */
+  outputs?: Record<string, InstanceInput[]>
+
+  /**
+   * The resolved unit outputs for the instance.
+   *
+   * Only for computed composite instances.
+   */
+  resolvedOutputs?: Record<string, InstanceInput[]>
+}
+
+/**
+ * Formats the instance id from the instance type and instance name.
+ *
+ * @param instanceType The type of the instance.
+ * @param instanceName The name of the instance.
+ *
+ * @returns The formatted instance id.
+ */
+export function getInstanceId(instanceType: string, instanceName: string): string {
+  return `${instanceType}:${instanceName}`
+}
+
+/**
+ * Parses the instance id into the instance type and instance name.
+ *
+ * @param instanceId The instance id to parse.
+ *
+ * @returns The instance type and instance name.
+ */
+export function parseInstanceId(instanceId: string): [instanceType: string, instanceName: string] {
+  const parts = instanceId.split(":")
+
+  if (parts.length !== 2) {
+    throw new Error(`Invalid instance key: ${instanceId}`)
+  }
+
+  return parts as [string, string]
+}
+
+export function findInput<T extends string>(
+  inputs: InstanceInput<T>[],
+  name: string,
+): InstanceInput<T> | null {
+  const matchedInputs = inputs.filter(
+    input => parseInstanceId(input.instanceId)[1] === name || input.instanceId === name,
+  )
+
+  if (matchedInputs.length === 0) {
+    return null
+  }
+
+  if (1 < matchedInputs.length) {
+    throw new Error(
+      `Multiple inputs found for "${name}": ${matchedInputs.map(input => input.instanceId).join(", ")}. Specify the full instance id to disambiguate.`,
+    )
+  }
+
+  return matchedInputs[0]
+}
+
+export function findRequiredInput<T extends string>(
+  inputs: InstanceInput<T>[],
+  name: string,
+): InstanceInput<T> {
+  const input = findInput(inputs, name)
+
+  if (input === null) {
+    throw new Error(`Required input "${name}" not found.`)
+  }
+
+  return input
+}