Type Generator

The type generator (@xriptjs/typegen) reads an xript manifest and produces TypeScript definition files (.d.ts). This gives extenders autocomplete, type checking, and inline documentation in their editors.

Installation

npm install @xriptjs/typegen

CLI Usage

# Print TypeScript definitions to stdout
xript-typegen manifest.json

# Write to a file
xript-typegen manifest.json --output types.d.ts
xript-typegen manifest.json -o types.d.ts

Example

Given a manifest with a greet binding and a Position type:

$ xript-typegen manifest.json

Produces:

// Auto-generated by @xriptjs/typegen
// Source manifest: my-app v1.0.0
// Do not edit manually.

/** A 2D position. */
interface Position {
  /** Horizontal coordinate. */
  x: number;
  /** Vertical coordinate. */
  y: number;
}

/**
 * Returns a greeting.
 * @param name - The name to greet.
 */
declare function greet(name: string): string;

Programmatic Usage

import { generateTypes, generateTypesFromFile } from "@xriptjs/typegen";

// From a manifest object
const dts = generateTypes(manifest);

// From a file
const { content } = await generateTypesFromFile("./manifest.json");

Type Mapping

The generator maps manifest types to TypeScript following the rules in the Bindings spec:

Manifest	TypeScript
"string"	string
"number"	number
"boolean"	boolean
"void"	void
"string[]"	string[]
{ "array": "Position" }	Position[]
{ "union": ["string", "number"] }	string | number
{ "map": "number" }	Record<string, number>
{ "optional": "string" }	string | undefined

Custom object types become interface declarations. Enum types become string literal unions (type Direction = "north" \| "south" \| ...).

Generated JSDoc

The generator includes JSDoc comments from manifest descriptions:

• Function descriptions become the main JSDoc comment
• Parameter descriptions become @param tags
• Capability requirements become @remarks Requires capability: \name“ annotations
• Deprecation notices become @deprecated tags