@twin.org/core 0.9.3-next.2 → 0.9.3-next.4

package/docs/examples.md

@@ -171,12 +171,49 @@ class SimpleHasher implements IHasher {
   }
 }
 
-const factory = new Factory<IHasher>('hashers');
+const factory = Factory.createFactory<IHasher>('hashers');
 factory.register('simple', () => new SimpleHasher());
 
 factory.create('simple').hash('abc'); // 'abc-hash'
 ```
 
+## Factory Facades
+
+A facade wraps the components a factory produces, so a cross cutting concern can be applied without modifying them.
+
+```typescript
+import { ComponentFactory, FacadeFactory, Is, type IFacade } from '@twin.org/core';
+
+class LoggingFacade implements IFacade {
+  public wrap(target: unknown): unknown {
+    return new Proxy(target as object, {
+      get(t, prop, receiver): unknown {
+        const value = Reflect.get(t, prop, receiver);
+
+        if (!Is.function(value)) {
+          return value;
+        }
+
+        return (...args: unknown[]): unknown => {
+          globalThis.console.log('calling', String(prop));
+          return value.apply(t, args);
+        };
+      }
+    });
+  }
+}
+
+FacadeFactory.register('logging', () => new LoggingFacade());
+
+// Every component the factory produces from here on is wrapped.
+ComponentFactory.useFacade('logging');
+
+// No longer wrapped, for instances produced after this call.
+ComponentFactory.unuseFacade('logging');
+```
+
+An instance is passed through the facades in the order they were activated, so the first activated is the outermost.
+
 ## Encoding and Compression
 
 ```typescript

package/docs/reference/classes/Factory.md

@@ -366,12 +366,75 @@ Remove all the instances and the generators.
 
 ***
 
+### useFacade() {#usefacade}
+
+> **useFacade**(`name`): `void`
+
+Activate a facade for this factory, so every instance it produces is wrapped by it.
+An instance is passed through the facades in the order they were activated, so the facade
+activated first is the outermost. Activating a facade which is already active does nothing.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the facade, as registered with the facade factory.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+GuardError if the parameters are invalid.
+
+#### Throws
+
+GeneralError if no facade is registered with the name, or the factory is the facade
+factory itself.
+
+***
+
+### unuseFacade() {#unusefacade}
+
+> **unuseFacade**(`name`): `void`
+
+Deactivate a facade for this factory. Deactivating a facade which is not active does nothing.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the facade to deactivate.
+
+#### Returns
+
+`void`
+
+#### Throws
+
+GuardError if the parameters are invalid.
+
+***
+
 ### instancesMap() {#instancesmap}
 
-> **instancesMap**(): `object`
+> **instancesMap**(`withFacade?`): `object`
 
 Get all the instances as a map.
 
+#### Parameters
+
+##### withFacade?
+
+`boolean`
+
+Return the instances with the active facades applied, defaults to false.
+
 #### Returns
 
 `object`
@@ -382,10 +445,18 @@ The instances as a map.
 
 ### instancesList() {#instanceslist}
 
-> **instancesList**(): `T`[]
+> **instancesList**(`withFacade?`): `T`[]
 
 Get all the instances as a list in the order they were registered.
 
+#### Parameters
+
+##### withFacade?
+
+`boolean`
+
+Return the instances with the active facades applied, defaults to false.
+
 #### Returns
 
 `T`[]

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/index.md

@@ -52,6 +52,7 @@
 - [IComponent](interfaces/IComponent.md)
 - [IDuration](interfaces/IDuration.md)
 - [IError](interfaces/IError.md)
+- [IFacade](interfaces/IFacade.md)
 - [II18nShared](interfaces/II18nShared.md)
 - [IKeyValue](interfaces/IKeyValue.md)
 - [ILabelledValue](interfaces/ILabelledValue.md)
@@ -78,6 +79,7 @@
 ## Variables
 
 - [ComponentFactory](variables/ComponentFactory.md)
+- [FacadeFactory](variables/FacadeFactory.md)
 - [CoerceType](variables/CoerceType.md)
 - [CompressionType](variables/CompressionType.md)
 - [MutexMessageTypes](variables/MutexMessageTypes.md)

package/docs/reference/interfaces/IFacade.md

@@ -0,0 +1,32 @@
+# Interface: IFacade\<T\>
+
+A facade wraps a component so a cross cutting concern can be applied to it without the
+component being modified. The wrapped component is returned in place of the original.
+
+## Type Parameters
+
+### T
+
+`T` = `unknown`
+
+## Methods
+
+### wrap() {#wrap}
+
+> **wrap**(`target`): `T`
+
+Wrap the target, returning a replacement.
+
+#### Parameters
+
+##### target
+
+`T`
+
+The component to wrap.
+
+#### Returns
+
+`T`
+
+The wrapped component.

package/docs/reference/variables/FacadeFactory.md

@@ -0,0 +1,5 @@
+# Variable: FacadeFactory
+
+> `const` **FacadeFactory**: [`Factory`](../classes/Factory.md)\<[`IFacade`](../interfaces/IFacade.md)\<`unknown`\>\>
+
+Factory for creating implementation of facade types.

package/locales/en.json

@@ -91,7 +91,10 @@
 		"factory": {
 			"noUnregister": "There is no {typeName} registered with the name \"{name}\"",
 			"noGet": "The requested {typeName} \"{name}\" does not exist in the factory",
-			"noCreate": "The requested {typeName} \"{name}\" cannot be created by the factory, with params \"{params}\""
+			"noCreate": "The requested {typeName} \"{name}\" cannot be created by the factory, with params \"{params}\"",
+			"noFacade": "The requested facade \"{name}\" is not registered, so it cannot be applied to the {typeName} factory",
+			"noFacadeOnFacades": "Facades cannot be applied to the facade factory itself",
+			"noFacadeWrap": "The facade \"{name}\" did not return a wrapped instance for the {typeName} factory"
 		},
 		"bitString": {
 			"outOfRange": "The index should be >= 0 and less than the length of the bit string, the index is \"{index}\" and the number of bit is \"{numberBits}\""

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/core",
-	"version": "0.9.3-next.2",
+	"version": "0.9.3-next.4",
 	"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.2",
+		"@twin.org/nameof": "0.9.3-next.4",
 		"intl-messageformat": "11.2.13",
 		"rfc6902": "5.3.0"
 	},