umbrella

thi.ng/umbrella

About
Getting Started
Examples & Showcase
- awesome.thi.ng
- Generative art projects
Community, contributing, getting help
- Wiki
Projects
Building
Acknowledgements
License
Contributors

About

"A collection of functional programming libraries that can be composed together. Unlike a framework, thi.ng is a suite of instruments and you (the user) must be the composer of. Geared towards versatility, not any specific type of music." — @loganpowell via Twitter

Please visit thi.ng for additional information. You might also find the following tools useful to find & explore projects in this vast ecosystem:

thi.ng tag browser

tag-based search on the thi.ng website

repo-wide doc string search

generated API docs

This project is NOT a framework and all packages can be used in isolation.

Not including deprecations, this mono-repository is home to 198 individual TypeScript libraries/packages/tools and ~175 example projects illustrating their usage, currently totalling ~208k SLOC and ~4100 source files... Some of the projects have been in regular development since 2015. The monorepo exists in its current form since January 2018.

Unlike most other large mono-repos this one is not for a single project, but a broad collection of jointly developed, yet independent libraries, tools and general purpose building blocks for the following non-exhaustive list of topics (see package overview below):

Functional programming (ES6 iterators/generators, composition, memoization, transducers, multi-methods)
Reactive programming, stream / transducer based dataflow graphs / pipelines / DOM
Fiber process tree abstraction for ES6 generators (co-routines / cooperative multitasking)
Data structures & data transformations for wide range of use cases (maps, sets, heaps, queues, graphs etc.)
WebAssembly bridge APIs & data structure bindings code generators for multiple target languages (primarily aimed at Zig & C11)
PEG-style functional parser combinators w/ (optional) custom grammar definition language
Customizable HTML & Markdown parsers
2D/3D geometry generation, shape primitives, math, manipulation, intersections, conversions & visualizations
Canvas abstractions, pixel buffers & SVG serialization/conversion
Comprehensive function collection (900+) for nD-vectors and matrices (dense & sparse)
ECS implementations with optional support for strided memory layouts
Semi-declarative WebGL 1/2 abstraction layer
DSL for shader functions defined in TypeScript and cross-compilation to GLSL, JS, VEX etc.
Value-based equivalence (vs. native object identity) and associative data structures (sets, maps)
DSP building blocks: oscillators, noise generators, filters, 1D FFT/IFFT, muxers, rate converters
Immutable data handling, state containers, transacted state updates, Undo-Redo history
Reactive UI component toolkits (DOM-based, canvas-based, immediate-mode, multiple approaches...)
Multi-format, multi-channel pixel buffers (int & float based), conversions, dithering, Porter-Duff alpha-blending operators
Color space/format conversions, matrix based color manipulation, gradient generators, color palettes, dominant color extraction
Date-time abstraction, relative dates, iterators, formatters, math
WebWorker workflow abstractions
Forth-style pointfree DSL for functional composition and DSL development/extension
S-expression parser & runtime (interpreter) infrastructure for custom DSL creation
WASM-based SIMD batch-processing of vector data
Pen-plotter (AxiDraw) toolchain & geometry conversions
Interpolations, math helpers, automatic differentiation (Dual numbers)
etc.

Once more, this project is NOT a framework. There's no turn-key, one-size-fits-all approach and instead the overall design philosophy encourages a mix & match philosophy for key aspects of application design (inside & outside the browser). Customization points are provided wherever useful and only expect certain interfaces/type signatures rather than hard-coded concrete implementations. In many cases presets are provided too.

All packages:

are versioned independently
have auto-generated online documentation at docs.thi.ng
built via esbuild and tested via bun.sh
released via thi.ng/monopub publishing toolchain
distributed as ESM modules (ES2022 syntax) with export maps, TypeScript typings & change logs
highly modular with often only a single function / class (incl. closely related functions) per file to help w/ selective imports and tree shaking
provide re-exports of all their publics for full library imports
have either none or only @thi.ng internal runtime dependencies (w/ very few exceptions! All dependencies are listed in each package readme)
declare public interfaces, enums & types in an api.ts file
licensed under Apache Software License 2.0

Getting started

A common misconception is to think of this repo as single project. It is not! The sheer number and varied nature & purpose of these packages makes it impossible to provide traditional "Getting started" tutorials — there would have to be dozens of them... To compensate, this repo provides ~175 example projects, detailed package readmes (at the very least for all the larger and/or more important ones), as well as hundreds of small usage examples/snippets in doc strings & readme files.

Documentation and changelogs for all packages: docs.thi.ng

If you're unsure about something, please reach out! Any constructive feedback is always highly appreciated!

Project templates

You might find one of the following template repos an useful starting point (only updated sporadically, make sure to update dependencies manually):

tpl-umbrella-basic: Bare-bones template repo for browser-based projects
tpl-umbrella-fxhash: Project template repo for generative art projects on the fx(hash) platform
tpl-umbrella-zig: Minimal browser project template for hybrid TypeScript & Zig (WebAssembly) apps

#HowToThing

Between August-November 2023, #HowToThing was a series of short posts & mini-tutorials on Mastodon, demonstrating a range of different techniques, patterns and use cases from across the thi.ng/umbrella ecosystem. These are not necessarily intro examples, but each one comes with heavily commented code (and often with visual outputs/results).

Blog posts

"Of umbrellas, transducers, reactive streams & mushrooms" (ongoing series):
How to UI in 2018
The Jacob's Ladder of coding

Videos

The following videos have been migrated from YouTube to their new home at makertube.net (more to come):

Examples & Showcase

There's a steadily growing number (~175) of standalone examples of different complexities (often combining functionality from several packages) in the examples directory.

Example screenshots	(small selection)
<a href="https://github.com/thi-ng/umbrella/blob/develop/examples/boid-basics"><img src="./assets/examples/boid-basics.png" width="240"/></a>	<a href="https://github.com/thi-ng/umbrella/blob/develop/examples/imgui"><img src="./assets/imgui/imgui-all.png" width="240"/></a>	<a href="https://github.com/thi-ng/umbrella/blob/develop/examples/shader-ast-raymarch"><img src="./assets/shader-ast/shader-ast-raymarch.jpg" width="240"/></a>
<a href="https://github.com/thi-ng/umbrella/blob/develop/examples/geom-terrain-viz"><img