typesugarSyntactic sugar for TypeScript with zero calories

Quick Example ​

interface User {
  id: number;
  name: string;
  email: string;
}

const alice: User = { id: 1, name: "Alice", email: "alice@example.com" };
const bob: User = { id: 2, name: "Bob", email: "bob@example.com" };

// Operators just work — auto-derived, auto-specialized
alice === bob; // Compiles to: alice.id === bob.id && alice.name === bob.name && ...
alice < bob; // Lexicographic comparison

// Methods just work too
alice.show(); // "User(id = 1, name = Alice, email = alice@example.com)"
alice.clone(); // Deep copy
alice.toJson(); // JSON serialization

How it works: The compiler sees === on a User, resolves the Eq typeclass, auto-derives an instance from the type's fields, and inlines the comparison directly — no dictionary lookup, no runtime cost.

Macro System ​

Custom language features that compile away

typesugar provides 6 kinds of macros, each triggered differently:

• Expression macros — myMacro(...) function calls
• Attribute macros — @myDecorator on classes, methods, properties
• Derive macros — @derive(Eq, Clone) generates implementations from type structure
• Tagged template macros — sql`SELECT * FROM users` with compile-time validation
• Type macros — Refined<number, Positive> at the type level
• Labeled block macros — let: { } yield: { } for custom control flow

// Define a simple expression macro
defineSyntaxMacro("unless", {
  arms: [
    {
      pattern: "$cond:expr, $body:expr",
      expand: "($cond) ? undefined : ($body)",
    },
  ],
});

// Use it
unless(isLoggedIn, redirect("/login"));
// Compiles to: (isLoggedIn) ? undefined : (redirect("/login"))

Writing Macros Guide · Macro Types Reference

Functional Programming & Type Theory ​

Typeclasses, monads, and proofs — for the nerds

If you're into FP, typesugar has you covered:

• Typeclasses with implicit resolution and zero-cost specialization — Eq, Ord, Show, Functor, Monad, and more
• Data types — Option (null-based, zero-cost), Either, IO, Validated, List
• Do-notation via let:/yield: labeled blocks — works with any monad
• HKT with F<A> syntax — write generic code over type constructors
• Refined types — Positive, Port, Email, NonEmpty<T> with compile-time validation
• Design by Contract — requires(), ensures(), @invariant with compile-time proof elimination

// HKT with F<A> syntax (the transformer rewrites F<A> to Kind<F, A>)
interface Functor<F> {
  map<A, B>(fa: F<A>, f: (a: A) => B): F<B>;
}

// Do-notation for any monad
const result = let: {
  user  << fetchUser(id);
  posts << fetchPosts(user.id);
  stats << computeStats(posts);
}
yield: { { user, posts, stats } };

// Contracts with compile-time proof elimination
function sqrt(x: number): number {
  requires: { x >= 0 }
  ensures: { result => result >= 0 }
  return Math.sqrt(x);
}

Typeclasses Guide · FP Guide · Contracts Guide

Compile-Time Powers ​

Run code at build time, not at runtime

Move computation from runtime to compile time:

• comptime() — evaluate any expression at build time
• @tailrec — tail-call elimination for stack-safe recursion
• includeStr() / includeJson() — embed file contents at compile time
• staticAssert() — compile-time assertions that disappear in output
• cfg() / @cfgAttr — conditional compilation for feature flags
• collectTypes() — introspect your entire project at compile time
• "use no typesugar" — opt-out directives for debugging and interop

// Computed at compile time, inlined as a literal
const BUILD_TIME = comptime(new Date().toISOString());
const FIB_50 = comptime(fibonacci(50));

// Stack-safe recursion via loop transformation
@tailrec
function factorial(n: number, acc = 1): number {
  if (n <= 1) return acc;
  return factorial(n - 1, n * acc);
}
// Compiles to: while(true) { if (n <= 1) return acc; acc = n * acc; n = n - 1; }

// Embed files at compile time
const SCHEMA = includeJson("./schema.json");
const TEMPLATE = includeStr("./email.html");

Compile-Time Guide · Conditional Compilation

Standard Library ​

TypeScript's missing standard library

Batteries included for everyday TypeScript:

• Extension methods — (42).clamp(0, 100), "hello".capitalize(), [1,2,3].sum()
• Pattern matching — exhaustive match() with discriminated unions, guards, OR patterns
• Reflection — typeInfo<T>(), fieldNames<T>(), validator<T>() at compile time
• Object mapping — transformInto() for zero-cost struct-to-struct conversion
• Derive macros — @derive(Eq, Ord, Clone, Debug, Hash, Json, Builder, TypeGuard)
• Tagged templates — sql, regex, html, fmt with compile-time validation

// Pattern matching with exhaustiveness checking
type Result<T, E> = { tag: "Ok"; value: T } | { tag: "Err"; error: E };

const message = match(result, {
  Ok: ({ value }) => `Got ${value}`,
  Err: ({ error }) => `Failed: ${error}`,
});

// Extension methods on primitives
const clamped = (255).clamp(0, 100); // 100
const words = "hello world".words(); // ["hello", "world"]
const total = [1, 2, 3, 4, 5].sum(); // 15

// Auto-derive common implementations
@derive(Eq, Clone, Debug, Json)
class Point {
  constructor(
    public x: number,
    public y: number
  ) {}
}

Pattern Matching · Derive Guide · Extension Methods

Data Structures & Algorithms ​

Powerful abstractions with zero runtime cost

Advanced data structures and algorithms following typesugar's zero-cost philosophy:

• HList — Heterogeneous lists with compile-time type tracking (Boost.Fusion)
• Parser — Compile-time parser generation from PEG grammars (Boost.Spirit)
• Fusion — Single-pass iterator pipelines and expression templates (Blitz++)
• Graph — Graph algorithms and state machine verification (Boost.Graph)
• Erased — Typeclass-based type erasure for heterogeneous collections (dyn Trait)
• Codec — Versioned serialization with schema evolution (Boost.Serialization)

// Lazy iterator fusion — single pass, no intermediate arrays
const result = lazy([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
  .filter((x) => x % 2 === 0)
  .map((x) => x * x)
  .take(3)
  .toArray();
// → [4, 16, 36] — single loop, early termination

// PEG grammar → recursive descent parser
const csv = grammar`
  file   = record ("\\n" record)*
  record = field ("," field)*
  field  = quoted | unquoted
  quoted = '"' (!'"' .)* '"'
  unquoted = (!',' !'\\n' .)*
`;

HList Guide · Parser Guide · Fusion Guide · Graph Guide

Framework Adapters ​

Supercharge your existing tools

typesugar integrates deeply with popular frameworks:

Effect-TS ​

Reduce Effect boilerplate with macros. The let:/yield: do-notation works seamlessly with Effect.

@service
class UserService {
  getUser(id: string) { return Effect.succeed({ id, name: "Alice" }); }
}

@layer
class UserServiceLive implements UserService {
  getUser(id: string) { return Effect.succeed({ id, name: "Alice" }); }
}

// Do-notation with Effect
const program = let: {
  user  << UserService.getUser("123");
  posts << PostService.getPosts(user.id);
}
yield: { posts.length };

Testing ​

Power assertions and property-based testing:

// Power assertions show expression breakdown on failure
assert(user.age > 18 && user.name.length > 0);
// On failure:
//   assert(user.age > 18 && user.name.length > 0)
//          |    |   |     |    |    |      |
//          |    16  false |    ""   0      false
//          { age: 16, name: "" }

class Point {
  constructor(
    public x: number,
    public y: number
  ) {}
}

// forAll auto-derives Arbitrary generators from field types
forAll(Point, (p) => p.x + p.y === p.y + p.x);
forAll(Point, 1000, (p) => p.x * 0 === 0); // custom iteration count

Effect Integration · Testing Guide

Developer Experience ​

When something goes wrong, you should know exactly what happened and how to fix it.

Rust-Style Errors ​

Every error shows the code, points at the problem, and suggests a fix:

error[TS9101]: Cannot auto-derive Eq<UserProfile>: field `metadata` has type `unknown` which lacks Eq
  --> src/user.ts:5:3
   |
 3 |   interface UserProfile {
 4 |     id: number;
 5 |     metadata: unknown;
   |     ^^^^^^^^ this field prevents auto-derivation
   |
   = note: `unknown` cannot implement Eq — it could be anything
   = help: Use a concrete type instead of `unknown`, or provide @instance Eq<UserProfile>

Look up any error: npx typesugar --explain TS9101

Import Suggestions ​

Missing an import? typesugar tells you where to find it:

error[TS9062]: Method `clamp` does not exist on type `number`
  --> src/math.ts:7:20
   |
 7 |   const safe = value.clamp(0, 100);
   |                      ^^^^^
   |
   = help: Did you mean to import?
     + import { clamp } from "@typesugar/std";

Opt-Out When You Need To ​

"use no typesugar"; // whole file
function debug() {
  "use no typesugar";
} // one function
specialize(add); // @ts-no-typesugar     // one line
("use no typesugar extensions"); // just extensions

Error Messages Guide · Developer Experience Guide · Opt-Out Guide · Error Reference · Performance Architecture

Packages ​

Build Infrastructure ​

Standard Library ​

Typeclasses & Derivation ​

Syntax Sugar ​

Type Safety & Contracts ​

Data Structures & Algorithms ​

Ecosystem Integrations ​

Developer Experience ​

Full Package Reference

Inspired by the Best ​

typesugar draws from the best ideas across language ecosystems:

Vision ​

Long-term vision documents for typesugar's future:

• Vision Index — Overview, philosophy, roadmap
• Reactivity — State model with type-aware auto-unwrapping
• Effect Integration — Deep Effect-TS integration