Feature Guides

Deep-dive guides for typesugar features, organized by category.

Standard Library

Everyday features from @typesugar/std:

Guide	Description
Extension Methods	UFCS, @opaque dot syntax, global augmentation
Pattern Matching	Exhaustive match() with discriminated unions
Pattern Matching (v2)	Scala-style structural patterns, exhaustiveness, extractors
Do-Notation	Monadic let:/yield: and applicative par:/yield:
Standard Typeclasses	Eq, Ord, Hash, Show, Monoid, FlatMap

Typeclasses & Derivation

The framework for ad-hoc polymorphism:

Guide	Description
Typeclasses	Scala 3-style implicit resolution
Derive Macros	Auto-generate implementations with @derive()
Specialization	Zero-cost typeclass inlining
Reflection	typeInfo<T>(), fieldNames<T>(), validator<T>()

Syntax Sugar

New language features — the "typesugar" in typesugar:

Guide	Description
Operators	Operator overloading via @op JSDoc on typeclass methods
Tagged Templates	Type-safe SQL, regex, HTML, and units
String Macros	regex, html, raw templates
Compile-Time Eval	Run code at build time with comptime()
Conditional Compilation	Feature flags with cfg() and @cfgAttr

Type Safety & Contracts

Compile-time correctness guarantees:

Guide	Description
Contracts	Design by contract with requires:/ensures:
Refined Types	Integration with refinement types
Type System	Refined types, newtype, HKT, phantom types
Validation	Schema validation macros
Units of Measure	Type-safe physical units

Data Structures & Algorithms

Powerful abstractions with zero runtime cost:

Guide	Description
Functional Programming	Option, Either, IO with @opaque dot syntax
HList	Heterogeneous lists (Boost.Fusion)
Type Erasure	dyn Trait for heterogeneous collections
Loop Fusion	Single-pass iterator pipelines
Parser Combinators	PEG grammar to parser (Boost.Spirit)
Collections	Typeclasses for collections, HashSet, HashMap
Graph Algorithms	GraphLike typeclass, BFS, DFS, Dijkstra, state machines
Versioned Codecs	Schema evolution (serde)
Math	Rational, complex, matrix, interval
Object Mapping	Zero-cost struct transformation
Symbolic Math	Calculus, simplification, rendering

Ecosystem Integrations

Supercharge your existing tools:

Guide	Description
Effect-TS	@service, @layer, resolveLayer<R>()
SQL	Doobie-like type-safe SQL

Developer Experience

When something goes wrong, you should know exactly what happened and how to get the level of type safety you want:

Guide	Description
Type Safety	The three-layer model: build, IDE, CI
Overview	How error messages, suggestions, and tooling work
Error Messages	Rust-style errors with labeled spans
Opt-Out Directives	Disable transformations for debugging
Testing	Power assertions, property testing
Library Manifest	Publishing typesugar-powered libraries
Interactive Playground	Try code in-browser with runtime libraries, 20+ examples

---

Quick Reference

Import Patterns

// Standard library
import { clamp, abs, match, registerFlatMap } from "@typesugar/std";

// Derive macros
import { derive, Eq, Ord, Clone, Debug, Json } from "@typesugar/derive";

// Typeclasses
import { typeclass, instance, derive, summon } from "@typesugar/typeclass";

// Operators (pipe, compose)
import { pipe, compose } from "typesugar";

// Compile-time
import { comptime, includeStr, staticAssert } from "@typesugar/macros";

// Contracts
import { requires, ensures, invariant } from "@typesugar/contracts";

// FP
import { Option, Some, None, Result, Ok, Err, IO } from "@typesugar/fp";

// SQL
import { sql, ConnectionIO } from "@typesugar/sql";

// Testing
import { assert, staticAssert, typeAssert, forAll } from "@typesugar/testing";

Feature Matrix

Feature	Package	Macro Type
comptime()	@typesugar/macros	Expression
@derive()	@typesugar/derive	Attribute
@typeclass	@typesugar/typeclass	Attribute
summon<T>()	@typesugar/typeclass	Expression
match()	@typesugar/std	Expression
sql	@typesugar/sql	Tagged Template
requires:	@typesugar/contracts	Labeled Block
let:/yield:	@typesugar/std	Labeled Block
par:/yield:	@typesugar/std	Labeled Block
cfg()	@typesugar/core	Expression
assert()	@typesugar/testing	Expression