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

package/dist/types/index.d.ts

@@ -1,2 +1,9 @@
 export * from "./factories/entityStorageConnectorFactory";
+export * from "./models/api/IEntityStorageGetRequest";
+export * from "./models/api/IEntityStorageGetResponse";
+export * from "./models/api/IEntityStorageListRequest";
+export * from "./models/api/IEntityStorageListResponse";
+export * from "./models/api/IEntityStorageRemoveRequest";
+export * from "./models/api/IEntityStorageSetRequest";
+export * from "./models/IEntityStorageComponent";
 export * from "./models/IEntityStorageConnector";

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

@@ -0,0 +1,55 @@
+import type { IComponent } from "@twin.org/core";
+import type { EntityCondition, SortDirection } from "@twin.org/entity";
+/**
+ * Interface describing an entity storage component.
+ */
+export interface IEntityStorageComponent<T = unknown> extends IComponent {
+    /**
+     * Set an entity.
+     * @param entity The entity to set.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
+     * @returns The id of the entity.
+     */
+    set(entity: T, userIdentity?: string, nodeIdentity?: string): 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 userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
+     * @returns The object if it can be found or undefined.
+     */
+    get(id: string, secondaryIndex?: keyof T, userIdentity?: string, nodeIdentity?: string): Promise<T | undefined>;
+    /**
+     * Remove the entity.
+     * @param id The id of the entity to remove.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
+     * @returns Nothing.
+     */
+    remove(id: string, userIdentity?: string, nodeIdentity?: string): Promise<void>;
+    /**
+     * Query all the entities which match the conditions.
+     * @param conditions The conditions to match for the entities.
+     * @param orderBy The order for the results.
+     * @param orderByDirection The direction for the order, defaults to ascending.
+     * @param properties The optional properties to return, defaults to all.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+     * @param userIdentity The user identity to use with storage operations.
+     * @param nodeIdentity The node identity to use with storage operations.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    query(conditions?: EntityCondition<T>, orderBy?: keyof T, orderByDirection?: SortDirection, properties?: (keyof T)[], cursor?: string, pageSize?: number, userIdentity?: string, nodeIdentity?: string): Promise<{
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: Partial<T>[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    }>;
+}

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

@@ -1,28 +1,45 @@
 import type { IComponent } from "@twin.org/core";
-import type { EntityCondition, SortDirection } from "@twin.org/entity";
+import type { EntityCondition, IEntitySchema, SortDirection } from "@twin.org/entity";
 /**
  * Interface describing an entity storage connector.
  */
 export interface IEntityStorageConnector<T = unknown> extends IComponent {
     /**
-     * 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.
-     * @returns The object if it can be found or undefined.
+     * Get the schema for the entities.
+     * @returns The schema for the entities.
      */
-    get(id: string, secondaryIndex?: keyof T): Promise<T | undefined>;
+    getSchema(): IEntitySchema;
     /**
      * 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>;
+    /**
+     * 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, 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): Promise<void>;
+    remove(id: string, conditions?: {
+        property: keyof T;
+        value: unknown;
+    }[]): Promise<void>;
     /**
      * Query all the entities which match the conditions.
      * @param conditions The conditions to match for the entities.

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

@@ -0,0 +1,23 @@
+/**
+ * Get an entry from entity storage.
+ */
+export interface IEntityStorageGetRequest {
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the entity to get.
+         */
+        id: string;
+    };
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The secondary index to query with the id.
+         */
+        secondaryIndex?: string;
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Get an entry from entity storage.
+ */
+export interface IEntityStorageGetResponse {
+    /**
+     * The data for the requested entity.
+     */
+    body: unknown;
+}

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

@@ -0,0 +1,35 @@
+import type { SortDirection } from "@twin.org/entity";
+/**
+ * Query the entries from entity storage.
+ */
+export interface IEntityStorageListRequest {
+    /**
+     * The parameters from the query.
+     */
+    query?: {
+        /**
+         * The condition for the query as JSON version of EntityCondition type.
+         */
+        conditions?: string;
+        /**
+         * The order property for the results.
+         */
+        orderBy?: string;
+        /**
+         * The direction for the order, defaults to desc.
+         */
+        orderByDirection?: SortDirection;
+        /**
+         * The properties to return in the response as a comma separated list, by default returns all properties.
+         */
+        properties?: string;
+        /**
+         * The number of entries to return per page.
+         */
+        pageSize?: number;
+        /**
+         * The cursor to get next chunk of data, returned in previous response.
+         */
+        cursor?: string;
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Response to getting the list of entries from a query.
+ */
+export interface IEntityStorageListResponse {
+    /**
+     * The list of entries from the query.
+     */
+    body: {
+        /**
+         * The entities from the query.
+         */
+        entities: unknown[];
+        /**
+         * The cursor for the next page.
+         */
+        cursor?: string;
+    };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Remove an entry from entity storage.
+ */
+export interface IEntityStorageRemoveRequest {
+    /**
+     * The parameters from the path.
+     */
+    pathParams: {
+        /**
+         * The id of the entity to remove.
+         */
+        id: string;
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Set an entry in entity storage.
+ */
+export interface IEntityStorageSetRequest {
+    /**
+     * The data to be used in the entity.
+     */
+    body: unknown;
+}

package/docs/changelog.md

@@ -1,5 +1,33 @@
 # @twin.org/entity-storage-models - Changelog
 
-## v0.0.1-next.3
+## [0.0.1-next.30](https://github.com/twinfoundation/entity-storage/compare/entity-storage-models-v0.0.1-next.29...entity-storage-models-v0.0.1-next.30) (2025-06-12)
+
+
+### Features
+
+* update dependencies ([7ccc0c4](https://github.com/twinfoundation/entity-storage/commit/7ccc0c429125d073dc60b3de6cf101abc8cc6cba))
+
+## [0.0.1-next.29](https://github.com/twinfoundation/entity-storage/compare/entity-storage-models-v0.0.1-next.28...entity-storage-models-v0.0.1-next.29) (2025-04-17)
+
+
+### Features
+
+* use shared store mechanism ([#34](https://github.com/twinfoundation/entity-storage/issues/34)) ([68b6b71](https://github.com/twinfoundation/entity-storage/commit/68b6b71e7a96d7d016cd57bfff36775b56bf3f93))
+
+## [0.0.1-next.28](https://github.com/twinfoundation/entity-storage/compare/entity-storage-models-v0.0.1-next.27...entity-storage-models-v0.0.1-next.28) (2025-04-09)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-models:** Synchronize repo versions
+
+## [0.0.1-next.27](https://github.com/twinfoundation/entity-storage/compare/entity-storage-models-v0.0.1-next.26...entity-storage-models-v0.0.1-next.27) (2025-03-28)
+
+
+### Miscellaneous Chores
+
+* **entity-storage-models:** Synchronize repo versions
+
+## v0.0.1-next.26
 
 - Initial Release

package/docs/reference/index.md

@@ -2,7 +2,14 @@
 
 ## Interfaces
 
+- [IEntityStorageComponent](interfaces/IEntityStorageComponent.md)
 - [IEntityStorageConnector](interfaces/IEntityStorageConnector.md)
+- [IEntityStorageGetRequest](interfaces/IEntityStorageGetRequest.md)
+- [IEntityStorageGetResponse](interfaces/IEntityStorageGetResponse.md)
+- [IEntityStorageListRequest](interfaces/IEntityStorageListRequest.md)
+- [IEntityStorageListResponse](interfaces/IEntityStorageListResponse.md)
+- [IEntityStorageRemoveRequest](interfaces/IEntityStorageRemoveRequest.md)
+- [IEntityStorageSetRequest](interfaces/IEntityStorageSetRequest.md)
 
 ## Variables
 

package/docs/reference/interfaces/IEntityStorageComponent.md

@@ -0,0 +1,186 @@
+# Interface: IEntityStorageComponent\<T\>
+
+Interface describing an entity storage component.
+
+## Extends
+
+- `IComponent`
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+## Methods
+
+### set()
+
+> **set**(`entity`, `userIdentity?`, `nodeIdentity?`): `Promise`\<`void`\>
+
+Set an entity.
+
+#### Parameters
+
+##### entity
+
+`T`
+
+The entity to set.
+
+##### userIdentity?
+
+`string`
+
+The user identity to use with storage operations.
+
+##### nodeIdentity?
+
+`string`
+
+The node identity to use with storage operations.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+The id of the entity.
+
+***
+
+### get()
+
+> **get**(`id`, `secondaryIndex?`, `userIdentity?`, `nodeIdentity?`): `Promise`\<`undefined` \| `T`\>
+
+Get an entity.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the entity to get, or the index value if secondaryIndex is set.
+
+##### secondaryIndex?
+
+keyof `T`
+
+Get the item using a secondary index.
+
+##### userIdentity?
+
+`string`
+
+The user identity to use with storage operations.
+
+##### nodeIdentity?
+
+`string`
+
+The node identity to use with storage operations.
+
+#### Returns
+
+`Promise`\<`undefined` \| `T`\>
+
+The object if it can be found or undefined.
+
+***
+
+### remove()
+
+> **remove**(`id`, `userIdentity?`, `nodeIdentity?`): `Promise`\<`void`\>
+
+Remove the entity.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the entity to remove.
+
+##### userIdentity?
+
+`string`
+
+The user identity to use with storage operations.
+
+##### nodeIdentity?
+
+`string`
+
+The node identity to use with storage operations.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+***
+
+### query()
+
+> **query**(`conditions?`, `orderBy?`, `orderByDirection?`, `properties?`, `cursor?`, `pageSize?`, `userIdentity?`, `nodeIdentity?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
+
+Query all the entities which match the conditions.
+
+#### Parameters
+
+##### conditions?
+
+`EntityCondition`\<`T`\>
+
+The conditions to match for the entities.
+
+##### orderBy?
+
+keyof `T`
+
+The order for the results.
+
+##### orderByDirection?
+
+`SortDirection`
+
+The direction for the order, defaults to ascending.
+
+##### properties?
+
+keyof `T`[]
+
+The optional properties to return, defaults to all.
+
+##### cursor?
+
+`string`
+
+The cursor to request the next page of entities.
+
+##### pageSize?
+
+`number`
+
+The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
+
+##### userIdentity?
+
+`string`
+
+The user identity to use with storage operations.
+
+##### nodeIdentity?
+
+`string`
+
+The node identity to use with storage operations.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.

package/docs/reference/interfaces/IEntityStorageConnector.md

@@ -8,66 +8,108 @@ Interface describing an entity storage connector.
 
 ## Type Parameters
 
-• **T** = `unknown`
+### T
+
+`T` = `unknown`
 
 ## Methods
 
-### get()
+### getSchema()
 
-> **get**(`id`, `secondaryIndex`?): `Promise`\<`undefined` \| `T`\>
+> **getSchema**(): `IEntitySchema`
 
-Get an entity.
+Get the schema for the entities.
+
+#### Returns
+
+`IEntitySchema`
+
+The schema for the entities.
+
+***
+
+### set()
+
+> **set**(`entity`, `conditions?`): `Promise`\<`void`\>
+
+Set an entity.
 
 #### Parameters
 
-• **id**: `string`
+##### entity
 
-The id of the entity to get, or the index value if secondaryIndex is set.
+`T`
 
-• **secondaryIndex?**: keyof `T`
+The entity to set.
 
-Get the item using a secondary index.
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
 
 #### Returns
 
-`Promise`\<`undefined` \| `T`\>
+`Promise`\<`void`\>
 
-The object if it can be found or undefined.
+The id of the entity.
 
 ***
 
-### set()
+### get()
 
-> **set**(`entity`): `Promise`\<`void`\>
+> **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`undefined` \| `T`\>
 
-Set an entity.
+Get an entity.
 
 #### Parameters
 
-• **entity**: `T`
+##### id
 
-The entity to set.
+`string`
+
+The id of the entity to get, or the index value if secondaryIndex is set.
+
+##### secondaryIndex?
+
+keyof `T`
+
+Get the item using a secondary index.
+
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
 
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`undefined` \| `T`\>
 
-The id of the entity.
+The object if it can be found or undefined.
 
 ***
 
 ### remove()
 
-> **remove**(`id`): `Promise`\<`void`\>
+> **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
 Remove the entity.
 
 #### Parameters
 
-• **id**: `string`
+##### id
+
+`string`
 
 The id of the entity to remove.
 
+##### conditions?
+
+`object`[]
+
+The optional conditions to match for the entities.
+
 #### Returns
 
 `Promise`\<`void`\>
@@ -78,47 +120,45 @@ Nothing.
 
 ### query()
 
-> **query**(`conditions`?, `sortProperties`?, `properties`?, `cursor`?, `pageSize`?): `Promise`\<`object`\>
+> **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `pageSize?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
 Query all the entities which match the conditions.
 
 #### Parameters
 
-• **conditions?**: `EntityCondition`\<`T`\>
+##### conditions?
+
+`EntityCondition`\<`T`\>
 
 The conditions to match for the entities.
 
-• **sortProperties?**: `object`[]
+##### sortProperties?
+
+`object`[]
 
 The optional sort order.
 
-• **properties?**: keyof `T`[]
+##### properties?
+
+keyof `T`[]
 
 The optional properties to return, defaults to all.
 
-• **cursor?**: `string`
+##### cursor?
+
+`string`
 
 The cursor to request the next page of entities.
 
-• **pageSize?**: `number`
+##### pageSize?
+
+`number`
 
 The suggested number of entities to return in each chunk, in some scenarios can return a different amount.
 
 #### Returns
 
-`Promise`\<`object`\>
+`Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
 All the entities for the storage matching the conditions,
 and a cursor which can be used to request more entities.
-
-##### entities
-
-> **entities**: `Partial`\<`T`\>[]
-
-The entities, which can be partial if a limited keys list was provided.
-
-##### cursor?
-
-> `optional` **cursor**: `string`
-
-An optional cursor, when defined can be used to call find to get more entities.

package/docs/reference/interfaces/IEntityStorageGetRequest.md

@@ -0,0 +1,31 @@
+# Interface: IEntityStorageGetRequest
+
+Get an entry from entity storage.
+
+## Properties
+
+### pathParams
+
+> **pathParams**: `object`
+
+The parameters from the path.
+
+#### id
+
+> **id**: `string`
+
+The id of the entity to get.
+
+***
+
+### query?
+
+> `optional` **query**: `object`
+
+The query parameters.
+
+#### secondaryIndex?
+
+> `optional` **secondaryIndex**: `string`
+
+The secondary index to query with the id.

package/docs/reference/interfaces/IEntityStorageGetResponse.md

@@ -0,0 +1,11 @@
+# Interface: IEntityStorageGetResponse
+
+Get an entry from entity storage.
+
+## Properties
+
+### body
+
+> **body**: `unknown`
+
+The data for the requested entity.

package/docs/reference/interfaces/IEntityStorageListRequest.md

@@ -0,0 +1,47 @@
+# Interface: IEntityStorageListRequest
+
+Query the entries from entity storage.
+
+## Properties
+
+### query?
+
+> `optional` **query**: `object`
+
+The parameters from the query.
+
+#### conditions?
+
+> `optional` **conditions**: `string`
+
+The condition for the query as JSON version of EntityCondition type.
+
+#### orderBy?
+
+> `optional` **orderBy**: `string`
+
+The order property for the results.
+
+#### orderByDirection?
+
+> `optional` **orderByDirection**: `SortDirection`
+
+The direction for the order, defaults to desc.
+
+#### properties?
+
+> `optional` **properties**: `string`
+
+The properties to return in the response as a comma separated list, by default returns all properties.
+
+#### pageSize?
+
+> `optional` **pageSize**: `number`
+
+The number of entries to return per page.
+
+#### cursor?
+
+> `optional` **cursor**: `string`
+
+The cursor to get next chunk of data, returned in previous response.

package/docs/reference/interfaces/IEntityStorageListResponse.md

@@ -0,0 +1,23 @@
+# Interface: IEntityStorageListResponse
+
+Response to getting the list of entries from a query.
+
+## Properties
+
+### body
+
+> **body**: `object`
+
+The list of entries from the query.
+
+#### entities
+
+> **entities**: `unknown`[]
+
+The entities from the query.
+
+#### cursor?
+
+> `optional` **cursor**: `string`
+
+The cursor for the next page.

package/docs/reference/interfaces/IEntityStorageRemoveRequest.md

@@ -0,0 +1,17 @@
+# Interface: IEntityStorageRemoveRequest
+
+Remove an entry from entity storage.
+
+## Properties
+
+### pathParams
+
+> **pathParams**: `object`
+
+The parameters from the path.
+
+#### id
+
+> **id**: `string`
+
+The id of the entity to remove.

package/docs/reference/interfaces/IEntityStorageSetRequest.md

@@ -0,0 +1,11 @@
+# Interface: IEntityStorageSetRequest
+
+Set an entry in entity storage.
+
+## Properties
+
+### body
+
+> **body**: `unknown`
+
+The data to be used in the entity.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/entity-storage-models",
-	"version": "0.0.1-next.3",
+	"version": "0.0.1-next.30",
 	"description": "Models which define the structure of the entity storage contracts and connectors",
 	"repository": {
 		"type": "git",
@@ -13,47 +13,21 @@
 	"engines": {
 		"node": ">=20.0.0"
 	},
-	"scripts": {
-		"clean": "rimraf dist coverage docs/reference",
-		"build": "tspc",
-		"test": "vitest --run --config ./vitest.config.ts --no-cache",
-		"coverage": "vitest --run --coverage --config ./vitest.config.ts --no-cache",
-		"bundle:esm": "rollup --config rollup.config.mjs --environment MODULE:esm",
-		"bundle:cjs": "rollup --config rollup.config.mjs --environment MODULE:cjs",
-		"bundle": "npm run bundle:esm && npm run bundle:cjs",
-		"docs:clean": "rimraf docs/reference",
-		"docs:generate": "typedoc",
-		"docs": "npm run docs:clean && npm run docs:generate",
-		"dist": "npm run clean && npm run build && npm run test && npm run bundle && npm run docs"
-	},
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next"
 	},
-	"devDependencies": {
-		"@twin.org/nameof-transformer": "next",
-		"@vitest/coverage-v8": "2.1.1",
-		"copyfiles": "2.4.1",
-		"rimraf": "6.0.1",
-		"rollup": "4.21.3",
-		"rollup-plugin-typescript2": "0.36.0",
-		"ts-patch": "3.2.1",
-		"typedoc": "0.26.7",
-		"typedoc-plugin-markdown": "4.2.7",
-		"typescript": "5.6.2",
-		"vitest": "2.1.1"
-	},
 	"main": "./dist/cjs/index.cjs",
 	"module": "./dist/esm/index.mjs",
 	"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",