fix(hf): add promise memo and unwrapGroup

Author: mathcovax

docs/en/v1/api/common/addWrappedProperties.md

@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "The addWrappedProperties() function dynamically adds derived properties to a wrapped value while keeping the original type and extending the new type."
 prev:
-  text: "unwrap"
-  link: "/en/v1/api/common/unwrap"
+  text: "unwrapGroup"
+  link: "/en/v1/api/common/unwrapGroup"
 next:
   text: "clone"
   link: "/en/v1/api/common/clone"

docs/en/v1/api/common/index.md

@@ -115,6 +115,9 @@ Async pause to wait for a certain time.
 ### [memo](/en/v1/api/common/memo)
 Evaluates a function only once and reuses the result (lazy memoization).
 
+### [memoPromise](/en/v1/api/common/memoPromise)
+Lazy memoization for functions returning a value or a promise.
+
 ### [toJSON](/en/v1/api/common/toJSON)
 Prepares a value for JSON serialization.
 
@@ -154,6 +157,9 @@ Ensures a value is wrapped (idempotent if already wrapped).
 ### [unwrap](/en/v1/api/common/unwrap)
 Retrieves the inner value of a wrapper.
 
+### [unwrapGroup](/en/v1/api/common/unwrapGroup)
+Unwraps every value of an object.
+
 ### [addWrappedProperties](/en/v1/api/common/addWrappedProperties)
 Dynamically adds derived properties to a wrapped value.
 

docs/en/v1/api/common/memo.md

@@ -5,13 +5,13 @@ prev:
   text: "sleep"
   link: "/en/v1/api/common/sleep"
 next:
-  text: "toJSON"
-  link: "/en/v1/api/common/toJSON"
+  text: "memoPromise"
+  link: "/en/v1/api/common/memoPromise"
 ---
 
 # memo
 
-The **`memo()`** function evaluates a function only once then memorizes the result. Subsequent calls return the same value without recalculation.
+The **`memo()`** function evaluates a function only once then memorizes the result. The first access to `value` triggers the evaluation, and subsequent accesses return the same value without recalculation.
 
 ## Interactive example
 
@@ -25,13 +25,13 @@ The **`memo()`** function evaluates a function only once then memorizes the resu
 
 ```typescript
 interface Memoized<
-	GenericInput extends unknown
+	GenericValue extends unknown
 > {
-	readonly input: GenericInput;
+	readonly value: GenericValue;
 }
 
 function memo<
-	GenericOutput extends AnyValue
+	GenericOutput extends unknown
 >(
 	theFunction: () => GenericOutput
 ): Memoized<GenericOutput>;
@@ -43,7 +43,7 @@ function memo<
 
 ## Return value
 
-A `Memoized` object with the `input` property containing the single result.
+A `Memoized` object with the `value` property containing the single result.
 
 ## See also
 

docs/en/v1/api/common/memoPromise.md

@@ -0,0 +1,52 @@
+---
+outline: [2, 3]
+description: "The memoPromise() function lazily evaluates a function that returns a value or a promise, then memoizes the resolved result."
+prev:
+  text: "memo"
+  link: "/en/v1/api/common/memo"
+next:
+  text: "toJSON"
+  link: "/en/v1/api/common/toJSON"
+---
+
+# memoPromise
+
+The **`memoPromise()`** function lazily evaluates a function that returns a value or a promise, then memoizes the resolved result.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/common/memoPromise/tryout.doc.ts"
+  majorVersion="v1"
+  height="292px"
+/>
+
+## Syntax
+
+```typescript
+interface MemoizedPromise<
+	GenericValue extends unknown
+> {
+	readonly value: MaybePromise<GenericValue>;
+}
+
+function memoPromise<
+	GenericOutput extends unknown
+>(
+	theFunction: () => MaybePromise<GenericOutput>
+): MemoizedPromise<GenericOutput>;
+```
+
+## Parameters
+
+- `theFunction` : Function evaluated once on first access, returning a value or a promise.
+
+## Return value
+
+A `MemoizedPromise` object with a lazy `value` getter. The first access returns a promise; once resolved, the property holds the resolved value.
+
+## See also
+
+- [`memo`](/en/v1/api/common/memo) - Lazy memoization for synchronous values
+- [`externalPromise`](/en/v1/api/common/externalPromise) - Controllable promise
+- [`promiseObject`](/en/v1/api/common/promiseObject) - Resolves objects of promises

docs/en/v1/api/common/toJSON.md

@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "The toJSON() function prepares a value for JSON serialization while respecting objects' toJSON methods, traversing arrays/tuples, and excluding functions."
 prev:
-  text: "memo"
-  link: "/en/v1/api/common/memo"
+  text: "memoPromise"
+  link: "/en/v1/api/common/memoPromise"
 next:
   text: "toTransform"
   link: "/en/v1/api/common/toTransform"

docs/en/v1/api/common/unwrap.md

@@ -5,8 +5,8 @@ prev:
   text: "toWrappedValue"
   link: "/en/v1/api/common/toWrappedValue"
 next:
-  text: "addWrappedProperties"
-  link: "/en/v1/api/common/addWrappedProperties"
+  text: "unwrapGroup"
+  link: "/en/v1/api/common/unwrapGroup"
 ---
 
 # unwrap

docs/en/v1/api/common/unwrapGroup.md

@@ -0,0 +1,45 @@
+---
+outline: [2, 3]
+description: "The unwrapGroup() function unwraps every value of an object using unwrap(), while keeping the same keys."
+prev:
+  text: "unwrap"
+  link: "/en/v1/api/common/unwrap"
+next:
+  text: "addWrappedProperties"
+  link: "/en/v1/api/common/addWrappedProperties"
+---
+
+# unwrapGroup
+
+The **`unwrapGroup()`** function unwraps every value of an object using `unwrap()`, while keeping the same keys.
+
+## Interactive example
+
+<MonacoTSEditor
+  src="/examples/v1/api/common/unwrapGroup/tryout.doc.ts"
+  majorVersion="v1"
+  height="292px"
+/>
+
+## Syntax
+
+```typescript
+function unwrapGroup<
+	GenericGroup extends Record<string, unknown>
+>(
+	group: GenericGroup
+): ComputeResult<GenericGroup>;
+```
+
+## Parameters
+
+- `group` : Object whose values can be wrapped or plain.
+
+## Return value
+
+A new object with the same keys and all values unwrapped. The input object is not mutated.
+
+## See also
+
+- [`unwrap`](/en/v1/api/common/unwrap) - Unwraps a single value
+- [`wrapValue`](/en/v1/api/common/wrapValue) - Wraps a value

docs/examples/v1/api/common/memoPromise/tryout.doc.ts

@@ -0,0 +1,12 @@
+import { memoPromise } from "@duplojs/utils";
+
+let calls = 0;
+const memoized = memoPromise(() => {
+	calls += 1;
+	return Promise.resolve("cached");
+});
+
+const first = await memoized.value;
+// "cached", calls = 1
+const second = await memoized.value;
+// "cached", calls = 1 (no recompute)

docs/examples/v1/api/common/unwrapGroup/tryout.doc.ts

@@ -0,0 +1,12 @@
+import { unwrapGroup, wrapValue } from "@duplojs/utils";
+
+const group = {
+	userId: wrapValue(42),
+	role: "admin",
+};
+
+const result = unwrapGroup(group);
+// { userId: 42, role: "admin" }
+
+const stillWrapped = group.userId;
+// WrappedValue<number>

docs/fr/v1/api/common/addWrappedProperties.md

@@ -2,8 +2,8 @@
 outline: [2, 3]
 description: "La fonction addWrappedProperties() ajoute dynamiquement des propriétés dérivées à une valeur wrappée, tout en conservant le type d'origine et en étendant le nouveau type."
 prev:
-  text: "unwrap"
-  link: "/fr/v1/api/common/unwrap"
+  text: "unwrapGroup"
+  link: "/fr/v1/api/common/unwrapGroup"
 next:
   text: "clone"
   link: "/fr/v1/api/common/clone"