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

package/docs/examples.md

@@ -1 +1,105 @@
-# @twin.org/entity-storage-connector-mysql - Examples
+# Entity Storage Connector MySQL Examples
+
+This page focuses on full connector lifecycle work, from initial bootstrap and entity access to schema maintenance and connection shutdown.
+
+## MySqlEntityStorageConnector
+
+```typescript
+import {
+  MySqlEntityStorageConnector,
+  type IMySqlEntityStorageConnectorConstructorOptions
+} from '@twin.org/entity-storage-connector-mysql';
+import {
+  ComparisonOperator,
+  LogicalOperator,
+  SortDirection,
+  type EntityCondition
+} from '@twin.org/entity';
+
+interface Profile {
+  id: string;
+  email: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+
+const options: IMySqlEntityStorageConnectorConstructorOptions = {
+  entitySchema: 'Profile',
+  config: {
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'root',
+    database: 'entity_storage',
+    tableName: 'profiles'
+  }
+};
+
+const connector = new MySqlEntityStorageConnector<Profile>(options);
+await connector.bootstrap();
+
+const className = connector.className();
+const schema = connector.getSchema();
+
+await connector.set({
+  id: 'profile-1',
+  email: 'ada@example.com',
+  status: 'active',
+  createdAt: '2026-03-09T10:30:00.000Z'
+});
+
+const byPrimaryKey = await connector.get('profile-1');
+const bySecondaryIndex = await connector.get('ada@example.com', 'email');
+
+const activeCondition: EntityCondition<Profile> = {
+  logicalOperator: LogicalOperator.And,
+  conditions: [
+    {
+      property: 'status',
+      comparison: ComparisonOperator.Equals,
+      value: 'active'
+    }
+  ]
+};
+
+const result = await connector.query(
+  activeCondition,
+  [{ property: 'createdAt', sortDirection: SortDirection.Descending }],
+  ['id', 'email', 'status'],
+  undefined,
+  25
+);
+
+await connector.remove('profile-1');
+```
+
+```typescript
+import { MySqlEntityStorageConnector } from '@twin.org/entity-storage-connector-mysql';
+
+interface Profile {
+  id: string;
+  email: string;
+  status: 'active' | 'inactive';
+  createdAt: string;
+}
+
+const connector = new MySqlEntityStorageConnector<Profile>({
+  entitySchema: 'Profile',
+  config: {
+    host: 'localhost',
+    user: 'root',
+    password: 'root',
+    database: 'entity_storage',
+    tableName: 'profiles'
+  }
+});
+
+const databaseExists = await connector.databaseExists();
+if (databaseExists) {
+  await connector.tableEmpty();
+}
+
+await connector.tableDrop();
+await connector.stop();
+await connector.close();
+```

package/docs/reference/classes/MySqlEntityStorageConnector.md

@@ -10,7 +10,7 @@ Class for performing entity storage operations using MySql.
 
 ## Implements
 
-- `IEntityStorageConnector`\<`T`\>
+- `IEntityStorageMigrationConnector`\<`T`\>
 
 ## Constructors
 
@@ -34,7 +34,7 @@ The options for the connector.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -42,7 +42,7 @@ Runtime name for the class.
 
 ## Methods
 
-### className()
+### className() {#classname}
 
 > **className**(): `string`
 
@@ -56,11 +56,29 @@ The class name of the component.
 
 #### Implementation of
 
-`IEntityStorageConnector.className`
+`IEntityStorageMigrationConnector.className`
 
 ***
 
-### getSchema()
+### health() {#health}
+
+> **health**(): `Promise`\<`IHealth`[]\>
+
+Get the health of the component.
+
+#### Returns
+
+`Promise`\<`IHealth`[]\>
+
+The health of the component.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.health`
+
+***
+
+### getSchema() {#getschema}
 
 > **getSchema**(): `IEntitySchema`
 
@@ -74,11 +92,11 @@ The schema for the entities.
 
 #### Implementation of
 
-`IEntityStorageConnector.getSchema`
+`IEntityStorageMigrationConnector.getSchema`
 
 ***
 
-### bootstrap()
+### bootstrap() {#bootstrap}
 
 > **bootstrap**(`nodeLoggingComponentType?`): `Promise`\<`boolean`\>
 
@@ -100,11 +118,37 @@ A promise that resolves to a boolean indicating success.
 
 #### Implementation of
 
-`IEntityStorageConnector.bootstrap`
+`IEntityStorageMigrationConnector.bootstrap`
+
+***
+
+### stop() {#stop}
+
+> **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+The component needs to be stopped when the node is closed.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.stop`
 
 ***
 
-### get()
+### get() {#get}
 
 > **get**(`id`, `secondaryIndex?`, `conditions?`): `Promise`\<`T` \| `undefined`\>
 
@@ -138,11 +182,11 @@ The object if it can be found or undefined.
 
 #### Implementation of
 
-`IEntityStorageConnector.get`
+`IEntityStorageMigrationConnector.get`
 
 ***
 
-### set()
+### set() {#set}
 
 > **set**(`entity`, `conditions?`): `Promise`\<`void`\>
 
@@ -170,11 +214,55 @@ The id of the entity.
 
 #### Implementation of
 
-`IEntityStorageConnector.set`
+`IEntityStorageMigrationConnector.set`
+
+***
+
+### setBatch() {#setbatch}
+
+> **setBatch**(`entities`): `Promise`\<`void`\>
+
+Set multiple entities in a batch.
+
+#### Parameters
+
+##### entities
+
+`T`[]
+
+The entities to set.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.setBatch`
 
 ***
 
-### remove()
+### empty() {#empty}
+
+> **empty**(): `Promise`\<`void`\>
+
+Empty the entity storage.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.empty`
+
+***
+
+### remove() {#remove}
 
 > **remove**(`id`, `conditions?`): `Promise`\<`void`\>
 
@@ -202,11 +290,63 @@ Nothing.
 
 #### Implementation of
 
-`IEntityStorageConnector.remove`
+`IEntityStorageMigrationConnector.remove`
+
+***
+
+### teardown() {#teardown}
+
+> **teardown**(`nodeLoggingComponentType?`): `Promise`\<`boolean`\>
+
+Teardown the entity storage by dropping the table.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True if the teardown process was successful.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.teardown`
+
+***
+
+### removeBatch() {#removebatch}
+
+> **removeBatch**(`ids`): `Promise`\<`void`\>
+
+Remove multiple entities by their primary key IDs.
+
+#### Parameters
+
+##### ids
+
+`string`[]
+
+The ids of the entities to remove.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.removeBatch`
 
 ***
 
-### query()
+### query() {#query}
 
 > **query**(`conditions?`, `sortProperties?`, `properties?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `Partial`\<`T`\>[]; `cursor?`: `string`; \}\>
 
@@ -253,39 +393,175 @@ and a cursor which can be used to request more entities.
 
 #### Implementation of
 
-`IEntityStorageConnector.query`
+`IEntityStorageMigrationConnector.query`
 
 ***
 
-### tableDrop()
+### count() {#count}
+
+> **count**(`conditions?`): `Promise`\<`number`\>
 
-> **tableDrop**(): `Promise`\<`void`\>
+Count all the entities which match the conditions.
+
+#### Parameters
 
-Drop the table.
+##### conditions?
+
+`EntityCondition`\<`T`\>
+
+The optional conditions to match for the entities.
 
 #### Returns
 
-`Promise`\<`void`\>
+`Promise`\<`number`\>
 
-Nothing.
+The total count of entities in the storage.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.count`
+
+***
+
+### getPartitionContextIds() {#getpartitioncontextids}
+
+> **getPartitionContextIds**(): `Promise`\<`IContextIds`[]\>
+
+Get all unique partition context ids present in the table.
+
+#### Returns
+
+`Promise`\<`IContextIds`[]\>
+
+An array of context id objects, one per unique partition.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.getPartitionContextIds`
+
+***
+
+### createTargetConnector() {#createtargetconnector}
+
+> **createTargetConnector**\<`U`\>(`newEntitySchema`): `Promise`\<`IEntityStorageConnector`\<`U`\>\>
+
+Create the target connector for performing the migration using a temporary table.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### newEntitySchema
+
+`string`
+
+The name of the new entity schema to create the connector for.
+
+#### Returns
+
+`Promise`\<`IEntityStorageConnector`\<`U`\>\>
+
+Connector for performing the migration.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.createTargetConnector`
+
+***
+
+### finalizeMigration() {#finalizemigration}
+
+> **finalizeMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<`MySqlEntityStorageConnector`\<`U`\>\>
+
+Finalize the migration by dropping the source table and renaming the migration table to the original name.
+
+#### Type Parameters
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### targetConnector
+
+`MySqlEntityStorageConnector`\<`U`\>
+
+The connector holding the migrated data in a temporary table.
+
+##### options?
+
+`IMigrationOptions`\<`T`, `U`\>
+
+The options to control how the migration is finalized.
+
+##### loggingComponentType?
+
+`string`
+
+The logging component type to use during finalization.
+
+#### Returns
+
+`Promise`\<`MySqlEntityStorageConnector`\<`U`\>\>
+
+The final connector using the original table name with the new schema.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.finalizeMigration`
 
 ***
 
-### tableEmpty()
+### cleanupMigration() {#cleanupmigration}
+
+> **cleanupMigration**\<`U`\>(`targetConnector`, `options?`, `loggingComponentType?`): `Promise`\<`void`\>
+
+Cleanup a failed or aborted migration by dropping the temporary migration table.
+
+#### Type Parameters
+
+##### U
 
-> **tableEmpty**(): `Promise`\<`void`\>
+`U`
 
-Empty the table.
+#### Parameters
+
+##### targetConnector
+
+`IEntityStorageConnector`\<`U`\> \| `undefined`
+
+The target connector to cleanup.
+
+##### options?
+
+`IMigrationOptions`\<`T`, `U`\>
+
+The options to control how the migration is cleaned up.
+
+##### loggingComponentType?
+
+`string`
+
+The optional component type to use for logging.
 
 #### Returns
 
 `Promise`\<`void`\>
 
-Nothing.
+A promise that resolves when the cleanup is complete.
+
+#### Implementation of
+
+`IEntityStorageMigrationConnector.cleanupMigration`
 
 ***
 
-### databaseExists()
+### databaseExists() {#databaseexists}
 
 > **databaseExists**(): `Promise`\<`boolean`\>
 
@@ -296,3 +572,18 @@ Check if the database exists.
 `Promise`\<`boolean`\>
 
 True if the database exists, false otherwise.
+
+***
+
+### close() {#close}
+
+> **close**(): `Promise`\<`void`\>
+
+Close the connection pool and release all connections.
+Should be called when the connector is no longer needed.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.

package/docs/reference/interfaces/IMySqlEntityStorageConnectorConfig.md

@@ -4,7 +4,7 @@ Configuration for the MySql Entity Storage Connector.
 
 ## Properties
 
-### host
+### host {#host}
 
 > **host**: `string`
 
@@ -12,15 +12,15 @@ The host for the MySql instance.
 
 ***
 
-### port?
+### port? {#port}
 
-> `optional` **port**: `number`
+> `optional` **port?**: `number`
 
 The port for the MySql instance.
 
 ***
 
-### user
+### user {#user}
 
 > **user**: `string`
 
@@ -28,7 +28,7 @@ The user for the MySql instance.
 
 ***
 
-### password
+### password {#password}
 
 > **password**: `string`
 
@@ -36,7 +36,7 @@ The password for the MySql instance.
 
 ***
 
-### database
+### database {#database}
 
 > **database**: `string`
 
@@ -44,8 +44,88 @@ The name of the database to be used.
 
 ***
 
-### tableName
+### tableName {#tablename}
 
 > **tableName**: `string`
 
 The name of the table to be used.
+
+***
+
+### pool? {#pool}
+
+> `optional` **pool?**: `object`
+
+Optional connection pool configuration.
+
+#### connectionLimit?
+
+> `optional` **connectionLimit?**: `number`
+
+Maximum number of connections in pool.
+
+##### Default
+
+```ts
+10
+```
+
+#### maxIdle?
+
+> `optional` **maxIdle?**: `number`
+
+Maximum number of idle connections.
+
+##### Default
+
+```ts
+10
+```
+
+#### idleTimeout?
+
+> `optional` **idleTimeout?**: `number`
+
+Time in ms before removing idle connection.
+
+##### Default
+
+```ts
+60000 (1 minute)
+```
+
+#### enableKeepAlive?
+
+> `optional` **enableKeepAlive?**: `boolean`
+
+Enable TCP keep-alive.
+
+##### Default
+
+```ts
+true
+```
+
+#### waitForConnections?
+
+> `optional` **waitForConnections?**: `boolean`
+
+Wait for available connection when pool is full.
+
+##### Default
+
+```ts
+true
+```
+
+#### queueLimit?
+
+> `optional` **queueLimit?**: `number`
+
+Maximum queued requests (0 = unlimited).
+
+##### Default
+
+```ts
+0
+```

package/docs/reference/interfaces/IMySqlEntityStorageConnectorConstructorOptions.md

@@ -4,7 +4,7 @@ The options for the MySql entity storage connector constructor.
 
 ## Properties
 
-### entitySchema
+### entitySchema {#entityschema}
 
 > **entitySchema**: `string`
 
@@ -12,17 +12,17 @@ The schema for the entity.
 
 ***
 
-### partitionContextIds?
+### partitionContextIds? {#partitioncontextids}
 
-> `optional` **partitionContextIds**: `string`[]
+> `optional` **partitionContextIds?**: `string`[]
 
 The keys to use from the context ids to create partitions.
 
 ***
 
-### loggingComponentType?
+### loggingComponentType? {#loggingcomponenttype}
 
-> `optional` **loggingComponentType**: `string`
+> `optional` **loggingComponentType?**: `string`
 
 The type of logging component to use.
 
@@ -34,7 +34,7 @@ logging
 
 ***
 
-### config
+### config {#config}
 
 > **config**: [`IMySqlEntityStorageConnectorConfig`](IMySqlEntityStorageConnectorConfig.md)