@twin.org/engine-core 0.0.3-next.26 → 0.0.3-next.27

package/README.md

@@ -1,6 +1,6 @@
 # TWIN Engine Core
 
-Engine implementation for the core.
+Engine Core provides the runtime lifecycle and orchestration layer for engine instances. It manages component initialisation, context handling, state persistence, and cloning workflows that higher-level packages rely on.
 
 ## Installation
 

package/docs/changelog.md

@@ -1,4 +1,18 @@
-# @twin.org/engine-core - Changelog
+# Changelog
+
+## [0.0.3-next.27](https://github.com/twinfoundation/engine/compare/engine-core-v0.0.3-next.26...engine-core-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-models 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-core-v0.0.3-next.25...engine-core-v0.0.3-next.26) (2026-03-05)
 

package/docs/examples.md

@@ -1 +1,156 @@
-# @twin.org/engine-core - Examples
+# Engine Core Examples
+
+These examples focus on common runtime patterns such as lifecycle control, cloning, state storage, and module loading.
+
+## EngineCore
+
+```typescript
+import { EngineCore, MemoryStateStorage } from '@twin.org/engine-core';
+import type { IEngineCoreConfig, IEngineState } from '@twin.org/engine-models';
+
+interface AppState extends IEngineState {
+  runCount?: number;
+}
+
+const config: IEngineCoreConfig = {
+  debug: true,
+  silent: false,
+  types: {}
+};
+
+const stateStorage = new MemoryStateStorage<AppState>();
+const engineCore = new EngineCore<IEngineCoreConfig, AppState>({
+  config,
+  stateStorage,
+  skipBootstrap: true
+});
+
+engineCore.addTypeInitialiser('loggingConnector', '@twin.org/engine-types', 'initLoggingConnector');
+console.log(engineCore.getTypeConfig('loggingConnector')?.length ?? 0); // 0
+
+engineCore.addContextIdKey('tenant', ['tenant']);
+engineCore.addContextId('tenant', 'tenant-a');
+
+console.log(engineCore.getContextIdKeys()); // ["tenant"]
+console.log(engineCore.getContextIds()); // { tenant: "tenant-a" }
+console.log(engineCore.isPrimary()); // true
+console.log(engineCore.isClone()); // false
+console.log(engineCore.isStarted()); // false
+
+await engineCore.start(true);
+console.log(engineCore.isStarted()); // true
+
+await engineCore.logInfo('Engine started for tenant-a');
+
+const state = engineCore.getState();
+state.runCount = (state.runCount ?? 0) + 1;
+engineCore.setStateDirty();
+
+console.log(engineCore.getConfig().debug); // true
+console.log(engineCore.getRegisteredInstances()); // { loggingConnector: [...], loggingComponent: [...] }
+console.log(engineCore.getRegisteredInstanceType('loggingComponent')); // "engine-logging-service"
+console.log(engineCore.getRegisteredInstanceTypeOptional('hostingComponent')); // undefined
+
+await engineCore.stop();
+console.log(engineCore.isStarted()); // false
+```
+
+```typescript
+import { BaseError, GeneralError } from '@twin.org/core';
+import { EngineCore } from '@twin.org/engine-core';
+
+const engineCore = new EngineCore({
+  config: { debug: false, silent: true, types: {} },
+  skipBootstrap: true
+});
+
+const wrapped = new GeneralError(
+  EngineCore.CLASS_NAME,
+  'sampleFailure',
+  { area: 'examples' },
+  BaseError.fromError(new Error('Sample failure'))
+);
+await engineCore.logError(wrapped);
+```
+
+```typescript
+import { EngineCore } from '@twin.org/engine-core';
+
+const primary = new EngineCore({
+  config: { debug: false, silent: true, types: {} },
+  skipBootstrap: true
+});
+primary.addContextIdKey('node', ['node']);
+
+const cloneData = primary.getCloneData();
+
+const clone = new EngineCore({ config: { debug: false, silent: true, types: {} } });
+clone.populateClone(cloneData, { node: 'node-1', tenant: 'tenant-a' }, true);
+
+console.log(clone.isClone()); // true
+console.log(clone.getContextIds()); // { node: "node-1", tenant: "tenant-a" }
+```
+
+## FileStateStorage
+
+```typescript
+import { EngineCore, FileStateStorage } from '@twin.org/engine-core';
+
+const engineCore = new EngineCore({
+  config: { debug: false, silent: true, types: {} },
+  skipBootstrap: true
+});
+const fileStorage = new FileStateStorage('./data/engine-state.json');
+
+await fileStorage.save(engineCore, { ready: true });
+
+const loaded = await fileStorage.load(engineCore);
+console.log(loaded); // { ready: true }
+```
+
+## MemoryStateStorage
+
+```typescript
+import { EngineCore, MemoryStateStorage } from '@twin.org/engine-core';
+
+const engineCore = new EngineCore({
+  config: { debug: false, silent: true, types: {} },
+  skipBootstrap: true
+});
+const memoryStorage = new MemoryStateStorage(false, { retries: 1 });
+
+console.log(await memoryStorage.load(engineCore)); // { retries: 1 }
+
+await memoryStorage.save(engineCore, { retries: 2 });
+console.log(await memoryStorage.load(engineCore)); // { retries: 2 }
+```
+
+## EngineModuleHelper
+
+```typescript
+import { EngineCore, EngineModuleHelper } from '@twin.org/engine-core';
+import type { IEngineModuleConfig } from '@twin.org/engine-models';
+
+const engineCore = new EngineCore({
+  config: { debug: false, silent: true, types: {} },
+  skipBootstrap: true
+});
+
+const moduleConfig: IEngineModuleConfig = {
+  moduleName: '@twin.org/logging-service',
+  className: 'LoggingService',
+  dependencies: [
+    {
+      propertyName: 'loggingConnectorType',
+      componentName: 'loggingConnector',
+      isOptional: false
+    }
+  ],
+  config: {
+    level: 'info'
+  }
+};
+
+const component = await EngineModuleHelper.loadComponent<unknown>(engineCore, moduleConfig);
+console.log(component !== undefined); // true
+```

package/docs/reference/classes/EngineCore.md

@@ -38,7 +38,7 @@ The options for the engine.
 
 ## Properties
 
-### LOGGING\_COMPONENT\_TYPE\_NAME
+### LOGGING\_COMPONENT\_TYPE\_NAME {#logging_component_type_name}
 
 > `readonly` `static` **LOGGING\_COMPONENT\_TYPE\_NAME**: `string` = `"engine-logging-service"`
 
@@ -46,7 +46,7 @@ Name for the engine logger component, used for direct console logging.
 
 ***
 
-### LOGGING\_CONNECTOR\_TYPE\_NAME
+### LOGGING\_CONNECTOR\_TYPE\_NAME {#logging_connector_type_name}
 
 > `readonly` `static` **LOGGING\_CONNECTOR\_TYPE\_NAME**: `string` = `"engine-logging-connector"`
 
@@ -54,7 +54,7 @@ Name for the engine logger connector, used for direct console logging.
 
 ***
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -62,7 +62,7 @@ Runtime name for the class.
 
 ***
 
-### \_context
+### \_context {#_context}
 
 > `protected` **\_context**: `IEngineCoreContext`\<`C`, `S`\>
 
@@ -70,7 +70,7 @@ The core context.
 
 ***
 
-### \_contextIdKeys
+### \_contextIdKeys {#_contextidkeys}
 
 > `protected` `readonly` **\_contextIdKeys**: `object`[]
 
@@ -86,15 +86,15 @@ The context ID keys.
 
 ***
 
-### \_contextIds?
+### \_contextIds? {#_contextids}
 
-> `protected` `optional` **\_contextIds**: `IContextIds`
+> `protected` `optional` **\_contextIds?**: `IContextIds`
 
 The context IDs.
 
 ## Methods
 
-### addTypeInitialiser()
+### addTypeInitialiser() {#addtypeinitialiser}
 
 > **addTypeInitialiser**(`type`, `module`, `method`): `void`
 
@@ -130,7 +130,7 @@ The name of the method to call.
 
 ***
 
-### getTypeConfig()
+### getTypeConfig() {#gettypeconfig}
 
 > **getTypeConfig**(`type`): `IEngineCoreTypeConfig`[] \| `undefined`
 
@@ -156,7 +156,7 @@ The type config or undefined if not found.
 
 ***
 
-### addContextIdKey()
+### addContextIdKey() {#addcontextidkey}
 
 > **addContextIdKey**(`key`, `componentFeatures`): `void`
 
@@ -186,7 +186,7 @@ The component features for the context ID handler.
 
 ***
 
-### getContextIdKeys()
+### getContextIdKeys() {#getcontextidkeys}
 
 > **getContextIdKeys**(): `string`[]
 
@@ -204,7 +204,7 @@ The context IDs keys.
 
 ***
 
-### addContextId()
+### addContextId() {#addcontextid}
 
 > **addContextId**(`key`, `value`): `void`
 
@@ -234,7 +234,7 @@ The context ID value.
 
 ***
 
-### getContextIds()
+### getContextIds() {#getcontextids}
 
 > **getContextIds**(): `IContextIds` \| `undefined`
 
@@ -252,7 +252,7 @@ The context IDs or undefined if none are set.
 
 ***
 
-### start()
+### start() {#start}
 
 > **start**(`skipComponentStart?`): `Promise`\<`void`\>
 
@@ -278,7 +278,7 @@ Nothing.
 
 ***
 
-### stop()
+### stop() {#stop}
 
 > **stop**(): `Promise`\<`void`\>
 
@@ -296,7 +296,7 @@ Nothing.
 
 ***
 
-### isStarted()
+### isStarted() {#isstarted}
 
 > **isStarted**(): `boolean`
 
@@ -314,7 +314,7 @@ True if the engine is started.
 
 ***
 
-### isPrimary()
+### isPrimary() {#isprimary}
 
 > **isPrimary**(): `boolean`
 
@@ -332,7 +332,7 @@ True if the engine is the primary instance.
 
 ***
 
-### isClone()
+### isClone() {#isclone}
 
 > **isClone**(): `boolean`
 
@@ -350,7 +350,7 @@ True if the engine instance is a clone.
 
 ***
 
-### logInfo()
+### logInfo() {#loginfo}
 
 > **logInfo**(`message`): `Promise`\<`void`\>
 
@@ -374,7 +374,7 @@ The message to log.
 
 ***
 
-### logError()
+### logError() {#logerror}
 
 > **logError**(`error`): `Promise`\<`void`\>
 
@@ -398,7 +398,7 @@ The error to log.
 
 ***
 
-### getConfig()
+### getConfig() {#getconfig}
 
 > **getConfig**(): `C`
 
@@ -416,7 +416,7 @@ The config for the engine.
 
 ***
 
-### getState()
+### getState() {#getstate}
 
 > **getState**(): `S`
 
@@ -434,7 +434,7 @@ The state of the engine.
 
 ***
 
-### setStateDirty()
+### setStateDirty() {#setstatedirty}
 
 > **setStateDirty**(): `void`
 
@@ -450,7 +450,7 @@ Set the state to dirty so it gets saved.
 
 ***
 
-### getRegisteredInstances()
+### getRegisteredInstances() {#getregisteredinstances}
 
 > **getRegisteredInstances**(): `object`
 
@@ -468,7 +468,7 @@ The registered instances.
 
 ***
 
-### getRegisteredInstanceType()
+### getRegisteredInstanceType() {#getregisteredinstancetype}
 
 > **getRegisteredInstanceType**(`componentConnectorType`, `features?`): `string`
 
@@ -504,7 +504,7 @@ If a matching instance was not found.
 
 ***
 
-### getRegisteredInstanceTypeOptional()
+### getRegisteredInstanceTypeOptional() {#getregisteredinstancetypeoptional}
 
 > **getRegisteredInstanceTypeOptional**(`componentConnectorType`, `features?`): `string` \| `undefined`
 
@@ -536,7 +536,7 @@ The instance type matching the criteria if one is registered.
 
 ***
 
-### getCloneData()
+### getCloneData() {#getclonedata}
 
 > **getCloneData**(): `IEngineCoreClone`\<`C`, `S`\>
 
@@ -554,7 +554,7 @@ The clone data.
 
 ***
 
-### populateClone()
+### populateClone() {#populateclone}
 
 > **populateClone**(`cloneData`, `contextIds?`, `silent?`): `void`
 

package/docs/reference/classes/EngineModuleHelper.md

@@ -14,7 +14,7 @@ Helper class for engine modules.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -22,7 +22,7 @@ Runtime name for the class.
 
 ## Methods
 
-### loadComponent()
+### loadComponent() {#loadcomponent}
 
 > `static` **loadComponent**\<`T`\>(`engineCore`, `engineModuleConfig`): `Promise`\<`T`\>
 

package/docs/reference/classes/FileStateStorage.md

@@ -40,7 +40,7 @@ Whether the file is in read-only mode.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -48,7 +48,7 @@ Runtime name for the class.
 
 ## Methods
 
-### load()
+### load() {#load}
 
 > **load**(`engineCore`): `Promise`\<`S` \| `undefined`\>
 
@@ -74,7 +74,7 @@ The state of the engine or undefined if it doesn't exist.
 
 ***
 
-### save()
+### save() {#save}
 
 > **save**(`engineCore`, `state`): `Promise`\<`void`\>
 

package/docs/reference/classes/MemoryStateStorage.md

@@ -40,7 +40,7 @@ The initial state.
 
 ## Properties
 
-### CLASS\_NAME
+### CLASS\_NAME {#class_name}
 
 > `readonly` `static` **CLASS\_NAME**: `string`
 
@@ -48,7 +48,7 @@ Runtime name for the class.
 
 ## Methods
 
-### load()
+### load() {#load}
 
 > **load**(`engineCore`): `Promise`\<`S` \| `undefined`\>
 
@@ -74,7 +74,7 @@ The state of the engine or undefined if it doesn't exist.
 
 ***
 
-### save()
+### save() {#save}
 
 > **save**(`engineCore`, `state`): `Promise`\<`void`\>
 

package/docs/reference/interfaces/IEngineCoreOptions.md

@@ -14,33 +14,33 @@ The options for creating engine core.
 
 ## Properties
 
-### config?
+### config? {#config}
 
-> `optional` **config**: `C`
+> `optional` **config?**: `C`
 
 The engine core config.
 
 ***
 
-### stateStorage?
+### stateStorage? {#statestorage}
 
-> `optional` **stateStorage**: `IEngineStateStorage`\<`S`\>
+> `optional` **stateStorage?**: `IEngineStateStorage`\<`S`\>
 
 The state storage component.
 
 ***
 
-### skipBootstrap?
+### skipBootstrap? {#skipbootstrap}
 
-> `optional` **skipBootstrap**: `boolean`
+> `optional` **skipBootstrap?**: `boolean`
 
 Skip the bootstrap process, useful for additional engine instances.
 
 ***
 
-### populateTypeInitialisers()?
+### populateTypeInitialisers? {#populatetypeinitialisers}
 
-> `optional` **populateTypeInitialisers**: (`engineCore`, `context`) => `void`
+> `optional` **populateTypeInitialisers?**: (`engineCore`, `context`) => `void`
 
 Populate the type initialisers for the engine.
 
@@ -60,9 +60,9 @@ Populate the type initialisers for the engine.
 
 ***
 
-### customBootstrap()?
+### customBootstrap? {#custombootstrap}
 
-> `optional` **customBootstrap**: (`engineCore`, `context`) => `Promise`\<`void`\>
+> `optional` **customBootstrap?**: (`engineCore`, `context`) => `Promise`\<`void`\>
 
 Custom bootstrap method for the engine.
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@twin.org/engine-core",
-	"version": "0.0.3-next.26",
-	"description": "Engine core.",
+	"version": "0.0.3-next.27",
+	"description": "Core runtime lifecycle and state orchestration for engine instances.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/twinfoundation/engine.git",
@@ -18,7 +18,7 @@
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
 		"@twin.org/data-core": "next",
-		"@twin.org/engine-models": "0.0.3-next.26",
+		"@twin.org/engine-models": "0.0.3-next.27",
 		"@twin.org/entity": "next",
 		"@twin.org/logging-connector-console": "next",
 		"@twin.org/logging-models": "next",