@highstate/contract 0.16.0 → 0.17.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import z5, { z } from 'zod';
+import { z } from 'zod';
 export { z } from 'zod';
 import { mapValues, pickBy, isNonNullish, uniqueBy } from 'remeda';
 import { parse } from 'yaml';
@@ -116,7 +116,10 @@ var timestampsSchema = z.object({
    */
   updatedAt: z.date()
 });
-var genericNameSchema = z.string().regex(/^[a-z][a-z0-9-_.]+$/).min(2).max(64);
+var genericNameSchema = z.string().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);
 var versionedNameSchema = z.union([
   z.templateLiteral([genericNameSchema, z.literal("."), z.literal("v"), z.number().int().min(1)]),
   // to prevent TypeScript matching "proxmox.virtual-machine.v2" as
@@ -154,14 +157,49 @@ function parseVersionedName(name) {
   }
   return [baseName, version];
 }
-var fieldNameSchema = z.string().regex(/^[a-z][a-zA-Z0-9]+$/).min(2).max(64);
+var fieldNameSchema = z.string().regex(/^[a-z][a-zA-Z0-9]+$/, "Field name must start with a letter and be in camelCase format").min(2).max(64);
 
 // src/entity.ts
+var 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()
+});
 var entityModelSchema = z.object({
   /**
    * The static type of the entity.
    */
   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.
    */
@@ -181,6 +219,9 @@ var entityModelSchema = z.object({
    */
   definitionHash: z.number()
 });
+function isEntityIncludeRef(value) {
+  return typeof value === "object" && value !== null && "entity" in value;
+}
 function defineEntity(options) {
   try {
     entityModelSchema.shape.type.parse(options.type);
@@ -190,13 +231,78 @@ function defineEntity(options) {
   if (!options.schema) {
     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;
+    },
+    {}
+  );
+  let finalSchema = Object.values(options.extends ?? {}).reduce(
+    (schema, entity) => z.intersection(schema, entity.schema),
+    options.schema
+  );
+  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;
+  }, []);
   try {
+    let _schema;
     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 : void 0,
+        directExtensions: directExtensions.length > 0 ? directExtensions : void 0,
+        inclusions: inclusions.length > 0 ? inclusions : void 0,
+        directInclusions: directInclusions.length > 0 ? directInclusions : void 0,
+        get schema() {
+          if (!_schema) {
+            _schema = z.toJSONSchema(finalSchema, { target: "draft-7", unrepresentable: "any" });
+          }
+          return _schema;
+        },
         meta: {
           ...options.meta,
           title: options.meta?.title || camelCaseToHumanReadable(parseVersionedName(options.type)[0])
@@ -204,6 +310,7 @@ function defineEntity(options) {
         // will be calculated by the library loader
         definitionHash: null
       }
+      // biome-ignore lint/suspicious/noExplicitAny: we already typed return type
     };
   } catch (error) {
     throw new Error(`Failed to define entity "${options.type}"`, { cause: error });
@@ -212,6 +319,15 @@ function defineEntity(options) {
 function isEntity(value) {
   return typeof value === "object" && value !== null && "model" in value;
 }
+function isAssignableTo(entity, target) {
+  if (entity.type === target) {
+    return true;
+  }
+  if (entity.extensions?.includes(target)) {
+    return true;
+  }
+  return entity.inclusions?.some((implementation) => implementation.type === target) ?? false;
+}
 var boundaryInput = Symbol("boundaryInput");
 var boundaryInputs = Symbol("boundaryInputs");
 function formatInstancePath(instance) {
@@ -522,7 +638,11 @@ function isSchemaOptional(schema) {
 function mapArgument(value, key) {
   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: {
@@ -532,7 +652,7 @@ function mapArgument(value, key) {
     };
   }
   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: {
@@ -778,12 +898,23 @@ function findRequiredInputs(inputs, names) {
 var HighstateSignature = /* @__PURE__ */ ((HighstateSignature2) => {
   HighstateSignature2["Artifact"] = "d55c63ac-3174-4756-808f-f778e99af0d1";
   HighstateSignature2["Yaml"] = "c857cac5-caa6-4421-b82c-e561fbce6367";
+  HighstateSignature2["Id"] = "348d020e-0d9e-4ae7-9415-b91af99f5339";
+  HighstateSignature2["Ref"] = "6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8";
   return HighstateSignature2;
 })(HighstateSignature || {});
 var yamlValueSchema = z.object({
   ["c857cac5-caa6-4421-b82c-e561fbce6367" /* Yaml */]: z.literal(true),
   value: z.string()
 });
+var objectWithIdSchema = z.object({
+  ["348d020e-0d9e-4ae7-9415-b91af99f5339" /* Id */]: z.literal(true),
+  id: z.number(),
+  value: z.unknown()
+});
+var objectRefSchema = z.object({
+  ["6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8" /* Ref */]: z.literal(true),
+  id: z.number()
+});
 var fileMetaSchema = z.object({
   name: z.string(),
   contentType: z.string().optional(),
@@ -819,27 +950,27 @@ var componentSecretSchema = componentArgumentSchema.extend({
   /**
    * The secret cannot be modified by the user, but can be modified by the unit.
    */
-  readonly: z5.boolean(),
+  readonly: z.boolean(),
   /**
    * The secret value is computed by the unit and should not be passed to it when invoked.
    */
-  computed: z5.boolean()
+  computed: z.boolean()
 });
-var unitSourceSchema = z5.object({
+var unitSourceSchema = z.object({
   /**
    * The package where the unit implementation is located.
    *
    * May be both: local monorepo package or a remote NPM package.
    */
-  package: z5.string(),
+  package: z.string(),
   /**
    * The path to the unit implementation within the package.
    *
    * If not provided, the root of the package is assumed.
    */
-  path: z5.string().optional()
+  path: z.string().optional()
 });
-var unitModelSchema = z5.object({
+var unitModelSchema = z.object({
   ...componentModelSchema.shape,
   /**
    * The source of the unit.
@@ -848,7 +979,7 @@ var unitModelSchema = z5.object({
   /**
    * The record of the secret specs.
    */
-  secrets: z5.record(z5.string(), componentSecretSchema)
+  secrets: z.record(z.string(), componentSecretSchema)
 });
 function defineUnit(options) {
   if (!options.source) {
@@ -878,8 +1009,8 @@ function defineUnit(options) {
   }
   return component;
 }
-function $secrets(secrets2) {
-  return toFullComponentArgumentOptions(secrets2);
+function $secrets(secrets) {
+  return toFullComponentArgumentOptions(secrets);
 }
 function mapSecret(value, key) {
   if ("schema" in value) {
@@ -927,6 +1058,13 @@ var triggerInvocationSchema = z.object({
 });
 
 // src/pulumi.ts
+var unitInputReference = z.object({
+  ...instanceInputSchema.shape,
+  /**
+   * The resolved inclusion needed to extract the input value.
+   */
+  inclusion: entityInclusionSchema.optional()
+});
 var unitConfigSchema = z.object({
   /**
    * The ID of the instance.
@@ -939,7 +1077,7 @@ var 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.
    */
@@ -1098,6 +1236,301 @@ var workerRunOptionsSchema = z.object({
    */
   apiKey: z.string()
 });
+function compact(value) {
+  const counts = /* @__PURE__ */ new WeakMap();
+  const cyclic = /* @__PURE__ */ new WeakSet();
+  const expanded = /* @__PURE__ */ new WeakSet();
+  const inStack = /* @__PURE__ */ new WeakSet();
+  const stack = [];
+  function countIdentities(current) {
+    if (current === null || typeof current !== "object") {
+      return;
+    }
+    counts.set(current, (counts.get(current) ?? 0) + 1);
+    if (inStack.has(current)) {
+      cyclic.add(current);
+      for (const entry of stack) {
+        cyclic.add(entry);
+      }
+      return;
+    }
+    if (expanded.has(current)) {
+      return;
+    }
+    expanded.add(current);
+    inStack.add(current);
+    stack.push(current);
+    if (Array.isArray(current)) {
+      try {
+        for (const item of current) {
+          countIdentities(item);
+        }
+        return;
+      } finally {
+        stack.pop();
+        inStack.delete(current);
+      }
+    }
+    try {
+      for (const entryValue of Object.values(current)) {
+        countIdentities(entryValue);
+      }
+    } finally {
+      stack.pop();
+      inStack.delete(current);
+    }
+  }
+  countIdentities(value);
+  const ids = /* @__PURE__ */ new WeakMap();
+  const definitionSites = /* @__PURE__ */ new WeakMap();
+  let nextId = 1;
+  function ensureId(current) {
+    const existing = ids.get(current);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const allocated = nextId;
+    nextId += 1;
+    ids.set(current, allocated);
+    return allocated;
+  }
+  function assignDefinitionSitesBfs(root) {
+    if (root === null || typeof root !== "object") {
+      return;
+    }
+    const queue = [];
+    const expandedQueue = /* @__PURE__ */ new WeakSet();
+    if (Array.isArray(root)) {
+      for (let index = 0; index < root.length; index += 1) {
+        queue.push({ parent: root, key: index, value: root[index] });
+      }
+    } else {
+      for (const [key, entryValue] of Object.entries(root)) {
+        queue.push({ parent: root, key, value: entryValue });
+      }
+    }
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === void 0) {
+        continue;
+      }
+      if (current.value === null || typeof current.value !== "object") {
+        continue;
+      }
+      const occurrences = counts.get(current.value) ?? 0;
+      if (occurrences > 1 && definitionSites.get(current.value) === void 0) {
+        definitionSites.set(current.value, { parent: current.parent, key: current.key });
+        ensureId(current.value);
+      }
+      if (expandedQueue.has(current.value)) {
+        continue;
+      }
+      expandedQueue.add(current.value);
+      if (Array.isArray(current.value)) {
+        for (let index = 0; index < current.value.length; index += 1) {
+          queue.push({ parent: current.value, key: index, value: current.value[index] });
+        }
+        continue;
+      }
+      for (const [key, entryValue] of Object.entries(current.value)) {
+        queue.push({ parent: current.value, key, value: entryValue });
+      }
+    }
+  }
+  assignDefinitionSitesBfs(value);
+  const emitted = /* @__PURE__ */ new WeakSet();
+  function buildTreeChildren(current, rootOfIdValue) {
+    if (Array.isArray(current)) {
+      return current.map((item) => buildTree(item, rootOfIdValue));
+    }
+    return mapValues(current, (entryValue) => buildTree(entryValue, rootOfIdValue));
+  }
+  function buildTree(current, rootOfIdValue) {
+    if (current === null || typeof current !== "object") {
+      return current;
+    }
+    if (rootOfIdValue !== void 0 && emitted.has(current)) {
+      const id = ids.get(current);
+      if (id === void 0) {
+        throw new Error("Compaction invariant violation: missing id for repeated object");
+      }
+      return {
+        ["6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8" /* Ref */]: true,
+        id
+      };
+    }
+    if (rootOfIdValue !== void 0 && cyclic.has(current) && !emitted.has(current)) {
+      const id = ensureId(current);
+      emitted.add(current);
+      return {
+        ["348d020e-0d9e-4ae7-9415-b91af99f5339" /* Id */]: true,
+        id,
+        value: buildTreeChildren(current, current)
+      };
+    }
+    return buildTreeChildren(current, rootOfIdValue);
+  }
+  function buildAt(parent, key, current) {
+    if (current === null || typeof current !== "object") {
+      return current;
+    }
+    const occurrences = counts.get(current) ?? 0;
+    if (occurrences <= 1) {
+      if (Array.isArray(current)) {
+        return current.map((item, index) => buildAt(current, index, item));
+      }
+      return mapValues(current, (entryValue, entryKey) => buildAt(current, entryKey, entryValue));
+    }
+    const site = definitionSites.get(current);
+    const shouldDefineHere = site?.parent === parent && site.key === key;
+    const id = ids.get(current);
+    if (id === void 0) {
+      throw new Error("Compaction invariant violation: missing id for repeated object");
+    }
+    if (!shouldDefineHere || emitted.has(current)) {
+      return {
+        ["6d7f9da0-9cb6-496d-b72e-cf85ee4d9cf8" /* Ref */]: true,
+        id
+      };
+    }
+    emitted.add(current);
+    return {
+      ["348d020e-0d9e-4ae7-9415-b91af99f5339" /* Id */]: true,
+      id,
+      value: buildTreeChildren(current, current)
+    };
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  const topLevelOccurrences = counts.get(value) ?? 0;
+  if (topLevelOccurrences > 1) {
+    const id = ensureId(value);
+    emitted.add(value);
+    return {
+      ["348d020e-0d9e-4ae7-9415-b91af99f5339" /* Id */]: true,
+      id,
+      value: buildTreeChildren(value, value)
+    };
+  }
+  if (Array.isArray(value)) {
+    return value.map((item, index) => buildAt(value, index, item));
+  }
+  return mapValues(
+    value,
+    (entryValue, entryKey) => buildAt(value, entryKey, entryValue)
+  );
+}
+function decompact(value) {
+  const rawValuesById = /* @__PURE__ */ new Map();
+  const placeholdersById = /* @__PURE__ */ new Map();
+  function collect(current, visited) {
+    const result = objectWithIdSchema.safeParse(current);
+    if (result.success) {
+      const { id } = result.data;
+      if (rawValuesById.has(id)) {
+        throw new Error(`Duplicate compacted id ${id}`);
+      }
+      rawValuesById.set(id, result.data.value);
+      collect(result.data.value, visited);
+      return;
+    }
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return;
+    }
+    if (visited.has(current)) {
+      return;
+    }
+    visited.add(current);
+    if (Array.isArray(current)) {
+      for (const item of current) {
+        collect(item, visited);
+      }
+      return;
+    }
+    for (const entryValue of Object.values(current)) {
+      collect(entryValue, visited);
+    }
+  }
+  function ensurePlaceholder(id) {
+    const existing = placeholdersById.get(id);
+    if (existing !== void 0) {
+      return existing;
+    }
+    const raw = rawValuesById.get(id);
+    if (raw === void 0) {
+      throw new Error(`Unresolved compacted ref id ${id}`);
+    }
+    let placeholder;
+    if (raw !== null && typeof raw === "object") {
+      placeholder = Array.isArray(raw) ? [] : {};
+    } else {
+      placeholder = raw;
+    }
+    placeholdersById.set(id, placeholder);
+    return placeholder;
+  }
+  function resolve(current) {
+    const refResult = objectRefSchema.safeParse(current);
+    if (refResult.success) {
+      return ensurePlaceholder(refResult.data.id);
+    }
+    const withIdResult = objectWithIdSchema.safeParse(current);
+    if (withIdResult.success) {
+      return ensurePlaceholder(withIdResult.data.id);
+    }
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return current;
+    }
+    if (Array.isArray(current)) {
+      return current.map((item) => resolve(item));
+    }
+    return mapValues(current, (entryValue) => resolve(entryValue));
+  }
+  function fillPlaceholder(id, visitedIds2) {
+    if (visitedIds2.has(id)) {
+      return;
+    }
+    visitedIds2.add(id);
+    const raw = rawValuesById.get(id);
+    if (raw === void 0) {
+      throw new Error(`Unresolved compacted ref id ${id}`);
+    }
+    const placeholder = ensurePlaceholder(id);
+    if (placeholder === null || typeof placeholder !== "object") {
+      return;
+    }
+    if (raw === null || typeof raw !== "object") {
+      throw new Error(`Compaction invariant violation: id ${id} points to non-object value`);
+    }
+    const resolved = resolve(raw);
+    if (Array.isArray(placeholder)) {
+      if (!Array.isArray(resolved)) {
+        throw new Error(`Compaction invariant violation: id ${id} array placeholder mismatch`);
+      }
+      placeholder.length = 0;
+      for (const item of resolved) {
+        placeholder.push(item);
+      }
+      return;
+    }
+    if (Array.isArray(resolved) || resolved === null || typeof resolved !== "object") {
+      throw new Error(`Compaction invariant violation: id ${id} object placeholder mismatch`);
+    }
+    for (const [key, entryValue] of Object.entries(resolved)) {
+      placeholder[key] = entryValue;
+    }
+  }
+  collect(value, /* @__PURE__ */ new WeakSet());
+  for (const id of rawValuesById.keys()) {
+    ensurePlaceholder(id);
+  }
+  const visitedIds = /* @__PURE__ */ new Set();
+  for (const id of rawValuesById.keys()) {
+    fillPlaceholder(id, visitedIds);
+  }
+  return resolve(value);
+}
 function text(strings, ...values) {
   const stringValues = values.map(String);
   let result = "";
@@ -1140,6 +1573,6 @@ function stripNullish(obj) {
   return pickBy(obj, isNonNullish);
 }
 
-export { $addArgumentDescription, $addInputDescription, $args, $inputs, $outputs, $secrets, HighstateConfigKey, HighstateSignature, InstanceNameConflictError, WellKnownInstanceCustomStatus, bytesToHumanReadable, camelCaseToHumanReadable, check, clearKnownAbbreviations, commonObjectMetaSchema, componentArgumentSchema, componentInputSchema, componentModelSchema, componentSecretSchema, defineComponent, defineEntity, defineUnit, entityModelSchema, fieldNameSchema, fileContentSchema, fileMetaSchema, fileSchema, findInput, findInputs, findRequiredInput, findRequiredInputs, genericNameSchema, getInstanceId, getOrCreate, getRuntimeInstances, globalCommonObjectMetaSchema, hubInputSchema, hubModelPatchSchema, hubModelSchema, inputKey, instanceIdSchema, instanceInputSchema, instanceModelPatchSchema, instanceModelSchema, instanceStatusFieldSchema, instanceStatusFieldValueSchema, isComponent, isEntity, isUnitModel, objectMetaSchema, originalCreate, pageBlockSchema, parseArgumentValue, parseInstanceId, parseVersionedName, positionSchema, registerKnownAbbreviations, resetEvaluation, runtimeSchema, serviceAccountMetaSchema, setValidationEnabled, stripNullish, terminalSpecSchema, text, timestampsSchema, triggerInvocationSchema, triggerSpecSchema, trimIndentation, unitArtifactId, unitArtifactSchema, unitConfigSchema, unitModelSchema, unitPageSchema, unitSourceSchema, unitTerminalSchema, unitTriggerSchema, unitWorkerSchema, versionedNameSchema, workerRunOptionsSchema, yamlValueSchema };
+export { $addArgumentDescription, $addInputDescription, $args, $inputs, $outputs, $secrets, HighstateConfigKey, HighstateSignature, InstanceNameConflictError, WellKnownInstanceCustomStatus, bytesToHumanReadable, camelCaseToHumanReadable, check, clearKnownAbbreviations, commonObjectMetaSchema, compact, componentArgumentSchema, componentInputSchema, componentModelSchema, componentSecretSchema, decompact, defineComponent, defineEntity, defineUnit, entityModelSchema, fieldNameSchema, fileContentSchema, fileMetaSchema, fileSchema, findInput, findInputs, findRequiredInput, findRequiredInputs, genericNameSchema, getInstanceId, getOrCreate, getRuntimeInstances, globalCommonObjectMetaSchema, hubInputSchema, hubModelPatchSchema, hubModelSchema, inputKey, instanceIdSchema, instanceInputSchema, instanceModelPatchSchema, instanceModelSchema, instanceStatusFieldSchema, instanceStatusFieldValueSchema, isAssignableTo, isComponent, isEntity, isUnitModel, objectMetaSchema, objectRefSchema, objectWithIdSchema, originalCreate, pageBlockSchema, parseArgumentValue, parseInstanceId, parseVersionedName, positionSchema, registerKnownAbbreviations, resetEvaluation, runtimeSchema, serviceAccountMetaSchema, setValidationEnabled, stripNullish, terminalSpecSchema, text, timestampsSchema, triggerInvocationSchema, triggerSpecSchema, trimIndentation, unitArtifactId, unitArtifactSchema, unitConfigSchema, unitInputReference, unitModelSchema, unitPageSchema, unitSourceSchema, unitTerminalSchema, unitTriggerSchema, unitWorkerSchema, versionedNameSchema, workerRunOptionsSchema, yamlValueSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map