### Git Commit Examples

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Provides examples of correctly formatted Git commit messages that adhere to the project's conventions, contrasting them with examples of messages to avoid.

```shell
# Good commit messages
git commit -m "feat: add JWT token validation"
git commit -m "fix: prevent endless loop in data lookup"
git commit -m "docs: update installation instructions"

# Bad commit messages (avoid these)
git commit -m "fix stuff"
git commit -m "WIP"
git commit -m "changes"
```

--------------------------------

### Clone Repository and Install Dependencies (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Instructions for cloning the project repository and installing necessary npm dependencies. Assumes Git and Node.js (v20.x+) are installed.

```shell
git clone https://github.com/twinfoundation/<repo>.git
cd <repo>
npm install
```

--------------------------------

### Run MySQL Docker Container for Testing

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/README.md

Starts a MySQL Docker container named 'twin-entity-storage-mysql' on port 3400 for local testing. This requires Docker to be installed and running.

```shell
docker run -p 3400:3306 --name twin-entity-storage-mysql --hostname mysql -e MYSQL_ROOT_PASSWORD=password -d mysql:latest
```

--------------------------------

### Run Local DynamoDB Instance for Testing

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-dynamodb/README.md

Starts a local DynamoDB instance using Docker for running functional tests. This requires Docker to be installed and running on your system.

```shell
docker run -p 10000:8000 --name twin-entity-storage-dynamodb --hostname dynamodb -d amazon/dynamodb-local
```

--------------------------------

### Install MySQL Entity Storage Connector

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/README.md

Installs the TWIN Entity Storage Connector for MySQL using npm. This is the primary step to integrate the connector into your project.

```shell
npm install @twin.org/entity-storage-connector-mysql
```

--------------------------------

### Install Entity Storage Service using npm

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/README.md

This snippet shows how to install the TWIN Entity Storage Service using the npm package manager. It is a prerequisite for using the service.

```shell
npm install @twin.org/entity-storage-service
```

--------------------------------

### Install TWIN Entity Storage Packages

Source: https://context7.com/twinfoundation/entity-storage/llms.txt

Installs the core models, service layer, REST client, and various storage connectors for TWIN Entity Storage. Choose connectors based on your specific storage needs.

```shell
# Core models and interfaces
npm install @twin.org/entity-storage-models

# Service layer with REST endpoints
npm install @twin.org/entity-storage-service

# REST client for remote access
npm install @twin.org/entity-storage-rest-client

# Storage connectors (choose as needed)
npm install @twin.org/entity-storage-connector-memory
npm install @twin.org/entity-storage-connector-file
npm install @twin.org/entity-storage-connector-postgresql
npm install @twin.org/entity-storage-connector-mysql
npm install @twin.org/entity-storage-connector-mongodb
npm install @twin.org/entity-storage-connector-dynamodb
npm install @twin.org/entity-storage-connector-cosmosdb
npm install @twin.org/entity-storage-connector-scylladb
npm install @twin.org/entity-storage-connector-gcp-firestore
```

--------------------------------

### Install DynamoDB Entity Storage Connector

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-dynamodb/README.md

Installs the DynamoDB entity storage connector package using npm. This is the primary step to include the connector in your project.

```shell
npm install @twin.org/entity-storage-connector-dynamodb
```

--------------------------------

### Install MongoDB Entity Storage Connector

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mongodb/README.md

Installs the MongoDB entity storage connector package using npm. This is a prerequisite for using the connector in your project.

```shell
npm install @twin.org/entity-storage-connector-mongodb
```

--------------------------------

### EntityStorageService Methods

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/classes/EntityStorageService.md

Provides methods for interacting with the entity storage, including setting, getting, removing, and querying entities.

```APIDOC
## POST /entities

### Description
Sets an entity in the storage. If the entity with the same ID already exists, it will be overwritten.

### Method
POST

### Endpoint
`/entities`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **entity** (T) - Required - The entity object to be stored.

### Request Example
```json
{
  "entity": {
    "id": "unique-entity-id",
    "name": "Example Entity",
    "value": 123
  }
}
```

### Response
#### Success Response (200)
- **void** - Indicates the operation was successful.

#### Response Example
```json
// No response body on success
```
```

```APIDOC
## GET /entities/{id}

### Description
Retrieves an entity from the storage by its ID or a secondary index.

### Method
GET

### Endpoint
`/entities/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity to retrieve, or the index value if `secondaryIndex` is provided.

#### Query Parameters
- **secondaryIndex** (keyof T) - Optional - Specifies a secondary index to use for retrieving the entity.

#### Request Body
None

### Request Example
```http
GET /entities/unique-entity-id
```

### Response
#### Success Response (200)
- **entity** (T | undefined) - The retrieved entity object, or undefined if not found.

#### Response Example
```json
{
  "id": "unique-entity-id",
  "name": "Example Entity",
  "value": 123
}
```
```

```APIDOC
## DELETE /entities/{id}

### Description
Removes an entity from the storage by its ID.

### Method
DELETE

### Endpoint
`/entities/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the entity to remove.

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
DELETE /entities/unique-entity-id
```

### Response
#### Success Response (200)
- **void** - Indicates the operation was successful.

#### Response Example
```json
// No response body on success
```
```

```APIDOC
## POST /entities/query

### Description
Queries entities from the storage based on specified conditions, ordering, and pagination.

### Method
POST

### Endpoint
`/entities/query`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **conditions** (EntityCondition<T>) - Optional - The conditions to match for the entities.
- **orderBy** (keyof T) - Optional - The field to order the results by.
- **orderByDirection** (SortDirection) - Optional - The direction for the order (defaults to ascending).
- **properties** (keyof T[]) - Optional - An array of properties to return for each entity (defaults to all).
- **cursor** (string) - Optional - A cursor for requesting the next chunk of entities.
- **limit** (number) - Optional - The suggested number of entities to return in each chunk.

#### Request Body
None

### Request Example
```json
{
  "conditions": {
    "name": "Example Entity"
  },
  "orderBy": "value",
  "orderByDirection": "DESC",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **entities** (Partial<T>[]) - An array of entities matching the query conditions.
- **cursor** (string) - A cursor for fetching the next page of results, if available.

#### Response Example
```json
{
  "entities": [
    {
      "id": "entity-1",
      "name": "Example Entity",
      "value": 200
    },
    {
      "id": "entity-2",
      "name": "Example Entity",
      "value": 150
    }
  ],
  "cursor": "next-page-cursor-string"
}
```
```

```APIDOC
## GET /entities/className

### Description
Returns the runtime class name of the component.

### Method
GET

### Endpoint
`/entities/className`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
GET /entities/className
```

### Response
#### Success Response (200)
- **className** (string) - The runtime class name of the component.

#### Response Example
```json
{
  "className": "EntityStorageService"
}
```
```

--------------------------------

### Run MongoDB Locally with Docker

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mongodb/README.md

Starts a MongoDB instance locally using Docker for testing purposes. This command maps the container's port 27017 to the host's port 27500 and names the container 'twin-entity-storage-mongodb'.

```shell
docker run -p 27500:27017 --name twin-entity-storage-mongodb --hostname mongo -d mongo
```

--------------------------------

### Get Entity from Storage

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/functions/entityStorageGet.md

Retrieves an entry from the entity storage using the provided component name and request details.

```APIDOC
## GET /entityStorageGet

### Description
Retrieves an entry from the entity storage.

### Method
GET

### Endpoint
/entityStorageGet

### Parameters
#### Query Parameters
- **componentName** (string) - Required - The name of the component to use in the routes.
- **request** (IEntityStorageGetRequest) - Required - The request object containing details for retrieval.

### Request Example
```json
{
  "componentName": "exampleComponent",
  "request": {
    "entityId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

### Response
#### Success Response (200)
- **entity** (object) - The retrieved entity object.
- **metadata** (object) - Metadata associated with the entity.

#### Response Example
```json
{
  "entity": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Example Entity",
    "value": 100
  },
  "metadata": {
    "createdAt": "2023-10-27T10:00:00Z",
    "updatedAt": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### get()

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-scylladb/docs/reference/classes/ScyllaDBViewConnector.md

Retrieves a single entity by its ID, optionally using a secondary index and conditions.

```APIDOC
## GET /entities/{id}

### Description
Get an entity by its ID.

### Method
GET

### Endpoint
/entities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The id of the entity to get.

#### Query Parameters
- **secondaryIndex** (keyof T) - Optional - Get the item using a secondary index.
- **conditions** (object[]) - Optional - The optional conditions to match for the entities.

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **entity** (T | undefined) - The object if it can be found or undefined.

#### Response Example
```json
{
  "entity": { ... } 
}
```
```

--------------------------------

### Get Entity

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-models/docs/reference/interfaces/IEntityStorageGetRequest.md

Retrieves a specific entry from the entity storage using its ID and optional secondary index.

```APIDOC
## GET /entity/{id}

### Description
Get an entry from entity storage.

### Method
GET

### Endpoint
/entity/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The id of the entity to get.

#### Query Parameters
- **secondaryIndex** (string) - Optional - The secondary index to query with the id.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **entity** (object) - The retrieved entity data.

#### Response Example
```json
{
  "example": "{\"id\": \"some-entity-id\", \"data\": {}}"
}
```
```

--------------------------------

### Create Feature Branch (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Steps to create a new feature branch from the 'next' development branch, following the project's branch naming conventions. This is the starting point for new development.

```shell
git checkout next
git pull origin next
git checkout -b feat/your-feature-name
```

--------------------------------

### bootstrap()

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-scylladb/docs/reference/classes/ScyllaDBViewConnector.md

Initializes the component by creating and setting up necessary resources.

```APIDOC
## POST /bootstrap

### Description
Bootstrap the component by creating and initializing any resources it needs.

### Method
POST

### Endpoint
/bootstrap

### Parameters
#### Path Parameters
N/A

#### Query Parameters
- **nodeLoggingComponentType** (string) - Optional - The node logging component type.

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **success** (boolean) - True if the bootstrapping process was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Bootstrap MongoDb Environment

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mongodb/docs/reference/classes/MongoDbEntityStorageConnector.md

Initializes the MongoDB environment for the entity storage connector. This method should be called before performing any storage operations.

```APIDOC
## bootstrap(nodeLoggingComponentType?: string): Promise<boolean>

### Description
Initialize the MongoDb environment.

### Method
POST

### Endpoint
/bootstrap

### Parameters
#### Query Parameters
- **nodeLoggingComponentType** (string) - Optional - Optional type of the logging component.

#### Returns
`Promise<boolean>` - A promise that resolves to a boolean indicating success.

### Response
#### Success Response (200)
- **boolean** - Indicates if the bootstrap process was successful.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### ScyllaDB View Connector Constructor Options

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-scylladb/docs/reference/interfaces/IScyllaDBViewConnectorConstructorOptions.md

Provides details on the properties required and optional for configuring the ScyllaDB View Connector.

```APIDOC
## ScyllaDB View Connector Constructor Options

### Description
Options for the ScyllaDB View Connector constructor.

### Method
N/A (Constructor Options)

### Endpoint
N/A (Constructor Options)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### Properties
- **loggingComponentType** (string) - Optional - The type of logging component to use, defaults to no logging.
- **entitySchema** (string) - Required - The name of the entity schema.
- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.
- **viewSchema** (string) - Required - The name of the view schema.
- **config** (IScyllaDBViewConfig) - Required - The configuration for the connector.

### Request Example
```json
{
  "loggingComponentType": "my-log-type",
  "entitySchema": "my-entity-schema",
  "partitionContextIds": ["id1", "id2"],
  "viewSchema": "my-view-schema",
  "config": {
    "keyspace": "my-keyspace",
    "table": "my-table"
  }
}
```

### Response
#### Success Response (N/A for constructor options)
N/A

#### Response Example
N/A
```

--------------------------------

### EntityStorageService Constructor

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/classes/EntityStorageService.md

Initializes a new instance of the EntityStorageService. This service is generic and can handle entities of any type T.

```APIDOC
## Constructor EntityStorageService<T>

### Description
Creates a new instance of EntityStorageService.

### Method
CONSTRUCTOR

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
const options = { /* dependency injection options */ };
const entityStorage = new EntityStorageService<MyEntityType>(options);
```

### Response
#### Success Response (200)
An instance of EntityStorageService<T>.

#### Response Example
```typescript 
// No direct response body for constructor, returns an instance.
```
```

--------------------------------

### MySqlEntityStorageConnector Constructor

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/docs/reference/classes/MySqlEntityStorageConnector.md

Initializes a new instance of MySqlEntityStorageConnector. It requires an options object conforming to IMySqlEntityStorageConnectorConstructorOptions.

```typescript
new MySqlEntityStorageConnector<T>(options: IMySqlEntityStorageConnectorConstructorOptions)
```

--------------------------------

### Release Process: Next (Prerelease) Versions

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Details the steps for preparing and publishing prerelease versions from the `next` branch. This involves using GitHub Actions to create a PR for version bumps and changelog updates, followed by publishing to NPM with the `next` tag.

```markdown
1. **Prepare Release**:
   - Run `Prepare Release` GitHub Action on `next` branch
   - Set semver type to `prerelease`
   - This creates a PR with version bumps and changelog updates

2. **Review & Merge**:
   - Review the generated PR carefully
   - Merge the PR to `next` branch

3. **Publish**:
   - Run `Publish Release` GitHub Action
   - Publishes packages to NPM with `next` tag
   - Creates GitHub releases marked as prerelease
```

--------------------------------

### Entity Storage Service Constructor Options

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/interfaces/IEntityStorageServiceConstructorOptions.md

Defines the structure for options passed to the Entity Storage Service constructor.

```APIDOC
## Entity Storage Service Constructor Options

### Description
Options for the Entity Storage Service constructor.

### Properties

#### entityStorageType
- **entityStorageType** (string) - Required - The type of the entity storage.

#### config
- **config** (IEntityStorageServiceConfig) - Optional - The configuration for the service.

### Request Example
```json
{
  "entityStorageType": "someType",
  "config": {
    "someConfigField": "someValue"
  }
}
```

### Response
#### Success Response (200)
- **entityStorageType** (string) - The type of the entity storage.
- **config** (IEntityStorageServiceConfig) - The configuration for the service.

#### Response Example
```json
{
  "entityStorageType": "defaultStorage",
  "config": {
    "retries": 3
  }
}
```
```

--------------------------------

### MySqlEntityStorageConnector Bootstrap

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/docs/reference/classes/MySqlEntityStorageConnector.md

Initializes the MySQL environment for the entity storage connector. It can optionally accept a node logging component type. Returns a promise that resolves to a boolean indicating success.

```typescript
bootstrap(nodeLoggingComponentType?: string): Promise<boolean>
```

--------------------------------

### IPostgreSqlEntityStorageConnectorConstructorOptions

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-postgresql/docs/reference/interfaces/IPostgreSqlEntityStorageConnectorConstructorOptions.md

Defines the structure for the constructor options of the PostgreSql entity storage connector.

```APIDOC
## Interface: IPostgreSqlEntityStorageConnectorConstructorOptions

### Description
The options for the PostgreSql entity storage connector constructor.

### Properties

#### entitySchema
- **entitySchema** (string) - Required - The schema for the entity.

#### partitionContextIds
- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.

#### loggingComponentType
- **loggingComponentType** (string) - Optional - The type of logging component to use. Defaults to 'logging'.

#### config
- **config** (IPostgreSqlEntityStorageConnectorConfig) - Required - The configuration for the connector.

### Request Example
```json
{
  "entitySchema": "my_schema",
  "partitionContextIds": ["id1", "id2"],
  "loggingComponentType": "custom_logger",
  "config": {
    "connectionString": "postgresql://user:password@host:port/database"
  }
}
```

### Response
(This interface describes constructor options, not a direct API response.)

#### Success Response (N/A)

#### Response Example (N/A)
```

--------------------------------

### Get Entity Schema

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mongodb/docs/reference/classes/MongoDbEntityStorageConnector.md

Retrieves the schema definition for the entities managed by this storage connector.

```APIDOC
## getSchema(): IEntitySchema

### Description
Get the schema for the entities.

### Method
GET

### Endpoint
/schema

### Returns
`IEntitySchema` - The schema for the entities.

### Response
#### Success Response (200)
- **IEntitySchema** - The schema object.

### Response Example
```json
{
  "schema": {
    "fields": [
      {
        "name": "id",
        "type": "string"
      }
    ]
  }
}
```
```

--------------------------------

### Get Entity by ID

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mongodb/docs/reference/classes/MongoDbEntityStorageConnector.md

Retrieves a single entity from MongoDB based on its ID or a secondary index.

```APIDOC
## get(id: string, secondaryIndex?: keyof T, conditions?: object[]): Promise<T | undefined>

### Description
Get an entity from MongoDb.

### Method
GET

### Endpoint
/entities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The id of the entity to get, or the index value if secondaryIndex is set.

#### Query Parameters
- **secondaryIndex** (keyof T) - Optional - Get the item using a secondary index.
- **conditions** (object[]) - Optional - The optional conditions to match for the entities.

#### Returns
`Promise<T | undefined>` - The object if it can be found or undefined.

### Response
#### Success Response (200)
- **T | undefined** - The found entity or undefined if not found.

### Response Example
```json
{
  "id": "entity-123",
  "name": "Example Entity"
}
```
```

--------------------------------

### ScyllaDBViewConnector Constructor

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-scylladb/docs/reference/classes/ScyllaDBViewConnector.md

Creates a new instance of ScyllaDBViewConnector.

```APIDOC
## new ScyllaDBViewConnector()

### Description
Create a new instance of ScyllaDBViewConnector.

### Method
CONSTRUCTOR

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### MySqlEntityStorageConnector Get Schema

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/docs/reference/classes/MySqlEntityStorageConnector.md

Retrieves the entity schema managed by this connector. This method is part of the IEntityStorageConnector interface implementation.

```typescript
getSchema(): IEntitySchema
```

--------------------------------

### Get Class Name

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-cosmosdb/docs/reference/classes/CosmosDbEntityStorageConnector.md

Returns the runtime class name of the component. This is a utility method for identifying the component type.

```typescript
/**
 * Returns the class name of the component.
 * @returns The class name of the component.
 */
className(): string
```

--------------------------------

### Get Entity Schema

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-cosmosdb/docs/reference/classes/CosmosDbEntityStorageConnector.md

Retrieves the schema definition for the entities managed by this connector. This is useful for understanding the structure and types of the stored entities.

```typescript
/**
 * Get the schema for the entities.
 * @returns The schema for the entities.
 */
getSchema(): IEntitySchema
```

--------------------------------

### MySqlEntityStorageConnector Get Entity

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/docs/reference/classes/MySqlEntityStorageConnector.md

Retrieves a single entity from MySQL based on its ID or a secondary index. Optional conditions can be provided for filtering. Returns a promise that resolves to the entity or undefined if not found.

```typescript
get(id: string, secondaryIndex?: keyof T, conditions?: object[]): Promise<T | undefined>
```

--------------------------------

### MySql Entity Storage Connector Options

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-mysql/docs/reference/interfaces/IMySqlEntityStorageConnectorConstructorOptions.md

Details the properties and types for configuring the MySql entity storage connector.

```APIDOC
## Interface: IMySqlEntityStorageConnectorConstructorOptions

The options for the MySql entity storage connector constructor.

### Properties

#### entitySchema
- **entitySchema** (string) - Required - The schema for the entity.

#### partitionContextIds
- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.

#### loggingComponentType
- **loggingComponentType** (string) - Optional - The type of logging component to use.
  - Default: `logging`

#### config
- **config** (IMySqlEntityStorageConnectorConfig) - Required - The configuration for the connector.
```

--------------------------------

### Entity Storage REST Routes Generation

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/functions/generateRestRoutesEntityStorage.md

This function generates REST routes for entity storage. It allows customization through base route names, component names, and optional configurations like type names, tag names, and examples.

```APIDOC
## Function: generateRestRoutesEntityStorage()

### Description
Generates the REST routes for entity storage.

### Method
N/A (This is a function signature, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Function Signature
`generateRestRoutesEntityStorage(baseRouteName: string, componentName: string, options?: { typeName?: string; tagName?: string; examples?: IEntityStorageRoutesExamples }): IRestRoute<any, any>[]`

### Parameters
#### `baseRouteName`
- **Type**: `string`
- **Description**: Prefix to prepend to the paths.

#### `componentName`
- **Type**: `string`
- **Description**: The name of the component to use in the routes stored in the ComponentFactory.

#### `options` (Optional)
- **Type**: `object`
- **Description**: Additional options for the routes.
  - #### `typeName` (Optional)
    - **Type**: `string`
    - **Description**: Optional type name to use in the routes, defaults to Entity Storage.
  - #### `tagName` (Optional)
    - **Type**: `string`
    - **Description**: Optional name to use in OpenAPI spec for tag.
  - #### `examples` (Optional)
    - **Type**: `IEntityStorageRoutesExamples`
    - **Description**: Optional examples to use in the routes.

### Returns
- **Type**: `IRestRoute<any, any>[]`
- **Description**: The generated routes.
```

--------------------------------

### IMemoryEntityStorageConnectorConstructorOptions

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-memory/docs/reference/interfaces/IMemoryEntityStorageConnectorConstructorOptions.md

Provides options for the Memory Entity Storage Connector constructor, including entity schema and partition context IDs.

```APIDOC
## IMemoryEntityStorageConnectorConstructorOptions

### Description
Options for the Memory Entity Storage Connector constructor.

### Properties

#### entitySchema
- **entitySchema** (string) - Required - The schema for the entity.

#### partitionContextIds
- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.
```

--------------------------------

### API Documentation Generation with TypeDoc

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Explains that API documentation is automatically generated from TypeScript comments using the TypeDoc tool. It outlines the sources of documentation, including JSDoc comments in source files and additional content within package `docs/` folders.

```markdown
Documentation is auto-generated from TypeScript comments using **TypeDoc**:

### Documentation Structure

- **Source Comments**: JSDoc comments in TypeScript source files
- **Package Docs**: Additional content in each package's `docs/` folder
- **Auto-Generation**: Built documentation is merged into the main docs site
```

--------------------------------

### Get Entity from Cosmos DB

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-cosmosdb/docs/reference/classes/CosmosDbEntityStorageConnector.md

Retrieves a single entity from Cosmos DB based on its ID or a secondary index. Supports optional conditions for more specific retrieval. Returns the entity if found, otherwise undefined.

```typescript
/**
 * Get an entity from Cosmos DB.
 * @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?: object[]): Promise<T | undefined>
```

--------------------------------

### Release Failure Recovery

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Provides guidance on how to recover if the `Prepare Release` GitHub Action fails, which can prevent future releases. It suggests looking for and removing the `autorelease: pending` tag from relevant PRs.

```markdown
If running `Prepare Release` fails it will most likely leave a PR in a state where it is impossible to generate a new release. If this happens then look for a PR (might be closed) that is tagged with `autorelease: pending` and remove the tag.
```

--------------------------------

### EntityStorageRestClient for Consuming Entity Storage (TypeScript)

Source: https://context7.com/twinfoundation/entity-storage/llms.txt

Provides a TypeScript client for interacting with remote entity storage endpoints. It mirrors the service interface for operations like set, get, remove, and query. Dependencies include '@twin.org/entity-storage-rest-client' and '@twin.org/entity'.

```typescript
import { EntityStorageRestClient } from "@twin.org/entity-storage-rest-client";
import { SortDirection } from "@twin.org/entity";

// Create client instance
const client = new EntityStorageRestClient<User>({
  endpoint: "http://localhost:3000/api/users"
});

// All operations mirror the service interface
await client.set({
  id: "user-005",
  email: "eve@example.com",
  name: "Eve Williams",
  age: 27,
  isActive: true
});

const user = await client.get("user-005");
const userByEmail = await client.get("eve@example.com", "email");

await client.remove("user-005");

// Query with full options
const result = await client.query(
  { property: "age", value: 25, comparison: ComparisonOperator.GreaterThan },
  "name",
  SortDirection.Ascending,
  ["id", "name", "email"],
  undefined,
  50
);

// Paginate through results
let cursor: string | undefined;
do {
  const page = await client.query(undefined, undefined, undefined, undefined, cursor, 10);
  console.log(`Got ${page.entities.length} entities`);
  cursor = page.cursor;
} while (cursor);
```

--------------------------------

### IScyllaDBTableConnectorConstructorOptions

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-scylladb/docs/reference/interfaces/IScyllaDBTableConnectorConstructorOptions.md

Defines the configuration options for creating a ScyllaDB Table Connector.

```APIDOC
## Interface: IScyllaDBTableConnectorConstructorOptions

Options for the ScyllaDB Table Connector constructor.

### Properties

#### loggingComponentType

- **loggingComponentType** (string) - Optional - The type of logging component to use, defaults to no logging.

#### entitySchema

- **entitySchema** (string) - Required - The name of the entity schema.

#### partitionContextIds

- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.

#### config

- **config** (IScyllaDBTableConfig) - Required - The configuration for the connector.
```

--------------------------------

### Retrieve Entity from Storage using entityStorageGet

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-service/docs/reference/functions/entityStorageGet.md

The entityStorageGet function retrieves a specific entry from entity storage. It requires an httpRequestContext, the componentName, and a request object. The function returns a Promise that resolves with the IEntityStorageGetResponse, which includes additional HTTP response properties.

```typescript
/**
 * Get the entry from entity storage.
 * @param httpRequestContext The request context for the API.
 * @param componentName The name of the component to use in the routes.
 * @param request The request.
 * @returns A Promise resolving to the response object with additional http response properties.
 */
async function entityStorageGet(httpRequestContext: IHttpRequestContext, componentName: string, request: IEntityStorageGetRequest): Promise<IEntityStorageGetResponse> {
  // Implementation details would go here
  return {} as IEntityStorageGetResponse;
}
```

--------------------------------

### Version Strategy Table

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Summarizes the versioning strategy for different branches, indicating their purpose, the corresponding NPM tag used for publishing, and the type of GitHub release generated.

```markdown
| Branch | Purpose             | NPM Tag  | GitHub Release |
| ------ | ------------------- | -------- | -------------- |
| `next` | Development/Testing | `next`   | Prerelease     |
| `main` | Production          | `latest` | Stable         |
```

--------------------------------

### Entity Storage Service for TypeScript

Source: https://context7.com/twinfoundation/entity-storage/llms.txt

Provides a unified service layer that wraps storage connectors, offering a consistent interface for operations. It integrates with a connector factory for dependency injection and supports operations like setting, getting by ID or secondary index, removing, and querying with pagination.

```typescript
import { EntityStorageService } from "@twin.org/entity-storage-service";
import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
import { MemoryEntityStorageConnector } from "@twin.org/entity-storage-connector-memory";
import { SortDirection } from "@twin.org/entity";

// Register connector with factory
EntityStorageConnectorFactory.register(
  "user-storage",
  () => new MemoryEntityStorageConnector<User>({ entitySchema: "User" })
);

// Create service instance
const userService = new EntityStorageService<User>({
  entityStorageType: "user-storage"
});

// Service provides same operations as connector
await userService.set({
  id: "user-004",
  email: "diana@example.com",
  name: "Diana Prince",
  age: 30,
  isActive: true
});

// Get by ID (throws NotFoundError if not found)
try {
  const user = await userService.get("user-004");
  console.log(user.name); // "Diana Prince"
} catch (error) {
  // Handle NotFoundError
}

// Get by secondary index
const userByEmail = await userService.get("diana@example.com", "email");

// Remove entity
await userService.remove("user-004");

// Query with pagination
const queryResult = await userService.query(
  undefined, // no conditions - get all
  "name", // order by
  SortDirection.Descending,
  ["id", "name"], // properties to return
  undefined, // cursor
  20 // limit
);

console.log(queryResult.entities); // Partial<User>[]
console.log(queryResult.cursor); // string | undefined for pagination
```

--------------------------------

### File Entity Storage Connector Configuration

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-file/docs/reference/interfaces/IFileEntityStorageConnectorConfig.md

Provides configuration details for the File Entity Storage Connector, specifying the directory for storage.

```APIDOC
## Interface IFileEntityStorageConnectorConfig

### Description
Configuration for the File Entity Storage Connector.

### Properties

#### directory
- **directory** (string) - Required - The directory to use for storage.
```

--------------------------------

### Release Process: Production Versions

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Describes the procedure for releasing stable production versions. This includes preparing the `main` branch by merging from `next`, then using GitHub Actions for version bumps and publishing to NPM with the `latest` tag, followed by updating the `next` branch.

```markdown
1. **Prepare Main Branch**:
   - Run `Versions Prepare` on `main` branch
   - Set type to `production`
   - Creates PR merging `next` to `main`

2. **Merge to Main**:
   - Review and merge the preparation PR

3. **Prepare Release**:
   - Run `Prepare Release` GitHub Action on `main` branch
   - Choose semver type: `major`, `minor`, or `patch`
   - Creates PR with version bumps and changelog updates

4. **Merge Release**:
   - Review and merge the release PR

5. **Publish**:
   - Run `Publish Release` GitHub Action
   - Publishes packages to NPM with `latest` tag
   - Creates stable GitHub releases

6. **Update Next Branch**:
   - Run `Versions Prepare` on `next` branch
   - Updates `next` branch versions to reflect published version
```

--------------------------------

### Package-Level Development Commands (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Development commands specific to individual packages within the monorepo, offering faster builds, watch modes, documentation generation, and testing options.

```shell
# Build without tests (faster during development)
npm run build

# Watch the files and auto build and package when spotting changes
npm run dev

# Build the docs
npm run docs

# Run the tests
npm run test

# Run the tests with coverage
npm run test:coverage

# Complete build (build, package, test and docs)
npm run dist
```

--------------------------------

### PostgreSql Entity Storage Connector Configuration

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-postgresql/docs/reference/interfaces/IPostgreSqlEntityStorageConnectorConfig.md

Defines the configuration parameters required for connecting to and utilizing a PostgreSql database for entity storage.

```APIDOC
## PostgreSql Entity Storage Connector Configuration

### Description
Configuration for the PostgreSql Entity Storage Connector.

### Method
N/A (Configuration Object)

### Endpoint
N/A (Configuration Object)

### Parameters
#### Request Body
- **host** (string) - Required - The host for the PostgreSql instance.
- **port** (number) - Optional - The port for the PostgreSql instance.
- **user** (string) - Required - The user for the PostgreSql instance.
- **password** (string) - Required - The password for the PostgreSql instance.
- **database** (string) - Required - The name of the database to be used.
- **tableName** (string) - Required - The name of the table to be used.

### Request Example
```json
{
  "host": "localhost",
  "port": 5432,
  "user": "admin",
  "password": "secret",
  "database": "entitydb",
  "tableName": "entities"
}
```

### Response
#### Success Response (200)
This configuration object is typically used in a request body or as part of a larger configuration structure. A direct success response is not applicable for this definition.

#### Response Example
N/A
```

--------------------------------

### IFirestoreEntityStorageConnectorConstructorOptions

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-connector-gcp-firestore/docs/reference/interfaces/IFirestoreEntityStorageConnectorConstructorOptions.md

Options for the Firestore Entity Storage Connector constructor.

```APIDOC
## Interface: IFirestoreEntityStorageConnectorConstructorOptions

Options for the Firestore Entity Storage Connector constructor.

### Properties

#### entitySchema

- **entitySchema** (string) - Required - The schema for the entity.

#### partitionContextIds

- **partitionContextIds** (string[]) - Optional - The keys to use from the context ids to create partitions.

#### loggingComponentType

- **loggingComponentType** (string) - Optional - The type of logging component to use, defaults to no logging.

#### config

- **config** (IFirestoreEntityStorageConnectorConfig) - Required - The configuration for the connector.
```

--------------------------------

### Repository-Level Development Commands (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Common development commands available at the root of the repository for formatting, linting, and building the project. These ensure code quality and project integrity.

```shell
# Format code with Prettier
npm run format

# Run ESLint checks
npm run lint

# Perform a complete build
npm run dist
```

--------------------------------

### Quality Requirements Check (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Combined command to ensure code quality by running formatting, linting, and a full build. This should be executed before committing code.

```shell
npm run format && npm run lint && npm run dist
```

--------------------------------

### Build Project (Shell)

Source: https://github.com/twinfoundation/entity-storage/blob/next/CONTRIBUTING.md

Command to perform a full build of the monorepo, including cleaning, compiling, testing, packaging, and generating documentation. This is a core development command.

```shell
npm run dist
```

--------------------------------

### Entity Storage Component API

Source: https://github.com/twinfoundation/entity-storage/blob/next/packages/entity-storage-models/docs/reference/interfaces/IEntityStorageComponent.md

This section details the methods available for interacting with the entity storage component.

```APIDOC
## Entity Storage Component API

This API provides functionalities to set, get, remove, and query entities within a storage component.

### set()

#### Description
Sets an entity in the storage.

#### Method
POST

#### Endpoint
/entity-storage

#### Parameters
##### Request Body
- **entity** (T) - Required - The entity object to set.

#### Request Example
```json
{
  "entity": { ... }
}
```

#### Response
##### Success Response (200)
- **void** - Indicates the entity was successfully set.

### get()

#### Description
Retrieves an entity from the storage by its ID or a secondary index.

#### Method
GET

#### Endpoint
/entity-storage/{id}

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the entity to retrieve, or the index value if secondaryIndex is set.
##### Query Parameters
- **secondaryIndex** (keyof T) - Optional - Specifies a secondary index to use for retrieval.

#### Response
##### Success Response (200)
- **T | undefined** - The entity object if found, otherwise undefined.

#### Response Example
```json
{
  "entity": { ... }
}
```

### remove()

#### Description
Removes an entity from the storage by its ID.

#### Method
DELETE

#### Endpoint
/entity-storage/{id}

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the entity to remove.

#### Response
##### Success Response (200)
- **void** - Indicates the entity was successfully removed.

### query()

#### Description
Queries entities based on specified conditions, ordering, and properties.

#### Method
POST

#### Endpoint
/entity-storage/query

#### Parameters
##### Request Body
- **conditions** (EntityCondition<T>) - Optional - The conditions to match for the entities.
- **orderBy** (keyof T) - Optional - The field to order the results by.
- **orderByDirection** (SortDirection) - Optional - The direction for the order (defaults to ascending).
- **properties** (keyof T[]) - Optional - An array of properties to return (defaults to all).
- **cursor** (string) - Optional - A cursor for requesting the next chunk of entities.
- **limit** (number) - Optional - The suggested number of entities to return per chunk.

#### Request Example
```json
{
  "conditions": { ... },
  "orderBy": "fieldName",
  "orderByDirection": "desc",
  "properties": ["prop1", "prop2"],
  "cursor": "someCursor",
  "limit": 10
}
```

#### Response
##### Success Response (200)
- **entities** (Partial<T>[]) - An array of entities matching the query.
- **cursor** (string) - An optional cursor for fetching the next page of results.

#### Response Example
```json
{
  "entities": [
    { ... },
    { ... }
  ],
  "cursor": "nextCursor"
}
```
```

--------------------------------

### Interact with Entity Storage REST API using curl (Bash)

Source: https://context7.com/twinfoundation/entity-storage/llms.txt

Demonstrates how to interact with the generated REST API endpoints using curl commands. Covers creating/updating, retrieving by ID or secondary index, deleting, and querying entities with various options like conditions, sorting, and pagination. Assumes the service is running on http://localhost:3000.

```bash
# Create or update an entity
curl -X POST http://localhost:3000/api/users/ \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user-001",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "age": 28,
    "isActive": true
  }'
# Response: 204 No Content

# Get an entity by ID
curl -X GET http://localhost:3000/api/users/user-001
# Response: { "body": { "id": "user-001", "email": "alice@example.com", ... } }

# Get an entity by secondary index
curl -X GET "http://localhost:3000/api/users/alice@example.com?secondaryIndex=email"
# Response: { "body": { "id": "user-001", "email": "alice@example.com", ... } }

# Delete an entity
curl -X DELETE http://localhost:3000/api/users/user-001
# Response: 204 No Content

# Query all entities
curl -X GET http://localhost:3000/api/users/
# Response: { "body": { "entities": [...], "cursor": "..." } }

# Query with conditions (URL-encoded JSON)
curl -X GET "http://localhost:3000/api/users/?conditions=%7B%22property%22%3A%22isActive%22%2C%22value%22%3Atrue%2C%22comparison%22%3A%22eq%22%7D"

# Query with sorting and pagination
curl -X GET "http://localhost:3000/api/users/?orderBy=name&orderByDirection=asc&limit=10&cursor=20"

# Query with specific properties
curl -X GET "http://localhost:3000/api/users/?properties=id,name,email"
```