@twin.org/node-core 0.0.1-next.2 → 0.0.1-next.4

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,28 @@ 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 extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param customConfig Extends the engine configuration with any additional custom configuration.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, extendConfig) {
+async function start(serverInfo, envVarsPrefix, envVars, openApiSpecFile, stateStorage, customConfig) {
     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(extendConfig)) {
-        await extendConfig(engineConfig);
+    if (core.Is.function(customConfig)) {
+        await customConfig(engineConfig);
     }
     // Build the server configuration from the environment variables.
     const serverConfig = engineServer.buildEngineServerConfiguration(envVars, engineConfig, serverInfo, openApiSpecFile);
@@ -539,21 +542,14 @@ async function start(serverInfo, envVars, openApiSpecFile, stateStorage, extendC
 /* eslint-disable no-console */
 /**
  * Run the TWIN Node server.
- * @param options Optional options for the server.
- * @param options.serverName Optional name of the server, defaults to "TWIN Node Server".
- * @param options.serverVersion Optional version of the server, defaults to current version.
- * @param options.envFilenames Additional environment variable filenames to load, defaults to .env.
- * @param options.envPrefix Optional prefix for environment variables, defaults to "TWIN_NODE_".
- * @param options.executionDirectory Optional directory to override the execution location, defaults to process directory.
- * @param options.localesDirectory Optional directory to override the locales directory, defaults to the locales directory.
- * @param options.openApiSpecFile Optional path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+ * @param options Optional configuration options for running the server.
  * @returns A promise that resolves when the server is started.
  */
 async function run(options) {
     try {
         const serverInfo = {
             name: options?.serverName ?? "TWIN Node Server",
-            version: options?.serverVersion ?? "0.0.1-next.1" // x-release-please-version
+            version: options?.serverVersion ?? "0.0.1-next.4" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -579,8 +575,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);
+        const startResult = await start(serverInfo, envPrefix, envVars, options?.openApiSpecFile, options.stateStorage, options.customConfig);
         if (!core.Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
                 process.on(signal, async () => {

package/dist/esm/index.mjs

@@ -470,25 +470,28 @@ 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 extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param customConfig Extends the engine configuration with any additional custom configuration.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, extendConfig) {
+async function start(serverInfo, envVarsPrefix, envVars, openApiSpecFile, stateStorage, customConfig) {
     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(extendConfig)) {
-        await extendConfig(engineConfig);
+    if (Is.function(customConfig)) {
+        await customConfig(engineConfig);
     }
     // Build the server configuration from the environment variables.
     const serverConfig = buildEngineServerConfiguration(envVars, engineConfig, serverInfo, openApiSpecFile);
@@ -518,21 +521,14 @@ async function start(serverInfo, envVars, openApiSpecFile, stateStorage, extendC
 /* eslint-disable no-console */
 /**
  * Run the TWIN Node server.
- * @param options Optional options for the server.
- * @param options.serverName Optional name of the server, defaults to "TWIN Node Server".
- * @param options.serverVersion Optional version of the server, defaults to current version.
- * @param options.envFilenames Additional environment variable filenames to load, defaults to .env.
- * @param options.envPrefix Optional prefix for environment variables, defaults to "TWIN_NODE_".
- * @param options.executionDirectory Optional directory to override the execution location, defaults to process directory.
- * @param options.localesDirectory Optional directory to override the locales directory, defaults to the locales directory.
- * @param options.openApiSpecFile Optional path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+ * @param options Optional configuration options for running the server.
  * @returns A promise that resolves when the server is started.
  */
 async function run(options) {
     try {
         const serverInfo = {
             name: options?.serverName ?? "TWIN Node Server",
-            version: options?.serverVersion ?? "0.0.1-next.1" // x-release-please-version
+            version: options?.serverVersion ?? "0.0.1-next.4" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -558,8 +554,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);
+        const startResult = await start(serverInfo, envPrefix, envVars, options?.openApiSpecFile, options.stateStorage, options.customConfig);
         if (!Is.empty(startResult)) {
             for (const signal of ["SIGHUP", "SIGINT", "SIGTERM"]) {
                 process.on(signal, async () => {

package/dist/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./bootstrap";
 export * from "./models/INodeState";
 export * from "./models/INodeVariables";
+export * from "./models/IRunOptions";
 export * from "./models/nodeFeatures";
 export * from "./node";
 export * from "./server";

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

@@ -0,0 +1,45 @@
+import type { IEngineStateStorage } from "@twin.org/engine-models";
+import type { IEngineConfig } from "@twin.org/engine-types";
+/**
+ * The options when running the node.
+ */
+export interface IRunOptions {
+    /**
+     * The name of the server, defaults to "TWIN Node Server".
+     * @default "TWIN Node Server"
+     */
+    serverName?: string;
+    /**
+     * The version of the server, defaults to the current version.
+     */
+    serverVersion?: string;
+    /**
+     * Additional environment variable filenames to load, defaults to .env.
+     */
+    envFilenames?: string[];
+    /**
+     * The prefix for environment variables, defaults to "TWIN_NODE_".
+     */
+    envPrefix?: string;
+    /**
+     * The directory to override the execution location, defaults to process directory.
+     */
+    executionDirectory?: string;
+    /**
+     * The directory to override the locales directory, defaults to the locales directory.
+     */
+    localesDirectory?: string;
+    /**
+     * The path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+     */
+    openApiSpecFile?: string;
+    /**
+     * Method to extend the engine configuration with any additional custom configuration.
+     */
+    customConfig?: (config: IEngineConfig) => Promise<void>;
+    /**
+     * The state storage to use for the engine.
+     * If not provided, a default file-based state storage will be used.
+     */
+    stateStorage?: IEngineStateStorage;
+}

package/dist/types/node.d.ts

@@ -1,21 +1,7 @@
+import type { IRunOptions } from "./models/IRunOptions";
 /**
  * Run the TWIN Node server.
- * @param options Optional options for the server.
- * @param options.serverName Optional name of the server, defaults to "TWIN Node Server".
- * @param options.serverVersion Optional version of the server, defaults to current version.
- * @param options.envFilenames Additional environment variable filenames to load, defaults to .env.
- * @param options.envPrefix Optional prefix for environment variables, defaults to "TWIN_NODE_".
- * @param options.executionDirectory Optional directory to override the execution location, defaults to process directory.
- * @param options.localesDirectory Optional directory to override the locales directory, defaults to the locales directory.
- * @param options.openApiSpecFile Optional path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+ * @param options Optional configuration options for running the server.
  * @returns A promise that resolves when the server is started.
  */
-export declare function run(options?: {
-    serverName?: string;
-    serverVersion?: string;
-    envFilenames?: string[];
-    envPrefix?: string;
-    executionDirectory?: string;
-    localesDirectory?: string;
-    openApiSpecFile?: string;
-}): Promise<void>;
+export declare function run(options?: IRunOptions): Promise<void>;

package/dist/types/server.d.ts

@@ -9,13 +9,14 @@ 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 extendConfig Extends the engine configuration with any additional custom configuration.
+ * @param customConfig Extends the engine configuration with any additional custom configuration.
  * @returns The engine server.
  */
-export declare function start(serverInfo: IServerInfo, envVars: INodeVariables, openApiSpecFile?: string, stateStorage?: IEngineStateStorage, extendConfig?: (config: IEngineConfig) => Promise<void>): Promise<{
+export declare function start(serverInfo: IServerInfo, envVarsPrefix: string, envVars: INodeVariables, openApiSpecFile?: string, stateStorage?: IEngineStateStorage, customConfig?: (config: IEngineConfig) => Promise<void>): Promise<{
     engine: Engine<IEngineServerConfig, INodeState>;
     server: EngineServer;
 } | undefined>;

package/docs/changelog.md

@@ -1,8 +1,26 @@
-# Changelog
+# @twin.org/node-core - Changelog
 
-## [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)
+## [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)
 
 ### Features
 
-* initial commit ([522f1e5](https://github.com/twinfoundation/node/commit/522f1e515348f9b1dd1eeb3170b1249e2b0b5371))
+- initial commit ([522f1e5](https://github.com/twinfoundation/node/commit/522f1e515348f9b1dd1eeb3170b1249e2b0b5371))

package/docs/examples.md

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

package/docs/reference/functions/run.md

@@ -8,49 +8,9 @@ Run the TWIN Node server.
 
 ### options?
 
-Optional options for the server.
+[`IRunOptions`](../interfaces/IRunOptions.md)
 
-#### serverName?
-
-`string`
-
-Optional name of the server, defaults to "TWIN Node Server".
-
-#### serverVersion?
-
-`string`
-
-Optional version of the server, defaults to current version.
-
-#### envFilenames?
-
-`string`[]
-
-Additional environment variable filenames to load, defaults to .env.
-
-#### envPrefix?
-
-`string`
-
-Optional prefix for environment variables, defaults to "TWIN_NODE_".
-
-#### executionDirectory?
-
-`string`
-
-Optional directory to override the execution location, defaults to process directory.
-
-#### localesDirectory?
-
-`string`
-
-Optional directory to override the locales directory, defaults to the locales directory.
-
-#### openApiSpecFile?
-
-`string`
-
-Optional path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+Optional configuration options for running the server.
 
 ## Returns
 

package/docs/reference/functions/start.md

@@ -1,6 +1,6 @@
 # Function: start()
 
-> **start**(`serverInfo`, `envVars`, `openApiSpecFile?`, `stateStorage?`, `extendConfig?`): `Promise`\<`undefined` \| \{ `engine`: `Engine`\<`IEngineServerConfig`, [`INodeState`](../interfaces/INodeState.md)\>; `server`: `EngineServer`; \}\>
+> **start**(`serverInfo`, `envVarsPrefix`, `envVars`, `openApiSpecFile?`, `stateStorage?`, `customConfig?`): `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,7 +36,7 @@ Path to the OpenAPI spec file.
 
 The state storage.
 
-### extendConfig?
+### customConfig?
 
 (`config`) => `Promise`\<`void`\>
 

package/docs/reference/index.md

@@ -4,6 +4,7 @@
 
 - [INodeState](interfaces/INodeState.md)
 - [INodeVariables](interfaces/INodeVariables.md)
+- [IRunOptions](interfaces/IRunOptions.md)
 
 ## Type Aliases
 

package/docs/reference/interfaces/IRunOptions.md

@@ -0,0 +1,92 @@
+# Interface: IRunOptions
+
+The options when running the node.
+
+## Properties
+
+### serverName?
+
+> `optional` **serverName**: `string`
+
+The name of the server, defaults to "TWIN Node Server".
+
+#### Default
+
+```ts
+"TWIN Node Server"
+```
+
+***
+
+### serverVersion?
+
+> `optional` **serverVersion**: `string`
+
+The version of the server, defaults to the current version.
+
+***
+
+### envFilenames?
+
+> `optional` **envFilenames**: `string`[]
+
+Additional environment variable filenames to load, defaults to .env.
+
+***
+
+### envPrefix?
+
+> `optional` **envPrefix**: `string`
+
+The prefix for environment variables, defaults to "TWIN_NODE_".
+
+***
+
+### executionDirectory?
+
+> `optional` **executionDirectory**: `string`
+
+The directory to override the execution location, defaults to process directory.
+
+***
+
+### localesDirectory?
+
+> `optional` **localesDirectory**: `string`
+
+The directory to override the locales directory, defaults to the locales directory.
+
+***
+
+### openApiSpecFile?
+
+> `optional` **openApiSpecFile**: `string`
+
+The path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
+
+***
+
+### customConfig()?
+
+> `optional` **customConfig**: (`config`) => `Promise`\<`void`\>
+
+Method to extend the engine configuration with any additional custom configuration.
+
+#### Parameters
+
+##### config
+
+`IEngineConfig`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### stateStorage?
+
+> `optional` **stateStorage**: `IEngineStateStorage`\<`IEngineState`\>
+
+The state storage to use for the engine.
+If not provided, a default file-based state storage will be used.

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.2",
+	"version": "0.0.1-next.4",
 	"description": "TWIN Node Core for serving APIs using the specified configuration",
 	"repository": {
 		"type": "git",