@twin.org/node-core 0.0.1-next.3 → 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,19 +491,22 @@ 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.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customConfig) {
+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);
@@ -546,7 +549,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.4" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -572,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, options.stateStorage, options.customConfig);
+        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,19 +470,22 @@ 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.
  * @returns The engine server.
  */
-async function start(serverInfo, envVars, openApiSpecFile, stateStorage, customConfig) {
+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);
@@ -525,7 +528,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.4" // x-release-please-version
         };
         console.log(`\u001B[4m🌩️  ${serverInfo.name} v${serverInfo.version}\u001B[24m\n`);
         const executionDirectory = options?.executionDirectory ?? getExecutionDirectory();
@@ -551,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, options.stateStorage, options.customConfig);
+        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/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 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, customConfig?: (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,12 +1,23 @@
-# 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.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))
+- 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?`, `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)

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