tsondb 0.21.1 → 0.21.2

package/dist/src/node/config.d.ts

@@ -1,7 +1,7 @@
 import type { FormatterOptions as MarkdownFormatterOptions } from "@elyukai/markdown/format";
 import type { DefaultTSONDBTypes, ValidationOptions } from "./index.ts";
 import type { Output } from "./output.ts";
-import type { EntityDecl } from "./schema/dsl/index.ts";
+import type { EntityDecl, SingletonEntityDecl } from "./schema/dsl/index.ts";
 import type { Schema } from "./schema/index.ts";
 /**
  * The main configuration type for TSONDB.
@@ -33,7 +33,7 @@ export type ServerOptions = {
 export type HomeLayoutSection = {
     title: string;
     comment?: string;
-    entities: EntityDecl[];
+    entities: (EntityDecl | SingletonEntityDecl)[];
 };
 /**
  * The configuration type required for generation commands.

package/dist/src/node/git.d.ts

@@ -1,6 +1,6 @@
 import type { SimpleGit } from "simple-git";
 import type { InstanceContainerOverview } from "../shared/utils/instances.ts";
-import type { DefaultTSONDBTypes, EntityName, TSONDB } from "./index.ts";
+import type { DefaultTSONDBTypes, StoringEntityName, TSONDB } from "./index.ts";
 import type { DatabaseInMemory } from "./utils/databaseInMemory.ts";
 export declare class Git<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
     #private;
@@ -36,7 +36,7 @@ export declare class Git<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      *
      * @throws {HTTPError} when no git repository is found
      */
-    stage(entity?: EntityName<T>, id?: string): Promise<void>;
+    stage(entity?: StoringEntityName<T>, id?: string): Promise<void>;
     /**
      * Removes files from the git staging area.
      *
@@ -46,7 +46,7 @@ export declare class Git<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      *
      * @throws {HTTPError} when no git repository is found
      */
-    unstage(entity?: EntityName<T>, id?: string): Promise<void>;
+    unstage(entity?: StoringEntityName<T>, id?: string): Promise<void>;
     /**
      * Restores files in the git repository to their last committed state.
      *
@@ -56,7 +56,7 @@ export declare class Git<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      *
      * @throws {HTTPError} when no git repository is found
      */
-    restore(entity?: EntityName<T>, id?: string): Promise<void>;
+    restore(entity?: StoringEntityName<T>, id?: string): Promise<void>;
     /**
      * Commits staged changes to the git repository with the provided commit message.
      *

package/dist/src/node/index.d.ts

@@ -1,23 +1,27 @@
-import type { InstanceContainer, InstanceContainerOverview } from "../shared/utils/instances.ts";
+import type { InstanceContainer, InstanceContainerOverview, SingletonInstanceContainer } from "../shared/utils/instances.ts";
 import type { FormatterOptions } from "./config.ts";
 import { Git } from "./git.js";
 import type { Output } from "./output.ts";
 import { type EntityDecl } from "./schema/dsl/index.ts";
-import type { AnyChildEntityMap, AnyEntityMap, AnyEnumMap, AnyTypeAliasMap } from "./schema/generatedTypeHelpers.ts";
+import type { AnyChildEntityMap, AnyEntityMap, AnyEnumMap, AnySingletonEntityMap, AnyTypeAliasMap } from "./schema/generatedTypeHelpers.ts";
 import { type IdArgsVariant } from "./schema/generatedTypeHelpers.ts";
 import type { Schema } from "./schema/index.ts";
 import { Transaction } from "./transaction.ts";
 export interface DefaultTSONDBTypes {
     entityMap: AnyEntityMap;
+    singletonEntityMap: AnySingletonEntityMap;
     childEntityMap: AnyChildEntityMap;
     enumMap: AnyEnumMap;
     typeAliasMap: AnyTypeAliasMap;
 }
 export type Entity<T extends DefaultTSONDBTypes, E extends EntityName<T>> = T["entityMap"][E];
 export type EntityName<T extends DefaultTSONDBTypes> = Extract<keyof T["entityMap"], string>;
+export type SingletonEntity<T extends DefaultTSONDBTypes, E extends SingletonEntityName<T>> = T["singletonEntityMap"][E];
+export type SingletonEntityName<T extends DefaultTSONDBTypes> = Extract<keyof T["singletonEntityMap"], string>;
 export type EnumName<T extends DefaultTSONDBTypes> = Extract<keyof T["enumMap"], string>;
 export type TypeAliasName<T extends DefaultTSONDBTypes> = Extract<keyof T["typeAliasMap"], string>;
-export type DeclarationName<T extends DefaultTSONDBTypes> = EntityName<T> | EnumName<T> | TypeAliasName<T>;
+export type StoringEntityName<T extends DefaultTSONDBTypes> = EntityName<T> | SingletonEntityName<T>;
+export type DeclarationName<T extends DefaultTSONDBTypes> = EntityName<T> | SingletonEntityName<T> | EnumName<T> | TypeAliasName<T>;
 export type ChildEntity<T extends DefaultTSONDBTypes, E extends ChildEntityName<T>> = T["childEntityMap"][E][0];
 export type ChildEntityConfig<T extends DefaultTSONDBTypes, E extends ChildEntityName<T>> = T["childEntityMap"][E];
 export type ChildEntityName<T extends DefaultTSONDBTypes> = Extract<keyof T["childEntityMap"], string>;
@@ -148,7 +152,7 @@ export declare class TSONDB<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      * The provided function is called with a `Transaction` object, which can be used to create, update, or delete instances. If an error is thrown during the execution of the function, the transaction is rolled back and no changes are made to the database.
      * @throws {Error} when the transaction could not be completed
      */
-    runTransaction<R>(fn: (transaction: Transaction<T["entityMap"]>) => [Transaction<T["entityMap"]>, R]): Promise<R>;
+    runTransaction<R>(fn: (transaction: Transaction<T["entityMap"], T["singletonEntityMap"]>) => [Transaction<T["entityMap"], T["singletonEntityMap"]>, R]): Promise<R>;
     /**
      * Creates a new instance in the database.
      *
@@ -168,6 +172,25 @@ export declare class TSONDB<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      * @throws {Error} when the instance could not be deleted
      */
     deleteInstance<E extends EntityName<T>>(entityName: E, id: string): Promise<Entity<T, E>>;
+    /**
+     * Creates a new singleton instance in the database.
+     *
+     * If the instance is of the locale entity, a locale identifier must be provided as `id`.
+     * @throws {Error} when the instance could not be created
+     */
+    createSingletonInstance<E extends SingletonEntityName<T>>(entityName: E, content: SingletonEntity<T, E>): Promise<SingletonInstanceContainer<SingletonEntity<T, E>>>;
+    /**
+     * Updates a singleton instance in the database.
+     *
+     * @throws {Error} when the instance could not be updated
+     */
+    updateSingletonInstance<E extends SingletonEntityName<T>>(entityName: E, content: SingletonEntity<T, E>): Promise<SingletonInstanceContainer<SingletonEntity<T, E>>>;
+    /**
+     * Deletes a singleton instance in the database.
+     *
+     * @throws {Error} when the instance could not be deleted
+     */
+    deleteSingletonInstance<E extends SingletonEntityName<T>>(entityName: E): Promise<SingletonEntity<T, E>>;
     /**
      * Retrieves an instance of the specified entity by its identifier.
      */
@@ -192,10 +215,22 @@ export declare class TSONDB<T extends DefaultTSONDBTypes = DefaultTSONDBTypes> {
      * Retrieves all instance overviews of the specified entity.
      */
     getAllInstanceOverviewsOfEntity(entity: EntityDecl<EntityName<T>> | EntityName<T>): InstanceContainerOverview[];
+    /**
+     * Retrieves an instance of the specified entity by its identifier.
+     */
+    getSingletonInstanceOfEntity<E extends SingletonEntityName<T>>(entityName: E): T["singletonEntityMap"][E] | undefined;
+    /**
+     * Retrieves the instance container of the specified entity by its identifier.
+     */
+    getSingletonInstanceContainerOfEntity<E extends SingletonEntityName<T>>(entityName: E): SingletonInstanceContainer<T["singletonEntityMap"][E]> | undefined;
     /**
      * Counts the number of instances registered for the specified entity.
      */
     countInstancesOfEntity(entityName: EntityName<T>): number;
+    /**
+     * Returns whether the singleton entity has an instance.
+     */
+    hasInstanceOfSingletonEntity(entityName: SingletonEntityName<T>): boolean;
     /**
      * Retrieves overviews for all instances in the database, grouped by entity name.
      */

package/dist/src/node/index.js

@@ -1,19 +1,22 @@
 import { on } from "@elyukai/utils/function";
 import { Lazy } from "@elyukai/utils/lazy";
+import { nullableToArray } from "@elyukai/utils/nullable";
 import { compareNumber, reduceCompare } from "@elyukai/utils/ordering";
 import { isError } from "@elyukai/utils/result";
+import { assertExhaustive } from "@elyukai/utils/typeSafety";
 import Debug from "debug";
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, sep } from "node:path";
 import { stderr } from "node:process";
 import { styleText } from "node:util";
 import { simpleGit } from "simple-git";
+import { NodeKind } from "../shared/schema/Node.js";
 import { parallelizeErrors } from "../shared/utils/validation.js";
 import { Git } from "./git.js";
 import { getDisplayName, getDisplayNameWithId } from "./schema/detached.js";
 import {} from "./schema/dsl/index.js";
 import {} from "./schema/generatedTypeHelpers.js";
-import { isEntityDeclWithParentReference } from "./schema/guards.js";
+import { isEntityDecl, isEntityDeclWithParentReference } from "./schema/guards.js";
 import { serializeNode } from "./schema/treeOperations/serialization.js";
 import { createEntityNameValidator, createReferenceValidator, validateDeclReferentialIntegrity, validateDeclStructuralIntegrity, } from "./schema/treeOperations/validation.js";
 import { Transaction } from "./transaction.js";
@@ -22,7 +25,7 @@ import { DatabaseInMemory } from "./utils/databaseInMemory.js";
 import { applyStepsToDisk } from "./utils/databaseOnDisk.js";
 import { getAllInstanceOverviewsByEntityName, getDisplayNameFromEntityInstance, getInstanceOverview, getInstanceOverviewsByEntityName, } from "./utils/displayName.js";
 import { countError, countErrors, getErrorMessageForDisplay, HTTPError, wrapErrorsIfAny, } from "./utils/error.js";
-import { formatInstance, getFileNameForId, readInstance, writeInstance } from "./utils/files.js";
+import { formatInstance, getFileNameForId, getSingletonFileName, readInstance, readSingletonInstance, writeInstance, writeSingletonInstance, } from "./utils/files.js";
 import { attachGitStatusToDatabaseInMemory } from "./utils/git.js";
 import { getReferencesToInstances, isReferencedByOtherInstances, } from "./utils/references.js";
 import { checkUniqueConstraintsForAllEntities } from "./utils/unique.js";
@@ -64,7 +67,7 @@ const checkLocales = (schema, data, locales) => {
 };
 const initData = async (dataRootPath, schema, locales, git, gitStatus, skipReferenceCache) => {
     debug("loading database into memory ...");
-    let data = await DatabaseInMemory.load(dataRootPath, schema.entities);
+    let data = await DatabaseInMemory.load(dataRootPath, schema.entities, schema.singletonEntities);
     debug("done");
     checkLocales(schema, data, locales);
     const serializedDeclarationsByName = Object.fromEntries(schema.resolvedDeclarations.map(decl => [decl.name, serializeNode(decl)]));
@@ -172,7 +175,7 @@ export class TSONDB {
     #validate(data, options = {}) {
         const { checkReferentialIntegrity, checkOnlyEntities } = this.#validationOptions;
         const { skipStructuralValidation = false, logToConsole = true, changedEntities: changedEntityNames, } = options;
-        const entities = this.#schema.entities;
+        const entities = [...this.#schema.entities, ...this.#schema.singletonEntities];
         const getEntity = this.#schema.getEntity.bind(this.#schema);
         for (const onlyEntity of checkOnlyEntities) {
             if (!entities.find(entity => entity.name === onlyEntity)) {
@@ -193,9 +196,23 @@ export class TSONDB {
         if (!skipStructuralValidation) {
             debug("Checking structural integrity ...");
             const structureErrors = onlyEntities
-                .flatMap(entity => parallelizeErrors(data
-                .getAllInstanceContainersOfEntity(entity.name)
-                .map(instance => wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", join(entity.name, getFileNameForId(instance.id)))}"`)}`, validateDeclStructuralIntegrity(validationContext, [], entity, [], instance.content)))))
+                .flatMap(entity => {
+                switch (entity.kind) {
+                    case NodeKind.EntityDecl:
+                        return parallelizeErrors(data
+                            .getAllInstanceContainersOfEntity(entity.name)
+                            .map(instance => wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", join(entity.name, getFileNameForId(instance.id)))}"`)}`, validateDeclStructuralIntegrity(validationContext, [], entity, [], instance.content))));
+                    case NodeKind.SingletonEntityDecl: {
+                        const instance = data.getSingletonInstanceContainerOfEntity(entity.name);
+                        if (instance) {
+                            return nullableToArray(wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", getSingletonFileName(entity.name))}"`)}`, validateDeclStructuralIntegrity(validationContext, [], entity, [], instance.content)));
+                        }
+                        return [];
+                    }
+                    default:
+                        return assertExhaustive(entity);
+                }
+            })
                 .toSorted((a, b) => a.message.localeCompare(b.message));
             if (structureErrors.length > 0) {
                 const errorCount = countErrors(structureErrors);
@@ -213,9 +230,23 @@ export class TSONDB {
                     const entityNameValidator = createEntityNameValidator(this.#schema.isEntityName.bind(this.#schema), true);
                     const referenceValidator = createReferenceValidator(this.#schema.isEntityName.bind(this.#schema), data, true);
                     const referenceErrors = onlyEntities
-                        .flatMap(entity => parallelizeErrors(data
-                        .getAllInstanceContainersOfEntity(entity.name)
-                        .map(instance => wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", join(entity.name, getFileNameForId(instance.id)))}"`)}`, validateDeclReferentialIntegrity(validationContext, entityNameValidator, referenceValidator, [], entity, [], instance.content)))))
+                        .flatMap(entity => {
+                        switch (entity.kind) {
+                            case NodeKind.EntityDecl:
+                                return parallelizeErrors(data
+                                    .getAllInstanceContainersOfEntity(entity.name)
+                                    .map(instance => wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", join(entity.name, getFileNameForId(instance.id)))}"`)}`, validateDeclReferentialIntegrity(validationContext, entityNameValidator, referenceValidator, [], entity, [], instance.content))));
+                            case NodeKind.SingletonEntityDecl: {
+                                const instance = data.getSingletonInstanceContainerOfEntity(entity.name);
+                                if (instance) {
+                                    return nullableToArray(wrapErrorsIfAny(`in file ${styleText("white", `"${this.#dataRootPath}${sep}${styleText("bold", getSingletonFileName(entity.name))}"`)}`, validateDeclReferentialIntegrity(validationContext, entityNameValidator, referenceValidator, [], entity, [], instance.content)));
+                                }
+                                return [];
+                            }
+                            default:
+                                return assertExhaustive(entity);
+                        }
+                    })
                         .toSorted((a, b) => a.message.localeCompare(b.message));
                     if (referenceErrors.length > 0) {
                         const errorCount = countErrors(referenceErrors);
@@ -232,7 +263,7 @@ export class TSONDB {
             }
             debug("Checking unique constraints ...");
             const instanceOverviewsByEntityName = getAllInstanceOverviewsByEntityName(getEntity, data, this.#locales);
-            const uniqueConstraintResult = checkUniqueConstraintsForAllEntities(data, changedEntities ?? onlyEntities, instanceOverviewsByEntityName);
+            const uniqueConstraintResult = checkUniqueConstraintsForAllEntities(data, (changedEntities ?? onlyEntities).filter(e => isEntityDecl(e)), instanceOverviewsByEntityName);
             if (isError(uniqueConstraintResult)) {
                 const errorCount = countError(uniqueConstraintResult.error);
                 debug(`${errorCount.toString()} unique constraint violation${errorCount === 1 ? "" : "s"} found`);
@@ -286,6 +317,11 @@ export class TSONDB {
             const entity = this.#schema.getEntity(entityName);
             await writeInstance(this.#dataRootPath, entity, instance.id, instance.content, this.#formatterOptions);
         }, true);
+        await this.#data.forEachSingletonInstance(async (entityName, instance) => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const entity = this.#schema.getSingletonEntity(entityName);
+            await writeSingletonInstance(this.#dataRootPath, entity, instance.content, this.#formatterOptions);
+        }, true);
         debug("All data is formatted");
     }
     /**
@@ -306,6 +342,17 @@ export class TSONDB {
             }
             total++;
         }, true);
+        await this.#data.forEachSingletonInstance(async (entityName, instance) => {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            const entity = this.#schema.getSingletonEntity(entityName);
+            const instanceOnDisk = await readSingletonInstance(this.#dataRootPath, entity);
+            const currentFormatted = formatInstance(entity, instance.content, this.#formatterOptions);
+            if (instanceOnDisk !== currentFormatted) {
+                console.log(`Singleton instance of entity ${styleText("cyan", entityName)} is not formatted correctly.`);
+                counter++;
+            }
+            total++;
+        }, true);
         if (counter === 0) {
             console.log(styleText("green", `All ${total.toFixed()} instance${total === 1 ? "" : "s"} are formatted correctly`));
             return true;
@@ -342,9 +389,11 @@ export class TSONDB {
         this.#locked = true;
         try {
             const getEntity = this.#schema.getEntity.bind(this.#schema);
+            const getSingletonEntity = this.#schema.getSingletonEntity.bind(this.#schema);
             const [txn, res] = fn(new Transaction({
                 data: this.#data,
                 getEntity,
+                getSingletonEntity,
                 referencesToInstances: this.#referencesToInstances,
                 validate: this.#strucurallyValidateInstance.bind(this),
                 localeEntity: this.#schema.localeEntity,
@@ -426,6 +475,40 @@ export class TSONDB {
         txn.deleteInstance(this.#schema.getEntity(entityName), id));
         return res.content;
     }
+    /**
+     * Creates a new singleton instance in the database.
+     *
+     * If the instance is of the locale entity, a locale identifier must be provided as `id`.
+     * @throws {Error} when the instance could not be created
+     */
+    async createSingletonInstance(entityName, content) {
+        const res = await this.runTransaction(txn => 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        txn.createSingletonInstance(this.#schema.getSingletonEntity(entityName), content));
+        return res;
+    }
+    /**
+     * Updates a singleton instance in the database.
+     *
+     * @throws {Error} when the instance could not be updated
+     */
+    async updateSingletonInstance(entityName, content) {
+        const res = await this.runTransaction(txn => 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        txn.updateSingletonInstance(this.#schema.getSingletonEntity(entityName), content));
+        return res;
+    }
+    /**
+     * Deletes a singleton instance in the database.
+     *
+     * @throws {Error} when the instance could not be deleted
+     */
+    async deleteSingletonInstance(entityName) {
+        const res = await this.runTransaction(txn => 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        txn.deleteSingletonInstance(this.#schema.getSingletonEntity(entityName)));
+        return res.content;
+    }
     /**
      * Retrieves an instance of the specified entity by its identifier.
      */
@@ -466,12 +549,30 @@ export class TSONDB {
         }
         return getInstanceOverviewsByEntityName(this.getInstanceContainerOfEntityById.bind(this), this.getAllChildInstanceContainersForParent.bind(this), this.#schema.getEntity.bind(this.#schema), normEntity, this.getAllInstanceContainersOfEntity(normEntity.name), this.#locales);
     }
+    /**
+     * Retrieves an instance of the specified entity by its identifier.
+     */
+    getSingletonInstanceOfEntity(entityName) {
+        return this.#data.getSingletonInstanceOfEntity(entityName);
+    }
+    /**
+     * Retrieves the instance container of the specified entity by its identifier.
+     */
+    getSingletonInstanceContainerOfEntity(entityName) {
+        return this.#data.getSingletonInstanceContainerOfEntity(entityName);
+    }
     /**
      * Counts the number of instances registered for the specified entity.
      */
     countInstancesOfEntity(entityName) {
         return this.#data.countInstancesOfEntity(entityName);
     }
+    /**
+     * Returns whether the singleton entity has an instance.
+     */
+    hasInstanceOfSingletonEntity(entityName) {
+        return this.#data.hasInstanceOfSingletonEntity(entityName);
+    }
     /**
      * Retrieves overviews for all instances in the database, grouped by entity name.
      */

package/dist/src/node/renderers/jsonschema/render.js

@@ -156,6 +156,11 @@ const renderEntityDecl = (options, decl) => ({
     deprecated: decl.isDeprecated,
     ...renderType(options, addEphemeralUUIDToType(decl)),
 });
+const renderSingletonEntityDecl = (options, decl) => ({
+    description: decl.comment,
+    deprecated: decl.isDeprecated,
+    ...renderType(options, decl.type.value),
+});
 const renderEnumDecl = (options, decl) => ({
     description: decl.comment,
     deprecated: decl.isDeprecated,
@@ -170,6 +175,8 @@ const renderDecl = (options, decl) => {
     switch (decl.kind) {
         case NodeKind.EntityDecl:
             return renderEntityDecl({ ...options, parentDecl: decl }, decl);
+        case NodeKind.SingletonEntityDecl:
+            return renderSingletonEntityDecl({ ...options, parentDecl: decl }, decl);
         case NodeKind.EnumDecl:
             return renderEnumDecl({ ...options, parentDecl: decl }, decl);
         case NodeKind.TypeAliasDecl:

package/dist/src/node/renderers/ts/render.d.ts

@@ -8,6 +8,10 @@ export type TypeScriptRendererOptions = {
          * If `true` or a string, generates an object type with all names of the entities as the key and their corresponding generated type as their respective value. Uses `EntityMap` as a default name when using `true` or the string if set to a string.
          */
         entityMap: boolean | string;
+        /**
+         * If `true` or a string, generates an object type with all names of the singleton entities as the key and their corresponding generated type as their respective value. Uses `SingletonEntityMap` as a default name when using `true` or the string if set to a string.
+         */
+        singletonEntityMap: boolean | string;
         /**
          * If `true` or a string, generates an object type with all names of entities with parent references as the key and their corresponding generated type as well as their parent reference key as their respective value. Uses `ChildEntityMap` as a default name when using `true` or the string if set to a string.
          */

package/dist/src/node/renderers/ts/render.js

@@ -9,6 +9,7 @@ import { extractParameterTypeNamesFromMessage, mapParameterTypeNames, } from "..
 import { asDecl } from "../../schema/dsl/declarations/Decl.js";
 import { addEphemeralUUIDToType, createEntityIdentifierTypeAsDecl, isEntityDecl, isEntityDeclWithParentReference, } from "../../schema/dsl/declarations/EntityDecl.js";
 import { isEnumDecl } from "../../schema/dsl/declarations/EnumDecl.js";
+import { isSingletonEntityDecl, } from "../../schema/dsl/declarations/SingletonEntityDecl.js";
 import { isTypeAliasDecl, TypeAliasDecl } from "../../schema/dsl/declarations/TypeAliasDecl.js";
 import { isNestedEntityMapType } from "../../schema/dsl/types/NestedEntityMapType.js";
 import { isObjectType } from "../../schema/dsl/types/ObjectType.js";
@@ -148,6 +149,7 @@ const renderType = (options, type) => {
     }
 };
 const renderEntityDecl = (options, decl) => syntax `${renderDocumentation(decl.comment, decl.isDeprecated)}export ${options.objectTypeKeyword} ${decl.name} ${options.objectTypeKeyword === "type" ? "= " : ""}${renderType(options, options.addIdentifierToEntities ? addEphemeralUUIDToType(decl) : decl.type.value)}`;
+const renderSingletonEntityDecl = (options, decl) => syntax `${renderDocumentation(decl.comment, decl.isDeprecated)}export ${options.objectTypeKeyword} ${decl.name} ${options.objectTypeKeyword === "type" ? "= " : ""}${renderType(options, decl.type.value)}`;
 const renderEnumDecl = (options, decl) => syntax `${renderDocumentation(decl.comment, decl.isDeprecated)}export type ${decl.name}${renderTypeParameters(options, decl.parameters)} =${renderEnumType(options, decl.type.value)}`;
 const renderTypeAliasDecl = (options, decl) => isObjectType(decl.type.value)
     ? syntax `${renderDocumentation(decl.comment, decl.isDeprecated)}export ${options.objectTypeKeyword} ${decl.name}${renderTypeParameters(options, decl.parameters)} ${options.objectTypeKeyword === "type" ? "= " : ""}${renderType(options, decl.type.value)}`
@@ -156,6 +158,8 @@ const renderDecl = (options, decl) => {
     switch (decl.kind) {
         case NodeKind.EntityDecl:
             return renderEntityDecl(options, decl);
+        case NodeKind.SingletonEntityDecl:
+            return renderSingletonEntityDecl(options, decl);
         case NodeKind.EnumDecl:
             return renderEnumDecl(options, decl);
         case NodeKind.TypeAliasDecl:
@@ -193,6 +197,7 @@ const renderMapHelperType = (options, declarations, key, defaultName, filterFn,
         : "";
 };
 const renderEntityMapType = (options, declarations) => renderMapHelperType(options, declarations, "entityMap", "EntityMap", isEntityDecl);
+const renderSingletonEntityMapType = (options, declarations) => renderMapHelperType(options, declarations, "singletonEntityMap", "SingletonEntityMap", isSingletonEntityDecl);
 const renderChildEntityMapType = (options, declarations) => renderMapHelperType(options, declarations, "childEntityMap", "ChildEntityMap", decl => isEntityDecl(decl) && isEntityDeclWithParentReference(decl), decl => `${decl.name}: [${decl.name}, "${decl.parentReferenceKey}", ${decl.name}["${decl.parentReferenceKey}"]]`);
 const renderEnumMapType = (options, declarations) => renderMapHelperType(options, declarations, "enumMap", "EnumMap", isEnumDecl);
 const renderTypeAliasMapType = (options, declarations) => renderMapHelperType(options, declarations, "typeAliasMap", "TypeAliasMap", isTypeAliasDecl);
@@ -255,6 +260,7 @@ export const render = (options = defaultOptions, declarations) => {
         return undefined;
     }, declarations));
     return (renderEntityMapType(finalOptions, declarations) +
+        renderSingletonEntityMapType(finalOptions, declarations) +
         renderChildEntityMapType(finalOptions, declarations) +
         renderEnumMapType(finalOptions, declarations) +
         renderTypeAliasMapType(finalOptions, declarations) +

package/dist/src/node/schema/dsl/declarations/Decl.d.ts

@@ -5,14 +5,15 @@ import type { EnumCaseDecl } from "../types/EnumType.ts";
 import type { Type } from "../types/Type.ts";
 import type { EntityDecl } from "./EntityDecl.ts";
 import type { EnumDecl } from "./EnumDecl.ts";
+import { type SingletonEntityDecl } from "./SingletonEntityDecl.ts";
 import type { TypeAliasDecl } from "./TypeAliasDecl.ts";
 export type TypeArguments<Params extends TypeParameter[]> = {
     [K in keyof Params]: Params[K] extends TypeParameter<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<Name extends string = string> = EntityDecl<Name> | EnumDecl<Name> | TypeAliasDecl<Name>;
-export type DeclP<Params extends TypeParameter[] = TypeParameter[]> = EntityDecl | EnumDecl<string, Record<string, EnumCaseDecl>, Params> | TypeAliasDecl<string, Type, Params>;
+export type Decl<Name extends string = string> = EntityDecl<Name> | SingletonEntityDecl<Name> | EnumDecl<Name> | TypeAliasDecl<Name>;
+export type DeclP<Params extends TypeParameter[] = TypeParameter[]> = EntityDecl | SingletonEntityDecl | EnumDecl<string, Record<string, EnumCaseDecl>, Params> | TypeAliasDecl<string, Type, Params>;
 export type IncludableDeclP<Params extends TypeParameter[] = TypeParameter[]> = EnumDecl<string, Record<string, EnumCaseDecl>, Params> | TypeAliasDecl<string, Type, Params>;
 export type SecondaryDecl = EnumDecl | TypeAliasDecl;
 export declare const isDecl: (node: Node) => node is Decl;

package/dist/src/node/schema/dsl/declarations/Decl.js

@@ -2,12 +2,13 @@ import { walkTypeNodeTree } from "../../helpers.js";
 import { resolveTypeArguments } from "../../treeOperations/typeResolution.js";
 import { isEntityDecl } from "./EntityDecl.js";
 import { isEnumDecl } from "./EnumDecl.js";
+import { isSingletonEntityDecl } from "./SingletonEntityDecl.js";
 import { isTypeAliasDecl } from "./TypeAliasDecl.js";
 export const getParameterNames = (decl) => decl.parameters.map(param => param.name);
 export const getTypeArgumentsRecord = (decl, args) => Object.fromEntries(
 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 args.slice(0, decl.parameters.length).map((arg, i) => [decl.parameters[i].name, arg]));
-export const isDecl = (node) => isEntityDecl(node) || isEnumDecl(node) || isTypeAliasDecl(node);
+export const isDecl = (node) => isEntityDecl(node) || isSingletonEntityDecl(node) || isEnumDecl(node) || isTypeAliasDecl(node);
 export const asDecl = (node) => node && isDecl(node) ? node : undefined;
 const declNamePattern = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 export const validateDeclName = (name) => {

package/dist/src/node/schema/dsl/declarations/SingletonEntityDecl.d.ts

@@ -0,0 +1,35 @@
+import { Lazy } from "@elyukai/utils/lazy";
+import { NodeKind } from "../../../../shared/schema/Node.ts";
+import type { SortOrder } from "../../../../shared/schema/utils/sortOrder.ts";
+import type { CustomConstraint, TypedCustomConstraint } from "../../../utils/customConstraints.ts";
+import type { Node } from "../index.ts";
+import type { MemberDecl, ObjectType } from "../types/ObjectType.ts";
+import type { BaseDecl } from "./Decl.ts";
+type TConstraint = Record<string, MemberDecl>;
+export interface SingletonEntityDecl<Name extends string = string, T extends TConstraint = TConstraint> extends BaseDecl<Name, []> {
+    kind: NodeKind["SingletonEntityDecl"];
+    /**
+     * Changes the appearance of the entity’s name in singular form.
+     */
+    displayName?: string;
+    type: Lazy<ObjectType<T>>;
+    isDeprecated?: boolean;
+    customConstraints?: CustomConstraint;
+    /**
+     * The order in which instances of an entity are sorted in the editor. This affects entity details pages and reference options.
+     */
+    sortOrder?: SortOrder;
+}
+export declare const SingletonEntityDecl: <Name extends string, T extends TConstraint>(sourceUrl: string, options: {
+    name: Name;
+    /**
+     * Changes the appearance of the entity’s name in singular form.
+     */
+    displayName?: string;
+    comment?: string;
+    type: () => ObjectType<T>;
+    isDeprecated?: boolean;
+    customConstraints?: TypedCustomConstraint<Name>;
+}) => SingletonEntityDecl<Name, T>;
+export { SingletonEntityDecl as SingletonEntity };
+export declare const isSingletonEntityDecl: (node: Node) => node is SingletonEntityDecl;

package/dist/src/node/schema/dsl/declarations/SingletonEntityDecl.js

@@ -0,0 +1,23 @@
+import { Lazy } from "@elyukai/utils/lazy";
+import { NodeKind } from "../../../../shared/schema/Node.js";
+import { validateDeclName } from "./Decl.js";
+export const SingletonEntityDecl = (sourceUrl, options) => {
+    validateDeclName(options.name);
+    return {
+        ...options,
+        kind: NodeKind.SingletonEntityDecl,
+        sourceUrl,
+        parameters: [],
+        type: Lazy.of(() => {
+            const type = options.type();
+            Object.keys(type.properties).forEach(key => {
+                if (key === "id") {
+                    throw new TypeError(`Invalid object key "${key}" for entity "${options.name}". The key "id" is reserved for the entity identifier.`);
+                }
+            });
+            return type;
+        }),
+    };
+};
+export { SingletonEntityDecl as SingletonEntity };
+export const isSingletonEntityDecl = (node) => node.kind === NodeKind.SingletonEntityDecl;

package/dist/src/node/schema/dsl/index.d.ts

@@ -5,6 +5,7 @@ export { Param, TypeParameter } from "./TypeParameter.ts";
 export { type Decl, type DeclP, type IncludableDeclP, type SecondaryDecl, } from "./declarations/Decl.ts";
 export { Entity, EntityDecl, type EntityDeclWithParentReference, type EntityDisplayName, } from "./declarations/EntityDecl.ts";
 export { Enum, EnumDecl, GenEnum, GenEnumDecl } from "./declarations/EnumDecl.ts";
+export { SingletonEntity, SingletonEntityDecl } from "./declarations/SingletonEntityDecl.ts";
 export { GenTypeAlias, GenTypeAliasDecl, TypeAlias, TypeAliasDecl, } from "./declarations/TypeAliasDecl.ts";
 export { Array, ArrayType } from "./types/ArrayType.ts";
 export { Boolean, BooleanType } from "./types/BooleanType.ts";

package/dist/src/node/schema/dsl/index.js

@@ -2,6 +2,7 @@ export { Param, TypeParameter } from "./TypeParameter.js";
 export {} from "./declarations/Decl.js";
 export { Entity, EntityDecl, } from "./declarations/EntityDecl.js";
 export { Enum, EnumDecl, GenEnum, GenEnumDecl } from "./declarations/EnumDecl.js";
+export { SingletonEntity, SingletonEntityDecl } from "./declarations/SingletonEntityDecl.js";
 export { GenTypeAlias, GenTypeAliasDecl, TypeAlias, TypeAliasDecl, } from "./declarations/TypeAliasDecl.js";
 export { Array, ArrayType } from "./types/ArrayType.js";
 export { Boolean, BooleanType } from "./types/BooleanType.js";

package/dist/src/node/schema/generatedTypeHelpers.d.ts

@@ -8,6 +8,7 @@ import type { DisplayNameResult } from "../../shared/utils/displayName.ts";
 import type { InstanceContainer, InstanceContainerOverview, InstanceContent } from "../../shared/utils/instances.ts";
 import type { DeclarationName, DefaultTSONDBTypes } from "../index.ts";
 import type { EntityDecl } from "./dsl/declarations/EntityDecl.ts";
+import type { SingletonEntityDecl } from "./dsl/declarations/SingletonEntityDecl.ts";
 export interface Register {
 }
 export type AnyEntityMap = Record<string, InstanceContent>;
@@ -19,6 +20,15 @@ export type RegisteredEntity<Name extends string, T = Register> = T extends {
         [K in Name]: InstanceContent;
     };
 } ? T["entityMap"][Name] : InstanceContent;
+export type AnySingletonEntityMap = Record<string, InstanceContent>;
+export type RegisteredSingletonEntityMap<T = Register> = T extends {
+    singletonEntityMap: AnySingletonEntityMap;
+} ? T["singletonEntityMap"] : AnySingletonEntityMap;
+export type RegisteredSingletonEntity<Name extends string, T = Register> = T extends {
+    singletonEntityMap: {
+        [K in Name]: InstanceContent;
+    };
+} ? T["singletonEntityMap"][Name] : InstanceContent;
 export type AnyChildEntityMap = Record<string, [
     content: InstanceContent,
     parentKey: string,
@@ -133,6 +143,14 @@ export type GetDisplayNameAndId<T extends AnyEntityMap = RegisteredEntityMap> =
  * A function that retrieves an entity declaration by its name.
  */
 export type GetEntityByName<T extends AnyEntityMap = RegisteredEntityMap> = <E extends Extract<keyof T, string> = Extract<keyof T, string>>(name: E) => EntityDecl<E> | undefined;
+/**
+ * A function that retrieves an entity declaration by its name.
+ */
+export type GetSingletonEntityByName<T extends AnySingletonEntityMap = RegisteredSingletonEntityMap> = <E extends Extract<keyof T, string> = Extract<keyof T, string>>(name: E) => SingletonEntityDecl<E> | undefined;
+/**
+ * A function that retrieves the singleton instance by its entity if available.
+ */
+export type GetSingletonInstance<T extends AnySingletonEntityMap = RegisteredSingletonEntityMap> = <E extends Extract<keyof T, string> = Extract<keyof T, string>>(entity: E) => T[E] | undefined;
 /**
  * A type guard function that checks if a given string is a valid declaration name.
  */

package/dist/src/node/schema/guards.d.ts

@@ -1,6 +1,7 @@
 export { isDecl, isDeclWithoutTypeParameters } from "./dsl/declarations/Decl.ts";
 export { isEntityDecl, isEntityDeclWithParentReference } from "./dsl/declarations/EntityDecl.ts";
 export { isEnumDecl } from "./dsl/declarations/EnumDecl.ts";
+export { isSingletonEntityDecl } from "./dsl/declarations/SingletonEntityDecl.ts";
 export { isTypeAliasDecl } from "./dsl/declarations/TypeAliasDecl.ts";
 export { isArrayType } from "./dsl/types/ArrayType.ts";
 export { isBooleanType } from "./dsl/types/BooleanType.ts";

package/dist/src/node/schema/guards.js

@@ -1,6 +1,7 @@
 export { isDecl, isDeclWithoutTypeParameters } from "./dsl/declarations/Decl.js";
 export { isEntityDecl, isEntityDeclWithParentReference } from "./dsl/declarations/EntityDecl.js";
 export { isEnumDecl } from "./dsl/declarations/EnumDecl.js";
+export { isSingletonEntityDecl } from "./dsl/declarations/SingletonEntityDecl.js";
 export { isTypeAliasDecl } from "./dsl/declarations/TypeAliasDecl.js";
 export { isArrayType } from "./dsl/types/ArrayType.js";
 export { isBooleanType } from "./dsl/types/BooleanType.js";

package/dist/src/node/schema/helpers.js

@@ -12,6 +12,7 @@ export const reduceNodes = (reducer, nodes, options = {}) => {
     const reduceNodeTree = (parentNodes, node, collectedResults, reducedDecls) => {
         switch (node.kind) {
             case NodeKind.EntityDecl:
+            case NodeKind.SingletonEntityDecl:
             case NodeKind.EnumDecl:
             case NodeKind.TypeAliasDecl:
                 return reduceNodeTree([node], node.type.value, reducer(parentNodes, node, collectedResults), [...reducedDecls, node]);