feat: improve doc

Author: quolpr

README.md

@@ -18,14 +18,14 @@ differs.
 
 It was built to fix the things that hurt when you reach for Redux or MobX or other state management libs in a local-first app:
 
-- **Cheap inserts into sorted data.** Every table is backed by a real B+tree, so
+- **Cheap inserts into sorted data.** Every table index is backed by a real B-tree, so
   inserting into a sorted collection stays `O(log n)` instead of the `O(n)` you
   pay rebuilding (Redux) or shifting (MobX) an array. Ideal for fractional
-  indexing.
+  indexing for local-first apps.
 - **Fine-grained reactivity.** Selectors record exactly which index ranges they
   scanned, so a mutation only re-runs the selectors that overlap it, without
   proxies or `observer()`.
-- **Run the same logic on the backend.** Because a table is just a B-tree, the
+- **Run the same logic on the backend.** Because a table index is just a B-tree, the
   same schema, selectors, and actions run against a persistent store on the
   server (SQLite today). The runtime reads only the rows a selector touches; it
   never loads the whole dataset into memory.
@@ -123,8 +123,6 @@ db.loadTables([tasksTable]);
 ```
 
 ```tsx
-// 5. Use it in React. The list re-renders only when a mutation
-//    touches the range it read.
 import {
   DBProvider,
   useSyncSelector,

TODO.md

@@ -4,6 +4,9 @@ Github:
 Codesandbox:
 1. Add demo
 
+Devtool:
+1. resetcss
+
 Doc:
 1. Fix npm install/doc links
 1. Add performance compare doc

packages/hyperdb-doc/src/content/docs/database/data-types.md

@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-HyperDB stores a fixed set of value types. Every value you write is **normalized**
+HyperDB stores a fixed set of value types. Every value you write is normalized
 against its validator before it reaches the storage driver, which guarantees that
 what comes back out matches your schema.
 
@@ -14,7 +14,7 @@ what comes back out matches your schema.
 | Validator              | TypeScript type  | Notes                                                                 |
 | ---------------------- | ---------------- | --------------------------------------------------------------------- |
 | `v.string()`           | `string`         |                                                                       |
-| `v.number()`           | `number`         | **Finite only** — `NaN`/`Infinity` are rejected                       |
+| `v.number()`           | `number`         | Finite only; `NaN`/`Infinity` are rejected                        |
 | `v.bigint()`           | `bigint`         |                                                                       |
 | `v.boolean()`          | `boolean`        |                                                                       |
 | `v.null()`             | `null`           |                                                                       |
@@ -30,30 +30,30 @@ what comes back out matches your schema.
 
 ### Composite helpers
 
-- `v.partial(objectValidator)` — every field becomes optional.
-- `v.required(objectValidator, keys)` — make listed optional fields required.
-- `v.lazy(() => validator)` — defer resolution, useful for recursion.
+- `v.partial(objectValidator)`: every field becomes optional.
+- `v.required(objectValidator, keys)`: make listed optional fields required.
+- `v.lazy(() => validator)`: defer resolution, useful for recursion.
 
 ## Binary data
 
 `v.arrayBuffer()` accepts an `ArrayBuffer` directly, and also accepts any typed
-array or `DataView` — these are copied into a fresh `ArrayBuffer` during
+array or `DataView`, which are copied into a fresh `ArrayBuffer` during
 normalization. Storage drivers encode binary data appropriately:
 
-- The **SQLite** drivers encode `bigint`, `ArrayBuffer`, and typed-array/data-view
+- The SQLite drivers encode `bigint`, `ArrayBuffer`, and typed-array/data-view
   values around JSON storage.
-- The **IndexedDB** driver uses the same storage encoding and sort-key ordering
+- The IndexedDB driver uses the same storage encoding and sort-key ordering
   as SQLite.
-- The **in-memory** driver stores normalized JS values directly.
+- The in-memory driver stores normalized JS values directly.
 
 ## Indexable values
 
-Not every value can appear in an index. **Indexable** value types are:
+Not every value can appear in an index. Indexable value types are:
 
 - `string`, finite `number`, `bigint`, `boolean`, `null`
 - `ArrayBuffer` and typed-array / `DataView` values
 - `v.literal(...)` of an indexable primitive
-- `v.union(...)` where **every** variant is indexable
+- `v.union(...)` where every variant is indexable
 - `v.optional(...)` of an indexable value
 
 If you try to build an index on a non-indexable column (an `array`, `object`,
@@ -63,18 +63,18 @@ If you try to build an index on a non-indexable column (an `array`, `object`,
 
 `v.any()` accepts arbitrary JSON-like structures but still enforces HyperDB's
 storage rules: numbers must be finite, object keys cannot be empty or start with
-`$`, and `undefined` is rejected inside arrays. Use it sparingly — you lose the
+`$`, and `undefined` is rejected inside arrays. Use it sparingly, since you lose the
 type information and the index-ability that explicit validators give you.
 
 ## Working with `undefined`
 
-`undefined` is **not a storable value**. The rules:
+`undefined` is not a storable value. The rules:
 
-- An **optional object field** may be omitted. Writing `{ note: undefined }` is
-  normalized to the field being absent — it round-trips as missing, not as
+- An optional object field may be omitted. Writing `{ note: undefined }` is
+  normalized to the field being absent, so it round-trips as missing, not as
   `undefined`.
-- `undefined` is **not allowed inside an array** (`[1, undefined]` is rejected).
-- `undefined` is **not allowed as a record value**.
+- `undefined` is not allowed inside an array (`[1, undefined]` is rejected).
+- `undefined` is not allowed as a record value.
 
 If you need to represent "explicitly empty", model it with `v.null()` instead of
 relying on `undefined`.

packages/hyperdb-doc/src/content/docs/database/indexes.md

@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-Every query runs **through an index** — HyperDB never does a full table scan.
+Every query runs through an index, so HyperDB never does a full table scan.
 Indexes are declared on the table and determine which filters and orderings are
 possible.
 
@@ -22,7 +22,7 @@ defineTable("tasks", {
   .index("byState", ["state"], { type: "hash" }); // single-column hash
 ```
 
-The built-in `byId` hash index on `id` is always present — you never declare it.
+The built-in `byId` hash index on `id` is always present, so you never declare it.
 
 ### B-tree vs. hash
 
@@ -33,8 +33,8 @@ The built-in `byId` hash index on `id` is always present — you never declare i
 | `order("asc" \| "desc")`      | ✅               | ❌                      |
 | Composite (multi-column)      | ✅               | ❌ (exactly one column) |
 
-Reach for a **hash** index when you only ever look up a column by exact value;
-use a **btree** index when you need ranges, ordering, or multi-column keys.
+Reach for a hash index when you only ever look up a column by exact value;
+use a btree index when you need ranges, ordering, or multi-column keys.
 
 ### What can be indexed
 
@@ -48,9 +48,9 @@ A composite B-tree index stores rows ordered by its columns left to right, like
 phone book ordered by `(lastName, firstName)`. That ordering dictates which
 filters are valid. Two rules:
 
-1. **Equality prefix.** You may constrain a column only if **every** column
+1. Equality prefix. You may constrain a column only if every column
    before it in the index is constrained by equality (`eq`).
-2. **One trailing range.** After the equality prefix, you may apply a single
+2. One trailing range. After the equality prefix, you may apply a single
    range (`gt`/`gte`/`lt`/`lte`) on the next column. You cannot range on a column
    and then constrain a later one.
 
@@ -75,19 +75,19 @@ For `byProjectOrder` = `["projectId", "orderToken"]`:
 The query builder validates bounds when the query is constructed and will throw
 for:
 
-- **A non-prefix column** — using a column without `eq` on all preceding columns
+- A non-prefix column, using a column without `eq` on all preceding columns
   (`Cannot use column 'X' without specifying eq conditions for all preceding
 columns`).
-- **`eq` mixed with a range on the same column** — e.g. `eq("c", 1).gt("c", 0)`
+- `eq` mixed with a range on the same column, e.g. `eq("c", 1).gt("c", 0)`
   (`Conflicting conditions for column 'c'`).
-- **Two equality conditions on one column** (`Multiple equality conditions`).
-- **A column that isn't in the index** (`Column 'X' not found in index`).
-- **No usable conditions** at all.
+- Two equality conditions on one column (`Multiple equality conditions`).
+- A column that isn't in the index (`Column 'X' not found in index`).
+- No usable conditions at all.
 
 ## Ordering with indexes
 
 Because a B-tree index is physically ordered, `order("asc")` returns rows in the
-index's key order and `order("desc")` returns them reversed — no separate sort
+index's key order and `order("desc")` returns them reversed, with no separate sort
 step. Choose your index column order to match how you want to read the data. For
 the `byProjectOrder` index, tasks come back ordered by `orderToken` within a
 project for free.

packages/hyperdb-doc/src/content/docs/database/reading-data.md

@@ -1,11 +1,11 @@
 ---
 title: Reading Data
-description: Query data with selectors and the selectFrom builder — filters, ordering, limits, and first results.
+description: Query data with selectors and the selectFrom builder, covering filters, ordering, limits, and first results.
 sidebar:
   order: 3
 ---
 
-You read data through **selectors** — generator functions that describe what to
+You read data through selectors, generator functions that describe what to
 read. Inside a selector you build queries with `selectFrom` and `yield*` them.
 Selectors can call other selectors but can never write; the runtime rejects any
 mutation emitted from a read.
@@ -36,14 +36,14 @@ Object-form selectors accept:
 | `args`        | Validator map for the single args object                                                               |
 | `handler`     | Generator function that does the reading                                                               |
 | `skipTrace`   | `true`, or `{ rootTrace, childTrace }` to skip tracing                                                 |
-| `memoization` | `{ root?, selfChild? }` cache controls — see [Selectors & Reactivity](/database/selectors-reactivity/) |
+| `memoization` | `{ root?, selfChild? }` cache controls (see [Selectors & Reactivity](/database/selectors-reactivity/)) |
 
 You can also wrap a bare generator function instead of using the object form.
 
 ## The query builder
 
-`selectFrom(table, indexName)` returns a builder. You always query **through an
-index** — there are no table scans. The builder is immutable: each method returns
+`selectFrom(table, indexName)` returns a builder. You always query through an
+index, so there are no table scans. The builder is immutable: each method returns
 a new builder.
 
 ```ts
@@ -73,13 +73,13 @@ Available comparisons:
 | `q.lt(col, val)`  | less than             |
 | `q.lte(col, val)` | less than or equal    |
 
-Comparisons apply to **index columns**, and which combinations are legal depends
+Comparisons apply to index columns, and which combinations are legal depends
 on the column order of the index. The rules (equality prefix + one trailing
 range) are explained in detail in [Indexes](/database/indexes/).
 
 ### OR queries
 
-To express an OR, return an **array** of query branches from `where`, or use the
+To express an OR, return an array of query branches from `where`, or use the
 `or(...)` helper. Each branch is scanned and the results are combined.
 
 ```ts
@@ -96,7 +96,7 @@ selectFrom(tasksTable, "byProjectState").where((q) => [
 ]);
 ```
 
-This is the idiom for batched lookups — for example fetching many rows by id in
+This is the idiom for batched lookups, for example fetching many rows by id in
 one query:
 
 ```ts
@@ -106,7 +106,7 @@ selectFrom(tasksTable, "byId").where((q) => ids.map((id) => q.eq("id", id)));
 ### `order` and `limit`
 
 ```ts
-.order("asc")   // or "desc" — follows the index's key order
+.order("asc")   // or "desc"; follows the index's key order
 .limit(50)      // cap the number of returned rows
 ```
 
@@ -117,7 +117,7 @@ reverse. Hash indexes are for equality lookups and do not provide ordering.
 
 ### Many rows
 
-`yield*`-ing a query returns an **array** of rows:
+`yield*`-ing a query returns an array of rows:
 
 ```ts
 const tasks =

packages/hyperdb-doc/src/content/docs/database/schemas.md

@@ -5,13 +5,13 @@ sidebar:
   order: 1
 ---
 
-A schema describes the **shape of your rows** and the **indexes** you can query
+A schema describes the shape of your rows and the indexes you can query
 by. Schemas are defined with `defineTable` and the `v` validator library, and
 they double as the source of truth for TypeScript types.
 
 ## Defining a table
 
-Every table has a name and a set of fields. A table **must** have a string `id`
+Every table has a name and a set of fields. A table must have a string `id`
 field. HyperDB automatically creates a built-in hash index named `byId` on `id`.
 
 ```ts
@@ -31,7 +31,7 @@ export const tasksTable = defineTable("tasks", {
 export type Task = ExtractSchema<typeof tasksTable>;
 ```
 
-`ExtractSchema<typeof table>` gives you the row type — here, `Task` is:
+`ExtractSchema<typeof table>` gives you the row type. Here, `Task` is:
 
 ```ts
 type Task = {
@@ -72,15 +72,15 @@ v.any();
 
 There are also helpers for deriving object validators:
 
-- `v.partial(objectValidator)` — make every field optional.
-- `v.required(objectValidator, ["a", "b"])` — make the listed optional fields
+- `v.partial(objectValidator)`: make every field optional.
+- `v.required(objectValidator, ["a", "b"])`: make the listed optional fields
   required again.
-- `v.lazy(() => validator)` — defer evaluation, for recursive shapes.
-- `v.pass<T>()` — accept any value as type `T` without normalizing it.
+- `v.lazy(() => validator)`: defer evaluation, for recursive shapes.
+- `v.pass<T>()`: accept any value as type `T` without normalizing it.
 
 ## Standalone validators and types
 
-Validators are useful beyond tables — for example to type selector/action
+Validators are useful beyond tables, for example to type selector/action
 arguments or intermediate data. Use `Infer` to get the TypeScript type of any
 validator.
 
@@ -99,7 +99,7 @@ type Filter = Infer<typeof filterSchema>;
 ## Tagged unions
 
 `defineTable` also accepts a standalone object or union validator instead of a
-field map. This is how you model a table whose rows are a **tagged union** of
+field map. This is how you model a table whose rows are a tagged union of
 several shapes:
 
 ```ts
@@ -129,14 +129,14 @@ defineTable("tasks", {
   .index("byTitle", ["title"], { type: "hash" }); // hash
 ```
 
-- **`btree`** (the default) supports equality _and_ range queries, ordering, and
+- `btree` (the default) supports equality _and_ range queries, ordering, and
   composite (multi-column) keys.
-- **`hash`** supports equality lookups only and must have **exactly one column**.
+- `hash` supports equality lookups only and must have exactly one column.
 
 Index columns must:
 
 - exist in the table schema, and
-- be **indexable** value types (`string`, finite `number`, `bigint`, `boolean`,
+- be indexable value types (`string`, finite `number`, `bigint`, `boolean`,
   `null`, `ArrayBuffer`/typed-array, and compatible literals, unions, and
   optionals of those).
 
@@ -146,7 +146,7 @@ immediately. For how composite indexes are queried, see
 
 ## The `undefined` rule
 
-Stored values can never contain `undefined`. Optional **object fields** may be
+Stored values can never contain `undefined`. Optional object fields may be
 omitted entirely, and `{ field: undefined }` is normalized to "missing". But
 `undefined` is not allowed inside arrays or as a record value. See
 [Data Types](/database/data-types/#working-with-undefined) for the details.