@twin.org/node-core 0.9.2-next.6 → 0.9.2-next.7

package/dist/types/builders/helper/envHelpers.d.ts

@@ -0,0 +1,80 @@
+import type { IEngineEnvironmentVariables } from "../../models/IEngineEnvironmentVariables.js";
+/**
+ * Coerces an env var to a boolean, falling back to the supplied default when not set.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @param defaultValue The value to return when the env var is absent.
+ * @returns The boolean value or the default.
+ * @throws GeneralError if the value is set but cannot be coerced to a boolean.
+ */
+export declare function envBoolean(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables, defaultValue: boolean): boolean;
+/**
+ * Coerces an env var that is already in milliseconds to an integer.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The millisecond value, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envMs(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var that represents an integer count or size to an integer.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The count, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envCount(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var that represents an integer to an integer.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The integer, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envInteger(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var that is already in seconds to an integer.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The second value, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envSeconds(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var that is already in minutes to an integer.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The minute value, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envMinutes(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var that is a datetime string, throwing when the value is set but not a valid datetime.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The datetime string, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to a datetime.
+ */
+export declare function envDateTime(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): string | undefined;
+/**
+ * Coerces an env var to an integer and converts from seconds to milliseconds.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The value in milliseconds, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envSecToMs(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Coerces an env var to an integer and converts from minutes to milliseconds.
+ * @param envVars The environment variables object.
+ * @param key The property name of the env var to coerce.
+ * @returns The value in milliseconds, or undefined when not set.
+ * @throws GeneralError if the value is set but cannot be coerced to an integer.
+ */
+export declare function envMinToMs(envVars: IEngineEnvironmentVariables, key: keyof IEngineEnvironmentVariables): number | undefined;
+/**
+ * Converts a comma separated list to an array.
+ * @param value The comma separated list.
+ * @returns The array.
+ */
+export declare function commaSeparatedListToArray<T>(value: string | undefined): T[];

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

@@ -138,7 +138,7 @@ export interface IEngineEnvironmentVariables {
     /**
      * MySQL port.
      */
-    mySqlPort?: number;
+    mySqlPort?: string;
     /**
      * MySQL username.
      */
@@ -158,7 +158,7 @@ export interface IEngineEnvironmentVariables {
     /**
      * MongoDB port.
      */
-    mongoDbPort?: number;
+    mongoDbPort?: string;
     /**
      * MongoDB username.
      */
@@ -178,7 +178,7 @@ export interface IEngineEnvironmentVariables {
     /**
      * PostgreSQl port.
      */
-    postgreSqlPort?: number;
+    postgreSqlPort?: string;
     /**
      * PostgreSQl username.
      */
@@ -564,18 +564,47 @@ export interface IEngineEnvironmentVariables {
      * The number of times to retry a proof task when it fails, 0 to disable retries.
      * @default 5
      */
-    immutableProofTaskRetryCount?: number;
+    immutableProofTaskRetryCount?: string;
     /**
      * The interval in seconds to wait between proof task retries.
      * @default 5
      */
-    immutableProofTaskRetryInterval?: number;
+    immutableProofTaskRetryInterval?: string;
     /**
      * The time in minutes to retain the record of a failed proof task.
      * Set to -1 to retain failures forever.
      * @default 10080
      */
-    immutableProofTaskFailureRetainFor?: number;
+    immutableProofTaskFailureRetainFor?: string;
+    /**
+     * How often in minutes the immutable proof reconciliation sweep runs.
+     * @default 30
+     */
+    immutableProofSweepInterval?: string;
+    /**
+     * The minimum age in minutes before a proof with no notarization is considered stuck.
+     * @default 180
+     */
+    immutableProofSweepStaleThreshold?: string;
+    /**
+     * The number of sweep attempts made before a proof is parked.
+     * @default 5
+     */
+    immutableProofSweepMaxAttempts?: string;
+    /**
+     * The maximum number of proofs to re-enqueue per tenant per sweep cycle.
+     * @default 10
+     */
+    immutableProofSweepBatchLimit?: string;
+    /**
+     * The minimum time in minutes between sweep attempts for the same proof.
+     * @default 60
+     */
+    immutableProofSweepBackoff?: string;
+    /**
+     * ISO 8601 date-time used to treat older missing-task proofs as retryable.
+     */
+    immutableProofSweepAssumeRetryableBefore?: string;
     /**
      * The type of attestation connector: entity-storage, iota.
      */
@@ -739,6 +768,14 @@ export interface IEngineEnvironmentVariables {
      * @default 30
      */
     dataspaceStalledTransferTimeout?: string;
+    /**
+     * How long in seconds a provider transfer may stay idle before the idle policy marks it as stalled.
+     */
+    dataspaceProviderTransferIdleTimeout?: string;
+    /**
+     * How frequently in seconds the provider idle transfer policy sweep runs.
+     */
+    dataspaceProviderTransferPolicySweepInterval?: string;
     /**
      * Path under which the dataspace control plane is mounted (path only, not full URL).
      * This must match the control-plane REST mount, as it is combined with the public
@@ -793,13 +830,9 @@ export interface IEngineEnvironmentVariables {
      */
     loggingMutexTimeout?: string;
     /**
-     * The mutex timeout in milliseconds for the memory entity storage connector.
-     */
-    entityStorageMemoryMutexTimeout?: string;
-    /**
-     * The mutex timeout in milliseconds for the file entity storage connector.
+     * The mutex timeout in milliseconds for the memory and file entity storage connectors.
      */
-    entityStorageFileMutexTimeout?: string;
+    entityStorageMutexTimeout?: string;
     /**
      * The mutex timeout in milliseconds for the rights management component.
      */

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.9.2-next.7](https://github.com/iotaledger/twin-node/compare/node-core-v0.9.2-next.6...node-core-v0.9.2-next.7) (2026-08-10)
+
+
+### Features
+
+* additional env vars and validation ([#324](https://github.com/iotaledger/twin-node/issues/324)) ([6b01e8c](https://github.com/iotaledger/twin-node/commit/6b01e8c10f9aa7181f51f13534d8164db3e7322d))
+
 ## [0.9.2-next.6](https://github.com/iotaledger/twin-node/compare/node-core-v0.9.2-next.5...node-core-v0.9.2-next.6) (2026-08-07)
 
 

package/docs/reference/interfaces/IEngineEnvironmentVariables.md

@@ -268,7 +268,7 @@ MySQL host.
 
 ### mySqlPort? {#mysqlport}
 
-> `optional` **mySqlPort?**: `number`
+> `optional` **mySqlPort?**: `string`
 
 MySQL port.
 
@@ -308,7 +308,7 @@ MongoDB host.
 
 ### mongoDbPort? {#mongodbport}
 
-> `optional` **mongoDbPort?**: `number`
+> `optional` **mongoDbPort?**: `string`
 
 MongoDB port.
 
@@ -348,7 +348,7 @@ PostgreSQl host.
 
 ### postgreSqlPort? {#postgresqlport}
 
-> `optional` **postgreSqlPort?**: `number`
+> `optional` **postgreSqlPort?**: `string`
 
 PostgreSQl port.
 
@@ -1129,7 +1129,7 @@ The identity verification method id to use with immutable proofs.
 
 ### immutableProofTaskRetryCount? {#immutableprooftaskretrycount}
 
-> `optional` **immutableProofTaskRetryCount?**: `number`
+> `optional` **immutableProofTaskRetryCount?**: `string`
 
 The number of times to retry a proof task when it fails, 0 to disable retries.
 
@@ -1143,7 +1143,7 @@ The number of times to retry a proof task when it fails, 0 to disable retries.
 
 ### immutableProofTaskRetryInterval? {#immutableprooftaskretryinterval}
 
-> `optional` **immutableProofTaskRetryInterval?**: `number`
+> `optional` **immutableProofTaskRetryInterval?**: `string`
 
 The interval in seconds to wait between proof task retries.
 
@@ -1157,7 +1157,7 @@ The interval in seconds to wait between proof task retries.
 
 ### immutableProofTaskFailureRetainFor? {#immutableprooftaskfailureretainfor}
 
-> `optional` **immutableProofTaskFailureRetainFor?**: `number`
+> `optional` **immutableProofTaskFailureRetainFor?**: `string`
 
 The time in minutes to retain the record of a failed proof task.
 Set to -1 to retain failures forever.
@@ -1170,6 +1170,84 @@ Set to -1 to retain failures forever.
 
 ***
 
+### immutableProofSweepInterval? {#immutableproofsweepinterval}
+
+> `optional` **immutableProofSweepInterval?**: `string`
+
+How often in minutes the immutable proof reconciliation sweep runs.
+
+#### Default
+
+```ts
+30
+```
+
+***
+
+### immutableProofSweepStaleThreshold? {#immutableproofsweepstalethreshold}
+
+> `optional` **immutableProofSweepStaleThreshold?**: `string`
+
+The minimum age in minutes before a proof with no notarization is considered stuck.
+
+#### Default
+
+```ts
+180
+```
+
+***
+
+### immutableProofSweepMaxAttempts? {#immutableproofsweepmaxattempts}
+
+> `optional` **immutableProofSweepMaxAttempts?**: `string`
+
+The number of sweep attempts made before a proof is parked.
+
+#### Default
+
+```ts
+5
+```
+
+***
+
+### immutableProofSweepBatchLimit? {#immutableproofsweepbatchlimit}
+
+> `optional` **immutableProofSweepBatchLimit?**: `string`
+
+The maximum number of proofs to re-enqueue per tenant per sweep cycle.
+
+#### Default
+
+```ts
+10
+```
+
+***
+
+### immutableProofSweepBackoff? {#immutableproofsweepbackoff}
+
+> `optional` **immutableProofSweepBackoff?**: `string`
+
+The minimum time in minutes between sweep attempts for the same proof.
+
+#### Default
+
+```ts
+60
+```
+
+***
+
+### immutableProofSweepAssumeRetryableBefore? {#immutableproofsweepassumeretryablebefore}
+
+> `optional` **immutableProofSweepAssumeRetryableBefore?**: `string`
+
+ISO 8601 date-time used to treat older missing-task proofs as retryable.
+
+***
+
 ### attestationConnector? {#attestationconnector}
 
 > `optional` **attestationConnector?**: `string`
@@ -1494,6 +1572,22 @@ progressing it before it is treated as timed out.
 
 ***
 
+### dataspaceProviderTransferIdleTimeout? {#dataspaceprovidertransferidletimeout}
+
+> `optional` **dataspaceProviderTransferIdleTimeout?**: `string`
+
+How long in seconds a provider transfer may stay idle before the idle policy marks it as stalled.
+
+***
+
+### dataspaceProviderTransferPolicySweepInterval? {#dataspaceprovidertransferpolicysweepinterval}
+
+> `optional` **dataspaceProviderTransferPolicySweepInterval?**: `string`
+
+How frequently in seconds the provider idle transfer policy sweep runs.
+
+***
+
 ### dataspaceCallbackPath? {#dataspacecallbackpath}
 
 > `optional` **dataspaceCallbackPath?**: `string`
@@ -1600,19 +1694,11 @@ The mutex timeout in milliseconds for the logging component.
 
 ***
 
-### entityStorageMemoryMutexTimeout? {#entitystoragememorymutextimeout}
-
-> `optional` **entityStorageMemoryMutexTimeout?**: `string`
-
-The mutex timeout in milliseconds for the memory entity storage connector.
-
-***
-
-### entityStorageFileMutexTimeout? {#entitystoragefilemutextimeout}
+### entityStorageMutexTimeout? {#entitystoragemutextimeout}
 
-> `optional` **entityStorageFileMutexTimeout?**: `string`
+> `optional` **entityStorageMutexTimeout?**: `string`
 
-The mutex timeout in milliseconds for the file entity storage connector.
+The mutex timeout in milliseconds for the memory and file entity storage connectors.
 
 ***
 

package/locales/en.json

@@ -14,6 +14,7 @@
 			"cliCommandParamMissing": "Parameter \"{param}\" is required for command \"{command}\"",
 			"cliCommandParamExtra": "Parameter(s) \"{params}\" are not recognised for command \"{command}\"",
 			"cliEnvVarMissing": "Environment variable \"{envVar}\" does not exist",
+			"invalidEnvVarValue": "Environment variable \"{key}\" has an invalid value \"{value}\", expected {type} type",
 			"unknownEnvVars": "Unknown environment variable properties [{keys}]. Check for typos in variable names, for custom variables use the {prefix}ENV_ALLOW_LIST."
 		},
 		"bootstrapDev": {

package/package.json

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