From 70e938b7674d65994e1d257d96c176362ddd9fde Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Fri, 17 May 2024 10:42:59 +0200
Subject: [PATCH] hs2js api docs

---
 packages/hs2js/README.md    | 83 ++++++++++++++++++++++++++++++++++++-
 packages/hs2js/package.json |  2 +-
 2 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/packages/hs2js/README.md b/packages/hs2js/README.md
index f4ca3ed5..7bd7acf3 100644
--- a/packages/hs2js/README.md
+++ b/packages/hs2js/README.md
@@ -1,8 +1,10 @@
 # hs2js
 
-Experimental haskell in javascript interpreter.
+Experimental haskell in javascript interpreter. Many haskell features are not implemented.
+This projects mainly exists to be able to write and interpret [Tidal Cycles](https://tidalcycles.org/) code in the browser,
+as part of [Strudel](https://github.com/tidalcycles/strudel).
 
-## Usage
+## Installation
 
 ### Via Script Tag
 
@@ -47,3 +49,80 @@ document.getElementById('hello').addEventListener('click', () => {
   hs2js.evaluate('alert "hello from haskell!"');
 });
 ```
+
+## API
+
+These are all functions exported by the package:
+
+### evaluate
+
+Evaluates a piece of haskell code
+
+- `code`: [valid](https://github.com/tree-sitter/tree-sitter-haskell?tab=readme-ov-file#supported-language-extensions) haskell code
+- `scope`: global scope, defaults to globalThis. Allows you to pass an object of your own functions / variables from JS to Haskell.
+- `ops`: mapping for custom infix operator
+
+Example:
+
+```js
+// simple
+hs2js.evaluate(`2 + 2`).then(console.log) // log 4
+// passing variables via scope:
+hs2js.evaluate(`a + b`, { a: 1, b: 2 }).then(console.log); // logs 3
+// custom operator
+hs2js.evaluate(`2 |* 3`, {}, { '|*': (l, r) => l * r }).then(console.log); // logs 6
+```
+
+### parse
+
+[Parses](https://github.com/tree-sitter/tree-sitter-haskell) a piece of haskell code, returning its AST representation.
+
+Example:
+
+```js
+hs2js.parse(`2 + 2`).then(ast=>console.log(ast.toString()))
+// (haskell declarations: (declarations (top_splice (apply function: (variable) argument: (literal (integer))))))
+```
+
+### run
+
+Evaluates `rootNode` of haskell AST (used by evaluate internally).
+
+- `rootNode`: haskell AST root node, as returned by `parse`
+- `scope`: see evaluate
+- `ops`: see evaluate
+
+Example:
+
+```js
+async function main() {
+  const ast = await hs2js.parse(`2 + 3`);
+  const res = hs2js.run(ast.rootNode);
+  console.log(res);
+}
+main(); // logs 5
+```
+
+### loadParser
+
+Loads and caches the parser by fetching `tree-sitter.wasm` and `tree-sitter-haskell.wasm`.
+This function is called internally by `parse` but calling it yourself might make the parser be ready faster, depending on your application.
+
+```js
+hs2js.loadParser().then(() => console.log('parser loaded'))
+```
+
+### setBase
+
+Sets the base path where the WASM files are expected by `loadParser`. Defaults to `/`.
+Expects `tree-sitter.wasm` and `tree-sitter-haskell.wasm` to be present.
+Can either be a relative path or a URL.
+
+```js
+hs2js.setBase('https://unpkg.com/hs2js@0.0.4/dist/');
+hs2js.loadParser(); 
+/* loads 
+- https://unpkg.com/hs2js@0.0.4/dist/tree-sitter.wasm
+- https://unpkg.com/hs2js@0.0.4/dist/tree-sitter-haskell.wasm
+*/
+```
diff --git a/packages/hs2js/package.json b/packages/hs2js/package.json
index d0cd0f62..604635e3 100644
--- a/packages/hs2js/package.json
+++ b/packages/hs2js/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hs2js",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Experimental Haskell in JavaScript interpreter",
   "main": "dist/index.js",
   "module": "dist/index.mjs",