English for TinyBase Developers

TinyBase is a small, reactive, in-memory data store for building local-first JavaScript apps — structured like a lightweight relational database, but designed to sync, persist, and drive UI reactivity out of the box. Because it borrows vocabulary from both spreadsheets and relational databases, review conversations need precise terms to stay unambiguous. Here’s the English for talking about it clearly.

---

Stores and Tables

Store — TinyBase’s core object holding all data for an app, organized into tables, plus optional metadata (values) that aren’t tied to any specific row.

“Don’t create a second store for that feature — add another table to the existing store, so everything stays in one reactive graph.”

Table — a named collection of rows within a store, each row identified by a row ID, conceptually similar to a table in a relational database but schema-flexible.

“Each row in that table doesn’t need identical fields — TinyBase doesn’t enforce a rigid schema the way a SQL table would.”

Cell — a single value at the intersection of a row and a column within a table, the smallest unit of data TinyBase tracks changes on.

“You can listen for changes on just that one cell instead of the whole row — that’s the more precise, less wasteful way to wire this up.”

---

Reactivity

Listener — a callback registered on a store, table, row, or cell that fires automatically whenever the corresponding data changes.

“Attach the listener at the row level, not the whole table — right now every row’s UI re-renders whenever any row in the table changes.”

Reactive hook (React) — TinyBase’s React bindings (useCell, useRow, useTable) that subscribe a component to exactly the slice of data it renders, re-rendering only when that slice changes.

“Swap that manual listener plus useState for the useCell hook — it already handles subscribing and re-rendering for you.”

Query (via queries module) — a derived, reactively-updating view over a store’s data, similar to a SQL SELECT, that recomputes automatically as underlying data changes.

“Don’t recompute that filtered list manually on every render — define it as a query once, and let it update reactively.”

---

Persistence and Sync

Persister — the pluggable module responsible for saving a store’s data to and loading it from a specific target — localStorage, IndexedDB, SQLite, or a remote server.

“Swapping from the localStorage persister to the SQLite one didn’t require touching any component — that’s the whole point of the abstraction.”

Synchronizer — the module that keeps a local store in sync with a remote store or other local stores, handling the network layer on top of the persistence layer.

“The data’s saving fine locally — this is a synchronizer issue, not a persister issue, since it’s specifically not reaching the other device.”

Common Mistakes

• Saying “the store isn’t updating” without specifying whether it’s a listener that wasn’t attached, a persister that failed to save, or a synchronizer that failed to sync — three very different bugs.
• Subscribing to an entire table when only a single cell’s changes matter, causing unnecessary re-renders across the UI.
• Treating queries as one-time computations instead of reactive views, then manually re-running them after every data change instead of letting them update automatically.

Practice Exercise

1. Explain, in two sentences, the difference between a store’s persister and its synchronizer to a teammate debugging a sync issue.
2. Write a short PR description for narrowing a table-level listener down to a row-level listener to fix excessive re-renders.
3. Draft a code review comment explaining why a filtered list should be defined as a query instead of recomputed manually on every render.

Related Resources

• English for Electric SQL
• English for RxDB Developers
• English for React Compiler

Navigating Nuance: Beyond Literal Translation

TinyBase’s strength lies not just in its technical architecture – the stores, tables, indexes, and persisters – but in how developers communicate about it. For non-native speakers, mastering professional English vocabulary is crucial for seamless collaboration, effective code reviews, and clear documentation. It’s easy to get bogged down in literal translations; understanding context and employing specific phrasing is where the real skill lies. Consider the difference between saying “the data is incorrect” versus “there’s a discrepancy in the data” – the latter sounds far more professional and invites discussion about the root cause. Similarly, direct translation of technical terms can lead to misunderstandings. Instead of simply stating “optimize this query,” you might say “refactor this query for improved performance.”

A key area where these nuances matter is during code reviews. Receiving a comment like “This index doesn’t seem efficient” isn’t helpful without further explanation. A more constructive response would be, “Could we explore adding a composite index on [column names] to potentially improve query speed? Let’s benchmark both approaches.” Notice the shift in tone – it prompts investigation and collaboration rather than simply pointing out a perceived problem. Similarly, crafting PR descriptions needs careful consideration. Don’t just list changes; articulate why those changes were made and their intended impact. Phrases like “This update enhances data consistency” or “These modifications improve read latency” demonstrate an understanding of the bigger picture.

Furthermore, Slack conversations often require a slightly different register than casual conversation. Using precise terminology demonstrates your expertise and commitment to quality. For example, instead of saying “I fixed it,” you might say, “I’ve resolved the issue by updating the persister configuration.” This subtle shift conveys professionalism and technical understanding. Remember, clear communication isn’t just about conveying information; it’s about building trust and fostering a productive team environment. Focusing on active voice and avoiding overly complex sentence structures also contributes to clarity.

# Example: Using TinyBase CLI to describe the schema change (illustrative)
tinybase schema update --store my_store --table users --operation add index user_id

This command, when discussed in a team setting, could be framed as “We’ve initiated an operation to add an index on the user_id column within the users table of the my_store store. This is intended to optimize queries based on user ID and improve retrieval performance.”