tinybase 7.0.0-beta.1 → 7.0.0-beta.3

package/agents.md

@@ -0,0 +1,343 @@
+# Agents Guide
+
+This file follows the [agents.md](https://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.
+
+## Overview
+
+**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)
+
+## Core Concepts
+
+### Data Store
+
+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.
+
+### Reactivity
+
+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.
+
+### Synchronization
+
+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.
+
+## Key Features
+
+### Data Management
+
+- **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
+
+### Persistence
+
+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
+
+### Synchronization
+
+Synchronizers enable real-time data sync:
+
+- WebSocket (client and server)
+- BroadcastChannel (same-origin tabs)
+- Local (in-memory for testing)
+- Custom transports (extensible)
+
+### React Integration
+
+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
+
+## Architecture
+
+### Modular Design
+
+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
+```
+
+### Type System
+
+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
+
+### Build System
+
+- **Gulp**: Build orchestration
+- **TypeScript**: Source language with strict mode
+- **Rollup**: Bundling (implied)
+- **ESM**: Primary module format
+- **Tree-shaking**: Aggressive optimization for minimal bundles
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 23.10.0
+- npm >= 10.9.2
+
+### Setup
+
+```bash
+git clone https://github.com/tinyplex/tinybase.git
+cd tinybase
+npm install
+```
+
+### Common Commands
+
+```bash
+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
+```
+
+### Testing
+
+- **Framework**: Vitest
+- **Coverage**: 100% required (enforced)
+- **Types**: Unit, performance, end-to-end, production
+- **Environment**: happy-dom (unit), puppeteer (e2e)
+
+### Code Style
+
+- **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}`
+
+## Project Structure
+
+```
+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
+```
+
+## Contributing
+
+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](CONTRIBUTING.md) for details.
+
+## Community
+
+- **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
+
+## Use Cases
+
+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
+
+## Performance
+
+- 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
+
+## Related Projects
+
+- **Synclets**: Generic synchronization library (https://synclets.org)
+- **TinyWidgets**: Widget toolkit built on TinyBase (https://tinywidgets.org)
+- **TinyTick**: Reactive ticker tape component (https://tinytick.org)
+
+## License
+
+MIT License - see [LICENSE](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.
+
+## Documentation System
+
+TinyBase has a sophisticated documentation system that generates the website
+from source code and markdown files.
+
+### Documentation Structure
+
+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**.
+
+### Documentation Testing
+
+TinyBase has automated tests that validate all inline code examples in
+documentation:
+
+```bash
+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)
+
+### Adding New Documentation
+
+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

package/checkpoints/index.js

@@ -1,8 +1,13 @@
 const EMPTY_STRING = '';
 
-const isUndefined = (thing) => thing == void 0;
-const ifNotUndefined = (value, then, otherwise) =>
-  isUndefined(value) ? otherwise?.() : then(value);
+const getIfNotFunction =
+  (predicate = isNullish) =>
+  (value, then, otherwise) =>
+    predicate(value) ? otherwise?.() : then(value);
+const isNullish = (thing) => thing == null;
+const isUndefined = (thing) => thing === void 0;
+const isNull = (thing) => thing === null;
+const ifNotUndefined = getIfNotFunction(isUndefined);
 const isArray = (thing) => Array.isArray(thing);
 const size = (arrayOrString) => arrayOrString.length;
 const test = (regex, subject) => regex.test(subject);
@@ -42,7 +47,7 @@ const mapGet = (map, key) => map?.get(key);
 const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
-  isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
+  value === void 0 ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue, hadExistingValue) => {
   if (!collHas(map, key)) {
     mapSet(map, key, getDefaultValue());
@@ -165,7 +170,7 @@ const getListenerFunctions = (getThing) => {
           const index = size(ids);
           if (index == size(path)) {
             listener(thing, ...ids, ...extraArgsGetter(ids));
-          } else if (isUndefined(path[index])) {
+          } else if (isNull(path[index])) {
             arrayForEach(pathGetters[index]?.(...ids) ?? [], (id2) =>
               callWithIds(...ids, id2),
             );
@@ -318,7 +323,7 @@ const createCheckpoints = getCreateFunction(
         ? goBackwardImpl
         : arrayHas(forwardIds, checkpointId)
           ? goForwardImpl
-          : null;
+          : void 0;
       while (!isUndefined(action) && checkpointId != currentId) {
         action();
       }

package/checkpoints/with-schemas/index.js

@@ -1,8 +1,13 @@
 const EMPTY_STRING = '';
 
-const isUndefined = (thing) => thing == void 0;
-const ifNotUndefined = (value, then, otherwise) =>
-  isUndefined(value) ? otherwise?.() : then(value);
+const getIfNotFunction =
+  (predicate = isNullish) =>
+  (value, then, otherwise) =>
+    predicate(value) ? otherwise?.() : then(value);
+const isNullish = (thing) => thing == null;
+const isUndefined = (thing) => thing === void 0;
+const isNull = (thing) => thing === null;
+const ifNotUndefined = getIfNotFunction(isUndefined);
 const isArray = (thing) => Array.isArray(thing);
 const size = (arrayOrString) => arrayOrString.length;
 const test = (regex, subject) => regex.test(subject);
@@ -42,7 +47,7 @@ const mapGet = (map, key) => map?.get(key);
 const mapForEach = (map, cb) =>
   collForEach(map, (value, key) => cb(key, value));
 const mapSet = (map, key, value) =>
-  isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
+  value === void 0 ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue, hadExistingValue) => {
   if (!collHas(map, key)) {
     mapSet(map, key, getDefaultValue());
@@ -165,7 +170,7 @@ const getListenerFunctions = (getThing) => {
           const index = size(ids);
           if (index == size(path)) {
             listener(thing, ...ids, ...extraArgsGetter(ids));
-          } else if (isUndefined(path[index])) {
+          } else if (isNull(path[index])) {
             arrayForEach(pathGetters[index]?.(...ids) ?? [], (id2) =>
               callWithIds(...ids, id2),
             );
@@ -318,7 +323,7 @@ const createCheckpoints = getCreateFunction(
         ? goBackwardImpl
         : arrayHas(forwardIds, checkpointId)
           ? goForwardImpl
-          : null;
+          : void 0;
       while (!isUndefined(action) && checkpointId != currentId) {
         action();
       }

package/common/index.js

@@ -2,14 +2,18 @@ const EMPTY_STRING = '';
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const getIfNotFunction =
+  (predicate = isNullish) =>
+  (value, then, otherwise) =>
+    predicate(value) ? otherwise?.() : then(value);
 const GLOBAL = globalThis;
 const math = Math;
 const mathMax = math.max;
 const mathFloor = math.floor;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
-const isUndefined = (thing) => thing == void 0;
-const ifNotUndefined = (value, then, otherwise) =>
-  isUndefined(value) ? otherwise?.() : then(value);
+const isNullish = (thing) => thing == null;
+const isUndefined = (thing) => thing === void 0;
+const ifNotUndefined = getIfNotFunction(isUndefined);
 
 const arrayForEach = (array, cb) => array.forEach(cb);
 const arrayMap = (array, cb) => array.map(cb);
@@ -38,7 +42,7 @@ const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),
     (uniqueId, number) => uniqueId + encode(number),
-    '',
+    EMPTY_STRING,
   );
 
 const jsonString = JSON.stringify;

package/common/with-schemas/index.js

@@ -2,14 +2,18 @@ const EMPTY_STRING = '';
 const strSplit = (str, separator = EMPTY_STRING, limit) =>
   str.split(separator, limit);
 
+const getIfNotFunction =
+  (predicate = isNullish) =>
+  (value, then, otherwise) =>
+    predicate(value) ? otherwise?.() : then(value);
 const GLOBAL = globalThis;
 const math = Math;
 const mathMax = math.max;
 const mathFloor = math.floor;
 const isInstanceOf = (thing, cls) => thing instanceof cls;
-const isUndefined = (thing) => thing == void 0;
-const ifNotUndefined = (value, then, otherwise) =>
-  isUndefined(value) ? otherwise?.() : then(value);
+const isNullish = (thing) => thing == null;
+const isUndefined = (thing) => thing === void 0;
+const ifNotUndefined = getIfNotFunction(isUndefined);
 
 const arrayForEach = (array, cb) => array.forEach(cb);
 const arrayMap = (array, cb) => array.map(cb);
@@ -38,7 +42,7 @@ const getUniqueId = (length = 16) =>
   arrayReduce(
     getRandomValues(new Uint8Array(length)),
     (uniqueId, number) => uniqueId + encode(number),
-    '',
+    EMPTY_STRING,
   );
 
 const jsonString = JSON.stringify;