@twin.org/engine 0.0.3-next.25 → 0.0.3-next.27

package/README.md

@@ -1,6 +1,6 @@
 # TWIN Engine
 
-Engine implementation.
+Engine provides a ready-to-use runtime that extends the core layer with built-in type initialisers. It helps applications start from a practical baseline while still allowing customisation of configuration and component selection.
 
 ## Installation
 

package/docs/changelog.md

@@ -1,4 +1,36 @@
-# @twin.org/engine - Changelog
+# Changelog
+
+## [0.0.3-next.27](https://github.com/twinfoundation/engine/compare/engine-v0.0.3-next.26...engine-v0.0.3-next.27) (2026-03-20)
+
+
+### Features
+
+* update dependencies ([e6ebe42](https://github.com/twinfoundation/engine/commit/e6ebe42b9d61066227ad8b45dae14c8f8615b760))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/engine-core bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/engine-models bumped from 0.0.3-next.26 to 0.0.3-next.27
+    * @twin.org/engine-types bumped from 0.0.3-next.26 to 0.0.3-next.27
+
+## [0.0.3-next.26](https://github.com/twinfoundation/engine/compare/engine-v0.0.3-next.25...engine-v0.0.3-next.26) (2026-03-05)
+
+
+### Bug Fixes
+
+* use custom instance type for entity storage registration ([#90](https://github.com/twinfoundation/engine/issues/90)) ([2c23995](https://github.com/twinfoundation/engine/commit/2c239953dab4510a4cf97063ee90d048210bf4a6))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/engine-core bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/engine-models bumped from 0.0.3-next.25 to 0.0.3-next.26
+    * @twin.org/engine-types bumped from 0.0.3-next.25 to 0.0.3-next.26
 
 ## [0.0.3-next.25](https://github.com/twinfoundation/engine/compare/engine-v0.0.3-next.24...engine-v0.0.3-next.25) (2026-03-02)
 

package/docs/examples.md

@@ -1,35 +1,68 @@
-# @twin.org/engine - Examples
+# Engine Examples
 
-## Environment Variables
+These examples show a practical way to configure and run an instance with built-in type initialisers and custom entity storage.
 
-The engine supports various environment variables for configuration. Here are some key examples:
+## Engine
 
-### IOTA DLT Configuration
+```typescript
+import { Engine } from '@twin.org/engine';
+import type { IEngineConfig } from '@twin.org/engine-types';
 
-Basic IOTA configuration:
+const config: IEngineConfig = {
+  debug: true,
+  silent: false,
+  types: {}
+};
 
-```bash
-# IOTA Node Configuration
-IOTA_NODE_ENDPOINT="https://api.devnet.iota.cafe"
-IOTA_FAUCET_ENDPOINT="https://faucet.devnet.iota.cafe"
-IOTA_EXPLORER_ENDPOINT="https://explorer.iota.org/"
-IOTA_NETWORK="devnet"
-IOTA_COIN_TYPE="4218"
-```
+const engine = new Engine({ config, skipBootstrap: true });
+
+engine.addContextIdKey('tenant', ['tenant']);
+engine.addContextId('tenant', 'tenant-a');
 
-### IOTA Gas Station Configuration (Optional)
+engine.addTypeInitialiser('loggingConnector', '@twin.org/engine-types', 'initLoggingConnector');
 
-The IOTA Gas Station pattern allows for sponsored transactions and improved UX:
+console.log(engine.getContextIdKeys()); // ["tenant"]
+console.log(engine.getContextIds()); // { tenant: "tenant-a" }
+console.log(engine.isStarted()); // false
 
-```bash
-# Gas Station Configuration
-IOTA_GAS_STATION_ENDPOINT="https://gas-station.example.com"
-IOTA_GAS_STATION_AUTH_TOKEN="your-auth-token"
+await engine.start(true);
+console.log(engine.isStarted()); // true
+
+await engine.stop();
+console.log(engine.isStarted()); // false
 ```
 
-**Configuration Options:**
+## EngineConfigHelper
+
+```typescript
+import { EngineConfigHelper } from '@twin.org/engine';
+import type { IEngineConfig } from '@twin.org/engine-types';
+import type { IEntitySchema } from '@twin.org/entity';
 
-- `IOTA_GAS_STATION_ENDPOINT`: The URL of the gas station service
-- `IOTA_GAS_STATION_AUTH_TOKEN`: Authentication token for the gas station
+interface Product {
+  id: string;
+  name: string;
+}
 
-When gas station is configured, all IOTA-related connectors (wallet, nft, verifiable-storage, identity, identity-resolver) will automatically use the centralized configuration and have access to gas station functionality.
+const config: IEngineConfig = {
+  debug: false,
+  silent: true,
+  types: {}
+};
+
+const productSchema = {
+  type: 'Product',
+  properties: {
+    id: { type: 'string', isPrimary: true },
+    name: { type: 'string' }
+  }
+} as IEntitySchema<Product>;
+
+EngineConfigHelper.addCustomEntityStorage(config, 'product', productSchema, '/products', [
+  'node',
+  'tenant'
+]);
+
+console.log(config.types.entityStorageComponent?.length ?? 0); // 1
+console.log(config.types.entityStorageComponent?.[0].restPath); // "/products"
+```

package/docs/reference/classes/Engine.md

@@ -42,7 +42,7 @@ The options for the engine.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -51,3 +51,567 @@ Runtime name for the class.
 #### Overrides
 
 `EngineCore.CLASS_NAME`
+
+***
+
+### LOGGING\_COMPONENT\_TYPE\_NAME {#logging_component_type_name}
+
+> `readonly` `static` **LOGGING\_COMPONENT\_TYPE\_NAME**: `string`
+
+Name for the engine logger component, used for direct console logging.
+
+#### Inherited from
+
+`EngineCore.LOGGING_COMPONENT_TYPE_NAME`
+
+***
+
+### LOGGING\_CONNECTOR\_TYPE\_NAME {#logging_connector_type_name}
+
+> `readonly` `static` **LOGGING\_CONNECTOR\_TYPE\_NAME**: `string`
+
+Name for the engine logger connector, used for direct console logging.
+
+#### Inherited from
+
+`EngineCore.LOGGING_CONNECTOR_TYPE_NAME`
+
+***
+
+### \_context {#_context}
+
+> `protected` **\_context**: `IEngineCoreContext`\<`C`, `S`\>
+
+The core context.
+
+#### Inherited from
+
+`EngineCore._context`
+
+***
+
+### \_contextIdKeys {#_contextidkeys}
+
+> `protected` `readonly` **\_contextIdKeys**: `object`[]
+
+The context ID keys.
+
+#### key
+
+> **key**: `string`
+
+#### componentFeatures
+
+> **componentFeatures**: `string`[]
+
+#### Inherited from
+
+`EngineCore._contextIdKeys`
+
+***
+
+### \_contextIds? {#_contextids}
+
+> `protected` `optional` **\_contextIds?**: `IContextIds`
+
+The context IDs.
+
+#### Inherited from
+
+`EngineCore._contextIds`
+
+## Methods
+
+### addTypeInitialiser() {#addtypeinitialiser}
+
+> **addTypeInitialiser**(`type`, `module`, `method`): `void`
+
+Add a type initialiser.
+
+#### Parameters
+
+##### type
+
+`string`
+
+The type to add the initialiser for.
+
+##### module
+
+`string`
+
+The name of the module which contains the initialiser method.
+
+##### method
+
+`string`
+
+The name of the method to call.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`EngineCore.addTypeInitialiser`
+
+***
+
+### getTypeConfig() {#gettypeconfig}
+
+> **getTypeConfig**(`type`): `IEngineCoreTypeConfig`[] \| `undefined`
+
+Get the type config for a specific type.
+
+#### Parameters
+
+##### type
+
+`string`
+
+The type to get the config for.
+
+#### Returns
+
+`IEngineCoreTypeConfig`[] \| `undefined`
+
+The type config or undefined if not found.
+
+#### Inherited from
+
+`EngineCore.getTypeConfig`
+
+***
+
+### addContextIdKey() {#addcontextidkey}
+
+> **addContextIdKey**(`key`, `componentFeatures`): `void`
+
+Add a context ID key to the engine.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The context ID key.
+
+##### componentFeatures
+
+`string`[]
+
+The component features for the context ID handler.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`EngineCore.addContextIdKey`
+
+***
+
+### getContextIdKeys() {#getcontextidkeys}
+
+> **getContextIdKeys**(): `string`[]
+
+Get the context ID keys for the engine.
+
+#### Returns
+
+`string`[]
+
+The context IDs keys.
+
+#### Inherited from
+
+`EngineCore.getContextIdKeys`
+
+***
+
+### addContextId() {#addcontextid}
+
+> **addContextId**(`key`, `value`): `void`
+
+Add a context ID to the engine.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The context ID key.
+
+##### value
+
+`string`
+
+The context ID value.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`EngineCore.addContextId`
+
+***
+
+### getContextIds() {#getcontextids}
+
+> **getContextIds**(): `IContextIds` \| `undefined`
+
+Get the context IDs for the engine.
+
+#### Returns
+
+`IContextIds` \| `undefined`
+
+The context IDs or undefined if none are set.
+
+#### Inherited from
+
+`EngineCore.getContextIds`
+
+***
+
+### start() {#start}
+
+> **start**(`skipComponentStart?`): `Promise`\<`void`\>
+
+Start the engine core.
+
+#### Parameters
+
+##### skipComponentStart?
+
+`boolean`
+
+Should the component start be skipped.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Inherited from
+
+`EngineCore.start`
+
+***
+
+### stop() {#stop}
+
+> **stop**(): `Promise`\<`void`\>
+
+Stop the engine core.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Inherited from
+
+`EngineCore.stop`
+
+***
+
+### isStarted() {#isstarted}
+
+> **isStarted**(): `boolean`
+
+Is the engine started.
+
+#### Returns
+
+`boolean`
+
+True if the engine is started.
+
+#### Inherited from
+
+`EngineCore.isStarted`
+
+***
+
+### isPrimary() {#isprimary}
+
+> **isPrimary**(): `boolean`
+
+Is this the primary engine instance.
+
+#### Returns
+
+`boolean`
+
+True if the engine is the primary instance.
+
+#### Inherited from
+
+`EngineCore.isPrimary`
+
+***
+
+### isClone() {#isclone}
+
+> **isClone**(): `boolean`
+
+Is this engine instance a clone.
+
+#### Returns
+
+`boolean`
+
+True if the engine instance is a clone.
+
+#### Inherited from
+
+`EngineCore.isClone`
+
+***
+
+### logInfo() {#loginfo}
+
+> **logInfo**(`message`): `Promise`\<`void`\>
+
+Log info.
+
+#### Parameters
+
+##### message
+
+`string`
+
+The message to log.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Inherited from
+
+`EngineCore.logInfo`
+
+***
+
+### logError() {#logerror}
+
+> **logError**(`error`): `Promise`\<`void`\>
+
+Log error.
+
+#### Parameters
+
+##### error
+
+`IError`
+
+The error to log.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+#### Inherited from
+
+`EngineCore.logError`
+
+***
+
+### getConfig() {#getconfig}
+
+> **getConfig**(): `C`
+
+Get the config for the engine.
+
+#### Returns
+
+`C`
+
+The config for the engine.
+
+#### Inherited from
+
+`EngineCore.getConfig`
+
+***
+
+### getState() {#getstate}
+
+> **getState**(): `S`
+
+Get the state of the engine.
+
+#### Returns
+
+`S`
+
+The state of the engine.
+
+#### Inherited from
+
+`EngineCore.getState`
+
+***
+
+### setStateDirty() {#setstatedirty}
+
+> **setStateDirty**(): `void`
+
+Set the state to dirty so it gets saved.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`EngineCore.setStateDirty`
+
+***
+
+### getRegisteredInstances() {#getregisteredinstances}
+
+> **getRegisteredInstances**(): `object`
+
+Get all the registered instances.
+
+#### Returns
+
+`object`
+
+The registered instances.
+
+#### Inherited from
+
+`EngineCore.getRegisteredInstances`
+
+***
+
+### getRegisteredInstanceType() {#getregisteredinstancetype}
+
+> **getRegisteredInstanceType**(`componentConnectorType`, `features?`): `string`
+
+Get the registered instance type for the component/connector.
+
+#### Parameters
+
+##### componentConnectorType
+
+`string`
+
+The type of the component/connector.
+
+##### features?
+
+`string`[]
+
+The requested features of the component, if not specified the default entry will be retrieved.
+
+#### Returns
+
+`string`
+
+The instance type matching the criteria if one is registered.
+
+#### Throws
+
+If a matching instance was not found.
+
+#### Inherited from
+
+`EngineCore.getRegisteredInstanceType`
+
+***
+
+### getRegisteredInstanceTypeOptional() {#getregisteredinstancetypeoptional}
+
+> **getRegisteredInstanceTypeOptional**(`componentConnectorType`, `features?`): `string` \| `undefined`
+
+Get the registered instance type for the component/connector if it exists.
+
+#### Parameters
+
+##### componentConnectorType
+
+`string`
+
+The type of the component/connector.
+
+##### features?
+
+`string`[]
+
+The requested features of the component, if not specified the default entry will be retrieved.
+
+#### Returns
+
+`string` \| `undefined`
+
+The instance type matching the criteria if one is registered.
+
+#### Inherited from
+
+`EngineCore.getRegisteredInstanceTypeOptional`
+
+***
+
+### getCloneData() {#getclonedata}
+
+> **getCloneData**(): `IEngineCoreClone`\<`C`, `S`\>
+
+Get the data required to create a clone of the engine.
+
+#### Returns
+
+`IEngineCoreClone`\<`C`, `S`\>
+
+The clone data.
+
+#### Inherited from
+
+`EngineCore.getCloneData`
+
+***
+
+### populateClone() {#populateclone}
+
+> **populateClone**(`cloneData`, `contextIds?`, `silent?`): `void`
+
+Populate the engine from the clone data.
+
+#### Parameters
+
+##### cloneData
+
+`IEngineCoreClone`\<`C`, `S`\>
+
+The clone data to populate from.
+
+##### contextIds?
+
+`IContextIds`
+
+The context IDs to use for the clone.
+
+##### silent?
+
+`boolean`
+
+Should the clone be silent.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`EngineCore.populateClone`

package/docs/reference/classes/EngineConfigHelper.md

@@ -14,7 +14,7 @@ Helper methods for engine config.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### addCustomEntityStorage()
+### addCustomEntityStorage() {#addcustomentitystorage}
 
 > `static` **addCustomEntityStorage**\<`T`\>(`engineConfig`, `entityTypeName`, `entitySchema`, `restPath?`, `partitionContextIds?`): `void`
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/engine",
-	"version": "0.0.3-next.25",
-	"description": "Engine implementation.",
+	"version": "0.0.3-next.27",
+	"description": "Ready-to-use engine runtime that preloads built-in type initialisers.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/engine.git",
@@ -16,9 +16,9 @@
 	"dependencies": {
 		"@twin.org/context": "next",
 		"@twin.org/core": "next",
-		"@twin.org/engine-core": "0.0.3-next.25",
-		"@twin.org/engine-models": "0.0.3-next.25",
-		"@twin.org/engine-types": "0.0.3-next.25",
+		"@twin.org/engine-core": "0.0.3-next.27",
+		"@twin.org/engine-models": "0.0.3-next.27",
+		"@twin.org/engine-types": "0.0.3-next.27",
 		"@twin.org/entity": "next",
 		"@twin.org/nameof": "next"
 	},