@twin.org/entity 0.0.3-next.4 → 0.0.3-next.40

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/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/functions/entitySchemaDiff.md

@@ -0,0 +1,38 @@
+# Function: entitySchemaDiff()
+
+> **entitySchemaDiff**\<`T`\>(`oldProperties`, `newProperties`): [`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
+
+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.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### oldProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
+
+The property descriptors from the current (live) schema.
+
+### newProperties
+
+[`IEntitySchemaProperty`](../interfaces/IEntitySchemaProperty.md)\<`T`\>[]
+
+The property descriptors from the target (new) schema.
+
+## Returns
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
+
+A diff object with `added`, `removed`, and `modified` arrays, each
+containing full `IEntitySchemaProperty` descriptors.

package/docs/reference/functions/isEmptyDiff.md

@@ -0,0 +1,25 @@
+# Function: isEmptyDiff()
+
+> **isEmptyDiff**\<`T`\>(`diff`): `boolean`
+
+Returns true when the diff contains no changes (nothing added, removed, or modified).
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### diff
+
+[`IEntitySchemaDiff`](../interfaces/IEntitySchemaDiff.md)\<`T`\>
+
+The diff to check.
+
+## Returns
+
+`boolean`
+
+True if the diff is empty.

package/docs/reference/index.md

@@ -12,6 +12,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)
@@ -38,3 +39,5 @@
 
 - [entity](functions/entity.md)
 - [property](functions/property.md)
+- [entitySchemaDiff](functions/entitySchemaDiff.md)
+- [isEmptyDiff](functions/isEmptyDiff.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,53 @@
+# Interface: IEntitySchemaDiff\<T\>
+
+The result of comparing two sets of entity schema properties.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+## Properties
+
+### added {#added}
+
+> **added**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
+
+Properties present in the new schema but absent from the old one.
+Each entry is the full property descriptor from the new schema, so it can
+be passed directly to bootstrap / table-creation logic.
+
+***
+
+### removed {#removed}
+
+> **removed**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>[]
+
+Properties present in the old schema but absent from the new one.
+Each entry is the full property descriptor from the old schema, allowing
+connectors to drop the correct column, index, or field by name.
+
+***
+
+### modified {#modified}
+
+> **modified**: `object`[]
+
+Properties that exist in both schemas but differ in at least one structural
+field (type, format, isSecondary, sortDirection, optional, itemType, itemTypeRef).
+`from` is the old descriptor; `to` is the new one.
+Both are full property objects so connectors can drop the old definition and
+create the new one using the same bootstrap code path.
+
+#### from
+
+> **from**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>
+
+The old property descriptor.
+
+#### to
+
+> **to**: [`IEntitySchemaProperty`](IEntitySchemaProperty.md)\<`T`\>
+
+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)
 

package/docs/reference/variables/ComparisonOperator.md

@@ -6,43 +6,43 @@ The types of comparisons.
 
 ## Type Declaration
 
-### Equals
+### Equals {#equals}
 
 > `readonly` **Equals**: `"equals"` = `"equals"`
 
 Equals.
 
-### NotEquals
+### NotEquals {#notequals}
 
 > `readonly` **NotEquals**: `"not-equals"` = `"not-equals"`
 
 Not Equals.
 
-### GreaterThan
+### GreaterThan {#greaterthan}
 
 > `readonly` **GreaterThan**: `"greater-than"` = `"greater-than"`
 
 Greater Than.
 
-### GreaterThanOrEqual
+### GreaterThanOrEqual {#greaterthanorequal}
 
 > `readonly` **GreaterThanOrEqual**: `"greater-than-or-equal"` = `"greater-than-or-equal"`
 
 Greater Than Or Equal.
 
-### LessThan
+### LessThan {#lessthan}
 
 > `readonly` **LessThan**: `"less-than"` = `"less-than"`
 
 Less Than.
 
-### LessThanOrEqual
+### LessThanOrEqual {#lessthanorequal}
 
 > `readonly` **LessThanOrEqual**: `"less-than-or-equal"` = `"less-than-or-equal"`
 
 Less Than Or Equal.
 
-### Includes
+### Includes {#includes}
 
 > `readonly` **Includes**: `"includes"` = `"includes"`
 
@@ -51,7 +51,7 @@ A string in a substring.
 A set contains an element.
 A list contains an element.
 
-### NotIncludes
+### NotIncludes {#notincludes}
 
 > `readonly` **NotIncludes**: `"not-includes"` = `"not-includes"`
 
@@ -60,7 +60,7 @@ A string not in a substring.
 A set does not contain an element.
 A list does not contain an element.
 
-### In
+### In {#in}
 
 > `readonly` **In**: `"in"` = `"in"`