feat: include a ref property on the Box type which can be used to directly access box bytes

docs/code/index/classes/ApplicationSpy.md

@@ -6,7 +6,7 @@
 
 # Class: ApplicationSpy\<TContract\>
 
-Defined in: [src/application-spy.ts:32](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L32)
+Defined in: [src/application-spy.ts:34](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L34)
 
 ## Type Parameters
 
@@ -20,7 +20,7 @@ Defined in: [src/application-spy.ts:32](https://github.com/algorandfoundation/al
 
 > **new ApplicationSpy**\<`TContract`\>(`contract`?): `ApplicationSpy`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:44](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L44)
+Defined in: [src/application-spy.ts:46](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L46)
 
 #### Parameters
 
@@ -38,15 +38,15 @@ Defined in: [src/application-spy.ts:44](https://github.com/algorandfoundation/al
 
 > `optional` **contract**: `TContract` \| `ConstructorFor`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:42](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L42)
+Defined in: [src/application-spy.ts:44](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L44)
 
 ***
 
 ### on
 
 > `readonly` **on**: `_TypedApplicationSpyCallBacks`\<`TContract`\>
 
-Defined in: [src/application-spy.ts:39](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L39)
+Defined in: [src/application-spy.ts:41](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L41)
 
 The `on` property is a proxy that allows you to register callbacks for specific method signatures.
 It dynamically creates methods based on the contract's methods.
@@ -57,7 +57,7 @@ It dynamically creates methods based on the contract's methods.
 
 > **notify**(`itxn`): `void`
 
-Defined in: [src/application-spy.ts:50](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L50)
+Defined in: [src/application-spy.ts:52](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L52)
 
 #### Parameters
 
@@ -73,44 +73,98 @@ Defined in: [src/application-spy.ts:50](https://github.com/algorandfoundation/al
 
 ### onAbiCall()
 
+#### Call Signature
+
 > **onAbiCall**(`methodSignature`, `callback`): `void`
 
-Defined in: [src/application-spy.ts:69](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L69)
+Defined in: [src/application-spy.ts:80](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L80)
 
 Registers a callback for a specific method signature.
 
-#### Parameters
+##### Parameters
 
-##### methodSignature
+###### methodSignature
 
 `bytes`
 
-##### callback
+###### callback
 
 `AppSpyCb`
 
-#### Returns
+##### Returns
+
+`void`
+
+#### Call Signature
+
+> **onAbiCall**(`methodSignature`, `ocas`, `callback`): `void`
+
+Defined in: [src/application-spy.ts:81](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L81)
+
+Registers a callback for a specific method signature.
+
+##### Parameters
+
+###### methodSignature
+
+`bytes`
+
+###### ocas
+
+`OnCompleteAction`[]
+
+###### callback
+
+`AppSpyCb`
+
+##### Returns
 
 `void`
 
 ***
 
 ### onBareCall()
 
+#### Call Signature
+
 > **onBareCall**(`callback`): `void`
 
-Defined in: [src/application-spy.ts:60](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L60)
+Defined in: [src/application-spy.ts:62](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L62)
 
 Registers a callback for a bare call (no arguments).
 
-#### Parameters
+##### Parameters
 
-##### callback
+###### callback
 
 `AppSpyCb`
 
 The callback to be executed when a bare call is detected.
 
-#### Returns
+##### Returns
+
+`void`
+
+#### Call Signature
+
+> **onBareCall**(`ocas`, `callback`): `void`
+
+Defined in: [src/application-spy.ts:63](https://github.com/algorandfoundation/algorand-typescript-testing/blob/main/src/application-spy.ts#L63)
+
+Registers a callback for a bare call (no arguments).
+
+##### Parameters
+
+###### ocas
+
+`OnCompleteAction`[]
+
+###### callback
+
+`AppSpyCb`
+
+The callback to be executed when a bare call is detected.
+
+##### Returns
 
 `void`

package.json

@@ -66,8 +66,8 @@
     "vitest": "3.1.3"
   },
   "dependencies": {
-    "@algorandfoundation/algorand-typescript": "1.0.0-alpha.54",
-    "@algorandfoundation/puya-ts": "1.0.0-alpha.54",
+    "@algorandfoundation/algorand-typescript": "1.0.0-alpha.55",
+    "@algorandfoundation/puya-ts": "1.0.0-alpha.55",
     "elliptic": "^6.6.1",
     "js-sha256": "^0.11.0",
     "js-sha3": "^0.9.3",

src/impl/state.ts

@@ -236,6 +236,10 @@ export class BoxCls<TValue> {
     return lazyContext.ledger.getBox(this.#app, this.key).length
   }
 
+  get ref(): BoxRefCls {
+    return new BoxRefCls(this.key)
+  }
+
   get(options: { default: TValue }): TValue {
     const [value, exists] = this.maybe()
     return exists ? value : options.default

tests/references/box-map.spec.ts

@@ -1,8 +1,8 @@
 import type { biguint, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
 import { BigUint, BoxMap, Bytes, op, Uint64 } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import type { Bool, DynamicBytes, Tuple } from '@algorandfoundation/algorand-typescript/arc4'
-import { ARC4Encoded, DynamicArray, interpretAsArc4, Str, Struct, UintN64 } from '@algorandfoundation/algorand-typescript/arc4'
+import type { Bool, DynamicBytes, StaticArray, Tuple, UintN16 } from '@algorandfoundation/algorand-typescript/arc4'
+import { ARC4Encoded, DynamicArray, interpretAsArc4, Str, Struct, UintN64, UintN8 } from '@algorandfoundation/algorand-typescript/arc4'
 import { afterEach, describe, expect, it, test } from 'vitest'
 import { MAX_UINT64 } from '../../src/constants'
 import { toBytes } from '../../src/encoders'
@@ -259,4 +259,36 @@ describe('BoxMap', () => {
       expect(boxMap(key).value.at(-1).native).toEqual(400)
     })
   })
+
+  test('should be able to replace specific bytes values using ref', () => {
+    ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+      const boxMap = BoxMap<uint64, StaticArray<UintN16, 4>>({ keyPrefix: 'a' })
+
+      const box1 = boxMap(1)
+      box1.create()
+
+      const boxRefA = box1.ref
+      boxRefA.replace(1, new UintN8(123).bytes)
+      expect(box1.value[0].native).toEqual(123)
+      expect(boxMap(1).value[0].native).toEqual(123)
+
+      const boxRefB = box1.ref
+      boxRefB.replace(2, new UintN8(255).bytes)
+      expect(box1.value[1].native).toEqual(65280)
+      expect(boxMap(1).value[1].native).toEqual(65280)
+
+      const box2 = boxMap(2)
+      box2.create()
+
+      const boxRefC = box2.ref
+      boxRefC.replace(1, new UintN8(223).bytes)
+      expect(box2.value[0].native).toEqual(223)
+      expect(boxMap(2).value[0].native).toEqual(223)
+
+      const boxRefD = box2.ref
+      boxRefD.replace(3, new UintN8(255).bytes)
+      expect(box2.value[1].native).toEqual(255)
+      expect(boxMap(2).value[1].native).toEqual(255)
+    })
+  })
 })

tests/references/box.spec.ts

@@ -1,7 +1,7 @@
 import type { biguint, bytes, uint64 } from '@algorandfoundation/algorand-typescript'
 import { BigUint, Box, Bytes, op, Uint64 } from '@algorandfoundation/algorand-typescript'
 import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
-import type { DynamicBytes } from '@algorandfoundation/algorand-typescript/arc4'
+import type { DynamicBytes, UintN16 } from '@algorandfoundation/algorand-typescript/arc4'
 import {
   ARC4Encoded,
   Bool,
@@ -269,6 +269,21 @@ describe('Box', () => {
     })
   })
 
+  test('should be able to replace specific bytes values using ref', () => {
+    ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {
+      const box = Box<StaticArray<UintN16, 4>>({ key: 'a' })
+      box.create()
+
+      const boxRef1 = box.ref
+      boxRef1.replace(1, new UintN8(123).bytes)
+      expect(box.value[0].native).toEqual(123)
+
+      const boxRef2 = box.ref
+      boxRef2.replace(2, new UintN8(255).bytes)
+      expect(box.value[1].native).toEqual(65280)
+    })
+  })
+
   describe('Box.create', () => {
     it('throw errors if size is not provided for dynamic value type', () => {
       ctx.txn.createScope([ctx.any.txn.applicationCall()]).execute(() => {