feat: debug utils package

algorandfoundation · Sep 24, 2024 · 2399f23 · 2399f23
1 parent dbd109e
commit 2399f23
Show file tree

Hide file tree

Showing 25 changed files with 568 additions and 374 deletions.
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -21,19 +21,6 @@ jobs:
         npx --yes wait-on tcp:4001 -t 30000
       audit-script: |
         npm run audit
-  pull_request_debug_package:
-    uses: makerxstudio/shared-config/.github/workflows/node-ci.yml@main
-    with:
-      node-version: 18.x
-      working-directory: ./debug-utils
-      run-commit-lint: true
-      run-build: true
-      pre-test-script: |
-        pipx install algokit
-        algokit localnet start
-        npx --yes wait-on tcp:4001 -t 30000
-      audit-script: |
-        npm run audit
   check_docs:
     runs-on: ubuntu-latest
     steps:

diff --git a/.prettierignore b/.prettierignore
@@ -12,5 +12,3 @@ coverage
 .idea
 # don't format auto generated code docs
 docs/code
-# don't format test contract artifacts
-tests/example-contracts/**/*.json
diff --git a/README.md b/README.md
@@ -1,25 +1,30 @@
-# AlgoKit TypeScript Utilities
+# AlgoKit TypeScript AVM Debugging Utilities
 
-A set of core Algorand utilities written in TypeScript and released via npm that make it easier to build solutions on Algorand. This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
+An optional addon package for [algokit-utils-ts](https://github.com/algorandfoundation/algokit-utils-ts) that provides **node** specific utilities that automatically gather artifacts required for instantiating [AlgoKit AVM VSCode Debugger Extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). This project is part of [AlgoKit](https://github.com/algorandfoundation/algokit-cli).
 
-The goal of this library is to provide intuitive, productive utility functions that make it easier, quicker and safer to build applications on Algorand. Largely these functions wrap the underlying Algorand SDK, but provide a higher level interface with sensible defaults and capabilities for common tasks.
+Note: [Python's version of algokit-utils](https://github.com/algorandfoundation/algokit-utils-py) contains the same functionality without requiring a separate package install. Consider using that if you are building your AlgoKit project in Python.
 
-Note: If you prefer Python there's an equivalent [Python utility library](https://github.com/algorandfoundation/algokit-utils-py).
-
-[Install](#install) | [Documentation](docs/README.md)
+[Install](#install) | [Documentation](docs/code/README.md)
 
 ## Install
 
 This library can be installed from NPM using your favourite npm client, e.g.:
 
 ```
-npm install @algorandfoundation/algokit-utils
+npm install @algorandfoundation/algokit-utils-debug
 ```
 
-Then to import it:
+Then to import it and activate `utils-ts` debugging:
 
 ```typescript
-import { AlgorandClient, Config } from '@algorandfoundation/algokit-utils'
+import { Config } from '@algorandfoundation/algokit-utils'
+import { registerDebugHandlers } from '@algorandfoundation/algokit-utils-debug'
+
+Config.configure({
+  debug: true,
+  traceAll: true, // optional, defaults to ignoring simulate on successfull transactions.
+})
+registerDebugHandlers() // must be called before any transactions are submitted.
 ```
 
 See [usage](./docs/README.md#usage) for more.
@@ -28,28 +33,6 @@ See [usage](./docs/README.md#usage) for more.
 
 This library follows the [Guiding Principles of AlgoKit](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/algokit.md#guiding-principles).
 
-## NextJS compatibility
-
-`algokit-utils-ts` has a set of `node` specific utilities used for simplifying aggregation of artifacts for [AlgoKit VSCode Debugger Extension](https://github.com/algorandfoundation/algokit-avm-vscode-debugger). Which causes Next.js based projects to fail on `fs` module not found. To fix this issue, you can add the following to your `next.config.js` file:
-
-```js
-  webpack: (config, { isServer }) => {
-    // Fix for Module not found: Can't resolve 'fs'
-    if (!isServer) {
-      config.resolve.fallback.fs = false;
-    }
-    return config;
-  },
-```
-
-The root cause is due to the fact that, unlike many frameworks, Next.js allows you to import server-only (Node.js APIs that don't work in a browser) code into your page files. When Next.js builds your project, it removes server only code from your client-side bundle by checking which code exists inside one any of the following built-in methods (code splitting):
-
-- getServerSideProps
-- getStaticProps
-- getStaticPaths
-
-The Module not found: can't resolve 'xyz' error happens when you try to use server only code outside of these methods. Despite `algokit-utils` lazy loading the node specific code dynamically, Next.js does not seem to correctly identify whether a dynamic import is specific to server or client side. Hence the above fix disables the fallback for `fs` module so it ignores polyfilling it on client side.
-
 ## Contributing
 
 This is an open source project managed by the Algorand Foundation. See the [AlgoKit contributing page](https://github.com/algorandfoundation/algokit-cli/blob/main/CONTRIBUTING.md) to learn about making improvements.

diff --git a/docs/code/classes/types_debugging.AVMDebuggerSourceMap.md b/docs/code/classes/types_debugging.AVMDebuggerSourceMap.md
@@ -29,8 +29,8 @@ AVM debugger source map class.
 
 #### Parameters
 
-| Name              | Type                                                                          |
-| :---------------- | :---------------------------------------------------------------------------- |
+| Name | Type |
+| :------ | :------ |
 | `txnGroupSources` | [`AVMDebuggerSourceMapEntry`](types_debugging.AVMDebuggerSourceMapEntry.md)[] |
 
 #### Returns
@@ -39,7 +39,7 @@ AVM debugger source map class.
 
 #### Defined in
 
-[types/debugging.ts:60](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L60)
+[types/debugging.ts:60](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L60)
 
 ## Properties
 
@@ -49,7 +49,7 @@ AVM debugger source map class.
 
 #### Defined in
 
-[types/debugging.ts:54](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L54)
+[types/debugging.ts:54](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L54)
 
 ## Methods
 
@@ -67,9 +67,9 @@ The dictionary
 
 #### Defined in
 
-[types/debugging.ts:79](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L79)
+[types/debugging.ts:79](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L79)
 
----
+___
 
 ### fromDict
 
@@ -79,9 +79,9 @@ Creates a source map from a dictionary of source map data.
 
 #### Parameters
 
-| Name   | Type                                                                                    | Description |
-| :----- | :-------------------------------------------------------------------------------------- | :---------- |
-| `data` | [`AVMDebuggerSourceMapDict`](../interfaces/types_debugging.AVMDebuggerSourceMapDict.md) | The data    |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `data` | [`AVMDebuggerSourceMapDict`](../interfaces/types_debugging.AVMDebuggerSourceMapDict.md) | The data |
 
 #### Returns
 
@@ -91,4 +91,4 @@ The source map
 
 #### Defined in
 
-[types/debugging.ts:69](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L69)
+[types/debugging.ts:69](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L69)
diff --git a/docs/code/classes/types_debugging.AVMDebuggerSourceMapEntry.md b/docs/code/classes/types_debugging.AVMDebuggerSourceMapEntry.md
@@ -32,18 +32,18 @@ Create an AVM debugger source map entry.
 
 #### Parameters
 
-| Name          | Type     | Description                                     |
-| :------------ | :------- | :---------------------------------------------- |
-| `location`    | `string` | The location of the file the source map is for. |
-| `programHash` | `string` | The hash of the TEAL binary.                    |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `location` | `string` | The location of the file the source map is for. |
+| `programHash` | `string` | The hash of the TEAL binary. |
 
 #### Returns
 
 [`AVMDebuggerSourceMapEntry`](types_debugging.AVMDebuggerSourceMapEntry.md)
 
 #### Defined in
 
-[types/debugging.ts:36](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L36)
+[types/debugging.ts:36](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L36)
 
 ## Properties
 
@@ -55,9 +55,9 @@ The location of the file the source map is for.
 
 #### Defined in
 
-[types/debugging.ts:37](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L37)
+[types/debugging.ts:37](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L37)
 
----
+___
 
 ### programHash
 
@@ -67,7 +67,7 @@ The hash of the TEAL binary.
 
 #### Defined in
 
-[types/debugging.ts:38](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L38)
+[types/debugging.ts:38](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L38)
 
 ## Methods
 
@@ -77,8 +77,8 @@ The hash of the TEAL binary.
 
 #### Parameters
 
-| Name    | Type                                                                        |
-| :------ | :-------------------------------------------------------------------------- |
+| Name | Type |
+| :------ | :------ |
 | `other` | [`AVMDebuggerSourceMapEntry`](types_debugging.AVMDebuggerSourceMapEntry.md) |
 
 #### Returns
@@ -87,9 +87,9 @@ The hash of the TEAL binary.
 
 #### Defined in
 
-[types/debugging.ts:41](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L41)
+[types/debugging.ts:41](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L41)
 
----
+___
 
 ### toString
 
@@ -101,4 +101,4 @@ The hash of the TEAL binary.
 
 #### Defined in
 
-[types/debugging.ts:45](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L45)
+[types/debugging.ts:45](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L45)
diff --git a/docs/code/classes/types_debugging.PersistSourceMapInput.md b/docs/code/classes/types_debugging.PersistSourceMapInput.md
@@ -40,11 +40,11 @@ Note: rawTeal and compiledTeal are mutually exclusive. Only one of them should b
 
 #### Parameters
 
-| Name            | Type                                                            |
-| :-------------- | :-------------------------------------------------------------- |
-| `appName`       | `string`                                                        |
-| `fileName`      | `string`                                                        |
-| `rawTeal?`      | `string`                                                        |
+| Name | Type |
+| :------ | :------ |
+| `appName` | `string` |
+| `fileName` | `string` |
+| `rawTeal?` | `string` |
 | `compiledTeal?` | [`CompiledTeal`](../interfaces/types_debugging.CompiledTeal.md) |
 
 #### Returns
@@ -53,7 +53,7 @@ Note: rawTeal and compiledTeal are mutually exclusive. Only one of them should b
 
 #### Defined in
 
-[types/debugging.ts:95](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L95)
+[types/debugging.ts:95](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L95)
 
 ## Properties
 
@@ -63,37 +63,37 @@ Note: rawTeal and compiledTeal are mutually exclusive. Only one of them should b
 
 #### Defined in
 
-[types/debugging.ts:92](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L92)
+[types/debugging.ts:92](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L92)
 
----
+___
 
 ### \_rawTeal
 
 • `Private` `Optional` **\_rawTeal**: `string`
 
 #### Defined in
 
-[types/debugging.ts:93](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L93)
+[types/debugging.ts:93](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L93)
 
----
+___
 
 ### appName
 
 • **appName**: `string`
 
 #### Defined in
 
-[types/debugging.ts:90](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L90)
+[types/debugging.ts:90](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L90)
 
----
+___
 
 ### compiledTeal
 
 • `Optional` **compiledTeal**: [`CompiledTeal`](../interfaces/types_debugging.CompiledTeal.md)
 
 #### Defined in
 
-[types/debugging.ts:91](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L91)
+[types/debugging.ts:91](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L91)
 
 ## Accessors
 
@@ -109,9 +109,9 @@ Get the file name
 
 #### Defined in
 
-[types/debugging.ts:136](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L136)
+[types/debugging.ts:136](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L136)
 
----
+___
 
 ### rawTeal
 
@@ -125,7 +125,7 @@ Get the underlying raw teal
 
 #### Defined in
 
-[types/debugging.ts:125](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L125)
+[types/debugging.ts:125](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L125)
 
 ## Methods
 
@@ -137,8 +137,8 @@ Strips the '.teal' extension from a filename, if present.
 
 #### Parameters
 
-| Name       | Type     | Description                               |
-| :--------- | :------- | :---------------------------------------- |
+| Name | Type | Description |
+| :------ | :------ | :------ |
 | `fileName` | `string` | The filename to strip the extension from. |
 
 #### Returns
@@ -149,9 +149,9 @@ The filename without the '.teal' extension.
 
 #### Defined in
 
-[types/debugging.ts:146](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L146)
+[types/debugging.ts:146](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L146)
 
----
+___
 
 ### fromCompiledTeal
 
@@ -161,11 +161,11 @@ Returns debugger source maps input from compiled TEAL code.
 
 #### Parameters
 
-| Name           | Type                                                            | Description                        |
-| :------------- | :-------------------------------------------------------------- | :--------------------------------- |
-| `compiledTeal` | [`CompiledTeal`](../interfaces/types_debugging.CompiledTeal.md) | The compiled TEAL code             |
-| `appName`      | `string`                                                        | The name of the app                |
-| `fileName`     | `string`                                                        | The name of the file to persist to |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `compiledTeal` | [`CompiledTeal`](../interfaces/types_debugging.CompiledTeal.md) | The compiled TEAL code |
+| `appName` | `string` | The name of the app |
+| `fileName` | `string` | The name of the file to persist to |
 
 #### Returns
 
@@ -175,9 +175,9 @@ The persist source map input
 
 #### Defined in
 
-[types/debugging.ts:120](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L120)
+[types/debugging.ts:120](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L120)
 
----
+___
 
 ### fromRawTeal
 
@@ -187,10 +187,10 @@ Returns debugger source maps input from raw TEAL code.
 
 #### Parameters
 
-| Name       | Type     | Description                        |
-| :--------- | :------- | :--------------------------------- |
-| `rawTeal`  | `string` | The raw TEAL code                  |
-| `appName`  | `string` | The name of the app                |
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `rawTeal` | `string` | The raw TEAL code |
+| `appName` | `string` | The name of the app |
 | `fileName` | `string` | The name of the file to persist to |
 
 #### Returns
@@ -201,4 +201,4 @@ The persist source map input
 
 #### Defined in
 
-[types/debugging.ts:109](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/debug-utils/src/types/debugging.ts#L109)
+[types/debugging.ts:109](https://github.com/algorandfoundation/algokit-utils-ts-debug/blob/main/src/types/debugging.ts#L109)