typesugar

TypeScript that F*cks! Compile-time macros for TypeScript.

Overview

typesugar brings Scala 3-style metaprogramming to TypeScript. Write macros that transform code at compile time, eliminating runtime overhead while maintaining full type safety.

This is the umbrella package that re-exports all core typesugar functionality. Install this if you want everything.

Installation

npm install typesugar
# or
pnpm add typesugar

Quick Start

1. Configure your bundler

// vite.config.ts
import typesugar from "typesugar/vite";

export default {
  plugins: [typesugar()],
};

2. Use macros in your code

import { comptime, derive, pipe } from "typesugar";

// Compile-time evaluation
const factorial5 = comptime(() => {
  let result = 1;
  for (let i = 1; i <= 5; i++) result *= i;
  return result;
});
// Compiles to: const factorial5 = 120;

// Auto-derived implementations
@derive(Eq, Debug, Clone)
interface User {
  id: number;
  name: string;
}
// Generates: userEq(), debugUser(), cloneUser()

// Operator overloading — via typeclass @op JSDoc (e.g., Numeric, Semigroup)
// When an instance exists: a + b compiles to instance.add(a, b)

// Function composition
const process = pipe(data, parse, validate, transform);
// Compiles to: transform(validate(parse(data)))

Features

Compile-Time Evaluation

Evaluate expressions during compilation — constants, computed values, complex logic.

Derive Macros (@typesugar/derive)

Auto-generate implementations: Eq, Ord, Clone, Debug, Hash, Default, Json, Builder, TypeGuard.

Type Reflection (@typesugar/reflect)

Compile-time type introspection: typeInfo<T>(), fieldNames<T>(), validator<T>().

Operator Overloading

Operators (+, -, *, /, etc.) dispatch to typeclass methods via @op JSDoc tags on typeclass method signatures. When an instance exists, a + b compiles directly to the method call — no wrapper needed.

Typeclasses (@typesugar/typeclass)

Scala 3-style typeclass system with @typeclass, @instance, @derive, and summon().

Zero-Cost Abstractions (@typesugar/specialize)

Eliminate typeclass dictionary passing at compile time for true zero-cost abstractions.

Package Structure

| Package | Description | | ------------------------ | ----------------------------------- | | typesugar | Umbrella package (this one) | | @typesugar/core | Foundation types, registry, context | | @typesugar/transformer | TypeScript transformer | | @typesugar/macros | Built-in macro implementations | | @typesugar/derive | Derive macros | | @typesugar/reflect | Type reflection | | @typesugar/typeclass | Typeclass system | | @typesugar/specialize | Zero-cost specialization | | unplugin-typesugar | Bundler plugins | | @typesugar/vscode | IDE extension |

Bundler Integration

// Vite
import typesugar from "typesugar/vite";

// Webpack
const typesugar = require("typesugar/webpack").default;

// esbuild
import typesugar from "typesugar/esbuild";

// Rollup
import typesugar from "typesugar/rollup";

CLI

# Build with macro expansion
npx typesugar build

# Watch mode
npx typesugar watch

# Type-check only
npx typesugar check

# Show expanded output
npx typesugar expand src/file.ts

API Reference

Re-exported from @typesugar/core

All core types: MacroKind, MacroContext, MacroDefinition, etc.

Re-exported Namespaces

• reflect — from @typesugar/reflect
• derive — from @typesugar/derive
• typeclass — from @typesugar/typeclass
• specialize — from @typesugar/specialize

Functions

• registerAllMacros() — Register all built-in macros

License

MIT