@carbonenginejs/format-yaml

Safe generic YAML syntax and data reading for CarbonEngineJS format packages and build tools. The package wraps the npm yaml parser, but converts its AST itself so custom tags remain inert unless a caller explicitly supplies a handler.

Status: provisional. This package is intentionally a low-level YAML syntax/data layer first; the API and edge-case coverage are expected to stabilize further as more CarbonEngineJS format packages adopt it.

format-yaml is the syntax/data layer beneath semantic formats:

format-yaml
  -> format-red
  -> future build-time profile adapters

It does not hydrate runtime classes, create resources, or implement Red or paperdoll behavior.

CarbonEngine and Fenris Creations (CCP Games) are named for interoperability and provenance context only. The legacy Python tag spellings supported here were identified from serialized YAML data and are treated only as inert data shapes. No CarbonEngine or Fenris Creations source code, tools, assets, shader source, or proprietary implementation code is included, copied, ported, adapted, or reverse-engineered. This package is not affiliated with or endorsed by CCP Games. See NOTICE for full provenance and third-party attribution.

Install

npm install @carbonenginejs/format-yaml

Public API

The package root exports one plain format facade, CjsFormatYaml, as both the default and named export. The Cjs prefix marks a CarbonEngineJS format boundary, not a runtime class. Reusable instance methods are PascalCase and static one-shot methods are camelCase.

import CjsFormatYaml from "@carbonenginejs/format-yaml";

const yaml = new CjsFormatYaml({ tagPolicy: "preserve" });
const payload = yaml.Read("name: example\n");
const raw = yaml.ReadRaw("left: &node { value: 1 }\nright: *node\n");
const document = yaml.ReadDocument("value: !domain/item 7\n");
const summary = yaml.Inspect("items: [1, 2]\n");

Read and ReadPayload return a JSON-safe payload. ReadRaw returns a plain JS graph and preserves anchor/alias shared identity, including cycles. ReadDocument returns the raw value plus tag, anchor, alias, warning, error, and source inventories. Inspect returns the inventories without converting the value. ToJSON converts a raw graph to the same deterministic JSON-safe shape used by payload reads.

Alias Encoding

Raw mode preserves identity. Payload mode leaves ordinary trees unchanged and encodes repeated or cyclic objects using $yamlId and $yamlRef:

{
  "left": { "$yamlId": 1, "value": 1 },
  "right": { "$yamlRef": 1 }
}

Repeated arrays use { "$yamlId": 1, "$yamlValues": [...] }. This output is deterministic for a deterministic YAML document and can always be passed to JSON.stringify. A repeated mapping that already owns a reserved identity field is rejected rather than silently overwritten.

Safe Tags

No YAML tag executes constructors or imports code. tagPolicy supports:

• preserve (default): unknown tags become inert { $yamlTag, $yamlValue } records.
• reject: unhandled non-standard tags are actionable read errors; the safe Python tuple and Unicode normalizers remain data-only exceptions.
• handle: every non-standard tag needs an explicit function in tagHandlers (apart from the safe Python scalar/sequence normalizers).

allowedTags optionally restricts all accepted custom tags. Entries may use a canonical tag URI, !!python/..., or a local !tag spelling. tagHandlers may be an object or Map; handlers receive (value, context) and are caller code, never code selected by YAML input.

Legacy Python tags used by profile data are handled without Python objects:

• !!python/tuple becomes an array.
• !!python/unicode becomes a string.
• !!python/object:paperDoll.ProjectedDecal is inert tagged data.
• !!python/object:paperDoll.AvatarPartMetaData is inert tagged data.

const value = CjsFormatYaml.readRaw("value: !units/metres 12\n", {
    tagPolicy: "handle",
    allowedTags: [ "!units/metres" ],
    tagHandlers: {
        "!units/metres": (amount) => ({ amount, unit: "m" })
    }
});

Options

• emit: payload/json (default), raw, or document.
• tagPolicy: preserve, reject, or handle.
• allowedTags: optional custom-tag allowlist.
• tagHandlers: explicit custom-tag handler object or Map.
• sourceName: source path/name included in diagnostics.
• maxAliasCount: document alias-count guard; defaults to 100.
• uniqueKeys: require unique mapping keys by default; set to false only for explicitly diagnosed legacy documents that require last-value-wins parsing.
• idField, refField, valuesField, tagField, valueField: reserved payload/tag envelope field names.

The package is read-only in this initial release.

Baseline Checks

npm test
npm run lint

The baseline checks are deterministic and require no network access, private assets, credentials, GUI tools, or external corpus.