@highstate/contract 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+import { Static, TUnion, TString, TNumber, TBoolean, TArray, TLiteral, TSchema, TAnySchema, TObject, TOptional } from '@sinclair/typebox';
+
+type UnitRegistration = Readonly<{
+    type: string;
+    name: string;
+    config: Readonly<Record<string, string>>;
+    dependencies: readonly string[];
+}>;
+declare function getUnitRegistrations(): Readonly<Record<string, UnitRegistration>>;
+
+/**
+ * The schema for a single argument value.
+ *
+ * This argument can have a limited set of types: primitive types, arrays of strings or numbers.
+ * This limitation is due to the fact that we need to display the arguments in the UI, and we can't display more complex types.
+ * Moreover, it encourages using separate components for organizing complex data.
+ */
+declare const argumentValueSchema: TUnion<[TString, TNumber, TBoolean, TArray<TString>, TArray<TNumber>]>;
+type ArgumentValueSchema = typeof argumentValueSchema;
+type ArgumentValue = Static<ArgumentValueSchema>;
+type AllowedArgumentSchema = TString | TNumber | TBoolean | TArray<TString> | TArray<TNumber> | TUnion<TLiteral[]>;
+/**
+ * The generic metadata of some contract.
+ */
+type Meta = {
+    /**
+     * The display name of the entity which can be shown in the UI.
+     */
+    displayName?: string;
+    /**
+     * The description of the entity which can be shown in the UI.
+     */
+    description?: string;
+    /**
+     * The hex color of the entity which can be used in the UI.
+     *
+     * @example "#ff0000"
+     */
+    color?: string;
+};
+
+type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type ListRequiredKeys<T extends Record<string, unknown>> = T extends Record<string, never> ? never : {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+type PickOptionalRecords<T extends Record<string, Record<string, unknown>>> = {
+    [K in keyof T]: ListRequiredKeys<T[K]> extends never ? K : never;
+}[keyof T];
+type PickRequiredRecords<T extends Record<string, Record<string, unknown>>> = {
+    [K in keyof T]: ListRequiredKeys<T[K]> extends never ? never : K;
+}[keyof T];
+type OptionalEmptyRecords<T extends Record<string, Record<string, unknown>>> = {
+    [K in PickOptionalRecords<T>]?: T[K];
+} & {
+    [K in PickRequiredRecords<T>]: T[K];
+};
+type PickUndefinedKeys<T extends Record<string, unknown>> = {
+    [K in keyof T]: undefined extends T[K] ? K : never;
+}[keyof T];
+type OptionalUndefinedFields<T extends Record<string, unknown>> = {
+    [K in PickUndefinedKeys<T>]?: T[K];
+} & {
+    [K in Exclude<keyof T, PickUndefinedKeys<T>>]: T[K];
+};
+/**
+ * Removes the indentation from a multiline string.
+ *
+ * @param str The string to trim.
+ * @returns The trimmed string.
+ */
+declare function text(array: TemplateStringsArray, ...values: unknown[]): 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.
+ * Every component inputs and outputs will reference such types and only entities of the same type can be passed.
+ */
+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;
+    /**
+     * Whether the content of the entity is sensitive and should be hidden from the UI.
+     */
+    sensitive: boolean;
+    /**
+     * The extra metadata of the entity.
+     */
+    meta: Meta;
+};
+type EntityOptions<TType extends string, TSchema extends TAnySchema> = PartialKeys<Entity<TType, TSchema>, "sensitive" | "meta">;
+declare function defineEntity<TType extends string, TSchema extends TAnySchema>(options: EntityOptions<TType, TSchema>): Entity<TType, TSchema>;
+declare function isEntity(value: unknown): value is Entity;
+type OutputRef<TType extends string = string> = {
+    type: TType;
+    project: string;
+    stack: string;
+    output: string;
+};
+
+type ComponentArgument = {
+    schema: ArgumentValueSchema;
+    required: boolean;
+    meta: Meta;
+};
+type ComponentArgumentFullOptions = Meta & {
+    schema: AllowedArgumentSchema;
+    required?: boolean;
+};
+type ComponentArgumentOptions = AllowedArgumentSchema | ComponentArgumentFullOptions;
+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]>>;
+};
+type ComponentInput = {
+    type: string;
+    required: boolean;
+    multiple: boolean;
+    meta: Meta;
+};
+type ComponentInputFullOptions = Meta & {
+    entity: Entity;
+    required?: boolean;
+    multiple?: boolean;
+};
+type ComponentInputOptions = Entity | ComponentInputFullOptions;
+type ComponentInputOptionsToOutputRef<T extends ComponentInputOptions> = T extends Entity ? OutputRef<T["type"]> : T extends ComponentInputFullOptions ? T["required"] extends false ? T["multiple"] extends true ? OutputRef<T["entity"]["type"]>[] | undefined : OutputRef<T["entity"]["type"]> | undefined : T["multiple"] extends true ? OutputRef<T["entity"]["type"]>[] : OutputRef<T["entity"]["type"]> : never;
+type ComponentInputSpec = [entity: Entity, required: boolean, multiple: boolean];
+type ComponentInputOptionsToSpec<T extends ComponentInputOptions> = T extends Entity ? [T, true, false] : 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;
+type ComponentInputMapToValue<T extends Record<string, ComponentInputOptions>> = OptionalUndefinedFields<{
+    [K in keyof T]: ComponentInputOptionsToOutputRef<T[K]>;
+}>;
+type ComponentParams<TArgs extends Record<string, ComponentArgumentOptions>, TInputs extends Record<string, ComponentInputOptions>> = {
+    name: string;
+    args: ComponentArgumentMapToValue<TArgs>;
+    inputs: ComponentInputMapToValue<TInputs>;
+};
+type InputComponentParams<TArgs extends Record<string, ArgumentValue>, TInputs extends Record<string, unknown>> = {
+    name: string;
+} & OptionalEmptyRecords<{
+    args: TArgs;
+    inputs: TInputs;
+}>;
+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>) => ComponentInputMapToValue<TOutputs>;
+};
+type ComponentMeta = Meta & {
+    primaryIcon?: string;
+    primaryIconColor?: string;
+    secondaryIcon?: string;
+    secondaryIconColor?: string;
+    category?: string;
+};
+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;
+};
+type InputSpecToOutputRef<T extends ComponentInputSpec> = T[1] extends true ? T[2] extends true ? OutputRef<T[0]["type"]>[] : OutputRef<T[0]["type"]> : T[2] extends true ? OutputRef<T[0]["type"]>[] | undefined : OutputRef<T[0]["type"]> | undefined;
+type OutputRefMap<TInputs extends Record<string, ComponentInputSpec>> = TInputs extends Record<string, [string, never, never]> ? Record<string, never> : {
+    [K in keyof TInputs]: InputSpecToOutputRef<TInputs[K]>;
+};
+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;
+    /**
+     * Creates the component at the evaluation time.
+     */
+    (context: InputComponentParams<TArgs, OutputRefMap<TInputs>>): OutputRefMap<TOutputs>;
+};
+type ArgumentOptionsMapToStatic<T extends Record<string, ComponentArgumentOptions>> = T extends Record<string, never> ? Record<string, never> : Static<TObject<{
+    [K in keyof T]: ComponentArgumentOptionsToSchema<T[K]>;
+}>>;
+declare 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>, {
+    [K in keyof TInputs]: ComponentInputOptionsToSpec<TInputs[K]>;
+}, {
+    [K in keyof TOutputs]: ComponentInputOptionsToSpec<TOutputs[K]>;
+}>;
+declare function isComponent(value: unknown): value is Component;
+
+type UnitOptions<TArgs extends Record<string, ComponentArgumentOptions>, TInputs extends Record<string, ComponentInputOptions>, TOutputs extends Record<string, ComponentInputOptions>, TSecrets extends Record<string, ComponentArgumentOptions>> = Omit<ComponentOptions<TArgs, TInputs, TOutputs>, "create"> & {
+    source: UnitSource;
+    secrets?: TSecrets;
+};
+type UnitSource = {
+    type: "npm";
+    package: string;
+    version?: string;
+    path?: string;
+};
+type UnitModel = ComponentModel & {
+    source: UnitSource;
+    /**
+     * The record of the secret argument schemas.
+     */
+    secrets: Record<string, ComponentArgument>;
+};
+type Unit<TArgs extends Record<string, ArgumentValue> = Record<string, never>, TInputs extends Record<string, ComponentInputSpec> = Record<string, never>, TOutputs extends Record<string, ComponentInputSpec> = Record<string, never>, TSecrets extends Record<string, ArgumentValue> = Record<string, never>> = Component<TArgs, TInputs, TOutputs> & {
+    __secrets: TSecrets;
+    model: UnitModel;
+};
+declare function isUnitModel(model: ComponentModel): model is UnitModel;
+declare function defineUnit<TArgs extends Record<string, ComponentArgumentOptions> = Record<string, never>, TInputs extends Record<string, ComponentInputOptions> = Record<string, never>, TOutputs extends Record<string, ComponentInputOptions> = Record<string, never>, TSecrets extends Record<string, ComponentArgumentOptions> = Record<string, never>>(options: UnitOptions<TArgs, TInputs, TOutputs, TSecrets>): Unit<ArgumentOptionsMapToStatic<TArgs>, {
+    [K in keyof TInputs]: ComponentInputOptionsToSpec<TInputs[K]>;
+}, {
+    [K in keyof TOutputs]: ComponentInputOptionsToSpec<TOutputs[K]>;
+}, ArgumentOptionsMapToStatic<TSecrets>>;
+
+export { type ArgumentValue, type Component, type ComponentArgument, type ComponentInput, type ComponentInputSpec, type ComponentMeta, type ComponentModel, type Entity, type OutputRef, type Unit, type UnitModel, type UnitRegistration, type UnitSource, defineComponent, defineEntity, defineUnit, getUnitRegistrations, isComponent, isEntity, isUnitModel, text };

package/dist/index.mjs

@@ -0,0 +1,135 @@
+import { OptionalKind, Type } from '@sinclair/typebox';
+import { mapValues } from 'remeda';
+
+const unitRegistrations = {};
+function getUnitRegistrations() {
+  return unitRegistrations;
+}
+function registerUnit(unit) {
+  unitRegistrations[`${unit.type}.${unit.name}`] = unit;
+}
+
+function defineEntity(options) {
+  return {
+    sensitive: false,
+    meta: {},
+    ...options
+  };
+}
+function isEntity(value) {
+  return typeof value === "object" && value !== null && "type" in value && "schema" in value && "sensitive" in value && "meta" in value;
+}
+
+function defineComponent(options) {
+  function create(params) {
+    const { name, args, inputs } = params;
+    return options.create({
+      name,
+      args: args ?? {},
+      inputs: inputs ?? {}
+    });
+  }
+  create.model = {
+    type: options.type,
+    args: mapValues(options.args ?? {}, mapArgument),
+    inputs: mapValues(options.inputs ?? {}, mapInput),
+    outputs: mapValues(options.outputs ?? {}, mapInput),
+    meta: options.meta ?? {}
+  };
+  return create;
+}
+function isComponent(value) {
+  return typeof value === "function" && "model" in value;
+}
+function mapArgument(value) {
+  if ("schema" in value) {
+    return {
+      schema: value.schema,
+      required: value.required ?? !value.schema[OptionalKind],
+      meta: {
+        displayName: value.displayName,
+        description: value.description,
+        color: value.color
+      }
+    };
+  }
+  return {
+    schema: value,
+    required: !value[OptionalKind],
+    secret: false,
+    meta: {}
+  };
+}
+function mapInput(value) {
+  if ("entity" in value) {
+    return {
+      type: value.entity.type,
+      required: value.required ?? true,
+      multiple: value.multiple ?? false,
+      meta: {
+        displayName: value.displayName,
+        description: value.description,
+        color: value.color
+      }
+    };
+  }
+  return {
+    type: value.type,
+    required: true,
+    multiple: false,
+    meta: {}
+  };
+}
+
+function isUnitModel(model) {
+  return "source" in model;
+}
+function defineUnit(options) {
+  const component = defineComponent({
+    ...options,
+    create({ name, args, inputs }) {
+      registerUnit({
+        type: options.type,
+        name,
+        config: {
+          ...mapValues(args, (value) => typeof value === "string" ? value : JSON.stringify(value)),
+          ...mapValues(inputs, (value) => JSON.stringify(value))
+        },
+        dependencies: Object.values(inputs).map((value) => `${value.project}.${value.stack}`)
+      });
+      return fillUnitOutputs(name, options.type, options.outputs);
+    }
+  });
+  component.model.source = options.source;
+  component.model.secrets = mapValues(options.secrets ?? {}, mapArgument);
+  return component;
+}
+function fillUnitOutputs(name, type, optionsOutputs = {}) {
+  const outputs = {};
+  for (const key in optionsOutputs) {
+    outputs[key] = {
+      type,
+      project: type,
+      stack: name,
+      output: key
+    };
+  }
+  return outputs;
+}
+
+function text(array, ...values) {
+  const str = array.reduce((result, part, i) => result + part + (String(values[i]) || ""), "");
+  const lines = str.split("\n");
+  const indent = lines.filter((line) => line.trim() !== "").map((line) => line.match(/^\s*/)?.[0].length ?? 0).reduce((min, indent2) => Math.min(min, indent2), Infinity);
+  return lines.map((line) => line.slice(indent)).join("\n").trim();
+}
+
+Type.Union([
+  Type.String(),
+  Type.Number(),
+  Type.Boolean(),
+  Type.Array(Type.String()),
+  Type.Array(Type.Number())
+]);
+
+export { defineComponent, defineEntity, defineUnit, getUnitRegistrations, isComponent, isEntity, isUnitModel, text };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highstate/contract",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -28,5 +28,5 @@
     "jest": "^29.7.0",
     "pkgroll": "^2.5.1"
   },
-  "gitHead": "41f789ef9d6da623923812bba9783c216605495d"
+  "gitHead": "205bae57e7b9e8e8ebe979859df3f18fdb8cfe81"
 }