@asterql/schema

npm install @asterql/schema

TypeNode schemas for AsterQL data shaping and code generation.

This package is intentionally small. It gives the rest of the AsterQL stack a plain JSON-like type graph that can represent practical TypeScript-shaped JSON, including recursive and reused shapes through named references.

import {
  arrayType,
  defineSchema,
  objectType,
  optionalProp,
  refType,
  stringType,
} from "@asterql/schema";

const schema = defineSchema({
  root: refType("Category"),
  definitions: {
    Category: objectType({
      id: stringType(),
      title: stringType(),
      parent: optionalProp(refType("Category")),
      children: arrayType(refType("Category")),
    }),
  },
});

Model

type TypeSchema = {
  root: TypeNode;
  definitions: Record<string, TypeNode>;
};

refType("Name") points at definitions.Name. References are never expanded during normalization, which keeps recursive graphs finite and deterministic.

API

• defineSchema(input): normalize a schema and verify all refs are defined.
• normalizeTypeNode(node): canonicalize a TypeNode.
• serializeTypeNode(node): stable JSON string for a TypeNode.
• serializeSchema(schema): stable JSON string for a schema.
• collectRefs(node): collect named refs from a TypeNode.
• Builders: unknownType, neverType, nullType, booleanType, numberType, stringType, literalType, arrayType, objectType, prop, optionalProp, unionType, intersectionType, recordType, tupleType, refType, and nullableType.

Why named refs?

AsterQL codegen needs to preserve shape identity. If two fields point at the same named type, codegen should know that. If a type points at itself, codegen must not expand forever. Named refs keep those cases simple and explicit.