@highstate/contract 0.16.0 → 0.18.0

package/src/component.ts

@@ -1,7 +1,7 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: maybe fix later */
 
 import type { Simplify } from "type-fest"
-import type { Entity } from "./entity"
+import type { Entity, implementedTypes } from "./entity"
 import type { OptionalEmptyRecords, OptionalUndefinedFields, PartialKeys } from "./utils"
 import { isNonNullish, mapValues, pickBy, uniqueBy } from "remeda"
 import { z } from "zod"
@@ -108,15 +108,15 @@ export type FullComponentInputOptions = {
 export type ComponentInputOptions = Entity | FullComponentInputOptions
 
 type ComponentInputOptionsToOutputRef<T extends ComponentInputOptions> = T extends Entity
-  ? InstanceInput<T["type"]>
+  ? InstanceInput<T[typeof implementedTypes]>
   : T extends FullComponentInputOptions
     ? T["required"] extends false
       ? T["multiple"] extends true
-        ? InstanceInput<T["entity"]["type"]>[] | undefined
-        : InstanceInput<T["entity"]["type"]> | undefined
+        ? InstanceInput<T["entity"][typeof implementedTypes]>[] | undefined
+        : InstanceInput<T["entity"][typeof implementedTypes]> | undefined
       : T["multiple"] extends true
-        ? InstanceInput<T["entity"]["type"]>[]
-        : InstanceInput<T["entity"]["type"]>
+        ? InstanceInput<T["entity"][typeof implementedTypes]>[]
+        : InstanceInput<T["entity"][typeof implementedTypes]>
     : never
 
 /**
@@ -171,6 +171,7 @@ export type InputComponentParams<
 }>
 
 export type ComponentOptions<
+  TType extends VersionedName,
   TArgs extends Record<string, ComponentArgumentOptions>,
   TInputs extends Record<string, ComponentInputOptions>,
   TOutputs extends Record<string, ComponentInputOptions>,
@@ -181,7 +182,7 @@ export type ComponentOptions<
    *
    * Examples: `proxmox.virtual-machine.v1`, `common.server.v1`.
    */
-  type: VersionedName
+  type: TType
 
   /**
    * The extra metadata of the component.
@@ -289,15 +290,15 @@ export type ComponentModel = z.infer<typeof componentModelSchema>
 
 type InputSpecToInputRef<T extends ComponentInputSpec> = T[1] extends true
   ? T[2] extends true
-    ? InstanceInput<T[0]["type"]>[]
-    : InstanceInput<T[0]["type"]>
+    ? InstanceInput<T[0][typeof implementedTypes]>[]
+    : InstanceInput<T[0][typeof implementedTypes]>
   : T[2] extends true
-    ? InstanceInput<T[0]["type"]>[] | undefined
-    : InstanceInput<T[0]["type"]> | undefined
+    ? InstanceInput<T[0][typeof implementedTypes]>[] | undefined
+    : InstanceInput<T[0][typeof implementedTypes]> | undefined
 
 type InputSpecToOutputRef<T extends ComponentInputSpec> = T[2] extends true
-  ? InstanceInput<T[0]["type"]>[]
-  : InstanceInput<T[0]["type"]>
+  ? InstanceInput<T[0][typeof implementedTypes]>[]
+  : InstanceInput<T[0][typeof implementedTypes]>
 
 export type InputSpecMapToInputRefMap<TInputs extends Record<string, ComponentInputSpec>> =
   TInputs extends Record<string, [string, never, never]>
@@ -313,10 +314,16 @@ export const originalCreate = Symbol("originalCreate")
 export const kind = Symbol("kind")
 
 export type Component<
+  TType extends VersionedName = VersionedName,
   TArgs extends Record<string, z.ZodType> = Record<string, never>,
   TInputs extends Record<string, ComponentInputSpec> = Record<string, never>,
   TOutputs extends Record<string, ComponentInputSpec> = Record<string, never>,
 > = {
+  /**
+   * The type of the component.
+   */
+  type: TType
+
   /**
    * The non-generic model of the component.
    */
@@ -343,12 +350,14 @@ export type Component<
 }
 
 export function defineComponent<
+  TType extends VersionedName = VersionedName,
   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>,
+  options: ComponentOptions<TType, TArgs, TInputs, TOutputs>,
 ): Component<
+  TType,
   { [K in keyof TArgs]: ComponentArgumentOptionsToSchema<TArgs[K]> },
   { [K in keyof TInputs]: ComponentInputOptionsToSpec<TInputs[K]> },
   { [K in keyof TOutputs]: ComponentInputOptionsToSpec<TOutputs[K]> }
@@ -536,7 +545,11 @@ function isSchemaOptional(schema: z.ZodType): boolean {
 export function mapArgument(value: ComponentArgumentOptions, key: string): ComponentArgument {
   if ("schema" in value) {
     return {
-      schema: z.toJSONSchema(value.schema, { target: "draft-7", io: "input" }),
+      schema: z.toJSONSchema(value.schema, {
+        target: "draft-7",
+        io: "input",
+        unrepresentable: "any",
+      }),
       [runtimeSchema]: value.schema,
       required: !isSchemaOptional(value.schema),
       meta: {
@@ -547,7 +560,7 @@ export function mapArgument(value: ComponentArgumentOptions, key: string): Compo
   }
 
   return {
-    schema: z.toJSONSchema(value, { target: "draft-7", io: "input" }),
+    schema: z.toJSONSchema(value, { target: "draft-7", io: "input", unrepresentable: "any" }),
     [runtimeSchema]: value,
     required: !isSchemaOptional(value),
     meta: {

package/src/entity.ts

@@ -1,3 +1,4 @@
+import type { IsEmptyObject, Simplify } from "type-fest"
 import type { PartialKeys } from "./utils"
 import { z } from "zod"
 import { camelCaseToHumanReadable } from "./i18n"
@@ -8,6 +9,29 @@ import {
   versionedNameSchema,
 } from "./meta"
 
+export const entityInclusionSchema = z.object({
+  /**
+   * The static type of the included entity.
+   */
+  type: versionedNameSchema,
+
+  /**
+   * Whether the included entity is required.
+   * If false, the entity may be omitted.
+   */
+  required: z.boolean(),
+
+  /**
+   * Whether the included entity is multiple.
+   */
+  multiple: z.boolean(),
+
+  /**
+   * The name of the field where the included entity is embedded.
+   */
+  field: z.string(),
+})
+
 /**
  * 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.
@@ -19,6 +43,26 @@ export const entityModelSchema = z.object({
    */
   type: versionedNameSchema,
 
+  /**
+   * The list of all extended entity types (direct and indirect).
+   */
+  extensions: z.string().array().optional(),
+
+  /**
+   * The list of directly extended entity types.
+   */
+  directExtensions: z.string().array().optional(),
+
+  /**
+   * The list of all included entities (directly or inherited from extensions).
+   */
+  inclusions: entityInclusionSchema.array().optional(),
+
+  /**
+   * The list of directly included entities.
+   */
+  directInclusions: entityInclusionSchema.array().optional(),
+
   /**
    * The JSON schema of the entity value.
    */
@@ -41,17 +85,29 @@ export const entityModelSchema = z.object({
   definitionHash: z.number(),
 })
 
+export type EntityInclusion = z.infer<typeof entityInclusionSchema>
 export type EntityModel = z.infer<typeof entityModelSchema>
+export type EntityTypes = Record<VersionedName, true>
+
+export declare const implementedTypes: unique symbol
 
 export type Entity<
   TType extends VersionedName = VersionedName,
-  TSchema extends z.ZodType = z.ZodType,
+  TImplementedTypes extends EntityTypes = EntityTypes,
+  TSchema extends z.ZodTypeAny = z.ZodTypeAny,
 > = {
   /**
    * The static type of the entity.
    */
   type: TType
 
+  /**
+   * The all types implemented by this entity including its own type.
+   *
+   * Does not exist at runtime.
+   */
+  [implementedTypes]: TImplementedTypes
+
   /**
    * The zod schema of the entity value.
    */
@@ -63,7 +119,12 @@ export type Entity<
   model: EntityModel
 }
 
-type EntityOptions<TType extends VersionedName, TSchema extends z.ZodType> = {
+type EntityOptions<
+  TType extends VersionedName,
+  TSchema extends z.ZodType,
+  TExtends extends Record<string, Entity>,
+  TIncludes extends Record<string, EntityIncludeRef>,
+> = {
   /**
    * The static type of the entity.
    */
@@ -78,11 +139,122 @@ type EntityOptions<TType extends VersionedName, TSchema extends z.ZodType> = {
    * The extra metadata of the entity.
    */
   meta?: PartialKeys<z.infer<typeof objectMetaSchema>, "title">
+
+  /**
+   * The list of entities to extend.
+   *
+   * The intersection of them will be used as the base schema and then intersected again with the provided schema.
+   *
+   * Note: Intersection does not mean inheritance or blind property merging.
+   * If two base types have field with the same name but different types,
+   * the resulting type of the field will be the intersection of the two types (and most likely `never`).
+   */
+  extends?: TExtends
+
+  /**
+   * The list of entities to include.
+   *
+   * Inclusion is more powerful mechanism that allows to embed other entities into this entity
+   * and then substitute them instead of this entity when connected to component inputs of included types.
+   */
+  includes?: TIncludes
+}
+
+export type EntityIncludeRef = Entity | { entity: Entity; multiple?: boolean; required?: boolean }
+
+function isEntityIncludeRef(
+  value: EntityIncludeRef,
+): value is { entity: Entity; multiple?: boolean; required?: boolean } {
+  return typeof value === "object" && value !== null && "entity" in value
+}
+
+type InclusionShape<TImplements extends Record<string, EntityIncludeRef>> = {
+  [K in keyof TImplements]: TImplements[K] extends {
+    entity: infer E
+    multiple?: infer M
+    required?: infer R
+  }
+    ? E extends Entity
+      ? M extends true
+        ? R extends false
+          ? z.ZodOptional<z.ZodArray<E["schema"]>>
+          : z.ZodArray<E["schema"]>
+        : R extends false
+          ? z.ZodOptional<E["schema"]>
+          : E["schema"]
+      : never
+    : TImplements[K] extends Entity
+      ? TImplements[K]["schema"]
+      : never
 }
 
-export function defineEntity<TType extends VersionedName, TSchema extends z.ZodType>(
-  options: EntityOptions<TType, TSchema>,
-): Entity<TType, TSchema> {
+type AddSchemaExtensions<
+  TSchema extends z.ZodTypeAny,
+  TExtends extends Record<string, Entity>,
+> = TExtends extends Record<string, never>
+  ? TSchema
+  : IsEmptyObject<TExtends> extends true
+    ? TSchema
+    : {
+        [K in keyof TExtends]: AddSchemaExtensions<
+          z.ZodIntersection<TSchema, TExtends[K]["schema"]>,
+          Omit<TExtends, K>
+        >
+      }[keyof TExtends]
+
+type AddTypeExtensions<
+  TImplementedTypes extends EntityTypes,
+  TExtends extends Record<string, Entity>,
+> = TExtends extends Record<string, never>
+  ? TImplementedTypes
+  : IsEmptyObject<TExtends> extends true
+    ? TImplementedTypes
+    : {
+        [K in keyof TExtends]: AddTypeExtensions<
+          TImplementedTypes & TExtends[K][typeof implementedTypes],
+          Omit<TExtends, K>
+        >
+      }[keyof TExtends]
+
+type AddSchemaInclusions<
+  TSchema extends z.ZodTypeAny,
+  TImplements extends Record<string, EntityIncludeRef>,
+> = TImplements extends Record<string, never>
+  ? TSchema
+  : z.ZodIntersection<TSchema, z.ZodObject<InclusionShape<TImplements>>>
+
+type AddTypeInclusions<
+  TImplementedTypes extends EntityTypes,
+  TImplements extends Record<string, EntityIncludeRef>,
+> = TImplements extends Record<string, never>
+  ? TImplementedTypes
+  : {
+      [K in keyof TImplements]: TImplements[K] extends {
+        entity: infer E
+      }
+        ? E extends Entity
+          ? AddTypeInclusions<TImplementedTypes & E[typeof implementedTypes], Omit<TImplements, K>>
+          : TImplementedTypes
+        : TImplements[K] extends Entity
+          ? AddTypeInclusions<
+              TImplementedTypes & TImplements[K][typeof implementedTypes],
+              Omit<TImplements, K>
+            >
+          : TImplementedTypes
+    }[keyof TImplements]
+
+export function defineEntity<
+  TType extends VersionedName,
+  TSchema extends z.ZodType,
+  TExtends extends Record<string, Entity> = Record<string, never>,
+  TImplements extends Record<string, EntityIncludeRef> = Record<string, never>,
+>(
+  options: EntityOptions<TType, TSchema, TExtends, TImplements>,
+): Entity<
+  TType,
+  Simplify<AddTypeInclusions<AddTypeExtensions<{ [K in TType]: true }, TExtends>, TImplements>>,
+  AddSchemaExtensions<AddSchemaInclusions<TSchema, TImplements>, TExtends>
+> {
   try {
     entityModelSchema.shape.type.parse(options.type)
   } catch (error) {
@@ -93,13 +265,94 @@ export function defineEntity<TType extends VersionedName, TSchema extends z.ZodT
     throw new Error("Entity schema is required")
   }
 
+  const includedEntities = Object.entries(options.includes ?? {}).map(([field, entityRef]) => {
+    if (isEntityIncludeRef(entityRef)) {
+      return {
+        entity: entityRef.entity,
+        inclusion: {
+          type: entityRef.entity.type,
+          required: entityRef.required ?? true,
+          multiple: entityRef.multiple ?? false,
+          field,
+        },
+      }
+    }
+
+    return {
+      entity: entityRef,
+      inclusion: {
+        type: entityRef.type,
+        required: true,
+        multiple: false,
+        field,
+      },
+    }
+  })
+
+  const inclusionShape = includedEntities.reduce(
+    (shape, { entity, inclusion }) => {
+      if (inclusion.multiple) {
+        shape[inclusion.field] = inclusion.required
+          ? entity.schema.array()
+          : entity.schema.array().optional()
+      } else {
+        shape[inclusion.field] = inclusion.required ? entity.schema : entity.schema.optional()
+      }
+
+      return shape
+    },
+    {} as Record<string, z.ZodTypeAny>,
+  )
+
+  let finalSchema = Object.values(options.extends ?? {}).reduce(
+    (schema, entity) => z.intersection(schema, entity.schema),
+    options.schema as z.ZodType,
+  )
+
+  if (includedEntities.length > 0) {
+    finalSchema = z.intersection(finalSchema, z.object(inclusionShape))
+  }
+
+  const directInclusions = includedEntities.map(({ inclusion }) => inclusion)
+  const directExtensions = Object.values(options.extends ?? {}).map(entity => entity.type)
+
+  const inclusions = Object.values(options.extends ?? {}).reduce(
+    (incs, entity) => {
+      if (entity.model.inclusions) {
+        incs.push(...entity.model.inclusions)
+      }
+
+      return incs
+    },
+    [...directInclusions],
+  )
+
+  const extensions = Object.values(options.extends ?? {}).reduce((exts, entity) => {
+    exts.push(...(entity.model.extensions ?? []), entity.type)
+
+    return exts
+  }, [] as string[])
+
   try {
+    let _schema: z.core.JSONSchema.BaseSchema
+
     return {
       type: options.type,
-      schema: options.schema,
+      schema: finalSchema,
       model: {
         type: options.type,
-        schema: z.toJSONSchema(options.schema, { target: "draft-7" }),
+        extensions: extensions.length > 0 ? extensions : undefined,
+        directExtensions: directExtensions.length > 0 ? directExtensions : undefined,
+        inclusions: inclusions.length > 0 ? inclusions : undefined,
+        directInclusions: directInclusions.length > 0 ? directInclusions : undefined,
+        get schema() {
+          if (!_schema) {
+            // TODO: forbid unrepresentable types (and find way to filter out "undefined" literals)
+            _schema = z.toJSONSchema(finalSchema, { target: "draft-7", unrepresentable: "any" })
+          }
+
+          return _schema
+        },
         meta: {
           ...options.meta,
           title:
@@ -108,7 +361,8 @@ export function defineEntity<TType extends VersionedName, TSchema extends z.ZodT
         // will be calculated by the library loader
         definitionHash: null!,
       },
-    }
+      // biome-ignore lint/suspicious/noExplicitAny: we already typed return type
+    } as any
   } catch (error) {
     throw new Error(`Failed to define entity "${options.type}"`, { cause: error })
   }
@@ -117,3 +371,27 @@ export function defineEntity<TType extends VersionedName, TSchema extends z.ZodT
 export function isEntity(value: unknown): value is Entity {
   return typeof value === "object" && value !== null && "model" in value
 }
+
+/**
+ * Checks whether the given entity can be assigned to the target type.
+ *
+ * An entity is considered assignable to a target type if:
+ * - The entity's type is exactly the same as the target type.
+ * - The entity extends the target type (either directly or indirectly).
+ * - The entity includes the target type (either directly or indirectly).
+ *
+ * @param entity The entity to check.
+ * @param target The target versioned name to check against.
+ * @returns True if the entity is assignable to the target type, false otherwise.
+ */
+export function isAssignableTo(entity: EntityModel, target: VersionedName): boolean {
+  if (entity.type === target) {
+    return true
+  }
+
+  if (entity.extensions?.includes(target)) {
+    return true
+  }
+
+  return entity.inclusions?.some(implementation => implementation.type === target) ?? false
+}

package/src/index.ts

@@ -1,6 +1,14 @@
 /** biome-ignore-all assist/source/organizeImports: will break groups */
 
-export * from "./entity"
+export {
+  type Entity,
+  type EntityModel,
+  isEntity,
+  isAssignableTo,
+  defineEntity,
+  entityModelSchema,
+} from "./entity"
+
 export * from "./instance"
 export * from "./unit"
 export * from "./i18n"
@@ -9,6 +17,7 @@ export * from "./terminal"
 export * from "./page"
 export * from "./trigger"
 export * from "./worker"
+export * from "./compaction"
 
 export {
   // common utilities

package/src/instance.ts

@@ -1,3 +1,4 @@
+import type { EntityTypes } from "./entity"
 import type { boundaryInput, boundaryInputs } from "./evaluation"
 import { z } from "zod"
 import { componentKindSchema } from "./component"
@@ -11,20 +12,21 @@ import {
 
 declare const type: unique symbol
 
-export type InstanceInput<TType extends string = string> = {
-  [type]?: TType
+export type InstanceInput<TTypes extends EntityTypes = EntityTypes> = {
+  [type]?: TTypes
   [boundaryInput]?: InstanceInput
   instanceId: InstanceId
   output: string
 }
 
-export type OptionalInstanceInput<TType extends string = string> =
-  | ({ provided: true } & InstanceInput<TType>)
+export type OptionalInstanceInput<TTypes extends EntityTypes = EntityTypes> =
+  | ({ provided: true } & InstanceInput<TTypes>)
   | { provided: false; [boundaryInput]?: InstanceInput }
 
-export type InstanceInputGroup<TType extends string = string> = InstanceInput<TType>[] & {
-  [boundaryInputs]?: InstanceInputGroup<TType>
-}
+export type InstanceInputGroup<TTypes extends EntityTypes = EntityTypes> =
+  InstanceInput<TTypes>[] & {
+    [boundaryInputs]?: InstanceInputGroup<TTypes>
+  }
 
 export function inputKey(input: InstanceInput): string {
   return `${input.instanceId}:${input.output}`
@@ -200,7 +202,7 @@ export function parseInstanceId(
   return parts as [VersionedName, GenericName]
 }
 
-export function findInput<T extends string>(
+export function findInput<T extends EntityTypes>(
   inputs: InstanceInput<T>[],
   name: string,
 ): InstanceInput<T> | null {
@@ -221,7 +223,7 @@ export function findInput<T extends string>(
   return matchedInputs[0]
 }
 
-export function findRequiredInput<T extends string>(
+export function findRequiredInput<T extends EntityTypes>(
   inputs: InstanceInput<T>[],
   name: string,
 ): InstanceInput<T> {
@@ -234,14 +236,14 @@ export function findRequiredInput<T extends string>(
   return input
 }
 
-export function findInputs<T extends string>(
+export function findInputs<T extends EntityTypes>(
   inputs: InstanceInput<T>[],
   names: string[],
 ): InstanceInput<T>[] {
   return names.map(name => findInput(inputs, name)).filter(Boolean) as InstanceInput<T>[]
 }
 
-export function findRequiredInputs<T extends string>(
+export function findRequiredInputs<T extends EntityTypes>(
   inputs: InstanceInput<T>[],
   names: string[],
 ): InstanceInput<T>[] {
@@ -256,6 +258,8 @@ export function findRequiredInputs<T extends string>(
 export enum HighstateSignature {
   Artifact = "d55c63ac-3174-4756-808f-f778e99af0d1",
   Yaml = "c857cac5-caa6-4421-b82c-e561fbce6367",
+  Id = "348d020e-0d9e-4ae7-9415-b91af99f5339",
+  Ref = "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8",
 }
 
 export const yamlValueSchema = z.object({
@@ -263,6 +267,17 @@ export const yamlValueSchema = z.object({
   value: z.string(),
 })
 
+export const objectWithIdSchema = z.object({
+  [HighstateSignature.Id]: z.literal(true),
+  id: z.number(),
+  value: z.unknown(),
+})
+
+export const objectRefSchema = z.object({
+  [HighstateSignature.Ref]: z.literal(true),
+  id: z.number(),
+})
+
 export type YamlValue = z.infer<typeof yamlValueSchema>
 
 export const fileMetaSchema = z.object({

package/src/meta.ts

@@ -125,7 +125,10 @@ export const timestampsSchema = z.object({
  */
 export const genericNameSchema = z
   .string()
-  .regex(/^[a-z][a-z0-9-_.]+$/)
+  .regex(
+    /^[a-z][a-z0-9-.]+$/,
+    "Name must start with a letter and can only contain lowercase letters, numbers, dashes (-) and dots (.)",
+  )
   .min(2)
   .max(64)
 
@@ -190,7 +193,7 @@ export function parseVersionedName(name: string): [name: string, version: number
  */
 export const fieldNameSchema = z
   .string()
-  .regex(/^[a-z][a-zA-Z0-9]+$/)
+  .regex(/^[a-z][a-zA-Z0-9]+$/, "Field name must start with a letter and be in camelCase format")
   .min(2)
   .max(64)
 

package/src/pulumi.ts

@@ -1,5 +1,6 @@
 import { parse } from "yaml"
 import { z } from "zod"
+import { entityInclusionSchema } from "./entity"
 import {
   fileMetaSchema,
   HighstateSignature,
@@ -10,6 +11,17 @@ import {
 import { commonObjectMetaSchema } from "./meta"
 import { triggerInvocationSchema } from "./trigger"
 
+export type UnitInputReference = z.infer<typeof unitInputReference>
+
+export const unitInputReference = z.object({
+  ...instanceInputSchema.shape,
+
+  /**
+   * The resolved inclusion needed to extract the input value.
+   */
+  inclusion: entityInclusionSchema.optional(),
+})
+
 export const unitConfigSchema = z.object({
   /**
    * The ID of the instance.
@@ -24,7 +36,7 @@ export const unitConfigSchema = z.object({
   /**
    * The record of input references for the unit.
    */
-  inputs: z.record(z.string(), instanceInputSchema.array()),
+  inputs: z.record(z.string(), unitInputReference.array()),
 
   /**
    * The list of triggers that have been invoked for this unit.