From dc6db1eb3c9ba265c9a99439c2c355de6c729532 Mon Sep 17 00:00:00 2001 From: Tristan Menzel Date: Thu, 20 Feb 2025 19:58:31 -0800 Subject: [PATCH] docs: Update docs for box maybe --- .../api/arc4/-internal-/classes/StructBase.md | 24 ++++++++++++++++--- .../type-aliases/StructConstructor.md | 6 ++--- docs/api/arc4/classes/DynamicBytes.md | 8 +++---- docs/api/arc4/classes/StaticBytes.md | 8 +++---- docs/api/arc4/functions/decodeArc4.md | 2 +- docs/api/arc4/functions/encodeArc4.md | 2 +- docs/api/arc4/functions/interpretAsArc4.md | 2 +- docs/api/arc4/variables/Struct.md | 2 +- docs/api/index/type-aliases/Box.md | 2 +- docs/api/index/type-aliases/BoxMap.md | 2 +- docs/api/index/type-aliases/BoxRef.md | 2 +- packages/algo-ts/src/box.ts | 6 ++--- 12 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/api/arc4/-internal-/classes/StructBase.md b/docs/api/arc4/-internal-/classes/StructBase.md index b367cb2d3..d7394a9aa 100644 --- a/docs/api/arc4/-internal-/classes/StructBase.md +++ b/docs/api/arc4/-internal-/classes/StructBase.md @@ -4,7 +4,7 @@ [@algorandfoundation/algorand-typescript](../../../README.md) / [arc4](../../README.md) / [\](../README.md) / StructBase -# Class: StructBase +# Class: StructBase\ Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:466](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L466) @@ -14,15 +14,19 @@ The base type for arc4 structs - [`ARC4Encoded`](../../classes/ARC4Encoded.md) +## Type Parameters + +• **T** + ## Constructors ### new StructBase() -> **new StructBase**(): [`StructBase`](StructBase.md) +> **new StructBase**\<`T`\>(): [`StructBase`](StructBase.md)\<`T`\> #### Returns -[`StructBase`](StructBase.md) +[`StructBase`](StructBase.md)\<`T`\> #### Inherited from @@ -47,3 +51,17 @@ Retrieve the encoded bytes for this type #### Inherited from [`ARC4Encoded`](../../classes/ARC4Encoded.md).[`bytes`](../../classes/ARC4Encoded.md#bytes) + +*** + +### native + +#### Get Signature + +> **get** **native**(): `T` + +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:470](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L470) + +##### Returns + +`T` diff --git a/docs/api/arc4/-internal-/type-aliases/StructConstructor.md b/docs/api/arc4/-internal-/type-aliases/StructConstructor.md index 7ed36f950..cda218999 100644 --- a/docs/api/arc4/-internal-/type-aliases/StructConstructor.md +++ b/docs/api/arc4/-internal-/type-aliases/StructConstructor.md @@ -6,9 +6,9 @@ # Type Alias: StructConstructor() -> **StructConstructor**: \<`T`\>(`initial`) => [`StructBase`](../classes/StructBase.md) & [`Readonly`](Readonly.md)\<`T`\> & `object` +> **StructConstructor**: \<`T`\>(`initial`) => [`StructBase`](../classes/StructBase.md)\<`T`\> & [`Readonly`](Readonly.md)\<`T`\> -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:475](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L475) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:479](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L479) Type alias for the Struct constructor function @@ -20,4 +20,4 @@ Type alias for the Struct constructor function ## Returns -[`StructBase`](../classes/StructBase.md) & [`Readonly`](Readonly.md)\<`T`\> & `object` +[`StructBase`](../classes/StructBase.md)\<`T`\> & [`Readonly`](Readonly.md)\<`T`\> diff --git a/docs/api/arc4/classes/DynamicBytes.md b/docs/api/arc4/classes/DynamicBytes.md index 1020c25a6..f96224bea 100644 --- a/docs/api/arc4/classes/DynamicBytes.md +++ b/docs/api/arc4/classes/DynamicBytes.md @@ -6,7 +6,7 @@ # Class: DynamicBytes -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:492](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L492) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:496](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L496) A variable length sequence of bytes prefixed with its length expressed as a 2 byte uint @@ -24,7 +24,7 @@ A variable length sequence of bytes prefixed with its length expressed as a 2 by > **new DynamicBytes**(`value`?): [`DynamicBytes`](DynamicBytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:500](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L500) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:504](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L504) Create a new DynamicBytes instance @@ -92,7 +92,7 @@ Returns the current length of this array > **get** **native**(): [`bytes`](../../index/type-aliases/bytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:507](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L507) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:511](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L511) Get the native bytes value (excludes the length prefix) @@ -151,7 +151,7 @@ The index of the item to retrieve > **concat**(`other`): [`DynamicBytes`](DynamicBytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:515](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L515) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:519](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L519) Returns a dynamic bytes object containing all bytes from _this_ and _other_ diff --git a/docs/api/arc4/classes/StaticBytes.md b/docs/api/arc4/classes/StaticBytes.md index 0f9b4df8e..139f9c0cc 100644 --- a/docs/api/arc4/classes/StaticBytes.md +++ b/docs/api/arc4/classes/StaticBytes.md @@ -6,7 +6,7 @@ # Class: StaticBytes\ -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:523](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L523) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:527](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L527) A fixed length sequence of bytes @@ -28,7 +28,7 @@ A fixed length sequence of bytes > **new StaticBytes**\<`TLength`\>(`value`?): [`StaticBytes`](StaticBytes.md)\<`TLength`\> -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:531](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L531) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:535](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L535) Create a new StaticBytes instance @@ -96,7 +96,7 @@ Returns the current length of this array > **get** **native**(): [`bytes`](../../index/type-aliases/bytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:538](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L538) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:542](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L542) Get the native bytes value @@ -155,7 +155,7 @@ The index of the item to retrieve > **concat**(`other`): [`DynamicBytes`](DynamicBytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:546](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L546) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:550](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L550) Returns a dynamic bytes object containing all bytes from _this_ and _other_ diff --git a/docs/api/arc4/functions/decodeArc4.md b/docs/api/arc4/functions/decodeArc4.md index 546db2bd5..c3566bb29 100644 --- a/docs/api/arc4/functions/decodeArc4.md +++ b/docs/api/arc4/functions/decodeArc4.md @@ -8,7 +8,7 @@ > **decodeArc4**\<`T`\>(`bytes`, `prefix`): `T` -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:565](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L565) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:569](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L569) Decode the provided bytes to a native Algorand TypeScript value diff --git a/docs/api/arc4/functions/encodeArc4.md b/docs/api/arc4/functions/encodeArc4.md index df9077bfe..ad0a9dfd0 100644 --- a/docs/api/arc4/functions/encodeArc4.md +++ b/docs/api/arc4/functions/encodeArc4.md @@ -8,7 +8,7 @@ > **encodeArc4**\<`T`\>(`value`): [`bytes`](../../index/type-aliases/bytes.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:573](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L573) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:577](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L577) Encode the provided Algorand TypeScript value as ARC4 bytes diff --git a/docs/api/arc4/functions/interpretAsArc4.md b/docs/api/arc4/functions/interpretAsArc4.md index 318588ceb..a8b48280b 100644 --- a/docs/api/arc4/functions/interpretAsArc4.md +++ b/docs/api/arc4/functions/interpretAsArc4.md @@ -8,7 +8,7 @@ > **interpretAsArc4**\<`T`\>(`bytes`, `prefix`): `T` -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:556](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L556) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:560](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L560) Interpret the provided bytes as an ARC4 encoded type with no validation diff --git a/docs/api/arc4/variables/Struct.md b/docs/api/arc4/variables/Struct.md index 156dbf71f..4aee4c35a 100644 --- a/docs/api/arc4/variables/Struct.md +++ b/docs/api/arc4/variables/Struct.md @@ -8,7 +8,7 @@ > `const` **Struct**: [`StructConstructor`](../-internal-/type-aliases/StructConstructor.md) -Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:487](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L487) +Defined in: [packages/algo-ts/src/arc4/encoded-types.ts:491](https://github.com/algorandfoundation/puya-ts/blob/main/packages/algo-ts/src/arc4/encoded-types.ts#L491) The base type of arc4 structs diff --git a/docs/api/index/type-aliases/Box.md b/docs/api/index/type-aliases/Box.md index 77655622f..170e1e479 100644 --- a/docs/api/index/type-aliases/Box.md +++ b/docs/api/index/type-aliases/Box.md @@ -80,7 +80,7 @@ The value if the box exists, else the default value Get the value stored in the box if available, and a boolean indicating if the box exists. -If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. +If the box does not exist, the value returned at position 0 should not be relied on to have a valid value. #### Returns diff --git a/docs/api/index/type-aliases/BoxMap.md b/docs/api/index/type-aliases/BoxMap.md index 2e0951464..7e6be3b1c 100644 --- a/docs/api/index/type-aliases/BoxMap.md +++ b/docs/api/index/type-aliases/BoxMap.md @@ -134,7 +134,7 @@ The length of the box Get the value of a keyed box if available, and a boolean indicating if the box exists. -If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. +If the box does not exist, the value returned at position 0 should not be relied on to have a valid value. #### Parameters diff --git a/docs/api/index/type-aliases/BoxRef.md b/docs/api/index/type-aliases/BoxRef.md index fbda30f21..c5f068c07 100644 --- a/docs/api/index/type-aliases/BoxRef.md +++ b/docs/api/index/type-aliases/BoxRef.md @@ -121,7 +121,7 @@ The value if the box exists, else the default value Get the value stored in the box if available, and a boolean indicating if the box exists. -If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. +If the box does not exist, the value returned at position 0 will be an empty byte array. #### Returns diff --git a/packages/algo-ts/src/box.ts b/packages/algo-ts/src/box.ts index 9dbaf6a8d..77a9db7cf 100644 --- a/packages/algo-ts/src/box.ts +++ b/packages/algo-ts/src/box.ts @@ -34,7 +34,7 @@ export type Box = { /** * Get the value stored in the box if available, and a boolean indicating if the box exists. * - * If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. + * If the box does not exist, the value returned at position 0 should not be relied on to have a valid value. * @returns A tuple with the first item being the box value, and the second item being a boolean indicating if the box exists. */ maybe(): readonly [TValue, boolean] @@ -87,7 +87,7 @@ export type BoxMap = { /** * Get the value of a keyed box if available, and a boolean indicating if the box exists. * - * If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. + * If the box does not exist, the value returned at position 0 should not be relied on to have a valid value. * @param key The key of the box to check * @returns A tuple with the first item being the box value, and the second item being a boolean indicating if the box exists. */ @@ -186,7 +186,7 @@ export type BoxRef = { /** * Get the value stored in the box if available, and a boolean indicating if the box exists. * - * If the box does not exist, the value returned at position 0 is _undocumented_ and should not be relied on to have a specific value. + * If the box does not exist, the value returned at position 0 will be an empty byte array. * @returns A tuple with the first item being the box value, and the second item being a boolean indicating if the box exists. */ maybe(): readonly [bytes, boolean]