@twin.org/entity-storage-service 0.0.3-next.2 → 0.0.3-next.21

package/docs/examples.md

@@ -1 +1,77 @@
-# @twin.org/entity-storage-service - Examples
+# Entity Storage Service Examples
+
+Use these snippets to wire a registered connector into the service layer and to expose matching REST routes.
+
+## EntityStorageService
+
+```typescript
+import {
+  EntityStorageService,
+  generateRestRoutesEntityStorage
+} from '@twin.org/entity-storage-service';
+import { EntityStorageConnectorFactory } from '@twin.org/entity-storage-models';
+import { MemoryEntityStorageConnector } from '@twin.org/entity-storage-connector-memory';
+import {
+  ComparisonOperator,
+  LogicalOperator,
+  SortDirection,
+  type EntityCondition
+} from '@twin.org/entity';
+
+interface Profile {
+  id: string;
+  email: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+
+EntityStorageConnectorFactory.register(
+  'profile-storage',
+  () =>
+    new MemoryEntityStorageConnector<Profile>({
+      entitySchema: 'Profile'
+    })
+);
+
+const service = new EntityStorageService<Profile>({
+  entityStorageType: 'profile-storage'
+});
+
+const className = service.className();
+
+await service.set({
+  id: 'profile-1',
+  email: 'ada@example.com',
+  status: 'active',
+  createdAt: '2026-03-09T10:30:00.000Z'
+});
+
+const byPrimaryKey = await service.get('profile-1');
+const bySecondaryIndex = await service.get('ada@example.com', 'email');
+
+const activeCondition: EntityCondition<Profile> = {
+  logicalOperator: LogicalOperator.And,
+  conditions: [
+    {
+      property: 'status',
+      comparison: ComparisonOperator.Equals,
+      value: 'active'
+    }
+  ]
+};
+
+const result = await service.query(
+  activeCondition,
+  'createdAt',
+  SortDirection.Descending,
+  ['id', 'email', 'status'],
+  undefined,
+  25
+);
+
+await service.remove('profile-1');
+
+const routes = generateRestRoutesEntityStorage('/profiles', 'profileStorageComponent', {
+  typeName: 'Profile'
+});
+```

package/docs/open-api/spec.json

@@ -28,6 +28,17 @@
 				"tags": [
 					"EntityStorage"
 				],
+				"parameters": [
+					{
+						"name": "conditions",
+						"description": "The optional conditions to match for the entity, JSON encoded array of property/value pairs.",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
+					}
+				],
 				"security": [
 					{
 						"jwtBearerAuthScheme": []
@@ -115,6 +126,91 @@
 					}
 				}
 			},
+			"delete": {
+				"operationId": "entityStorageEmpty",
+				"summary": "Remove all entries from entity storage.",
+				"tags": [
+					"EntityStorage"
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"requestBody": {
+					"description": "Remove all entries from entity storage.",
+					"required": true,
+					"content": {
+						"text/plain": {
+							"schema": {
+								"$ref": "#/components/schemas/EntityStorageEmptyRequest"
+							}
+						}
+					}
+				},
+				"responses": {
+					"204": {
+						"description": "The rest request ended in success with no data."
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			},
 			"get": {
 				"operationId": "entityStorageList",
 				"summary": "Query entries from entity storage.",
@@ -265,6 +361,200 @@
 				}
 			}
 		},
+		"/entity-storage/batch": {
+			"post": {
+				"operationId": "entityStorageSetBatch",
+				"summary": "Set multiple entries in entity storage.",
+				"tags": [
+					"EntityStorage"
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"requestBody": {
+					"description": "Set multiple entries in entity storage.",
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"$ref": "#/components/schemas/EntityStorageSetBatchRequest"
+							},
+							"examples": {
+								"entityStorageSetBatchRequestExample": {
+									"value": [
+										{
+											"id": "12345",
+											"name": "My Item"
+										},
+										{
+											"id": "67890",
+											"name": "My Other Item"
+										}
+									]
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"204": {
+						"description": "The rest request ended in success with no data."
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			},
+			"delete": {
+				"operationId": "entityStorageRemoveBatch",
+				"summary": "Remove multiple entries from entity storage by id.",
+				"tags": [
+					"EntityStorage"
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"requestBody": {
+					"description": "Remove multiple entries from entity storage by id.",
+					"required": true,
+					"content": {
+						"application/json": {
+							"schema": {
+								"$ref": "#/components/schemas/EntityStorageRemoveBatchRequest"
+							},
+							"examples": {
+								"entityStorageRemoveBatchRequestExample": {
+									"value": [
+										"12345",
+										"67890"
+									]
+								}
+							}
+						}
+					}
+				},
+				"responses": {
+					"204": {
+						"description": "The rest request ended in success with no data."
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
 		"/entity-storage/{id}": {
 			"get": {
 				"operationId": "entityStorageGet",
@@ -292,6 +582,15 @@
 						"schema": {
 							"type": "string"
 						}
+					},
+					{
+						"name": "conditions",
+						"description": "The optional conditions to match for the entity, JSON encoded array of property/value pairs.",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
 					}
 				],
 				"security": [
@@ -415,6 +714,15 @@
 						},
 						"style": "simple",
 						"example": "12345"
+					},
+					{
+						"name": "conditions",
+						"description": "The optional conditions to match for the entity, JSON encoded array of property/value pairs.",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
 					}
 				],
 				"security": [
@@ -506,10 +814,128 @@
 					}
 				}
 			}
+		},
+		"/entity-storage/count": {
+			"get": {
+				"operationId": "entityStorageCount",
+				"summary": "Count entries in entity storage.",
+				"tags": [
+					"EntityStorage"
+				],
+				"parameters": [
+					{
+						"name": "conditions",
+						"description": "The optional conditions to filter the count, JSON encoded EntityCondition.",
+						"in": "query",
+						"required": false,
+						"schema": {
+							"type": "string"
+						}
+					}
+				],
+				"security": [
+					{
+						"jwtBearerAuthScheme": []
+					}
+				],
+				"responses": {
+					"200": {
+						"description": "The response for counting entries in entity storage.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/EntityStorageCountResponse"
+								},
+								"examples": {
+									"entityStorageCountResponseExample": {
+										"value": {
+											"count": 1
+										}
+									}
+								}
+							}
+						}
+					},
+					"400": {
+						"description": "The server cannot process the request, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "GeneralError",
+											"message": "errorMessage",
+											"properties": {
+												"foo": "bar"
+											}
+										}
+									}
+								}
+							}
+						}
+					},
+					"401": {
+						"description": "You are not authorized to use the API or no credentials were supplied, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "UnauthorizedError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					},
+					"500": {
+						"description": "The server has encountered a situation it does not know how to handle, see the content for more details.",
+						"content": {
+							"application/json": {
+								"schema": {
+									"$ref": "#/components/schemas/Error"
+								},
+								"examples": {
+									"exampleResponse": {
+										"value": {
+											"name": "InternalServerError",
+											"message": "errorMessage"
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
 		}
 	},
 	"components": {
 		"schemas": {
+			"EntityStorageCountResponse": {
+				"type": "object",
+				"properties": {
+					"count": {
+						"type": "number",
+						"description": "The total count of entities."
+					}
+				},
+				"required": [
+					"count"
+				],
+				"description": "The body of the response."
+			},
+			"EntityStorageEmptyRequest": {
+				"description": "Remove all entries from entity storage.",
+				"type": "object"
+			},
 			"EntityStorageGetResponse": {
 				"description": "The data for the requested entity."
 			},
@@ -529,13 +955,25 @@
 				"required": [
 					"entities"
 				],
-				"additionalProperties": false,
 				"description": "The list of entries from the query."
 			},
+			"EntityStorageRemoveBatchRequest": {
+				"type": "array",
+				"items": {
+					"type": "string"
+				},
+				"description": "The ids of the entities to remove."
+			},
+			"EntityStorageSetBatchRequest": {
+				"type": "array",
+				"items": {},
+				"description": "The entities to set."
+			},
 			"EntityStorageSetRequest": {
 				"description": "The data to be used in the entity."
 			},
 			"Error": {
+				"description": "Model to describe serialized error.",
 				"type": "object",
 				"properties": {
 					"name": {
@@ -544,7 +982,7 @@
 					},
 					"message": {
 						"type": "string",
-						"description": "The message for the error."
+						"description": "The message for the error as an i18n key."
 					},
 					"source": {
 						"type": "string",
@@ -566,63 +1004,35 @@
 				"required": [
 					"name",
 					"message"
-				],
-				"additionalProperties": false,
-				"description": "Model to describe serialized error."
+				]
 			},
 			"NotFoundResponse": {
 				"type": "object",
-				"additionalProperties": false,
 				"properties": {
 					"notFoundId": {
 						"type": "string",
 						"description": "The id if the item that was not found."
-					},
-					"name": {
-						"type": "string",
-						"description": "The name for the error."
-					},
-					"message": {
-						"type": "string",
-						"description": "The message for the error."
-					},
-					"source": {
-						"type": "string",
-						"description": "The source of the error."
-					},
-					"properties": {
-						"type": "object",
-						"additionalProperties": {},
-						"description": "Any additional information for the error."
-					},
-					"stack": {
-						"type": "string",
-						"description": "The stack trace for the error."
-					},
-					"cause": {
-						"$ref": "#/components/schemas/Error"
 					}
 				},
-				"required": [
-					"message",
-					"name"
+				"allOf": [
+					{
+						"$ref": "#/components/schemas/Error"
+					}
 				],
 				"description": "The body which contains the error."
 			},
 			"SortDirection": {
+				"description": "The sort directions.",
 				"anyOf": [
 					{
-						"type": "string",
 						"const": "asc",
 						"description": "Ascending."
 					},
 					{
-						"type": "string",
 						"const": "desc",
 						"description": "Descending."
 					}
-				],
-				"description": "The sort directions."
+				]
 			}
 		},
 		"securitySchemes": {