arrowbase 0.1.1

package/MIGRATING.md

@@ -0,0 +1,238 @@
+# MIGRATING.md — from @tanstack/db to ArrowBase
+
+ArrowBase targets the same public API shape as `@tanstack/db`, but stores rows in
+Arrow-style column buffers. Most app code can switch imports first, then opt into
+columnar-specific persistence, IPC, and indexing features later.
+
+## Quick migration checklist
+
+1. Change imports from `@tanstack/db` to `arrowbase`.
+2. Add an ArrowBase schema and `capacity` for every root collection.
+3. Keep `getKey`, mutation handlers, transactions, optimistic actions, live query
+   builders, local-only helpers, and local-storage helpers the same shape.
+4. Run the parity gates: `pnpm typecheck`, `pnpm test`, `pnpm test:differential`,
+   `pnpm test:golden`, and `pnpm bench:vs-tanstack`.
+5. Check [COMPATIBILITY.md](./COMPATIBILITY.md) if an import touches a less common
+   helper or type alias.
+
+## Side-by-side snippets
+
+### 1. Local-only collection
+
+TanStack DB:
+
+```ts
+import { createCollection, localOnlyCollectionOptions } from '@tanstack/db';
+
+type Todo = {
+  id: number;
+  title: string;
+  done: boolean;
+};
+
+const todos = createCollection(
+  localOnlyCollectionOptions<Todo, number>({
+    id: 'todos',
+    getKey: (todo) => todo.id,
+    initialData: [{ id: 1, title: 'ship', done: false }],
+  }),
+);
+
+await todos.preload();
+```
+
+ArrowBase:
+
+```ts
+import { createCollection, defineSchema, localOnlyCollectionOptions } from 'arrowbase';
+
+type Todo = {
+  __id: number;
+  title: string;
+  done: boolean;
+};
+
+const todoSchema = defineSchema({
+  name: 'todos',
+  columns: {
+    __id: { type: 'uint32' },
+    title: { type: 'utf8' },
+    done: { type: 'bool' },
+  },
+});
+
+const todos = createCollection(
+  localOnlyCollectionOptions<Todo, number>({
+    id: 'todos',
+    schema: todoSchema,
+    capacity: 10_000,
+    getKey: (todo) => todo.__id,
+    initialData: [{ __id: 1, title: 'ship', done: false }],
+  }),
+);
+
+await todos.preload();
+```
+
+Key difference: ArrowBase needs a compiled column schema and fixed `capacity`.
+Use `__id` when you want the native primary-key fast path; custom keys still work
+through `getKey` for TanStack-shaped APIs.
+
+### 2. Mutations and transactions
+
+TanStack DB:
+
+```ts
+import { createTransaction } from '@tanstack/db';
+
+const tx = createTransaction({
+  mutationFn: async ({ transaction }) => {
+    await api.save(transaction.mutations);
+  },
+});
+
+tx.mutate(() => {
+  todos.insert({ id: 2, title: 'docs', done: false });
+  todos.update(1, (draft) => {
+    draft.done = true;
+  });
+});
+
+await tx.isPersisted.promise;
+```
+
+ArrowBase:
+
+```ts
+import { createTransaction } from 'arrowbase';
+
+const tx = createTransaction({
+  mutationFn: async ({ transaction }) => {
+    await api.save(transaction.mutations);
+  },
+});
+
+tx.mutate(() => {
+  todos.insert({ __id: 2, title: 'docs', done: false });
+  todos.update(1, (draft) => {
+    draft.done = true;
+  });
+});
+
+await tx.isPersisted.promise;
+```
+
+`ChangeMessage`, `PendingMutation`, rollback, optimistic mutation, and ambient
+transaction shapes match the reference implementation. ArrowBase keeps the same
+callback contracts but writes into column buffers.
+
+### 3. Query builder and aggregates
+
+TanStack DB:
+
+```ts
+import { Query, count, gt, sum } from '@tanstack/db';
+
+const byDone = new Query()
+  .from({ todos })
+  .select(({ todos }) => ({
+    done: todos.done,
+    n: count(todos.id),
+    total: sum(todos.id),
+  }))
+  .where(({ todos }) => gt(todos.id, 0))
+  .groupBy(({ todos }) => todos.done);
+```
+
+ArrowBase:
+
+```ts
+import { Query, count, gt, sum } from 'arrowbase';
+
+const byDone = new Query()
+  .from({ todos })
+  .select(({ todos }) => ({
+    done: todos.done,
+    n: count(todos.__id),
+    total: sum(todos.__id),
+  }))
+  .where(({ todos }) => gt(todos.__id, 0))
+  .groupBy(({ todos }) => todos.done);
+```
+
+The builder surface is compatible. ArrowBase also keeps its native `query()` /
+`run()` API and vectorized `filter()` DSL for hot columnar paths.
+
+### 4. Local storage
+
+TanStack DB:
+
+```ts
+import { createCollection, localStorageCollectionOptions } from '@tanstack/db';
+
+const prefs = createCollection(
+  localStorageCollectionOptions({
+    id: 'prefs',
+    storageKey: 'app:prefs',
+    getKey: (row) => row.id,
+  }),
+);
+```
+
+ArrowBase:
+
+```ts
+import { createCollection, defineSchema, localStorageCollectionOptions } from 'arrowbase';
+
+const prefsSchema = defineSchema({
+  name: 'prefs',
+  columns: {
+    __id: { type: 'uint32' },
+    name: { type: 'utf8' },
+    value: { type: 'utf8' },
+  },
+});
+
+const prefs = createCollection(
+  localStorageCollectionOptions({
+    id: 'prefs',
+    schema: prefsSchema,
+    capacity: 1_000,
+    storageKey: 'app:prefs',
+    getKey: (row) => row.__id,
+  }),
+);
+```
+
+ArrowBase local storage persists the same logical collection state and exposes
+`clearStorage`, `getStorageSize`, and `acceptMutations` utilities. The storage
+record is columnar snapshot data rather than plain row JSON unless you provide a
+custom parser.
+
+## Common pitfalls
+
+- **Capacity is explicit.** ArrowBase collections allocate typed column buffers
+  up front. Pick a headroom value and add app-level rollover/compaction if the
+  collection can exceed it.
+- **Schema first.** You must map row fields to ArrowBase column types. `utf8`,
+  `dict_utf8`, `binary`, `list`, and `struct` are available for richer rows.
+- **Primary-key naming.** Native examples use `__id`. If an existing app uses
+  `id`, either rename during migration or keep `getKey: (row) => row.id` and add
+  a numeric `__id` for columnar PK storage.
+- **BigInt ↔ Number.** Safe-range numeric join keys are normalized so `int64` and
+  `uint32` keys can match. Outside the safe integer range, keep both sides as
+  `bigint` to avoid precision loss.
+- **floating-point aggregate tolerance.** ArrowBase uses stable summation for
+  `sum`/`avg`. Results can differ from the reference in the last few bits; compare
+  with a tolerance rather than strict stringified floats.
+- **Soft deletes.** ArrowBase can preserve tombstones internally and omit them
+  from public rows. Use `includeSoftDeleted` only when the app intentionally
+  renders tombstones.
+- **Browser SharedArrayBuffer.** Browser use needs COOP/COEP headers. Node and
+  worker-thread usage do not need extra headers.
+
+## Compatibility source of truth
+
+[COMPATIBILITY.md](./COMPATIBILITY.md) is generated from the enumerated
+`@tanstack/db@0.6.5` export list. For this parity release it is all green:
+289/289 exports reviewed and accepted under the tolerances above.