@carbonenginejs/core-types

Shared CarbonEngineJS type, schema, document, hydration, and runtime model helpers.

This package is the common contract for packages that read, write, or generate CarbonEngineJS data. Format packages can stop at plain JSON or a neutral CjsCarbonDocument; runtime packages can opt into registered classes and CjsModel when they want live objects.

Install

npm install @carbonenginejs/core-types

What It Owns

• document: neutral CjsCarbonDocument, class/struct registries, hydration, and dehydration.
• hydration: adapter seam for construction, value application, and finalize behavior.
• schema: decorators, class/field/method metadata, enum registration, Carbon-method provenance, and component metadata helpers.
• types: Carbon type descriptors, defaults, coercion, cloning, and export helpers.
• model: CjsModel, CjsEventEmitter, CjsEventEmitterScope, CjsModelDirtyState, traversal helpers, and source-record utilities.

Generated enums and generated class catalogs should live in schema or generated runtime packages, not in this foundational package.

Hydration Contract

core-types does not impose a runtime lifecycle on callers. The hydrator only guarantees ordering:

1. construct
2. applyValues
3. finalize

The default behavior is intentionally minimal: registry/class construction, Object.assign for values, and no finalize step. Callers opt into stricter population rules by supplying an adapter.

Use createLifecycleAdapter() when your runtime classes follow a SetValues-style contract. Initialize is optional; disable it explicitly when a project only wants SetValues.

Usage

Hydrate a neutral document into runtime classes

import {
  CjsCarbonDocument,
  CjsClassRegistry,
  CjsDocumentHydrator,
  CjsModel,
  CjsSchema
} from "@carbonenginejs/core-types";
import { createLifecycleAdapter } from "@carbonenginejs/core-types/hydration";

class DemoNode extends CjsModel
{
  position = [0, 0, 0];
}

CjsSchema.define(DemoNode, { className: "DemoNode" });
CjsSchema.defineField(DemoNode, "position", "type", { kind: "vec3" });
CjsSchema.defineField(DemoNode, "position", "io", {
  read: true,
  write: true,
  persist: true,
  notify: true
});

const document = CjsCarbonDocument.create({
  format: "example",
  roots: [{ ref: { $ref: 1 } }],
  nodes: [{
    id: 1,
    kind: "DemoNode",
    fields: { position: [1, 2, 3] }
  }]
});

const registry = CjsClassRegistry.fromMaps({
  constructors: { DemoNode }
});

const adapter = createLifecycleAdapter({ initialize: false });
const { root } = CjsDocumentHydrator.hydrate(document, { registry, adapter });

Work with schema-backed runtime models directly

const node = DemoNode.from({ position: [1, 2, 3] });

node.OnEvent("modified", (_target, payload) => {
  console.log([...payload.properties]);
});

node.SetValues({ position: [4, 5, 6] });
const plain = node.GetValues();

CjsModel is evented, tracks dirty/update state explicitly, and uses schema metadata as its default field contract. registerSourceShapes() and initializeSourceFields() still exist for source-shaped compatibility, but new schema-backed model classes do not need them.

Subpaths

import { CjsCarbonDocument, CjsDocumentHydrator } from "@carbonenginejs/core-types/document";
import { createLifecycleAdapter } from "@carbonenginejs/core-types/hydration";
import { CjsSchema, type, io, carbon, components } from "@carbonenginejs/core-types/schema";
import { CjsModel, CjsEventEmitter, CjsModelDirtyState } from "@carbonenginejs/core-types/model";
import { CARBON_TYPE, normalizeCarbonValue } from "@carbonenginejs/core-types/types";