@twin.org/entity 0.0.1-next.5 → 0.0.1-next.51

package/dist/cjs/index.cjs

@@ -61,7 +61,7 @@ function property(options) {
         const entitySchema = DecoratorHelper.getSchema(target);
         entitySchema.properties ??= [];
         const idx = entitySchema.properties.findIndex(p => p.property === propertyKey);
-        if (idx >= 0) {
+        if (idx !== -1) {
             entitySchema.properties[idx] = {
                 ...options,
                 property: propertyKey
@@ -533,6 +533,60 @@ 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) ||
+                    core.Is.array(value) ||
+                    core.Is.string(value) ||
+                    core.Is.number(value) ||
+                    core.Is.boolean(value) ||
+                    core.Is.null(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, "invalidEntityProperty", {
+                    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.
@@ -572,7 +626,9 @@ class EntitySorter {
      */
     static compare(entity1, entity2, prop, type, direction = SortDirection.Ascending) {
         let res = 0;
-        if (!core.Is.empty(entity1[prop]) && !core.Is.empty(entity2[prop])) {
+        const hasProp1 = !core.Is.empty(entity1[prop]);
+        const hasProp2 = !core.Is.empty(entity2[prop]);
+        if (hasProp1 && hasProp2) {
             if (type === "number" || type === "integer") {
                 res = entity1[prop] - entity2[prop];
             }
@@ -593,6 +649,12 @@ class EntitySorter {
                 res = entity1[prop].localeCompare(entity2[prop]);
             }
         }
+        else if (hasProp1) {
+            res = -1;
+        }
+        else {
+            res = 1;
+        }
         return direction === SortDirection.Ascending ? res : res * -1;
     }
 }

package/dist/esm/index.mjs

@@ -59,7 +59,7 @@ function property(options) {
         const entitySchema = DecoratorHelper.getSchema(target);
         entitySchema.properties ??= [];
         const idx = entitySchema.properties.findIndex(p => p.property === propertyKey);
-        if (idx >= 0) {
+        if (idx !== -1) {
             entitySchema.properties[idx] = {
                 ...options,
                 property: propertyKey
@@ -531,6 +531,60 @@ 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) ||
+                    Is.array(value) ||
+                    Is.string(value) ||
+                    Is.number(value) ||
+                    Is.boolean(value) ||
+                    Is.null(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, "invalidEntityProperty", {
+                    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.
@@ -570,7 +624,9 @@ class EntitySorter {
      */
     static compare(entity1, entity2, prop, type, direction = SortDirection.Ascending) {
         let res = 0;
-        if (!Is.empty(entity1[prop]) && !Is.empty(entity2[prop])) {
+        const hasProp1 = !Is.empty(entity1[prop]);
+        const hasProp2 = !Is.empty(entity2[prop]);
+        if (hasProp1 && hasProp2) {
             if (type === "number" || type === "integer") {
                 res = entity1[prop] - entity2[prop];
             }
@@ -591,6 +647,12 @@ class EntitySorter {
                 res = entity1[prop].localeCompare(entity2[prop]);
             }
         }
+        else if (hasProp1) {
+            res = -1;
+        }
+        else {
+            res = 1;
+        }
         return direction === SortDirection.Ascending ? res : res * -1;
     }
 }

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,33 @@
 # @twin.org/entity - Changelog
 
-## 0.0.1-next.5
+## [0.0.1-next.51](https://github.com/twinfoundation/framework/compare/entity-v0.0.1-next.50...entity-v0.0.1-next.51) (2025-03-27)
+
+
+### Miscellaneous Chores
+
+* **entity:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.1-next.50 to 0.0.1-next.51
+
+## [0.0.1-next.50](https://github.com/twinfoundation/framework/compare/entity-v0.0.1-next.49...entity-v0.0.1-next.50) (2025-03-26)
+
+
+### Miscellaneous Chores
+
+* **entity:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/core bumped from 0.0.1-next.49 to 0.0.1-next.50
+
+## 0.0.1-next.49
 
 - Initial Release

package/docs/reference/classes/DecoratorHelper.md

@@ -26,7 +26,9 @@ Get the schema from the reflection metadata.
 
 #### Parameters
 
-• **target**: `any`
+##### target
+
+`any`
 
 The object to get the schema data from.
 
@@ -50,11 +52,15 @@ Set the schema from the reflection metadata.
 
 #### Parameters
 
-• **target**: `any`
+##### target
+
+`any`
 
 The object to get the schema data from.
 
-• **entitySchema**: [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
+##### entitySchema
+
+[`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
 The schema to set.
 

package/docs/reference/classes/EntityConditions.md

@@ -26,11 +26,15 @@ See if the entity matches the conditions.
 
 #### Parameters
 
-• **entity**: `T`
+##### entity
+
+`T`
 
 The entity to test.
 
-• **condition?**: [`EntityCondition`](../type-aliases/EntityCondition.md)\<`T`\>
+##### condition?
+
+[`EntityCondition`](../type-aliases/EntityCondition.md)\<`T`\>
 
 The conditions to test.
 
@@ -54,11 +58,15 @@ See if the entity matches the conditions.
 
 #### Parameters
 
-• **entity**: `T`
+##### entity
+
+`T`
 
 The entity to test.
 
-• **comparator**: [`IComparator`](../interfaces/IComparator.md)
+##### comparator
+
+[`IComparator`](../interfaces/IComparator.md)
 
 The condition to test.
 

package/docs/reference/classes/EntitySchemaHelper.md

@@ -26,7 +26,9 @@ Get the schema for the specified object.
 
 #### Parameters
 
-• **target**: `any`
+##### target
+
+`any`
 
 The object to get the schema data for.
 
@@ -50,7 +52,9 @@ Get the primary key from the entity schema.
 
 #### Parameters
 
-• **entitySchema**: [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
+##### entitySchema
+
+[`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
 The entity schema to find the primary key from.
 
@@ -78,7 +82,9 @@ Get the sort properties from the schema.
 
 #### Parameters
 
-• **entitySchema**: [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
+##### entitySchema
+
+[`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
 The entity schema to find the primary key from.
 
@@ -102,11 +108,15 @@ Build sort properties from the schema and override if necessary.
 
 #### Parameters
 
-• **entitySchema**: [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
+##### entitySchema
+
+[`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
 The entity schema to retrieve the default sort keys.
 
-• **overrideSortKeys?**: `object`[]
+##### overrideSortKeys?
+
+`object`[]
 
 The override sort keys.
 
@@ -115,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/docs/reference/classes/EntitySorter.md

@@ -26,11 +26,15 @@ Sort a list of entities using multiple keys and direction.
 
 #### Parameters
 
-• **entities**: `T`[]
+##### entities
+
+`T`[]
 
 The list of entities.
 
-• **entitySorters?**: [`IEntitySort`](../interfaces/IEntitySort.md)\<`T`\>[]
+##### entitySorters?
+
+[`IEntitySort`](../interfaces/IEntitySort.md)\<`T`\>[]
 
 The sort keys to use.
 
@@ -54,23 +58,33 @@ Compare two properties.
 
 #### Parameters
 
-• **entity1**: `T`
+##### entity1
+
+`T`
 
 The first entity.
 
-• **entity2**: `T`
+##### entity2
+
+`T`
 
 The second entity.
 
-• **prop**: keyof `T`
+##### prop
+
+keyof `T`
 
 The property to compare.
 
-• **type**: [`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
+##### type
+
+[`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
 
 The type of the property.
 
-• **direction**: [`SortDirection`](../type-aliases/SortDirection.md) = `SortDirection.Ascending`
+##### direction
+
+[`SortDirection`](../type-aliases/SortDirection.md) = `SortDirection.Ascending`
 
 The direction of the sort.
 

package/docs/reference/functions/entity.md

@@ -6,7 +6,9 @@ Decorator to produce schema data for entity.
 
 ## Parameters
 
-• **options?**: [`IEntitySchemaOptions`](../interfaces/IEntitySchemaOptions.md)
+### options?
+
+[`IEntitySchemaOptions`](../interfaces/IEntitySchemaOptions.md)
 
 The options for the entity.
 

package/docs/reference/functions/property.md

@@ -6,7 +6,9 @@ Decorator to produce schema property data for entities.
 
 ## Parameters
 
-• **options**: `Omit`\<[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`unknown`\>, `"property"`\>
+### options
+
+`Omit`\<[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`unknown`\>, `"property"`\>
 
 The options for the property.
 

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",
+			"invalidEntityProperty": "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.5",
+	"version": "0.0.1-next.51",
 	"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.5",
+		"@twin.org/core": "0.0.1-next.51",
 		"@twin.org/nameof": "next",
 		"reflect-metadata": "0.2.2"
 	},
@@ -23,11 +23,11 @@
 	"types": "./dist/types/index.d.ts",
 	"exports": {
 		".": {
+			"types": "./dist/types/index.d.ts",
 			"require": "./dist/cjs/index.cjs",
-			"import": "./dist/esm/index.mjs",
-			"types": "./dist/types/index.d.ts"
+			"import": "./dist/esm/index.mjs"
 		},
-		"./locales": "./locales"
+		"./locales/*.json": "./locales/*.json"
 	},
 	"files": [
 		"dist/cjs",