aqua-compiler - npm Package Compare versions

Comparing version 0.0.13 to 0.0.14

package.json

 {
   "name": "aqua-compiler",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "An expressive high level language for the Algorand block chain that compiles to TEAL code.",
@@ -36,2 +36,5 @@ "main": "build/index.js",
   },
+  "bin": {
+    "aqua": "./bin/cli"
+  },
   "keywords": [],
@@ -38,0 +41,0 @@ "author": "[e-mail]",

README.md

@@ -13,2 +13,8 @@ # Aqua-compiler
 
+You can also install Aqua using npm:
+
+```bash
+npm install -g aqua-compiler
+```
+
 ## REPL
@@ -55,5 +61,113 @@
 
+## Using the Aqua API
 
+You can compile Aqua to TEAL code using Aqua's JavaScript/TypesScript API.
+
+First install Aqua in your Node.js project:
+
+```bash
+npm install --save aqua-compiler
+```
+
+Then import Aqua's `compile` function:
+
+```javascript
+const { compile } = require("aqua-compiler");
+```
+
+Or in TypeScript:
+
+```typescript
+import { compile } from "aqua-compiler";
+```
+
+Now use `compile` to compile Aqua to TEAL:
+
+```javascript
+const aquaCode = "return 1 + 2;"
+const tealCode = compiler(aquaCode);
+console.log(tealCode);
+```
+
+## Testing Aqua code with Jest
+
+One reason why you might want to use Aqua's API is to enable automated testing.
+
+For example, here's a Jest test that compiles Aqua to TEAL:
+
+```javascript
+import { compile } from "aqua-compiler";
+import { readFile } from "fs/promises";
+
+describe("My smart contract test suite", () => {
+
+    test("My first test", async () => {
+
+        const tealCode = await compileAquaFile("my-smart-contract.aqua");
+
+        // ... test that you can execute teal code against your sandbox blockchain ...
+    });
+
+    // ... other tests go here ...
+
+});
+
+//
+// Loads and compiles an Aqua file.
+//
+async function compileAquaFile(fileName) {
+    const fileContent = await readFile(join(tealPath, tealFileName), { encoding: "utf8" });
+    return compile(fileContent);
+}
+```
+
+After compiling an Aqua file to TEAL code you can then deploy that code against your sandbox Algorand blockchain.
+
+Another way of testing that is faster and doesn't require having an actual Algorand node instance is to use [the TEAL interpreter](https://www.npmjs.com/package/teal-interpreter) to simulate the Algorand virtual machine.
+
+A Jest test that runs Aqua code against the TEAL interpreter might look like this:
+
+```javascript
+import { compile } from "aqua-compiler";
+import { readFile } from "fs/promises";
+import { execute } from "teal-interpreter";
+
+describe("My smart contract test suite", () => {
+
+    test("My first test", async () => {
+
+        const config = {
+            // ... configure the initial state of the TEAL interpreter ...
+        }
+        const result = await executeAqua("my-smart-contract.aqua", config);
+
+        // ... run expectations against the result to check that execution of the aqua code has expected results ...
+        
+    });
+
+    // ... other tests go here ...
+
+});
+
+//
+// Loads and compiles an Aqua file.
+//
+async function compileAquaFile(fileName) {
+    const fileContent = await readFile(join(tealPath, tealFileName), { encoding: "utf8" });
+    return compile(fileContent);
+}
+
+//
+// Executes Aqua code against the TEAL interpreter.
+//
+async function executeAqua(fileName, config) {
+    const tealCode = await compileAquaFile(fileName);
+    return await execute(tealCode, config);
+}
+````
+
+
+
 ## Development
 
 See [the development guide](docs/DEVELOPMENT.md) for instructions on development of Aqua.

No alert changes

Improved metrics

Number of lines in readme file

171

increased by200%

Worsened metrics

Total package byte prevSize

323806

decreased by-0.82%

Number of package files

31

decreased by-8.82%

No dependency changes