@tldraw/utils

Active contributors: Steve Ruiz, Mime Čuvalo, David Sheldrick

Purpose

@tldraw/utils is the shared helper library: collections, throttling, retries, fractional indexing, version registry, perf trackers, and other primitives that don't belong to any one product package.

Directory layout

packages/utils/src/lib/
├── ExecutionQueue.ts        # serial promise queue
├── LruCache.ts
├── PerformanceTracker.ts
├── array.ts                 # 9 KB of array helpers
├── bind.ts                  # @bind decorator-ish
├── cache.ts                 # WeakCache, etc.
├── control.ts               # control-flow helpers (assert, exhaustiveSwitchError, …)
├── debounce.ts
├── error.ts                 # annotateError, Result
├── file.ts                  # FileHelpers
├── function.ts
├── hash.ts                  # hashString, getHashForObject
├── id.ts                    # uniqueId
├── iterable.ts
├── json-value.ts
├── network.ts               # fetch wrapper
├── number.ts
├── object.ts                # 12 KB of object helpers
├── perf.ts
├── reordering.ts            # fractional indexing (IndexKey)
├── retry.ts
├── sort.ts
├── storage.tsx              # LocalStorage hooks
├── stringEnum.ts
├── throttle.ts              # 7 KB
├── timers.ts                # setTimeout/Interval helpers
├── types.ts
├── url.ts
├── value.ts
├── version.ts               # registerTldrawLibraryVersion
├── warn.ts
└── media/                   # image/video helpers

Notable utilities

Helper	File	What it does
IndexKey, getIndexAbove, getIndexBetween, ZERO_INDEX_KEY	reordering.ts	Fractional indexing for ordered lists (used for shape ordering on a page).
throttle, throttleToNextFrame	throttle.ts	Frame-aligned throttling used by the editor render loop.
assert, exhaustiveSwitchError, Result	control.ts, error.ts	Control-flow helpers used everywhere in the runtime.
WeakCache, LruCache	cache.ts, LruCache.ts	Memoization helpers.
FileHelpers	file.ts	Read/write helpers for File / Blob / DataURL.
registerTldrawLibraryVersion	version.ts	Registers a package version so the runtime can detect mismatched packages.
PerformanceTracker	PerformanceTracker.ts	Used by the editor to attribute frame time.

Integration points

• Imported by every other SDK package.
• No runtime dependencies — pure TypeScript helpers.

Related

• Editor managers (PerformanceManager uses PerformanceTracker).