@twin.org/entity 0.0.1-next.44 → 0.0.1-next.45

package/dist/cjs/index.cjs

@@ -533,6 +533,54 @@ class EntitySchemaHelper {
         }
         return finalSortKeys;
     }
+    /**
+     * Validate the entity against the schema.
+     * @param entity The entity to validate.
+     * @param entitySchema The schema to validate against.
+     * @throws If the entity is invalid.
+     */
+    static validateEntity(entity, entitySchema) {
+        core.Guards.object(EntitySchemaHelper._CLASS_NAME, "entity", entity);
+        core.Guards.object(EntitySchemaHelper._CLASS_NAME, "entitySchema", entitySchema);
+        const properties = entitySchema.properties ?? [];
+        if (properties.length === 0 && core.Is.objectValue(entity)) {
+            throw new core.GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntityProperties");
+        }
+        const allKeys = Object.keys(entity);
+        for (const prop of properties) {
+            const idx = allKeys.indexOf(prop.property);
+            if (idx !== -1) {
+                allKeys.splice(idx, 1);
+            }
+            const value = entity[prop.property];
+            if (core.Is.empty(value)) {
+                // If the value is empty but the property is not optional, then it's invalid
+                if (!prop.optional) {
+                    throw new core.GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidOptional", {
+                        property: prop.property,
+                        type: prop.type
+                    });
+                }
+            }
+            else if (prop.type === "integer" && core.Is.integer(value)) ;
+            else if (prop.type === "object" && core.Is.object(value)) ;
+            else if (prop.type === "array" && core.Is.array(value)) ;
+            else if (prop.type !== typeof value) {
+                // The schema type does not match the value type
+                throw new core.GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntity", {
+                    value,
+                    property: prop.property,
+                    type: prop.type
+                });
+            }
+        }
+        if (allKeys.length > 0) {
+            // There are keys in the entity that are not in the schema
+            throw new core.GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntityKeys", {
+                keys: allKeys.join(", ")
+            });
+        }
+    }
 }
 
 // Copyright 2024 IOTA Stiftung.

package/dist/esm/index.mjs

@@ -531,6 +531,54 @@ class EntitySchemaHelper {
         }
         return finalSortKeys;
     }
+    /**
+     * Validate the entity against the schema.
+     * @param entity The entity to validate.
+     * @param entitySchema The schema to validate against.
+     * @throws If the entity is invalid.
+     */
+    static validateEntity(entity, entitySchema) {
+        Guards.object(EntitySchemaHelper._CLASS_NAME, "entity", entity);
+        Guards.object(EntitySchemaHelper._CLASS_NAME, "entitySchema", entitySchema);
+        const properties = entitySchema.properties ?? [];
+        if (properties.length === 0 && Is.objectValue(entity)) {
+            throw new GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntityProperties");
+        }
+        const allKeys = Object.keys(entity);
+        for (const prop of properties) {
+            const idx = allKeys.indexOf(prop.property);
+            if (idx !== -1) {
+                allKeys.splice(idx, 1);
+            }
+            const value = entity[prop.property];
+            if (Is.empty(value)) {
+                // If the value is empty but the property is not optional, then it's invalid
+                if (!prop.optional) {
+                    throw new GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidOptional", {
+                        property: prop.property,
+                        type: prop.type
+                    });
+                }
+            }
+            else if (prop.type === "integer" && Is.integer(value)) ;
+            else if (prop.type === "object" && Is.object(value)) ;
+            else if (prop.type === "array" && Is.array(value)) ;
+            else if (prop.type !== typeof value) {
+                // The schema type does not match the value type
+                throw new GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntity", {
+                    value,
+                    property: prop.property,
+                    type: prop.type
+                });
+            }
+        }
+        if (allKeys.length > 0) {
+            // There are keys in the entity that are not in the schema
+            throw new GeneralError(EntitySchemaHelper._CLASS_NAME, "invalidEntityKeys", {
+                keys: allKeys.join(", ")
+            });
+        }
+    }
 }
 
 // Copyright 2024 IOTA Stiftung.

package/dist/types/utils/entitySchemaHelper.d.ts

@@ -35,4 +35,11 @@ export declare class EntitySchemaHelper {
         property: keyof T;
         sortDirection: SortDirection;
     }[]): IEntitySort<T>[] | undefined;
+    /**
+     * Validate the entity against the schema.
+     * @param entity The entity to validate.
+     * @param entitySchema The schema to validate against.
+     * @throws If the entity is invalid.
+     */
+    static validateEntity<T>(entity: T, entitySchema: IEntitySchema<T>): void;
 }

package/docs/changelog.md

@@ -1,5 +1,5 @@
 # @twin.org/entity - Changelog
 
-## 0.0.1-next.44
+## 0.0.1-next.45
 
 - Initial Release

package/docs/reference/classes/EntitySchemaHelper.md

@@ -125,3 +125,37 @@ The override sort keys.
 `undefined` \| [`IEntitySort`](../interfaces/IEntitySort.md)\<`T`\>[]
 
 The finalised sort keys.
+
+***
+
+### validateEntity()
+
+> `static` **validateEntity**\<`T`\>(`entity`, `entitySchema`): `void`
+
+Validate the entity against the schema.
+
+#### Type Parameters
+
+• **T**
+
+#### Parameters
+
+##### entity
+
+`T`
+
+The entity to validate.
+
+##### entitySchema
+
+[`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
+
+The schema to validate against.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+If the entity is invalid.

package/locales/en.json

@@ -2,7 +2,11 @@
 	"error": {
 		"entitySchemaHelper": {
 			"noIsPrimary": "Property \"entitySchema.properties\" must contain a value with isPrimary set",
-			"multipleIsPrimary": "Property \"entitySchema.properties\" contains more than one property with isPrimary set"
+			"multipleIsPrimary": "Property \"entitySchema.properties\" contains more than one property with isPrimary set",
+			"invalidEntityProperties": "The schema has no properties defined, but the entity has properties",
+			"invalidEntity": "The entity value of \"{value}\" does not match the type \"{type}\" for property \"{property}\"",
+			"invalidOptional": "The entity property \"{property}\" of type \"{type}\" is not optional, but no value has been provided",
+			"invalidEntityKeys": "The entity had additional properties that are not in the schema, \"{keys}\""
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity",
-	"version": "0.0.1-next.44",
+	"version": "0.0.1-next.45",
 	"description": "Helpers for defining and working with entities",
 	"repository": {
 		"type": "git",
@@ -14,7 +14,7 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@twin.org/core": "0.0.1-next.44",
+		"@twin.org/core": "0.0.1-next.45",
 		"@twin.org/nameof": "next",
 		"reflect-metadata": "0.2.2"
 	},