@highstate/contract 0.9.15 → 0.9.18

package/src/evaluation.ts

@@ -1,41 +1,87 @@
-import type { ComponentModel } from "./component"
 import { mapValues } from "remeda"
-import { boundaryInput, type InstanceInput, type InstanceModel } from "./instance"
-import { isUnitModel } from "./unit"
+import { boundaryInput, type Component } from "./component"
+import { type InstanceInput, type InstanceModel } from "./instance"
+import { isUnitModel } from "./component"
 
-export type CompositeInstance = {
+export type RuntimeInstance = {
   instance: InstanceModel
-  children: InstanceModel[]
+  component: Component
 }
 
-const compositeInstances: Map<string, CompositeInstance> = new Map()
-let currentCompositeInstance: CompositeInstance | null = null
+function formatInstancePath(instance: InstanceModel): string {
+  let result = instance.id
+  while (instance.parentId) {
+    const parent = runtimeInstances.get(instance.parentId)?.instance
+    if (!parent) {
+      break
+    }
+
+    result = `${parent.id} -> ${result}`
+    instance = parent
+  }
+
+  return result
+}
 
+export class InstanceNameConflictError extends Error {
+  constructor(
+    readonly instanceId: string,
+    readonly firstPath: string,
+    readonly secondPath: string,
+  ) {
+    super(
+      `Multiple instances produced with the same instance ID "${instanceId}":\n` +
+        `1. ${firstPath}\n` +
+        `2. ${secondPath}`,
+    )
+
+    this.name = "InstanceNameConflictError"
+  }
+}
+
+let currentInstance: InstanceModel | null = null
+
+const runtimeInstances: Map<string, RuntimeInstance> = new Map()
+
+/**
+ * Resets the evaluation state, clearing all collected composite instances and runtime instances.
+ */
 export function resetEvaluation(): void {
-  compositeInstances.clear()
-  currentCompositeInstance = null
+  runtimeInstances.clear()
+  currentInstance = null
 }
 
-export function getCompositeInstances(): CompositeInstance[] {
-  return Array.from(compositeInstances.values())
+/**
+ * Returns all runtime instances collected during the evaluation.
+ *
+ * Note that these instances are not serializable.
+ */
+export function getRuntimeInstances(): RuntimeInstance[] {
+  return Array.from(runtimeInstances.values())
 }
 
-export function registerInstance<T>(
-  component: ComponentModel,
-  instance: InstanceModel,
-  fn: () => T,
-): T {
-  let previousParentInstance: CompositeInstance | null = null
+export function registerInstance<T>(component: Component, instance: InstanceModel, fn: () => T): T {
+  if (runtimeInstances.has(instance.id)) {
+    const existing = runtimeInstances.get(instance.id)!
+
+    throw new InstanceNameConflictError(
+      instance.id,
+      formatInstancePath(existing.instance),
+      formatInstancePath(instance),
+    )
+  }
+
+  runtimeInstances.set(instance.id, { instance, component })
+
+  let previousParentInstance: InstanceModel | null = null
 
-  if (currentCompositeInstance) {
-    instance.parentId = currentCompositeInstance.instance.id
-    currentCompositeInstance.children.push(instance)
+  if (currentInstance) {
+    instance.parentId = currentInstance.id
   }
 
-  if (!isUnitModel(component)) {
-    previousParentInstance = currentCompositeInstance
-    currentCompositeInstance = { instance, children: [] }
-    compositeInstances.set(currentCompositeInstance.instance.id, currentCompositeInstance)
+  if (!isUnitModel(component.model)) {
+    previousParentInstance = currentInstance
+    currentInstance = instance
   }
 
   try {
@@ -55,7 +101,7 @@ export function registerInstance<T>(
     ) as T
   } finally {
     if (previousParentInstance) {
-      currentCompositeInstance = previousParentInstance
+      currentInstance = previousParentInstance
     }
   }
 }

package/src/i18n.ts

@@ -0,0 +1,25 @@
+const knownAbbreviationsMap = new Map<string, string>()
+
+export function registerKnownAbbreviations(abbreviations: string[]) {
+  for (const abbr of abbreviations) {
+    const lower = abbr.toLowerCase()
+    if (!knownAbbreviationsMap.has(lower)) {
+      knownAbbreviationsMap.set(lower, abbr)
+    }
+  }
+}
+
+export function camelCaseToHumanReadable(text: string) {
+  const words = text.split(/(?=[A-Z])|_|-|\./)
+
+  return words
+    .map(word => {
+      const lower = word.toLowerCase()
+      if (knownAbbreviationsMap.has(lower)) {
+        return knownAbbreviationsMap.get(lower)
+      }
+
+      return word.charAt(0).toUpperCase() + word.slice(1)
+    })
+    .join(" ")
+}

package/src/index.ts

@@ -1,69 +1,52 @@
+export * from "./entity"
+export * from "./instance"
+export * from "./unit"
+export * from "./i18n"
+export * from "./meta"
+
 export {
-  type InstanceInput,
-  type HubInput,
-  type InstanceModel,
-  type Position,
-  getInstanceId,
-  parseInstanceId,
-  findInput,
-  findRequiredInput,
-  findInputs,
-  findRequiredInputs,
-} from "./instance"
-export { getCompositeInstances, resetEvaluation, type CompositeInstance } from "./evaluation"
-export { type Entity, defineEntity, isEntity } from "./entity"
+  // common utilities
+  bytesToHumanReadable,
+  trimIndentation,
+  text,
+
+  // type utilities
+  type PartialKeys,
+  type RequiredKeys,
+} from "./utils"
+
 export {
-  type Component,
-  type ComponentModel,
-  type ComponentMeta,
-  type ComponentArgument,
-  type ComponentInput,
-  type ComponentInputSpec,
-  type ComponentArgumentSpec,
-  type ComponentArgumentSpecToStatic,
+  // user API
   defineComponent,
+  $args,
+  $inputs,
+  $outputs,
+
+  // extra helpers
   isComponent,
-  originalCreate,
-} from "./component"
-export { type Unit, type UnitModel, type UnitSource, defineUnit, isUnitModel } from "./unit"
-export {
-  type RequiredKeys,
-  type PartialKeys,
-  text,
-  trimIndentation,
-  bytesToHumanReadable,
-} from "./utils"
-export { type ArgumentValue, type ArgumentValueSchema } from "./types"
-export * from "@sinclair/typebox"
+  setValidationEnabled,
+  isUnitModel,
 
-import {
-  Type as BaseType,
-  type Static,
-  type TLiteral,
-  type TSchema,
-  type TUnion,
-} from "@sinclair/typebox"
+  // types
+  type Component,
+  type ComponentModel,
+  type ComponentInput,
+  type ComponentArgument,
 
-type MapToLiteral<T extends readonly string[]> = {
-  [K in keyof T]: T[K] extends string ? TLiteral<T[K]> : never
-}
+  // schemas
+  componentModelSchema,
+  componentInputSchema,
+  componentArgumentSchema,
 
-function StringEnum<T extends string[]>(values: [...T]): TUnion<MapToLiteral<T>> {
-  return Type.Union(values.map(value => Type.Literal(value))) as TUnion<MapToLiteral<T>>
-}
+  // for evaluation
+  originalCreate,
+} from "./component"
 
-function Default<T extends TSchema>(
-  schema: T,
-  defaultValue: Static<T>,
-): T & { default: Static<T> } {
-  return { ...schema, default: defaultValue }
-}
+export {
+  type RuntimeInstance,
+  InstanceNameConflictError,
+  getRuntimeInstances,
+  resetEvaluation,
+} from "./evaluation"
 
-export const Type = {
-  ...BaseType,
-  StringEnum,
-  Default,
-} as typeof BaseType & {
-  StringEnum: typeof StringEnum
-  Default: typeof Default
-}
+export { z } from "zod"

package/src/instance.ts

@@ -1,66 +1,55 @@
+import type { boundaryInput } from "./component"
+import { z } from "zod"
+import { genericNameSchema } from "./meta"
+
 declare const type: unique symbol
 
 export type InstanceInput<TType extends string = string> = {
   [type]?: TType
   [boundaryInput]?: InstanceInput
-  instanceId: string
+  instanceId: InstanceId
   output: string
 }
 
-export const boundaryInput = Symbol("boundaryInput")
+export const positionSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+})
 
-export type HubInput = {
-  hubId: string
-}
+export type Position = z.infer<typeof positionSchema>
 
-export type Position = {
-  x: number
-  y: number
-}
+export const instanceIdSchema = z.templateLiteral([genericNameSchema, ":", genericNameSchema])
 
-export type InstanceModel = {
-  /**
-   * The id of the instance unique within the project.
-   *
-   * The format is `${instanceType}:${instanceName}`.
-   */
-  id: string
+export type InstanceId = z.infer<typeof instanceIdSchema>
 
-  /**
-   * The type of the instance.
-   */
-  type: string
+export const instanceInputSchema = z.object({
+  instanceId: instanceIdSchema,
+  output: z.string(),
+})
 
-  /**
-   * The name of the instance.
-   *
-   * Must be unique within instances of the same type in the project.
-   */
-  name: string
+export const hubInputSchema = z.object({
+  hubId: z.string(),
+})
+
+export type HubInput = z.infer<typeof hubInputSchema>
 
+export const instanceModelPatchSchema = z.object({
   /**
    * The static arguments passed to the instance.
    */
-  args?: Record<string, unknown>
+  args: z.record(z.string(), z.unknown()).optional(),
 
   /**
    * The direct instances passed as inputs to the instance.
    */
-  inputs?: Record<string, InstanceInput[]>
+  inputs: z.record(z.string(), z.array(instanceInputSchema)).optional(),
 
   /**
    * 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[]>
+  hubInputs: z.record(z.string(), z.array(hubInputSchema)).optional(),
 
   /**
    * The inputs injected to the instance from the hubs.
@@ -70,36 +59,101 @@ export type InstanceModel = {
    *
    * Only for designer-first instances.
    */
-  injectionInputs?: HubInput[]
+  injectionInputs: z.array(hubInputSchema).optional(),
 
   /**
    * The position of the instance on the canvas.
    *
    * Only for designer-first instances.
    */
-  position?: Position
+  position: positionSchema.optional(),
+})
+
+export const instanceModelSchema = z.object({
+  /**
+   * The id of the instance unique within the project.
+   *
+   * The format is `${instanceType}:${instanceName}`.
+   */
+  id: instanceIdSchema,
+
+  /**
+   * The type of the instance.
+   */
+  type: genericNameSchema,
+
+  /**
+   * The name of the instance.
+   *
+   * Must be unique within instances of the same type in the project.
+   */
+  name: genericNameSchema,
+
+  ...instanceModelPatchSchema.shape,
 
   /**
    * The id of the top level parent instance.
    *
    * Only for child instances of the composite instances.
    */
-  parentId?: string
+  resolvedInputs: z.record(z.string(), z.array(instanceInputSchema)).optional(),
+
+  /**
+   * The position of the instance on the canvas.
+   *
+   * Only for designer-first instances.
+   */
+  parentId: z.string().optional(),
 
   /**
-   * The direct instance inputs and same-level children outputs returned by the instance as outputs.
+   * The direct instance outputs returned by the instance as outputs.
    *
    * Only for computed composite instances.
    */
-  outputs?: Record<string, InstanceInput[]>
+  outputs: z.record(z.string(), z.array(instanceInputSchema)).optional(),
 
   /**
    * The resolved unit outputs for the instance.
    *
    * Only for computed composite instances.
    */
-  resolvedOutputs?: Record<string, InstanceInput[]>
-}
+  resolvedOutputs: z.record(z.string(), z.array(instanceInputSchema)).optional(),
+})
+
+export type InstanceModel = z.infer<typeof instanceModelSchema>
+
+export const hubModelPatchSchema = z.object({
+  /**
+   * The position of the hub on the canvas.
+   */
+  position: positionSchema.optional(),
+
+  /**
+   * The inputs of the hub.
+   */
+  inputs: z.array(instanceInputSchema).optional(),
+
+  /**
+   * The inputs injected to the hub from the hubs.
+   *
+   * While `inputs` allows to pass hubs to distinct inputs,
+   * `injectionInputs` allows to pass hubs to the hub as a whole filling all inputs with matching types.
+   */
+  injectionInputs: z.array(hubInputSchema).optional(),
+})
+
+export const hubModelSchema = z.object({
+  /**
+   * The id of the hub unique within the project.
+   */
+  id: z.nanoid(),
+
+  ...hubModelPatchSchema.shape,
+})
+
+export type InstanceModelPatch = z.infer<typeof instanceModelPatchSchema>
+export type HubModel = z.infer<typeof hubModelSchema>
+export type HubModelPatch = z.infer<typeof hubModelPatchSchema>
 
 /**
  * Formats the instance id from the instance type and instance name.
@@ -109,7 +163,7 @@ export type InstanceModel = {
  *
  * @returns The formatted instance id.
  */
-export function getInstanceId(instanceType: string, instanceName: string): string {
+export function getInstanceId(instanceType: string, instanceName: string): InstanceId {
   return `${instanceType}:${instanceName}`
 }
 
@@ -124,7 +178,7 @@ export function parseInstanceId(instanceId: string): [instanceType: string, inst
   const parts = instanceId.split(":")
 
   if (parts.length !== 2) {
-    throw new Error(`Invalid instance key: ${instanceId}`)
+    throw new Error(`Invalid instance ID: ${instanceId}`)
   }
 
   return parts as [string, string]
@@ -177,3 +231,70 @@ export function findRequiredInputs<T extends string>(
 ): InstanceInput<T>[] {
   return names.map(name => findRequiredInput(inputs, name))
 }
+
+/**
+ * The field names that indicate special objects which Highstate understands regardless of the context.
+ *
+ * UUIDs are used to prevent conflicts with user-defined fields.
+ */
+export enum HighstateSignature {
+  Artifact = "d55c63ac-3174-4756-808f-f778e99af0d1",
+  Secret = "56ebf97b-57de-4985-8c86-bc1bc5871e6e",
+  Yaml = "c857cac5-caa6-4421-b82c-e561fbce6367",
+}
+
+export const yamlValueSchema = z.object({
+  [HighstateSignature.Yaml]: z.literal(true),
+  value: z.string(),
+})
+
+export type YamlValue = z.infer<typeof yamlValueSchema>
+
+export const fileMetaSchema = z.object({
+  name: z.string(),
+  contentType: z.string().optional(),
+  size: z.number().optional(),
+  mode: z.number().optional(),
+  isBinary: z.boolean().optional(),
+})
+
+export const unitObjectMetaSchema = z.object({
+  displayName: z.string().optional(),
+  description: z.string().optional(),
+  primaryIcon: z.string().optional(),
+})
+
+export const unitSecretSchema = z.object({
+  [HighstateSignature.Secret]: z.literal(true),
+  id: z.uuidv7(),
+  value: z.unknown(),
+})
+
+export const unitArtifactSchema = z.object({
+  [HighstateSignature.Artifact]: z.literal(true),
+  hash: z.string(),
+  meta: unitObjectMetaSchema.optional(),
+})
+
+export const fileContentSchema = z.union([
+  z.object({
+    type: z.literal("embedded"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("artifact"),
+    ...unitArtifactSchema.shape,
+  }),
+])
+
+export const fileSchema = z.object({
+  meta: fileMetaSchema,
+  content: fileContentSchema,
+})
+
+export type FileMeta = z.infer<typeof fileMetaSchema>
+export type FileContent = z.infer<typeof fileContentSchema>
+export type UnitObjectMeta = z.infer<typeof unitObjectMetaSchema>
+export type UnitArtifact = z.infer<typeof unitArtifactSchema>
+export type File = z.infer<typeof fileSchema>
+export type UnitSecretModel = z.infer<typeof unitSecretSchema>

package/src/meta.ts

@@ -0,0 +1,120 @@
+import { z } from "zod"
+
+export const userObjectMetaSchema = z.object({
+  /**
+   * Human-readable name of the object.
+   *
+   * Used in UI components for better user experience.
+   */
+  title: z.string().optional(),
+
+  /**
+   * The title used globally for the object.
+   *
+   * For example, the title of an instance secret is "Password" which is okay
+   * to display in the instance secret list, but when the secret is displayed in a
+   * global secret list the name should be more descriptive, like "Proxmox Password".
+   */
+  globalTitle: z.string().optional(),
+
+  /**
+   * Description of the object.
+   *
+   * Provides additional context for users and developers.
+   */
+  description: z.string().optional(),
+
+  /**
+   * The color of the object.
+   *
+   * Used in UI components to visually distinguish objects.
+   */
+  color: z.string().optional(),
+
+  /**
+   * Primary icon identifier.
+   *
+   * Should reference a iconify icon name, like "mdi:server" or "gg:remote".
+   */
+  icon: z.string().optional(),
+
+  /**
+   * The color of the primary icon.
+   */
+  iconColor: z.string().optional(),
+
+  /**
+   * The secondary icon identifier.
+   *
+   * Used to provide additional context or actions related to the object.
+   *
+   * Should reference a iconify icon name, like "mdi:edit" or "mdi:delete".
+   */
+  secondaryIcon: z.string().optional(),
+
+  /**
+   * The color of the secondary icon.
+   */
+  secondaryIconColor: z.string().optional(),
+})
+
+export const objectMetaSchema = userObjectMetaSchema.extend({
+  /**
+   * Creation timestamp in milliseconds.
+   *
+   * Managed automatically by the system.
+   */
+  createdAt: z.number().optional(),
+
+  /**
+   * Last update timestamp in milliseconds.
+   *
+   * Managed automatically by the system.
+   */
+  updatedAt: z.number().optional(),
+
+  /**
+   * The optional version of the document to support optimistic concurrency control.
+   *
+   * Managed automatically by the system.
+   */
+  version: z.number().optional(),
+})
+
+export type UserObjectMeta = z.infer<typeof userObjectMetaSchema>
+export type ObjectMeta = z.infer<typeof objectMetaSchema>
+
+/**
+ * The schema for strings that represent names in Highstate.
+ *
+ * The name:
+ * - must be alphanumeric;
+ * - can include dashes (`-`) as word separators and dots (`.`) as namespace separators;
+ * - must begin with a letter;
+ * - must be lowercase;
+ * - must include from 2 to 64 characters.
+ */
+export const genericNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9-_.]+$/)
+  .min(2)
+  .max(64)
+
+export type GenericName = z.infer<typeof genericNameSchema>
+
+/**
+ * The schema for field names in Highstate.
+ *
+ * The field name:
+ * - must be alphanumeric;
+ * - must be in camelCase;
+ * - must begin with a letter;
+ * - must include from 2 to 64 characters.
+ */
+export const fieldNameSchema = z
+  .string()
+  .regex(/^[a-z][a-zA-Z0-9]+$/)
+  .min(2)
+  .max(64)
+
+export type FieldName = z.infer<typeof fieldNameSchema>