tsondb 0.1.3

package/lib/renderers/jsonschema/render.js

@@ -0,0 +1,156 @@
+import { addEphemeralUUIDToType, createEntityIdentifierTypeAsDecl, isEntityDecl, } from "../../schema/declarations/EntityDecl.js";
+import { TypeAliasDecl } from "../../schema/declarations/TypeAliasDecl.js";
+import { flatMapAuxiliaryDecls, NodeKind } from "../../schema/Node.js";
+import { isNestedEntityMapType, } from "../../schema/types/references/NestedEntityMapType.js";
+import { getParentDecl } from "../../schema/types/Type.js";
+import { discriminatorKey } from "../../shared/enum.js";
+import { assertExhaustive } from "../../shared/utils/typeSafety.js";
+const defaultOptions = {
+    indentation: 2,
+};
+const renderArrayType = (options, type) => ({
+    type: "array",
+    items: renderType(options, type.items),
+    minItems: type.minItems,
+    maxItems: type.maxItems,
+    uniqueItems: type.uniqueItems,
+});
+const renderObjectType = (options, type) => ({
+    type: "object",
+    properties: Object.fromEntries(Object.entries(type.properties).map(([name, config]) => [
+        name,
+        { description: config.comment, ...renderType(options, config.type) },
+    ])),
+    required: Object.entries(type.properties)
+        .filter(([, config]) => config.isRequired)
+        .map(([name]) => name),
+    minProperties: type.minProperties,
+    maxProperties: type.maxProperties,
+    additionalProperties: type.additionalProperties,
+});
+const renderBooleanType = (_options, _type) => ({ type: "boolean" });
+const renderDateType = (_options, _type) => ({
+    type: "string",
+    format: "date",
+});
+const renderNumericRangeBounds = (inclusiveKey, exclusiveKey, rangeBound) => rangeBound === undefined
+    ? undefined
+    : typeof rangeBound === "number"
+        ? { [inclusiveKey]: rangeBound }
+        : rangeBound.isExclusive
+            ? { [exclusiveKey]: rangeBound.value }
+            : { [inclusiveKey]: rangeBound.value };
+const renderMultipleOf = (multipleOf) => multipleOf === undefined ? undefined : { multipleOf };
+const renderFloatType = (_options, type) => ({
+    type: "number",
+    ...renderNumericRangeBounds("minimum", "exclusiveMinimum", type.minimum),
+    ...renderNumericRangeBounds("maximum", "exclusiveMaximum", type.maximum),
+    ...renderMultipleOf(type.multipleOf),
+});
+const renderIntegerType = (_options, type) => ({
+    type: "integer",
+    ...renderNumericRangeBounds("minimum", "exclusiveMinimum", type.minimum),
+    ...renderNumericRangeBounds("maximum", "exclusiveMaximum", type.maximum),
+    ...renderMultipleOf(type.multipleOf),
+});
+const renderStringType = (_options, type) => ({
+    type: "string",
+    minLength: type.minLength,
+    maxLength: type.maxLength,
+    pattern: type.pattern?.source,
+});
+const renderGenericArgumentIdentifierType = (_options, _type) => {
+    throw new TypeError("GenericArgumentIdentifierType is not supported in JSON Schema.");
+};
+const renderReferenceIdentifierType = (_options, type) => ({
+    $ref: `#/$defs/${type.entity.name}_ID`,
+});
+const renderIncludeIdentifierType = (_options, type) => ({
+    $ref: `#/$defs/${type.reference.name}`,
+});
+const renderNestedEntityMapType = (_options, type) => ({
+    type: "object",
+    additionalProperties: {
+        $ref: `#/$defs/${type.name}`,
+    },
+});
+const renderType = (options, type) => {
+    switch (type.kind) {
+        case NodeKind.ArrayType:
+            return renderArrayType(options, type);
+        case NodeKind.ObjectType:
+            return renderObjectType(options, type);
+        case NodeKind.BooleanType:
+            return renderBooleanType(options, type);
+        case NodeKind.DateType:
+            return renderDateType(options, type);
+        case NodeKind.FloatType:
+            return renderFloatType(options, type);
+        case NodeKind.IntegerType:
+            return renderIntegerType(options, type);
+        case NodeKind.StringType:
+            return renderStringType(options, type);
+        case NodeKind.GenericArgumentIdentifierType:
+            return renderGenericArgumentIdentifierType(options, type);
+        case NodeKind.ReferenceIdentifierType:
+            return renderReferenceIdentifierType(options, type);
+        case NodeKind.IncludeIdentifierType:
+            return renderIncludeIdentifierType(options, type);
+        case NodeKind.NestedEntityMapType:
+            return renderNestedEntityMapType(options, type);
+        default:
+            return assertExhaustive(type, "Unknown type");
+    }
+};
+const renderEntityDecl = (options, decl) => ({
+    description: decl.comment,
+    ...renderType(options, addEphemeralUUIDToType(decl)),
+});
+const renderEnumDecl = (options, decl) => ({
+    description: decl.comment,
+    oneOf: Object.entries(decl.values.value).map(([caseName, caseDef]) => ({
+        type: "object",
+        properties: {
+            [discriminatorKey]: {
+                const: caseName,
+            },
+            ...(caseDef === null ? {} : { [caseName]: renderType(options, caseDef) }),
+        },
+        required: [discriminatorKey, ...(caseDef === null ? [] : [caseName])],
+    })),
+});
+const renderTypeAliasDecl = (options, decl) => ({
+    description: decl.comment,
+    ...renderType(options, decl.type.value),
+});
+const renderDecl = (options, decl) => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return renderEntityDecl(options, decl);
+        case NodeKind.EnumDecl:
+            return renderEnumDecl(options, decl);
+        case NodeKind.TypeAliasDecl:
+            return renderTypeAliasDecl(options, decl);
+        default:
+            return assertExhaustive(decl, "Unknown declaration");
+    }
+};
+const renderDeclarations = (options, declarations) => Object.fromEntries(declarations.map(decl => [decl.name, renderDecl(options, decl)]));
+export const render = (options = defaultOptions, declarations) => {
+    const finalOptions = { ...defaultOptions, ...options };
+    return JSON.stringify({
+        $defs: renderDeclarations(finalOptions, flatMapAuxiliaryDecls(node => {
+            if (isNestedEntityMapType(node)) {
+                return TypeAliasDecl(getParentDecl(node)?.sourceUrl ?? "", {
+                    name: node.name,
+                    comment: node.comment,
+                    type: () => node.type.value,
+                });
+            }
+            else if (isEntityDecl(node)) {
+                return createEntityIdentifierTypeAsDecl(node);
+            }
+            return undefined;
+        }, declarations)),
+    }, undefined, finalOptions.indentation);
+};

package/lib/renderers/ts/index.d.ts

@@ -0,0 +1,6 @@
+import { Output } from "../Output.js";
+import { TypeScriptRendererOptions } from "./render.js";
+export declare const TypeScriptOutput: (options: {
+    targetPath: string;
+    rendererOptions?: TypeScriptRendererOptions;
+}) => Output;

package/lib/renderers/ts/index.js

@@ -0,0 +1,11 @@
+import { mkdir, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { render } from "./render.js";
+export const TypeScriptOutput = (options) => ({
+    run: async (schema) => {
+        await mkdir(dirname(options.targetPath), { recursive: true });
+        await writeFile(options.targetPath, render(options.rendererOptions, schema.declarations), {
+            encoding: "utf-8",
+        });
+    },
+});

package/lib/renderers/ts/render.d.ts

@@ -0,0 +1,5 @@
+import { Decl } from "../../schema/declarations/Declaration.js";
+export type TypeScriptRendererOptions = {
+    indentation: number;
+};
+export declare const render: (options: Partial<TypeScriptRendererOptions> | undefined, declarations: readonly Decl[]) => string;

package/lib/renderers/ts/render.js

@@ -0,0 +1,109 @@
+import { EOL } from "node:os";
+import { addEphemeralUUIDToType, createEntityIdentifierTypeAsDecl, isEntityDecl, } from "../../schema/declarations/EntityDecl.js";
+import { TypeAliasDecl } from "../../schema/declarations/TypeAliasDecl.js";
+import { flatMapAuxiliaryDecls, NodeKind } from "../../schema/Node.js";
+import { isObjectType } from "../../schema/types/generic/ObjectType.js";
+import { isNestedEntityMapType, } from "../../schema/types/references/NestedEntityMapType.js";
+import { getParentDecl } from "../../schema/types/Type.js";
+import { discriminatorKey } from "../../shared/enum.js";
+import { toCamelCase } from "../../shared/utils/string.js";
+import { assertExhaustive } from "../../shared/utils/typeSafety.js";
+import { applyIndentation, joinSyntax, prefixLines, syntax } from "../../utils/render.js";
+const defaultOptions = {
+    indentation: 2,
+};
+const renderDocumentation = (comment) => comment === undefined
+    ? ""
+    : syntax `/**
+${prefixLines(" * ", comment, true)}
+ */
+`;
+const renderTypeParameters = (options, params) => params.length === 0
+    ? ""
+    : `<${params
+        .map(param => param.constraint === undefined
+        ? param.name
+        : joinSyntax(param.name, " extends ", renderType(options, param.constraint)))
+        .join(", ")}>`;
+const renderArrayType = (options, type) => `${renderType(options, type.items)}[]`;
+const wrapAsObject = (options, syntax) => joinSyntax("{", EOL, applyIndentation(1, syntax, options.indentation), EOL, "}");
+const renderObjectType = (options, type) => {
+    return wrapAsObject(options, Object.entries(type.properties)
+        .map(([name, config]) => joinSyntax(renderDocumentation(config.comment), name, config.isRequired ? "" : "?", ": ", renderType(options, config.type)))
+        .join(Object.values(type.properties).some(prop => prop.comment !== undefined) ? EOL + EOL : EOL));
+};
+const renderBooleanType = (_options, _type) => "boolean";
+const renderDateType = (_options, _type) => "Date";
+const renderNumericType = (_options, _type) => "number";
+const renderStringType = (_options, _type) => "string";
+const renderGenericArgumentIdentifierType = (_options, type) => type.argument.name;
+const renderReferenceIdentifierType = (_options, type) => type.entity.name + "_ID";
+const renderIncludeIdentifierType = (_options, type) => type.reference.name;
+const renderNestedEntityMapType = (options, type) => wrapAsObject(options, syntax `[${toCamelCase(type.secondaryEntity.name)}Id: string]: ${type.name}`);
+const renderType = (options, type) => {
+    switch (type.kind) {
+        case NodeKind.ArrayType:
+            return renderArrayType(options, type);
+        case NodeKind.ObjectType:
+            return renderObjectType(options, type);
+        case NodeKind.BooleanType:
+            return renderBooleanType(options, type);
+        case NodeKind.DateType:
+            return renderDateType(options, type);
+        case NodeKind.FloatType:
+            return renderNumericType(options, type);
+        case NodeKind.IntegerType:
+            return renderNumericType(options, type);
+        case NodeKind.StringType:
+            return renderStringType(options, type);
+        case NodeKind.GenericArgumentIdentifierType:
+            return renderGenericArgumentIdentifierType(options, type);
+        case NodeKind.ReferenceIdentifierType:
+            return renderReferenceIdentifierType(options, type);
+        case NodeKind.IncludeIdentifierType:
+            return renderIncludeIdentifierType(options, type);
+        case NodeKind.NestedEntityMapType:
+            return renderNestedEntityMapType(options, type);
+        default:
+            return assertExhaustive(type, "Unknown type");
+    }
+};
+const renderEntityDecl = (options, decl) => joinSyntax(renderDocumentation(decl.comment), "export interface ", decl.name, " ", renderType(options, addEphemeralUUIDToType(decl)));
+const renderEnumDecl = (options, decl) => joinSyntax(renderDocumentation(decl.comment), "export type ", decl.name, renderTypeParameters(options, decl.parameters), " =", ...Object.entries(decl.values.value).map(([caseName, caseDef]) => applyIndentation(1, joinSyntax(EOL, "| {", EOL, applyIndentation(1, joinSyntax(`${discriminatorKey}: "${caseName}"`, caseDef === null
+    ? ""
+    : joinSyntax(EOL, caseName + ": ", renderType(options, caseDef))), options.indentation), EOL, "}"), options.indentation)));
+const renderTypeAliasDecl = (options, decl) => {
+    const type = decl.type.value;
+    return isObjectType(type)
+        ? joinSyntax(renderDocumentation(decl.comment), "export interface ", decl.name, renderTypeParameters(options, decl.parameters), " ", renderType(options, type))
+        : joinSyntax(renderDocumentation(decl.comment), "export type ", decl.name, renderTypeParameters(options, decl.parameters), " = ", renderType(options, type));
+};
+const renderDecl = (options, decl) => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return renderEntityDecl(options, decl);
+        case NodeKind.EnumDecl:
+            return renderEnumDecl(options, decl);
+        case NodeKind.TypeAliasDecl:
+            return renderTypeAliasDecl(options, decl);
+        default:
+            return assertExhaustive(decl, "Unknown declaration");
+    }
+};
+const renderDeclarations = (options, declarations) => declarations.map(decl => renderDecl(options, decl)).join(EOL + EOL);
+export const render = (options = defaultOptions, declarations) => {
+    const finalOptions = { ...defaultOptions, ...options };
+    return renderDeclarations(finalOptions, flatMapAuxiliaryDecls(node => {
+        if (isNestedEntityMapType(node)) {
+            return TypeAliasDecl(getParentDecl(node)?.sourceUrl ?? "", {
+                name: node.name,
+                comment: node.comment,
+                type: () => node.type.value,
+            });
+        }
+        else if (isEntityDecl(node)) {
+            return createEntityIdentifierTypeAsDecl(node);
+        }
+        return undefined;
+    }, declarations));
+};

package/lib/schema/Node.d.ts

@@ -0,0 +1,37 @@
+import { InstancesByEntityName } from "../shared/utils/instances.js";
+import { Decl } from "./declarations/Declaration.js";
+import { Type } from "./types/Type.js";
+export interface NodeKind {
+    EntityDecl: "EntityDecl";
+    EnumDecl: "EnumDecl";
+    TypeAliasDecl: "TypeAliasDecl";
+    MemberDecl: "MemberDecl";
+    ArrayType: "ArrayType";
+    ObjectType: "ObjectType";
+    BooleanType: "BooleanType";
+    FloatType: "FloatType";
+    IntegerType: "IntegerType";
+    StringType: "StringType";
+    DateType: "DateType";
+    GenericArgumentIdentifierType: "GenericArgumentIdentifierType";
+    GenericParameter: "GenericParameter";
+    ReferenceIdentifierType: "ReferenceIdentifierType";
+    IncludeIdentifierType: "IncludeIdentifierType";
+    NestedEntityMapType: "NestedEntityMapType";
+}
+export declare const NodeKind: NodeKind;
+export interface BaseNode {
+    kind: (typeof NodeKind)[keyof typeof NodeKind];
+}
+export type Node = Decl | Type;
+export declare const flatMapAuxiliaryDecls: (callbackFn: (node: Node) => (Decl | undefined)[] | Decl | undefined, declarations: readonly Decl[]) => Decl[];
+export type IdentifierToCheck = {
+    name: string;
+    value: unknown;
+};
+export interface Validators {
+    checkReferentialIntegrity: (identifier: IdentifierToCheck) => Error[];
+}
+export declare const createValidators: (instancesByEntityName: InstancesByEntityName) => Validators;
+export type Serializer<T, U> = (node: T) => U;
+export type GetReferences<T extends Node> = (node: T, value: unknown) => string[];

package/lib/schema/Node.js

@@ -0,0 +1,79 @@
+import { assertExhaustive } from "../shared/utils/typeSafety.js";
+import { enumOfObject } from "../utils/enum.js";
+export const NodeKind = enumOfObject({
+    EntityDecl: null,
+    EnumDecl: null,
+    TypeAliasDecl: null,
+    MemberDecl: null,
+    ArrayType: null,
+    ObjectType: null,
+    BooleanType: null,
+    FloatType: null,
+    IntegerType: null,
+    StringType: null,
+    DateType: null,
+    GenericArgumentIdentifierType: null,
+    GenericParameter: null,
+    ReferenceIdentifierType: null,
+    IncludeIdentifierType: null,
+    NestedEntityMapType: null,
+});
+export const flatMapAuxiliaryDecls = (callbackFn, declarations) => {
+    const mapNodeTree = (callbackFn, node, decls) => {
+        switch (node.kind) {
+            case NodeKind.EntityDecl: {
+                const newDecls = callbackFn(node, decls);
+                return mapNodeTree(callbackFn, node.type.value, newDecls);
+            }
+            case NodeKind.EnumDecl: {
+                const newDecls = callbackFn(node, decls);
+                return Object.values(node.values.value).reduce((newDeclsAcc, caseDef) => caseDef === null ? newDecls : mapNodeTree(callbackFn, caseDef, newDeclsAcc), newDecls);
+            }
+            case NodeKind.TypeAliasDecl: {
+                const newDecls = callbackFn(node, decls);
+                return mapNodeTree(callbackFn, node.type.value, newDecls);
+            }
+            case NodeKind.ArrayType: {
+                const newDecls = callbackFn(node, decls);
+                return mapNodeTree(callbackFn, node.items, newDecls);
+            }
+            case NodeKind.ObjectType: {
+                const newDecls = callbackFn(node, decls);
+                return Object.values(node.properties).reduce((newDeclsAcc, prop) => mapNodeTree(callbackFn, prop.type, newDeclsAcc), newDecls);
+            }
+            case NodeKind.BooleanType:
+            case NodeKind.DateType:
+            case NodeKind.FloatType:
+            case NodeKind.IntegerType:
+            case NodeKind.StringType:
+            case NodeKind.GenericArgumentIdentifierType:
+            case NodeKind.ReferenceIdentifierType:
+            case NodeKind.IncludeIdentifierType:
+            case NodeKind.NestedEntityMapType:
+                return callbackFn(node, decls);
+            default:
+                return assertExhaustive(node);
+        }
+    };
+    const reducer = (node, decls) => {
+        const result = callbackFn(node);
+        const normalizedResult = (Array.isArray(result) ? result : [result]).filter(decl => decl !== undefined);
+        normalizedResult.forEach(decl => {
+            if (decls.some(existingDecl => existingDecl.name === decl.name)) {
+                throw new Error(`Duplicate declaration name: "${decl.name}". Make sure declaration names are globally unique.`);
+            }
+        });
+        return decls.concat(normalizedResult);
+    };
+    return declarations.reduce((decls, node) => mapNodeTree(reducer, node, [...decls, node]), []);
+};
+export const createValidators = (instancesByEntityName) => ({
+    checkReferentialIntegrity: ({ name, value }) => instancesByEntityName[name].some(instance => typeof instance.content === "object" &&
+        instance.content !== null &&
+        !Array.isArray(instance.content) &&
+        instance.id === value)
+        ? []
+        : [
+            ReferenceError(`Invalid reference to instance of entity "${name}" with identifier ${JSON.stringify(value)}`),
+        ],
+});

package/lib/schema/declarations/Declaration.d.ts

@@ -0,0 +1,44 @@
+import { BaseNode, GetReferences, Node, Serializer } from "../Node.js";
+import { SerializedTypeParameter, TypeParameter } from "../parameters/TypeParameter.js";
+import { ObjectType, SerializedObjectType } from "../types/generic/ObjectType.js";
+import { SerializedType, Type } from "../types/Type.js";
+import { ValidatorHelpers } from "../validation/type.js";
+import { EntityDecl, SerializedEntityDecl } from "./EntityDecl.js";
+import { EnumDecl, SerializedEnumDecl } from "./EnumDecl.js";
+import { SerializedTypeAliasDecl, TypeAliasDecl } from "./TypeAliasDecl.js";
+export type TypeArguments<Params extends TypeParameter[]> = {
+    [K in keyof Params]: Params[K] extends TypeParameter<string, infer T> ? T : Type;
+};
+export type SerializedTypeArguments<Params extends SerializedTypeParameter[]> = {
+    [K in keyof Params]: Params[K] extends SerializedTypeParameter<string, infer T> ? T : Type;
+};
+export declare const getParameterNames: (decl: Decl) => string[];
+export declare const getTypeArgumentsRecord: <Params extends TypeParameter[]>(decl: DeclP<Params>, args: TypeArguments<Params>) => Record<string, Type>;
+export type Decl = EntityDecl | EnumDecl | TypeAliasDecl;
+export type SerializedDecl = SerializedEntityDecl | SerializedEnumDecl | SerializedTypeAliasDecl;
+export type DeclP<Params extends TypeParameter[] = TypeParameter[]> = EntityDecl<string, ObjectType> | EnumDecl<string, Record<string, Type | null>, Params> | TypeAliasDecl<string, Type, Params>;
+export type SerializedDeclP<Params extends SerializedTypeParameter[] = SerializedTypeParameter[]> = SerializedEntityDecl<string, SerializedObjectType> | SerializedEnumDecl<string, Record<string, SerializedType | null>, Params> | SerializedTypeAliasDecl<string, SerializedType, Params>;
+export type SecondaryDecl = EnumDecl | TypeAliasDecl;
+export type SerializedSecondaryDecl = SerializedEnumDecl | SerializedTypeAliasDecl;
+export declare const getNestedDeclarations: GetNestedDeclarations;
+export type GetNestedDeclarations<T extends Node = Node> = (isDeclarationAdded: (decl: Decl) => boolean, node: T) => Decl[];
+export declare const isDecl: (node: Node) => node is Decl;
+export interface BaseDecl<Name extends string = string, Params extends TypeParameter[] = TypeParameter[]> extends BaseNode {
+    sourceUrl: string;
+    name: Name;
+    comment?: string;
+    parameters: Params;
+}
+export interface SerializedBaseDecl<Name extends string = string, Params extends SerializedTypeParameter[] = SerializedTypeParameter[]> extends BaseNode {
+    sourceUrl: string;
+    name: Name;
+    comment?: string;
+    parameters: Params;
+}
+export declare const validateDecl: (helpers: ValidatorHelpers, decl: Decl, args: Type[], value: unknown) => Error[];
+export declare const validateDeclName: (name: string) => void;
+export declare const resolveTypeArgumentsInDecl: <Params extends TypeParameter[]>(decl: DeclP<Params>, args: TypeArguments<Params>) => DeclP<[]>;
+export declare const isDeclWithoutTypeParameters: (decl: Decl) => decl is DeclP<[]>;
+export declare const resolveTypeArgumentsInDecls: (decls: readonly Decl[]) => DeclP<[]>[];
+export declare const serializeDecl: Serializer<Decl, SerializedDecl>;
+export declare const getReferencesForDecl: GetReferences<Decl>;

package/lib/schema/declarations/Declaration.js

@@ -0,0 +1,98 @@
+import { assertExhaustive } from "../../shared/utils/typeSafety.js";
+import { NodeKind } from "../Node.js";
+import { getNestedDeclarationsInArrayType } from "../types/generic/ArrayType.js";
+import { getNestedDeclarationsInObjectType, } from "../types/generic/ObjectType.js";
+import { getNestedDeclarationsInIncludeIdentifierType } from "../types/references/IncludeIdentifierType.js";
+import { getNestedDeclarationsInNestedEntityMapType } from "../types/references/NestedEntityMapType.js";
+import { getNestedDeclarationsInReferenceIdentifierType } from "../types/references/ReferenceIdentifierType.js";
+import { getNestedDeclarationsInEntityDecl, getReferencesForEntityDecl, isEntityDecl, resolveTypeArgumentsInEntityDecl, serializeEntityDecl, validateEntityDecl, } from "./EntityDecl.js";
+import { getNestedDeclarationsInEnumDecl, getReferencesForEnumDecl, isEnumDecl, resolveTypeArgumentsInEnumDecl, serializeEnumDecl, validateEnumDecl, } from "./EnumDecl.js";
+import { getNestedDeclarationsInTypeAliasDecl, getReferencesForTypeAliasDecl, isTypeAliasDecl, resolveTypeArgumentsInTypeAliasDecl, serializeTypeAliasDecl, validateTypeAliasDecl, } from "./TypeAliasDecl.js";
+export const getParameterNames = (decl) => decl.parameters.map(param => param.name);
+export const getTypeArgumentsRecord = (decl, args) => Object.fromEntries(args.map((arg, i) => [decl.parameters[i].name, arg]));
+export const getNestedDeclarations = (isDeclAdded, node) => {
+    switch (node.kind) {
+        case NodeKind.EntityDecl:
+            return isDeclAdded(node) ? [] : getNestedDeclarationsInEntityDecl(isDeclAdded, node);
+        case NodeKind.EnumDecl:
+            return isDeclAdded(node) ? [] : getNestedDeclarationsInEnumDecl(isDeclAdded, node);
+        case NodeKind.TypeAliasDecl:
+            return isDeclAdded(node) ? [] : getNestedDeclarationsInTypeAliasDecl(isDeclAdded, node);
+        case NodeKind.ArrayType:
+            return getNestedDeclarationsInArrayType(isDeclAdded, node);
+        case NodeKind.ObjectType:
+            return getNestedDeclarationsInObjectType(isDeclAdded, node);
+        case NodeKind.BooleanType:
+        case NodeKind.DateType:
+        case NodeKind.FloatType:
+        case NodeKind.IntegerType:
+        case NodeKind.StringType:
+        case NodeKind.GenericArgumentIdentifierType:
+            return [];
+        case NodeKind.ReferenceIdentifierType:
+            return getNestedDeclarationsInReferenceIdentifierType(isDeclAdded, node);
+        case NodeKind.IncludeIdentifierType:
+            return getNestedDeclarationsInIncludeIdentifierType(isDeclAdded, node);
+        case NodeKind.NestedEntityMapType:
+            return getNestedDeclarationsInNestedEntityMapType(isDeclAdded, node);
+        default:
+            return assertExhaustive(node);
+    }
+};
+export const isDecl = (node) => isEntityDecl(node) || isEnumDecl(node) || isTypeAliasDecl(node);
+export const validateDecl = (helpers, decl, args, value) => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return validateEntityDecl(helpers, decl, value);
+        case NodeKind.EnumDecl:
+            return validateEnumDecl(helpers, decl, args, value);
+        case NodeKind.TypeAliasDecl:
+            return validateTypeAliasDecl(helpers, decl, args, value);
+        default:
+            return assertExhaustive(decl);
+    }
+};
+const declNamePattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const validateDeclName = (name) => {
+    if (!declNamePattern.test(name)) {
+        throw new Error(`Invalid declaration name "${name}". Declaration names must match the pattern ${declNamePattern.toString()}.`);
+    }
+};
+export const resolveTypeArgumentsInDecl = (decl, args) => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return resolveTypeArgumentsInEntityDecl(decl);
+        case NodeKind.EnumDecl:
+            return resolveTypeArgumentsInEnumDecl(decl, args);
+        case NodeKind.TypeAliasDecl:
+            return resolveTypeArgumentsInTypeAliasDecl(decl, args);
+        default:
+            return assertExhaustive(decl);
+    }
+};
+export const isDeclWithoutTypeParameters = (decl) => decl.parameters.length === 0;
+export const resolveTypeArgumentsInDecls = (decls) => decls.filter(isDeclWithoutTypeParameters).map(decl => resolveTypeArgumentsInDecl(decl, []));
+export const serializeDecl = decl => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return serializeEntityDecl(decl);
+        case NodeKind.EnumDecl:
+            return serializeEnumDecl(decl);
+        case NodeKind.TypeAliasDecl:
+            return serializeTypeAliasDecl(decl);
+        default:
+            return assertExhaustive(decl);
+    }
+};
+export const getReferencesForDecl = (decl, value) => {
+    switch (decl.kind) {
+        case NodeKind.EntityDecl:
+            return getReferencesForEntityDecl(decl, value);
+        case NodeKind.EnumDecl:
+            return getReferencesForEnumDecl(decl, value);
+        case NodeKind.TypeAliasDecl:
+            return getReferencesForTypeAliasDecl(decl, value);
+        default:
+            return assertExhaustive(decl);
+    }
+};

package/lib/schema/declarations/EntityDecl.d.ts

@@ -0,0 +1,73 @@
+import { Lazy } from "../../utils/lazy.js";
+import { Leaves } from "../../utils/object.js";
+import { GetReferences, Node, NodeKind, Serializer } from "../Node.js";
+import { MemberDecl, ObjectType, SerializedObjectType } from "../types/generic/ObjectType.js";
+import { StringType } from "../types/primitives/StringType.js";
+import { AsType, SerializedAsType, Type } from "../types/Type.js";
+import { ValidatorHelpers } from "../validation/type.js";
+import { BaseDecl, GetNestedDeclarations, SerializedBaseDecl } from "./Declaration.js";
+import { TypeAliasDecl } from "./TypeAliasDecl.js";
+export interface EntityDecl<Name extends string = string, T extends ObjectType = ObjectType> extends BaseDecl<Name, []> {
+    kind: NodeKind["EntityDecl"];
+    type: Lazy<T>;
+    /**
+     * @default "name"
+     */
+    displayName?: Leaves<AsType<T>> | {
+        /**
+         * @default "translations"
+         */
+        pathToLocaleMap?: Leaves<AsType<T>>;
+        /**
+         * @default "name"
+         */
+        pathInLocaleMap?: string;
+    };
+}
+export interface SerializedEntityDecl<Name extends string = string, T extends SerializedObjectType = SerializedObjectType> extends SerializedBaseDecl<Name, []> {
+    kind: NodeKind["EntityDecl"];
+    type: T;
+    /**
+     * @default "name"
+     */
+    displayName?: Leaves<SerializedAsType<T>> | {
+        /**
+         * @default "translations"
+         */
+        pathToLocaleMap?: Leaves<SerializedAsType<T>>;
+        /**
+         * @default "name"
+         */
+        pathInLocaleMap?: string;
+    };
+}
+export declare const EntityDecl: <Name extends string, T extends ObjectType>(sourceUrl: string, options: {
+    name: Name;
+    comment?: string;
+    type: () => T;
+    /**
+     * @default "name"
+     */
+    displayName?: Leaves<AsType<T>> | {
+        /**
+         * @default "translations"
+         */
+        pathToLocaleMap?: Leaves<AsType<T>>;
+        /**
+         * @default "name"
+         */
+        pathInLocaleMap?: string;
+    };
+}) => EntityDecl<Name, T>;
+export { EntityDecl as Entity };
+export declare const isEntityDecl: (node: Node) => node is EntityDecl;
+export declare const getNestedDeclarationsInEntityDecl: GetNestedDeclarations<EntityDecl>;
+export declare const validateEntityDecl: (helpers: ValidatorHelpers, decl: EntityDecl, value: unknown) => Error[];
+export declare const resolveTypeArgumentsInEntityDecl: (decl: EntityDecl) => EntityDecl;
+export declare const addEphemeralUUIDToType: <T extends Record<string, MemberDecl<Type, boolean>>>(decl: EntityDecl<string, ObjectType<T>>) => ObjectType<Omit<T, "id"> & {
+    id: MemberDecl<StringType, true>;
+}>;
+export declare const createEntityIdentifierType: () => StringType;
+export declare const createEntityIdentifierTypeAsDecl: <Name extends string>(decl: EntityDecl<Name, ObjectType>) => TypeAliasDecl<`${Name}_ID`, StringType, []>;
+export declare const serializeEntityDecl: Serializer<EntityDecl, SerializedEntityDecl>;
+export declare const getReferencesForEntityDecl: GetReferences<EntityDecl>;