@abcubed3/postcode-wasm 0.0.0-stage → 0.1.7

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# Postcode Nigeria WebAssembly (WASM)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency, offline-first Nigerian Postcode engine compiled to WebAssembly. Enables AI agents, edge workers, mobile apps, and web browsers to perform high-speed validation, diagnostics, formatting, administrative segment parsing/assembly, geocoding, and agent tool execution without network overhead.
+
+## Features
+
+- **Blazing Fast**: Microsecond execution on edge runtimes (Cloudflare Workers, Fastly, Vercel Edge, AWS Lambda@Edge).
+- **Full Parity with Go Native**: Exposes all 19 Go library and CLI capabilities directly to Node.js, Bun, Deno, and web browsers.
+- **Zero Network Overhead (Offline Core)**: Validation, batch validation, format repair tips, parsing, formatting, segment assembly/disassembly, geocoding, and synthetic address benchmarking run 100% offline in WASM memory.
+- **NIPOST Gateway Integration (Online)**: Level 1–3 lookups, address autocompletion, radius-based nearby search, and reverse geocoding via standard async Promises.
+- **Native AI Agent Protocols**: Pre-formatted tool definitions ready for OpenAI (`function`), Anthropic (`input_schema`), and Google Gemini (`functionDeclarations`), with a unified `executeTool` dispatcher and telemetry guardrails.
+
+## Building the WASM Binary
+
+```bash
+GOOS=js GOARCH=wasm go build -ldflags="-s -w" -o wasm/postcode.wasm ./wasm
+```
+
+## Quick Start (Node.js / Edge)
+
+```javascript
+const { initPostcode } = require('@abcubed3/postcode-wasm');
+
+async function main() {
+  const postcode = await initPostcode();
+
+  // 1. Single & Batch Validation
+  const valid = postcode.validate('EK 01 A03 FK 01');
+  console.log(valid.valid, valid.state_name); // true, 'Ekiti'
+
+  const batch = postcode.validateBatch(['EK 01 A03 FK 01', 'LA 11 W06 TC 10', 'INVALID']);
+  console.log(batch.map(r => r.valid)); // [true, true, false]
+
+  // 2. Formatting & Styles (canonical, spaced, compact, slug)
+  console.log(postcode.format('EK 01 A03 FK 01', 'compact')); // 'EK01A03FK01'
+  console.log(postcode.format('EK01A03FK01', 'canonical'));   // 'EK-01-A03-FK-01'
+  console.log(postcode.format('EK 01 A03 FK 01', 'slug'));    // 'ek-01-a03-fk-01'
+
+  // 3. Administrative Disassembly & Assembly
+  const segs = postcode.disassemble('EK-01-A03-FK-01');
+  // { state: 'EK', lga: '01', district: 'A03', area: 'FK', unit: '01' }
+
+  const assembled = postcode.assemble({
+    state: 'LA', lga: '11', district: 'W06', area: 'TC', unit: '10'
+  });
+  console.log(assembled.postcode, assembled.display); // 'LA-11-W06-TC-10', 'LA 11 W06 TC 10'
+
+  // 4. Intelligent Diagnostic Engine
+  const diag = postcode.diagnose('10001');
+  console.log(diag.actionable_tip);
+  // "Fix Length: Exactly 11 alphanumeric characters (e.g. 'EK 01 A03 FK 01'); Fix State: consider LA (Lagos)..."
+
+  // 5. Offline Geolocation & Universal Maps
+  const loc = postcode.resolveLocation('EK 01 A03 FK 01');
+  console.log(loc.latitude, loc.longitude);
+  console.log(loc.google_maps_directions_url); // Navigation URL
+  console.log(loc.apple_maps_url);              // Apple Maps URL
+
+  // 6. AI Agent Protocol (OpenAI, Anthropic, Gemini)
+  const openAITools = postcode.getAgentTools('openai');
+  const toolResult = await postcode.executeTool('validate_postcode', { code: 'EK 01 A03 FK 01' });
+  console.log('Agent tool execution:', toolResult.valid, toolResult.state_name);
+
+  // 7. Synthetic Address Generation for LLM Benchmarking
+  const dataset = postcode.generateSyntheticAddresses({ count: 5, noiseRate: 0.2 });
+  console.log(dataset[0].raw_text, dataset[0].expected_postcode);
+
+  // 8. Live Gateway Operations (L1-L3 Lookup, Autocomplete, Nearby, Reverse Geocoding)
+  postcode.setAPIKey('nipost_live_your_api_key_here');
+
+  // Query live NIPOST Gateway for commercial building data
+  const details = await postcode.lookup('EK 01 A03 FK 01', 3);
+  console.log(details.building_use_status);
+
+  // Autocomplete search
+  const suggestions = await postcode.autocomplete('Adetokunbo');
+  console.log(suggestions.results);
+
+  // Search nearby units
+  const nearby = await postcode.nearby({ latitude: 6.6018, longitude: 3.3515, radiusKm: 2 });
+  console.log(nearby.results);
+}
+
+main();
+```
+
+## API Reference
+
+### Core Offline Engine (Sync)
+| Method | Description |
+|---|---|
+| `validate(code: string): ValidationResult` | Instant 11-char grammar & state validation. |
+| `validateBatch(codes: string[]): ValidationResult[]` | High-throughput batch validation in WebAssembly memory. |
+| `diagnose(code: string): DiagnosticReport` | Granular per-segment error detection with fuzzy repair tips. |
+| `parse(code: string): ParsedPostcode` | Extracts full parsed model with capital, zone, and components. |
+| `format(code: string, style?: string): string` | Normalizes to `canonical`, `compact`, `spaced`, `hyphenated`, or `slug`. |
+| `assemble(segments: Segments): AssembledPostcode` | Assembles 5 administrative segments into canonical, display, and compact codes. |
+| `disassemble(code: string): Segments` | Decomposes code into state, LGA, district, area, and building unit. |
+| `resolveLocation(code: string): LocationResult` | Resolves offline centroid coordinates, Google Maps, Apple Maps, and OSM links. |
+| `listStates(): Record<string, StateRecord>` | Returns static dictionary of all 36 Nigerian States + FCT. |
+
+### AI Agent Protocol & Benchmarking
+| Method | Description |
+|---|---|
+| `getAgentTools(format?: 'openai' \| 'anthropic' \| 'gemini'): any[]` | Exports JSON schemas for agent function calling. |
+| `executeTool(name: string, args: any): Promise<any>` | Directly invokes agent tool handlers with structured responses. |
+| `getAgentMetrics(): AgentGuardMetrics` | Telemetry for commercial vs. offline calls and downgrade rates. |
+| `generateSyntheticAddresses(options?: GeneratorOptions): SyntheticAddress[]` | Generates realistic dirty/clean addresses with ground truth for LLM evaluation. |
+
+### Live Gateway Operations (Async)
+| Method | Description |
+|---|---|
+| `lookup(code: string, level?: number): Promise<LookupResponse>` | Queries NIPOST Gateway for Level 1, 2, or 3 commercial metadata. |
+| `autocomplete(query: string): Promise<AutocompleteResponse>` | Real-time address and street suggestions. |
+| `nearby(params: NearbyParams): Promise<NearbyResponse>` | Radius search for postcode units surrounding a coordinate. |
+| `reverseGeocode(params: ReverseParams): Promise<ReverseResponse>` | Reverse-resolves latitude and longitude into nearest valid postcode. |
+
+## Configuring the NIPOST API Key
+
+### 1. Offline vs. Online Boundary
+- **Offline Methods (No API Key Required)**: `validate()`, `validateBatch()`, `diagnose()`, `parse()`, `format()`, `assemble()`, `disassemble()`, `resolveLocation()`, `listStates()`, `getAgentTools()`, and `generateSyntheticAddresses()` run 100% offline in WebAssembly memory with zero network latency.
+- **Online Methods (API Key Configurable)**: `lookup()`, `autocomplete()`, `nearby()`, and `reverseGeocode()` connect to the live NIPOST Gateway (for commercial Level 2/3 street names, building use status, and GIS point geometry).
+
+### 2. Ways to Set or Update the API Key
+
+#### Option A: Dynamically at Runtime
+```javascript
+postcode.setAPIKey('nipost_live_your_new_key');
+```
+
+#### Option B: Full Configuration Object
+```javascript
+postcode.configure({
+  apiKey: 'nipost_live_your_key',
+  baseURL: 'https://api.postcode.gov.ng' // optional custom gateway
+});
+```
+
+#### Option C: At Engine Initialization
+```javascript
+const postcode = await initPostcode(undefined, {
+  apiKey: 'nipost_live_your_key'
+});
+```
+
+#### Option D: Automatic Environment Variable (Node.js)
+In Node.js, `initPostcode()` automatically detects `NIPOST_API_KEY` or `POSTCODE_API_KEY` from `process.env`.
+```bash
+export NIPOST_API_KEY=nipost_live_...
+node app.js
+```
+
+## Browser Usage
+
+```html
+<script src="wasm_exec.js"></script>
+<script>
+  async function loadWasm() {
+    const go = new Go();
+    const result = await WebAssembly.instantiateStreaming(fetch("postcode.wasm"), go.importObject);
+    go.run(result.instance);
+
+    // window.Postcode is now globally available
+    const res = window.Postcode.validate("EK 01 A03 FK 01");
+    console.log(res);
+
+    const loc = window.Postcode.resolveLocation("EK 01 A03 FK 01");
+    console.log("Directions:", loc.google_maps_directions_url);
+  }
+  loadWasm();
+</script>
+```

package/index.d.ts

@@ -0,0 +1,245 @@
+/**
+ * TypeScript definitions for Postcode Nigeria WebAssembly module.
+ */
+
+export interface ValidationResult {
+  valid: boolean;
+  postcode?: string;
+  compact?: string;
+  state_code?: string;
+  state_name?: string;
+  lga_code?: string;
+  district?: string;
+  area?: string;
+  unit?: string;
+  error?: string;
+  actionable_tip?: string;
+  clean_length?: number;
+}
+
+export interface Segments {
+  valid?: boolean;
+  error?: string;
+  state: string;
+  lga: string;
+  district: string;
+  area: string;
+  unit: string;
+}
+
+export interface AssembledPostcode {
+  valid: boolean;
+  error?: string;
+  postcode?: string;
+  display?: string;
+  compact?: string;
+}
+
+export interface ParsedPostcode {
+  valid: boolean;
+  input?: string;
+  postcode?: string;
+  formatted?: string;
+  compact?: string;
+  spaced?: string;
+  state_code?: string;
+  state_name?: string;
+  lga_code?: string;
+  lga_name?: string;
+  district?: string;
+  area?: string;
+  unit?: string;
+  zone?: string;
+  state_capital?: string;
+  error?: string;
+}
+
+export interface SegmentDiagnosis {
+  segment: 'Length' | 'State' | 'LGA' | 'District' | 'Area' | 'BuildingUnit';
+  input: string;
+  expected: string;
+  message: string;
+  suggestions?: string[];
+}
+
+export interface DiagnosticReport {
+  input: string;
+  valid: boolean;
+  normalized?: string;
+  clean_length: number;
+  format_score: number;
+  diagnoses?: SegmentDiagnosis[];
+  actionable_tip?: string;
+}
+
+export interface LocationResult {
+  postcode: string;
+  compact: string;
+  latitude: number;
+  longitude: number;
+  address?: string;
+  state?: string;
+  state_code: string;
+  state_name: string;
+  lga?: string;
+  lga_code?: string;
+  lga_name?: string;
+  zone?: string;
+  precision: 'building' | 'area' | 'district' | 'lga' | 'state' | number;
+  google_maps_url: string;
+  google_maps_directions_url?: string;
+  apple_maps_url: string;
+  osm_url: string;
+  search_query?: string;
+  error?: string;
+}
+
+export interface AdministrativeAddress {
+  state?: string;
+  state_name?: string;
+  lga?: string;
+  lga_name?: string;
+  district?: string;
+  district_name?: string;
+  area?: string;
+  area_name?: string;
+  unit?: string;
+  zone?: string;
+  locality_name?: string;
+}
+
+export interface RecentHouseAddress {
+  address?: string;
+  recent?: string;
+  house_number?: string;
+  street_name?: string;
+  locality_name?: string;
+}
+
+export interface PointGeometry {
+  type?: string;
+  coordinates?: [number, number];
+}
+
+export interface LookupResponse {
+  postcode: string;
+  valid: boolean;
+  administrative_address?: AdministrativeAddress;
+  recent_house_address?: RecentHouseAddress;
+  building_use_status?: string;
+  other_building_info?: Record<string, any>;
+  point_geometry?: PointGeometry;
+}
+
+export interface AutocompleteSuggestion {
+  postcode: string;
+  description: string;
+  score?: number;
+}
+
+export interface AutocompleteResponse {
+  query: string;
+  suggestions: AutocompleteSuggestion[];
+}
+
+export interface NearbyUnit {
+  postcode: string;
+  display: string;
+  distance_m: number;
+  confidence: string;
+  state_name?: string;
+  lga_name?: string;
+  address?: string;
+}
+
+export interface NearbyResponse {
+  results: NearbyUnit[];
+}
+
+export interface ReverseResponse {
+  latitude: number;
+  longitude: number;
+  postcode: string;
+  distance_m?: number;
+  location?: LocationResult;
+}
+
+export interface AgentGuardMetrics {
+  total_calls: number;
+  commercial_calls: number;
+  downgraded_calls: number;
+  offline_fallbacks: number;
+}
+
+export interface SyntheticAddress {
+  raw_text: string;
+  expected_state: string;
+  expected_state_code: string;
+  expected_lga?: string;
+  expected_postcode?: string;
+  expected_lat?: number;
+  expected_lng?: number;
+  noise_type?: string;
+}
+
+export interface GeneratorOptions {
+  count?: number;
+  noiseRate?: number;
+  seed?: number;
+}
+
+export interface PostcodeEngineOptions {
+  apiKey?: string;
+  baseURL?: string;
+}
+
+export interface StateRecord {
+  code: string;
+  name: string;
+  capital: string;
+  latitude: number;
+  longitude: number;
+  zone: string;
+}
+
+export interface PostcodeEngine {
+  // --- 1. Core Offline (Sync) ---
+  validate(code: string): ValidationResult;
+  validateBatch(codes: string[]): ValidationResult[];
+  diagnose(code: string): DiagnosticReport;
+  parse(code: string): ParsedPostcode;
+  format(code: string, style?: 'canonical' | 'compact' | 'spaced' | 'hyphenated' | 'slug'): string;
+  assemble(segments: { state: string; lga: string; district: string; area: string; unit: string }): AssembledPostcode;
+  disassemble(code: string): Segments;
+  resolveLocation(code: string): LocationResult;
+  listStates(): Record<string, StateRecord>;
+
+  // --- 2. Configuration & State (Sync) ---
+  setAPIKey(key: string): boolean;
+  getAPIKey(): string;
+  configure(options: PostcodeEngineOptions): boolean;
+
+  // --- 3. Live Gateway Operations (Async) ---
+  lookup(code: string, level?: number): Promise<LookupResponse>;
+  autocomplete(query: string): Promise<AutocompleteResponse>;
+  nearby(params: { latitude: number; longitude: number; radiusKm?: number; radius_m?: number; limit?: number }): Promise<NearbyResponse>;
+  reverseGeocode(params: { latitude: number; longitude: number; maxDistanceKm?: number; max_distance_m?: number }): Promise<ReverseResponse>;
+
+  // --- 4. AI Agent Tooling & Guardrails ---
+  getAgentTools(format?: 'openai' | 'anthropic' | 'gemini'): any[];
+  executeTool(name: string, args?: Record<string, any> | string): Promise<any>;
+  getAgentMetrics(): AgentGuardMetrics;
+
+  // --- 5. Synthetic Evaluation Benchmark ---
+  generateSyntheticAddresses(options?: GeneratorOptions): SyntheticAddress[];
+}
+
+/**
+ * Initializes and instantiates the Postcode Nigeria WebAssembly module.
+ * @param wasmSourceOrOptions Optional custom path, buffer, fetch Response, or options object.
+ * @param options Optional configuration options when wasmSource is specified.
+ */
+export function initPostcode(
+  wasmSourceOrOptions?: string | Buffer | ArrayBuffer | Response | PostcodeEngineOptions,
+  options?: PostcodeEngineOptions
+): Promise<PostcodeEngine>;

package/index.js

@@ -0,0 +1,81 @@
+/**
+ * Postcode Nigeria WebAssembly Loader
+ * Supports Node.js, Deno, Bun, and browser environments.
+ */
+
+const fs = typeof window === 'undefined' ? require('fs') : null;
+const path = typeof window === 'undefined' ? require('path') : null;
+
+// Require wasm_exec.js if running in Node.js
+if (typeof window === 'undefined' && typeof globalThis.Go === 'undefined') {
+  require('./wasm_exec.js');
+}
+
+/**
+ * Initializes the Postcode WebAssembly module.
+ * @param {string|Buffer|ArrayBuffer|Response|{ apiKey?: string, baseURL?: string }} [wasmSource] Optional path, buffer, fetch response, or options.
+ * @param {{ apiKey?: string, baseURL?: string }} [options] Optional configuration options.
+ * @returns {Promise<typeof globalThis.Postcode>} The initialized Postcode module.
+ */
+async function initPostcode(wasmSource, options = {}) {
+  if (wasmSource && typeof wasmSource === 'object' && !(wasmSource instanceof ArrayBuffer) && !(typeof Buffer !== 'undefined' && Buffer.isBuffer(wasmSource)) && !(typeof Response !== 'undefined' && wasmSource instanceof Response)) {
+    options = wasmSource;
+    wasmSource = undefined;
+  }
+
+  if (globalThis.Postcode) {
+    if (options.apiKey) globalThis.Postcode.setAPIKey(options.apiKey);
+    if (options.baseURL) globalThis.Postcode.configure({ baseURL: options.baseURL });
+    return globalThis.Postcode;
+  }
+
+  const go = new globalThis.Go();
+  let wasmBytes;
+
+  if (!wasmSource) {
+    if (typeof window === 'undefined') {
+      const defaultPath = path.resolve(__dirname, 'postcode.wasm');
+      if (fs.existsSync(defaultPath)) {
+        wasmBytes = fs.readFileSync(defaultPath);
+      } else {
+        throw new Error(`postcode.wasm not found at ${defaultPath}. Build it first with: GOOS=js GOARCH=wasm go build -o wasm/postcode.wasm ./wasm`);
+      }
+    } else {
+      wasmSource = 'postcode.wasm';
+    }
+  }
+
+  let instance;
+  if (wasmBytes) {
+    const result = await WebAssembly.instantiate(wasmBytes, go.importObject);
+    instance = result.instance;
+  } else if (typeof wasmSource === 'string' && typeof fetch !== 'undefined') {
+    const response = await fetch(wasmSource);
+    const result = await WebAssembly.instantiateStreaming(response, go.importObject);
+    instance = result.instance;
+  } else if (wasmSource instanceof ArrayBuffer || (typeof Buffer !== 'undefined' && Buffer.isBuffer(wasmSource))) {
+    const result = await WebAssembly.instantiate(wasmSource, go.importObject);
+    instance = result.instance;
+  } else {
+    throw new Error('Unsupported wasmSource format');
+  }
+
+  // Run the Go runtime in background (it will register globalThis.Postcode)
+  go.run(instance);
+
+  // Configure API key if provided via options or environment variable
+  const envKey = typeof process !== 'undefined' && process.env ? (process.env.NIPOST_API_KEY || process.env.POSTCODE_API_KEY) : undefined;
+  const apiKey = options.apiKey || envKey;
+  if (apiKey) {
+    globalThis.Postcode.setAPIKey(apiKey);
+  }
+  if (options.baseURL) {
+    globalThis.Postcode.configure({ baseURL: options.baseURL });
+  }
+
+  return globalThis.Postcode;
+}
+
+module.exports = {
+  initPostcode,
+};

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@abcubed3/postcode-wasm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.7",
+  "description": "Zero-dependency Nigerian Postcode validation, format diagnostics, and geocoding engine compiled to WebAssembly from Go",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "wasm_exec.js",
+    "postcode.wasm",
+    "README.md"
+  ],
+  "keywords": [
+    "nigeria",
+    "postcode",
+    "nipost",
+    "geocoding",
+    "wasm",
+    "webassembly",
+    "address",
+    "validation"
+  ],
+  "author": "abcubed3",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abcubed3/postcode.git",
+    "directory": "wasm"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/wasm_exec.js

@@ -0,0 +1,575 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+"use strict";
+
+(() => {
+	const enosys = () => {
+		const err = new Error("not implemented");
+		err.code = "ENOSYS";
+		return err;
+	};
+
+	if (!globalThis.fs) {
+		let outputBuf = "";
+		globalThis.fs = {
+			constants: { O_WRONLY: -1, O_RDWR: -1, O_CREAT: -1, O_TRUNC: -1, O_APPEND: -1, O_EXCL: -1, O_DIRECTORY: -1 }, // unused
+			writeSync(fd, buf) {
+				outputBuf += decoder.decode(buf);
+				const nl = outputBuf.lastIndexOf("\n");
+				if (nl != -1) {
+					console.log(outputBuf.substring(0, nl));
+					outputBuf = outputBuf.substring(nl + 1);
+				}
+				return buf.length;
+			},
+			write(fd, buf, offset, length, position, callback) {
+				if (offset !== 0 || length !== buf.length || position !== null) {
+					callback(enosys());
+					return;
+				}
+				const n = this.writeSync(fd, buf);
+				callback(null, n);
+			},
+			chmod(path, mode, callback) { callback(enosys()); },
+			chown(path, uid, gid, callback) { callback(enosys()); },
+			close(fd, callback) { callback(enosys()); },
+			fchmod(fd, mode, callback) { callback(enosys()); },
+			fchown(fd, uid, gid, callback) { callback(enosys()); },
+			fstat(fd, callback) { callback(enosys()); },
+			fsync(fd, callback) { callback(null); },
+			ftruncate(fd, length, callback) { callback(enosys()); },
+			lchown(path, uid, gid, callback) { callback(enosys()); },
+			link(path, link, callback) { callback(enosys()); },
+			lstat(path, callback) { callback(enosys()); },
+			mkdir(path, perm, callback) { callback(enosys()); },
+			open(path, flags, mode, callback) { callback(enosys()); },
+			read(fd, buffer, offset, length, position, callback) { callback(enosys()); },
+			readdir(path, callback) { callback(enosys()); },
+			readlink(path, callback) { callback(enosys()); },
+			rename(from, to, callback) { callback(enosys()); },
+			rmdir(path, callback) { callback(enosys()); },
+			stat(path, callback) { callback(enosys()); },
+			symlink(path, link, callback) { callback(enosys()); },
+			truncate(path, length, callback) { callback(enosys()); },
+			unlink(path, callback) { callback(enosys()); },
+			utimes(path, atime, mtime, callback) { callback(enosys()); },
+		};
+	}
+
+	if (!globalThis.process) {
+		globalThis.process = {
+			getuid() { return -1; },
+			getgid() { return -1; },
+			geteuid() { return -1; },
+			getegid() { return -1; },
+			getgroups() { throw enosys(); },
+			pid: -1,
+			ppid: -1,
+			umask() { throw enosys(); },
+			cwd() { throw enosys(); },
+			chdir() { throw enosys(); },
+		}
+	}
+
+	if (!globalThis.path) {
+		globalThis.path = {
+			resolve(...pathSegments) {
+				return pathSegments.join("/");
+			}
+		}
+	}
+
+	if (!globalThis.crypto) {
+		throw new Error("globalThis.crypto is not available, polyfill required (crypto.getRandomValues only)");
+	}
+
+	if (!globalThis.performance) {
+		throw new Error("globalThis.performance is not available, polyfill required (performance.now only)");
+	}
+
+	if (!globalThis.TextEncoder) {
+		throw new Error("globalThis.TextEncoder is not available, polyfill required");
+	}
+
+	if (!globalThis.TextDecoder) {
+		throw new Error("globalThis.TextDecoder is not available, polyfill required");
+	}
+
+	const encoder = new TextEncoder("utf-8");
+	const decoder = new TextDecoder("utf-8");
+
+	globalThis.Go = class {
+		constructor() {
+			this.argv = ["js"];
+			this.env = {};
+			this.exit = (code) => {
+				if (code !== 0) {
+					console.warn("exit code:", code);
+				}
+			};
+			this._exitPromise = new Promise((resolve) => {
+				this._resolveExitPromise = resolve;
+			});
+			this._pendingEvent = null;
+			this._scheduledTimeouts = new Map();
+			this._nextCallbackTimeoutID = 1;
+
+			const setInt64 = (addr, v) => {
+				this.mem.setUint32(addr + 0, v, true);
+				this.mem.setUint32(addr + 4, Math.floor(v / 4294967296), true);
+			}
+
+			const setInt32 = (addr, v) => {
+				this.mem.setUint32(addr + 0, v, true);
+			}
+
+			const getInt64 = (addr) => {
+				const low = this.mem.getUint32(addr + 0, true);
+				const high = this.mem.getInt32(addr + 4, true);
+				return low + high * 4294967296;
+			}
+
+			const loadValue = (addr) => {
+				const f = this.mem.getFloat64(addr, true);
+				if (f === 0) {
+					return undefined;
+				}
+				if (!isNaN(f)) {
+					return f;
+				}
+
+				const id = this.mem.getUint32(addr, true);
+				return this._values[id];
+			}
+
+			const storeValue = (addr, v) => {
+				const nanHead = 0x7FF80000;
+
+				if (typeof v === "number" && v !== 0) {
+					if (isNaN(v)) {
+						this.mem.setUint32(addr + 4, nanHead, true);
+						this.mem.setUint32(addr, 0, true);
+						return;
+					}
+					this.mem.setFloat64(addr, v, true);
+					return;
+				}
+
+				if (v === undefined) {
+					this.mem.setFloat64(addr, 0, true);
+					return;
+				}
+
+				let id = this._ids.get(v);
+				if (id === undefined) {
+					id = this._idPool.pop();
+					if (id === undefined) {
+						id = this._values.length;
+					}
+					this._values[id] = v;
+					this._goRefCounts[id] = 0;
+					this._ids.set(v, id);
+				}
+				this._goRefCounts[id]++;
+				let typeFlag = 0;
+				switch (typeof v) {
+					case "object":
+						if (v !== null) {
+							typeFlag = 1;
+						}
+						break;
+					case "string":
+						typeFlag = 2;
+						break;
+					case "symbol":
+						typeFlag = 3;
+						break;
+					case "function":
+						typeFlag = 4;
+						break;
+				}
+				this.mem.setUint32(addr + 4, nanHead | typeFlag, true);
+				this.mem.setUint32(addr, id, true);
+			}
+
+			const loadSlice = (addr) => {
+				const array = getInt64(addr + 0);
+				const len = getInt64(addr + 8);
+				return new Uint8Array(this._inst.exports.mem.buffer, array, len);
+			}
+
+			const loadSliceOfValues = (addr) => {
+				const array = getInt64(addr + 0);
+				const len = getInt64(addr + 8);
+				const a = new Array(len);
+				for (let i = 0; i < len; i++) {
+					a[i] = loadValue(array + i * 8);
+				}
+				return a;
+			}
+
+			const loadString = (addr) => {
+				const saddr = getInt64(addr + 0);
+				const len = getInt64(addr + 8);
+				return decoder.decode(new DataView(this._inst.exports.mem.buffer, saddr, len));
+			}
+
+			const testCallExport = (a, b) => {
+				this._inst.exports.testExport0();
+				return this._inst.exports.testExport(a, b);
+			}
+
+			const timeOrigin = Date.now() - performance.now();
+			this.importObject = {
+				_gotest: {
+					add: (a, b) => a + b,
+					callExport: testCallExport,
+				},
+				gojs: {
+					// Go's SP does not change as long as no Go code is running. Some operations (e.g. calls, getters and setters)
+					// may synchronously trigger a Go event handler. This makes Go code get executed in the middle of the imported
+					// function. A goroutine can switch to a new stack if the current stack is too small (see morestack function).
+					// This changes the SP, thus we have to update the SP used by the imported function.
+
+					// func wasmExit(code int32)
+					"runtime.wasmExit": (sp) => {
+						sp >>>= 0;
+						const code = this.mem.getInt32(sp + 8, true);
+						this.exited = true;
+						delete this._inst;
+						delete this._values;
+						delete this._goRefCounts;
+						delete this._ids;
+						delete this._idPool;
+						this.exit(code);
+					},
+
+					// func wasmWrite(fd uintptr, p unsafe.Pointer, n int32)
+					"runtime.wasmWrite": (sp) => {
+						sp >>>= 0;
+						const fd = getInt64(sp + 8);
+						const p = getInt64(sp + 16);
+						const n = this.mem.getInt32(sp + 24, true);
+						fs.writeSync(fd, new Uint8Array(this._inst.exports.mem.buffer, p, n));
+					},
+
+					// func resetMemoryDataView()
+					"runtime.resetMemoryDataView": (sp) => {
+						sp >>>= 0;
+						this.mem = new DataView(this._inst.exports.mem.buffer);
+					},
+
+					// func nanotime1() int64
+					"runtime.nanotime1": (sp) => {
+						sp >>>= 0;
+						setInt64(sp + 8, (timeOrigin + performance.now()) * 1000000);
+					},
+
+					// func walltime() (sec int64, nsec int32)
+					"runtime.walltime": (sp) => {
+						sp >>>= 0;
+						const msec = (new Date).getTime();
+						setInt64(sp + 8, msec / 1000);
+						this.mem.setInt32(sp + 16, (msec % 1000) * 1000000, true);
+					},
+
+					// func scheduleTimeoutEvent(delay int64) int32
+					"runtime.scheduleTimeoutEvent": (sp) => {
+						sp >>>= 0;
+						const id = this._nextCallbackTimeoutID;
+						this._nextCallbackTimeoutID++;
+						this._scheduledTimeouts.set(id, setTimeout(
+							() => {
+								this._resume();
+								while (this._scheduledTimeouts.has(id)) {
+									// for some reason Go failed to register the timeout event, log and try again
+									// (temporary workaround for https://github.com/golang/go/issues/28975)
+									console.warn("scheduleTimeoutEvent: missed timeout event");
+									this._resume();
+								}
+							},
+							getInt64(sp + 8),
+						));
+						this.mem.setInt32(sp + 16, id, true);
+					},
+
+					// func clearTimeoutEvent(id int32)
+					"runtime.clearTimeoutEvent": (sp) => {
+						sp >>>= 0;
+						const id = this.mem.getInt32(sp + 8, true);
+						clearTimeout(this._scheduledTimeouts.get(id));
+						this._scheduledTimeouts.delete(id);
+					},
+
+					// func getRandomData(r []byte)
+					"runtime.getRandomData": (sp) => {
+						sp >>>= 0;
+						crypto.getRandomValues(loadSlice(sp + 8));
+					},
+
+					// func finalizeRef(v ref)
+					"syscall/js.finalizeRef": (sp) => {
+						sp >>>= 0;
+						const id = this.mem.getUint32(sp + 8, true);
+						this._goRefCounts[id]--;
+						if (this._goRefCounts[id] === 0) {
+							const v = this._values[id];
+							this._values[id] = null;
+							this._ids.delete(v);
+							this._idPool.push(id);
+						}
+					},
+
+					// func stringVal(value string) ref
+					"syscall/js.stringVal": (sp) => {
+						sp >>>= 0;
+						storeValue(sp + 24, loadString(sp + 8));
+					},
+
+					// func valueGet(v ref, p string) ref
+					"syscall/js.valueGet": (sp) => {
+						sp >>>= 0;
+						const result = Reflect.get(loadValue(sp + 8), loadString(sp + 16));
+						sp = this._inst.exports.getsp() >>> 0; // see comment above
+						storeValue(sp + 32, result);
+					},
+
+					// func valueSet(v ref, p string, x ref)
+					"syscall/js.valueSet": (sp) => {
+						sp >>>= 0;
+						Reflect.set(loadValue(sp + 8), loadString(sp + 16), loadValue(sp + 32));
+					},
+
+					// func valueDelete(v ref, p string)
+					"syscall/js.valueDelete": (sp) => {
+						sp >>>= 0;
+						Reflect.deleteProperty(loadValue(sp + 8), loadString(sp + 16));
+					},
+
+					// func valueIndex(v ref, i int) ref
+					"syscall/js.valueIndex": (sp) => {
+						sp >>>= 0;
+						storeValue(sp + 24, Reflect.get(loadValue(sp + 8), getInt64(sp + 16)));
+					},
+
+					// valueSetIndex(v ref, i int, x ref)
+					"syscall/js.valueSetIndex": (sp) => {
+						sp >>>= 0;
+						Reflect.set(loadValue(sp + 8), getInt64(sp + 16), loadValue(sp + 24));
+					},
+
+					// func valueCall(v ref, m string, args []ref) (ref, bool)
+					"syscall/js.valueCall": (sp) => {
+						sp >>>= 0;
+						try {
+							const v = loadValue(sp + 8);
+							const m = Reflect.get(v, loadString(sp + 16));
+							const args = loadSliceOfValues(sp + 32);
+							const result = Reflect.apply(m, v, args);
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 56, result);
+							this.mem.setUint8(sp + 64, 1);
+						} catch (err) {
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 56, err);
+							this.mem.setUint8(sp + 64, 0);
+						}
+					},
+
+					// func valueInvoke(v ref, args []ref) (ref, bool)
+					"syscall/js.valueInvoke": (sp) => {
+						sp >>>= 0;
+						try {
+							const v = loadValue(sp + 8);
+							const args = loadSliceOfValues(sp + 16);
+							const result = Reflect.apply(v, undefined, args);
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 40, result);
+							this.mem.setUint8(sp + 48, 1);
+						} catch (err) {
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 40, err);
+							this.mem.setUint8(sp + 48, 0);
+						}
+					},
+
+					// func valueNew(v ref, args []ref) (ref, bool)
+					"syscall/js.valueNew": (sp) => {
+						sp >>>= 0;
+						try {
+							const v = loadValue(sp + 8);
+							const args = loadSliceOfValues(sp + 16);
+							const result = Reflect.construct(v, args);
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 40, result);
+							this.mem.setUint8(sp + 48, 1);
+						} catch (err) {
+							sp = this._inst.exports.getsp() >>> 0; // see comment above
+							storeValue(sp + 40, err);
+							this.mem.setUint8(sp + 48, 0);
+						}
+					},
+
+					// func valueLength(v ref) int
+					"syscall/js.valueLength": (sp) => {
+						sp >>>= 0;
+						setInt64(sp + 16, parseInt(loadValue(sp + 8).length));
+					},
+
+					// valuePrepareString(v ref) (ref, int)
+					"syscall/js.valuePrepareString": (sp) => {
+						sp >>>= 0;
+						const str = encoder.encode(String(loadValue(sp + 8)));
+						storeValue(sp + 16, str);
+						setInt64(sp + 24, str.length);
+					},
+
+					// valueLoadString(v ref, b []byte)
+					"syscall/js.valueLoadString": (sp) => {
+						sp >>>= 0;
+						const str = loadValue(sp + 8);
+						loadSlice(sp + 16).set(str);
+					},
+
+					// func valueInstanceOf(v ref, t ref) bool
+					"syscall/js.valueInstanceOf": (sp) => {
+						sp >>>= 0;
+						this.mem.setUint8(sp + 24, (loadValue(sp + 8) instanceof loadValue(sp + 16)) ? 1 : 0);
+					},
+
+					// func copyBytesToGo(dst []byte, src ref) (int, bool)
+					"syscall/js.copyBytesToGo": (sp) => {
+						sp >>>= 0;
+						const dst = loadSlice(sp + 8);
+						const src = loadValue(sp + 32);
+						if (!(src instanceof Uint8Array || src instanceof Uint8ClampedArray)) {
+							this.mem.setUint8(sp + 48, 0);
+							return;
+						}
+						const toCopy = src.subarray(0, dst.length);
+						dst.set(toCopy);
+						setInt64(sp + 40, toCopy.length);
+						this.mem.setUint8(sp + 48, 1);
+					},
+
+					// func copyBytesToJS(dst ref, src []byte) (int, bool)
+					"syscall/js.copyBytesToJS": (sp) => {
+						sp >>>= 0;
+						const dst = loadValue(sp + 8);
+						const src = loadSlice(sp + 16);
+						if (!(dst instanceof Uint8Array || dst instanceof Uint8ClampedArray)) {
+							this.mem.setUint8(sp + 48, 0);
+							return;
+						}
+						const toCopy = src.subarray(0, dst.length);
+						dst.set(toCopy);
+						setInt64(sp + 40, toCopy.length);
+						this.mem.setUint8(sp + 48, 1);
+					},
+
+					"debug": (value) => {
+						console.log(value);
+					},
+				}
+			};
+		}
+
+		async run(instance) {
+			if (!(instance instanceof WebAssembly.Instance)) {
+				throw new Error("Go.run: WebAssembly.Instance expected");
+			}
+			this._inst = instance;
+			this.mem = new DataView(this._inst.exports.mem.buffer);
+			this._values = [ // JS values that Go currently has references to, indexed by reference id
+				NaN,
+				0,
+				null,
+				true,
+				false,
+				globalThis,
+				this,
+			];
+			this._goRefCounts = new Array(this._values.length).fill(Infinity); // number of references that Go has to a JS value, indexed by reference id
+			this._ids = new Map([ // mapping from JS values to reference ids
+				[0, 1],
+				[null, 2],
+				[true, 3],
+				[false, 4],
+				[globalThis, 5],
+				[this, 6],
+			]);
+			this._idPool = [];   // unused ids that have been garbage collected
+			this.exited = false; // whether the Go program has exited
+
+			// Pass command line arguments and environment variables to WebAssembly by writing them to the linear memory.
+			let offset = 4096;
+
+			const strPtr = (str) => {
+				const ptr = offset;
+				const bytes = encoder.encode(str + "\0");
+				new Uint8Array(this.mem.buffer, offset, bytes.length).set(bytes);
+				offset += bytes.length;
+				if (offset % 8 !== 0) {
+					offset += 8 - (offset % 8);
+				}
+				return ptr;
+			};
+
+			const argc = this.argv.length;
+
+			const argvPtrs = [];
+			this.argv.forEach((arg) => {
+				argvPtrs.push(strPtr(arg));
+			});
+			argvPtrs.push(0);
+
+			const keys = Object.keys(this.env).sort();
+			keys.forEach((key) => {
+				argvPtrs.push(strPtr(`${key}=${this.env[key]}`));
+			});
+			argvPtrs.push(0);
+
+			const argv = offset;
+			argvPtrs.forEach((ptr) => {
+				this.mem.setUint32(offset, ptr, true);
+				this.mem.setUint32(offset + 4, 0, true);
+				offset += 8;
+			});
+
+			// The linker guarantees global data starts from at least wasmMinDataAddr.
+			// Keep in sync with cmd/link/internal/ld/data.go:wasmMinDataAddr.
+			const wasmMinDataAddr = 4096 + 8192;
+			if (offset >= wasmMinDataAddr) {
+				throw new Error("total length of command line and environment variables exceeds limit");
+			}
+
+			this._inst.exports.run(argc, argv);
+			if (this.exited) {
+				this._resolveExitPromise();
+			}
+			await this._exitPromise;
+		}
+
+		_resume() {
+			if (this.exited) {
+				throw new Error("Go program has already exited");
+			}
+			this._inst.exports.resume();
+			if (this.exited) {
+				this._resolveExitPromise();
+			}
+		}
+
+		_makeFuncWrapper(id) {
+			const go = this;
+			return function () {
+				const event = { id: id, this: this, args: arguments };
+				go._pendingEvent = event;
+				go._resume();
+				return event.result;
+			};
+		}
+	}
+})();