Targo Cheatsheet

Targo uses TypeScript syntax, but its semantics are Go-first. Treat it as a Go language with a TypeScript-shaped surface, not as JavaScript with a different compiler.

Mental Model

• src/ is the source of truth.
• dist/ and tsconfig.targo.json are generated artifacts.
• types/ and vendored .targo/ trees are generated declaration output when those workflows are used.
• Validate against current Targo behavior, not against plain TypeScript expectations.
• If a construct feels "valid TypeScript but not very Go-like", treat it as suspicious until verified.

Support Matrix

Core Types

Feature	Status	Notes
number	Supported	Maps to float64
Explicit Go numeric types	Supported	int, int64, uint32, float64, etc. Prefer at API boundaries
bool	Supported	Conditions must be explicitly bool
string	Supported	.length follows Go len (byte length)
byte / rune	Supported	Go character types
bigint	Supported	Maps to *big.Int with immutability semantics
null / undefined	Supported	Part of Targo's nullable model
?. / ??	Supported	Optional chaining and nullish coalescing

Structs and Types

Feature	Status	Notes
class	Supported	Go struct with reference semantics
constructor	Supported	Subject to checker restrictions
Inheritance via extends	Not supported	Prefer composition
interface	Supported	Go-style contracts
GoInterface	Supported	Marker for Go interface boundaries
Embedding<{ ... }>()	Supported	Struct embedding pattern
DefinedType<...>()	Supported	Go defined types
#private fields	Supported	Use this form
private / protected keywords	Not supported	Use #field instead
Struct tags	Supported	Via @json / @tag JSDoc on fields

Collections

Feature	Status	Notes
slice<T>	Supported	Go-native dynamic collection
Array<T> / T[]	Supported	Runtime-backed collection with JS-style methods
map<K, V>	Supported	Go map semantics
Map<K, V>	Supported	Runtime-backed ordered map with JS-style methods
Set<T>	Supported	Runtime-backed ordered set
Fixed<T, N>	Supported	Fixed-size Go arrays
chan<T>	Supported	Channel communication

Functions and Flow

Feature	Status	Notes
Tuples for multi-return	Supported	[T, error | null] pattern
error | null	Supported	Preferred error model
panic() / recover()	Supported	Use sparingly
defer	Supported	Go-style deferred execution
async/await	Not supported	Use Go concurrency primitives
Promise	Not supported	No JS async runtime
go(() => {})	Supported	Starts goroutines
chan<T>	Supported	Channel communication
switch (chan.$select)	Supported	Select-style coordination

Tooling and Interop

Feature	Status	Notes
Direct Go package imports	Supported	Regenerate declarations after changes
targo init	Supported	Refresh declarations and config-derived state
targo test	Supported	Uses Go's test runner
testing.T / testing.B	Supported	Standard test and benchmark signatures
/** @go:* */ directives	Supported	JSDoc-based Go directives

Migration Quick Rules

• Replace exception-driven APIs with explicit error returns.
• Prefer slice<T> for Go-native code; use Array<T> when you explicitly need runtime collection methods.
• Re-check string indexing assumptions when Unicode behavior matters.
• Re-run npm run targo init after changing dependencies, imports, or Targo config.
• Prefer the Go-shaped option over the JavaScript-shaped one.

When In Doubt

• If you are reaching for Promise, extends, DOM APIs, or Node-only globals, stop and confirm the project actually supports that pattern.
• Treat older Targo docs as suspicious unless they match current code and fixtures.
• For agent workflows, start with .targo-docs/INDEX.md and then jump to the relevant topic file.

Runtime Declaration Files

Targo's type system and API surface are defined in .d.ts files. When you need to check exact signatures or whether an API exists, read these files directly:

File	Location	What it defines
lib.targo.d.ts	.targo/lib.targo.d.ts	Core types: slice, map, chan, Fixed, Ptr, Val, GoInterface, DefinedType, Embedding, numeric types, builtins (make, len, cap, append, copy, delete, close, go, defer, panic, recover, zero, ref, deref, min, max), generic constraints (comparable, Ordered, Signed, Unsigned, Integer, Float, Numeric)
lib.es.core.d.ts	.targo/lib.es.core.d.ts	ES core skeletons: String, RegExp, Function (bind/call/apply), Symbol, Iterator, Map/Set/WeakMap/WeakSet constructor stubs
lib.es.d.ts	node_modules/@targo/runtime/lib.es.d.ts	Runtime APIs: Array<T> methods, Array.of/from/make, String methods, RegExp, JSON (with [T, error] returns), Object, Map<K,V>/Set<T> full surface
lib.es.globals.d.ts	node_modules/@targo/runtime/lib.es.globals.d.ts	Globals: console.log/error (→ fmt), Math.* (→ math), NaN/Infinity/isNaN/isFinite
lib.embed.d.ts	.targo/lib.embed.d.ts	embed tagged template literal for @go:embed
lib.unsafe.d.ts	.targo/lib.unsafe.d.ts	unsafe.Pointer, Sizeof/Alignof/Offsetof, Slice/SliceData
~/.targo/pkg/std/goX.Y/*.d.ts	Global cache	Go stdlib declarations: fmt, net/http, os, strings, time, errors, etc.