gofront 0.0.2 → 0.0.4

package/README.md

@@ -46,7 +46,7 @@ highlighting, bracket matching, and indentation rules without any extra configur
 npm install -g gofront
 ```
 
-Requires Node.js 25+.
+Requires Node.js 20+.
 
 ---
 
@@ -145,7 +145,7 @@ readable and debuggable — no name mangling, no opaque wrappers.
 | `for {}` | `while (true) {}` |
 | `for i, v := range slice` | `for (const [i, v] of arr.entries())` |
 | `for k, v := range map` | `for (const [k, v] of Object.entries(m))` |
-| `for i, ch := range str` | `for (const [i, ch] of Array.from(s).entries())` |
+| `for i, r := range str` | `for (const [i, r] of Array.from(s, (c, i) => [i, c.codePointAt(0)]))` — `r` is a rune integer |
 | `for i := range n` | `for (let i = 0; i < n; i++)` |
 | `switch` / `fallthrough` | `switch` / case fall-through |
 | `switch v := x.(type)` | `if/else if` with `typeof` / `instanceof` checks |
@@ -169,6 +169,12 @@ readable and debuggable — no name mangling, no opaque wrappers.
 | `clear(x)` | `.length = 0` (slice) or delete-loop (map) |
 | `print` / `println` | `console.log` |
 | `fmt.Sprintf` | `__sprintf` tree-shaken helper |
+| `strings.*` | JS string methods (`.includes`, `.startsWith`, `.split`, etc.) |
+| `strconv.*` | `String()`, `parseInt()`, `Number()` |
+| `sort.Slice` | `Array.prototype.sort()` with comparator wrapping |
+| `math.*` | `Math.*` methods and constants |
+| `errors.New` | Identity (returns string) |
+| `time.Now()` | `Date.now()` |
 
 ### Type system at runtime
 
@@ -179,36 +185,71 @@ enforces correctness; JavaScript doesn't need to know.
 
 ---
 
-## Example — Todo App
+## Examples — Todo App
 
-The only example is a full todo web app in `example/`, split across a
-sub-package and four source files to showcase multi-file compilation.
+There are two example apps — both implement the same todo app to show different aspects
+of GoFront.
+
+### Simple (vanilla DOM)
+
+The default example. Zero dependencies, clean 1:1 compiled JS output. Showcases GoFront's
+core language features with straightforward DOM manipulation.
 
 ```
-example/
+example/simple/
   src/
-    utils/        ← sub-package: Plural(), Max(), Clamp() — pure utilities
-      utils.go
-    types.go      ← Todo struct · FilterMode & Priority consts (iota) · filterLabel()
-    store.go      ← state management: add/toggle/remove/clear · visibleTodos()
-                     · stats() with named returns · statusLine() via utils.Plural
-    render.go     ← renderTodo() · renderFilterBar() · renderFooter() · render()
-    main.go       ← priority-toggle state · submitInput() · event wiring · seed data
-  index.html      ← HTML + CSS, loads app.js as an ES module
-  app.js          ← generated output  (produced by build)
-  build.sh        ← build script
+    types.go      ← Todo struct · FilterAll/Active/Completed iota · Priority iota
+    store.go      ← state as plain variables · add/toggle/remove/clear · visibleTodos()
+                     · stats() with named returns · defer/recover · async persistence
+    render.go     ← render() updates DOM via innerHTML · renderTodo() · renderFilterBar()
+    styles.go     ← injectStyles() creates <style> element with all CSS
+    main.go       ← createApp() builds DOM shell · setupEvents() · event delegation
+    utils/
+      utils.go    ← Plural() — cross-package import demo
+    browser.d.ts  ← minimal external type declarations (sleep)
+  index.html      ← bare HTML shell, loads app.js as ES module
+  app.js          ← generated output
 ```
 
-**Features demonstrated:** structs & methods, iota constants, named return values,
-closures, slices, maps, `for range`, `switch`, cross-package imports, multi-file
-same-package compilation, DOM APIs.
+### Reactive (signals + d.ts imports)
+
+Same app rebuilt with [reactive.js](https://github.com/seriva/microtastic), a tiny
+signals-based reactive framework. Demonstrates how GoFront integrates with external JS
+libraries via `.d.ts` type declarations — the GoFront code uses typed `Signal` values,
+`Signals.create()`, `Signals.computed()`, `Signals.batch()`, and `Reactive.bind()`,
+all described in a hand-written `browser.d.ts` shim.
+
+```
+example/reactive/
+  src/
+    types.go      ← Todo, Stats, AppElements structs
+    store.go      ← Signal-typed state · Signals.create/computed/batch
+    render.go     ← createAppShell() returns AppElements · ctx.computed/ctx.bind
+    styles.go     ← injectStyles()
+    main.go       ← wires everything together
+    utils/
+      utils.go    ← Plural()
+    browser.d.ts  ← Signal interface · Signals/Reactive/ComponentContext namespaces
+  reactive.js     ← signals framework (from microtastic)
+  index.html      ← loads reactive.js + app.js
+  app.js          ← generated output
+```
+
+### Features demonstrated
+
+Both apps cover: structs & methods, iota constants, named return values, closures,
+slices, `for range`, `switch`, cross-package imports, multi-file same-package compilation,
+`async`/`await`, `defer`/`recover`, localStorage persistence, and DOM APIs.
 
-**Build and run:**
+The reactive example additionally demonstrates: external `.d.ts` type imports,
+`declare namespace` patterns for typing JS libraries, and reactive UI updates via signals.
+
+### Build and run
 
 ```sh
-sh example/build.sh
-# → writes example/app.js
-# open example/index.html in a browser
+npm run build:simple      # → example/simple/app.js
+npm run build:reactive    # → example/reactive/app.js
+# open the respective index.html in a browser
 ```
 
 ---
@@ -308,6 +349,7 @@ signatures into GoFront's internal type representation.
 | Variadic parameters | ✓ |
 | `init()` functions | ✓ |
 | Structs + methods | ✓ |
+| Anonymous struct types (`struct { Name string }`) | ✓ — compile to plain JS objects (no class emitted) |
 | Embedded structs | ✓ |
 | Pointer receivers | ✓ |
 | Interfaces | ✓ |
@@ -323,11 +365,11 @@ signatures into GoFront's internal type representation.
 | Type conversions | ✓ |
 | Type assertions (`x.(T)`) | ✓ |
 | Type switch (`switch x.(type)`, `switch v := x.(type)`) | ✓ — compiles to `if/else if` with `typeof` / `instanceof` checks |
-| Slice expressions (`s[lo:hi]`) | ✓ |
+| Slice expressions (`s[lo:hi]`, `s[lo:hi:max]`) | ✓ — three-index form is parsed; `max` is ignored at runtime (JS has no capacity) |
 | `break` / `continue` / labeled `break` / labeled `continue` | ✓ |
 | `cap()`, `copy()`, `panic()` | ✓ |
 | Variadic spread (`f(slice...)`, `append(a, b...)`) | ✓ |
-| Bitwise operators (`&`, `\|`, `^`, `<<`, `>>`) | ✓ |
+| Bitwise operators (`&`, `\|`, `^`, `&^`, `<<`, `>>`) | ✓ — `&^` (bit clear) compiles to `& ~` |
 | Compound assignment (`+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=`) | ✓ |
 | Increment / decrement (`i++`, `i--`) | ✓ |
 | Raw string literals (backticks) | ✓ |
@@ -338,7 +380,15 @@ signatures into GoFront's internal type representation.
 | Pointer operators (`&`, `*`) | ✓ |
 | `error` type / `error("msg")` / `.Error()` | ✓ |
 | `async func` / `await` expressions | ✓ |
-| `fmt.Sprintf` / `fmt.Printf` / `fmt.Println` / `fmt.Print` / `fmt.Errorf` | ✓ |
+| `fmt.Sprintf` / `fmt.Printf` / `fmt.Println` / `fmt.Print` / `fmt.Errorf` | ✓ — expanded: `%t`, `%x`, `%X`, `%o`, `%b`, `%q`, `%e`, `%g`, width/precision |
+| `strings` package | ✓ — 20 functions: `Contains`, `HasPrefix`, `Split`, `Join`, `ToUpper`, `ToLower`, `TrimSpace`, etc. |
+| `strconv` package | ✓ — `Itoa`, `Atoi`, `FormatBool`, `FormatInt`, `ParseFloat`, `ParseInt`, `ParseBool` |
+| `sort` package | ✓ — `Ints`, `Float64s`, `Strings`, `Slice`, `SliceStable`, `SliceIsSorted` |
+| `math` package | ✓ — `Sqrt`, `Pow`, `Abs`, `Floor`, `Ceil`, `Round`, `Log`, trig functions + `Pi`, `E`, `MaxInt` constants |
+| `errors` package | ✓ — `errors.New` (returns plain string) |
+| `time` package (partial) | ✓ — `Now`, `Since`, `Sleep` + `Millisecond`, `Second`, `Minute`, `Hour` constants |
+| `unicode` package | ✓ — `IsLetter`, `IsDigit`, `IsSpace`, `IsUpper`, `IsLower`, `IsPunct`, `IsControl`, `IsPrint`, `IsGraphic`, `ToUpper`, `ToLower` |
+| `os` package (partial) | ✓ — `Exit`, `Args`, `Getenv` |
 | External `.d.ts` types | ✓ |
 | npm package types | ✓ |
 | Multi-file packages | ✓ |
@@ -350,46 +400,114 @@ signatures into GoFront's internal type representation.
 | `[]rune(s)` conversion | ✓ — produces Unicode code points via `Array.from` |
 | `[...]T{...}` array length inference | ✓ |
 | Side-effect imports (`import _ "pkg"`) | ✓ — dependency code is bundled; package namespace is not exposed |
+| Dot imports (`import . "pkg"`) | ✓ — merges package exports into the current scope (no qualifier needed) |
+| Unused local import detection | ✓ — unused cross-package imports are type errors (matching Go); `import _` exempt |
 | `min()` / `max()` builtins | ✓ — compiles to `Math.min` / `Math.max` |
 | `clear()` builtin | ✓ — zeroes slice length or deletes all map keys |
 | `range` over integer (`for i := range n`) | ✓ — Go 1.22; also supports `for range n` |
 | Type aliases (`type A = B`) | ✓ — transparent alias; no conversion needed between alias and original |
+| Numeric literal separators (`1_000_000`) | ✓ — underscores stripped at lex time |
+| Binary / octal literals (`0b1010`, `0o777`) | ✓ — passed through to JS which supports them natively |
+| Hex float literals (`0x1.8p1`) | ✓ — evaluated at lex time to a decimal value |
+| Untyped constants | ✓ — `const x = 5` produces an untyped int that coerces to `int` or `float64` on use (Go spec §Constants) |
+| Positional (unkeyed) struct literals (`Point{1, 2}`) | ✓ |
+| Method expressions (`T.Method`) | ✓ — compiles to `(recv, ...args) => recv.Method(...args)` |
+| Method values (`x.Method`) | ✓ — compiles to `x.Method.bind(x)` |
+| Struct and array equality (`a == b`) | ✓ — deep comparison via tree-shaken `__equal` helper |
+| Multi-value function forwarding (`f(g())`) | ✓ — single multi-return call forwarded as spread |
+| Terminating statement analysis | ✓ — missing `return` in non-void functions is a type error |
 
 ---
 
-## What's not implemented, and why
+## Go Compatibility
+
+GoFront implements a practical subset of the
+[Go Language Specification](https://go.dev/ref/spec) (go1.26). It is not aiming for
+byte-level parity — it is a Go-inspired language for the JavaScript platform. This
+section explains exactly where GoFront matches Go, where it intentionally diverges, and
+where JS fundamentally prevents matching Go semantics.
+
+### What matches Go
+
+The core language surface is well covered. All of these compile and behave as a Go
+developer would expect:
+
+- **Declarations**: `var`, `:=` (with re-declaration), `const` (with `iota`), `type`,
+  `func`, methods, `init()`.
+- **Control flow**: `if`/`else` (with init statement), `for` (classic, condition-only,
+  infinite, `range`), `switch`/`case`/`default`/`fallthrough`, type switches, labeled
+  `break`/`continue`, `defer`, `panic`/`recover`.
+- **Types**: `int`, `float64`, `string`, `bool`, sized integers (`int8`–`int64`,
+  `uint8`–`uint64`), `float32`, `byte`, `rune`, `error`, slices, maps, arrays, structs,
+  interfaces (with embedding), pointers (`*T`, `&x`), type aliases, function types.
+- **Expressions**: all arithmetic, comparison, logical, and bitwise operators (including
+  `&^`), compound assignment, increment/decrement, type conversions, type assertions
+  (plain and comma-ok), slice expressions (`a[lo:hi]`, `a[lo:hi:max]`), composite
+  literals (keyed and positional), `[...]T{...}` inference, rune literals, raw string
+  literals, variadic spread, blank identifier `_`, method expressions (`T.Method`),
+  method values (`x.Method`), struct/array equality, multi-value function forwarding.
+- **Builtins**: `len`, `cap`, `append`, `copy`, `make`, `delete`, `new`, `clear`, `min`,
+  `max`, `print`, `println`, `panic`, `recover`, `fmt.Sprintf`/`Printf`/`Println`/`Errorf`.
+- **Standard library shims**: `strings` (20 functions), `strconv` (8 functions),
+  `sort` (6 functions), `math` (20 functions + 6 constants), `errors.New`,
+  `time.Now`/`Since`/`Sleep` + duration constants, `unicode` (11 functions),
+  `os.Exit`/`Args`/`Getenv`.
+- **Packages**: multi-file packages, cross-package imports, import aliases,
+  dot imports, blank imports, unused import detection.
+
+### GoFront extensions (not in Go)
+
+These features are intentional additions for the JavaScript platform:
+
+| Feature | Purpose |
+|---|---|
+| `async func` / `await` | First-class async syntax for frontend work. |
+| Browser globals (`document`, `console`, etc.) | Predeclared as `any` for practical DOM access. |
+| `.d.ts` type imports (`import "js:./types.d.ts"`) | Type-safe interop with JavaScript libraries. |
+| npm package resolution | Import types from `node_modules/` and `@types/` automatically. |
 
-GoFront targets the browser. Several Go features don't translate to JavaScript, and
-some were intentionally left out to keep the compiler simple.
+### What's not implemented
 
-### Fundamental mismatches — can't implement without a runtime
+| Feature | Reason | Prospect |
+|---|---|---|
+| Generics (`[T any]`) | Touches every compiler stage. Large effort, limited runtime payoff on a JS target. | Feasible — highest-priority future feature. |
+| Range over iterator functions (Go 1.23) | `func(yield func(K, V) bool)` protocol. | Feasible. |
+| Complex numbers (`complex64`, `complex128`, `3i`) | Would need a runtime complex type. Rarely used in frontend. | Feasible but low priority. |
+| `goto` | No clean JS translation. Rare in idiomatic Go. | Not planned. |
+| Goroutines / channels / `select` | Go's concurrency model has no JS equivalent. A userland scheduler defeats the "no runtime" goal. | Out of scope. |
+| `unsafe`, `reflect`, `cgo` | Require memory model or runtime type metadata that JS cannot provide. | Out of scope. |
 
-| Feature | Why |
-|---|---|
-| Goroutines (`go` keyword) | Go's concurrency model has no JS equivalent. Workers are a different abstraction. A userland scheduler would defeat the "no runtime" goal. |
-| Channels (`chan`, `<-`) | Channels are the communication primitive for goroutines. Without goroutines, channels have no purpose. |
-| `select` statement | Multiplexes channel operations. Same dependency. |
-| Generics (Go 1.18+) | Would require monomorphisation or type-erasure strategy. Type parameters (`[T any]`) touch every compiler stage. Possible, but a large effort with limited payoff for a JS target where everything is `any` at runtime. |
+### Semantic differences
 
-### Intentionally skipped
+These features are implemented but behave differently due to fundamental JS runtime
+constraints. These are **not bugs** — they are deliberate trade-offs documented here so
+you know exactly what to expect.
 
-| Feature | Why |
-|---|---|
-| `goto` statement | Unstructured control flow has no clean JS translation. `goto` is rare in idiomatic Go. Not planned. |
+| Feature | GoFront | Go | Why |
+|---|---|---|---|
+| Map iteration order | Insertion-order (`Object.entries`) | Randomised | JS objects preserve insertion order. |
+| Integer overflow | IEEE 754 float64 semantics | Wraps at type boundary (e.g. `int32`) | All JS numbers are float64. |
+| Integer precision | Safe up to 2⁵³ | Full width per type (`int64` = 64 bits) | JS `number` limitation. |
+| `cap()` | Always equals `len()` | May exceed `len()` | JS arrays have no separate capacity. |
+| Fixed-size arrays (`[n]T`) | Plain JS arrays (no length enforcement) | Fixed at compile time | Runtime enforcement adds overhead for no JS benefit. |
+| `nil` | Maps to `null` | Typed nil (distinct per type) | JS has no typed nil concept. |
+| `rune` / `byte` | Treated as `int` | Distinct types with UTF-8 encoding | JS strings are UTF-16. |
+| `range` over string | Rune integers via `.codePointAt()` | Runes (UTF-8 code points) | Close match — indices are byte-sequential, values are code points. |
+| `len()` on strings | JS `.length` (UTF-16 code units) | Byte count (UTF-8) | Matching Go would require `TextEncoder` on every call. |
+| `error` type | Plain string | Interface `{ Error() string }` | Practical simplification for JS. |
+| `defer` | `try`/`finally` with a defer stack | Runtime stack unwinding | Covers most cases but not identical to Go internals. |
+| Struct field tags | Parsed, silently discarded | Available via `reflect` | No reflection = no use for tag values. |
+| Pointers (`&x`, `*p`) | Syntax accepted, semantically transparent | True memory indirection | JS has no pointer model. |
+| Three-index slice (`a[lo:hi:max]`) | `max` is parsed but ignored | Sets result capacity | JS arrays have no capacity. |
+| Exported / unexported | Enforced for GoFront packages; external `.d.ts`/npm namespaces are exempt | Access enforced uniformly | External JS APIs use lowercase names by convention. |
 
-### Semantic differences — JS can't match Go behaviour
+---
 
-These features exist but behave differently due to fundamental JS/Go runtime differences:
+## Roadmap
 
-| Feature | GoFront behaviour | Go behaviour | Why |
-|---|---|---|---|
-| Map iteration order | Insertion-order (`Object.entries`) | Randomised | JS objects preserve insertion order. Wrapping in a custom `Map` class would add runtime overhead for no practical benefit. |
-| Integer overflow | IEEE 754 float64 wrap | Wraps at type boundary (e.g. `int32`) | All JS numbers are float64. Emitting `\|0` or `BigInt` for every arithmetic op would be prohibitively expensive. |
-| `cap()` | Always equals `len()` | May exceed `len()` | JS arrays don't expose allocation capacity. |
-| Fixed-size arrays (`[n]T`) | Plain JS arrays (no length enforcement) | Fixed at compile time | Could add a length check at construction, but runtime enforcement adds overhead for no safety benefit in JS. |
-| `rune` / `byte` types | Treated as `int` | Distinct types with UTF-8 encoding | JS strings are UTF-16. Proper rune handling would require wrapping every string operation. |
-| `range` over string | JS characters (UTF-16 code units via `Array.from`) | Go runes (UTF-8 code points) | Same UTF-16 vs UTF-8 mismatch. |
-| `len()` on strings | JS `.length` (UTF-16 code units) | Byte count (UTF-8) | Matching Go would require `TextEncoder` on every `len(s)` call. |
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full roadmap and release history.
+Design documents for planned features are organised by release under `docs/v*/`
+(e.g. [`docs/v0.0.5/`](docs/v0.0.5/)).
 
 ---
 
@@ -399,4 +517,7 @@ These features exist but behave differently due to fundamental JS/Go runtime dif
 npm test
 ```
 
-468 tests covering language features, type errors, edge cases, DOM (jsdom), external `.d.ts`, npm resolver, multi-file compilation, embedded structs, string formatting, and the example app.
+655 tests covering language features, type errors, edge cases, DOM (jsdom), external
+`.d.ts`, npm resolver, multi-file compilation, embedded structs, string formatting, map
+iteration order, integer overflow semantics, unused variable detection, unused import
+detection, semantic difference verification, stdlib shim packages, and both example apps.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gofront",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"author": "Luuk van Venrooij",
 	"license": "MIT",
 	"repository": {
@@ -21,14 +21,18 @@
 		"type-safe"
 	],
 	"engines": {
-		"node": ">=25"
+		"node": ">=20"
 	},
 	"type": "module",
+	"files": [
+		"src/"
+	],
 	"bin": {
 		"gofront": "./src/index.js"
 	},
 	"scripts": {
-		"build": "node src/index.js",
+		"build:simple": "node src/index.js example/simple/src -o example/simple/app.js",
+		"build:reactive": "node src/index.js example/reactive/src -o example/reactive/app.js",
 		"test": "node test/run.js",
 		"format": "biome format --write .",
 		"check": "biome check ."