@brika/type-system 0.1.1

package/src/autocomplete.ts

@@ -0,0 +1,174 @@
+/**
+ * Autocomplete — generate completion items from TypeDescriptor.
+ *
+ * Given a resolved type, produces a flat list of completable paths
+ * with their types. Used by the expression editor to offer
+ * deep property autocompletion (e.g., inputs.in.name, inputs.in.age).
+ */
+
+import type { TypeDescriptor } from './descriptor';
+import { displayType } from './display';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Completion Item
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CompletionItem {
+  /** Short label (e.g., "name") */
+  label: string;
+  /** Type display string (e.g., "string") */
+  type: string;
+  /** Full dotted path (e.g., "inputs.in.name") */
+  path: string;
+  /** Whether this item has children (for nested objects) */
+  hasChildren: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Entry Point
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_MAX_DEPTH = 3;
+
+/**
+ * Get autocomplete items for a type at a given base path.
+ *
+ * @param desc - The TypeDescriptor to explore
+ * @param basePath - The path prefix (e.g., "inputs.in")
+ * @param maxDepth - Maximum depth to recurse (default 3)
+ * @returns Flat list of completion items
+ */
+export function getCompletions(
+  desc: TypeDescriptor,
+  basePath: string,
+  maxDepth = DEFAULT_MAX_DEPTH
+): CompletionItem[] {
+  const items: CompletionItem[] = [];
+
+  // Add the root item itself
+  items.push({
+    label: lastSegment(basePath),
+    type: displayType(desc),
+    path: basePath,
+    hasChildren: hasNestedFields(desc),
+  });
+
+  // Recurse into fields
+  if (maxDepth > 0) {
+    collectFields(desc, basePath, maxDepth, items);
+  }
+
+  return items;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal
+// ─────────────────────────────────────────────────────────────────────────────
+
+function collectFields(
+  desc: TypeDescriptor,
+  basePath: string,
+  depth: number,
+  items: CompletionItem[]
+): void {
+  if (depth <= 0) return;
+
+  switch (desc.kind) {
+    case 'object': {
+      for (const [fieldName, field] of Object.entries(desc.fields)) {
+        const path = `${basePath}.${fieldName}`;
+        items.push({
+          label: fieldName,
+          type: displayType(field.type),
+          path,
+          hasChildren: hasNestedFields(field.type),
+        });
+        collectFields(field.type, path, depth - 1, items);
+      }
+      break;
+    }
+
+    case 'array': {
+      // Offer [n] access for element type
+      const path = `${basePath}[n]`;
+      items.push({
+        label: '[n]',
+        type: displayType(desc.element),
+        path,
+        hasChildren: hasNestedFields(desc.element),
+      });
+      collectFields(desc.element, path, depth - 1, items);
+      break;
+    }
+
+    case 'record': {
+      // Offer [key] access for value type
+      const path = `${basePath}[key]`;
+      items.push({
+        label: '[key]',
+        type: displayType(desc.value),
+        path,
+        hasChildren: hasNestedFields(desc.value),
+      });
+      collectFields(desc.value, path, depth - 1, items);
+      break;
+    }
+
+    case 'union': {
+      // For unions, expose fields that are common across all object variants
+      const commonFields = getCommonObjectFields(desc.variants);
+      if (commonFields) {
+        for (const [fieldName, fieldType] of Object.entries(commonFields)) {
+          const path = `${basePath}.${fieldName}`;
+          items.push({
+            label: fieldName,
+            type: displayType(fieldType),
+            path,
+            hasChildren: hasNestedFields(fieldType),
+          });
+          collectFields(fieldType, path, depth - 1, items);
+        }
+      }
+      break;
+    }
+    // Primitives, literals, enums, etc. have no nested fields
+  }
+}
+
+function hasNestedFields(desc: TypeDescriptor): boolean {
+  return desc.kind === 'object' || desc.kind === 'array' || desc.kind === 'record';
+}
+
+function lastSegment(path: string): string {
+  const dot = path.lastIndexOf('.');
+  return dot >= 0 ? path.slice(dot + 1) : path;
+}
+
+/**
+ * For a union of object types, find fields that exist in ALL variants.
+ * Returns a map of fieldName → TypeDescriptor (using the first variant's type).
+ */
+function getCommonObjectFields(
+  variants: readonly TypeDescriptor[]
+): Record<string, TypeDescriptor> | null {
+  const objectVariants = variants.filter(
+    (v): v is Extract<TypeDescriptor, { kind: 'object' }> => v.kind === 'object'
+  );
+
+  if (objectVariants.length === 0 || objectVariants.length !== variants.length) {
+    return null;
+  }
+
+  // Start with fields from the first variant, keep only those present in all
+  const first = objectVariants[0] as Extract<TypeDescriptor, { kind: 'object' }>;
+  const common: Record<string, TypeDescriptor> = {};
+
+  for (const [fieldName, field] of Object.entries(first.fields)) {
+    const presentInAll = objectVariants.every((v) => fieldName in v.fields);
+    if (presentInAll) {
+      common[fieldName] = field.type;
+    }
+  }
+
+  return Object.keys(common).length > 0 ? common : null;
+}

package/src/compatibility.ts

@@ -0,0 +1,200 @@
+/**
+ * Structural Type Compatibility
+ *
+ * Checks if an output type can flow into an input type.
+ * Replaces both arePortTypesCompatible (string-based) and isSchemaCompatible (Zod-based).
+ *
+ * Rules (in priority order):
+ * 1. any/unknown/generic inputs accept everything
+ * 2. any/unknown/generic outputs are accepted by everything
+ * 3. Exact kind + structural match
+ * 4. Numeric equivalence (number/integer/float/double all compatible)
+ * 5. Widening: number/boolean → string
+ * 6. Object structural subtyping
+ * 7. Union rules (output union: all must satisfy; input union: one must match)
+ */
+
+import type { TypeDescriptor } from './descriptor';
+
+const NUMERIC_TYPES = new Set(['number', 'integer', 'float', 'double']);
+
+/**
+ * Check if an output type is compatible with an input type.
+ * Returns true if data of `output` type can safely flow into a port expecting `input` type.
+ */
+export function isCompatible(output: TypeDescriptor, input: TypeDescriptor): boolean {
+  // Wildcards accept/produce anything
+  if (isAcceptAll(input) || isAcceptAll(output)) {
+    return true;
+  }
+
+  // Passthrough/resolved are treated as wildcards (they need resolution first)
+  if (input.kind === 'passthrough' || input.kind === 'resolved') return true;
+  if (output.kind === 'passthrough' || output.kind === 'resolved') return true;
+
+  // Exact same kind — dispatch to specific checker
+  if (output.kind === input.kind) {
+    return checkSameKind(output, input);
+  }
+
+  // Union handling
+  if (input.kind === 'union') {
+    // Output must satisfy at least one variant
+    return input.variants.some((variant) => isCompatible(output, variant));
+  }
+  if (output.kind === 'union') {
+    // All output variants must satisfy input
+    return output.variants.every((variant) => isCompatible(variant, input));
+  }
+
+  // Enum → primitive widening
+  if (output.kind === 'enum' && input.kind === 'primitive') {
+    return isEnumCompatibleWithPrimitive(output.values, input.type);
+  }
+
+  // Literal → primitive widening
+  if (output.kind === 'literal' && input.kind === 'primitive') {
+    return isLiteralCompatibleWithPrimitive(output.value, input.type);
+  }
+
+  // Primitive widening: number/boolean → string
+  if (output.kind === 'primitive' && input.kind === 'primitive') {
+    return isPrimitiveCompatible(output.type, input.type);
+  }
+
+  // Record → object: a record can satisfy an object if value type is compatible with all fields
+  if (output.kind === 'record' && input.kind === 'object') {
+    return Object.values(input.fields).every(
+      (field) => field.optional || isCompatible(output.value, field.type)
+    );
+  }
+
+  // Object → record: an object can produce a record
+  if (output.kind === 'object' && input.kind === 'record') {
+    return Object.values(output.fields).every((field) => isCompatible(field.type, input.value));
+  }
+
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function isAcceptAll(desc: TypeDescriptor): boolean {
+  return desc.kind === 'any' || desc.kind === 'unknown' || desc.kind === 'generic';
+}
+
+function checkSameKind(output: TypeDescriptor, input: TypeDescriptor): boolean {
+  switch (output.kind) {
+    case 'primitive':
+      return isPrimitiveCompatible(
+        output.type,
+        (input as Extract<TypeDescriptor, { kind: 'primitive' }>).type
+      );
+
+    case 'literal': {
+      const inputLit = input as Extract<TypeDescriptor, { kind: 'literal' }>;
+      return output.value === inputLit.value;
+    }
+
+    case 'object': {
+      const inputObj = input as Extract<TypeDescriptor, { kind: 'object' }>;
+      return isObjectCompatible(output.fields, inputObj.fields);
+    }
+
+    case 'array': {
+      const inputArr = input as Extract<TypeDescriptor, { kind: 'array' }>;
+      return isCompatible(output.element, inputArr.element);
+    }
+
+    case 'tuple': {
+      const inputTuple = input as Extract<TypeDescriptor, { kind: 'tuple' }>;
+      if (output.elements.length !== inputTuple.elements.length) return false;
+      return output.elements.every((el, i) => {
+        const inputEl = inputTuple.elements[i];
+        return inputEl !== undefined && isCompatible(el, inputEl);
+      });
+    }
+
+    case 'union': {
+      const inputUnion = input as Extract<TypeDescriptor, { kind: 'union' }>;
+      // All output variants must satisfy at least one input variant
+      return output.variants.every((outV) =>
+        inputUnion.variants.some((inV) => isCompatible(outV, inV))
+      );
+    }
+
+    case 'record': {
+      const inputRec = input as Extract<TypeDescriptor, { kind: 'record' }>;
+      return isCompatible(output.value, inputRec.value);
+    }
+
+    case 'enum': {
+      const inputEnum = input as Extract<TypeDescriptor, { kind: 'enum' }>;
+      // All output values must be in input values
+      return output.values.every((v) => inputEnum.values.includes(v));
+    }
+
+    default:
+      return true;
+  }
+}
+
+function isPrimitiveCompatible(outputType: string, inputType: string): boolean {
+  if (outputType === inputType) return true;
+
+  // Numeric equivalence
+  if (NUMERIC_TYPES.has(outputType) && NUMERIC_TYPES.has(inputType)) return true;
+
+  // Widening: number/boolean → string
+  if (inputType === 'string' && (NUMERIC_TYPES.has(outputType) || outputType === 'boolean')) {
+    return true;
+  }
+
+  return false;
+}
+
+function isObjectCompatible(
+  outputFields: Record<string, { type: TypeDescriptor; optional: boolean }>,
+  inputFields: Record<string, { type: TypeDescriptor; optional: boolean }>
+): boolean {
+  // All required input fields must exist in output with compatible types
+  for (const [key, inputField] of Object.entries(inputFields)) {
+    const outputField = outputFields[key];
+
+    if (!outputField) {
+      // Output doesn't have this field
+      if (!inputField.optional) return false;
+      continue;
+    }
+
+    // Check field type compatibility
+    if (!isCompatible(outputField.type, inputField.type)) return false;
+  }
+
+  return true;
+}
+
+function isEnumCompatibleWithPrimitive(
+  values: readonly (string | number)[],
+  primitiveType: string
+): boolean {
+  if (primitiveType === 'string') {
+    return values.every((v) => typeof v === 'string' || typeof v === 'number');
+  }
+  if (NUMERIC_TYPES.has(primitiveType)) {
+    return values.every((v) => typeof v === 'number');
+  }
+  return false;
+}
+
+function isLiteralCompatibleWithPrimitive(
+  value: string | number | boolean,
+  primitiveType: string
+): boolean {
+  if (primitiveType === 'string') return true; // any literal can be stringified
+  if (primitiveType === 'boolean') return typeof value === 'boolean';
+  if (NUMERIC_TYPES.has(primitiveType)) return typeof value === 'number';
+  return false;
+}

package/src/descriptor.ts

@@ -0,0 +1,157 @@
+/**
+ * TypeDescriptor — serializable, structural type representation.
+ *
+ * This is the single source of truth for port types across the entire system.
+ * Both backend and frontend work with the same representation.
+ * JSON-serializable, works over IPC.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Descriptor
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type PrimitiveType = 'string' | 'number' | 'boolean' | 'null';
+
+export type TypeDescriptor =
+  | { readonly kind: 'primitive'; readonly type: PrimitiveType }
+  | { readonly kind: 'literal'; readonly value: string | number | boolean }
+  | {
+      readonly kind: 'object';
+      readonly fields: Record<string, { readonly type: TypeDescriptor; readonly optional: boolean }>;
+    }
+  | { readonly kind: 'array'; readonly element: TypeDescriptor }
+  | { readonly kind: 'tuple'; readonly elements: readonly TypeDescriptor[] }
+  | { readonly kind: 'union'; readonly variants: readonly TypeDescriptor[] }
+  | { readonly kind: 'record'; readonly value: TypeDescriptor }
+  | { readonly kind: 'enum'; readonly values: readonly (string | number)[] }
+  | { readonly kind: 'any' }
+  | { readonly kind: 'unknown' }
+  | { readonly kind: 'generic'; readonly typeVar: string }
+  | { readonly kind: 'passthrough'; readonly sourcePortId: string }
+  | { readonly kind: 'resolved'; readonly source: string; readonly configField: string };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constructors — shorthand factories for readable code
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const T = {
+  string: { kind: 'primitive', type: 'string' } as TypeDescriptor,
+  number: { kind: 'primitive', type: 'number' } as TypeDescriptor,
+  boolean: { kind: 'primitive', type: 'boolean' } as TypeDescriptor,
+  null: { kind: 'primitive', type: 'null' } as TypeDescriptor,
+  any: { kind: 'any' } as TypeDescriptor,
+  unknown: { kind: 'unknown' } as TypeDescriptor,
+
+  literal(value: string | number | boolean): TypeDescriptor {
+    return { kind: 'literal', value };
+  },
+
+  object(fields: Record<string, { type: TypeDescriptor; optional: boolean }>): TypeDescriptor {
+    return { kind: 'object', fields };
+  },
+
+  /** Shorthand: all fields required */
+  obj(fields: Record<string, TypeDescriptor>): TypeDescriptor {
+    const mapped: Record<string, { type: TypeDescriptor; optional: boolean }> = {};
+    for (const [k, v] of Object.entries(fields)) {
+      mapped[k] = { type: v, optional: false };
+    }
+    return { kind: 'object', fields: mapped };
+  },
+
+  array(element: TypeDescriptor): TypeDescriptor {
+    return { kind: 'array', element };
+  },
+
+  tuple(elements: TypeDescriptor[]): TypeDescriptor {
+    return { kind: 'tuple', elements };
+  },
+
+  union(variants: TypeDescriptor[]): TypeDescriptor {
+    return { kind: 'union', variants };
+  },
+
+  record(value: TypeDescriptor): TypeDescriptor {
+    return { kind: 'record', value };
+  },
+
+  enum(values: (string | number)[]): TypeDescriptor {
+    return { kind: 'enum', values };
+  },
+
+  generic(typeVar = 'T'): TypeDescriptor {
+    return { kind: 'generic', typeVar };
+  },
+
+  passthrough(sourcePortId: string): TypeDescriptor {
+    return { kind: 'passthrough', sourcePortId };
+  },
+
+  resolved(source: string, configField: string): TypeDescriptor {
+    return { kind: 'resolved', source, configField };
+  },
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Type Guards
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Returns true if the type is concrete (not generic, passthrough, or resolved) */
+export function isConcrete(desc: TypeDescriptor): boolean {
+  return desc.kind !== 'generic' && desc.kind !== 'passthrough' && desc.kind !== 'resolved';
+}
+
+/** Returns true if the type accepts any value (any, unknown, or generic) */
+export function isWildcard(desc: TypeDescriptor): boolean {
+  return desc.kind === 'any' || desc.kind === 'unknown' || desc.kind === 'generic';
+}
+
+/** Returns true if the type needs resolution before it can be used */
+export function needsResolution(desc: TypeDescriptor): boolean {
+  return desc.kind === 'generic' || desc.kind === 'passthrough' || desc.kind === 'resolved';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Parsing — convert legacy typeName strings to TypeDescriptor
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Parse a legacy typeName string (e.g. "string", "generic<T>", "passthrough(in)") into a TypeDescriptor */
+export function parseTypeName(typeName?: string): TypeDescriptor {
+  if (!typeName) return T.generic();
+
+  if (typeName.startsWith('generic')) return T.generic(typeName.match(/<(\w+)>/)?.[1] ?? 'T');
+  if (typeName.startsWith('__passthrough:')) return T.passthrough(typeName.slice('__passthrough:'.length));
+  if (typeName.startsWith('passthrough')) return T.passthrough(typeName.match(/\((\w+)\)/)?.[1] ?? 'in');
+  if (typeName.startsWith('$resolve:')) {
+    const parts = typeName.slice('$resolve:'.length).split(':');
+    return T.resolved(parts[0] ?? '', parts[1] ?? '');
+  }
+  if (typeName === 'unknown' || typeName === 'any') return T.unknown;
+  if (typeName === 'string') return T.string;
+  if (typeName === 'number' || typeName === 'integer') return T.number;
+  if (typeName === 'boolean') return T.boolean;
+  if (typeName === 'null') return T.null;
+  if (typeName === 'array') return T.array(T.unknown);
+  if (typeName.endsWith('[]')) return T.array(parseTypeName(typeName.slice(0, -2)));
+
+  return T.unknown;
+}
+
+/** Extract a TypeDescriptor from a port, preferring the structured `type` field over `typeName` */
+export function parsePortType(port: { typeName?: string; type?: Record<string, unknown> }): TypeDescriptor {
+  if (port.type && typeof port.type === 'object' && 'kind' in port.type) {
+    return port.type as unknown as TypeDescriptor;
+  }
+  return parseTypeName(port.typeName);
+}
+
+/** Infer a TypeDescriptor from a runtime JSON value */
+export function inferType(data: unknown): TypeDescriptor {
+  if (data === null) return T.null;
+  if (typeof data === 'string') return T.string;
+  if (typeof data === 'number') return T.number;
+  if (typeof data === 'boolean') return T.boolean;
+  if (Array.isArray(data)) return T.array(T.unknown);
+  if (typeof data === 'object') return T.record(T.unknown);
+  return T.unknown;
+}

package/src/display.ts

@@ -0,0 +1,71 @@
+/**
+ * Display — human-readable type names from TypeDescriptor.
+ *
+ * Produces TypeScript-like type strings:
+ * - "string", "number", "boolean", "null"
+ * - "{name: string, age: number}"
+ * - "number[]"
+ * - "string | number"
+ * - "generic<T>"
+ */
+
+import type { TypeDescriptor } from './descriptor';
+
+/**
+ * Convert a TypeDescriptor to a human-readable type name string.
+ */
+export function displayType(desc: TypeDescriptor): string {
+  switch (desc.kind) {
+    case 'primitive':
+      return desc.type;
+
+    case 'literal':
+      return typeof desc.value === 'string' ? `"${desc.value}"` : String(desc.value);
+
+    case 'object': {
+      const entries = Object.entries(desc.fields);
+      if (entries.length === 0) return '{}';
+      const fields = entries
+        .map(([k, v]) => `${k}${v.optional ? '?' : ''}: ${displayType(v.type)}`)
+        .join(', ');
+      return `{${fields}}`;
+    }
+
+    case 'array': {
+      const el = displayType(desc.element);
+      // Wrap union types in parens for readability: (string | number)[]
+      const needsParens = desc.element.kind === 'union';
+      return needsParens ? `(${el})[]` : `${el}[]`;
+    }
+
+    case 'tuple': {
+      const elements = desc.elements.map(displayType).join(', ');
+      return `[${elements}]`;
+    }
+
+    case 'union':
+      return desc.variants.map(displayType).join(' | ');
+
+    case 'record': {
+      return `Record<string, ${displayType(desc.value)}>`;
+    }
+
+    case 'enum':
+      return desc.values.map((v) => (typeof v === 'string' ? `"${v}"` : String(v))).join(' | ');
+
+    case 'any':
+      return 'any';
+
+    case 'unknown':
+      return 'unknown';
+
+    case 'generic':
+      return `generic<${desc.typeVar}>`;
+
+    case 'passthrough':
+      return `passthrough(${desc.sourcePortId})`;
+
+    case 'resolved':
+      return `$resolve:${desc.source}:${desc.configField}`;
+  }
+}