@twin.org/node-core 0.0.1-next.3 → 0.0.1-next.6

package/README.md

@@ -1,32 +1,20 @@
 # TWIN Node Core
 
-Core of a TWIN node for running the TWIN engine as a REST server.
+TWIN Node Core for serving APIs using the specified configuration
 
-## Building and running the application
-
-To install the dependencies, perform a full build and start the server.
-
-```shell
-npm install
-npm run dist
-npm start
-```
-
-## Development mode
-
-Once you have performed a full build you can run the server in development mode, this will watch the TypeScript code, rebuild if there are any changes, and relaunch the server.
+## Installation
 
 ```shell
-npm run dev
+npm install @twin.org/node-core
 ```
 
-## Configuration
+## Examples
 
-There are various options you can set through configuration, these can be found in [docs/configuration.md](docs/configuration.md)
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
 
-## Deployment
+## Reference
 
-Examples of how to deploy the app can be found in [docs/deployment.md](docs/deployment.md)
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
 
 ## Changelog
 

package/dist/cjs/index.cjs

@@ -491,25 +491,30 @@ async function bootstrapAuth(engineCore, context, envVars, features) {
 /**
  * Start the engine server.
  * @param serverInfo The server information.
+ * @param envVarsPrefix The prefix for the environment variables.
  * @param envVars The environment variables.
  * @param openApiSpecFile Path to the OpenAPI spec file.
  * @param stateStorage The state storage.
- * @param customConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendEngine Extends the engine with any additional options.
+ * @param extendEngineServer Extends the engine server with any additional options.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customConfig) {
+async function start(serverInfo, envVarsPrefix, envVars, openApiSpecFile, stateStorage, extendConfig, extendEngine, extendEngineServer) {
     envVars.storageFileRoot ??= "";
     if ((envVars.entityStorageConnectorType === engineTypes.EntityStorageConnectorType.File ||
         envVars.blobStorageConnectorType === engineTypes.BlobStorageConnectorType.File ||
         core.Is.empty(stateStorage)) &&
         !core.Is.stringValue(envVars.storageFileRoot)) {
-        throw new core.GeneralError("node", "storageFileRootNotSet");
+        throw new core.GeneralError("node", "storageFileRootNotSet", {
+            storageFileRoot: `${envVarsPrefix}_STORAGE_FILE_ROOT`
+        });
     }
     // Build the engine configuration from the environment variables.
     const engineConfig = engine.buildEngineConfiguration(envVars);
     // Extend the engine configuration with a custom type.
-    if (core.Is.function(customConfig)) {
-        await customConfig(engineConfig);
+    if (core.Is.function(extendConfig)) {
+        await extendConfig(engineConfig);
     }
     // Build the server configuration from the environment variables.
     const serverConfig = engineServer.buildEngineServerConfiguration(envVars, engineConfig, serverInfo, openApiSpecFile);
@@ -519,11 +524,19 @@ async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customC
         stateStorage: stateStorage ?? new engineCore.FileStateStorage(envVars.stateFilename ?? ""),
         customBootstrap: async (core, engineContext) => bootstrap(core, engineContext, envVars)
     });
+    // Extend the engine.
+    if (core.Is.function(extendEngine)) {
+        await extendEngine(engine$1);
+    }
+    // Construct the server with the engine.
+    const server = new engineServer.EngineServer({ engineCore: engine$1 });
+    // Extend the engine server.
+    if (core.Is.function(extendEngineServer)) {
+        await extendEngineServer(server);
+    }
     // Need to register the engine with the factory so that background tasks
     // can clone it to spawn new instances.
     engineModels.EngineCoreFactory.register("engine", () => engine$1);
-    // Construct the server with the engine.
-    const server = new engineServer.EngineServer({ engineCore: engine$1 });
     // Start the server, which also starts the engine.
     const canContinue = await server.start();
     if (canContinue) {
@@ -546,7 +559,7 @@ async function run(options) {
     try {
         const serverInfo = {
             name: options?.serverName ?? "TWIN Node Server",
-            version: options?.serverVersion ?? "0.0.1-next.3" // x-release-please-version
+            version: options?.serverVersion ?? "0.0.1-next.6" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -572,8 +585,11 @@ async function run(options) {
         const envPrefix = options?.envPrefix ?? "TWIN_NODE_";
         console.info("Environment Prefix:", envPrefix);
         const envVars = core.EnvHelper.envToJson(process.env, envPrefix);
+        if (Object.keys(envVars).length === 0) {
+            throw new core.GeneralError("node", "noEnvVars", { prefix: envPrefix });
+        }
         console.info();
-        const startResult = await start(serverInfo, envVars, options?.openApiSpecFile, options.stateStorage, options.customConfig);
+        const startResult = await start(serverInfo, envPrefix, envVars, options?.openApiSpecFile, options.stateStorage, options.extendConfig, options.extendEngine, options.extendEngineServer);
         if (!core.Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
                 process.on(signal, async () => {

package/dist/esm/index.mjs

@@ -470,25 +470,30 @@ async function bootstrapAuth(engineCore, context, envVars, features) {
 /**
  * Start the engine server.
  * @param serverInfo The server information.
+ * @param envVarsPrefix The prefix for the environment variables.
  * @param envVars The environment variables.
  * @param openApiSpecFile Path to the OpenAPI spec file.
  * @param stateStorage The state storage.
- * @param customConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendEngine Extends the engine with any additional options.
+ * @param extendEngineServer Extends the engine server with any additional options.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customConfig) {
+async function start(serverInfo, envVarsPrefix, envVars, openApiSpecFile, stateStorage, extendConfig, extendEngine, extendEngineServer) {
     envVars.storageFileRoot ??= "";
     if ((envVars.entityStorageConnectorType === EntityStorageConnectorType.File ||
         envVars.blobStorageConnectorType === BlobStorageConnectorType.File ||
         Is.empty(stateStorage)) &&
         !Is.stringValue(envVars.storageFileRoot)) {
-        throw new GeneralError("node", "storageFileRootNotSet");
+        throw new GeneralError("node", "storageFileRootNotSet", {
+            storageFileRoot: `${envVarsPrefix}_STORAGE_FILE_ROOT`
+        });
     }
     // Build the engine configuration from the environment variables.
     const engineConfig = buildEngineConfiguration(envVars);
     // Extend the engine configuration with a custom type.
-    if (Is.function(customConfig)) {
-        await customConfig(engineConfig);
+    if (Is.function(extendConfig)) {
+        await extendConfig(engineConfig);
     }
     // Build the server configuration from the environment variables.
     const serverConfig = buildEngineServerConfiguration(envVars, engineConfig, serverInfo, openApiSpecFile);
@@ -498,11 +503,19 @@ async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customC
         stateStorage: stateStorage ?? new FileStateStorage(envVars.stateFilename ?? ""),
         customBootstrap: async (core, engineContext) => bootstrap(core, engineContext, envVars)
     });
+    // Extend the engine.
+    if (Is.function(extendEngine)) {
+        await extendEngine(engine);
+    }
+    // Construct the server with the engine.
+    const server = new EngineServer({ engineCore: engine });
+    // Extend the engine server.
+    if (Is.function(extendEngineServer)) {
+        await extendEngineServer(server);
+    }
     // Need to register the engine with the factory so that background tasks
     // can clone it to spawn new instances.
     EngineCoreFactory.register("engine", () => engine);
-    // Construct the server with the engine.
-    const server = new EngineServer({ engineCore: engine });
     // Start the server, which also starts the engine.
     const canContinue = await server.start();
     if (canContinue) {
@@ -525,7 +538,7 @@ async function run(options) {
     try {
         const serverInfo = {
             name: options?.serverName ?? "TWIN Node Server",
-            version: options?.serverVersion ?? "0.0.1-next.3" // x-release-please-version
+            version: options?.serverVersion ?? "0.0.1-next.6" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -551,8 +564,11 @@ async function run(options) {
         const envPrefix = options?.envPrefix ?? "TWIN_NODE_";
         console.info("Environment Prefix:", envPrefix);
         const envVars = EnvHelper.envToJson(process.env, envPrefix);
+        if (Object.keys(envVars).length === 0) {
+            throw new GeneralError("node", "noEnvVars", { prefix: envPrefix });
+        }
         console.info();
-        const startResult = await start(serverInfo, envVars, options?.openApiSpecFile, options.stateStorage, options.customConfig);
+        const startResult = await start(serverInfo, envPrefix, envVars, options?.openApiSpecFile, options.stateStorage, options.extendConfig, options.extendEngine, options.extendEngineServer);
         if (!Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
                 process.on(signal, async () => {

package/dist/types/models/IRunOptions.d.ts

@@ -1,4 +1,4 @@
-import type { IEngineStateStorage } from "@twin.org/engine-models";
+import type { IEngineCore, IEngineServer, IEngineStateStorage } from "@twin.org/engine-models";
 import type { IEngineConfig } from "@twin.org/engine-types";
 /**
  * The options when running the node.
@@ -36,7 +36,15 @@ export interface IRunOptions {
     /**
      * Method to extend the engine configuration with any additional custom configuration.
      */
-    customConfig?: (config: IEngineConfig) => Promise<void>;
+    extendConfig?: (config: IEngineConfig) => Promise<void>;
+    /**
+     * Method to extend the engine with any additional options.
+     */
+    extendEngine?: (engine: IEngineCore) => Promise<void>;
+    /**
+     * Method to extend the engine server with any additional options.
+     */
+    extendEngineServer?: (engineServer: IEngineServer) => Promise<void>;
     /**
      * The state storage to use for the engine.
      * If not provided, a default file-based state storage will be used.

package/dist/types/server.d.ts

@@ -1,6 +1,6 @@
 import type { IServerInfo } from "@twin.org/api-models";
 import { Engine } from "@twin.org/engine";
-import { type IEngineStateStorage } from "@twin.org/engine-models";
+import { type IEngineCore, type IEngineServer, type IEngineStateStorage } from "@twin.org/engine-models";
 import { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
 import { type IEngineConfig } from "@twin.org/engine-types";
@@ -9,13 +9,16 @@ import type { INodeVariables } from "./models/INodeVariables";
 /**
  * Start the engine server.
  * @param serverInfo The server information.
+ * @param envVarsPrefix The prefix for the environment variables.
  * @param envVars The environment variables.
  * @param openApiSpecFile Path to the OpenAPI spec file.
  * @param stateStorage The state storage.
- * @param customConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param extendEngine Extends the engine with any additional options.
+ * @param extendEngineServer Extends the engine server with any additional options.
  * @returns The engine server.
  */
-export declare function start(serverInfo: IServerInfo, envVars: INodeVariables, openApiSpecFile?: string, stateStorage?: IEngineStateStorage, customConfig?: (config: IEngineConfig) => Promise<void>): Promise<{
+export declare function start(serverInfo: IServerInfo, envVarsPrefix: string, envVars: INodeVariables, openApiSpecFile?: string, stateStorage?: IEngineStateStorage, extendConfig?: (config: IEngineConfig) => Promise<void>, extendEngine?: (engine: IEngineCore) => Promise<void>, extendEngineServer?: (engineServer: IEngineServer) => Promise<void>): Promise<{
     engine: Engine<IEngineServerConfig, INodeState>;
     server: EngineServer;
 } | undefined>;

package/docs/changelog.md

@@ -1,12 +1,45 @@
-# Changelog
+# @twin.org/node-core - Changelog
 
-## [0.0.1-next.3](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.2...node-core-v0.0.1-next.3) (2025-05-27)
+## [0.0.1-next.6](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.5...node-core-v0.0.1-next.6) (2025-06-12)
 
 
 ### Features
 
+* add extend engine and server methods ([ec09c7e](https://github.com/twinfoundation/node/commit/ec09c7eb882d9f5797f2fd372e96cad1a3716f59))
+* add extend engine and server methods ([0136a6f](https://github.com/twinfoundation/node/commit/0136a6f3f4e1a82b1427ee9618b8a17c79bc7fda))
 * additional run options ([c35e5bb](https://github.com/twinfoundation/node/commit/c35e5bbb8a80fe6a36628d41f64585b3723d9ad7))
+* improve error reporting ([fcd39a1](https://github.com/twinfoundation/node/commit/fcd39a18da2a6ce33965a99ca5f2f36f4aba712f))
+* initial commit ([522f1e5](https://github.com/twinfoundation/node/commit/522f1e515348f9b1dd1eeb3170b1249e2b0b5371))
 * node app use JavaScript ([14fe08c](https://github.com/twinfoundation/node/commit/14fe08cb760dd885a5dac9056a4d5dbc3d61df64))
+* update dependencies ([9d25f16](https://github.com/twinfoundation/node/commit/9d25f16f1d554cd38f3bec28fdf7f8fff892ceaf))
+
+
+### Bug Fixes
+
+* broken docs ([61479fd](https://github.com/twinfoundation/node/commit/61479fd618f766d22c5aafec5277e1a89e22b453))
+
+## [0.0.1-next.5](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.4...node-core-v0.0.1-next.5) (2025-06-12)
+
+### Features
+
+- add extend engine and server methods ([0136a6f](https://github.com/twinfoundation/node/commit/0136a6f3f4e1a82b1427ee9618b8a17c79bc7fda))
+
+## [0.0.1-next.4](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.3...node-core-v0.0.1-next.4) (2025-05-27)
+
+### Features
+
+- improve error reporting ([fcd39a1](https://github.com/twinfoundation/node/commit/fcd39a18da2a6ce33965a99ca5f2f36f4aba712f))
+
+### Bug Fixes
+
+- broken docs ([61479fd](https://github.com/twinfoundation/node/commit/61479fd618f766d22c5aafec5277e1a89e22b453))
+
+## [0.0.1-next.3](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.2...node-core-v0.0.1-next.3) (2025-05-27)
+
+### Features
+
+- additional run options ([c35e5bb](https://github.com/twinfoundation/node/commit/c35e5bbb8a80fe6a36628d41f64585b3723d9ad7))
+- node app use JavaScript ([14fe08c](https://github.com/twinfoundation/node/commit/14fe08cb760dd885a5dac9056a4d5dbc3d61df64))
 
 ## [0.0.1-next.2](https://github.com/twinfoundation/node/compare/node-core-v0.0.1-next.1...node-core-v0.0.1-next.2) (2025-05-27)
 

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/node-core - Examples

package/docs/reference/functions/start.md

@@ -1,6 +1,6 @@
 # Function: start()
 
-> **start**(`serverInfo`, `envVars`, `openApiSpecFile?`, `stateStorage?`, `customConfig?`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeState`](../interfaces/INodeState.md)\>; `server`: `EngineServer`; \}\>
+> **start**(`serverInfo`, `envVarsPrefix`, `envVars`, `openApiSpecFile?`, `stateStorage?`, `extendConfig?`, `extendEngine?`, `extendEngineServer?`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeState`](../interfaces/INodeState.md)\>; `server`: `EngineServer`; \}\>
 
 Start the engine server.
 
@@ -12,6 +12,12 @@ Start the engine server.
 
 The server information.
 
+### envVarsPrefix
+
+`string`
+
+The prefix for the environment variables.
+
 ### envVars
 
 [`INodeVariables`](../interfaces/INodeVariables.md)
@@ -30,12 +36,24 @@ Path to the OpenAPI spec file.
 
 The state storage.
 
-### customConfig?
+### extendConfig?
 
 (`config`) => `Promise`\<`void`\>
 
 Extends the engine configuration with any additional custom configuration.
 
+### extendEngine?
+
+(`engine`) => `Promise`\<`void`\>
+
+Extends the engine with any additional options.
+
+### extendEngineServer?
+
+(`engineServer`) => `Promise`\<`void`\>
+
+Extends the engine server with any additional options.
+
 ## Returns
 
 `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeState`](../interfaces/INodeState.md)\>; `server`: `EngineServer`; \}\>

package/docs/reference/interfaces/IRunOptions.md

@@ -66,9 +66,9 @@ The path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
 
 ***
 
-### customConfig()?
+### extendConfig()?
 
-> `optional` **customConfig**: (`config`) => `Promise`\<`void`\>
+> `optional` **extendConfig**: (`config`) => `Promise`\<`void`\>
 
 Method to extend the engine configuration with any additional custom configuration.
 
@@ -84,6 +84,42 @@ Method to extend the engine configuration with any additional custom configurati
 
 ***
 
+### extendEngine()?
+
+> `optional` **extendEngine**: (`engine`) => `Promise`\<`void`\>
+
+Method to extend the engine with any additional options.
+
+#### Parameters
+
+##### engine
+
+`IEngineCore`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### extendEngineServer()?
+
+> `optional` **extendEngineServer**: (`engineServer`) => `Promise`\<`void`\>
+
+Method to extend the engine server with any additional options.
+
+#### Parameters
+
+##### engineServer
+
+`IEngineServer`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
 ### stateStorage?
 
 > `optional` **stateStorage**: `IEngineStateStorage`\<`IEngineState`\>

package/locales/en.json

@@ -1,8 +1,8 @@
 {
 	"error": {
 		"node": {
-			"noEnvVars": "There are no environment variables starting TWIN_NODE_ the server will not start without them, please set them in the shell or create a .env file",
-			"storageFileRootNotSet": "TWIN_NODE_STORAGE_FILE_ROOT is not set, the server will not start without it, please set it in the shell or create a .env file"
+			"noEnvVars": "There are no environment variables starting \"{prefix}\" the server will not start without them, please set them in the shell or create a .env file",
+			"storageFileRootNotSet": "{storageFileRoot} is not set, the server will not start without it, please set it in the shell or create a .env file"
 		}
 	},
 	"node": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/node-core",
-	"version": "0.0.1-next.3",
+	"version": "0.0.1-next.6",
 	"description": "TWIN Node Core for serving APIs using the specified configuration",
 	"repository": {
 		"type": "git",