@twin.org/core 0.9.3-next.3 → 0.9.3-next.5

package/docs/reference/classes/LfuCache.md

@@ -10,6 +10,8 @@ minimum frequency is evicted.
 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.
+`set` and `getOrSet` accept an optional hard expiry timestamp; the entry is removed once that
+time is reached however recently it was used, and the TTI still applies alongside it.
 `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.
 
@@ -125,7 +127,7 @@ The cached value, or undefined on a miss or idle eviction.
 
 ### set() {#set}
 
-> **set**(`key`, `value`): `void`
+> **set**(`key`, `value`, `expires?`): `void`
 
 Store a value in the cache.
 If the key already exists its value and frequency are updated.
@@ -146,6 +148,13 @@ The key to store.
 
 The value to cache.
 
+##### expires?
+
+`number`
+
+Hard expiry timestamp in milliseconds since the epoch. The entry is removed
+once this time is reached regardless of how recently it was used. Must be an integer.
+
 #### Returns
 
 `void`
@@ -154,7 +163,7 @@ The value to cache.
 
 ### getOrSet() {#getorset}
 
-> **getOrSet**(`key`, `valueFactory`): `Promise`\<`T`\>
+> **getOrSet**(`key`, `valueFactory`, `expires?`): `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.
@@ -173,6 +182,13 @@ The key to get or create.
 
 Async callback used to build a value when the key is absent.
 
+##### expires?
+
+`number`
+
+Hard expiry timestamp in milliseconds since the epoch, applied to the entry
+when one is created. Must be an integer.
+
 #### Returns
 
 `Promise`\<`T`\>

package/docs/reference/classes/LruCache.md

@@ -8,6 +8,8 @@ Entries are removed in two ways:
 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.
+`set` and `getOrSet` accept an optional hard expiry timestamp; the entry is removed once that
+time is reached however recently it was used, and the TTI still applies alongside it.
 `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.
 
@@ -123,7 +125,7 @@ The cached value, or undefined on a miss or idle eviction.
 
 ### set() {#set}
 
-> **set**(`key`, `value`): `void`
+> **set**(`key`, `value`, `expires?`): `void`
 
 Store a value in the cache.
 If the key already exists its value and idle timer are refreshed.
@@ -144,6 +146,13 @@ The key to store.
 
 The value to cache.
 
+##### expires?
+
+`number`
+
+Hard expiry timestamp in milliseconds since the epoch. The entry is removed
+once this time is reached regardless of how recently it was used. Must be an integer.
+
 #### Returns
 
 `void`
@@ -152,7 +161,7 @@ The value to cache.
 
 ### getOrSet() {#getorset}
 
-> **getOrSet**(`key`, `valueFactory`): `Promise`\<`T`\>
+> **getOrSet**(`key`, `valueFactory`, `expires?`): `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.
@@ -171,6 +180,13 @@ The key to get or create.
 
 Async callback used to build a value when the key is absent.
 
+##### expires?
+
+`number`
+
+Hard expiry timestamp in milliseconds since the epoch, applied to the entry
+when one is created. Must be an integer.
+
 #### Returns
 
 `Promise`\<`T`\>

package/docs/reference/classes/Mutex.md

@@ -12,6 +12,13 @@ the shared buffer with the main thread on first use of each key, then caches it
 The main thread must call Mutex.handleWorkerMessage(msg) from its worker message handler
 before that worker first calls Mutex.lock().
 
+Callers on the same thread are served in the order they arrived. Each key has a FIFO
+queue of waiters, unlock() hands the lock directly to the waiter at the front, and a new
+caller only takes the lock outright when that queue is empty. Without this a caller that
+arrives while a waiter is being woken can take the lock first, which lets a busy key
+starve a waiter until its timeout elapses. Threads still contend with each other for the
+shared lock, so the ordering guarantee is per thread rather than global.
+
 The lock is not re-entrant: a thread that already holds a key and calls lock() again on
 the same key will block until the timeout elapses.
 
@@ -81,6 +88,8 @@ Acquires a lock for the given key without blocking the event loop. If the lock i
 held, it suspends the current async task until the lock is released or the timeout is reached.
 Use this in async single-threaded contexts (e.g. the main thread or a Fastify route handler)
 where calling the synchronous lock() would freeze the event loop and deadlock.
+Callers on the same thread are served in the order they arrived, so a contended key
+cannot starve an earlier caller.
 The lock is not re-entrant: if the same context holds the key and calls lockAsync() again on
 the same key, it will suspend until the timeout elapses.
 

package/docs/reference/index.md

@@ -59,6 +59,7 @@
 - [ILocale](interfaces/ILocale.md)
 - [ILocaleDictionary](interfaces/ILocaleDictionary.md)
 - [ILocalesIndex](interfaces/ILocalesIndex.md)
+- [IMutexWaiter](interfaces/IMutexWaiter.md)
 - [IMutexWorkerMessage](interfaces/IMutexWorkerMessage.md)
 - [IPatchOperation](interfaces/IPatchOperation.md)
 - [ISharedObjectBufferOptions](interfaces/ISharedObjectBufferOptions.md)

package/docs/reference/interfaces/IMutexWaiter.md

@@ -0,0 +1,37 @@
+# Interface: IMutexWaiter
+
+A caller queued on a mutex key, waiting to be handed the lock.
+
+## Properties
+
+### settled {#settled}
+
+> **settled**: `boolean`
+
+Has the waiter already been granted the lock or given up waiting.
+
+***
+
+### resolve? {#resolve}
+
+> `optional` **resolve?**: (`granted`) => `void`
+
+Resolves the queued caller, true when it now owns the lock.
+
+#### Parameters
+
+##### granted
+
+`boolean`
+
+#### Returns
+
+`void`
+
+***
+
+### timer? {#timer}
+
+> `optional` **timer?**: `Timeout`
+
+Timer which enforces the waiter's deadline.

package/locales/en.json

@@ -114,7 +114,7 @@
 		"mutex": {
 			"lockNotFound": "The key \"{key}\" has no active lock",
 			"lockAlreadyReleased": "The key \"{key}\" is not currently locked",
-			"lockTimeout": "Failed to acquire lock for key \"{key}\" within the timeout of {timeout} milliseconds",
+			"lockTimeout": "Failed to acquire lock for key \"{key}\" within the timeout of {timeoutMs} milliseconds",
 			"bufferFetchFailed": "Failed to retrieve shared buffer for key \"{key}\" from the main thread",
 			"invalidTimeout": "The timeout value \"{timeoutMs}\" is invalid, it must be a non-negative integer"
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/core",
-	"version": "0.9.3-next.3",
+	"version": "0.9.3-next.5",
 	"description": "Helper methods/classes for data type checking/validation/guarding/error handling",
 	"repository": {
 		"type": "git",
@@ -14,7 +14,7 @@
 		"node": ">=24.0.0"
 	},
 	"dependencies": {
-		"@twin.org/nameof": "0.9.3-next.3",
+		"@twin.org/nameof": "0.9.3-next.5",
 		"intl-messageformat": "11.2.13",
 		"rfc6902": "5.3.0"
 	},