arrowbase 0.1.1

package/dist/tanstack.js

@@ -0,0 +1,191 @@
+// src/pushdown.ts
+function pushDown(expr, knownColumns) {
+  if (!expr) return null;
+  return translate(expr, knownColumns);
+}
+function translate(expr, knownColumns) {
+  switch (expr.type) {
+    case "val":
+      return null;
+    case "ref":
+      return toRefPredicate(expr, knownColumns);
+    case "func": {
+      const f = expr;
+      return translateFunc(f, knownColumns);
+    }
+    default:
+      return null;
+  }
+}
+function translateFunc(f, knownColumns) {
+  const name = f.name;
+  const args = f.args;
+  if (name === "eq" && args.length === 2) {
+    return translateEq(args[0], args[1], knownColumns);
+  }
+  if (name === "and" || name === "or") {
+    const children = [];
+    for (const arg of args) {
+      const c = translate(arg, knownColumns);
+      if (!c) return null;
+      children.push(c);
+    }
+    if (name === "and") {
+      return (row) => children.every((c) => c(row));
+    }
+    return (row) => children.some((c) => c(row));
+  }
+  if (name === "not" && args.length === 1) {
+    const inner = translate(args[0], knownColumns);
+    if (!inner) return null;
+    return (row) => !inner(row);
+  }
+  return null;
+}
+function translateEq(a, b, knownColumns) {
+  let ref = null;
+  let lit = null;
+  if (a.type === "ref" && b.type === "val") {
+    ref = a;
+    lit = b;
+  } else if (a.type === "val" && b.type === "ref") {
+    ref = b;
+    lit = a;
+  } else {
+    return null;
+  }
+  const col = resolveRef(ref, knownColumns);
+  if (!col) return null;
+  const literal = lit.value;
+  return (row) => row[col] === literal;
+}
+function toRefPredicate(ref, knownColumns) {
+  const col = resolveRef(ref, knownColumns);
+  if (!col) return null;
+  return (row) => row[col] === true;
+}
+function resolveRef(ref, knownColumns) {
+  if (!ref.path || ref.path.length === 0) return null;
+  let col;
+  if (ref.path.length === 1) {
+    col = ref.path[0];
+  } else if (ref.path.length === 2) {
+    col = ref.path[1];
+  } else {
+    return null;
+  }
+  if (!knownColumns.has(col)) return null;
+  return col;
+}
+
+// src/tanstack.ts
+function toTanstackCollection(abColl, options = {}) {
+  const id = options.id ?? `arrowbase:${abColl.schema.name}`;
+  const pkName = abColl.schema.primaryKey;
+  const includeSoftDeleted = options.includeSoftDeleted ?? false;
+  const sync = {
+    sync: (params) => {
+      const { begin, write, commit, markReady, truncate } = params;
+      begin();
+      for (const row of abColl.rows({ includeSoftDeleted })) {
+        write({ value: row, type: "insert" });
+      }
+      commit();
+      markReady();
+      const unsubscribe = abColl.subscribe((event) => {
+        if (event.op === "compact" || event.op === "rollback") {
+          begin();
+          truncate();
+          for (const row of abColl.rows({ includeSoftDeleted })) {
+            write({ value: row, type: "insert" });
+          }
+          commit();
+          return;
+        }
+        translateEvent(abColl, event, pkName, includeSoftDeleted, {
+          begin,
+          write,
+          commit
+        });
+      });
+      return {
+        cleanup: () => unsubscribe(),
+        // Push-down hook: when TanStack DB requests a subset with an
+        // eq/and/or/not filter over known columns, we translate it to
+        // an ArrowBase predicate and emit only matching rows. This
+        // module keeps behaviour correct regardless — TanStack DB also
+        // re-evaluates the predicate against materialized rows, so an
+        // over-approximation here just means extra work, never wrong
+        // results.
+        loadSubset: (opts) => {
+          const knownCols = new Set(abColl.columnNames());
+          const predicate = pushDown(opts.where, knownCols);
+          if (!predicate) {
+            return true;
+          }
+          begin();
+          for (const row of abColl.rows({ includeSoftDeleted })) {
+            if (!predicate(row)) continue;
+            write({ value: row, type: "update" });
+          }
+          commit();
+          return true;
+        }
+      };
+    },
+    // Full row snapshots keep the adapter stateless. TanStack DB's
+    // default is 'partial'; we override because ArrowBase always
+    // produces a full row on read.
+    rowUpdateMode: "full"
+  };
+  return {
+    id,
+    getKey: (item) => item[pkName],
+    sync,
+    onInsert: async ({ transaction }) => {
+      for (const m of transaction.mutations) {
+        abColl.insert(m.modified);
+      }
+    },
+    onUpdate: async ({ transaction }) => {
+      for (const m of transaction.mutations) {
+        const key = m.key;
+        abColl.update(key, m.changes);
+      }
+    },
+    onDelete: async ({ transaction }) => {
+      for (const m of transaction.mutations) {
+        abColl.delete(m.key);
+      }
+    }
+  };
+}
+function translateEvent(abColl, event, _pkName, includeSoftDeleted, port) {
+  const key = event.rowId;
+  if (event.op === "delete") {
+    if (!includeSoftDeleted) {
+      port.begin();
+      port.write({ key, type: "delete" });
+      port.commit();
+      return;
+    }
+    const row2 = abColl.get(key);
+    if (!row2) return;
+    port.begin();
+    port.write({ value: row2, type: "update" });
+    port.commit();
+    return;
+  }
+  const row = abColl.get(key);
+  if (!row) return;
+  port.begin();
+  port.write({
+    value: row,
+    type: event.op === "insert" ? "insert" : "update"
+  });
+  port.commit();
+}
+
+export { toTanstackCollection };
+//# sourceMappingURL=tanstack.js.map
+//# sourceMappingURL=tanstack.js.map

package/dist/tanstack.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pushdown.ts","../src/tanstack.ts"],"names":["row"],"mappings":"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","file":"tanstack.js","sourcesContent":["/**\n * TanStack DB → ArrowBase push-down: translate a `BasicExpression<boolean>`\n * into an ArrowBase predicate `(row) => boolean` when possible.\n *\n * v1 recognises:\n *   - eq(prop, literal)      → row[col] === lit\n *   - eq(literal, prop)      → row[col] === lit\n *   - and(a, b, ...)         → every translated arg\n *   - or(a, b, ...)          → some translated arg\n *   - not(a)                 → !translated arg\n *\n * Any expression containing a node type that is not one of the above\n * causes the translator to return `null`. Callers should treat `null`\n * as \"not pushable\" and either fall back to full scan or let TanStack\n * DB's own evaluator run against the materialized rows.\n *\n * `PropRef` paths are taken as `[alias, column]` when length === 2, or\n * `[column]` when length === 1. Anything deeper (nested struct fields)\n * is not supported in v1.\n */\n\nimport type { RowValue } from './collection/collection.js';\n\n// TanStack DB's IR lives under the `IR` namespace on the package root.\n// We only depend on the types at compile time; runtime type-checks use\n// the `type` field on each node so no runtime IR import is needed.\nimport type { IR } from '@tanstack/db';\n\ntype BasicExpression<T = unknown> = IR.BasicExpression<T>;\ntype PropRef<T = unknown> = IR.PropRef<T>;\ntype ValueExpr<T = unknown> = IR.Value<T>;\ntype Func<T = unknown> = IR.Func<T>;\n\nexport type Predicate = (row: RowValue) => boolean;\n\n/**\n * Attempt to translate a TanStack DB expression into an ArrowBase\n * predicate. Returns `null` if the expression is not pushable.\n */\nexport function pushDown(\n  expr: BasicExpression<boolean> | undefined,\n  knownColumns: ReadonlySet<string>,\n): Predicate | null {\n  if (!expr) return null;\n  return translate(expr, knownColumns);\n}\n\nfunction translate(\n  expr: BasicExpression,\n  knownColumns: ReadonlySet<string>,\n): Predicate | null {\n  switch (expr.type) {\n    case 'val':\n      // Literal at the root of a where doesn't make sense; TanStack\n      // would have short-circuited.\n      return null;\n    case 'ref':\n      // A ref at the root means boolean-column projection\n      // (e.g. where(row.active)). Supported.\n      return toRefPredicate(expr as PropRef, knownColumns);\n    case 'func': {\n      const f = expr as Func;\n      return translateFunc(f, knownColumns);\n    }\n    default:\n      return null;\n  }\n}\n\nfunction translateFunc(\n  f: Func,\n  knownColumns: ReadonlySet<string>,\n): Predicate | null {\n  const name = f.name;\n  const args = f.args;\n\n  if (name === 'eq' && args.length === 2) {\n    return translateEq(args[0]!, args[1]!, knownColumns);\n  }\n\n  if (name === 'and' || name === 'or') {\n    const children: Predicate[] = [];\n    for (const arg of args) {\n      const c = translate(arg, knownColumns);\n      if (!c) return null;\n      children.push(c);\n    }\n    if (name === 'and') {\n      return (row) => children.every((c) => c(row));\n    }\n    return (row) => children.some((c) => c(row));\n  }\n\n  if (name === 'not' && args.length === 1) {\n    const inner = translate(args[0]!, knownColumns);\n    if (!inner) return null;\n    return (row) => !inner(row);\n  }\n\n  return null;\n}\n\nfunction translateEq(\n  a: BasicExpression,\n  b: BasicExpression,\n  knownColumns: ReadonlySet<string>,\n): Predicate | null {\n  // eq(ref, value) or eq(value, ref). Anything else → not pushable.\n  let ref: PropRef | null = null;\n  let lit: ValueExpr | null = null;\n  if (a.type === 'ref' && b.type === 'val') {\n    ref = a as PropRef;\n    lit = b as ValueExpr;\n  } else if (a.type === 'val' && b.type === 'ref') {\n    ref = b as PropRef;\n    lit = a as ValueExpr;\n  } else {\n    return null;\n  }\n\n  const col = resolveRef(ref, knownColumns);\n  if (!col) return null;\n  const literal = lit.value;\n  return (row) => row[col] === literal;\n}\n\nfunction toRefPredicate(\n  ref: PropRef,\n  knownColumns: ReadonlySet<string>,\n): Predicate | null {\n  const col = resolveRef(ref, knownColumns);\n  if (!col) return null;\n  return (row) => row[col] === true;\n}\n\nfunction resolveRef(\n  ref: PropRef,\n  knownColumns: ReadonlySet<string>,\n): string | null {\n  if (!ref.path || ref.path.length === 0) return null;\n  // TanStack DB encodes refs as [alias, column] inside a join/from,\n  // but for a single collection the alias is dropped. We accept both\n  // shapes: [col] or [alias, col]. Anything deeper is rejected.\n  let col: string;\n  if (ref.path.length === 1) {\n    col = ref.path[0]!;\n  } else if (ref.path.length === 2) {\n    col = ref.path[1]!;\n  } else {\n    return null;\n  }\n  if (!knownColumns.has(col)) return null;\n  return col;\n}\n","/**\n * TanStack DB adapter for ArrowBase.\n *\n * Exposes an ArrowBase `Collection` as a standard `@tanstack/db`\n * `createCollection({ sync, onInsert, onUpdate, onDelete, getKey })` config\n * so the two stores can be joined via TanStack DB's live query engine.\n *\n * Design notes:\n *   - `@tanstack/db` is an optional peer dependency. This module only\n *     imports its *types* (erased at build time) and its value exports\n *     are resolved by the consumer. Import this module via the\n *     `arrowbase/tanstack` subpath only when you intend to use TanStack\n *     DB; the main `arrowbase` entry stays TanStack-free.\n *   - Rows handed to TanStack DB are plain JS objects (a snapshot from\n *     ArrowBase). The zero-copy proxy idea from PRD v2.0 was dropped in\n *     v2.1 because TanStack caches values internally.\n *   - Row-update mode is 'full' — every sync write carries a full row\n *     snapshot. `partial` would require TanStack DB to merge deltas\n *     against its cached value, but we always have the full current\n *     value from ArrowBase, so 'full' is simpler and correct.\n */\n\nimport type {\n  CollectionConfig,\n  DeleteKeyMessage,\n  SyncConfig,\n  LoadSubsetOptions,\n} from '@tanstack/db';\n\nimport type { Collection, RowValue } from './collection/collection.js';\nimport type { ChangeEvent } from './collection/events.js';\nimport { pushDown } from './pushdown.js';\n\n/** Options for the adapter. */\nexport interface ToTanstackOptions {\n  /**\n   * TanStack DB collection id. Defaults to `arrowbase:<schema.name>`.\n   */\n  id?: string;\n  /**\n   * When true, include soft-deleted rows in sync. Default false (the\n   * adapter filters them out, matching `Collection.rows()` semantics).\n   */\n  includeSoftDeleted?: boolean;\n}\n\n/**\n * Convert an ArrowBase collection into a TanStack DB `CollectionConfig`.\n *\n * Usage:\n * ```ts\n * import { createCollection } from '@tanstack/db';\n * import { toTanstackCollection } from 'arrowbase/tanstack';\n *\n * const features = createCollection(toTanstackCollection(abFeatures));\n * ```\n */\nexport function toTanstackCollection(\n  abColl: Collection,\n  options: ToTanstackOptions = {},\n): CollectionConfig<RowValue, number> {\n  const id = options.id ?? `arrowbase:${abColl.schema.name}`;\n  const pkName = abColl.schema.primaryKey;\n  const includeSoftDeleted = options.includeSoftDeleted ?? false;\n\n  const sync: SyncConfig<RowValue, number> = {\n    sync: (params) => {\n      const { begin, write, commit, markReady, truncate } = params;\n\n      // ---- Initial backfill ---------------------------------------\n      begin();\n      for (const row of abColl.rows({ includeSoftDeleted })) {\n        // TanStack DB derives the key from the value via getKey when\n        // the `key` field is absent, per the sync protocol.\n        write({ value: row, type: 'insert' });\n      }\n      commit();\n      markReady();\n\n      // ---- Live change feed ---------------------------------------\n      const unsubscribe = abColl.subscribe((event) => {\n        // compact + rollback are wholesale changes: truncate then\n        // replay every live row.\n        if (event.op === 'compact' || event.op === 'rollback') {\n          begin();\n          truncate();\n          for (const row of abColl.rows({ includeSoftDeleted })) {\n            write({ value: row, type: 'insert' });\n          }\n          commit();\n          return;\n        }\n\n        translateEvent(abColl, event, pkName, includeSoftDeleted, {\n          begin,\n          write,\n          commit,\n        });\n      });\n\n      return {\n        cleanup: () => unsubscribe(),\n        // Push-down hook: when TanStack DB requests a subset with an\n        // eq/and/or/not filter over known columns, we translate it to\n        // an ArrowBase predicate and emit only matching rows. This\n        // module keeps behaviour correct regardless — TanStack DB also\n        // re-evaluates the predicate against materialized rows, so an\n        // over-approximation here just means extra work, never wrong\n        // results.\n        loadSubset: (opts: LoadSubsetOptions) => {\n          const knownCols = new Set(abColl.columnNames());\n          const predicate = pushDown(opts.where, knownCols);\n          if (!predicate) {\n            // Not pushable: TanStack DB already has the full dataset\n            // from the initial eager backfill. Returning `true` signals\n            // \"already loaded\" — no additional work required.\n            return true;\n          }\n          begin();\n          for (const row of abColl.rows({ includeSoftDeleted })) {\n            if (!predicate(row)) continue;\n            write({ value: row, type: 'update' });\n          }\n          commit();\n          return true;\n        },\n      };\n    },\n    // Full row snapshots keep the adapter stateless. TanStack DB's\n    // default is 'partial'; we override because ArrowBase always\n    // produces a full row on read.\n    rowUpdateMode: 'full',\n  };\n\n  return {\n    id,\n    getKey: (item: RowValue) => item[pkName] as number,\n    sync,\n    onInsert: async ({ transaction }) => {\n      for (const m of transaction.mutations) {\n        abColl.insert(m.modified as RowValue);\n      }\n    },\n    onUpdate: async ({ transaction }) => {\n      for (const m of transaction.mutations) {\n        const key = m.key as number;\n        // TanStack's `changes` is the field-level diff; forward only\n        // the changed columns so we do not bump unchanged column\n        // versions unnecessarily.\n        abColl.update(key, m.changes as Partial<RowValue>);\n      }\n    },\n    onDelete: async ({ transaction }) => {\n      for (const m of transaction.mutations) {\n        abColl.delete(m.key as number);\n      }\n    },\n  };\n}\n\n// ---------------------------------------------------------------------\n// helpers\n// ---------------------------------------------------------------------\n\ninterface SyncPort {\n  begin: (options?: { immediate?: boolean }) => void;\n  write: (\n    msg:\n      | { value: RowValue; type: 'insert' | 'update' }\n      | DeleteKeyMessage<number>,\n  ) => void;\n  commit: () => void;\n}\n\nfunction translateEvent(\n  abColl: Collection,\n  event: ChangeEvent,\n  _pkName: string,\n  includeSoftDeleted: boolean,\n  port: SyncPort,\n): void {\n  const key = event.rowId;\n\n  if (event.op === 'delete') {\n    // Hard delete: row is gone. Soft delete: row still exists but\n    // `__deleted=true`. TanStack DB should see a delete in either\n    // case unless the caller opted in to soft-deleted visibility.\n    if (!includeSoftDeleted) {\n      port.begin();\n      port.write({ key, type: 'delete' });\n      port.commit();\n      return;\n    }\n    // Soft delete with includeSoftDeleted=true: emit as update so the\n    // __deleted=true field propagates to consumers.\n    const row = abColl.get(key);\n    if (!row) return;\n    port.begin();\n    port.write({ value: row, type: 'update' });\n    port.commit();\n    return;\n  }\n\n  // Insert / update: read the full current row and emit.\n  const row = abColl.get(key);\n  if (!row) return; // e.g. the row was deleted between the emit and here\n  port.begin();\n  port.write({\n    value: row,\n    type: event.op === 'insert' ? 'insert' : 'update',\n  });\n  port.commit();\n}\n"]}

package/dist/types-CSoU6uED.d.ts

@@ -0,0 +1,50 @@
+import { R as RowValue } from './collection-DGlKgOGi.js';
+
+/**
+ * Delta types exchanged by SyncAdapters.
+ *
+ * A `Delta` carries a single primary-key change with its outcome:
+ *   - insert: full row payload, with `version` = globalVersion after insert
+ *   - update: full row payload (we send post-image for simplicity in v1)
+ *   - delete: no payload
+ *
+ * v1 uses `version` as a monotonic clock. Senders are responsible for
+ * producing deltas in version order; receivers apply blindly. No
+ * per-row version tracking yet — last-writer-wins emerges from
+ * deterministic version ordering at the sender.
+ */
+
+type DeltaOp = 'insert' | 'update' | 'delete';
+interface Delta {
+    readonly op: DeltaOp;
+    readonly key: number;
+    /** Required for insert/update, absent for delete. */
+    readonly value?: RowValue;
+    /**
+     * Monotonic version at the moment of the mutation (globalVersion).
+     * Consumers use this to resume from a cursor.
+     */
+    readonly version: number;
+}
+/**
+ * Interface implemented by pluggable sync transports (REST, WebSocket,
+ * CRDT, …). Adapters shuttle deltas between a local ArrowBase collection
+ * and a remote source.
+ */
+interface SyncAdapter {
+    /** Apply remote deltas to the local collection. */
+    apply(deltas: readonly Delta[]): Promise<void>;
+    /**
+     * Pull deltas strictly newer than `sinceVersion`. Returns the deltas
+     * and the new cursor (`upTo`) that callers should pass back on the
+     * next pull.
+     */
+    pull(sinceVersion: number): Promise<{
+        deltas: Delta[];
+        upTo: number;
+    }>;
+    /** Push local deltas to the remote. */
+    push(deltas: readonly Delta[]): Promise<void>;
+}
+
+export type { Delta as D, SyncAdapter as S, DeltaOp as a };

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "arrowbase",
+  "version": "0.1.1",
+  "private": false,
+  "description": "Columnar Arrow store with an @tanstack/db-compatible API.",
+  "keywords": [
+    "arrow",
+    "columnar",
+    "tanstack-db",
+    "local-first",
+    "sharedarraybuffer",
+    "reactive-query"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/natanelia/arrowbase.git"
+  },
+  "bugs": {
+    "url": "https://github.com/natanelia/arrowbase/issues"
+  },
+  "homepage": "https://natanelia.github.io/arrowbase/",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tanstack": {
+      "types": "./dist/tanstack.d.ts",
+      "import": "./dist/tanstack.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./arrow": {
+      "types": "./dist/arrow.d.ts",
+      "import": "./dist/arrow.js"
+    },
+    "./idb": {
+      "types": "./dist/idb.d.ts",
+      "import": "./dist/idb.js"
+    },
+    "./broadcast": {
+      "types": "./dist/broadcast.d.ts",
+      "import": "./dist/broadcast.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "MIGRATING.md",
+    "COMPATIBILITY.md",
+    "CHANGELOG.md",
+    "RELEASE_NOTES.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run -c vitest.config.ts",
+    "test:watch": "vitest -c vitest.config.ts",
+    "test:differential": "vitest run -c vitest.differential.config.ts",
+    "test:golden": "vitest run -c vitest.golden.config.ts",
+    "test:showcase-docs": "vitest run -c vitest.config.ts tests/showcase-docs.test.ts",
+    "test:public-api": "vitest run -c vitest.config.ts tests/public-api-contract.test.ts",
+    "verify:package-exports": "tsx scripts/verify-package-exports.ts",
+    "lint": "tsc --noEmit",
+    "bench": "node --expose-gc --import tsx bench/index.ts",
+    "bench:all": "tsx bench/all.ts",
+    "bench:ivm": "tsx bench/ivm-live.ts",
+    "bench:operations": "node --expose-gc --import tsx bench/query-operations.ts",
+    "bench:spatial": "node --expose-gc --import tsx bench/spatial.ts",
+    "bench:vs-tanstack": "node --expose-gc --import tsx bench/vs-tanstack.ts",
+    "release:verify": "node scripts/verify-release.mjs",
+    "release:pack": "pnpm build && pnpm pack --pack-destination .release",
+    "playground:build:pages": "pnpm --filter @arrowbase/showcase build:pages",
+    "release:tag": "git tag v$npm_package_version",
+    "prepublishOnly": "pnpm release:verify && pnpm check && pnpm build && pnpm verify:package-exports",
+    "check": "pnpm typecheck && pnpm test:public-api && pnpm test:differential && pnpm test:golden && pnpm test:showcase-docs && pnpm test",
+    "playground:dev": "pnpm --filter @arrowbase/showcase dev",
+    "playground:build": "pnpm --filter @arrowbase/showcase build",
+    "playground:test": "pnpm --filter @arrowbase/showcase test",
+    "playground:e2e": "pnpm --filter @arrowbase/showcase e2e",
+    "playground:typecheck": "pnpm --filter @arrowbase/showcase typecheck",
+    "playground:check": "pnpm playground:typecheck && pnpm playground:test && pnpm playground:build",
+    "bench:showcase": "pnpm --filter @arrowbase/showcase bench:report"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@tanstack/db": "^0.6.16",
+    "apache-arrow": "^19.0.0 || ^20.0.0 || ^21.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/db": {
+      "optional": true
+    },
+    "apache-arrow": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/db": "^0.6.16",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "apache-arrow": "^21.1.0",
+    "fake-indexeddb": "^6.2.5",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tinybench": "^6.0.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "packageManager": "pnpm@10.26.2",
+  "dependencies": {
+    "@tanstack/db-ivm": "0.1.18",
+    "flatbush": "^4.5.1"
+  }
+}