@twin.org/core 0.9.2-next.9 → 0.9.3-next.1

package/docs/changelog.md

@@ -1,5 +1,153 @@
 # Changelog
 
+## [0.9.3-next.1](https://github.com/iotaledger/twin-framework/compare/core-v0.9.3-next.0...core-v0.9.3-next.1) (2026-08-26)
+
+
+### Features
+
+* add context id features ([#206](https://github.com/iotaledger/twin-framework/issues/206)) ([ef0d4ee](https://github.com/iotaledger/twin-framework/commit/ef0d4ee11a4f5fc6cc6f52a4958ce905c04ee13b))
+* add duration support ([#362](https://github.com/iotaledger/twin-framework/issues/362)) ([24dbe8b](https://github.com/iotaledger/twin-framework/commit/24dbe8b208eb127a52024cb219d31d27731e9ae3))
+* add factory.createIfExists ([aad5a53](https://github.com/iotaledger/twin-framework/commit/aad5a53cef1b1c2e04344ea46244d41e371dff9b))
+* add Factory.getFactory ([ad6cd2d](https://github.com/iotaledger/twin-framework/commit/ad6cd2d30351c145c70212f8cce1b66d5e8a5235))
+* add guard.dateString ([#335](https://github.com/iotaledger/twin-framework/issues/335)) ([a26a166](https://github.com/iotaledger/twin-framework/commit/a26a166eb1f62ece05b2432730cb7354feacecfc))
+* add health method to components ([a88016d](https://github.com/iotaledger/twin-framework/commit/a88016d90d172413e5bc5238dc1b3e35f82fcc2c))
+* add isDefault option to factory registration ([a8a700b](https://github.com/iotaledger/twin-framework/commit/a8a700bb8ddaf7dd5097869a358b8fc5f7c40ce7))
+* add lru and lft cache ([#449](https://github.com/iotaledger/twin-framework/issues/449)) ([67d741e](https://github.com/iotaledger/twin-framework/commit/67d741eab3b89556e3c55053b5a473a4c1592fed))
+* add mutex ([#316](https://github.com/iotaledger/twin-framework/issues/316)) ([1027e5a](https://github.com/iotaledger/twin-framework/commit/1027e5ac77aa9804178b4253abdeefd6f1c3d521))
+* add objectHelper.split ([386830a](https://github.com/iotaledger/twin-framework/commit/386830a77f8e842a5b119be0983708e042c3b14b))
+* add partial second support ([39bf087](https://github.com/iotaledger/twin-framework/commit/39bf087ddc113a9bf73e0d0e99f738f6f60c2f2d))
+* add single occurrence array type ([e890e43](https://github.com/iotaledger/twin-framework/commit/e890e4399e75ae5097f3ad8b1007321cbb1ed4ac))
+* add single occurrence array type ([#245](https://github.com/iotaledger/twin-framework/issues/245)) ([771dc78](https://github.com/iotaledger/twin-framework/commit/771dc78025b5546c9c9681be9494a76ab71171c6))
+* add support for health i18n validation ([7a286dd](https://github.com/iotaledger/twin-framework/commit/7a286ddb0c1bfa498bf3a77126cd589042bad6de))
+* add teardown to IComponent interface ([32c173c](https://github.com/iotaledger/twin-framework/commit/32c173cda115c20d3b4cee14b8a29cdc08e91555))
+* add teardown to IComponent interface ([98ce864](https://github.com/iotaledger/twin-framework/commit/98ce8648e709310c4435de334825b381fb4e32cb))
+* add typeName method to factory ([699fcbd](https://github.com/iotaledger/twin-framework/commit/699fcbd1168228401ddb81fdacb959b8cdc4206a))
+* add uuidv7 support ([#219](https://github.com/iotaledger/twin-framework/issues/219)) ([916c657](https://github.com/iotaledger/twin-framework/commit/916c657d270ce99fafe554233739fdd9ca28635b))
+* add wildcard support to the envhelper ([c064d46](https://github.com/iotaledger/twin-framework/commit/c064d46d36bbee8022a741b985d2b64c8f9572e4))
+* adding link header helper ([#225](https://github.com/iotaledger/twin-framework/issues/225)) ([703c072](https://github.com/iotaledger/twin-framework/commit/703c0725aceac6b6ec0c4fa729ef832d12fb3fd7))
+* additional nameof operators ([a5aab60](https://github.com/iotaledger/twin-framework/commit/a5aab60bf66a86f1b7ff8af7c4f044cb03706d50))
+* bump version ([c5354fa](https://github.com/iotaledger/twin-framework/commit/c5354fa906f4493c70f2642a9175a66780a10636))
+* coerce array ([#452](https://github.com/iotaledger/twin-framework/issues/452)) ([2019567](https://github.com/iotaledger/twin-framework/commit/20195673a65fe7179272ac84f37dc927218c128a))
+* concurrency in SharedStore ([#388](https://github.com/iotaledger/twin-framework/issues/388)) ([0610198](https://github.com/iotaledger/twin-framework/commit/0610198ba482273c3f6ba918e34f5875a3659571))
+* configurable timeout for mutex ([2087e04](https://github.com/iotaledger/twin-framework/commit/2087e04464a110a3f009fbc8b066696ed6784fc2))
+* env helper conversion methods ([e8c607e](https://github.com/iotaledger/twin-framework/commit/e8c607e59f6f79d4b1d562e9313babe348778835))
+* expand error params to accept properties ([032e9fd](https://github.com/iotaledger/twin-framework/commit/032e9fd1388e457cde32ca1005dfe014a5a9c077))
+* factory create and integrity ([#235](https://github.com/iotaledger/twin-framework/issues/235)) ([9f98b99](https://github.com/iotaledger/twin-framework/commit/9f98b99daf46eb365346fae49cc4ffba63e74cb3))
+* health status grouping ([5007c29](https://github.com/iotaledger/twin-framework/commit/5007c29fe4123fe56f754450b993dbe5dc32a057))
+* improve async cache edge cases ([4e57a6e](https://github.com/iotaledger/twin-framework/commit/4e57a6ec4113533b0ea903eae7d469200fa1348c))
+* improve error formatting ([#313](https://github.com/iotaledger/twin-framework/issues/313)) ([5a19623](https://github.com/iotaledger/twin-framework/commit/5a196231bcbf088bf9ba92a93b7478d3b8c5593f))
+* improve Is.function and ModuleHelper.getModuleMethod signatures ([ecf968b](https://github.com/iotaledger/twin-framework/commit/ecf968b02934b3676be4bf7cd2d1e7f8e7af6ce2))
+* improve Is.function definition to retain types ([f20b6b0](https://github.com/iotaledger/twin-framework/commit/f20b6b0dd16e74b75dc359be72b05989305c6410))
+* improve signatures ([45a7d58](https://github.com/iotaledger/twin-framework/commit/45a7d58baa5b6abc8c0735656f393d402fabb4ad))
+* improve signatures ([cdd24be](https://github.com/iotaledger/twin-framework/commit/cdd24be6fb898d33955b6f2f93c3ddbd73582269))
+* improve signatures ([2041ae2](https://github.com/iotaledger/twin-framework/commit/2041ae214cbd8d472d5e8be8d3403cd06a114040))
+* improve signatures ([d8a0ee1](https://github.com/iotaledger/twin-framework/commit/d8a0ee16542134a3f8b0653065239f42045125b4))
+* improve signatures ([1d084c5](https://github.com/iotaledger/twin-framework/commit/1d084c58c7eb41ae50b0ce80ce57e48a22dd3102))
+* improve signatures ([#287](https://github.com/iotaledger/twin-framework/issues/287)) ([c9f38f0](https://github.com/iotaledger/twin-framework/commit/c9f38f00e1cea8759e1105b41872a650c66c00f4))
+* improved coercion ([fcc7d98](https://github.com/iotaledger/twin-framework/commit/fcc7d9826f5405be5e3b5414ea53be42f974f9d5))
+* is and coerce accept duration object ([51dffa1](https://github.com/iotaledger/twin-framework/commit/51dffa18066eb86a14c700d90d3c1bd8b322c0fc))
+* linting and dependency update ([1c428ef](https://github.com/iotaledger/twin-framework/commit/1c428efe0391c52632962847d8dad68bd8e5dd00))
+* linting and dependency update ([676b4e9](https://github.com/iotaledger/twin-framework/commit/676b4e9d9bce158065200bbf875bb31da81d166d))
+* locales validation ([#197](https://github.com/iotaledger/twin-framework/issues/197)) ([55fdadb](https://github.com/iotaledger/twin-framework/commit/55fdadb13595ce0047f787bd1d4135d429a99f12))
+* move health support to api repo ([#435](https://github.com/iotaledger/twin-framework/issues/435)) ([867f766](https://github.com/iotaledger/twin-framework/commit/867f766afc86607bec6b5cf9c3ab5bd5c41d0b3c))
+* mutex safe usage in browser ([#339](https://github.com/iotaledger/twin-framework/issues/339)) ([02d409f](https://github.com/iotaledger/twin-framework/commit/02d409f211e91267964208d58a27f29791715086))
+* nodeIdentity optional in IComponent methods ([c78dc17](https://github.com/iotaledger/twin-framework/commit/c78dc17f4357d3e1ae40e415f468d3eae13e81f4))
+* optimistic locking version property for schemas ([#443](https://github.com/iotaledger/twin-framework/issues/443)) ([1b90987](https://github.com/iotaledger/twin-framework/commit/1b909875dc915a0ec133d8424d013ae7e4ddfb48))
+* shared object buffer ([#355](https://github.com/iotaledger/twin-framework/issues/355)) ([70d82ea](https://github.com/iotaledger/twin-framework/commit/70d82ea8f43f01aa840ae90ee0b1f23b064a07c6))
+* simplify factory options ([7f85a85](https://github.com/iotaledger/twin-framework/commit/7f85a8553dd3008364e8e1104f2e6f6b6595d77e))
+* simplify StringHelper signature ([0390403](https://github.com/iotaledger/twin-framework/commit/039040344952f91ee3c671249bc0e1c8f3b38e17))
+* typescript 6 update ([1d10f31](https://github.com/iotaledger/twin-framework/commit/1d10f31e6516ec622773f45e88af82fe749b384a))
+* update dependencies ([4da77ab](https://github.com/iotaledger/twin-framework/commit/4da77ab30f499e52825ac5a76f51436ceb59c26e))
+* urn and header helper extensions ([#395](https://github.com/iotaledger/twin-framework/issues/395)) ([5976756](https://github.com/iotaledger/twin-framework/commit/5976756886d22e5063671052abc4dfa04ce23a53))
+* urn random switched to using uuidv7 ([606c9a2](https://github.com/iotaledger/twin-framework/commit/606c9a2ed68a10fc7fc2bc5f93388c1b71033154))
+* urn random switched to using uuidv7 ([6a29f8b](https://github.com/iotaledger/twin-framework/commit/6a29f8bd573d06992b7eaa027b1daf4c2a2e1e85))
+
+
+### Bug Fixes
+
+* async thread lock ([97a96a5](https://github.com/iotaledger/twin-framework/commit/97a96a57f60c7b45a0ccbbfa1c43199b6e7512f9))
+* coerce and includes ([#429](https://github.com/iotaledger/twin-framework/issues/429)) ([98c9132](https://github.com/iotaledger/twin-framework/commit/98c9132316c0393ede9d6e634bbae9e5ece2d6b9))
+* ensure __decorate is defined for decorators ([103a563](https://github.com/iotaledger/twin-framework/commit/103a563ce01ebdef6240d2e590e7b026e8692684))
+* improve exception handling in asyncCache ([c81b29b](https://github.com/iotaledger/twin-framework/commit/c81b29b660b152d2f0757d323430287e6491bf59))
+* improve jsdoc comments ([f7c8e43](https://github.com/iotaledger/twin-framework/commit/f7c8e43fab9803dffa6461950d5b9979e25bcd24))
+* iso 8601 checks ([#409](https://github.com/iotaledger/twin-framework/issues/409)) ([4427101](https://github.com/iotaledger/twin-framework/commit/442710109b63ec67ca5ee7cb948df742500d0151))
+* large regex tests ([#463](https://github.com/iotaledger/twin-framework/issues/463)) ([f4a3a5c](https://github.com/iotaledger/twin-framework/commit/f4a3a5c95619abed1e16791e54e884d4ffc503a8))
+* linting ([b77511d](https://github.com/iotaledger/twin-framework/commit/b77511de8781707088b1beb4c92f12d7d6e0fd5f))
+* mutex locking ([d5af3c1](https://github.com/iotaledger/twin-framework/commit/d5af3c1e66070f86408ba1410809689c6d22958b))
+* number coercion wrongly accepts alpha ([c04c1af](https://github.com/iotaledger/twin-framework/commit/c04c1af24697b6c92a180a71c0722c5673313360))
+* number coercion wrongly accepts alpha ([dd5b193](https://github.com/iotaledger/twin-framework/commit/dd5b193c2501f6d30ca94aa0fc30a6edfe405e6f))
+* pick non iterable keys ([399399a](https://github.com/iotaledger/twin-framework/commit/399399abfb8947c4eb235df527532ffe186986b3))
+* prevent TOCTOU race in Mutex.getOrFetchLock for concurrent async callers ([#343](https://github.com/iotaledger/twin-framework/issues/343)) ([5238ad1](https://github.com/iotaledger/twin-framework/commit/5238ad1a68e24c69162204b02030c6686c15e9f4))
+* remove misleading undefined from AsyncCache return type ([05b3291](https://github.com/iotaledger/twin-framework/commit/05b32914e03a63c7daf7b77952a2ebedb7ca7f6b))
+* settle AsyncCache waiters correctly when a request resolves undefined or null ([#401](https://github.com/iotaledger/twin-framework/issues/401)) ([6ae3f8a](https://github.com/iotaledger/twin-framework/commit/6ae3f8aca688ca76d93ec3964178a3b1a8895453))
+* time coercion ([8ac43f8](https://github.com/iotaledger/twin-framework/commit/8ac43f85fbd521ff54786d92df3e432d7f738b0c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.3-next.0 to 0.9.3-next.1
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.3-next.0 to 0.9.3-next.1
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.3-next.0 to 0.9.3-next.1
+
+## [0.9.2](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2...core-v0.9.2) (2026-08-24)
+
+
+### Features
+
+* release to production ([b24cba1](https://github.com/iotaledger/twin-framework/commit/b24cba1b6a969278d638e632590602ec881e49fb))
+* release to production ([787287d](https://github.com/iotaledger/twin-framework/commit/787287d06ea8319657401589d61fff369310c422))
+* release to production ([53f4843](https://github.com/iotaledger/twin-framework/commit/53f484326b2851d7a506d2620db24c4a65cee7b3))
+* release to production ([56cda4d](https://github.com/iotaledger/twin-framework/commit/56cda4da93e978c5be19ec7cfd421ae2a7fe4147))
+* release to production ([f7c6586](https://github.com/iotaledger/twin-framework/commit/f7c6586f6976b903b647b4c5ac5ad9421e0c9051))
+* release to production ([829d53d](https://github.com/iotaledger/twin-framework/commit/829d53d3953b1e1b40b0243c04cfdfd3842aac7b))
+* release to production ([5cf3a76](https://github.com/iotaledger/twin-framework/commit/5cf3a76a09eff2e6414d0cba846c7c37400a11d6))
+* release to production ([#330](https://github.com/iotaledger/twin-framework/issues/330)) ([d73f565](https://github.com/iotaledger/twin-framework/commit/d73f565588d156d23ef49b2a5718973756f7a696))
+* release to production ([#382](https://github.com/iotaledger/twin-framework/issues/382)) ([bbed01a](https://github.com/iotaledger/twin-framework/commit/bbed01a605ee9724bda77a0f7feab249118c2d90))
+* release to production ([#417](https://github.com/iotaledger/twin-framework/issues/417)) ([59727e7](https://github.com/iotaledger/twin-framework/commit/59727e73903a137310ca48fe469189cf29879cb9))
+* release to production ([#459](https://github.com/iotaledger/twin-framework/issues/459)) ([e26e2d9](https://github.com/iotaledger/twin-framework/commit/e26e2d9a88767364c32494c45232033447b26e22))
+
+
+### Miscellaneous Chores
+
+* release to production ([63cae24](https://github.com/iotaledger/twin-framework/commit/63cae2401f6c11f93b2a01260b665064e8bd28e0))
+
+## [0.9.2-next.11](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.10...core-v0.9.2-next.11) (2026-08-20)
+
+
+### Features
+
+* coerce array ([#452](https://github.com/iotaledger/twin-framework/issues/452)) ([2019567](https://github.com/iotaledger/twin-framework/commit/20195673a65fe7179272ac84f37dc927218c128a))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.2-next.10 to 0.9.2-next.11
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.2-next.10 to 0.9.2-next.11
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.2-next.10 to 0.9.2-next.11
+
+## [0.9.2-next.10](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.9...core-v0.9.2-next.10) (2026-08-11)
+
+
+### Features
+
+* add lru and lft cache ([#449](https://github.com/iotaledger/twin-framework/issues/449)) ([67d741e](https://github.com/iotaledger/twin-framework/commit/67d741eab3b89556e3c55053b5a473a4c1592fed))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/nameof bumped from 0.9.2-next.9 to 0.9.2-next.10
+  * devDependencies
+    * @twin.org/nameof-transformer bumped from 0.9.2-next.9 to 0.9.2-next.10
+    * @twin.org/nameof-vitest-plugin bumped from 0.9.2-next.9 to 0.9.2-next.10
+
 ## [0.9.2-next.9](https://github.com/iotaledger/twin-framework/compare/core-v0.9.2-next.8...core-v0.9.2-next.9) (2026-08-10)
 
 

package/docs/reference/classes/Coerce.md

@@ -214,6 +214,34 @@ The duration object, or undefined if the value cannot be coerced.
 
 ***
 
+### array() {#array}
+
+> `static` **array**\<`T`\>(`value`): `T`[] \| `undefined`
+
+Coerce the value to an array.
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+The value to coerce.
+
+#### Returns
+
+`T`[] \| `undefined`
+
+The coerced array, or undefined if the value cannot be coerced.
+
+***
+
 ### object() {#object}
 
 > `static` **object**\<`T`\>(`value`): `T` \| `undefined`

package/docs/reference/classes/LfuCache.md

@@ -0,0 +1,265 @@
+# Class: LfuCache\<T\>
+
+A fixed-capacity LFU cache with time-to-idle eviction.
+
+Entries are removed in two ways:
+- Capacity eviction: when the cache is full the least-frequently-used entry is removed first.
+Ties in frequency are broken by recency the least-recently-used entry among those with the
+minimum frequency is evicted.
+- 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` increment an entry's access frequency and reset its idle timer.
+`has` and `keys` are pure peeks they evict idle entries but do not affect frequency or TTI.
+Call `destroy` when the cache is no longer needed to stop the background timer.
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Constructors
+
+### Constructor
+
+> **new LfuCache**\<`T`\>(`options?`): `LfuCache`\<`T`\>
+
+Create a new instance of LfuCache.
+
+#### 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
+
+`LfuCache`\<`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 increments the entry's frequency and resets its idle timer.
+
+#### 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 frequency are updated.
+When the cache is at capacity, idle entries are swept first; if it is still full the
+least-frequently-used entry is evicted (LRU among ties).
+
+#### 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 frequency and TTI are not updated.
+
+#### 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.
+Keys are returned in ascending frequency order; within the same frequency, LRU first.
+
+#### Returns
+
+`string`[]
+
+An array of live keys ordered from least-frequently-used to most-frequently-used.
+
+***
+
+### 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`