@twin.org/node-core 0.0.3-next.28 → 0.0.3-next.29

package/docs/reference/interfaces/INodeOptions.md

@@ -4,25 +4,31 @@ The options when running the node.
 
 ## Properties
 
-### serverName?
+### serverName? {#servername}
 
-> `optional` **serverName**: `string`
+> `optional` **serverName?**: `string`
 
 The name of the server, defaults to "TWIN Node".
 
+#### Default
+
+```ts
+"TWIN Node"
+```
+
 ***
 
-### serverVersion?
+### serverVersion? {#serverversion}
 
-> `optional` **serverVersion**: `string`
+> `optional` **serverVersion?**: `string`
 
 The version of the server, defaults to the current version.
 
 ***
 
-### envVars?
+### envVars? {#envvars}
 
-> `optional` **envVars**: `object`
+> `optional` **envVars?**: `object`
 
 Additional environment variables to set.
 
@@ -32,25 +38,25 @@ Additional environment variables to set.
 
 ***
 
-### envFilenames?
+### envFilenames? {#envfilenames}
 
-> `optional` **envFilenames**: `string`[]
+> `optional` **envFilenames?**: `string`[]
 
 Additional environment variable filenames to load, defaults to .env.
 
 ***
 
-### envPrefix?
+### envPrefix? {#envprefix}
 
-> `optional` **envPrefix**: `string`
+> `optional` **envPrefix?**: `string`
 
 The prefix for environment variables, defaults to "TWIN_".
 
 ***
 
-### configFilenames?
+### configFilenames? {#configfilenames}
 
-> `optional` **configFilenames**: `string`[]
+> `optional` **configFilenames?**: `string`[]
 
 A list of JSON files to load as configuration files.
 The files will be loaded in the order they are provided, and the last one will
@@ -58,58 +64,58 @@ override any previous values.
 
 ***
 
-### config?
+### config? {#config}
 
-> `optional` **config**: `IEngineConfig`
+> `optional` **config?**: `IEngineConfig`
 
 Provides the ability to have some initial custom configuration for the engine.
 This will be merged with any configuration loaded from the environment variables.
 
 ***
 
-### scriptDirectory?
+### scriptDirectory? {#scriptdirectory}
 
-> `optional` **scriptDirectory**: `string`
+> `optional` **scriptDirectory?**: `string`
 
 The directory to override the script location, defaults to location of index.js.
 
 ***
 
-### executionDirectory?
+### executionDirectory? {#executiondirectory}
 
-> `optional` **executionDirectory**: `string`
+> `optional` **executionDirectory?**: `string`
 
 The directory to override the execution location, defaults to process directory.
 
 ***
 
-### localesDirectory?
+### localesDirectory? {#localesdirectory}
 
-> `optional` **localesDirectory**: `string`
+> `optional` **localesDirectory?**: `string`
 
 The directory to override the locales directory, defaults to the locales directory.
 
 ***
 
-### openApiSpecFile?
+### openApiSpecFile? {#openapispecfile}
 
-> `optional` **openApiSpecFile**: `string`
+> `optional` **openApiSpecFile?**: `string`
 
 The path to the OpenAPI spec file, defaults to docs/open-api/spec.json.
 
 ***
 
-### favIconFile?
+### favIconFile? {#faviconfile}
 
-> `optional` **favIconFile**: `string`
+> `optional` **favIconFile?**: `string`
 
 The path to the favicon, defaults to static/favicon.png.
 
 ***
 
-### extendEnvVars()?
+### extendEnvVars? {#extendenvvars}
 
-> `optional` **extendEnvVars**: (`envVars`) => `Promise`\<`void`\>
+> `optional` **extendEnvVars?**: (`envVars`) => `Promise`\<`void`\>
 
 Method to extend the engine environment variables with any additional custom configuration.
 
@@ -125,9 +131,9 @@ Method to extend the engine environment variables with any additional custom con
 
 ***
 
-### extendConfig()?
+### extendConfig? {#extendconfig}
 
-> `optional` **extendConfig**: (`envVars`, `config`) => `Promise`\<`void`\>
+> `optional` **extendConfig?**: (`envVars`, `config`) => `Promise`\<`void`\>
 
 Method to extend the engine configuration with any additional custom configuration.
 
@@ -147,9 +153,9 @@ Method to extend the engine configuration with any additional custom configurati
 
 ***
 
-### extendEngine()?
+### extendEngine? {#extendengine}
 
-> `optional` **extendEngine**: (`engine`) => `Promise`\<`void`\>
+> `optional` **extendEngine?**: (`engine`) => `Promise`\<`void`\>
 
 Method to extend the engine with any additional options.
 
@@ -165,9 +171,9 @@ Method to extend the engine with any additional options.
 
 ***
 
-### extendEngineServer()?
+### extendEngineServer? {#extendengineserver}
 
-> `optional` **extendEngineServer**: (`engineServer`) => `Promise`\<`void`\>
+> `optional` **extendEngineServer?**: (`engineServer`) => `Promise`\<`void`\>
 
 Method to extend the engine server with any additional options.
 
@@ -183,17 +189,17 @@ Method to extend the engine server with any additional options.
 
 ***
 
-### stateStorage?
+### stateStorage? {#statestorage}
 
-> `optional` **stateStorage**: `IEngineStateStorage`\<`IEngineState`\>
+> `optional` **stateStorage?**: `IEngineStateStorage`\<`IEngineState`\>
 
 The state storage to use for the engine.
 If not provided, a default file-based state storage will be used.
 
 ***
 
-### disableProcessExitOnFailure?
+### disableProcessExitOnFailure? {#disableprocessexitonfailure}
 
-> `optional` **disableProcessExitOnFailure**: `boolean`
+> `optional` **disableProcessExitOnFailure?**: `boolean`
 
 Disables process.exit calls on fatal errors and throws instead.

package/docs/reference/interfaces/IProtocolHandlerResult.md

@@ -4,7 +4,7 @@ The result from a protocol handler.
 
 ## Properties
 
-### resolvedPath
+### resolvedPath {#resolvedpath}
 
 > **resolvedPath**: `string`
 
@@ -12,7 +12,7 @@ The resolved path to the module file.
 
 ***
 
-### cached
+### cached {#cached}
 
 > **cached**: `boolean`
 

package/docs/reference/type-aliases/NodeExtensionInitialiseEngineMethod.md

@@ -1,4 +1,4 @@
-# Type Alias: NodeExtensionInitialiseEngineMethod()
+# Type Alias: NodeExtensionInitialiseEngineMethod
 
 > **NodeExtensionInitialiseEngineMethod** = (`engineCore`) => `Promise`\<`void`\>
 

package/docs/reference/type-aliases/NodeExtensionInitialiseEngineServerMethod.md

@@ -1,4 +1,4 @@
-# Type Alias: NodeExtensionInitialiseEngineServerMethod()
+# Type Alias: NodeExtensionInitialiseEngineServerMethod
 
 > **NodeExtensionInitialiseEngineServerMethod** = (`engineCore`, `engineServer`) => `Promise`\<`void`\>
 

package/docs/reference/type-aliases/NodeExtensionInitialiseMethod.md

@@ -1,4 +1,4 @@
-# Type Alias: NodeExtensionInitialiseMethod()
+# Type Alias: NodeExtensionInitialiseMethod
 
 > **NodeExtensionInitialiseMethod** = (`envVars`, `nodeEngineConfig`) => `Promise`\<`void`\>
 

package/docs/reference/type-aliases/NodeExtensionShutdownMethod.md

@@ -1,4 +1,4 @@
-# Type Alias: NodeExtensionShutdownMethod()
+# Type Alias: NodeExtensionShutdownMethod
 
 > **NodeExtensionShutdownMethod** = () => `Promise`\<`void`\>
 

package/docs/reference/variables/ModuleProtocol.md

@@ -6,31 +6,31 @@ The protocol types for modules.
 
 ## Type Declaration
 
-### Local
+### Local {#local}
 
 > `readonly` **Local**: `"local"` = `"local"`
 
 Local module (starts with . or / or file://).
 
-### Npm
+### Npm {#npm}
 
 > `readonly` **Npm**: `"npm"` = `"npm"`
 
 NPM package (starts with npm:).
 
-### Https
+### Https {#https}
 
 > `readonly` **Https**: `"https"` = `"https"`
 
 HTTPS URL (starts with https://).
 
-### Http
+### Http {#http}
 
 > `readonly` **Http**: `"http"` = `"http"`
 
 HTTP URL (starts with http://).
 
-### Default
+### Default {#default}
 
 > `readonly` **Default**: `"default"` = `"default"`
 

package/package.json

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

package/docs/detailed-guide.md

@@ -1,129 +0,0 @@
-# TWIN Node - Detailed Documentation
-
-## Overview
-
-TWIN Node provides the foundational components for running TWIN nodes, including dynamic extension loading, protocol-based module resolution, and lifecycle management.
-
-## Protocol-Based Extension Loading
-
-The TWIN Node supports dynamic extension loading from multiple sources:
-
-### Local Files
-
-Load extensions from your filesystem:
-
-```bash
-TWIN_EXTENSIONS="./my-extension.mjs"
-```
-
-### NPM Packages
-
-Automatically install and load npm packages:
-
-```bash
-TWIN_EXTENSIONS="npm:@twin.org/package"
-```
-
-### HTTPS URLs
-
-Download and cache remote extensions:
-
-```bash
-TWIN_EXTENSIONS="https://example.com/extension.mjs"
-```
-
-## Extension Lifecycle Hooks
-
-Extensions can implement lifecycle hooks to customize node behavior at different stages:
-
-- **`extensionInitialise`** - Called before engine initialization
-- **`extensionInitialiseEngine`** - Called during engine initialization
-- **`extensionInitialiseEngineServer`** - Called during server initialization
-- **`extensionShutdown`** - Called during graceful shutdown
-
-### Example Extension
-
-```javascript
-// my-extension.mjs
-export function extensionInitialise() {
-  console.log('Extension initializing...');
-}
-
-export function extensionInitialiseEngine(engine) {
-  console.log('Configuring engine...');
-  // Add custom components, routes, etc.
-}
-
-export function extensionInitialiseEngineServer(server) {
-  console.log('Configuring server...');
-  // Add middleware, routes, etc.
-}
-
-export function extensionShutdown() {
-  console.log('Extension shutting down...');
-  // Cleanup resources
-}
-```
-
-## Configuration Options
-
-### Cache Management
-
-- `TWIN_EXTENSIONS_CACHE_TTL_HOURS` - TTL for HTTPS extensions cache (default: 24)
-- `TWIN_EXTENSIONS_FORCE_REFRESH` - Force refresh all cached extensions (default: false)
-- `TWIN_EXTENSIONS_CACHE_DIRECTORY` - Custom cache directory (default: ".tmp")
-
-### Security
-
-- `TWIN_EXTENSIONS_MAX_SIZE_MB` - Maximum size for HTTPS downloads (default: 10)
-- `TWIN_EXTENSIONS_CLEAR_CACHE` - Clear cache on startup (default: false)
-
-## API Reference
-
-### Core Functions
-
-#### `overrideModuleImport(executionDirectory, envVars)`
-
-Sets up protocol-based module resolution for extensions.
-
-#### `buildConfiguration(options)`
-
-Builds node configuration from environment variables and options.
-
-#### `start(options)`
-
-Starts the TWIN node with the specified configuration.
-
-### Utility Functions
-
-#### `parseModuleProtocol(moduleName)`
-
-Parses module name to determine protocol type (npm, https, local, etc.).
-
-#### `handleNpmProtocol(packageName, executionDirectory, cacheDirectory)`
-
-Handles installation and resolution of npm packages.
-
-#### `handleHttpsProtocol(url, executionDirectory, maxSizeMb, cacheDirectory, ttlHours, forceRefresh)`
-
-Handles download and caching of HTTPS extensions.
-
-## Security Considerations
-
-- **HTTPS Only**: Remote extensions must use HTTPS protocol
-- **Size Limits**: Downloads are limited by `TWIN_EXTENSIONS_MAX_SIZE_MB`
-- **Cache TTL**: Extensions are automatically refreshed based on TTL
-- **Security Warnings**: Warnings are displayed when loading remote extensions
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Extension not found**: Check that the path/URL is correct and accessible
-2. **Cache issues**: Use `TWIN_EXTENSIONS_FORCE_REFRESH=true` to force refresh
-3. **Size limit exceeded**: Increase `TWIN_EXTENSIONS_MAX_SIZE_MB` if needed
-4. **Network issues**: Ensure HTTPS URLs are accessible and not blocked by firewall
-
-### Debug Mode
-
-Set `NODE_ENV=development` for additional debug output during extension loading.