This file follows the agents.md specification for AI agent context. If you're a human reading this, it provides a comprehensive overview of the TinyBase project for AI assistants working with the codebase.

TinyBase is a reactive data store and sync engine for local-first applications. It is a TypeScript library that provides a reactive, in-memory data store with a powerful synchronization engine. It's designed for building local-first applications that work offline and sync across devices. The library is exceptionally small (5.3kB-11.7kB), has zero runtime dependencies, and maintains 100% test coverage.

• Website: https://tinybase.org
• Repository: https://github.com/tinyplex/tinybase
• Documentation: https://tinybase.org/api/
• License: MIT
• Author: James Pearce (@jamesgpearce)

TinyBase provides two types of data structures:

• Tables: Tabular data organized as Table → Row → Cell (similar to relational databases)
• Values: Simple key-value pairs for application state

Both can coexist in the same Store and support optional schemas with type enforcement.

The library implements a fine-grained reactive system where you can listen to changes at any level:

• Entire store changes
• Table/value additions or removals
• Row changes within a table
• Individual cell or value changes

Listeners fire automatically when data changes, enabling efficient UI updates that only re-render affected components.

TinyBase includes native CRDT (Conflict-free Replicated Data Type) support via the MergeableStore, allowing deterministic synchronization across multiple clients and servers using Hybrid Logical Clocks for causality tracking.

• Schemas: Optional TypeScript-inferred schemas for type safety
• Indexes: Fast lookups by cell values with slice-based grouping
• Queries: SQL-like query engine (select, join, filter, group) without actual SQL
• Relationships: Define foreign-key relationships between tables
• Metrics: Built-in aggregations (sum, avg, min, max)
• Checkpoints: Undo/redo functionality with branching support

Multiple storage backends supported via Persisters:

• Browser: LocalStorage, SessionStorage, IndexedDB, OPFS
• Databases: SQLite (Bun, WASM, sqlite3), PostgreSQL, PGlite, Turso (libSQL)
• Third-party: ElectricSQL, PowerSync, CR-SQLite
• Cloud: PartyKit, Cloudflare Durable Objects
• Files: Node.js file system
• CRDT: Yjs, Automerge integration
• React Native: MMKV, SQLite

Synchronizers enable real-time data sync:

• WebSocket (client and server)
• BroadcastChannel (same-origin tabs)
• Local (in-memory for testing)
• Custom transports (extensible)

Optional ui-react module provides:

• Hooks: useCell, useRow, useTable, useTables, useValue, etc.
• Components: Pre-built reactive views for data rendering
• Context: Multi-store support with ID-based contexts
• DOM Components: ui-react-dom with interactive tables
• Inspector: Developer tools overlay for debugging

TinyBase uses a modular architecture where each feature is an independent module that can be imported separately:

tinybase              # Core store module
tinybase/indexes      # Indexing
tinybase/queries      # Query engine
tinybase/relationships # Relationships
tinybase/metrics      # Aggregations
tinybase/checkpoints  # Undo/redo
tinybase/mergeable-store # CRDT support
tinybase/persisters/persister-* # Storage backends
tinybase/synchronizers/synchronizer-* # Sync transports
tinybase/ui-react     # React hooks
tinybase/ui-react-dom # React DOM components
tinybase/ui-react-inspector # DevTools

Strong TypeScript support with:

• Generic types that infer from schemas
• Conditional types for schema-aware APIs
• Mapped types for compile-time validation
• Type-safe hooks and components

• Gulp: Build orchestration
• TypeScript: Source language with strict mode
• Rollup: Bundling (implied)
• ESM: Primary module format
• Tree-shaking: Aggressive optimization for minimal bundles

• Node.js >= 23.10.0
• npm >= 10.9.2

git clone https://github.com/tinyplex/tinybase.git
cd tinybase
npm install

npm run compileAndTestUnit  # Compile and run unit tests
npm run testUnitFast        # Quick test iteration
npm run lint                # Run ESLint
npm run spell               # Spell check
npm run preCommit           # Full pre-commit check
npm run compileDocs         # Generate API documentation
npm run serveDocs           # Preview documentation locally

• Framework: Vitest
• Coverage: 100% required (enforced)
• Types: Unit, performance, end-to-end, production
• Environment: happy-dom (unit), puppeteer (e2e)

• ESLint: Enforced with strict rules
• Prettier: Automatic formatting
• Max line length: 80 characters
• Quotes: Single quotes (template literals allowed)
• Semicolons: Required
• Object spacing: No spaces in braces {key: value}

tinybase/
├── src/                    # Source code
│   ├── @types/            # TypeScript declarations
│   ├── store/             # Core store implementation
│   ├── indexes/           # Indexing module
│   ├── queries/           # Query engine
│   ├── relationships/     # Relationships module
│   ├── metrics/           # Metrics module
│   ├── checkpoints/       # Checkpoints module
│   ├── mergeable-store/   # CRDT implementation
│   ├── persisters/        # Storage backends
│   ├── synchronizers/     # Sync transports
│   ├── ui-react/          # React hooks
│   ├── ui-react-dom/      # React DOM components
│   ├── ui-react-inspector/ # DevTools
│   └── common/            # Shared utilities
├── test/                  # Tests
│   ├── unit/             # Unit tests
│   ├── perf/             # Performance tests
│   ├── e2e/              # End-to-end tests
│   └── prod/             # Production build tests
├── docs/                  # Generated documentation
├── dist/                  # Build output
├── site/                  # Documentation site source
├── gulpfile.mjs          # Build configuration
├── vitest.config.ts      # Test configuration
├── eslint.config.js      # Linting rules
└── tsconfig.json         # TypeScript config

Contributions are welcome! This is a spare-time project, so response times may vary.

Requirements:

1. Follow the Prettier and ESLint configurations
2. Maintain 100% test coverage
3. Update documentation for API changes
4. Add examples for new features

Process:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run npm run preCommit to verify
5. Submit a pull request

See CONTRIBUTING.md for details.

• Discord: https://discord.com/invite/mGz3mevwP8
• Discussions: https://github.com/tinyplex/tinybase/discussions
• Issues: https://github.com/tinyplex/tinybase/issues
• Bluesky: https://bsky.app/profile/tinybase.bsky.social
• Twitter/X: https://x.com/tinybasejs

TinyBase is ideal for:

• Local-first applications: Apps that work offline and sync later
• Real-time collaboration: Multi-user applications with CRDT sync
• Reactive UIs: Applications requiring fine-grained reactivity
• Mobile apps: React Native apps with local storage
• Edge computing: Cloudflare Workers, Durable Objects
• Progressive Web Apps: Offline-capable web applications
• Games: Real-time state management with undo/redo
• Data dashboards: Reactive data visualization

• Tiny bundle sizes (5.3kB - 11.7kB depending on features)
• Zero runtime dependencies
• Efficient change detection and listener notification
• Memory pooling for ID generation
• Tree-shakeable modular design
• Optimized for bundle size and runtime performance

• Synclets: Generic synchronization library (https://synclets.org)
• TinyWidgets: Widget toolkit built on TinyBase (https://tinywidgets.org)
• TinyTick: Reactive ticker tape component (https://tinytick.org)

MIT License - see LICENSE file for details.

Note for AI Agents: TinyBase uses unique patterns including utility function wrappers (e.g., arrayForEach, mapGet, objHas) instead of native methods for consistency and tree-shaking. Always use factory functions (createStore, createIndexes, etc.) with builder pattern chaining. Maintain 100% test coverage and follow the strict 80-character line length. See .github/copilot-instructions.md for detailed coding patterns.

TinyBase has a sophisticated documentation system that generates the website from source code and markdown files.

1. Type Definitions (src/@types/*/): TypeScript .d.ts files contain the API type definitions. Never add comments directly to .d.ts files.

2. Documentation Files (src/@types/*/docs.js): Companion docs.js files sit alongside .d.ts files. Use /// convention to document types and functions. These are stitched together at build time to generate documentation.

3. Guide Files (site/guides/*/*.md): Markdown files in the site/guides/ directory, organized by topic (basics, schemas, persistence, etc.). These are source files for guides on the website.

4. Generated Files: /releases.md and /readme.md in the root are GENERATED from /site/guides/16_releases.md and /site/home/index.md. Never edit the generated files directly.

TinyBase has automated tests that validate all inline code examples in documentation:

npx vitest run ./test/unit/documentation.test.ts --retry=0

How it works:

• Extracts all code blocks from markdown files and docs.js files
• Concatenates all examples from each file together
• Parses and executes them to ensure they work
• This means examples in the same file share scope

Critical constraints:

• Don't redeclare variables across examples in the same file
• First example can declare const store = createStore(), subsequent examples reuse it
• Include necessary imports in examples that use them
• Avoid async operations in examples unless necessary
• Keep examples simple and focused

Common pitfalls:

• ❌ Declaring const store multiple times in the same file
• ❌ Using undefined functions (forgot import statement)
• ✅ First example: const store = createStore()
• ✅ Later examples: store.setCell(...) (reuses existing store)

1. API Documentation: Edit docs.js file next to the type definition
2. Guide Content: Edit markdown files in /site/guides/
3. Release Notes: Edit /site/guides/16_releases.md (not /releases.md)
4. Always run documentation tests after changes to verify examples work