@twin.org/node-core 0.0.3-next.8 → 0.9.0-next.1

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

@@ -0,0 +1,4 @@
+/**
+ * Type for the properties in commands.
+ */
+export type CliCommandParamType = string | number | boolean;

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

@@ -0,0 +1,4 @@
+/**
+ * The set of camelCase property names that are valid IEngineEnvironmentVariables keys.
+ */
+export declare const ENGINE_ENVIRONMENT_VARIABLE_KEYS: ReadonlySet<string>;

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

@@ -0,0 +1,7 @@
+/**
+ * The set of camelCase property names (and wildcard patterns ending with *) that are valid
+ * IEngineServerEnvironmentVariables keys.
+ * Used at startup to detect unrecognised TWIN_* environment variables (typos, stale names).
+ * The "restPath*" entry covers dynamic TWIN_REST_PATH_<COMPONENT_TYPE> variables.
+ */
+export declare const ENGINE_SERVER_ENVIRONMENT_VARIABLE_KEYS: ReadonlySet<string>;

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

@@ -0,0 +1,5 @@
+/**
+ * The set of camelCase property names that are valid INodeEnvironmentVariables keys.
+ * Used at startup to detect unrecognised TWIN_* environment variables (typos, stale names).
+ */
+export declare const NODE_ENVIRONMENT_VARIABLE_KEYS: ReadonlySet<string>;

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

@@ -0,0 +1,8 @@
+import type { IEngineCore } from "@twin.org/engine-models";
+/**
+ * The type for the initialise engine method of an extension module.
+ * This is called when the engine has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ * @returns A promise that resolves when the extension engine initialisation is complete.
+ */
+export type NodeExtensionInitialiseEngineMethod = (engineCore: IEngineCore) => Promise<void>;

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

@@ -0,0 +1,9 @@
+import type { IEngineCore, IEngineServer } from "@twin.org/engine-models";
+/**
+ * The type for the initialise engine server method of an extension module.
+ * This is called when the engine server has been constructed but not yet started.
+ * @param engineCore The engine core instance.
+ * @param engineServer The engine server instance.
+ * @returns A promise that resolves when the extension engine-server initialisation is complete.
+ */
+export type NodeExtensionInitialiseEngineServerMethod = (engineCore: IEngineCore, engineServer: IEngineServer) => Promise<void>;

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

@@ -0,0 +1,9 @@
+import type { IEnvironmentVariables } from "./IEnvironmentVariables.js";
+import type { INodeEngineConfig } from "./INodeEngineConfig.js";
+/**
+ * The type for the initialise method of an extension module.
+ * @param envVars The environment variables for the node.
+ * @param nodeEngineConfig The node engine config.
+ * @returns A promise that resolves when the extension configuration initialisation is complete.
+ */
+export type NodeExtensionInitialiseMethod = (envVars: IEnvironmentVariables, nodeEngineConfig: INodeEngineConfig) => Promise<void>;

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

@@ -0,0 +1,6 @@
+/**
+ * The type for the shutdown method of an extension module.
+ * This is called when the engine is shutting down.
+ * @returns A promise that resolves when the extension shutdown is complete.
+ */
+export type NodeExtensionShutdownMethod = () => Promise<void>;

package/dist/types/node.d.ts

@@ -2,22 +2,23 @@ import type { IServerInfo } from "@twin.org/api-models";
 import type { Engine } from "@twin.org/engine";
 import type { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { IEnvironmentVariables } from "./models/IEnvironmentVariables.js";
 import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
 import type { INodeEngineState } from "./models/INodeEngineState.js";
-import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
 import type { INodeOptions } from "./models/INodeOptions.js";
 /**
- * Run the TWIN Node server.
+ * Run the TWIN Node.
  * @param nodeOptions Optional configuration options for running the server.
+ * @param args Optional command line arguments.
  * @returns A promise that resolves when the server is started containing a shutdown method.
  */
-export declare function run(nodeOptions?: INodeOptions): Promise<{
+export declare function run(nodeOptions?: INodeOptions, args?: string[]): Promise<{
     engine: Engine<IEngineServerConfig, INodeEngineState>;
     server: EngineServer;
     shutdown: () => Promise<void>;
 } | undefined>;
 /**
- * Build the configuration for the TWIN Node server.
+ * Build the configuration for the TWIN Node.
  * @param processEnv The environment variables from the process.
  * @param options The options for running the server.
  * @param serverInfo The server information.
@@ -27,13 +28,13 @@ export declare function run(nodeOptions?: INodeOptions): Promise<{
 export declare function buildConfiguration(processEnv: {
     [id: string]: string;
 }, options: INodeOptions, serverInfo: IServerInfo): Promise<{
-    nodeEnvVars: INodeEnvironmentVariables & {
+    nodeEnvVars: IEnvironmentVariables & {
         [id: string]: string | unknown;
     };
     nodeEngineConfig: INodeEngineConfig;
     availableContextIdKeys: {
         key: string;
-        componentFeatures: string[];
+        requiredHandlerFeatures: string[];
     }[];
 }>;
 /**
@@ -41,4 +42,4 @@ export declare function buildConfiguration(processEnv: {
  * @param executionDirectory The execution directory for resolving local module paths.
  * @param envVars The environment variables containing extension configuration (optional, uses defaults if not provided).
  */
-export declare function overrideModuleImport(executionDirectory: string, envVars?: INodeEnvironmentVariables): void;
+export declare function overrideModuleImport(executionDirectory: string, envVars?: IEnvironmentVariables): void;

package/dist/types/{server.d.ts → start.d.ts}

@@ -1,21 +1,24 @@
 import { Engine } from "@twin.org/engine";
 import { EngineServer } from "@twin.org/engine-server";
 import type { IEngineServerConfig } from "@twin.org/engine-server-types";
+import type { ICliCommand } from "./models/ICliCommand.js";
+import type { IEngineEnvironmentVariables } from "./models/IEngineEnvironmentVariables.js";
+import type { IEnvironmentVariables } from "./models/IEnvironmentVariables.js";
 import type { INodeEngineConfig } from "./models/INodeEngineConfig.js";
 import type { INodeEngineState } from "./models/INodeEngineState.js";
-import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
 import type { INodeOptions } from "./models/INodeOptions.js";
 /**
  * Start the engine server.
  * @param nodeOptions Optional run options for the engine server.
  * @param nodeEngineConfig The configuration for the engine server.
  * @param envVars The environment variables.
+ * @param cliCommand The constructed CLI command (optional).
  * @param availableContextIdKeys The context ID keys available for operation.
  * @returns The engine server.
  */
-export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: INodeEnvironmentVariables, availableContextIdKeys?: {
+export declare function start(nodeOptions: INodeOptions | undefined, nodeEngineConfig: INodeEngineConfig, envVars: IEnvironmentVariables & IEngineEnvironmentVariables, cliCommand?: ICliCommand, availableContextIdKeys?: {
     key: string;
-    componentFeatures: string[];
+    requiredHandlerFeatures: string[];
 }[]): Promise<{
     engine: Engine<IEngineServerConfig, INodeEngineState>;
     server: EngineServer;

package/dist/types/utils.d.ts

@@ -1,11 +1,10 @@
 import type { IModuleProtocol } from "./models/IModuleProtocol.js";
-import type { INodeEnvironmentVariables } from "./models/INodeEnvironmentVariables.js";
 import type { IProtocolHandlerResult } from "./models/IProtocolHandlerResult.js";
 import { ModuleProtocol } from "./models/moduleProtocol.js";
-import { NodeFeatures } from "./models/nodeFeatures.js";
 /**
  * Initialise the locales for the application.
  * @param localesDirectory The directory containing the locales.
+ * @returns A promise that resolves when the locale dictionary has been loaded.
  */
 export declare function initialiseLocales(localesDirectory: string): Promise<void>;
 /**
@@ -13,6 +12,12 @@ export declare function initialiseLocales(localesDirectory: string): Promise<voi
  * @returns The execution directory.
  */
 export declare function getExecutionDirectory(): string;
+/**
+ * Get the directory where the script is located.
+ * @param args The command line arguments.
+ * @returns The directory containing the entry-point script, or the current working directory if not determinable.
+ */
+export declare function getScriptDirectory(args?: string[]): string;
 /**
  * Does the specified file exist.
  * @param filename The filename to check for existence.
@@ -40,21 +45,15 @@ export declare function getFiles(directory: string): Promise<string[]>;
 /**
  * Load the text file.
  * @param filename The filename of the text file to load.
- * @returns The contents of the text file if it could not be loaded.
+ * @returns The contents of the text file as a UTF-8 string.
  */
 export declare function loadTextFile(filename: string): Promise<string>;
 /**
  * Load the JSON file.
  * @param filename The filename of the JSON file to load.
- * @returns The contents of the JSON file or null if it could not be loaded.
+ * @returns The parsed JSON content of the file.
  */
 export declare function loadJsonFile<T>(filename: string): Promise<T>;
-/**
- * Get the features that are enabled on the node.
- * @param env The environment variables for the node.
- * @returns The features that are enabled on the node.
- */
-export declare function getFeatures(env: INodeEnvironmentVariables): NodeFeatures[];
 /**
  * Parse the protocol from a module name.
  * @param moduleName The module name to parse.