typesugar

Appearance

Package Reference ​

All typesugar packages organized by category.

Build Infrastructure ​

typesugar ​

Umbrella package including all common packages.

bash
npm install typesugar

Includes: core, derive, reflect, typeclass, specialize.

Inspired by: Umbrella packages (Lodash, Effect)

@typesugar/core ​

Macro registration and types.

bash
npm install @typesugar/core

Exports:

typescript
// Registration
defineExpressionMacro;
defineAttributeMacro;
defineDeriveMacro;
defineTaggedTemplateMacro;
defineTypeMacro;
defineLabeledBlockMacro;

// Types
MacroContext;
MacroDefinition;
DeriveTypeInfo;
ComptimeValue;

// Configuration
config;
cfg;
cfgAttr;

// Diagnostics
DiagnosticBuilder;
DiagnosticDescriptor;
renderDiagnosticCLI;

// Resolution Scope
globalResolutionScope;
isInOptedOutScope;
hasInlineOptOut;

// Import Suggestions
getSuggestionsForSymbol;
getSuggestionsForMethod;

@typesugar/macros ​

Built-in macro implementations. Internal package — most users should import from typesugar or specific feature packages.

bash
npm install @typesugar/macros

Exports:

typescript
// Typeclass System
typeclassRegistry;
instanceRegistry;

// Derive Infrastructure
defineCustomDerive;
defineFieldDerive;
extractTypeInfo;

// Extension Methods
extensionAttribute; // @extension decorator
// "use extension" directive (file-level)

// And many more internal implementations...

Inspired by: Rust macro system, Scala 3 metaprogramming

@typesugar/transformer ​

The TypeScript transformer that expands macros.

bash
npm install --save-dev @typesugar/transformer

Exports:

  • Default export: transformer factory
  • CLI: typesugar command

@typesugar/preprocessor ​

Lexical preprocessor for HKT type syntax (F<A> → Kind<F, A>) plus the shared source-map types used by the transformer pipeline.

bash
npm install --save-dev @typesugar/preprocessor

Exports:

typescript
preprocess();

Inspired by: Zig comptime

unplugin-typesugar ​

Bundler plugins for Vite, Webpack, esbuild, Rollup.

bash
npm install --save-dev unplugin-typesugar

Exports:

typescript
import typesugar from "unplugin-typesugar/vite";
import typesugar from "unplugin-typesugar/webpack";
import typesugar from "unplugin-typesugar/esbuild";
import typesugar from "unplugin-typesugar/rollup";

@typesugar/ts-plugin ​

TypeScript language service plugin for IDE integration.

bash
npm install --save-dev @typesugar/ts-plugin

Enables type-aware transformation, diagnostics, go-to-definition, completions, and hover info for typesugar syntax in any TypeScript editor.

Developer Experience ​

@typesugar/vscode ​

VSCode/Cursor extension (install from marketplace).

  • Syntax highlighting for custom syntax
  • Inline expansion previews
  • Go-to-definition for macro-generated code
  • Error lens integration

@typesugar/eslint-plugin ​

ESLint plugin with processor for typesugar files.

bash
npm install --save-dev @typesugar/eslint-plugin

Exports:

typescript
configs.recommended;
configs.full;
configs.strict;
processor;

@typesugar/prettier-plugin ​

Prettier formatting for custom syntax.

bash
npm install --save-dev @typesugar/prettier-plugin

@typesugar/testing ​

Power assertions, property-based testing, macro testing.

bash
npm install --save-dev @typesugar/testing

Exports:

typescript
assert(); // Power assertion with sub-expression capture
staticAssert(); // Compile-time assertion
typeAssert<T>(); // Type-level assertion
testCases(); // Parameterized tests
forAll(); // Property-based testing
assertSnapshot(); // Source-capturing snapshots

Inspired by: Power Assert (JS), QuickCheck (Haskell), proptest (Rust)

Guide

Standard Library ​

@typesugar/std ​

Standard library extensions: typeclasses, extension methods, pattern matching, do-notation.

bash
npm install @typesugar/std

Exports:

typescript
// Extension methods (import functions, call as methods)
(abs, ceil, floor, sqrt, clamp, isEven, isPrime); // number
(capitalize, titleCase, strip, truncate); // string
(head, tail, chunk, unique, groupBy); // array

// Pattern matching — fluent API (PEP-008)
match(); // Fluent: match(v).case(...).then(...).else(...)
MatchError; // Runtime error when no pattern matches (extends Error, has .value)

// FlatMap for do-notation
FlatMap;
registerFlatMap();

// Standard typeclasses
(Eq, Ord, Show, Hash, Semigroup, Monoid);

// Hash instances and combinators
(hashNumber, hashString, hashBoolean, hashBigInt, hashDate);
(makeHash, hashBy, hashArray);

Inspired by: Scala 3 extension methods, Rust derives, Kotlin stdlib

Extension Methods Guide · Pattern Matching Guide · Do-Notation Guide · Standard Typeclasses Guide

Typeclasses & Derivation ​

@typesugar/typeclass ​

Scala 3-style typeclasses with implicit resolution.

bash
npm install @typesugar/typeclass

Exports:

typescript
typeclass();  // decorator
instance();   // decorator
derive();     // decorator (generates typeclass instances)
summon<T>();
summonAll<...>();
extend();
implicit();   // default parameter marker

Inspired by: Scala 3 typeclasses, Haskell typeclasses

Guide

@typesugar/derive ​

Auto-derive implementations from type structure.

bash
npm install @typesugar/derive

Exports:

typescript
derive(); // decorator
(Eq, Ord, Clone, Debug, Hash, Default, Json, Builder, TypeGuard);
(deriveIgnore, deriveWith);

Inspired by: Rust derive macros

Guide

@typesugar/specialize ​

Zero-cost typeclass specialization.

bash
npm install @typesugar/specialize

Exports:

typescript
specialize();
specialize$();
mono<T>();
inlineCall();

Inspired by: GHC SPECIALIZE pragma, Rust monomorphization

Guide

@typesugar/reflect ​

Compile-time type reflection.

bash
npm install @typesugar/reflect

Exports:

typescript
reflect(); // decorator
typeInfo<T>();
fieldNames<T>();
validator<T>();

Inspired by: Zig @typeInfo, Rust proc_macro

Guide

Syntax Sugar ​

@typesugar/strings ​

String validation macros with compile-time checking.

bash
npm install @typesugar/strings

Exports:

typescript
regex`...`; // tagged template
html`...`; // tagged template
raw`...`; // tagged template
fmt`...`; // tagged template

Guide

Type Safety & Contracts ​

@typesugar/type-system ​

Advanced type system extensions.

bash
npm install @typesugar/type-system

Exports:

typescript
// HKT
($, Kind, _, TypeFunction, ArrayF, PromiseF);

// Newtype
(Newtype, wrap, unwrap, newtypeCtor);

// Refinement
(Refined, refine);
(Positive, NonNegative, Int, Byte, Port);
(NonEmpty, Email, Url, Uuid);

// Vec
Vec;

// Type-level arithmetic
(Add, Sub, Mul, Div, Pow);

Inspired by: Haskell/ML type systems, Scala 3 opaque types

Guide

@typesugar/contracts ​

Design by contract with compile-time verification.

bash
npm install @typesugar/contracts

Exports:

typescript
requires:; // labeled block
ensures:; // labeled block
invariant(); // decorator
old();
assert();
configure();

Inspired by: Eiffel contracts, Coq proofs

Guide

@typesugar/contracts-refined ​

Refinement type integration for contracts.

bash
npm install @typesugar/contracts-refined

Exports:

typescript
registerRefinementPredicate();
getRegisteredPredicates();

Guide

@typesugar/validate ​

Zero-cost validation and schema macros.

bash
npm install @typesugar/validate

Exports:

typescript
is<T>(); // type guard
assert<T>(); // assertion
validate<T>(); // validation with error accumulation
Schema; // schema DSL

Inspired by: Zod, io-ts

Guide

@typesugar/units ​

Type-safe physical units with dimensional analysis.

bash
npm install @typesugar/units

Exports:

typescript
// Unit class with .add(), .sub(), .mul(), .div(), .to(), .scale(), .equals()
Unit;

// Constructors
(meters, kilometers, centimeters, millimeters, feet, inches, miles);
(kilograms, grams, milligrams, pounds);
(seconds, minutes, hours, days, milliseconds);
(metersPerSecond, kilometersPerHour, milesPerHour);
(newtons, joules, kilojoules, watts, kilowatts);
(kelvin, celsius, pascals, kilopascals, atmospheres);
units`...`; // tagged template

// Dimension types
(Length, Mass, Time, Velocity, Force, Energy, Power, Pressure, Temperature);
(MulDimensions, DivDimensions, SameDimensions);

Inspired by: Boost.Units, F# Units of Measure

Guide

Data Structures & Algorithms ​

@typesugar/fp ​

Functional programming data types.

bash
npm install @typesugar/fp

Exports:

typescript
// Option (null-based, zero-cost)
(Option, Some, None);

// Result
(Result, Ok, Err);

// Either
(Either, Left, Right);

// Validated
(Validated, Valid, Invalid);

// IO
IO;

// List
(List, Cons, Nil);

// Typeclasses
(Functor, Applicative, Monad);
(Semigroup, Monoid);
(Eq, Ord, Show);

Inspired by: Scala fp-ts, Haskell Prelude

Guide

@typesugar/hlist ​

Heterogeneous lists with compile-time type tracking.

bash
npm install @typesugar/hlist

Exports:

typescript
hlist();
(head(), tail(), last(), at());
(append(), prepend(), concat(), reverse(), zip());
(labeled(), get(), set(), project(), merge());
(map(), foldLeft(), forEach());

Inspired by: Boost.Fusion, Boost.Hana

Guide

@typesugar/fusion ​

Single-pass iterator fusion and expression templates.

bash
npm install @typesugar/fusion

Exports:

typescript
lazy();
(range(), iterate(), repeat(), generate());
(vec(), add(), sub(), mul(), dot());

Inspired by: Blitz++, Rust iterators

Guide

@typesugar/parser ​

Compile-time parser generation from PEG grammars.

bash
npm install @typesugar/parser

Exports:

typescript
grammar`...`; // tagged template
(literal(), char(), charRange(), regex());
(seq(), alt(), many(), many1(), optional());
(map(), sepBy(), between(), lazy());

Inspired by: Boost.Spirit, PEG.js

Guide

@typesugar/graph ​

Graph algorithms and state machine verification.

bash
npm install @typesugar/graph

Exports:

typescript
(createDigraph(), createGraph());
digraph`...`; // tagged template
(topoSort(), bfs(), dfs(), dijkstra());
(stronglyConnectedComponents(), detectCycles());
(defineStateMachine(), verify());

// GraphLike typeclass
(GraphLike, WeightedGraphLike);
(graphLike, weightedGraphLike);

// Generic algorithms (parameterized over GraphLike + Eq + Hash)
(topoSortG, hasCyclesG, bfsG, dfsG, reachableG, hasPathG, shortestPathG, dijkstraWithG, sccG);

Inspired by: Boost.Graph

Guide

@typesugar/erased ​

Typeclass-based type erasure for heterogeneous collections.

bash
npm install @typesugar/erased

Exports:

typescript
eraseWith();
(showable(), equatable(), showableEq());
(show(), equals(), compare(), hash(), clone());
(widen(), narrow(), hasCapability());

Inspired by: Rust dyn Trait

Guide

@typesugar/codec ​

Versioned codecs with schema evolution.

bash
npm install @typesugar/codec

Exports:

typescript
schema();
createJsonCodec();
createBinaryCodec();
generateMigrations();

Inspired by: serde, Boost.Serialization, Protocol Buffers

Guide

@typesugar/collections ​

Collection typeclasses and hash-based data structures.

bash
npm install @typesugar/collections

Exports:

typescript
// Typeclasses
(IterableOnce, Iterable, Seq, SetLike, MapLike);
(PersistentSetLike, PersistentMapLike, MutableSetLike, MutableMapLike);

// Data structures
(HashSet, HashMap);

// Instances
(arrayIterableOnce, arrayIterable, arraySeq, arraySeqOf);
(nativeSetLike, nativeMutableSetLike, nativeMapLike, nativeMutableMapLike);
(stringIterable, stringSeq);
(hashSetLike, hashMutableSetLike, hashMapLike, hashMutableMapLike);
(mutableSetFor, mutableMapFor);

// Derived operations
(forEach, toArray, find, exists, forAll, count, sum);
(head, last, take, drop, sorted, seqContains);
(union, intersection, difference, isSubsetOf);
(getOrElse, mapValues, filterEntries, mapEntries);

Inspired by: Scala collections, Haskell Data.Set/Data.Map, Rust std::collections

Guide

@typesugar/math ​

Math types and typeclasses.

bash
npm install @typesugar/math

Exports:

typescript
(rational(), complex(), bigDecimal());
(matrix(), det(), matMul(), transpose());
(interval(), mod(), polynomial());
(VectorSpace, InnerProduct, Normed);

Inspired by: Haskell Numeric, Boost.Multiprecision

Guide

@typesugar/mapper ​

Zero-cost object mapping.

bash
npm install @typesugar/mapper

Exports:

typescript
transformInto<S, T>();

Inspired by: Scala Chimney

Guide

@typesugar/symbolic ​

Type-safe symbolic mathematics with AST, rendering, evaluation, calculus, and simplification.

bash
npm install @typesugar/symbolic

Exports:

typescript
// AST construction
var_;
const_;
add;
mul;
pow;
sin;
cos;
ln;

// Calculus
diff;
integrate;
limit;

// Evaluation & rendering
evaluate;
toLatex;
toMathML;
simplify;
solve;

Inspired by: SymPy, Mathematica

Guide

Ecosystem Integrations ​

@typesugar/effect ​

Effect-TS integration.

bash
npm install @typesugar/effect effect

Exports:

typescript
// Service & Layer (primary)
service(); // decorator
layer(); // decorator
layerMake<R>(); // ZIO-style explicit wiring
resolveLayer<R>(); // implicit wiring from import scope
formatDebugTree(); // resolved graph visualization

// Derives
(EffectSchema, EffectEqual, EffectHash);

// Extensions
(EffectExt, OptionExt, EitherExt);

// Typeclass instances
(effectFunctor, effectMonad);

Inspired by: Scala ZIO

Guide

@typesugar/sql ​

Type-safe SQL tagged templates with ConnectionIO.

bash
npm install @typesugar/sql

Exports:

typescript
sql`...`; // tagged template
(Query, Update, Fragment);
ConnectionIO;
Transactor;

Inspired by: Scala Doobie

Guide

Peer Dependencies ​

Most packages have:

  • typescript: >=5.0.0
  • @typesugar/transformer: >=0.1.0 (peer)

Check each package's package.json for specifics.

Released under the MIT License.

Copyright © 2024-present