constants

(no submodules)

Purpose

The constants module owns the single source of truth for the current schema version of @suaveplan/control-surface-schema. Every other module — the Zod schemas, the validator, the upgrade engine, the migration registry — imports CURRENT_SCHEMA_VERSION from this file so that bumping a release touches exactly one literal. The version drives both the strict-root Zod literal check and the loop-termination condition inside upgradeSurface.

Features

Single exported value CURRENT_SCHEMA_VERSION of literal type "0.1.0".
Companion CurrentSchemaVersion type alias for use in API surfaces that pin a parameter to the current release.
Zero runtime dependencies — pure const.

Usage: Basic Example

import { CURRENT_SCHEMA_VERSION } from "@suaveplan/control-surface-schema";

const draft = {
    id: "abc",
    name: "draft",
    version: CURRENT_SCHEMA_VERSION,
    createdAt: Date.now(),
    updatedAt: Date.now(),
    skin: { id: "default" },
    root: {
        type: "group",
        id: "root",
        layout: { kind: "absolute" },
        transform: { position: { x: 0, y: 0 } },
        children: [],
    },
} as const;

Usage: Advanced Example

Use the literal type as a generic parameter for a build-time check:

import {
    CURRENT_SCHEMA_VERSION,
    type CurrentSchemaVersion,
    upgradeSurface,
} from "@suaveplan/control-surface-schema";

declare function persistAtCurrent<V extends CurrentSchemaVersion>(
    version: V,
): void;

const upgraded = upgradeSurface(rawDocFromDisk);
persistAtCurrent(upgraded.version as CurrentSchemaVersion);
// The signature pins the call site to whatever version this build emits;
// a stale literal becomes a typecheck error at the call site.

API Reference

CURRENT_SCHEMA_VERSION — readonly string literal "0.1.0".
type CurrentSchemaVersion — typeof CURRENT_SCHEMA_VERSION.

Implementation Notes

The version literal is intentionally narrow (as const) so consumer code can rely on type narrowing in switch statements over versioned documents. A breaking change to the schema MUST bump this constant AND register the forward migration before the release ships; the pre-publish gate fails if validateSurface produces a different version than CURRENT_SCHEMA_VERSION on the same document upgradeSurface returned, which catches missed bumps. Consumers that hard-code the literal in their own typed shapes should import the type alias rather than re-derive it, so a future schema version bump only requires updating the version string in this file plus the registered migration in src/upgrade/upgrade.ts. The constant lives outside the schema module so circular imports between Zod schemas and the upgrade pipeline never form.

2.8 KiB Raw Blame History