@platform/metaltura¶

Location: modules/platform/metaltura/
Dependencies: @platform/core, @platform/socket, @platform/doc, @platform/schema

Overview¶

@platform/metaltura is the visual modeling and workspace editor of the platform. It provides:

A class-diagram editor for defining domain models visually (classes, properties, relations, inheritance).
A Workspace runtime that can instantiate and manipulate elements according to a model.
An execution engine that can run TypeScript functions defined on model elements.
Persistence via @platform/doc and real-time collaboration via @platform/socket.

Before reading the API: understand the Core metamodel first.
See metamodel.md for the self-referential bootstrap, CoreCache, and the @metaltura/core ambient module.
See workspace.md for the loading pipeline, element paths, the Update protocol, and React reactivity.

Core Concepts¶

Concept	Description
Core model	The hardcoded bootstrap metamodel that describes all other models — see metamodel.md
Model	A named collection of `Class` definitions — analogous to a package
Class	A named type with properties, relations, validations, and optional inheritance
Element	A runtime instance of a `Class`
Property	A typed attribute on a `Class` — may be primitive or a relation to another class
Relation	A property whose type is another `Class`
Function	A code property on a `Class` that can be executed at runtime
Workspace	The stateful container that holds models and element instances
Package	A namespace grouping several classes inside a model

Contexts¶

Context	Entry point	Contents
`client`	`src/client/index.ts`	Diagram components, workspace hooks, `MetalturaModule`
`server`	`src/server/index.ts`	`MetalturaServer` — socket services for workspace persistence
`common`	`src/common/index.ts`	`Workspace`, `Class`, `Element`, `Model`, and all related classes/types

Common API¶

Core Classes¶

import {
  Workspace, Model, Class, Element,
  Property, Relation, PrimitiveProperty,
  Function, Parameter, ReturnType,
  Package, PrimitiveType, Validation
} from '@platform/metaltura/common'

Export	Description
`Workspace`	Central runtime container — manages models, elements, and emits RxJS updates (see workspace.md)
`Model`	Collection of class definitions
`Class`	Type definition with properties and optional superclass(es)
`Element`	Runtime instance of a `Class`
`Property`	Abstract base for class attributes
`PrimitiveProperty`	Property with a primitive value (string, number, boolean)
`Relation`	Property whose value is another `Element`
`Function`	Executable code property on a `Class`
`Parameter`	Function parameter definition
`ReturnType`	Function return type definition
`Package`	Namespace grouping classes
`PrimitiveType`	Built-in primitive type descriptor
`Validation`	Validation rule attached to a class or property

Workspace Methods¶

The Workspace instance exposes methods for full CRUD on the model graph:

Method	Description
`loadModel(raw)`	Parse and register a raw model definition
`loadModels(raws)`	Load multiple models at once
`get(path)`	Retrieve an element by path
`filter(predicate)`	Query elements matching a predicate
`add(element, property, value)`	Append a value to an array property
`set(element, property, value)`	Set a property value on an element
`unset(element, property)`	Remove a property value
`remove(element, property, index)`	Remove an item from an array property
`del(element)`	Delete an element from the workspace
`move(element, property, target)`	Move an element between owners
`update(updates)`	Apply a batch of `Update` operations, then run compilation/validation asynchronously
`validate(element)`	Run all validation rules on an element

Model dependency rule: an element can only reference elements from its own model, from models listed in depends (directly or transitively), and from Core (always available). Violations are reported by validation with message modelDependency. | createExecuter(func) | Create a callable from a Function property | | subject | RxJS BehaviorSubject<Model[]> — fires after every update() call; used by React via a version counter (see workspace.md) |

Diagram Entities¶

import {
  ClassDiagram, ClassElement, RelationLink, ExtendsLink
} from '@platform/metaltura/common'

Export	Description
`ClassDiagram`	A visual diagram document storing class positions and links
`ClassElement`	A class box in the diagram (position, size, source class)
`RelationLink`	A link between two `ClassElement`s representing a relation
`ExtendsLink`	A link representing an inheritance relationship

Tools¶

import { classToSchema } from '@platform/metaltura/common'  // schema tool
import { compileFunction, getExtraLibs } from '@platform/metaltura/common'  // func tools
import { isRawElement, isRawModel, toRawElement } from '@platform/metaltura/common'  // raw tool

Tool category	Exports	Description
Schema	`classToSchema`	Convert a `Class` definition to a TypeBox schema
Function	`compileFunction`	Compile a `Function` property into a callable JavaScript function
Function	`getExtraLibs`	Generate Monaco editor extra libs from a workspace for code completion
Raw	`isRawElement` / `isRawModel`	Type guards for raw (unparsed) data
Raw	`toRawElement`	Serialize an `Element` back to a plain object

Client API¶

import {
  MetalturaModule,
  Diagram, useDiagramContext,
  ClassDiagramComponent,
  CreateElementDialog,
  useMetalturaContext,
  useWorkspace,
  useElementMenuItems
} from '@platform/metaltura/client'

Export	Description
`MetalturaModule`	Top-level module component — registers Metaltura in the application shell
`Diagram`	JointJS-backed diagram canvas component
`useDiagramContext`	Hook to access the current JointJS paper and graph (must be used inside a `Diagram`)
`ClassDiagramComponent`	Class-diagram renderer — accepts a live `ClassDiagram` entity as prop
`CreateElementDialog`	Dialog for creating a new element in the workspace
`useMetalturaContext`	Hook to access the full `MetalturaContext` (workspace, selection, editor, creation)
`useWorkspace`	Shorthand hook — returns `workspace` from `MetalturaContext` directly
`useElementMenuItems`	Hook that returns context menu items for a selected element

Usage Example¶

// Common — programmatic workspace manipulation
import { Workspace } from '@platform/metaltura/common'

const ws = new Workspace([
  {
    name: 'MyModel',
    instanceOf: 'core.Model',
    elements: [
      {
        name: 'MyPackage',
        instanceOf: 'core.Package',
        elements: [
          {
            name: 'Person',
            instanceOf: 'core.Class',
            extends: ['core.RootElement'],
            properties: [
              { name: 'firstName', instanceOf: 'core.PrimitiveProperty', type: 'core.StringType' }
            ]
          }
        ]
      }
    ]
  }
])

const person = ws.get('MyPackage.Person', 'class')
console.log(person?.getProperties())

// Apply an update
ws.update({ action: 'set', element: 'MyPackage.Person', property: 'abstract', value: true })

// Client — ClassDiagramComponent takes a live ClassDiagram entity
import { ClassDiagramComponent } from '@platform/metaltura/client'
import { useWorkspace } from '@platform/metaltura/client'

function MyDiagramView() {
  const workspace = useWorkspace()
  const diagram = workspace.get('MyPackage.myDiagram', 'element')
  if (!diagram) return null
  return <ClassDiagramComponent diagram={diagram} />
}

For the raw model format and full Update protocol examples, see workspace.md.