Add readme and exports

Author: KevinBatdorf

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# These are supported funding model platforms
+github: [kevinbatdorf]

README.md

@@ -0,0 +1,92 @@
+# Pinky Compiler
+
+A fast, embeddable compiler for the Pinky scripting language.
+Compile Pinky code to WebAssembly and run it anywhere JavaScript runs.
+
+---
+
+## Features
+
+-  Compile Pinky source to WASM bytes
+-  Run Pinky code in the browser or Node.js
+-  TypeScript-first API
+-  Tiny, dependency-free runtime
+
+---
+
+## Install
+
+```sh
+npm install pinky-compiler
+```
+
+---
+
+## Usage
+
+```ts
+import { compileFromSource, init } from "pinky-compiler";
+
+// 1. Compile Pinky source to WASM bytes
+const source = `
+  x := 5
+  println "Hello, Pinky!"
+  println x + 10
+`;
+const { bytes, error } = compileFromSource(source);
+
+if (error) throw error;
+
+// 2. Initialize the WASM runtime (once per app)
+const { run } = await init();
+
+// 3. Run the compiled program
+const output = run(bytes);
+console.log(output.join("")); // Hello, Pinky!\n15\n
+```
+
+---
+
+## API
+
+### `compileFromSource(source: string)`
+
+Tokenizes, parses, and compiles Pinky source code to WASM.
+
+-  **Returns:** `{ bytes: Uint8Array, error, meta }`
+
+### `init()`
+
+Initializes the WASM runtime and returns an object with a `run` function.
+
+-  **Returns:** `Promise<{ run: (bytes: Uint8Array) => string[] }>`
+
+### `run(bytes: Uint8Array)`
+
+Runs the compiled WASM program and returns output as an array of strings.
+
+---
+
+## Advanced Usage
+
+You can also use the lower-level building blocks:
+
+```ts
+import { tokenize, parse, compile, init } from "pinky-compiler";
+
+const { tokens } = tokenize('println "hi"');
+const { ast } = parse(tokens);
+const { bytes } = compile(ast);
+const { run } = await init();
+run(bytes);
+```
+
+---
+
+## Types
+
+All major types are exported:
+
+```ts
+import type { AST, Token, CompilerErrorType, ParseErrorType, TokenErrorType } from "pinky-compiler";
+```

src/compiler.test.ts

@@ -1,14 +1,13 @@
 import { beforeAll, expect, test } from "vitest";
-import { compile } from "./compiler";
-import { tokenize } from "./lexer";
-import { parse } from "./parser";
-import { loadWasm, type RunFunction } from "./compiler/exports";
+import { compile, init, parse, tokenize } from ".";
+import type { RunFunction } from "./compiler/exports";
+
 declare global {
 	var run: RunFunction;
 }
 
 beforeAll(async () => {
-	const { run } = await loadWasm();
+	const { run } = await init();
 	globalThis.run = run;
 });
 

src/compiler/exports.ts

@@ -66,28 +66,26 @@ export const loadWasm = async (): Promise<{ run: RunFunction }> => {
 			return base ** exp;
 		},
 	};
-
-	return {
-		run: (bytes: Uint8Array): string[] => {
-			output.length = 0; // clear previous output
-			const program = new WebAssembly.Module(bytes);
-			const instance = new WebAssembly.Instance(program, {
-				env,
-			});
-			memory = instance.exports.memory as WebAssembly.Memory;
-			try {
-				(instance.exports.main as () => void)();
-			} catch (e) {
-				console.error("Runtime error:", e);
-				let msg = e instanceof Error ? e.message : String(e);
-				if (msg === "unreachable") {
-					msg = "Unreachable code found. Infinite loop?";
-				}
-				return [`RuntimeError: ${msg}`];
+	const run = (bytes: Uint8Array): string[] => {
+		output.length = 0; // clear previous output
+		const program = new WebAssembly.Module(bytes);
+		const instance = new WebAssembly.Instance(program, {
+			env,
+		});
+		memory = instance.exports.memory as WebAssembly.Memory;
+		try {
+			(instance.exports.main as () => void)();
+		} catch (e) {
+			console.error("Runtime error:", e);
+			let msg = e instanceof Error ? e.message : String(e);
+			if (msg === "unreachable") {
+				msg = "Unreachable code found. Infinite loop?";
 			}
-			return [...output];
-		},
+			return [`RuntimeError: ${msg}`];
+		}
+		return [...output];
 	};
+	return { run };
 };
 
 const boxString = (str: string, memory: WebAssembly.Memory): number => {

src/index.ts

@@ -0,0 +1,44 @@
+import { compile } from "./compiler";
+import { loadWasm } from "./compiler/exports";
+import { tokenize } from "./lexer";
+import { parse } from "./parser";
+
+export type { CompilerErrorType } from "./compiler";
+export { compile } from "./compiler";
+export { loadWasm } from "./compiler/exports";
+export { tokenize } from "./lexer";
+export type { TokenErrorType } from "./lexer";
+export type { AST, ParseErrorType } from "./parser";
+export { parse } from "./parser";
+export * from "./syntax";
+export type { Token } from "./tokens";
+
+/**
+ * Compiles Pinky source code from a string.
+ * This function tokenizes the source code, parses the tokens into an AST,
+ * and then compiles the AST into WebAssembly binary.
+ *
+ * ```
+ * const source = "x := 42 print(x)";
+ * const wasmBytes = compileFromSource(source);
+ * ```
+ */
+export const compileFromSource = (source: string) => {
+	const { tokens } = tokenize(source);
+	const { ast } = parse(tokens);
+	return compile(ast);
+};
+
+/**
+ * Initialize WASM runtime and get the run function.
+ * The run function outputs an array of strings.
+ *
+ * ```
+ *   const { run } = await init();
+ *   const output = run(bytes);
+ * ```
+ */
+export const init = async () => {
+	const { run } = await loadWasm();
+	return { run };
+};

src/lexer.test.ts

@@ -1,4 +1,5 @@
-import { test, expect } from "vitest";
+import { expect, test } from "vitest";
+import { tokenize } from ".";
 import {
 	advance,
 	decodeStringLiteralSegment,
@@ -11,7 +12,6 @@ import {
 	lookahead,
 	match,
 	peek,
-	tokenize,
 } from "./lexer";
 
 test("isAlpha", () => {

src/lexer.ts

@@ -102,6 +102,9 @@ export const decodeStringLiteralSegment = (
 	};
 };
 
+/**
+ * Tokenizes Pinky source code into tokens.
+ */
 export const tokenize = (
 	src: string,
 ): { tokens: Token[]; error: TokenErrorType | null } => {

src/parser.test.ts

@@ -1,16 +1,15 @@
 import { expect, test } from "vitest";
+import { parse, tokenize } from ".";
 import {
 	advance,
 	expectNext,
 	isEOF,
 	isNextToken,
 	match,
-	parse,
 	peek,
 	previousToken,
 } from "./parser";
 import type { Token } from "./tokens";
-import { tokenize } from "./lexer";
 
 // Helpers
 test("peek returns current token", () => {