• About
• Getting Started
  • Project templates
  • #HowToThing
  • Blog posts
  • Videos
• Examples & Showcase
  • awesome.thi.ng
  • Generative art projects
• Community, contributing, getting help
  • Wiki
• Projects
  • Latest updates
  • Fundamentals
  • Maths
  • Randomness
  • File / file format / hardware support
  • Iterator, stream & sequence processing
  • Reactive programming
  • Algorithms & data structures
  • Frontend / UI
  • Geometry, image & visualization
  • WebGL / GPGPU
  • Low-level, binary, memory management, interop
  • DSLs
  • Deprecated packages
• Building
  • Building example projects
  • Testing
  • Documentation
  • Extracting code examples from readme files & comments
• 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 199 individual TypeScript libraries/packages/tools and ~180 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 ~180 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).

• 001: FPS counter with moving average
• 002: Sorting an array by potentially CPU-costly sort criteria
• 003: Multiple key states and extracting commands via FSM
• 004: Creating text-based plots to debug & visualize sequential data
• 005: Barnsley fern IFS fractal
• 006: Clustering arbitrary n-dimensional data using K-means
• 007: Converting Google Maps bookmarks to KML
• 008: CSV parsing into structured data & multi-plot SVG dataviz
• 009: 2D canvas drawing & threadLast() dataflow operator
• 010: Basic web app UI/DOM via Zig/WASM and thi.ng/wasm-api
• 011: 2D cellular automata as WebGL2 multi-pass shader pipeline
• 012: Pure CSS image transition/reveal with thi.ng/hiccup-css
• 013: Lisp interpreter using thi.ng/sexpr & thi.ng/defmulti
• 014: A simple browser REPL for a Lispy mini language
• 015: Generative audio synth offline renderer and WAV file export
• 016: Building a reactive Mastodon UI, parsing & transforming API data
• 017: (Re)Constructing the thi.ng logo as 2D signed-distance field
• 018: Topological sorting, creating & visualizing a task dependency graph
• 019: Building a responsive & reactive stacked column layout
• 020: Generating randomized 4-point 2D multicolor gradient maps/images
• 021: Iterative animated convex polygon subdivision & heat map viz
• 022: Quasi-random voronoi lattice generator
• 023: Tag-based Jaccard similarity ranking/filtering using bitfields
• 024: 2.5D hidden line visualization of digital elevation files (DEM)
• 025: Fitting, transforming & plotting 10k data points per frame using SIMD
• 026: Shader meta-programming to generate animated function plots
• 027: Flocking sim with neighborhood queries to visualize proximity
• 028: Randomized, space-filling, nested 2D grid layout generator
• 029: Forth-like DSL & livecoding playground for 2D geometry generation
• 030: Procedural stochastic text generation via custom DSL & parse grammar

Blog posts

• "Of umbrellas, transducers, reactive streams & mushrooms" (ongoing series):
  • Part 1 - Project & series overview
  • Part 2 - HOFs, Transducers, Reducers
  • Part 3 - Convolution, 1D/2D Cellular automata
  • Part 4 - Disjoint Sets, Graph analysis, Signed Distance Fields
• 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):

• Building a web editor for creating/testing parse grammars
• Building a shader graph editor (WebGL, shader AST transpiler, UI)
• Crash course: TypeScript mapped types in action

Examples & Showcase

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

Example screenshots	(small selection)

awesome.thi.ng

Due to other priorities still very much in its infancy & planning stage, but please help to document your own usage of these packages by contributing project information to the awesome.thi.ng repo, which will be used to build a showcase site... Thank you!

Generative art projects

Several generative art projects by Karsten Schmidt on fx(hash) were created exclusively with libraries from this collection.

De/Frag series
Quasiflock	C-SCAPE	ASCII-SCAPE
Bubblemania	Danza (unreleased)	S-TRACE (unreleased)

Community, contributing, getting help

[!NOTE] My Mastodon account is the best place to learn about ongoing developments. This is a multi-purpose account, but you can view #ThingUmbrella tagged posts only and/or subscribe to those via RSS.

Join the discussions here on Github, get in touch via Mastodon or use the issue tracker. If you'd like to contribute in other ways, please first read this document.

In general, we welcome contributions of all kinds (docs, examples, bug fixes, feature requests, financial contributions etc.). You can find a detailed overview for contributors here: CONTRIBUTING.md.

Note: The default branch for this repo is develop and all PRs should be based on this branch. This too means, the README files on this branch might refer to yet-unreleased features or packages. Please use the main branch for viewing the most recently released version(s)!.

Wiki

To date, the wiki has only been updated sporadically, but please be sure to check it out for project-wide glossary, information, cookbooks, useful snippets etc.

Projects

Latest updates

As of: 2024-11-24

Status	Package	Version	Changelog
	@thi.ng/meta-css		changelog

Fundamentals

Project	Version	Changelog	Description
@thi.ng/args		changelog	Declarative & functional CLI arg parsing & coercions
@thi.ng/api		changelog	Common types, decorators, mixins
@thi.ng/bench		changelog	Basic benchmarking helpers
@thi.ng/checks		changelog	Type & value checks
@thi.ng/compare		changelog	Comparators
@thi.ng/compose		changelog	Functional composition helpers
@thi.ng/date		changelog	Date/time iterators, formatters, rounding
@thi.ng/defmulti		changelog	Dynamic multiple dispatch
@thi.ng/distance		changelog	n-D distance metrics & K-nearest neighborhoods
@thi.ng/equiv		changelog	Deep value equivalence checking
@thi.ng/errors		changelog	Custom error types
@thi.ng/expose		changelog	Conditional global variable exposition
@thi.ng/fibers		changelog	Process hierarchies & ops for cooperative multitasking
@thi.ng/hex		changelog	Hex value formatters for U4-64 words
@thi.ng/logger		changelog	Basis infrastructure for arbitrary logging
@thi.ng/memoize		changelog	Function memoization w/ customizable caching
@thi.ng/object-utils		changelog	Plain JS object & map manipulation
@thi.ng/oquery		changelog	Pattern based query engine for JS objects
@thi.ng/parse		changelog	Parser combinators & AST generator/transformer
@thi.ng/paths		changelog	Immutable nested object accessors
@thi.ng/strings		changelog	Higher-order string formatting utils
@thi.ng/system		changelog	Minimal life cycle container for stateful app components
@thi.ng/transclude		changelog	Template engine for text document generation
@thi.ng/units		changelog	Extensible SI unit conversions

Maths

Project	Version	Changelog	Description
@thi.ng/dual-algebra		changelog	Dual number algebra / automatic differentiation
@thi.ng/dsp		changelog	DSP utils, composable signal gens/processors
@thi.ng/fuzzy		changelog	Fuzzy logic primitives & rule inference engine
@thi.ng/intervals		changelog	Open/closed intervals, queries, set ops
@thi.ng/math		changelog	Assorted common math functions & utilities
@thi.ng/matrices		changelog	Matrix operations
@thi.ng/sparse		changelog	Sparse matrix & vector impls
@thi.ng/timestep		changelog	Fixed timestep simulation updates with state interpolation
@thi.ng/vectors		changelog	Fixed & arbitrary-length vector ops

Randomness

Project	Version	Changelog	Description
@thi.ng/colored-noise		changelog	1D colored noise generators
@thi.ng/ksuid		changelog	K-sortable unique identifiers, binary & base-N encoded
@thi.ng/lowdisc		changelog	n-D Low discrepancy sequence generators
@thi.ng/random		changelog	Seedable PRNG implementations, distributions & utilities
@thi.ng/random-fxhash		changelog	PRNG impl & utilities for fxhash projects
@thi.ng/uuid		changelog	Binary & string-based UUID v4 generator

File / file format / hardware support

Project	Version	Changelog	Description
@thi.ng/axidraw		changelog	Minimal, declarative AxiDraw plotter controller
@thi.ng/bencode		changelog	Bencode binary format encoding
@thi.ng/csv		changelog	Customizable CSV parser/object mapper
@thi.ng/dot		changelog	Graphviz DOM & export
@thi.ng/dsp-io-wav		changelog	WAV file format exporter
@thi.ng/file-io		changelog	Assorted file I/O utils for NodeJS
@thi.ng/geom-io-obj		changelog	Wavefront OBJ model parser
@thi.ng/hiccup-css		changelog	CSS from nested JS data structures
@thi.ng/hiccup-html		changelog	Type-checked HTML5 element wrappers for hiccup
@thi.ng/hiccup-html-parse		changelog	HTML parsing & transformation to hiccup format
@thi.ng/hiccup-markdown		changelog	Hiccup-to-Markdown serialization
@thi.ng/hiccup-svg		changelog	hiccup based SVG vocab
@thi.ng/iges		changelog	IGES format geometry serialization
@thi.ng/markdown-table		changelog	Markdown table generator / formatter
@thi.ng/mime		changelog	File extension to MIME type mappings
@thi.ng/msgpack		changelog	Msgpack serialization/deserialization
@thi.ng/pixel-io-geotiff		changelog	GeoTIFF reader support for thi.ng/pixel
@thi.ng/pixel-io-netpbm		changelog	1/8/16/24bit NetPBM image format reader/writer
@thi.ng/pixel-io-pfm		changelog	Portable FloatMap image format reader/writer
@thi.ng/prefixes		changelog	Linked Data, RDF & xmlns prefixes/URLs
@thi.ng/sax		changelog	SAX-like XML parser / transducer
@thi.ng/tangle		changelog	Literate programming utilities

Iterator, stream & sequence processing

Project	Version	Changelog	Description
@thi.ng/csp		changelog	Channel based async ops
@thi.ng/grid-iterators		changelog	2D grid iterator strategies
@thi.ng/seq		changelog	Lisp/Clojure-style sequence abstraction
@thi.ng/transducers		changelog	Composable data transformations
@thi.ng/transducers-async		changelog	Async transducers, reducers & iterators
@thi.ng/transducers-binary		changelog	Binary data related transducers
@thi.ng/transducers-fsm		changelog	Finite state transducer
@thi.ng/transducers-hdom		changelog	Transducer based hdom UI updates
@thi.ng/transducers-patch		changelog	Patch-based, array & object editing
@thi.ng/transducers-stats		changelog	Technical / statistical analysis

Reactive programming

Project	Version	Changelog	Description
@thi.ng/rstream		changelog	Push-based, reactive event stream primitves
@thi.ng/rstream-csp		changelog	Adapter bridge CSP -> rstream
@thi.ng/rstream-dot		changelog	Graphviz visualization of rstream topologies
@thi.ng/rstream-gestures		changelog	Mouse & touch event stream abstraction
@thi.ng/rstream-graph		changelog	Declarative dataflow graph construction
@thi.ng/rstream-log		changelog	Hierarchical structured data logging
@thi.ng/rstream-log-file		changelog	Log-file output handler
@thi.ng/rstream-query		changelog	Triple store & query engine

Algorithms & data structures

Project	Version	Changelog	Description
@thi.ng/adjacency		changelog	Adjacency matrices & graph algorithms
@thi.ng/arrays		changelog	Array utilities
@thi.ng/associative		changelog	Alt Set & Map implementations
@thi.ng/atom		changelog	Immutable value wrappers, views, history
@thi.ng/bitfield		changelog	1D/2D bit field implementations
@thi.ng/bidir-index		changelog	Bi-directional key-value map/index
@thi.ng/buffers		changelog	Generic read/write buffers w/ diff. behaviors
@thi.ng/cache		changelog	In-memory caches / strategies
@thi.ng/cellular		changelog	Highly configurable 1D Cellular automata
@thi.ng/dcons		changelog	Doubly-linked list
@thi.ng/diff		changelog	Array & object diffing
@thi.ng/disjoint-set		changelog	Disjoint Set data structure
@thi.ng/dgraph		changelog	Dependency graph
@thi.ng/ecs		changelog	Entity-Component System
@thi.ng/egf		changelog	Extensible Graph Format
@thi.ng/gp		changelog	Genetic programming helpers / AST gen
@thi.ng/heaps		changelog	Binary & d-ary heap impls
@thi.ng/idgen		changelog	Versioned ID generation / free-list
@thi.ng/k-means		changelog	K-means clustering of n-D data
@thi.ng/ramp		changelog	Parametric, interpolated lookup tables
@thi.ng/quad-edge		changelog	Quad-edge, dual-graph data structure
@thi.ng/resolve-map		changelog	DAG computations & value resolution
@thi.ng/sorted-map		changelog	Sorted map & set datastructure
@thi.ng/sparse-set		changelog	Sparse set datastructure
@thi.ng/trie		changelog	Trie-based map datastructure w/ prefix queries
@thi.ng/vclock		changelog	Vector clock functions / comparators
@thi.ng/zipper		changelog	Immutable tree editing / navigation

Frontend / UI

Project	Version	Changelog	Description
@thi.ng/blurhash		changelog	Fast image blurhash encoder/decoder
@thi.ng/canvas		changelog	Canvas creation & HDPI support helpers
@thi.ng/dl-asset		changelog	Asset/canvas/file download helpers
@thi.ng/emoji		changelog	Bi-directional emoji lookup tables (names/chars)
@thi.ng/hdiff		changelog	String diffing w/ hiccup output (includes CLI)
@thi.ng/hdom		changelog	Hiccup based VDOM & diffing
@thi.ng/hdom-canvas		changelog	hdom adapter for hiccup-canvas
@thi.ng/hdom-components		changelog	hdom based UI components
@thi.ng/hdom-mock		changelog	hdom mock implementation (testing / prototyping)
@thi.ng/hiccup		changelog	S-expression based HTML/XML serialization
@thi.ng/hiccup-canvas		changelog	hiccup interpreter for canvas api
@thi.ng/hiccup-carbon-icons		changelog	IBM Carbon icons in hiccup format
@thi.ng/imgui		changelog	Immediate mode GUI
@thi.ng/interceptors		changelog	Composable event handlers & processor
@thi.ng/meta-css		changelog	CSS framework codegen, transpiler, bundler
@thi.ng/rdom		changelog	Reactive, diff-less, async UI components
@thi.ng/rdom-canvas		changelog	rdom component wrapper for thi.ng/hiccup-canvas
@thi.ng/rdom-components		changelog	Unstyled, customizable component collection
@thi.ng/rdom-forms		changelog	Datadriven HTML form generation
@thi.ng/router		changelog	Customizable browser & non-browser router
@thi.ng/text-canvas		changelog	Text-mode canvas, drawing, tables, charts
@thi.ng/text-format		changelog	Color text formatting w/ ANSI & HTML presets

Geometry, image & visualization

Project	Version	Changelog	Description
@thi.ng/boids		changelog	Configurable n-dimensional boids simulation
@thi.ng/color		changelog	Color conversions, gradients
@thi.ng/color-palettes		changelog	Collection of image-based color palettes
@thi.ng/dgraph-dot		changelog	Dependency graph -> Graphviz
@thi.ng/distance-transform		changelog	Image based distance field generation
@thi.ng/fuzzy-viz		changelog	Visualization, instrumentation for @thi.ng/fuzzy
@thi.ng/geom		changelog	2D only geometry types & ops
@thi.ng/geom-accel		changelog	Spatial indexing data structures
@thi.ng/geom-axidraw		changelog	Shape conversions for AxiDraw pen plotter
@thi.ng/geom-arc		changelog	2D elliptic arc utils
@thi.ng/geom-clip-line		changelog	2D line clipping
@thi.ng/geom-clip-poly		changelog	2D convex polygon clipping
@thi.ng/geom-closest-point		changelog	Closest point helpers
@thi.ng/geom-fuzz		changelog	Fuzzy 2D shape drawing / filling
@thi.ng/geom-hull		changelog	2D convex hull (Graham scan)
@thi.ng/geom-isec		changelog	Point & shape intersection tests
@thi.ng/geom-isoline		changelog	2D contour line extraction
@thi.ng/geom-poly-utils		changelog	2D polygon helpers
@thi.ng/geom-resample		changelog	nD polyline / curve resampling
@thi.ng/geom-sdf		changelog	2D SDF creation, conversions, operators, utilities
@thi.ng/geom-splines		changelog	nD cubic / quadratic spline ops
@thi.ng/geom-subdiv-curve		changelog	nD iterative subdivision curves
@thi.ng/geom-tessellate		changelog	nD convex polygon tessellators
@thi.ng/geom-trace-bitmap		changelog	bitmap image to vector conversion
@thi.ng/geom-voronoi		changelog	2D iterative delaunay/voronoi
@thi.ng/geom-webgl		changelog	thi.ng/geom / WebGL shape conversion & interop
@thi.ng/imago		changelog	Declarative & extensible image processing pipelines
@thi.ng/lsys		changelog	Extensible L-System architecture
@thi.ng/pixel		changelog	Multi-format pixel buffers
@thi.ng/pixel-convolve		changelog	Extensible image convolution & kernel presets
@thi.ng/pixel-dominant-colors		changelog	k-means based dominant colors extraction
@thi.ng/pixel-dither		changelog	Image dithering w/ various algorithm presets
@thi.ng/poisson		changelog	nD Poisson disk sampling
@thi.ng/porter-duff		changelog	Alpha blending / compositing ops
@thi.ng/rasterize		changelog	Shape drawing, filling & rasterization
@thi.ng/scenegraph		changelog	Extensible 2D/3D scenegraph
@thi.ng/simd		changelog	WebAssembly SIMD vector batch processing
@thi.ng/viz		changelog	Declarative & functional data visualization toolkit

WebGL / GPGPU

Project	Version	Changelog	Description
@thi.ng/shader-ast		changelog	AST DSL for x-platform shader code
@thi.ng/shader-ast-glsl		changelog	GLSL code generator
@thi.ng/shader-ast-js		changelog	JS code generator
@thi.ng/shader-ast-optimize		changelog	AST code optimization strategies
@thi.ng/shader-ast-stdlib		changelog	100+ useful AST shader functions
@thi.ng/webgl		changelog	WebGL 1/2 / GPGPU facilities
@thi.ng/webgl-msdf		changelog	MSDF font rendering
@thi.ng/webgl-shadertoy		changelog	Shadertoy-like WebGL setup

Low-level, binary, memory management, interop

Project	Version	Changelog	Description
@thi.ng/base-n		changelog	Arbitrary base-n encoding/decoding with presets
@thi.ng/binary		changelog	Assorted binary / bitwise ops, utilities
@thi.ng/bitstream		changelog	Bitwise input / output streams
@thi.ng/dlogic		changelog	Digital logic ops / constructs
@thi.ng/leb128		changelog	WASM based LEB128 varint encoder / decoder
@thi.ng/malloc		changelog	Raw & typed array memory pool & allocator
@thi.ng/morton		changelog	Z-order-curve / Morton coding
@thi.ng/range-coder		changelog	Binary data Range encoder / decoder
@thi.ng/rle-pack		changelog	Run-length encoding data compression
@thi.ng/soa		changelog	Memory mapped data structures & serialization
@thi.ng/unionstruct		changelog	Wrapper for C-like structs / unions
@thi.ng/vector-pools		changelog	Data structures for memory mapped vectors
@thi.ng/wasm-api		changelog	Modular, extensible JS/WebAssembly bridge API
@thi.ng/wasm-api-bindgen		changelog	Polyglot bindings code generator for C/Zig/TS
@thi.ng/wasm-api-canvas		changelog	WASM-side Canvas2D API bindings
@thi.ng/wasm-api-dom		changelog	WASM-side DOM manipulation
@thi.ng/wasm-api-schedule		changelog	WASM-side delayed code execution/scheduling

DSLs

Project	Version	Changelog	Description
@thi.ng/pointfree		changelog	Stack-based DSL & functional composition
@thi.ng/pointfree-lang		changelog	Forth-like syntax layer for @thi.ng/pointfree
@thi.ng/proctext		changelog	Procedural text generation engine
@thi.ng/sexpr		changelog	S-Expression parser & runtime infrastructure

Deprecated packages

The following packages have been deprecated. Their readmes describe reasons and alternatives:

Project	Version	Changelog	Description
@thi.ng/fsm		changelog	FSM / parser primitives
@thi.ng/geom-api		changelog	Shared types for thi.ng/geom packages
@thi.ng/iterators		changelog	ES6 generators / iterators
@thi.ng/testament		changelog	Minimal test runner

Building

1git clone https://github.com/thi-ng/umbrella.git
2cd umbrella
3
4yarn install
5yarn build

Once the entire mono-repo has been fully built at least once before, individual packages can then be (re)built like so:

1yarn workspace @thi.ng/transducers run build
2
3# or
4
5(cd packages/transducers && yarn build)
6
7# or
8
9(cd packages/transducers && yarn build:esbuild)

Note: The yarn build script alias will also generate TS type declaration files. This step is only needed once in the beginning or if updating the public API of a package. If you're confident it's not needed, using the build:esbuild alias is sufficient and much faster. Also, TS declaration files can be manually rebuilt via build:decl...

Building example projects

Please see the example build instructions in the wiki for further details.

Testing

(Most, but not all packages have tests)

Test for all packages are run via bun.sh.

1# build all packages, then run all tests (in one go)
2yarn test
3
4# only run all tests
5yarn test:only
6
7# or individually
8yarn workspace @thi.ng/rstream run test

Documentation

Autogenerated documentation (using TypeDoc) will be saved under /packages/*/doc/ and is also available at docs.thi.ng.

1yarn doc

Extracting code examples from readme files & comments

All packages in this repo have prepared infrastructure to extract various code examples & snippets from their README files and from comments in the source code. Altogether, there're 800-1000 of them in this repo, but only ~420 have been processed thus far (it's an ongoing time consuming manual process to prepare & check each of them, but work is under way! Please get in touch if you want to help!).

The code extraction is handled via thi.ng/tangle, itself a part of thi.ng/umbrella. You can read more details about this process here:

• Mastodon post #1
• Mastodon post #2
• thi.ng/tangle readme

To extract code blocks as source files from readmes:

1# in the repo root (to process all packages)
2yarn doc:readme
3
4# for a single package only
5(cd packages/<name> && yarn doc:readme)

To extract example code blocks from doc strings (API docs) in source code:

1# in the repo root (to process all packages)
2yarn tool:tangle
3
4# for a single package only
5(cd packages/<name> && yarn tool:tangle)

In all cases, the extracted files will be saved in each package's /export folder and can then be run directly via bun:

1bun packages/arrays/export/topo-sort.ts

Acknowledgements

Maintaining a large monorepo like this requires a lot of infrastructure and I'm grateful for the tooling provided by the following projects to simplify those tasks:

• bun
• esbuild
• html-minifier-terser
• typedoc
• TypeScript
• Vite
• @thi.ng/monopub

License

© 2015 - 2024 Karsten Schmidt // Apache Software License 2.0

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Karsten Schmidt 💻 📖 🚧 💵	Alberto 💻 💡 🐛 🤔 💵	Arthur Carabott 💻 🤔 💡 📝 💵	André Wachter 💻 🤔 🐛	Gavin Cannizzaro 💻 🐛 🤔	Logan Powell 📖 🐛 🤔 💵	Marcin Ignac 🐛
arcticnoah 💻	allforabit 🐛 💻 🤔 💵	Yifan Wu 🐛 📖	stwind 💻 🐛	evilive 💻	Bnaya Peretz 💻 🐛 🤔	oljeger 🐛
Nik Shevchenko 🐛 💻	Matei Adriel 💻 🐛 🤔	Pierre Grimaud 📖	Matt Huebert 💵	Raphael Saunier 💵	Eric Ihli 💵	David Pham 💵
TBD 🐛 🤔	Pedro Henriques dos Santos Teixeira 💵	Jamie Owen 💻 🐛	Robert Kesteson 🐛 💻	Chancy Kennedy 💵	Jarred Sumner 🐛	Jamie Slome 🐛 🛡️
d3v53c 🐛 🛡️	Jannis Pohlmann 🐛	Shakthi Prasad G S 🐛 💻	Robin Gower 🐛	Michael Latzoni 🐛	Z Yin 🐛	Damien Seguin 🐛 💻
Rui Gil 🐛	Ja|nz 💻 🚇 🚧	Tyler Freeman 🐛 💻	blackhuman 🐛	David Negstad 💻	Muhammad Ridho 🐛 💻	MarcusWagberg 💻
Masashi Yoshikawa 🐛	Guido Schmidt 🐛 💵	tsukamotohideki 💵	Dave Meehan 💻 🤔	Aurélien Bottazini 🐛	Alex 🐛 💵	Ross Cairns 💵
Ruslan Prakapchuk 💵	Jarrod Davis 💵	Nicolas Lebrun 💡	Dawid Górny 💵	Michael Reitzenstein 💵	Sam Nosenzo 💵	Igor Loskutov 💻 🤔
Yury 💻 🤔 💵	Jean-Frédéric Faust 💻 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!