tsondb 0.14.0 → 0.15.0

package/dist/src/node/index.js

@@ -9,7 +9,9 @@ import { validateEntityDecl } from "./schema/declarations/EntityDecl.js";
 import { createValidationContext } from "./schema/Node.js";
 import { getEntities } from "./schema/Schema.js";
 import { createServer } from "./server/index.js";
+import { checkCustomConstraintsForAllEntities } from "./utils/customConstraints.js";
 import { asyncForEachInstanceInDatabaseInMemory, countInstancesInDatabaseInMemory, createDatabaseInMemory, getInstancesOfEntityFromDatabaseInMemory, } from "./utils/databaseInMemory.js";
+import { getAllInstanceOverviewsByEntityName } from "./utils/displayName.js";
 import { countError, countErrors, getErrorMessageForDisplay, wrapErrorsIfAny, } from "./utils/error.js";
 import { getFileNameForId, writeInstance } from "./utils/files.js";
 import { checkUniqueConstraintsForAllEntities } from "./utils/unique.js";
@@ -49,15 +51,27 @@ const _validate = (dataRootPath, entities, databaseInMemory, locales, options =
     }
     if (errors.length === 0) {
         debug("Checking unique constraints ...");
-        const constraintResult = checkUniqueConstraintsForAllEntities(databaseInMemory, Object.fromEntries(entities.map(entity => [entity.name, entity])), locales);
-        if (isError(constraintResult)) {
-            const errorCount = countError(constraintResult.error);
+        const entitiesByName = Object.fromEntries(entities.map(entity => [entity.name, entity]));
+        const instanceOverviewsByEntityName = getAllInstanceOverviewsByEntityName(entitiesByName, databaseInMemory, locales);
+        const uniqueConstraintResult = checkUniqueConstraintsForAllEntities(databaseInMemory, entitiesByName, instanceOverviewsByEntityName);
+        if (isError(uniqueConstraintResult)) {
+            const errorCount = countError(uniqueConstraintResult.error);
             debug(`${errorCount.toString()} unique constraint violation${errorCount === 1 ? "" : "s"} found`);
-            errors.push(constraintResult.error);
+            errors.push(uniqueConstraintResult.error);
         }
         else {
             debug("No unique constraint violations found");
         }
+        debug("Checking custom constraints ...");
+        const customConstraintResult = checkCustomConstraintsForAllEntities(databaseInMemory, entitiesByName, instanceOverviewsByEntityName);
+        if (isError(customConstraintResult)) {
+            const errorCount = countError(customConstraintResult.error);
+            debug(`${errorCount.toString()} custom constraint violation${errorCount === 1 ? "" : "s"} found`);
+            errors.push(customConstraintResult.error);
+        }
+        else {
+            debug("No custom constraint violations found");
+        }
     }
     else {
         debug("Skipping unique constraint checks due to previous structural integrity errors");
@@ -65,7 +79,7 @@ const _validate = (dataRootPath, entities, databaseInMemory, locales, options =
     const totalInstanceCount = countInstancesInDatabaseInMemory(databaseInMemory);
     console.log(`${totalInstanceCount.toString()} instance${totalInstanceCount === 1 ? "" : "s"} checked`);
     if (errors.length === 0) {
-        console.log(styleText("green", "All entities are valid"));
+        console.log(styleText("green", "All instances are valid"));
         return true;
     }
     else {

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

@@ -6,3 +6,4 @@ export interface Schema {
 }
 export declare const Schema: (declarations: Decl[], localeEntity?: EntityDecl) => Schema;
 export declare const getEntities: (schema: Schema) => EntityDecl[];
+export type * from "./externalTypes.ts";

package/dist/src/node/schema/declarations/EntityDecl.d.ts

@@ -1,6 +1,7 @@
 import type { UniqueConstraints } from "../../../shared/schema/declarations/EntityDecl.ts";
 import { Lazy } from "../../../shared/utils/lazy.ts";
-import type { DisplayNameCustomizer } from "../../utils/displayName.ts";
+import type { CustomConstraint, TypedCustomConstraint } from "../../utils/customConstraints.ts";
+import type { DisplayNameCustomizer, TypedDisplayNameCustomizer } from "../../utils/displayName.ts";
 import type { GetNestedDeclarations, GetReferences, Predicate, Serialized, TypeArgumentsResolver, Validator } from "../Node.ts";
 import { NodeKind } from "../Node.ts";
 import type { MemberDecl, ObjectType } from "../types/generic/ObjectType.ts";
@@ -35,9 +36,10 @@ export interface EntityDecl<Name extends string = string, T extends TConstraint
      * @default "name"
      */
     displayName?: GenericEntityDisplayName;
-    displayNameCustomizer?: DisplayNameCustomizer<ObjectType<T>>;
+    displayNameCustomizer?: DisplayNameCustomizer;
     isDeprecated?: boolean;
     uniqueConstraints?: UniqueConstraints;
+    customConstraint?: CustomConstraint;
 }
 export interface EntityDeclWithParentReference<Name extends string = string, T extends TConstraint = TConstraint, FK extends Extract<keyof T, string> = Extract<keyof T, string>> extends EntityDecl<Name, T, FK> {
 }
@@ -51,9 +53,10 @@ export declare const EntityDecl: {
          * @default "name"
          */
         displayName?: EntityDisplayName<T>;
-        displayNameCustomizer?: DisplayNameCustomizer<ObjectType<T>>;
+        displayNameCustomizer?: TypedDisplayNameCustomizer<Name>;
         isDeprecated?: boolean;
         uniqueConstraints?: UniqueConstraints;
+        customConstraint?: TypedCustomConstraint<Name>;
     }): EntityDecl<Name, T, undefined>;
     <Name extends string, T extends TConstraint, FK extends Extract<keyof T, string>>(sourceUrl: string, options: {
         name: Name;
@@ -65,9 +68,10 @@ export declare const EntityDecl: {
          * @default "name"
          */
         displayName?: EntityDisplayName<T>;
-        displayNameCustomizer?: DisplayNameCustomizer<ObjectType<T>>;
+        displayNameCustomizer?: TypedDisplayNameCustomizer<Name>;
         isDeprecated?: boolean;
         uniqueConstraints?: UniqueConstraints;
+        customConstraint?: TypedCustomConstraint<Name>;
     }): EntityDecl<Name, T, FK>;
 };
 export { EntityDecl as Entity };

package/dist/src/node/schema/declarations/EntityDecl.js

@@ -8,6 +8,8 @@ export const EntityDecl = (sourceUrl, options) => {
     validateDeclName(options.name);
     return {
         ...options,
+        displayNameCustomizer: options.displayNameCustomizer, // ignore contravariance of registered entity type
+        customConstraint: options.customConstraint, // ignore contravariance of registered entity type
         kind: NodeKind.EntityDecl,
         sourceUrl,
         parameters: [],

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

@@ -0,0 +1,20 @@
+import type { InstanceContent } from "../../shared/utils/instances.ts";
+export interface Register {
+}
+export type AnyEntityMap = Record<string, InstanceContent>;
+export type RegisteredEntityMap<T = Register> = T extends {
+    entityMap: AnyEntityMap;
+} ? T["entityMap"] : AnyEntityMap;
+export type RegisteredEntity<Name extends string, T = Register> = T extends {
+    entityMap: {
+        [K in Name]: InstanceContent;
+    };
+} ? T["entityMap"][Name] : InstanceContent;
+export type AnyChildEntityMap = Record<string, [
+    content: InstanceContent,
+    parentKey: string,
+    parentValue: string | object
+]>;
+export type RegisteredChildEntityMap<T = Register> = T extends {
+    childEntityMap: AnyChildEntityMap;
+} ? T["childEntityMap"] : AnyChildEntityMap;

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+import type { RegisteredChildEntityMap, RegisteredEntityMap } from "./externalTypes.ts";
+export type GetInstanceById = <U extends keyof RegisteredEntityMap>(entity: U, id: string) => RegisteredEntityMap[U] | undefined;
+export type GetAllInstances = <U extends keyof RegisteredEntityMap>(entity: U) => RegisteredEntityMap[U][];
+export type GetAllChildInstancesForParent = <U extends keyof RegisteredChildEntityMap>(entity: U, parentId: RegisteredChildEntityMap[U][2]) => RegisteredChildEntityMap[U][0][];

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

@@ -0,0 +1 @@
+export {};

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

@@ -2,6 +2,7 @@ export * from "./declarations/Declaration.ts";
 export * from "./declarations/EntityDecl.ts";
 export * from "./declarations/EnumDecl.ts";
 export * from "./declarations/TypeAliasDecl.ts";
+export type * from "./helpers.ts";
 export * from "./Node.ts";
 export * from "./TypeParameter.ts";
 export * from "./types/generic/ArrayType.ts";

package/dist/src/node/schema/types/references/NestedEntityMapType.d.ts

@@ -28,7 +28,7 @@ export declare const NestedEntityMapType: <Name extends string, T extends TConst
      * @default "name"
      */
     displayName?: EntityDisplayName<T>;
-    displayNameCustomizer?: DisplayNameCustomizer<ObjectType<T>>;
+    displayNameCustomizer?: DisplayNameCustomizer;
     isDeprecated?: boolean;
 }) => NestedEntityMapType<Name, T>;
 export { NestedEntityMapType as NestedEntityMap };

package/dist/src/node/utils/customConstraints.d.ts

@@ -0,0 +1,46 @@
+import type { InstanceContainerOverview, InstanceContent } from "../../shared/utils/instances.ts";
+import { type Result } from "../../shared/utils/result.ts";
+import type { RegisteredEntity } from "../schema/externalTypes.ts";
+import type { GetAllChildInstancesForParent, GetAllInstances, GetInstanceById } from "../schema/helpers.ts";
+import type { EntityDecl } from "../schema/index.ts";
+import { type DatabaseInMemory } from "./databaseInMemory.ts";
+/**
+ * A constraint that can be defined on an entity to enforce custom validation logic.
+ *
+ * The constraint function receives the instance to validate and helper functions
+ * to retrieve other instances from the database.
+ *
+ * It should return an array of strings describing the parts of the constraint
+ * that were violated. If the array is empty, the instance is considered valid.
+ */
+export type CustomConstraint = (params: {
+    instanceId: string;
+    instanceContent: InstanceContent;
+    getInstanceById: GetInstanceById;
+    getAllInstance: GetAllInstances;
+    getAllChildInstancesForParent: GetAllChildInstancesForParent;
+}) => string[];
+/**
+ * A constraint that can be defined on an entity to enforce custom validation logic.
+ *
+ * The constraint function receives the instance to validate and helper functions
+ * to retrieve other instances from the database.
+ *
+ * It should return an array of strings describing the parts of the constraint
+ * that were violated. If the array is empty, the instance is considered valid.
+ */
+export type TypedCustomConstraint<Name extends string> = (params: {
+    instanceId: string;
+    instanceContent: RegisteredEntity<Name>;
+    getInstanceById: GetInstanceById;
+    getAllInstance: GetAllInstances;
+    getAllChildInstancesForParent: GetAllChildInstancesForParent;
+}) => string[];
+/**
+ * Checks all custom constraints for all provided entities and their instances.
+ *
+ * Returns `Ok` when no violations have been found and an `Error` with a list of
+ * `AggregateError`s for each entity if there are any violations of any custom
+ * constraint.
+ */
+export declare const checkCustomConstraintsForAllEntities: (db: DatabaseInMemory, entitiesByName: Record<string, EntityDecl>, instanceOverviewsByEntityName: Record<string, InstanceContainerOverview[]>) => Result<void, AggregateError>;

package/dist/src/node/utils/customConstraints.js

@@ -0,0 +1,58 @@
+import { deepEqual } from "../../shared/utils/compare.js";
+import { error, isError, mapError, ok } from "../../shared/utils/result.js";
+import { getInstanceOfEntityFromDatabaseInMemory, getInstancesOfEntityFromDatabaseInMemory, } from "./databaseInMemory.js";
+/**
+ * Checks all custom constraints for all provided entities and their instances.
+ *
+ * Returns `Ok` when no violations have been found and an `Error` with a list of
+ * `AggregateError`s for each entity if there are any violations of any custom
+ * constraint.
+ */
+export const checkCustomConstraintsForAllEntities = (db, entitiesByName, instanceOverviewsByEntityName) => {
+    const accessors = {
+        getInstanceById: (entityName, id) => getInstanceOfEntityFromDatabaseInMemory(db, entityName, id),
+        getAllInstance: entityName => getInstancesOfEntityFromDatabaseInMemory(db, entityName),
+        getAllChildInstancesForParent: (entityName, parentId) => {
+            const entity = entitiesByName[entityName];
+            if (!entity || !entity.parentReferenceKey) {
+                return [];
+            }
+            const parentKey = entity.parentReferenceKey;
+            return getInstancesOfEntityFromDatabaseInMemory(db, entityName).filter(instance => deepEqual(instance.content[parentKey], parentId));
+        },
+    };
+    return mapError(Object.values(entitiesByName).reduce((acc, entity) => {
+        const constraintFn = entity.customConstraint;
+        if (!constraintFn) {
+            return acc;
+        }
+        const errors = getInstancesOfEntityFromDatabaseInMemory(db, entity.name)
+            .map((instance) => [
+            instance,
+            constraintFn({
+                ...accessors,
+                instanceId: instance.id,
+                instanceContent: instance.content,
+            }),
+        ])
+            .filter(([, violations]) => violations.length > 0)
+            .map(([instance, violations]) => {
+            const instanceOverview = instanceOverviewsByEntityName[entity.name]?.find(o => o.id === instance.id);
+            const name = instanceOverview
+                ? `"${instanceOverview.displayName}" (${instance.id})`
+                : instance.id;
+            return new AggregateError(violations.map(violation => new Error(violation)), `in instance ${name}`);
+        });
+        const aggregate = errors.length > 0 ? new AggregateError(errors, `in entity "${entity.name}"`) : undefined;
+        if (isError(acc)) {
+            if (aggregate) {
+                return error([...acc.error, aggregate]);
+            }
+            return acc;
+        }
+        if (aggregate) {
+            return error([aggregate]);
+        }
+        return acc;
+    }, ok()), errors => new AggregateError(errors.toSorted((a, b) => a.message.localeCompare(b.message)), "at least one custom constraint has been violated"));
+};

package/dist/src/node/utils/databaseTransactions.js

@@ -1,6 +1,8 @@
 import { isError, map, ok } from "../../shared/utils/result.js";
+import { checkCustomConstraintsForAllEntities } from "./customConstraints.js";
 import { deleteInstanceInDatabaseInMemory, setInstanceInDatabaseInMemory, } from "./databaseInMemory.js";
 import { applyStepsToDisk } from "./databaseOnDisk.js";
+import { getAllInstanceOverviewsByEntityName } from "./displayName.js";
 import { attachGitStatusToDatabaseInMemory } from "./git.js";
 import { updateReferencesToInstances } from "./references.js";
 import { checkUniqueConstraintsForAllEntities } from "./unique.js";
@@ -18,9 +20,14 @@ export const runDatabaseTransaction = async (root, git, entitiesByName, database
         return result;
     }
     const { db: newDb, refs: newRefs, steps, instanceContainer } = result.value;
-    const constraintResult = checkUniqueConstraintsForAllEntities(newDb, entitiesByName, locales);
-    if (isError(constraintResult)) {
-        return constraintResult;
+    const instanceOverviewsByEntityName = getAllInstanceOverviewsByEntityName(entitiesByName, newDb, locales);
+    const uniqueConstraintResult = checkUniqueConstraintsForAllEntities(newDb, entitiesByName, instanceOverviewsByEntityName);
+    if (isError(uniqueConstraintResult)) {
+        return uniqueConstraintResult;
+    }
+    const customConstraintResult = checkCustomConstraintsForAllEntities(newDb, entitiesByName, instanceOverviewsByEntityName);
+    if (isError(customConstraintResult)) {
+        return customConstraintResult;
     }
     const diskResult = await applyStepsToDisk(root, steps);
     if (isError(diskResult)) {

package/dist/src/node/utils/displayName.d.ts

@@ -1,14 +1,24 @@
 import { type DisplayNameResult } from "../../shared/utils/displayName.ts";
 import type { InstanceContainer, InstanceContainerOverview, InstanceContent } from "../../shared/utils/instances.ts";
 import { type EntityDecl } from "../schema/declarations/EntityDecl.ts";
-import type { AsDeepType, Type } from "../schema/types/Type.ts";
+import type { RegisteredEntity } from "../schema/externalTypes.ts";
 import { type DatabaseInMemory, type InstanceFromDatabaseInMemoryGetter } from "./databaseInMemory.ts";
 export type GetChildInstancesForInstanceId = (parentEntityName: string, parentId: string, childEntityName: string) => {
     id: string;
     content: InstanceContent;
 }[];
-export type DisplayNameCustomizer<T extends Type> = (params: {
-    instance: AsDeepType<T>;
+export type DisplayNameCustomizer = (params: {
+    instance: unknown;
+    instanceId: string;
+    instanceDisplayName: string;
+    instanceDisplayNameLocaleId: string | undefined;
+    locales: string[];
+    getInstanceById: (id: string) => InstanceContent | undefined;
+    getDisplayNameForInstanceId: (id: string) => DisplayNameResult | undefined;
+    getChildInstancesForInstanceId: GetChildInstancesForInstanceId;
+}) => DisplayNameResult;
+export type TypedDisplayNameCustomizer<Name extends string> = (params: {
+    instance: RegisteredEntity<Name>;
     instanceId: string;
     instanceDisplayName: string;
     instanceDisplayNameLocaleId: string | undefined;

package/dist/src/node/utils/displayName.js

@@ -6,7 +6,6 @@ export const getDisplayNameFromEntityInstance = (entity, instanceContainer, getI
     if (useCustomizer && entity.displayNameCustomizer) {
         const calculatedName = getDisplayNameFromEntityInstance(entity, instanceContainer, getInstanceById, getChildInstancesForInstanceId, locales, defaultName, false);
         return entity.displayNameCustomizer({
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment -- otherwise type instiatiation too deep
             instance: instanceContainer.content,
             instanceId: instanceContainer.id,
             instanceDisplayName: calculatedName.name,

package/dist/src/node/utils/unique.d.ts

@@ -20,4 +20,4 @@ export declare const checkUniqueConstraintsForEntity: (entity: EntityDecl, insta
  * `AggregateError`s for each entity if there are any violations of any unique
  * constraint.
  */
-export declare const checkUniqueConstraintsForAllEntities: (db: DatabaseInMemory, entitiesByName: Record<string, EntityDecl>, locales: string[]) => Result<void, AggregateError>;
+export declare const checkUniqueConstraintsForAllEntities: (db: DatabaseInMemory, entitiesByName: Record<string, EntityDecl>, instanceOverviewsByEntityName: Record<string, InstanceContainerOverview[]>) => Result<void, AggregateError>;

package/dist/src/node/utils/unique.js

@@ -3,7 +3,6 @@ import { anySameIndices, flatCombine } from "../../shared/utils/array.js";
 import { deepEqual } from "../../shared/utils/compare.js";
 import { error, isError, mapError, ok } from "../../shared/utils/result.js";
 import { getInstancesOfEntityFromDatabaseInMemory, } from "./databaseInMemory.js";
-import { getAllInstanceOverviewsByEntityName } from "./displayName.js";
 export class UniqueConstraintError extends Error {
     parts;
     constructor(message, parts) {
@@ -91,19 +90,16 @@ export const checkUniqueConstraintsForEntity = (entity, instances, instanceOverv
  * `AggregateError`s for each entity if there are any violations of any unique
  * constraint.
  */
-export const checkUniqueConstraintsForAllEntities = (db, entitiesByName, locales) => {
-    const instanceOverviewsByEntityName = getAllInstanceOverviewsByEntityName(entitiesByName, db, locales);
-    return mapError(Object.values(entitiesByName).reduce((acc, entity) => {
-        const resultForEntity = checkUniqueConstraintsForEntity(entity, getInstancesOfEntityFromDatabaseInMemory(db, entity.name), instanceOverviewsByEntityName[entity.name] ?? []);
-        if (isError(acc)) {
-            if (isError(resultForEntity)) {
-                return error([...acc.error, resultForEntity.error]);
-            }
-            return acc;
-        }
+export const checkUniqueConstraintsForAllEntities = (db, entitiesByName, instanceOverviewsByEntityName) => mapError(Object.values(entitiesByName).reduce((acc, entity) => {
+    const resultForEntity = checkUniqueConstraintsForEntity(entity, getInstancesOfEntityFromDatabaseInMemory(db, entity.name), instanceOverviewsByEntityName[entity.name] ?? []);
+    if (isError(acc)) {
         if (isError(resultForEntity)) {
-            return error([resultForEntity.error]);
+            return error([...acc.error, resultForEntity.error]);
         }
         return acc;
-    }, ok()), errors => new AggregateError(errors.toSorted((a, b) => a.message.localeCompare(b.message)), "at least one unique constraint has been violated"));
-};
+    }
+    if (isError(resultForEntity)) {
+        return error([resultForEntity.error]);
+    }
+    return acc;
+}, ok()), errors => new AggregateError(errors.toSorted((a, b) => a.message.localeCompare(b.message)), "at least one unique constraint has been violated"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsondb",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "",
   "license": "ISC",
   "author": "Lukas Obermann",