@twin.org/entity 0.0.3-next.9 → 0.0.4-next.1

package/docs/examples.md

@@ -1 +1,70 @@
-# @twin.org/entity - Examples
+# Entity Examples
+
+Use these snippets to build schemas, compose conditions and order data for query-style workflows.
+
+## EntitySchemaHelper
+
+```typescript
+import { EntitySchemaHelper } from '@twin.org/entity';
+
+class Product {
+  public id!: string;
+  public sku!: string;
+  public price!: number;
+}
+
+const schema = EntitySchemaHelper.getSchema(Product);
+EntitySchemaHelper.getPrimaryKey(schema); // 'id'
+EntitySchemaHelper.getSortProperties(schema); // ['sku', 'price']
+```
+
+## EntityConditions
+
+```typescript
+import { EntityConditions } from '@twin.org/entity';
+
+const product = {
+  sku: 'A-100',
+  price: 49.99,
+  active: true
+};
+
+EntityConditions.compare('eq', product.sku, 'A-100'); // true
+EntityConditions.check(product, [{ property: 'price', comparison: 'gt', value: 10 }]); // true
+```
+
+## EntitySorter
+
+```typescript
+import { EntitySorter } from '@twin.org/entity';
+
+const records = [
+  { sku: 'A-300', price: 15 },
+  { sku: 'A-100', price: 20 },
+  { sku: 'A-200', price: 10 }
+];
+
+EntitySorter.sort(records, [{ property: 'sku', sortDirection: 'ascending' }]);
+```
+
+## DecoratorHelper
+
+```typescript
+import { DecoratorHelper } from '@twin.org/entity';
+
+class Customer {
+  public id!: string;
+}
+
+DecoratorHelper.setSchema(Customer, {
+  primaryKey: 'id',
+  type: 'customer',
+  properties: {
+    id: {
+      type: 'string'
+    }
+  }
+});
+
+DecoratorHelper.getSchema(Customer)?.primaryKey; // 'id'
+```

package/docs/reference/classes/DecoratorHelper.md

@@ -14,7 +14,7 @@ Class to help with decorators.
 
 ## Methods
 
-### getSchema()
+### getSchema() {#getschema}
 
 > `static` **getSchema**\<`T`\>(`target`): [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
@@ -42,7 +42,7 @@ The schema from the metadata if it can be found.
 
 ***
 
-### setSchema()
+### setSchema() {#setschema}
 
 > `static` **setSchema**\<`T`\>(`target`, `entitySchema`): `void`
 

package/docs/reference/classes/EntityConditions.md

@@ -14,7 +14,7 @@ Class to perform condition checks.
 
 ## Methods
 
-### check()
+### check() {#check}
 
 > `static` **check**\<`T`\>(`entity`, `condition?`): `boolean`
 
@@ -48,7 +48,7 @@ True if the entity matches.
 
 ***
 
-### compare()
+### compare() {#compare}
 
 > `static` **compare**\<`T`\>(`entity`, `comparator`): `boolean`
 

package/docs/reference/classes/EntitySchemaDiffHelper.md

@@ -0,0 +1,147 @@
+# Class: EntitySchemaDiffHelper
+
+Helper class for comparing entity schemas and generating diffs.
+
+## Constructors
+
+### Constructor
+
+> **new EntitySchemaDiffHelper**(): `EntitySchemaDiffHelper`
+
+#### Returns
+
+`EntitySchemaDiffHelper`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### diff() {#diff}
+
+> `static` **diff**\<`T`, `U`\>(`oldProperties`, `newProperties`, `renames?`): [`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+Compare two arrays of entity schema properties and return a structured diff.
+
+Properties are matched by their `property` key name. A property is considered modified when any structural field differs: `type`, `format`, `isPrimary`, `isSecondary`, `sortDirection`, `optional`, `itemType`, or `itemTypeRef`.
+Documentation-only fields (`description`, `examples`) are intentionally excluded from the comparison to avoid spurious diffs.
+
+Because a pure name change cannot be detected automatically, callers may supply a `renames` list mapping old names to new names. Renamed properties appear in `modified` (never in `added` or `removed`) even when no other fields changed. Rename lookups take priority over direct same-name matches, which allows swap renames to work correctly and prevents a renamed source from silently disappearing when the target name already existed in the old schema. Self-renames (`from === to`) are ignored and the property is classified normally.
+
+When `renames` contains duplicate entries: if two entries share the same target, the last definition wins and the first source is treated as removed; if two entries share the same source, the first target wins and the second target is treated as added. Both cases are deterministic but callers should avoid them.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U` = `T`
+
+#### Parameters
+
+##### oldProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
+
+The property descriptors from the current (live) schema.
+
+##### newProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`U`\>[]
+
+The property descriptors from the target (new) schema.
+
+##### renames?
+
+`object`[]
+
+Optional list of property renames `{ from, to }` where `from` is the old name and `to` is the new name.
+
+#### Returns
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+A diff object with `added`, `removed`, `modified`, and `unchanged` arrays, each containing full `IEntitySchemaProperty` descriptors.
+
+#### Throws
+
+`GeneralError` if either input array contains duplicate property keys.
+
+***
+
+### hasChanges() {#haschanges}
+
+> `static` **hasChanges**\<`T`, `U`\>(`diff`): `boolean`
+
+Returns true when the diff contains at least one added, removed, or modified property.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### diff
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`, `U`\>
+
+The diff to check.
+
+#### Returns
+
+`boolean`
+
+True if the diff has any structural changes.
+
+***
+
+### schemaPropertiesEqual() {#schemapropertiesequal}
+
+> `static` **schemaPropertiesEqual**\<`T`, `U`\>(`schema1`, `schema2`): `boolean`
+
+Compare two property descriptors for structural equality.
+The `property` name field and documentation fields (`description`, `examples`) are intentionally excluded — callers match by name before invoking this method.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### schema1
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>
+
+The first property descriptor.
+
+##### schema2
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`U`\>
+
+The second property descriptor.
+
+#### Returns
+
+`boolean`
+
+True if all structural fields are equal.

package/docs/reference/classes/EntitySchemaHelper.md

@@ -14,7 +14,7 @@ Class to help with entity schema operations.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### getSchema()
+### getSchema() {#getschema}
 
 > `static` **getSchema**\<`T`\>(`target`): [`IEntitySchema`](../interfaces/IEntitySchema.md)\<`T`\>
 
@@ -50,7 +50,7 @@ The schema for the object if it can be found.
 
 ***
 
-### getPrimaryKey()
+### getPrimaryKey() {#getprimarykey}
 
 > `static` **getPrimaryKey**\<`T`\>(`entitySchema`): [`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>
 
@@ -82,7 +82,7 @@ If no primary key was found, or more than one.
 
 ***
 
-### getSortProperties()
+### getSortProperties() {#getsortproperties}
 
 > `static` **getSortProperties**\<`T`\>(`entitySchema`): [`IEntitySort`](../interfaces/IEntitySort.md)\<`T`\>[] \| `undefined`
 
@@ -110,7 +110,7 @@ The sort keys from the schema or undefined if there are none.
 
 ***
 
-### buildSortProperties()
+### buildSortProperties() {#buildsortproperties}
 
 > `static` **buildSortProperties**\<`T`\>(`entitySchema`, `overrideSortKeys?`): [`IEntitySort`](../interfaces/IEntitySort.md)\<`T`\>[] \| `undefined`
 
@@ -144,7 +144,7 @@ The finalised sort keys.
 
 ***
 
-### validateEntity()
+### validateEntity() {#validateentity}
 
 > `static` **validateEntity**\<`T`\>(`entity`, `entitySchema`): `void`
 

package/docs/reference/classes/EntitySorter.md

@@ -14,7 +14,7 @@ Class to perform sort operations on entities.
 
 ## Methods
 
-### sort()
+### sort() {#sort}
 
 > `static` **sort**\<`T`\>(`entities`, `entitySorters?`): `T`[]
 
@@ -48,9 +48,9 @@ The sorted list.
 
 ***
 
-### compare()
+### compare() {#compare}
 
-> `static` **compare**\<`T`\>(`entity1`, `entity2`, `prop`, `type`, `direction`): `number`
+> `static` **compare**\<`T`\>(`entity1`, `entity2`, `prop`, `type`, `direction?`): `number`
 
 Compare two properties.
 
@@ -86,7 +86,7 @@ The property to compare.
 
 The type of the property.
 
-##### direction
+##### direction?
 
 [`SortDirection`](../type-aliases/SortDirection.md) = `SortDirection.Ascending`
 

package/docs/reference/index.md

@@ -4,6 +4,7 @@
 
 - [DecoratorHelper](classes/DecoratorHelper.md)
 - [EntityConditions](classes/EntityConditions.md)
+- [EntitySchemaDiffHelper](classes/EntitySchemaDiffHelper.md)
 - [EntitySchemaHelper](classes/EntitySchemaHelper.md)
 - [EntitySorter](classes/EntitySorter.md)
 
@@ -12,6 +13,7 @@
 - [IComparator](interfaces/IComparator.md)
 - [IComparatorGroup](interfaces/IComparatorGroup.md)
 - [IEntitySchema](interfaces/IEntitySchema.md)
+- [IEntitySchemaDiff](interfaces/IEntitySchemaDiff.md)
 - [IEntitySchemaOptions](interfaces/IEntitySchemaOptions.md)
 - [IEntitySchemaProperty](interfaces/IEntitySchemaProperty.md)
 - [IEntitySort](interfaces/IEntitySort.md)

package/docs/reference/interfaces/IComparator.md

@@ -4,7 +4,7 @@ Interface defining comparator operator.
 
 ## Properties
 
-### property
+### property {#property}
 
 > **property**: `string`
 
@@ -12,7 +12,7 @@ The name of the property in the object to check.
 
 ***
 
-### value
+### value {#value}
 
 > **value**: `unknown`
 
@@ -20,7 +20,7 @@ The value of the property to check.
 
 ***
 
-### comparison
+### comparison {#comparison}
 
 > **comparison**: [`ComparisonOperator`](../type-aliases/ComparisonOperator.md)
 

package/docs/reference/interfaces/IComparatorGroup.md

@@ -10,7 +10,7 @@ Interface defining condition group operator.
 
 ## Properties
 
-### conditions
+### conditions {#conditions}
 
 > **conditions**: [`EntityCondition`](../type-aliases/EntityCondition.md)\<`T`\>[]
 
@@ -18,8 +18,8 @@ The conditions to join in a group.
 
 ***
 
-### logicalOperator?
+### logicalOperator? {#logicaloperator}
 
-> `optional` **logicalOperator**: [`LogicalOperator`](../type-aliases/LogicalOperator.md)
+> `optional` **logicalOperator?**: [`LogicalOperator`](../type-aliases/LogicalOperator.md)
 
 The logical operator to use.

package/docs/reference/interfaces/IEntitySchema.md

@@ -10,7 +10,7 @@ Definition for an entity schema.
 
 ## Properties
 
-### type
+### type {#type}
 
 > **type**: `string` \| `undefined`
 
@@ -18,16 +18,16 @@ The type of the entity.
 
 ***
 
-### options?
+### options? {#options}
 
-> `optional` **options**: [`IEntitySchemaOptions`](IEntitySchemaOptions.md)
+> `optional` **options?**: [`IEntitySchemaOptions`](IEntitySchemaOptions.md)
 
 The options for the entity.
 
 ***
 
-### properties?
+### properties? {#properties}
 
-> `optional` **properties**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
+> `optional` **properties?**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
 
 The properties of the entity.

package/docs/reference/interfaces/IEntitySchemaDiff.md

@@ -0,0 +1,59 @@
+# Interface: IEntitySchemaDiff\<T, U\>
+
+The result of comparing two sets of entity schema properties.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+### U
+
+`U` = `unknown`
+
+## Properties
+
+### unchanged {#unchanged}
+
+> **unchanged**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T` \| `U`\>[]
+
+Properties that are structurally identical between the old and new schemas.
+
+***
+
+### added {#added}
+
+> **added**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`U`\>[]
+
+Properties present in the new schema but absent from the old one.
+
+***
+
+### removed {#removed}
+
+> **removed**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
+
+Properties present in the old schema but absent from the new one.
+
+***
+
+### modified {#modified}
+
+> **modified**: `object`[]
+
+Properties that exist in both schemas but differ in at least one structural
+field (property, type, format, isPrimary, isSecondary, sortDirection, optional, itemType, itemTypeRef).
+`from` is the old descriptor; `to` is the new one.
+
+#### from
+
+> **from**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>
+
+The old property descriptor.
+
+#### to
+
+> **to**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`U`\>
+
+The new property descriptor.

package/docs/reference/interfaces/IEntitySchemaOptions.md

@@ -4,8 +4,8 @@ Definition for an entity schema options.
 
 ## Properties
 
-### description?
+### description? {#description}
 
-> `optional` **description**: `string`
+> `optional` **description?**: `string`
 
 Description of the object.

package/docs/reference/interfaces/IEntitySchemaProperty.md

@@ -10,7 +10,7 @@ Definition for an entity schema property.
 
 ## Properties
 
-### property
+### property {#property}
 
 > **property**: keyof `T`
 
@@ -18,7 +18,7 @@ The property name from the entity.
 
 ***
 
-### type
+### type {#type}
 
 > **type**: [`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
 
@@ -26,72 +26,72 @@ The type of the property.
 
 ***
 
-### format?
+### format? {#format}
 
-> `optional` **format**: [`EntitySchemaPropertyFormat`](../type-aliases/EntitySchemaPropertyFormat.md)
+> `optional` **format?**: [`EntitySchemaPropertyFormat`](../type-aliases/EntitySchemaPropertyFormat.md)
 
 The format of the property.
 
 ***
 
-### isPrimary?
+### isPrimary? {#isprimary}
 
-> `optional` **isPrimary**: `boolean`
+> `optional` **isPrimary?**: `boolean`
 
 Is this the primary index property.
 
 ***
 
-### isSecondary?
+### isSecondary? {#issecondary}
 
-> `optional` **isSecondary**: `boolean`
+> `optional` **isSecondary?**: `boolean`
 
 Is this a secondary index property.
 
 ***
 
-### sortDirection?
+### sortDirection? {#sortdirection}
 
-> `optional` **sortDirection**: [`SortDirection`](../type-aliases/SortDirection.md)
+> `optional` **sortDirection?**: [`SortDirection`](../type-aliases/SortDirection.md)
 
 Default sort direction for this field, leave empty if not sortable.
 
 ***
 
-### optional?
+### optional? {#optional}
 
-> `optional` **optional**: `boolean`
+> `optional` **optional?**: `boolean`
 
 Is the property optional.
 
 ***
 
-### itemType?
+### itemType? {#itemtype}
 
-> `optional` **itemType**: [`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
+> `optional` **itemType?**: [`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
 
 The type of the item (only applies when type is `array`).
 
 ***
 
-### itemTypeRef?
+### itemTypeRef? {#itemtyperef}
 
-> `optional` **itemTypeRef**: `string`
+> `optional` **itemTypeRef?**: `string`
 
 The type ref of the item (only applies when type is either `array` or `object`).
 
 ***
 
-### description?
+### description? {#description}
 
-> `optional` **description**: `string`
+> `optional` **description?**: `string`
 
 Description of the object.
 
 ***
 
-### examples?
+### examples? {#examples}
 
-> `optional` **examples**: `unknown`[]
+> `optional` **examples?**: `unknown`[]
 
 Examples of the property values.

package/docs/reference/interfaces/IEntitySort.md

@@ -10,7 +10,7 @@ Definition of an entity property sort details.
 
 ## Properties
 
-### property
+### property {#property}
 
 > **property**: keyof `T`
 
@@ -18,7 +18,7 @@ The name of the property.
 
 ***
 
-### type
+### type {#type}
 
 > **type**: [`EntitySchemaPropertyType`](../type-aliases/EntitySchemaPropertyType.md)
 
@@ -26,7 +26,7 @@ The type of the property.
 
 ***
 
-### sortDirection
+### sortDirection {#sortdirection}
 
 > **sortDirection**: [`SortDirection`](../type-aliases/SortDirection.md)