Merge branch 'main' into build/bump-tsdoc-markdown

dfinity · Jan 20, 2025 · 32e7bed · 32e7bed
2 parents 8c9cb48 + c4b8f63
commit 32e7bed
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 3 deletions.
diff --git a/packages/utils/README.md b/packages/utils/README.md
@@ -350,27 +350,46 @@ Returns the current timestamp in nanoseconds as a `bigint`.
 
 #### :gear: toNullable
 
+Converts a value into a Candid-style variant representation of an optional value.
+
 | Function     | Type                                               |
 | ------------ | -------------------------------------------------- |
 | `toNullable` | `<T>(value?: T or null or undefined) => [] or [T]` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L4)
+Parameters:
+
+- `value`: - The value to convert into a Candid-style variant.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L11)
 
 #### :gear: fromNullable
 
+Extracts the value from a Candid-style variant representation of an optional value.
+
 | Function       | Type                                      |
 | -------------- | ----------------------------------------- |
 | `fromNullable` | `<T>(value: [] or [T]) => T or undefined` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L8)
+Parameters:
+
+- `value`: - A Candid-style variant representing an optional value.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L22)
 
 #### :gear: fromDefinedNullable
 
+Extracts the value from a Candid-style variant representation of an optional value,
+ensuring the value is defined. Throws an error if the array is empty or the value is nullish.
+
 | Function              | Type                         |
 | --------------------- | ---------------------------- |
 | `fromDefinedNullable` | `<T>(value: [] or [T]) => T` |
 
-[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L12)
+Parameters:
+
+- `value`: - A Candid-style variant representing an optional value.
+
+[:link: Source](https://github.com/dfinity/ic-js/tree/main/packages/utils/src/utils/did.utils.ts#L35)
 
 #### :gear: jsonReplacer
 

diff --git a/packages/utils/src/utils/did.utils.ts b/packages/utils/src/utils/did.utils.ts
@@ -1,14 +1,37 @@
 import { assertNonNullish } from "./asserts.utils";
 import { nonNullish } from "./nullish.utils";
 
+/**
+ * Converts a value into a Candid-style variant representation of an optional value.
+ *
+ * @template T The type of the value.
+ * @param {T | null | undefined} value - The value to convert into a Candid-style variant.
+ * @returns {[] | [T]} A Candid-style variant representation: an empty array for `null` and `undefined` or an array with the value.
+ */
 export const toNullable = <T>(value?: T | null): [] | [T] => {
   return nonNullish(value) ? [value] : [];
 };
 
+/**
+ * Extracts the value from a Candid-style variant representation of an optional value.
+ *
+ * @template T The type of the value.
+ * @param {[] | [T]} value - A Candid-style variant representing an optional value.
+ * @returns {T | undefined} The extracted value, or `undefined` if the array is empty.
+ */
 export const fromNullable = <T>(value: [] | [T]): T | undefined => {
   return value?.[0];
 };
 
+/**
+ * Extracts the value from a Candid-style variant representation of an optional value,
+ * ensuring the value is defined. Throws an error if the array is empty or the value is nullish.
+ *
+ * @template T The type of the value.
+ * @param {[] | [T]} value - A Candid-style variant representing an optional value.
+ * @returns {T} The extracted value.
+ * @throws {Error} If the array is empty or the value is nullish.
+ */
 export const fromDefinedNullable = <T>(value: [] | [T]): T => {
   const result = fromNullable(value);