arrowbase 0.1.1

package/RELEASE_NOTES.md

@@ -0,0 +1,68 @@
+# Release notes — @tanstack/db parity
+
+Version: **v0.1.1**
+
+Compatibility: 294/294 exports ✅
+
+## Summary
+
+This release positions ArrowBase as a columnar Arrow store with an
+`@tanstack/db`-compatible API. The public surface has been reviewed against
+`@tanstack/db@0.6.16`, the compatibility catalog is all green, and migration docs
+now show side-by-side replacements for common TanStack DB usage.
+
+## Highlights
+
+- Publishes six verified ESM entry points with TypeScript declarations and npm
+  provenance: `arrowbase`, `tanstack`, `react`, `arrow`, `idb`, and `broadcast`.
+- Ships the 294/294 compatibility catalog against `@tanstack/db@0.6.16`, plus
+  exact public-export, operator-manifest, differential, and golden tests.
+- Adds columnar incremental live-query backends, spatial indexes, GeoArrow IPC,
+  optimistic transactions, persistence, and cross-tab synchronization.
+- Hosts the correctness-gated City Ops playground on GitHub Pages, with desktop
+  and mobile end-to-end coverage.
+- Keeps the published tarball focused on runtime output and consumer docs.
+
+## Migration
+
+Most callers can start by changing imports from `@tanstack/db` to `arrowbase`.
+Collection construction also needs an ArrowBase schema and explicit `capacity` so
+rows can be stored in fixed column buffers. See [MIGRATING.md](./MIGRATING.md)
+for side-by-side snippets and pitfalls.
+
+Documented tolerances:
+
+- BigInt/Number join keys normalize only in the safe integer range.
+- Floating-point aggregate comparisons should use numeric tolerance.
+- ArrowBase is fixed-capacity; choose capacity headroom per collection.
+
+## Benchmarks
+
+Run:
+
+```sh
+pnpm bench
+pnpm bench:vs-tanstack
+```
+
+`pnpm bench` remains the regression guard for ArrowBase hot paths.
+`pnpm bench:vs-tanstack` compares aggregate scan throughput and best-effort
+memory footprint against the installed `@tanstack/db` reference. Latest local
+validation measured aggregate scan at 39.084ms for `@tanstack/db` vs 15.343ms
+for ArrowBase, with ArrowBase at 0.15× the measured memory footprint.
+
+## Validation checklist
+
+Before tagging:
+
+```sh
+pnpm release:verify
+pnpm check
+pnpm playground:check
+pnpm playground:e2e
+pnpm build
+pnpm verify:package-exports
+```
+
+If any gate fails, do not tag. Fix the gap, regenerate `COMPATIBILITY.md` if the
+surface changed, then rerun the full ritual.

package/dist/arrow.d.ts

@@ -0,0 +1,93 @@
+import * as Arrow from 'apache-arrow';
+import { C as Collection } from './collection-DGlKgOGi.js';
+
+/**
+ * Apache Arrow IPC export/import adapter.
+ *
+ * Optional subpath (`arrowbase/arrow`). `apache-arrow` is an optional
+ * peerDep — install it separately if you need IPC interop:
+ *
+ *     pnpm add apache-arrow
+ *
+ * This module converts between an ArrowBase {@link Collection} and an
+ * Arrow IPC byte stream (or file). ArrowBase owns its own in-memory
+ * layout (ranged offsets, SAB-backed), which is deliberately not
+ * byte-compatible with Arrow's dense offsets format. Export here
+ * therefore materializes rows and rebuilds an Arrow Table via
+ * `apache-arrow`'s builders — correct and simple, not zero-copy.
+ *
+ * ### Type mapping
+ *
+ * | ArrowBase            | arrow-js                     |
+ * |----------------------|------------------------------|
+ * | bool                 | Bool                         |
+ * | int8/16/32           | Int8/16/32                   |
+ * | int64                | Int64 (BigInt64)             |
+ * | uint8/16/32          | Uint8/16/32                  |
+ * | uint64               | Uint64 (BigUint64)           |
+ * | float32/64           | Float32/Float64              |
+ * | utf8                 | Utf8                         |
+ * | dict_utf8            | Dictionary<Int32, Utf8>      |
+ * | binary               | Binary                       |
+ * | list<T>              | List<map(T)>                 |
+ * | struct<fields>       | Struct<map(fields)>          |
+ *
+ * ### Internal columns
+ *
+ * By default `__deleted` is stripped on export (soft-deleted rows are
+ * also removed from the output) and `__id` is preserved as a plain
+ * uint32. Pass `{ includeInternalColumns: true }` to keep `__deleted`.
+ */
+
+interface ExportArrowOptions {
+    /**
+     * 'stream' (default) produces the Arrow IPC stream format
+     * (schema + record batches). 'file' wraps it in the random-access
+     * file format with a footer.
+     */
+    format?: 'stream' | 'file';
+    /**
+     * If false (default), soft-deleted rows are skipped and `__deleted`
+     * is omitted from the Arrow schema. If true, all rows are exported
+     * and `__deleted` is included as a bool column.
+     */
+    includeInternalColumns?: boolean;
+    /**
+     * Dynamically resolved apache-arrow module (for callers that must
+     * control module loading, e.g., ESM + bundler edge cases). Most
+     * callers should leave this undefined — we will import lazily.
+     */
+    arrow?: typeof Arrow;
+}
+interface ImportArrowOptions {
+    /**
+     * Row capacity to allocate for the rehydrated collection.
+     * Defaults to the Arrow Table's `numRows`.
+     */
+    capacity?: number;
+    /**
+     * Override the schema name. Defaults to `'arrow'`.
+     */
+    name?: string;
+    /** See {@link ExportArrowOptions.arrow}. */
+    arrow?: typeof Arrow;
+}
+/**
+ * Export a collection as Arrow IPC bytes. Returns a `Uint8Array`; copy
+ * `.buffer` if you need an `ArrayBuffer`.
+ */
+declare function exportArrowIPC(collection: Collection, options?: ExportArrowOptions): Promise<Uint8Array>;
+/**
+ * Rebuild a collection from Arrow IPC bytes. The Arrow schema is
+ * translated into an ArrowBase schema; types that have no ArrowBase
+ * equivalent (e.g., Timestamp, Decimal) will throw.
+ */
+declare function importArrowIPC(buf: Uint8Array | ArrayBuffer, options?: ImportArrowOptions): Promise<Collection>;
+/**
+ * Build an Arrow `Table` from a collection without serializing it.
+ * Exposed for users who want to stream multiple collections into the
+ * same IPC writer, or who want to cross-check column-level data.
+ */
+declare function exportArrowTable(collection: Collection, options?: ExportArrowOptions): Promise<Arrow.Table>;
+
+export { type ExportArrowOptions, type ImportArrowOptions, exportArrowIPC, exportArrowTable, importArrowIPC };