|
| 1 | +<p>This file follows the <a href="https://agents.md/">agents.md</a> 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.</p><h2 id="overview">Overview</h2><p><strong>TinyBase</strong> 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.</p><ul><li><strong>Website</strong>: <a href="https://tinybase.org">https://tinybase.org</a></li><li><strong>Repository</strong>: <a href="https://github.com/tinyplex/tinybase">https://github.com/tinyplex/tinybase</a></li><li><strong><a href="https://tinybase.org/guides/how-tinybase-is-built/documentation/">Documentation</a></strong>: <a href="https://tinybase.org/api/">https://tinybase.org/api/</a></li><li><strong>License</strong>: MIT</li><li><strong>Author</strong>: James Pearce (@jamesgpearce)</li></ul><h2 id="core-concepts">Core Concepts</h2><h3 id="data-store">Data <a href="https://tinybase.org/api/the-essentials/creating-stores/store/"><code>Store</code></a></h3><p>TinyBase provides two types of data structures:</p><ul><li><strong><a href="https://tinybase.org/api/store/type-aliases/store/tables/"><code>Tables</code></a></strong>: Tabular data organized as <a href="https://tinybase.org/api/store/type-aliases/store/table/"><code>Table</code></a> → <a href="https://tinybase.org/api/store/type-aliases/store/row/"><code>Row</code></a> → <a href="https://tinybase.org/api/store/type-aliases/store/cell/"><code>Cell</code></a> (similar to relational databases)</li><li><strong><a href="https://tinybase.org/api/store/type-aliases/store/values/"><code>Values</code></a></strong>: Simple key-value pairs for application state</li></ul><p>Both can coexist in the same <a href="https://tinybase.org/api/the-essentials/creating-stores/store/"><code>Store</code></a> and support optional schemas with type enforcement.</p><h3 id="reactivity">Reactivity</h3><p>The library implements a fine-grained reactive system where you can listen to changes at any level:</p><ul><li>Entire store changes</li><li><a href="https://tinybase.org/api/store/type-aliases/store/table/"><code>Table</code></a>/value additions or removals</li><li><a href="https://tinybase.org/api/store/type-aliases/store/row/"><code>Row</code></a> changes within a table</li><li>Individual cell or value changes</li></ul><p>Listeners fire automatically when data changes, enabling efficient UI updates that only re-render affected components.</p><h3 id="synchronization"><a href="https://tinybase.org/guides/synchronization/">Synchronization</a></h3><p>TinyBase includes native CRDT (Conflict-free Replicated Data Type) support via the <a href="https://tinybase.org/api/mergeable-store/interfaces/mergeable/mergeablestore/"><code>MergeableStore</code></a>, allowing deterministic synchronization across multiple clients and servers using Hybrid Logical Clocks for causality tracking.</p><h2 id="key-features">Key Features</h2><h3 id="data-management">Data Management</h3><ul><li><strong><a href="https://tinybase.org/guides/schemas/">Schemas</a></strong>: Optional TypeScript-inferred schemas for type safety</li><li><strong><a href="https://tinybase.org/api/indexes/interfaces/indexes/indexes/"><code>Indexes</code></a></strong>: Fast lookups by cell values with slice-based grouping</li><li><strong><a href="https://tinybase.org/api/queries/interfaces/queries/queries/"><code>Queries</code></a></strong>: SQL-like query engine (select, join, filter, group) without actual SQL</li><li><strong><a href="https://tinybase.org/api/relationships/interfaces/relationships/relationships/"><code>Relationships</code></a></strong>: Define foreign-key relationships between tables</li><li><strong><a href="https://tinybase.org/api/metrics/interfaces/metrics/metrics/"><code>Metrics</code></a></strong>: Built-in aggregations (sum, avg, min, max)</li><li><strong><a href="https://tinybase.org/api/checkpoints/interfaces/checkpoints/checkpoints/"><code>Checkpoints</code></a></strong>: Undo/redo functionality with branching support</li></ul><h3 id="persistence"><a href="https://tinybase.org/guides/persistence/">Persistence</a></h3><p>Multiple storage backends supported via Persisters:</p><ul><li><strong>Browser</strong>: LocalStorage, SessionStorage, IndexedDB, OPFS</li><li><strong>Databases</strong>: SQLite (Bun, WASM, sqlite3), PostgreSQL, PGlite, Turso (libSQL)</li><li><strong>Third-party</strong>: ElectricSQL, PowerSync, CR-SQLite</li><li><strong>Cloud</strong>: PartyKit, <a href="https://tinybase.org/guides/integrations/cloudflare-durable-objects/">Cloudflare Durable Objects</a></li><li><strong>Files</strong>: Node.js file system</li><li><strong>CRDT</strong>: Yjs, Automerge integration</li><li><strong>React Native</strong>: MMKV, SQLite</li></ul><h3 id="synchronization"><a href="https://tinybase.org/guides/synchronization/">Synchronization</a></h3><p>Synchronizers enable real-time data sync:</p><ul><li>WebSocket (client and server)</li><li>BroadcastChannel (same-origin tabs)</li><li>Local (in-memory for testing)</li><li>Custom transports (extensible)</li></ul><h3 id="react-integration">React Integration</h3><p>Optional <code>ui-react</code> module provides:</p><ul><li><strong>Hooks</strong>: <code>useCell</code>, <code>useRow</code>, <code>useTable</code>, <code>useTables</code>, <code>useValue</code>, etc.</li><li><strong>Components</strong>: Pre-built reactive views for data rendering</li><li><strong>Context</strong>: Multi-store support with ID-based contexts</li><li><strong>DOM Components</strong>: <code>ui-react-dom</code> with interactive tables</li><li><strong>Inspector</strong>: Developer tools overlay for debugging</li></ul><h2 id="architecture"><a href="https://tinybase.org/guides/how-tinybase-is-built/architecture/">Architecture</a></h2><h3 id="modular-design">Modular Design</h3><p>TinyBase uses a modular architecture where each feature is an independent module that can be imported separately:</p> |
| 2 | + |
| 3 | +``` |
| 4 | +tinybase # Core store module |
| 5 | +tinybase/indexes # Indexing |
| 6 | +tinybase/queries # Query engine |
| 7 | +tinybase/relationships # Relationships |
| 8 | +tinybase/metrics # Aggregations |
| 9 | +tinybase/checkpoints # Undo/redo |
| 10 | +tinybase/mergeable-store # CRDT support |
| 11 | +tinybase/persisters/persister-* # Storage backends |
| 12 | +tinybase/synchronizers/synchronizer-* # Sync transports |
| 13 | +tinybase/ui-react # React hooks |
| 14 | +tinybase/ui-react-dom # React DOM components |
| 15 | +tinybase/ui-react-inspector # DevTools |
| 16 | +``` |
| 17 | + |
| 18 | +<h3 id="type-system">Type System</h3><p>Strong TypeScript support with:</p><ul><li>Generic types that infer from schemas</li><li>Conditional types for schema-aware APIs</li><li>Mapped types for compile-time validation</li><li>Type-safe hooks and components</li></ul><h3 id="build-system">Build System</h3><ul><li><strong>Gulp</strong>: Build orchestration</li><li><strong>TypeScript</strong>: Source language with strict mode</li><li><strong>Rollup</strong>: Bundling (implied)</li><li><strong>ESM</strong>: Primary module format</li><li><strong>Tree-shaking</strong>: Aggressive optimization for minimal bundles</li></ul><h2 id="development">Development</h2><h3 id="prerequisites">Prerequisites</h3><ul><li>Node.js >= 23.10.0</li><li>npm >= 10.9.2</li></ul><h3 id="setup">Setup</h3> |
| 19 | + |
| 20 | +```bash |
| 21 | +git clone https://github.com/tinyplex/tinybase.git |
| 22 | +cd tinybase |
| 23 | +npm install |
| 24 | +``` |
| 25 | + |
| 26 | +<h3 id="common-commands">Common Commands</h3> |
| 27 | + |
| 28 | +```bash |
| 29 | +npm run compileAndTestUnit # Compile and run unit tests |
| 30 | +npm run testUnitFast # Quick test iteration |
| 31 | +npm run lint # Run ESLint |
| 32 | +npm run spell # Spell check |
| 33 | +npm run preCommit # Full pre-commit check |
| 34 | +npm run compileDocs # Generate API documentation |
| 35 | +npm run serveDocs # Preview documentation locally |
| 36 | +``` |
| 37 | + |
| 38 | +<h3 id="testing"><a href="https://tinybase.org/guides/how-tinybase-is-built/testing/">Testing</a></h3><ul><li><strong>Framework</strong>: Vitest</li><li><strong>Coverage</strong>: 100% required (enforced)</li><li><strong>Types</strong>: Unit, performance, end-to-end, production</li><li><strong>Environment</strong>: happy-dom (unit), puppeteer (e2e)</li></ul><h3 id="code-style">Code Style</h3><ul><li><strong>ESLint</strong>: Enforced with strict rules</li><li><strong>Prettier</strong>: Automatic formatting</li><li><strong>Max line length</strong>: 80 characters</li><li><strong>Quotes</strong>: Single quotes (template literals allowed)</li><li><strong>Semicolons</strong>: Required</li><li><strong>Object spacing</strong>: No spaces in braces <code>{key: value}</code></li></ul><h2 id="project-structure">Project Structure</h2> |
| 39 | + |
| 40 | +``` |
| 41 | +tinybase/ |
| 42 | +├── src/ # Source code |
| 43 | +│ ├── @types/ # TypeScript declarations |
| 44 | +│ ├── store/ # Core store implementation |
| 45 | +│ ├── indexes/ # Indexing module |
| 46 | +│ ├── queries/ # Query engine |
| 47 | +│ ├── relationships/ # Relationships module |
| 48 | +│ ├── metrics/ # Metrics module |
| 49 | +│ ├── checkpoints/ # Checkpoints module |
| 50 | +│ ├── mergeable-store/ # CRDT implementation |
| 51 | +│ ├── persisters/ # Storage backends |
| 52 | +│ ├── synchronizers/ # Sync transports |
| 53 | +│ ├── ui-react/ # React hooks |
| 54 | +│ ├── ui-react-dom/ # React DOM components |
| 55 | +│ ├── ui-react-inspector/ # DevTools |
| 56 | +│ └── common/ # Shared utilities |
| 57 | +├── test/ # Tests |
| 58 | +│ ├── unit/ # Unit tests |
| 59 | +│ ├── perf/ # Performance tests |
| 60 | +│ ├── e2e/ # End-to-end tests |
| 61 | +│ └── prod/ # Production build tests |
| 62 | +├── docs/ # Generated documentation |
| 63 | +├── dist/ # Build output |
| 64 | +├── site/ # Documentation site source |
| 65 | +├── gulpfile.mjs # Build configuration |
| 66 | +├── vitest.config.ts # Test configuration |
| 67 | +├── eslint.config.js # Linting rules |
| 68 | +└── tsconfig.json # TypeScript config |
| 69 | +``` |
| 70 | + |
| 71 | +<h2 id="contributing">Contributing</h2><p>Contributions are welcome! This is a spare-time project, so response times may vary.</p><p><strong>Requirements</strong>:</p><ol><li>Follow the Prettier and ESLint configurations</li><li>Maintain 100% test coverage</li><li>Update documentation for API changes</li><li>Add examples for new features</li></ol><p><strong>Process</strong>:</p><ol><li>Fork the repository</li><li>Create a feature branch</li><li>Make your changes with tests</li><li>Run <code>npm run preCommit</code> to verify</li><li>Submit a pull request</li></ol><p>See <a href="CONTRIBUTING.md">CONTRIBUTING.md</a> for details.</p><h2 id="community">Community</h2><ul><li><strong>Discord</strong>: <a href="https://discord.com/invite/mGz3mevwP8">https://discord.com/invite/mGz3mevwP8</a></li><li><strong>Discussions</strong>: <a href="https://github.com/tinyplex/tinybase/discussions">https://github.com/tinyplex/tinybase/discussions</a></li><li><strong>Issues</strong>: <a href="https://github.com/tinyplex/tinybase/issues">https://github.com/tinyplex/tinybase/issues</a></li><li><strong>Bluesky</strong>: <a href="https://bsky.app/profile/tinybase.bsky.social">https://bsky.app/profile/tinybase.bsky.social</a></li><li><strong>Twitter/X</strong>: <a href="https://x.com/tinybasejs">https://x.com/tinybasejs</a></li></ul><h2 id="use-cases">Use Cases</h2><p>TinyBase is ideal for:</p><ul><li><strong>Local-first applications</strong>: Apps that work offline and sync later</li><li><strong>Real-time collaboration</strong>: Multi-user applications with CRDT sync</li><li><strong>Reactive UIs</strong>: Applications requiring fine-grained reactivity</li><li><strong>Mobile apps</strong>: React Native apps with local storage</li><li><strong>Edge computing</strong>: Cloudflare Workers, Durable Objects</li><li><strong>Progressive Web Apps</strong>: Offline-capable web applications</li><li><strong>Games</strong>: Real-time state management with undo/redo</li><li><strong>Data dashboards</strong>: Reactive data visualization</li></ul><h2 id="performance">Performance</h2><ul><li>Tiny bundle sizes (5.3kB - 11.7kB depending on features)</li><li>Zero runtime dependencies</li><li>Efficient change detection and listener notification</li><li>Memory pooling for ID generation</li><li>Tree-shakeable modular design</li><li>Optimized for bundle size and runtime performance</li></ul><h2 id="related-projects">Related Projects</h2><ul><li><strong>Synclets</strong>: Generic synchronization library (<a href="https://synclets.org">https://synclets.org</a>)</li><li><strong>TinyWidgets</strong>: Widget toolkit built on TinyBase (<a href="https://tinywidgets.org">https://tinywidgets.org</a>)</li><li><strong>TinyTick</strong>: Reactive ticker tape component (<a href="https://tinytick.org">https://tinytick.org</a>)</li></ul><h2 id="license">License</h2><p>MIT License - see <a href="LICENSE">LICENSE</a> file for details.</p><hr><p><strong>Note for AI Agents</strong>: TinyBase uses unique patterns including utility function wrappers (e.g., <code>arrayForEach</code>, <code>mapGet</code>, <code>objHas</code>) instead of native methods for consistency and tree-shaking. Always use factory functions (<code>createStore</code>, <code>createIndexes</code>, etc.) with builder pattern chaining. Maintain 100% test coverage and follow the strict 80-character line length. See <code>.github/copilot-instructions.md</code> for detailed coding patterns.</p> |
0 commit comments