@twin.org/entity-storage-models 0.0.3-next.3 → 0.0.3-next.30

package/dist/es/models/api/IEntityStorageGetRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityStorageGetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageGetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Get an entry from entity storage.\n */\nexport interface IEntityStorageGetRequest {\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the entity to get.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The query parameters.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * The secondary index to query with the id.\n\t\t */\n\t\tsecondaryIndex?: string;\n\t};\n}\n"]}
+{"version":3,"file":"IEntityStorageGetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageGetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Get an entry from entity storage.\n */\nexport interface IEntityStorageGetRequest {\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the entity to get.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The query parameters.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * The secondary index to query with the id.\n\t\t */\n\t\tsecondaryIndex?: string;\n\n\t\t/**\n\t\t * The optional conditions to match for the entity, JSON encoded array of property/value pairs.\n\t\t */\n\t\tconditions?: string;\n\t};\n}\n"]}

package/dist/es/models/api/IEntityStorageRemoveBatchRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IEntityStorageRemoveBatchRequest.js.map

package/dist/es/models/api/IEntityStorageRemoveBatchRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IEntityStorageRemoveBatchRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageRemoveBatchRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Remove multiple entries from entity storage by id.\n */\nexport interface IEntityStorageRemoveBatchRequest {\n\t/**\n\t * The ids of the entities to remove.\n\t */\n\tbody: string[];\n}\n"]}

package/dist/es/models/api/IEntityStorageRemoveRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityStorageRemoveRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageRemoveRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Remove an entry from entity storage.\n */\nexport interface IEntityStorageRemoveRequest {\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the entity to remove.\n\t\t */\n\t\tid: string;\n\t};\n}\n"]}
+{"version":3,"file":"IEntityStorageRemoveRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageRemoveRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Remove an entry from entity storage.\n */\nexport interface IEntityStorageRemoveRequest {\n\t/**\n\t * The parameters from the path.\n\t */\n\tpathParams: {\n\t\t/**\n\t\t * The id of the entity to remove.\n\t\t */\n\t\tid: string;\n\t};\n\n\t/**\n\t * The query parameters.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * The optional conditions to match for the entity, JSON encoded array of property/value pairs.\n\t\t */\n\t\tconditions?: string;\n\t};\n}\n"]}

package/dist/es/models/api/IEntityStorageSetBatchRequest.js

@@ -0,0 +1,4 @@
+// Copyright 2024 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IEntityStorageSetBatchRequest.js.map

package/dist/es/models/api/IEntityStorageSetBatchRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IEntityStorageSetBatchRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageSetBatchRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Set multiple entries in entity storage.\n */\nexport interface IEntityStorageSetBatchRequest {\n\t/**\n\t * The entities to set.\n\t */\n\tbody: unknown[];\n}\n"]}

package/dist/es/models/api/IEntityStorageSetRequest.js.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityStorageSetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageSetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Set an entry in entity storage.\n */\nexport interface IEntityStorageSetRequest {\n\t/**\n\t * The data to be used in the entity.\n\t */\n\tbody: unknown;\n}\n"]}
+{"version":3,"file":"IEntityStorageSetRequest.js","sourceRoot":"","sources":["../../../../src/models/api/IEntityStorageSetRequest.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Set an entry in entity storage.\n */\nexport interface IEntityStorageSetRequest {\n\t/**\n\t * The data to be used in the entity.\n\t */\n\tbody: unknown;\n\n\t/**\n\t * The query parameters.\n\t */\n\tquery?: {\n\t\t/**\n\t\t * The optional conditions to match for the entity, JSON encoded array of property/value pairs.\n\t\t */\n\t\tconditions?: string;\n\t};\n}\n"]}

package/dist/es/models/entityPropertyTransformer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entityPropertyTransformer.js.map

package/dist/es/models/entityPropertyTransformer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityPropertyTransformer.js","sourceRoot":"","sources":["../../../src/models/entityPropertyTransformer.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IEntitySchemaProperty } from \"@twin.org/entity\";\n\n/**\n * Type for the optional transformEntityProperty function.\n * Used in migration steps for custom property transformations.\n */\nexport type EntityPropertyTransformer<T = unknown, U = unknown> = (\n\tschema1Property: IEntitySchemaProperty<T>,\n\tschemaProperty2: IEntitySchemaProperty<U>,\n\tvalue: unknown\n) => unknown;\n"]}

package/dist/types/factories/schemaMigrationFactory.d.ts

@@ -0,0 +1,14 @@
+import { Factory } from "@twin.org/core";
+import type { ISchemaMigration } from "../models/ISchemaMigration.js";
+/**
+ * Factory for optional per-step migration overrides.
+ *
+ * Only register an entry when a version step requires property renames or a custom
+ * transform hook. For purely structural changes (add/remove/type-change) the
+ * SchemaVersionService diffs the two versioned schema classes automatically
+ * without needing any factory entry.
+ *
+ * Keys follow the convention "BaseSchemaName_fromVersion_toVersion",
+ * for example "MyEntity_0_1" for the step that migrates MyEntity from version 0 to 1.
+ */
+export declare const SchemaMigrationFactory: Factory<ISchemaMigration<unknown, unknown>>;

package/dist/types/helpers/entityStorageHelper.d.ts

@@ -0,0 +1,59 @@
+import { type EntityCondition, type IEntitySchema, type SortDirection } from "@twin.org/entity";
+/**
+ * Helper class for performing schema migrations between two connectors.
+ */
+export declare class EntityStorageHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Prepare the entity by handling undefined and null values and validating it against the schema.
+     * @param entity The entity to handle undefined and null values for.
+     * @param schema The schema to validate the entity against.
+     * @param additionalProperties Optional list of additional properties to set on the entity.
+     * @param options Options controlling how null/undefined optional properties are stored.
+     * @param options.nullBehavior "omit" strips null/undefined optional properties before writing
+     * (NoSQL — avoids index-key type errors). "nullify" converts undefined to null (SQL — the default).
+     * @returns The entity with undefined and null values handled.
+     */
+    static prepareEntity<T>(entity: T, schema: IEntitySchema<T>, additionalProperties?: {
+        property: string;
+        value: unknown;
+    }[], options?: {
+        nullBehavior?: "omit" | "nullify";
+    }): T;
+    /**
+     * Un-prepare the entity by removing null values.
+     * @param entity The entity to handle undefined and null values for.
+     * @param removeProperties Optional list of properties to remove from the entity.
+     * @returns The entity with undefined and null values handled.
+     */
+    static unPrepareEntity<T>(entity: Partial<T> | undefined, removeProperties?: string[]): T;
+    /**
+     * Validate that every sort property in the list is indexed in the schema (isPrimary, isSecondary,
+     * or has a default sortDirection), throwing sortNotIndexed for the first violation found.
+     * @param schema The entity schema to validate against.
+     * @param sortProperties The sort properties to check.
+     * @throws GeneralError If a sort property is not indexed in the schema.
+     */
+    static validateSortProperties<T>(schema: IEntitySchema<T>, sortProperties?: {
+        property: keyof T;
+        sortDirection: SortDirection;
+    }[]): void;
+    /**
+     * Validate that every property in the list exists in the schema, throwing propertyNotInSchema
+     * for the first property that is not found.
+     * @param schema The entity schema to validate against.
+     * @param properties The properties to check.
+     * @throws GeneralError If a property does not exist in the schema.
+     */
+    static validateProperties<T>(schema: IEntitySchema<T>, properties?: (keyof T)[]): void;
+    /**
+     * Deep-clone condition tree and normalise null/undefined to undefined on Equals/NotEquals leaves
+     * so in-memory evaluation matches stored-absent semantics (optional absent props are omitted/undefined).
+     * @param condition The user-supplied condition (not mutated).
+     * @returns A clone safe to pass to check.
+     */
+    static normalizeConditionValues<T>(condition: EntityCondition<T>): EntityCondition<T>;
+}

package/dist/types/helpers/migrationHelper.d.ts

@@ -0,0 +1,65 @@
+import { type IEntitySchemaDiff } from "@twin.org/entity";
+import type { EntityPropertyTransformer } from "../models/entityPropertyTransformer.js";
+import type { IEntityStorageConnector } from "../models/IEntityStorageConnector.js";
+import type { IEntityStorageMigrationConnector } from "../models/IEntityStorageMigrationConnector.js";
+import type { IMigrationOptions } from "../models/IMigrationOptions.js";
+import type { IResolvedMigrationStep } from "../models/IResolvedMigrationStep.js";
+/**
+ * Helper class for performing entity schema migrations between two connectors.
+ * The chain-based API (migrateWithChain / applyEntityChain) is the single migration
+ * path: a chain of one step covers the same case as a traditional single-step migration.
+ */
+export declare class MigrationHelper {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Performs a chain migration in a single connector swap, regardless of how many version
+     * steps the chain spans. Creates one target connector, reads all source entities, applies
+     * applyEntityChain to each, writes them to the target, then finalizes the migration.
+     * A chain of one step is equivalent to a traditional single-step migration.
+     * @param sourceConnector The connector holding data at the stored schema version.
+     * @param targetSchemaName The schema name for the current version (used to create the target connector).
+     * @param steps Ordered, fully-resolved migration steps from stored to current version.
+     * @param options Optional migration options.
+     * @param loggingComponentType The optional component type to use for logging the migration progress.
+     * @returns The finalized connector and the count of migrated entities.
+     */
+    static migrateWithChain(sourceConnector: IEntityStorageMigrationConnector, targetSchemaName: string, steps: IResolvedMigrationStep[], options?: IMigrationOptions, loggingComponentType?: string): Promise<{
+        finalConnector: IEntityStorageConnector;
+        migrated: number;
+    }>;
+    /**
+     * Reads all entities from one partition of the source connector, applies the migration
+     * chain to each entity, and writes the results to the target connector.
+     * @param source The connector to read from (already bootstrapped).
+     * @param target The connector to write to (already bootstrapped).
+     * @param steps Ordered, fully-resolved migration steps.
+     * @param options Optional migration options (batchSize, progress callbacks, transformEntityProperty).
+     * @returns The number of entities migrated.
+     */
+    static migratePartitionWithChain(source: IEntityStorageMigrationConnector, target: IEntityStorageConnector, steps: IResolvedMigrationStep[], options?: IMigrationOptions): Promise<number>;
+    /**
+     * Transforms a single entity through an ordered chain of fully-resolved migration steps.
+     * For each step the method diffs fromProperties against toProperties, then applies
+     * applyEntityTransform. Each step's output feeds the next step's input so that
+     * per-step transformEntityProperty hooks are honoured throughout the chain.
+     * @param entity The entity to transform (at the shape described by steps[0].fromProperties).
+     * @param steps Ordered, fully-resolved migration steps from stored version to current version.
+     * Each step's fromProperties and toProperties are resolved by the caller before invocation.
+     * @returns The entity transformed to the shape described by steps[last].toProperties.
+     */
+    static applyEntityChain(entity: unknown, steps: IResolvedMigrationStep[]): unknown;
+    /**
+     * Applies the entity transformation for a single diff, handling added, removed, and
+     * modified properties according to the provided schema diff and optional transform hook.
+     * @param entity The entity to transform.
+     * @param schemaDiff The schema diff between the old and new schemas.
+     * @param transformEntityProperty Optional per-property transform hook for object/array properties.
+     * @returns The transformed entity ready to be written to the new schema.
+     * @throws GeneralError if a transformation is required for an object or array property but no transformEntityProperty function is provided.
+     * @throws GeneralError if coercion of a modified property results in undefined for a non-optional target property.
+     */
+    static applyEntityTransform<T = unknown, U = unknown>(entity: Partial<T>, schemaDiff: IEntitySchemaDiff<T, U>, transformEntityProperty?: EntityPropertyTransformer<T, U>): U;
+}

package/dist/types/index.d.ts

@@ -1,9 +1,22 @@
 export * from "./factories/entityStorageConnectorFactory.js";
+export * from "./factories/schemaMigrationFactory.js";
+export * from "./helpers/entityStorageHelper.js";
+export * from "./helpers/migrationHelper.js";
+export * from "./models/api/IEntityStorageCountRequest.js";
+export * from "./models/api/IEntityStorageCountResponse.js";
+export * from "./models/api/IEntityStorageEmptyRequest.js";
 export * from "./models/api/IEntityStorageGetRequest.js";
 export * from "./models/api/IEntityStorageGetResponse.js";
 export * from "./models/api/IEntityStorageListRequest.js";
 export * from "./models/api/IEntityStorageListResponse.js";
+export * from "./models/api/IEntityStorageRemoveBatchRequest.js";
 export * from "./models/api/IEntityStorageRemoveRequest.js";
+export * from "./models/api/IEntityStorageSetBatchRequest.js";
 export * from "./models/api/IEntityStorageSetRequest.js";
+export * from "./models/entityPropertyTransformer.js";
 export * from "./models/IEntityStorageComponent.js";
 export * from "./models/IEntityStorageConnector.js";
+export * from "./models/IEntityStorageMigrationConnector.js";
+export * from "./models/IMigrationOptions.js";
+export * from "./models/IResolvedMigrationStep.js";
+export * from "./models/ISchemaMigration.js";

package/dist/types/models/IEntityStorageComponent.d.ts

@@ -7,22 +7,46 @@ export interface IEntityStorageComponent<T = unknown> extends IComponent {
     /**
      * Set an entity.
      * @param entity The entity to set.
+     * @param conditions The optional conditions to match for the entities.
      * @returns The id of the entity.
      */
-    set(entity: T): Promise<void>;
+    set(entity: T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    setBatch(entities: T[]): Promise<void>;
     /**
      * Get an entity.
      * @param id The id of the entity to get, or the index value if secondaryIndex is set.
      * @param secondaryIndex Get the item using a secondary index.
+     * @param conditions The optional conditions to match for the entities.
      * @returns The object if it can be found or undefined.
      */
-    get(id: string, secondaryIndex?: keyof T): Promise<T | undefined>;
+    get(id: string, secondaryIndex?: keyof T, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<T | undefined>;
     /**
      * Remove the entity.
      * @param id The id of the entity to remove.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns Nothing.
+     */
+    remove(id: string, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
+    /**
+     * Remove multiple entities by id.
+     * @param ids The ids of the entities to remove.
      * @returns Nothing.
      */
-    remove(id: string): Promise<void>;
+    removeBatch(ids: string[]): Promise<void>;
     /**
      * Query all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -44,4 +68,15 @@ export interface IEntityStorageComponent<T = unknown> extends IComponent {
          */
         cursor?: string;
     }>;
+    /**
+     * Remove all entities from the storage.
+     * @returns Nothing.
+     */
+    empty(): Promise<void>;
+    /**
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
+     */
+    count(conditions?: EntityCondition<T>): Promise<number>;
 }

package/dist/types/models/IEntityStorageConnector.d.ts

@@ -19,6 +19,12 @@ export interface IEntityStorageConnector<T = unknown> extends IComponent {
         property: keyof T;
         value: unknown;
     }[]): Promise<void>;
+    /**
+     * Set multiple entities in a batch.
+     * @param entities The entities to set.
+     * @returns Nothing.
+     */
+    setBatch(entities: T[]): Promise<void>;
     /**
      * Get an entity.
      * @param id The id of the entity to get, or the index value if secondaryIndex is set.
@@ -40,6 +46,12 @@ export interface IEntityStorageConnector<T = unknown> extends IComponent {
         property: keyof T;
         value: unknown;
     }[]): Promise<void>;
+    /**
+     * Remove multiple entities by id.
+     * @param ids The ids of the entities to remove.
+     * @returns Nothing.
+     */
+    removeBatch(ids: string[]): Promise<void>;
     /**
      * Query all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.
@@ -63,4 +75,15 @@ export interface IEntityStorageConnector<T = unknown> extends IComponent {
          */
         cursor?: string;
     }>;
+    /**
+     * Remove all entities from the storage.
+     * @returns Nothing.
+     */
+    empty(): Promise<void>;
+    /**
+     * Count all the entities which match the conditions.
+     * @param conditions The optional conditions to match for the entities.
+     * @returns The total count of entities in the storage.
+     */
+    count(conditions?: EntityCondition<T>): Promise<number>;
 }

package/dist/types/models/IEntityStorageMigrationConnector.d.ts

@@ -0,0 +1,35 @@
+import type { IContextIds } from "@twin.org/context";
+import type { IEntityStorageConnector } from "./IEntityStorageConnector.js";
+import type { IMigrationOptions } from "./IMigrationOptions.js";
+/**
+ * Interface describing an entity storage migration connector.
+ */
+export interface IEntityStorageMigrationConnector<T = unknown> extends IEntityStorageConnector<T> {
+    /**
+     * Get a unique list of all the context ids from the storage.
+     * @returns The list of unique context ids.
+     */
+    getPartitionContextIds(): Promise<IContextIds[]>;
+    /**
+     * Create the target connector for performing the migration it will use a temporary storage location.
+     * @param newEntitySchema The name of the new entity schema to create the connector for.
+     * @returns Connector for performing the migration.
+     */
+    createTargetConnector<U>(newEntitySchema: string): Promise<IEntityStorageConnector<U>>;
+    /**
+     * Finalize the migration by tearing down the old connector and replacing it with the target connector.
+     * @param targetConnector The target connector to finalize the migration with.
+     * @param options The options to control how the migration is finalized.
+     * @param loggingComponentType The optional component type to use for logging the migration progress.
+     * @returns A promise that resolves when the migration is finalized and returns the final connector.
+     */
+    finalizeMigration<U>(targetConnector: IEntityStorageConnector<U>, options?: IMigrationOptions, loggingComponentType?: string): Promise<IEntityStorageConnector<U>>;
+    /**
+     * Cleanup the migration if a migration fails or needs to be aborted.
+     * @param targetConnector The target connector to cleanup the migration with.
+     * @param options The options to control how the migration is cleaned up.
+     * @param loggingComponentType The optional component type to use for logging the migration progress.
+     * @returns A promise that resolves when the migration is cleaned up.
+     */
+    cleanupMigration<U>(targetConnector: IEntityStorageConnector<U> | undefined, options?: IMigrationOptions, loggingComponentType?: string): Promise<void>;
+}

package/dist/types/models/IMigrationOptions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Options controlling how a schema migration is executed.
+ */
+export interface IMigrationOptions {
+    /**
+     * Number of entities to read and write per batch.
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Called for progress tracking.
+     * @param progressItem The item progress being updated.
+     * @param itemTotal The total number of rows to migrate.
+     * @param itemIndex The number of rows migrated so far.
+     */
+    onProgress?: (progressItem: "partitionStart" | "partitionProgress" | "partitionEnd" | "partitionItemsStart" | "partitionItemsProgress" | "partitionItemsEnd", itemTotal: number, itemIndex: number) => Promise<void>;
+}

package/dist/types/models/IResolvedMigrationStep.d.ts

@@ -0,0 +1,38 @@
+import type { IEntitySchemaProperty } from "@twin.org/entity";
+import type { EntityPropertyTransformer } from "./entityPropertyTransformer.js";
+/**
+ * A fully-resolved single migration step used by MigrationHelper.
+ * The SchemaVersionService builds these by looking up versioned schema classes
+ * from EntitySchemaFactory (e.g. MyEntityV0, MyEntityV1) before invoking the helper,
+ * keeping factory knowledge out of the helper itself.
+ * @template T The entity type. Defaults to `unknown`. Use a concrete entity type
+ * when the step's source and target schemas are known at the call site.
+ */
+export interface IResolvedMigrationStep<T = unknown, U = unknown> {
+    /**
+     * The property list of the entity at the start of this step (the "old" shape).
+     * Sourced from the versioned schema class registered in EntitySchemaFactory,
+     * e.g. EntitySchemaFactory.get("MyEntityV0").properties.
+     */
+    fromProperties: IEntitySchemaProperty<T>[];
+    /**
+     * The property list of the entity at the end of this step (the "new" shape).
+     * For the final step this is the live current schema's properties.
+     */
+    toProperties: IEntitySchemaProperty<U>[];
+    /**
+     * Optional property renames for this step, forwarded to EntitySchemaDiffHelper.diff.
+     */
+    renames?: {
+        from: string;
+        to: string;
+    }[];
+    /**
+     * Optional transformation for properties, usually only called for object and array types.
+     * @param schema1Property The property schema in the old schema.
+     * @param schemaProperty2 The property schema in the new schema.
+     * @param value The value of the property in the old schema.
+     * @returns The transformed value to match the new schema.
+     */
+    transformEntityProperty?: EntityPropertyTransformer<T, U>;
+}

package/dist/types/models/ISchemaMigration.d.ts

@@ -0,0 +1,30 @@
+import type { EntityPropertyTransformer } from "./entityPropertyTransformer.js";
+/**
+ * Optional per-step override for a single version-to-version migration.
+ * Only register an entry in SchemaMigrationFactory when a step requires property
+ * renames or a custom object/array transform. For purely structural changes
+ * (add/remove/type-change fields) no entry is needed — the runner diffs the two
+ * versioned schema classes (e.g. MyEntityV0 vs MyEntityV1) from EntitySchemaFactory
+ * automatically.
+ *
+ * Register under the key "BaseSchemaName_fromVersion_toVersion"
+ * e.g. "MyEntity_0_1" for the step that migrates from version 0 to version 1.
+ * The key itself encodes the version pair; no version field is needed on the object.
+ */
+export interface ISchemaMigration<T = unknown, U = unknown> {
+    /**
+     * Optional property renames to apply during this step.
+     */
+    renames?: {
+        from: string;
+        to: string;
+    }[];
+    /**
+     * Optional transformation for properties, usually only called for object and array types.
+     * @param schema1Property The property schema in the old schema.
+     * @param schemaProperty2 The property schema in the new schema.
+     * @param value The value of the property in the old schema.
+     * @returns The transformed value to match the new schema.
+     */
+    transformEntityProperty?: EntityPropertyTransformer<T, U>;
+}

package/dist/types/models/api/IEntityStorageCountRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Count the entries in entity storage.
+ */
+export interface IEntityStorageCountRequest {
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The optional conditions to filter the count, JSON encoded EntityCondition.
+         */
+        conditions?: string;
+    };
+}

package/dist/types/models/api/IEntityStorageCountResponse.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The response for counting entries in entity storage.
+ */
+export interface IEntityStorageCountResponse {
+    /**
+     * The body of the response.
+     */
+    body: {
+        /**
+         * The total count of entities.
+         */
+        count: number;
+    };
+}

package/dist/types/models/api/IEntityStorageEmptyRequest.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Remove all entries from entity storage.
+ */
+export interface IEntityStorageEmptyRequest {
+}

package/dist/types/models/api/IEntityStorageGetRequest.d.ts

@@ -19,5 +19,9 @@ export interface IEntityStorageGetRequest {
          * The secondary index to query with the id.
          */
         secondaryIndex?: string;
+        /**
+         * The optional conditions to match for the entity, JSON encoded array of property/value pairs.
+         */
+        conditions?: string;
     };
 }

package/dist/types/models/api/IEntityStorageRemoveBatchRequest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Remove multiple entries from entity storage by id.
+ */
+export interface IEntityStorageRemoveBatchRequest {
+    /**
+     * The ids of the entities to remove.
+     */
+    body: string[];
+}

package/dist/types/models/api/IEntityStorageRemoveRequest.d.ts

@@ -11,4 +11,13 @@ export interface IEntityStorageRemoveRequest {
          */
         id: string;
     };
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The optional conditions to match for the entity, JSON encoded array of property/value pairs.
+         */
+        conditions?: string;
+    };
 }

package/dist/types/models/api/IEntityStorageSetBatchRequest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Set multiple entries in entity storage.
+ */
+export interface IEntityStorageSetBatchRequest {
+    /**
+     * The entities to set.
+     */
+    body: unknown[];
+}

package/dist/types/models/api/IEntityStorageSetRequest.d.ts

@@ -6,4 +6,13 @@ export interface IEntityStorageSetRequest {
      * The data to be used in the entity.
      */
     body: unknown;
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The optional conditions to match for the entity, JSON encoded array of property/value pairs.
+         */
+        conditions?: string;
+    };
 }

package/dist/types/models/entityPropertyTransformer.d.ts

@@ -0,0 +1,6 @@
+import type { IEntitySchemaProperty } from "@twin.org/entity";
+/**
+ * Type for the optional transformEntityProperty function.
+ * Used in migration steps for custom property transformations.
+ */
+export type EntityPropertyTransformer<T = unknown, U = unknown> = (schema1Property: IEntitySchemaProperty<T>, schemaProperty2: IEntitySchemaProperty<U>, value: unknown) => unknown;