@twin.org/core 0.9.1 → 0.9.2-next.10

package/docs/reference/classes/LruCache.md

@@ -0,0 +1,262 @@
+# Class: LruCache\<T\>
+
+A fixed-capacity LRU cache with time-to-idle eviction.
+
+Entries are removed in two ways:
+- Capacity eviction: when the cache is full the least-recently-used entry is removed first.
+- TTI eviction: a background timer sweeps idle entries every ttiMs milliseconds.
+The timer only runs while there are entries; it stops automatically when the cache empties.
+
+`get` and `set` both update an entry's LRU position and reset its idle timer.
+`has` is a pure peek it evicts idle entries but does not refresh a live entry's TTI.
+Call `destroy` when the cache is no longer needed to stop the background timer.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+## Constructors
+
+### Constructor
+
+> **new LruCache**\<`T`\>(`options?`): `LruCache`\<`T`\>
+
+Create a new instance of LruCache.
+
+#### Parameters
+
+##### options?
+
+The cache options.
+
+###### capacity?
+
+`number`
+
+Maximum number of entries. Defaults to 1000. Must be a positive integer.
+
+###### ttiMs?
+
+`number`
+
+Time-to-idle in milliseconds. Defaults to 10000. Must be a positive integer.
+
+###### mutexTimeoutMs?
+
+`number`
+
+Maximum time in milliseconds to wait for getOrSet mutex acquisition.
+
+#### Returns
+
+`LruCache`\<`T`\>
+
+#### Throws
+
+ValidationError if capacity or ttiMs is not a positive integer.
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### DEFAULT\_CAPACITY {#default_capacity}
+
+> `readonly` `static` **DEFAULT\_CAPACITY**: `1000` = `1000`
+
+Default capacity.
+
+***
+
+### DEFAULT\_TTI\_MS {#default_tti_ms}
+
+> `readonly` `static` **DEFAULT\_TTI\_MS**: `10000` = `10000`
+
+Default time-to-idle in milliseconds.
+
+## Methods
+
+### count() {#count}
+
+> **count**(): `number`
+
+The number of entries currently held in the cache.
+
+#### Returns
+
+`number`
+
+The number of entries in the cache.
+
+***
+
+### get() {#get}
+
+> **get**(`key`): `T` \| `undefined`
+
+Get a value from the cache.
+Returns undefined if the key is absent or the entry has idled out.
+A successful hit resets the entry's idle timer and moves it to most-recently-used.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key to retrieve.
+
+#### Returns
+
+`T` \| `undefined`
+
+The cached value, or undefined on a miss or idle eviction.
+
+***
+
+### set() {#set}
+
+> **set**(`key`, `value`): `void`
+
+Store a value in the cache.
+If the key already exists its value and idle timer are refreshed.
+When the cache is at capacity, idle entries are swept first; if it is still full the
+least-recently-used entry is evicted.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key to store.
+
+##### value
+
+`T`
+
+The value to cache.
+
+#### Returns
+
+`void`
+
+***
+
+### getOrSet() {#getorset}
+
+> **getOrSet**(`key`, `valueFactory`): `Promise`\<`T`\>
+
+Atomically get an existing value or create and store it once using an async factory.
+Concurrent calls for the same key are serialized via a mutex.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key to get or create.
+
+##### valueFactory
+
+() => `Promise`\<`T`\>
+
+Async callback used to build a value when the key is absent.
+
+#### Returns
+
+`Promise`\<`T`\>
+
+The existing or newly created value.
+
+***
+
+### has() {#has}
+
+> **has**(`key`): `boolean`
+
+Check whether a key exists in the cache and has not idled out.
+Idle entries are evicted on peek, but a live entry's TTI is not reset.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key to test.
+
+#### Returns
+
+`boolean`
+
+True if the key is present and not idle.
+
+***
+
+### keys() {#keys}
+
+> **keys**(): `string`[]
+
+Return all keys for entries that have not idled out.
+Idle entries encountered during iteration are evicted.
+
+#### Returns
+
+`string`[]
+
+An array of live keys in least-recently-used to most-recently-used order.
+
+***
+
+### delete() {#delete}
+
+> **delete**(`key`): `void`
+
+Remove an entry from the cache.
+Cancels the background timer if the cache becomes empty.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key to remove.
+
+#### Returns
+
+`void`
+
+***
+
+### clear() {#clear}
+
+> **clear**(): `void`
+
+Remove all entries from the cache and cancel the background timer.
+
+#### Returns
+
+`void`
+
+***
+
+### destroy() {#destroy}
+
+> **destroy**(): `void`
+
+Stop the background idle-sweep timer and release all entries.
+The cache must not be used after this call.
+
+#### Returns
+
+`void`

package/docs/reference/classes/ObjectHelper.md

@@ -196,7 +196,7 @@ True is the objects are equal.
 
 ### propertyGet() {#propertyget}
 
-> `static` **propertyGet**\<`T`\>(`obj`, `property`): `T` \| `undefined`
+> `static` **propertyGet**\<`T`\>(`object`, `property`): `T` \| `undefined`
 
 Get the property of an unknown object.
 
@@ -208,7 +208,7 @@ Get the property of an unknown object.
 
 #### Parameters
 
-##### obj
+##### object
 
 `unknown`
 
@@ -230,13 +230,13 @@ The property.
 
 ### propertySet() {#propertyset}
 
-> `static` **propertySet**(`obj`, `property`, `value`): `void`
+> `static` **propertySet**(`object`, `property`, `value`): `void`
 
 Set the property of an unknown object.
 
 #### Parameters
 
-##### obj
+##### object
 
 `unknown`
 
@@ -266,13 +266,13 @@ GeneralError if the property target is not an object.
 
 ### propertyDelete() {#propertydelete}
 
-> `static` **propertyDelete**(`obj`, `property`): `void`
+> `static` **propertyDelete**(`object`, `property`): `void`
 
 Delete the property of an unknown object.
 
 #### Parameters
 
-##### obj
+##### object
 
 `unknown`
 

package/docs/reference/index.md

@@ -40,6 +40,8 @@
 - [Guards](classes/Guards.md)
 - [I18n](classes/I18n.md)
 - [Is](classes/Is.md)
+- [LfuCache](classes/LfuCache.md)
+- [LruCache](classes/LruCache.md)
 - [Mutex](classes/Mutex.md)
 - [SharedObjectBuffer](classes/SharedObjectBuffer.md)
 - [SharedStore](classes/SharedStore.md)
@@ -50,7 +52,6 @@
 - [IComponent](interfaces/IComponent.md)
 - [IDuration](interfaces/IDuration.md)
 - [IError](interfaces/IError.md)
-- [IHealth](interfaces/IHealth.md)
 - [II18nShared](interfaces/II18nShared.md)
 - [IKeyValue](interfaces/IKeyValue.md)
 - [ILabelledValue](interfaces/ILabelledValue.md)
@@ -68,7 +69,6 @@
 
 - [CoerceType](type-aliases/CoerceType.md)
 - [CompressionType](type-aliases/CompressionType.md)
-- [HealthStatus](type-aliases/HealthStatus.md)
 - [MutexMessageTypes](type-aliases/MutexMessageTypes.md)
 - [SharedObjectBufferMessageTypes](type-aliases/SharedObjectBufferMessageTypes.md)
 - [ObjectOrArray](type-aliases/ObjectOrArray.md)
@@ -80,7 +80,6 @@
 - [ComponentFactory](variables/ComponentFactory.md)
 - [CoerceType](variables/CoerceType.md)
 - [CompressionType](variables/CompressionType.md)
-- [HealthStatus](variables/HealthStatus.md)
 - [MutexMessageTypes](variables/MutexMessageTypes.md)
 - [SharedObjectBufferMessageTypes](variables/SharedObjectBufferMessageTypes.md)
 - [DURATION\_REG\_EXP](variables/DURATION_REG_EXP.md)

package/docs/reference/interfaces/IComponent.md

@@ -103,17 +103,3 @@ The node logging component type.
 `Promise`\<`void`\>
 
 A promise that resolves when the component has stopped.
-
-***
-
-### health()? {#health}
-
-> `optional` **health**(): `Promise`\<[`IHealth`](IHealth.md)[]\>
-
-Returns the health status of the component.
-
-#### Returns
-
-`Promise`\<[`IHealth`](IHealth.md)[]\>
-
-The health status of the component, can return multiple entries for elements within the component.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/core",
-	"version": "0.9.1",
+	"version": "0.9.2-next.10",
 	"description": "Helper methods/classes for data type checking/validation/guarding/error handling",
 	"repository": {
 		"type": "git",
@@ -14,9 +14,9 @@
 		"node": ">=24.0.0"
 	},
 	"dependencies": {
-		"@twin.org/nameof": "^0.9.1",
-		"intl-messageformat": "11.2.12",
-		"rfc6902": "5.2.0"
+		"@twin.org/nameof": "0.9.2-next.10",
+		"intl-messageformat": "11.2.13",
+		"rfc6902": "5.3.0"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",

package/dist/es/models/IHealth.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=IHealth.js.map

package/dist/es/models/IHealth.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IHealth.js","sourceRoot":"","sources":["../../../src/models/IHealth.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { HealthStatus } from \"./healthStatus.js\";\n\n/**\n * Provides health information for a component.\n */\nexport interface IHealth {\n\t/**\n\t * The source of the health information.\n\t */\n\tsource: string;\n\n\t/**\n\t * The description of the component as an i18n key.\n\t */\n\tdescription?: string;\n\n\t/**\n\t * The overall status of the component, the entries can also report their own health.\n\t */\n\tstatus: HealthStatus;\n\n\t/**\n\t * The message for the status if there are further details to provide as an i18n key.\n\t */\n\tmessage?: string;\n\n\t/**\n\t * Data to substitute in the i18n key for the message.\n\t */\n\tdata?: { [id: string]: unknown };\n\n\t/**\n\t * The grouped child components, if any.\n\t */\n\tgrouped?: IHealth[];\n}\n"]}

package/dist/es/models/healthStatus.js

@@ -1,21 +0,0 @@
-// Copyright 2024 IOTA Stiftung.
-// SPDX-License-Identifier: Apache-2.0.
-/**
- * The health status of the component.
- */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const HealthStatus = {
-    /**
-     * OK.
-     */
-    Ok: "ok",
-    /**
-     * Warning.
-     */
-    Warning: "warning",
-    /**
-     * Error.
-     */
-    Error: "error"
-};
-//# sourceMappingURL=healthStatus.js.map

package/dist/es/models/healthStatus.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"healthStatus.js","sourceRoot":"","sources":["../../../src/models/healthStatus.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B;;OAEG;IACH,EAAE,EAAE,IAAI;IAER;;OAEG;IACH,OAAO,EAAE,SAAS;IAElB;;OAEG;IACH,KAAK,EAAE,OAAO;CACL,CAAC","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The health status of the component.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const HealthStatus = {\n\t/**\n\t * OK.\n\t */\n\tOk: \"ok\",\n\n\t/**\n\t * Warning.\n\t */\n\tWarning: \"warning\",\n\n\t/**\n\t * Error.\n\t */\n\tError: \"error\"\n} as const;\n\n/**\n * The health status of the component.\n */\nexport type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];\n"]}

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

@@ -1,32 +0,0 @@
-import type { HealthStatus } from "./healthStatus.js";
-/**
- * Provides health information for a component.
- */
-export interface IHealth {
-    /**
-     * The source of the health information.
-     */
-    source: string;
-    /**
-     * The description of the component as an i18n key.
-     */
-    description?: string;
-    /**
-     * The overall status of the component, the entries can also report their own health.
-     */
-    status: HealthStatus;
-    /**
-     * The message for the status if there are further details to provide as an i18n key.
-     */
-    message?: string;
-    /**
-     * Data to substitute in the i18n key for the message.
-     */
-    data?: {
-        [id: string]: unknown;
-    };
-    /**
-     * The grouped child components, if any.
-     */
-    grouped?: IHealth[];
-}

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

@@ -1,21 +0,0 @@
-/**
- * The health status of the component.
- */
-export declare const HealthStatus: {
-    /**
-     * OK.
-     */
-    readonly Ok: "ok";
-    /**
-     * Warning.
-     */
-    readonly Warning: "warning";
-    /**
-     * Error.
-     */
-    readonly Error: "error";
-};
-/**
- * The health status of the component.
- */
-export type HealthStatus = (typeof HealthStatus)[keyof typeof HealthStatus];

package/docs/reference/interfaces/IHealth.md

@@ -1,55 +0,0 @@
-# Interface: IHealth
-
-Provides health information for a component.
-
-## Properties
-
-### source {#source}
-
-> **source**: `string`
-
-The source of the health information.
-
-***
-
-### description? {#description}
-
-> `optional` **description?**: `string`
-
-The description of the component as an i18n key.
-
-***
-
-### status {#status}
-
-> **status**: [`HealthStatus`](../type-aliases/HealthStatus.md)
-
-The overall status of the component, the entries can also report their own health.
-
-***
-
-### message? {#message}
-
-> `optional` **message?**: `string`
-
-The message for the status if there are further details to provide as an i18n key.
-
-***
-
-### data? {#data}
-
-> `optional` **data?**: `object`
-
-Data to substitute in the i18n key for the message.
-
-#### Index Signature
-
-\[`id`: `string`\]: `unknown`
-
-***
-
-### grouped? {#grouped}
-
-> `optional` **grouped?**: `IHealth`[]
-
-The grouped child components, if any.

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

@@ -1,5 +0,0 @@
-# Type Alias: HealthStatus
-
-> **HealthStatus** = *typeof* [`HealthStatus`](../variables/HealthStatus.md)\[keyof *typeof* [`HealthStatus`](../variables/HealthStatus.md)\]
-
-The health status of the component.

package/docs/reference/variables/HealthStatus.md

@@ -1,25 +0,0 @@
-# Variable: HealthStatus
-
-> `const` **HealthStatus**: `object`
-
-The health status of the component.
-
-## Type Declaration
-
-### Ok {#ok}
-
-> `readonly` **Ok**: `"ok"` = `"ok"`
-
-OK.
-
-### Warning {#warning}
-
-> `readonly` **Warning**: `"warning"` = `"warning"`
-
-Warning.
-
-### Error {#error}
-
-> `readonly` **Error**: `"error"` = `"error"`
-
-Error.