core

Type Aliases

Annotation

type Annotation = object;

Annotation Annotation metadata preserved in IR.

name is the annotation identifier without the @ prefix. argument, when present, is fully resolved as a LiteralValue.

Properties

argument?

optional argument: LiteralValue;

name

name: string;

position

position: Position;

---

ConstantDef

type ConstantDef = object;

ConstantDef Fully resolved constant definition.

typeRef is explicit or inferred by analysis. value contains the fully resolved literal payload.

Properties

annotations

annotations: Annotation[];

doc?

optional doc: string;

name

name: string;

position

position: Position;

typeRef

typeRef: TypeRef;

value

value: LiteralValue;

---

EnumDef

type EnumDef = object;

EnumDef Flattened enum definition.

All enum spreads are already expanded into members.

Properties

annotations

annotations: Annotation[];

doc?

optional doc: string;

enumType

enumType: EnumValueType;

members

members: EnumMember[];

name

name: string;

position

position: Position;

---

EnumMember

type EnumMember = object;

EnumMember Enum member definition

Properties

annotations

annotations: Annotation[];

doc?

optional doc: string;

name

name: string;

position

position: Position;

value

value: LiteralValue;

---

EnumValueType

type EnumValueType = "string" | "int";

Underlying storage kind used by an enum

---

Field

type Field = object;

Field Flattened object/type field definition

Properties

annotations

annotations: Annotation[];

doc?

optional doc: string;

name

name: string;

optional

optional: boolean;

position

position: Position;

typeRef

typeRef: TypeRef;

---

IrSchema

type IrSchema = object;

IrSchema IrSchema is the generator-facing representation of a VDL program.

This model is intentionally "flat" and "resolved":

• spreads are already expanded
• references are already resolved
• collections are in deterministic order

A code generator should be able to consume IrSchema directly, without needing to re-run parser or semantic-analysis logic.

Properties

constants

constants: ConstantDef[];

docs

docs: TopLevelDoc[];

entryPoint

entryPoint: string;

enums

enums: EnumDef[];

types

types: TypeDef[];

---

LiteralKind

type LiteralKind = "string" | "int" | "float" | "bool" | "object" | "array";

Kind discriminator for LiteralValue.

LiteralValue is used for fully resolved literal data in:

• constant values
• annotation arguments

---

LiteralValue

type LiteralValue = object;

LiteralValue Fully resolved literal value.

The selected payload is determined by kind:

• string -> stringValue
• int -> intValue
• float -> floatValue
• bool -> boolValue
• object -> objectEntries
• array -> arrayItems

Properties

arrayItems?

optional arrayItems: LiteralValue[];

boolValue?

optional boolValue: boolean;

floatValue?

optional floatValue: number;

intValue?

optional intValue: number;

kind

kind: LiteralKind;

objectEntries?

optional objectEntries: ObjectEntry[];

position

position: Position;

stringValue?

optional stringValue: string;

---

ObjectEntry

type ObjectEntry = object;

ObjectEntry Key/value pair inside an object LiteralValue payload

Properties

key

key: string;

position

position: Position;

value

value: LiteralValue;

---

PluginInput

type PluginInput = object;

PluginInput PluginInput represents the data payload sent to a plugin.

The plugin receives this as a single argument containing the complete Intermediate Representation of the VDL schema along with any user-defined configuration options from vdl.config.vdl.

Properties

ir

ir: IrSchema;

options

options: Record<string, string>;

version

version: string;

---

PluginOutput

type PluginOutput = object;

PluginOutput PluginOutput represents the response payload returned by the plugin function.

After processing the input schema, the plugin outputs this object containing all files to be generated or errors to be displayed to the user.

If there are no errors and at least one file is returned, VDL will write each file to the specified path within the output directory. If there are errors, VDL will display them to the user and not write any files.

Properties

errors?

optional errors: PluginOutputError[];

files?

optional files: PluginOutputFile[];

---

PluginOutputError

type PluginOutputError = object;

PluginOutputError A structured error reported by the plugin.

Properties

message

message: string;

position?

optional position: Position;

---

PluginOutputFile

type PluginOutputFile = object;

PluginOutputFile PluginOutputFile represents a single generated file produced by the plugin.

This abstraction allows plugins to generate multiple files from a single invocation, enabling patterns like one-file-per-type or splitting large outputs across multiple modules.

Properties

content

content: string;

path

path: string;

---

Position

type Position = object;

Position It represents a position within a file and is used for error reporting, diagnostics, plugins, and tooling support.

Properties

column

column: number;

file

file: string;

line

line: number;

---

PrimitiveType

type PrimitiveType = "string" | "int" | "float" | "bool" | "datetime";

Primitive scalar type names

---

TopLevelDoc

type TopLevelDoc = object;

TopLevelDoc Standalone documentation block.

Used for top-level docstrings that are not attached to a type/enum/constant.

Properties

content

content: string;

position

position: Position;

---

TypeDef

type TypeDef = object;

TypeDef Flattened type definition.

All spreads are already expanded. The unified typeRef describes what this type IS, a primitive, custom reference, map, array, or object with fields.

Properties

annotations

annotations: Annotation[];

doc?

optional doc: string;

name

name: string;

position

position: Position;

typeRef

typeRef: TypeRef;

---

TypeKind

type TypeKind = "primitive" | "type" | "enum" | "array" | "map" | "object";

Kind discriminator for TypeRef

---

TypeRef

type TypeRef = object;

TypeRef Normalized type reference used by fields and constants.

kind selects which payload fields are meaningful. Generators should inspect kind first, then read the related payload fields.

Properties

arrayDims?

optional arrayDims: number;

arrayType?

optional arrayType: TypeRef;

enumName?

optional enumName: string;

enumType?

optional enumType: EnumValueType;

kind

kind: TypeKind;

mapType?

optional mapType: TypeRef;

objectFields?

optional objectFields: Field[];

primitiveName?

optional primitiveName: PrimitiveType;

typeName?

optional typeName: string;

---

VdlPluginHandler()

type VdlPluginHandler = (input) => PluginOutput;

Function signature implemented by every VDL plugin entry point.

The handler receives the typed plugin input produced by VDL and returns the generated files and any diagnostics for the current run.

Parameters

input

PluginInput

The plugin invocation context, including version, options, and IR.

Returns

PluginOutput

The files and errors produced by the plugin.

Example

const generate: VdlPluginHandler = (input) => {
  return {
    files: [{ path: "hello.txt", content: input.version }],
  };
};

Variables

EnumValueTypeList

const EnumValueTypeList: EnumValueType[];

---

LiteralKindList

const LiteralKindList: LiteralKind[];

---

PrimitiveTypeList

const PrimitiveTypeList: PrimitiveType[];

---

TypeKindList

const TypeKindList: TypeKind[];

Functions

definePlugin()

function definePlugin(handler): VdlPluginHandler;

Wraps a plugin handler so it can be exported as the canonical VDL entry point.

definePlugin is intentionally minimal. It preserves the handler's type information and gives plugin projects a single, explicit pattern for exporting generate from src/index.ts.

Parameters

handler

VdlPluginHandler

The plugin implementation to expose as the runtime entry point.

Returns

VdlPluginHandler

The same handler function, unchanged.

Example

import { definePlugin } from "@varavel/vdl-plugin-sdk";

export const generate = definePlugin((input) => {
  return {
    files: [
      {
        path: "schema-summary.txt",
        content: `VDL ${input.version}`,
      },
    ],
  };
});

---

hydrateAnnotation()

function hydrateAnnotation(input): Annotation;

Parameters

input

Annotation

Returns

Annotation

---

hydrateConstantDef()

function hydrateConstantDef(input): ConstantDef;

Parameters

input

ConstantDef

Returns

ConstantDef

---

hydrateEnumDef()

function hydrateEnumDef(input): EnumDef;

Parameters

input

EnumDef

Returns

EnumDef

---

hydrateEnumMember()

function hydrateEnumMember(input): EnumMember;

Parameters

input

EnumMember

Returns

EnumMember

---

hydrateField()

function hydrateField(input): Field;

Parameters

input

Field

Returns

Field

---

hydrateIrSchema()

function hydrateIrSchema(input): IrSchema;

Parameters

input

IrSchema

Returns

IrSchema

---

hydrateLiteralValue()

function hydrateLiteralValue(input): LiteralValue;

Parameters

input

LiteralValue

Returns

LiteralValue

---

hydrateObjectEntry()

function hydrateObjectEntry(input): ObjectEntry;

Parameters

input

ObjectEntry

Returns

ObjectEntry

---

hydratePluginInput()

function hydratePluginInput(input): PluginInput;

Parameters

input

PluginInput

Returns

PluginInput

---

hydratePluginOutput()

function hydratePluginOutput(input): PluginOutput;

Parameters

input

PluginOutput

Returns

PluginOutput

---

hydratePluginOutputError()

function hydratePluginOutputError(input): PluginOutputError;

Parameters

input

PluginOutputError

Returns

PluginOutputError

---

hydratePluginOutputFile()

function hydratePluginOutputFile(input): PluginOutputFile;

Parameters

input

PluginOutputFile

Returns

PluginOutputFile

---

hydratePosition()

function hydratePosition(input): Position;

Parameters

input

Position

Returns

Position

---

hydrateTopLevelDoc()

function hydrateTopLevelDoc(input): TopLevelDoc;

Parameters

input

TopLevelDoc

Returns

TopLevelDoc

---

hydrateTypeDef()

function hydrateTypeDef(input): TypeDef;

Parameters

input

TypeDef

Returns

TypeDef

---

hydrateTypeRef()

function hydrateTypeRef(input): TypeRef;

Parameters

input

TypeRef

Returns

TypeRef

---

isEnumValueType()

function isEnumValueType(value): value is EnumValueType;

Parameters

value

unknown

Returns

value is EnumValueType

---

isLiteralKind()

function isLiteralKind(value): value is LiteralKind;

Parameters

value

unknown

Returns

value is LiteralKind

---

isPrimitiveType()

function isPrimitiveType(value): value is PrimitiveType;

Parameters

value

unknown

Returns

value is PrimitiveType

---

isTypeKind()

function isTypeKind(value): value is TypeKind;

Parameters

value

unknown

Returns

value is TypeKind

---

validateAnnotation()

function validateAnnotation(input, path?): string | null;

Parameters

input

unknown

path?

string = "Annotation"

Returns

string | null

---

validateConstantDef()

function validateConstantDef(input, path?): string | null;

Parameters

input

unknown

path?

string = "ConstantDef"

Returns

string | null

---

validateEnumDef()

function validateEnumDef(input, path?): string | null;

Parameters

input

unknown

path?

string = "EnumDef"

Returns

string | null

---

validateEnumMember()

function validateEnumMember(input, path?): string | null;

Parameters

input

unknown

path?

string = "EnumMember"

Returns

string | null

---

validateField()

function validateField(input, path?): string | null;

Parameters

input

unknown

path?

string = "Field"

Returns

string | null

---

validateIrSchema()

function validateIrSchema(input, path?): string | null;

Parameters

input

unknown

path?

string = "IrSchema"

Returns

string | null

---

validateLiteralValue()

function validateLiteralValue(input, path?): string | null;

Parameters

input

unknown

path?

string = "LiteralValue"

Returns

string | null

---

validateObjectEntry()

function validateObjectEntry(input, path?): string | null;

Parameters

input

unknown

path?

string = "ObjectEntry"

Returns

string | null

---

validatePluginInput()

function validatePluginInput(input, path?): string | null;

Parameters

input

unknown

path?

string = "PluginInput"

Returns

string | null

---

validatePluginOutput()

function validatePluginOutput(input, path?): string | null;

Parameters

input

unknown

path?

string = "PluginOutput"

Returns

string | null

---

validatePluginOutputError()

function validatePluginOutputError(input, path?): string | null;

Parameters

input

unknown

path?

string = "PluginOutputError"

Returns

string | null

---

validatePluginOutputFile()

function validatePluginOutputFile(_input, _path?): string | null;

Parameters

_input

unknown

_path?

string = "PluginOutputFile"

Returns

string | null

---

validatePosition()

function validatePosition(_input, _path?): string | null;

Parameters

_input

unknown

_path?

string = "Position"

Returns

string | null

---

validateTopLevelDoc()

function validateTopLevelDoc(input, path?): string | null;

Parameters

input

unknown

path?

string = "TopLevelDoc"

Returns

string | null

---

validateTypeDef()

function validateTypeDef(input, path?): string | null;

Parameters

input

unknown

path?

string = "TypeDef"

Returns

string | null

---

validateTypeRef()

function validateTypeRef(input, path?): string | null;

Parameters

input

unknown

path?

string = "TypeRef"

Returns

string | null