@taladb/next 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 thinkgrid-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.mts

@@ -0,0 +1,44 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SyncOptions, SyncResult } from 'taladb';
+
+interface SyncProviderProps {
+    /** Base URL of your sync backend, e.g. `/api/sync` (same-origin route
+     * handler created with `createSyncHandlers`) or a full URL. */
+    endpoint: string;
+    /** Milliseconds between passes while the tab is open. Default 30 000. Set
+     * `0` to disable the interval (event-driven passes still run). */
+    intervalMs?: number;
+    /** Headers for every request — typically `Authorization`. Pass a function
+     * to read a fresh token per pass. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Scope/direction options forwarded to every `db.sync()` pass. */
+    options?: SyncOptions;
+    /** Called after each successful pass. */
+    onSync?: (result: SyncResult) => void;
+    /** Called when a pass fails (offline, 401, server down). The next replayed
+     * pass covers the gap. */
+    onError?: (error: unknown) => void;
+    children?: ReactNode;
+}
+/**
+ * ```tsx
+ * // app/providers.tsx
+ * 'use client'
+ * import { TalaDBProvider } from '@taladb/react'
+ * import { SyncProvider } from '@taladb/next/client'
+ *
+ * export function Providers({ children }) {
+ *   return (
+ *     <TalaDBProvider name="myapp.db">
+ *       <SyncProvider endpoint="/api/sync" headers={() => ({ Authorization: `Bearer ${getToken()}` })}>
+ *         {children}
+ *       </SyncProvider>
+ *     </TalaDBProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function SyncProvider({ endpoint, intervalMs, headers, options, onSync, onError, children, }: SyncProviderProps): react_jsx_runtime.JSX.Element;
+
+export { SyncProvider, type SyncProviderProps };

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SyncOptions, SyncResult } from 'taladb';
+
+interface SyncProviderProps {
+    /** Base URL of your sync backend, e.g. `/api/sync` (same-origin route
+     * handler created with `createSyncHandlers`) or a full URL. */
+    endpoint: string;
+    /** Milliseconds between passes while the tab is open. Default 30 000. Set
+     * `0` to disable the interval (event-driven passes still run). */
+    intervalMs?: number;
+    /** Headers for every request — typically `Authorization`. Pass a function
+     * to read a fresh token per pass. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** Scope/direction options forwarded to every `db.sync()` pass. */
+    options?: SyncOptions;
+    /** Called after each successful pass. */
+    onSync?: (result: SyncResult) => void;
+    /** Called when a pass fails (offline, 401, server down). The next replayed
+     * pass covers the gap. */
+    onError?: (error: unknown) => void;
+    children?: ReactNode;
+}
+/**
+ * ```tsx
+ * // app/providers.tsx
+ * 'use client'
+ * import { TalaDBProvider } from '@taladb/react'
+ * import { SyncProvider } from '@taladb/next/client'
+ *
+ * export function Providers({ children }) {
+ *   return (
+ *     <TalaDBProvider name="myapp.db">
+ *       <SyncProvider endpoint="/api/sync" headers={() => ({ Authorization: `Bearer ${getToken()}` })}>
+ *         {children}
+ *       </SyncProvider>
+ *     </TalaDBProvider>
+ *   )
+ * }
+ * ```
+ */
+declare function SyncProvider({ endpoint, intervalMs, headers, options, onSync, onError, children, }: SyncProviderProps): react_jsx_runtime.JSX.Element;
+
+export { SyncProvider, type SyncProviderProps };

package/dist/client.js

@@ -0,0 +1,105 @@
+'use client';
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.tsx
+var client_exports = {};
+__export(client_exports, {
+  SyncProvider: () => SyncProvider
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
+var import_react2 = require("@taladb/react");
+var import_jsx_runtime = require("react/jsx-runtime");
+function SyncProvider({
+  endpoint,
+  intervalMs = 3e4,
+  headers,
+  options,
+  onSync,
+  onError,
+  children
+}) {
+  const db = (0, import_react2.useTalaDB)();
+  const latest = (0, import_react.useRef)({ headers, options, onSync, onError });
+  latest.current = { headers, options, onSync, onError };
+  const activePass = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    let stopped = false;
+    let waitingForActive = false;
+    const sync = async () => {
+      if (stopped) return;
+      if (activePass.current) {
+        if (waitingForActive) return;
+        waitingForActive = true;
+        await activePass.current;
+        waitingForActive = false;
+        if (!stopped) void sync();
+        return;
+      }
+      const pass = Promise.resolve().then(async () => {
+        try {
+          const { HttpSyncAdapter } = await import("taladb");
+          const h = latest.current.headers;
+          const adapter = new HttpSyncAdapter({
+            endpoint,
+            headers: typeof h === "function" ? h() : h
+          });
+          const result = await db.sync(adapter, latest.current.options ?? {});
+          if (!stopped) latest.current.onSync?.(result);
+        } catch (e) {
+          if (!stopped) latest.current.onError?.(e);
+        }
+      });
+      activePass.current = pass;
+      await pass.finally(() => {
+        if (activePass.current === pass) activePass.current = null;
+      });
+    };
+    void sync();
+    const tick = intervalMs > 0 ? setInterval(sync, intervalMs) : void 0;
+    const onOnline = () => void sync();
+    const onVisible = () => {
+      if (document.visibilityState === "visible") void sync();
+    };
+    window.addEventListener("online", onOnline);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      stopped = true;
+      if (tick !== void 0) clearInterval(tick);
+      window.removeEventListener("online", onOnline);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [db, endpoint, intervalMs]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SyncProvider
+});

package/dist/client.mjs

@@ -0,0 +1,71 @@
+'use client';
+
+// src/client.tsx
+import { useEffect, useRef } from "react";
+import { useTalaDB } from "@taladb/react";
+import { Fragment, jsx } from "react/jsx-runtime";
+function SyncProvider({
+  endpoint,
+  intervalMs = 3e4,
+  headers,
+  options,
+  onSync,
+  onError,
+  children
+}) {
+  const db = useTalaDB();
+  const latest = useRef({ headers, options, onSync, onError });
+  latest.current = { headers, options, onSync, onError };
+  const activePass = useRef(null);
+  useEffect(() => {
+    let stopped = false;
+    let waitingForActive = false;
+    const sync = async () => {
+      if (stopped) return;
+      if (activePass.current) {
+        if (waitingForActive) return;
+        waitingForActive = true;
+        await activePass.current;
+        waitingForActive = false;
+        if (!stopped) void sync();
+        return;
+      }
+      const pass = Promise.resolve().then(async () => {
+        try {
+          const { HttpSyncAdapter } = await import("taladb");
+          const h = latest.current.headers;
+          const adapter = new HttpSyncAdapter({
+            endpoint,
+            headers: typeof h === "function" ? h() : h
+          });
+          const result = await db.sync(adapter, latest.current.options ?? {});
+          if (!stopped) latest.current.onSync?.(result);
+        } catch (e) {
+          if (!stopped) latest.current.onError?.(e);
+        }
+      });
+      activePass.current = pass;
+      await pass.finally(() => {
+        if (activePass.current === pass) activePass.current = null;
+      });
+    };
+    void sync();
+    const tick = intervalMs > 0 ? setInterval(sync, intervalMs) : void 0;
+    const onOnline = () => void sync();
+    const onVisible = () => {
+      if (document.visibilityState === "visible") void sync();
+    };
+    window.addEventListener("online", onOnline);
+    document.addEventListener("visibilitychange", onVisible);
+    return () => {
+      stopped = true;
+      if (tick !== void 0) clearInterval(tick);
+      window.removeEventListener("online", onOnline);
+      document.removeEventListener("visibilitychange", onVisible);
+    };
+  }, [db, endpoint, intervalMs]);
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+export {
+  SyncProvider
+};

package/dist/server.d.mts

@@ -0,0 +1,85 @@
+import { TalaDB } from 'taladb';
+
+/** The fields of a TalaDB change record the store keys on. Everything else in
+ * a record is opaque — store it verbatim. */
+interface ChangeRecord {
+    collection: string;
+    id: string;
+    changed_at: number;
+    [key: string]: unknown;
+}
+/**
+ * Where pushed changes live. Implementations keep the **latest change per
+ * document per scope** (Last-Write-Wins by `changed_at`) and answer
+ * "everything in this scope newer than `sinceMs`".
+ *
+ * `scope` partitions users or workspaces — the value returned by
+ * `authorize`. A store must never leak changes across scopes.
+ */
+interface SyncStore {
+    /** Merge a pushed changeset (JSON string of `ChangeRecord[]`) into `scope`. */
+    push(changeset: string, scope: string): Promise<void>;
+    /** Serialized changeset of `scope` changes with `changed_at > sinceMs`. */
+    pull(sinceMs: number, scope: string): Promise<string>;
+}
+interface CreateSyncHandlersOptions {
+    store: SyncStore;
+    /** Maximum accepted push body size in bytes. Default 1 MiB. */
+    maxBodyBytes?: number;
+    /** Maximum records accepted in one push. Default 10,000. */
+    maxRecords?: number;
+    /**
+     * Identify and authorize the caller, returning a scope key (e.g. the user
+     * id) — this is your security boundary. Return `null`/`undefined` to reject
+     * with 401. Omit for a single shared scope (`'default'`) — fine for
+     * prototypes and single-user apps, wrong for anything multi-user.
+     */
+    authorize?: (req: Request) => Promise<string | null | undefined> | string | null | undefined;
+}
+interface SyncHandlers {
+    /** Mount as the handler for `POST {endpoint}/push`. */
+    POST(req: Request): Promise<Response>;
+    /** Mount as the handler for `GET {endpoint}/pull`. */
+    GET(req: Request): Promise<Response>;
+}
+/**
+ * A complete sync backend as a pair of fetch-style route handlers.
+ *
+ * ```ts
+ * // app/api/sync/[[...action]]/route.ts
+ * import { createSyncHandlers, memorySyncStore } from '@taladb/next/server'
+ *
+ * export const { POST, GET } = createSyncHandlers({
+ *   store: memorySyncStore(),
+ *   authorize: async (req) => verifySession(req.headers.get('authorization')),
+ * })
+ * ```
+ *
+ * Point the client's `HttpSyncAdapter` at `endpoint: '/api/sync'`.
+ */
+declare function createSyncHandlers(options: CreateSyncHandlersOptions): SyncHandlers;
+/**
+ * In-memory store — perfect for development and tests; state is lost on
+ * server restart and not shared across serverless instances. Use
+ * {@link taladbSyncStore} (or your own database) in production.
+ */
+declare function memorySyncStore(): SyncStore;
+/**
+ * A store backed by a server-side TalaDB — TalaDB syncing to TalaDB. Open a
+ * file-backed database once (Node.js runtime, not edge) and hand it in:
+ *
+ * ```ts
+ * import { openDB } from 'taladb'
+ * import { createSyncHandlers, taladbSyncStore } from '@taladb/next/server'
+ *
+ * const serverDb = await openDB('sync-hub.db')
+ * export const { POST, GET } = createSyncHandlers({ store: taladbSyncStore(serverDb) })
+ * ```
+ *
+ * Stores the greatest timestamp per synced document and preserves distinct
+ * equal-timestamp candidates so TalaDB core can apply its exact deterministic
+ * tie-break when clients import them.
+ */
+declare function taladbSyncStore(db: TalaDB, collectionName?: string): SyncStore;
+
+export { type ChangeRecord, type CreateSyncHandlersOptions, type SyncHandlers, type SyncStore, createSyncHandlers, memorySyncStore, taladbSyncStore };

package/dist/server.d.ts

@@ -0,0 +1,85 @@
+import { TalaDB } from 'taladb';
+
+/** The fields of a TalaDB change record the store keys on. Everything else in
+ * a record is opaque — store it verbatim. */
+interface ChangeRecord {
+    collection: string;
+    id: string;
+    changed_at: number;
+    [key: string]: unknown;
+}
+/**
+ * Where pushed changes live. Implementations keep the **latest change per
+ * document per scope** (Last-Write-Wins by `changed_at`) and answer
+ * "everything in this scope newer than `sinceMs`".
+ *
+ * `scope` partitions users or workspaces — the value returned by
+ * `authorize`. A store must never leak changes across scopes.
+ */
+interface SyncStore {
+    /** Merge a pushed changeset (JSON string of `ChangeRecord[]`) into `scope`. */
+    push(changeset: string, scope: string): Promise<void>;
+    /** Serialized changeset of `scope` changes with `changed_at > sinceMs`. */
+    pull(sinceMs: number, scope: string): Promise<string>;
+}
+interface CreateSyncHandlersOptions {
+    store: SyncStore;
+    /** Maximum accepted push body size in bytes. Default 1 MiB. */
+    maxBodyBytes?: number;
+    /** Maximum records accepted in one push. Default 10,000. */
+    maxRecords?: number;
+    /**
+     * Identify and authorize the caller, returning a scope key (e.g. the user
+     * id) — this is your security boundary. Return `null`/`undefined` to reject
+     * with 401. Omit for a single shared scope (`'default'`) — fine for
+     * prototypes and single-user apps, wrong for anything multi-user.
+     */
+    authorize?: (req: Request) => Promise<string | null | undefined> | string | null | undefined;
+}
+interface SyncHandlers {
+    /** Mount as the handler for `POST {endpoint}/push`. */
+    POST(req: Request): Promise<Response>;
+    /** Mount as the handler for `GET {endpoint}/pull`. */
+    GET(req: Request): Promise<Response>;
+}
+/**
+ * A complete sync backend as a pair of fetch-style route handlers.
+ *
+ * ```ts
+ * // app/api/sync/[[...action]]/route.ts
+ * import { createSyncHandlers, memorySyncStore } from '@taladb/next/server'
+ *
+ * export const { POST, GET } = createSyncHandlers({
+ *   store: memorySyncStore(),
+ *   authorize: async (req) => verifySession(req.headers.get('authorization')),
+ * })
+ * ```
+ *
+ * Point the client's `HttpSyncAdapter` at `endpoint: '/api/sync'`.
+ */
+declare function createSyncHandlers(options: CreateSyncHandlersOptions): SyncHandlers;
+/**
+ * In-memory store — perfect for development and tests; state is lost on
+ * server restart and not shared across serverless instances. Use
+ * {@link taladbSyncStore} (or your own database) in production.
+ */
+declare function memorySyncStore(): SyncStore;
+/**
+ * A store backed by a server-side TalaDB — TalaDB syncing to TalaDB. Open a
+ * file-backed database once (Node.js runtime, not edge) and hand it in:
+ *
+ * ```ts
+ * import { openDB } from 'taladb'
+ * import { createSyncHandlers, taladbSyncStore } from '@taladb/next/server'
+ *
+ * const serverDb = await openDB('sync-hub.db')
+ * export const { POST, GET } = createSyncHandlers({ store: taladbSyncStore(serverDb) })
+ * ```
+ *
+ * Stores the greatest timestamp per synced document and preserves distinct
+ * equal-timestamp candidates so TalaDB core can apply its exact deterministic
+ * tie-break when clients import them.
+ */
+declare function taladbSyncStore(db: TalaDB, collectionName?: string): SyncStore;
+
+export { type ChangeRecord, type CreateSyncHandlersOptions, type SyncHandlers, type SyncStore, createSyncHandlers, memorySyncStore, taladbSyncStore };

package/dist/server.js

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  createSyncHandlers: () => createSyncHandlers,
+  memorySyncStore: () => memorySyncStore,
+  taladbSyncStore: () => taladbSyncStore
+});
+module.exports = __toCommonJS(server_exports);
+function createSyncHandlers(options) {
+  const { store } = options;
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const maxRecords = options.maxRecords ?? 1e4;
+  const authorize = options.authorize ?? (() => "default");
+  async function resolveScope(req) {
+    const scope = await authorize(req);
+    return scope ?? null;
+  }
+  return {
+    async POST(req) {
+      const scope = await resolveScope(req);
+      if (scope === null) return new Response("unauthorized", { status: 401 });
+      const declaredLength = Number(req.headers.get("content-length"));
+      if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+        return new Response("changeset too large", { status: 413 });
+      }
+      const body = await req.text();
+      if (new TextEncoder().encode(body).byteLength > maxBodyBytes) {
+        return new Response("changeset too large", { status: 413 });
+      }
+      let records;
+      try {
+        records = JSON.parse(body === "" ? "[]" : body);
+      } catch {
+        return new Response("invalid changeset: not JSON", { status: 400 });
+      }
+      if (!Array.isArray(records)) {
+        return new Response("invalid changeset: expected a JSON array", { status: 400 });
+      }
+      if (records.length > maxRecords) {
+        return new Response("too many change records", { status: 413 });
+      }
+      for (const r of records) {
+        const rec = r;
+        if (typeof rec !== "object" || rec === null || typeof rec.collection !== "string" || typeof rec.id !== "string" || typeof rec.changed_at !== "number" || !Number.isSafeInteger(rec.changed_at) || rec.changed_at < 0) {
+          return new Response("invalid changeset: malformed change record", { status: 400 });
+        }
+      }
+      if (records.length > 0) {
+        await store.push(JSON.stringify(records), scope);
+      }
+      return new Response(null, { status: 204 });
+    },
+    async GET(req) {
+      const scope = await resolveScope(req);
+      if (scope === null) return new Response("unauthorized", { status: 401 });
+      const sinceRaw = new URL(req.url).searchParams.get("since") ?? "0";
+      const since = Number(sinceRaw);
+      if (!Number.isSafeInteger(since) || since < 0) {
+        return new Response("invalid since parameter", { status: 400 });
+      }
+      const changeset = await store.pull(since, scope);
+      return new Response(changeset, {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      });
+    }
+  };
+}
+function memorySyncStore() {
+  const scopes = /* @__PURE__ */ new Map();
+  return {
+    async push(changeset, scope) {
+      let docs = scopes.get(scope);
+      if (!docs) {
+        docs = /* @__PURE__ */ new Map();
+        scopes.set(scope, docs);
+      }
+      for (const change of JSON.parse(changeset)) {
+        const key = `${change.collection}::${change.id}`;
+        const existing = docs.get(key) ?? [];
+        const latest = existing[0]?.changed_at;
+        if (latest === void 0 || change.changed_at > latest) docs.set(key, [change]);
+        else if (change.changed_at === latest) {
+          const serialized = JSON.stringify(change);
+          if (!existing.some((candidate) => JSON.stringify(candidate) === serialized)) {
+            existing.push(change);
+          }
+        }
+      }
+    },
+    async pull(sinceMs, scope) {
+      const docs = scopes.get(scope);
+      if (!docs) return "[]";
+      return JSON.stringify(
+        [...docs.values()].flat().filter((c) => c.changed_at > sinceMs)
+      );
+    }
+  };
+}
+var taladbStoreQueues = /* @__PURE__ */ new WeakMap();
+function taladbSyncStore(db, collectionName = "sync_changes") {
+  const col = db.collection(collectionName);
+  const indexed = (async () => {
+    await col.createIndex("doc_key").catch(() => {
+    });
+    await col.createIndex("changed_at").catch(() => {
+    });
+  })();
+  let queues = taladbStoreQueues.get(db);
+  if (!queues) {
+    queues = /* @__PURE__ */ new Map();
+    taladbStoreQueues.set(db, queues);
+  }
+  return {
+    async push(changeset, scope) {
+      const run = async () => {
+        await indexed;
+        for (const change of JSON.parse(changeset)) {
+          const docKey = `${change.collection}::${change.id}`;
+          const serialized = JSON.stringify(change);
+          const existing = await col.find({ scope, doc_key: docKey });
+          const latest = existing.reduce((n, row) => Math.max(n, row.changed_at), -Infinity);
+          if (change.changed_at > latest) {
+            if (existing.length > 0) await col.deleteMany({ scope, doc_key: docKey });
+            await col.insert({ scope, doc_key: docKey, changed_at: change.changed_at, change: serialized });
+          } else if (change.changed_at === latest && !existing.some((row) => row.change === serialized)) {
+            await col.insert({ scope, doc_key: docKey, changed_at: change.changed_at, change: serialized });
+          }
+        }
+      };
+      const previous = queues.get(collectionName) ?? Promise.resolve();
+      const operation = previous.then(run, run);
+      queues.set(collectionName, operation.catch(() => {
+      }));
+      await operation;
+    },
+    async pull(sinceMs, scope) {
+      await indexed;
+      const rows = await col.find({ scope, changed_at: { $gt: sinceMs } });
+      return `[${rows.map((r) => r.change).join(",")}]`;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSyncHandlers,
+  memorySyncStore,
+  taladbSyncStore
+});

package/dist/server.mjs

@@ -0,0 +1,141 @@
+// src/server.ts
+function createSyncHandlers(options) {
+  const { store } = options;
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const maxRecords = options.maxRecords ?? 1e4;
+  const authorize = options.authorize ?? (() => "default");
+  async function resolveScope(req) {
+    const scope = await authorize(req);
+    return scope ?? null;
+  }
+  return {
+    async POST(req) {
+      const scope = await resolveScope(req);
+      if (scope === null) return new Response("unauthorized", { status: 401 });
+      const declaredLength = Number(req.headers.get("content-length"));
+      if (Number.isFinite(declaredLength) && declaredLength > maxBodyBytes) {
+        return new Response("changeset too large", { status: 413 });
+      }
+      const body = await req.text();
+      if (new TextEncoder().encode(body).byteLength > maxBodyBytes) {
+        return new Response("changeset too large", { status: 413 });
+      }
+      let records;
+      try {
+        records = JSON.parse(body === "" ? "[]" : body);
+      } catch {
+        return new Response("invalid changeset: not JSON", { status: 400 });
+      }
+      if (!Array.isArray(records)) {
+        return new Response("invalid changeset: expected a JSON array", { status: 400 });
+      }
+      if (records.length > maxRecords) {
+        return new Response("too many change records", { status: 413 });
+      }
+      for (const r of records) {
+        const rec = r;
+        if (typeof rec !== "object" || rec === null || typeof rec.collection !== "string" || typeof rec.id !== "string" || typeof rec.changed_at !== "number" || !Number.isSafeInteger(rec.changed_at) || rec.changed_at < 0) {
+          return new Response("invalid changeset: malformed change record", { status: 400 });
+        }
+      }
+      if (records.length > 0) {
+        await store.push(JSON.stringify(records), scope);
+      }
+      return new Response(null, { status: 204 });
+    },
+    async GET(req) {
+      const scope = await resolveScope(req);
+      if (scope === null) return new Response("unauthorized", { status: 401 });
+      const sinceRaw = new URL(req.url).searchParams.get("since") ?? "0";
+      const since = Number(sinceRaw);
+      if (!Number.isSafeInteger(since) || since < 0) {
+        return new Response("invalid since parameter", { status: 400 });
+      }
+      const changeset = await store.pull(since, scope);
+      return new Response(changeset, {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      });
+    }
+  };
+}
+function memorySyncStore() {
+  const scopes = /* @__PURE__ */ new Map();
+  return {
+    async push(changeset, scope) {
+      let docs = scopes.get(scope);
+      if (!docs) {
+        docs = /* @__PURE__ */ new Map();
+        scopes.set(scope, docs);
+      }
+      for (const change of JSON.parse(changeset)) {
+        const key = `${change.collection}::${change.id}`;
+        const existing = docs.get(key) ?? [];
+        const latest = existing[0]?.changed_at;
+        if (latest === void 0 || change.changed_at > latest) docs.set(key, [change]);
+        else if (change.changed_at === latest) {
+          const serialized = JSON.stringify(change);
+          if (!existing.some((candidate) => JSON.stringify(candidate) === serialized)) {
+            existing.push(change);
+          }
+        }
+      }
+    },
+    async pull(sinceMs, scope) {
+      const docs = scopes.get(scope);
+      if (!docs) return "[]";
+      return JSON.stringify(
+        [...docs.values()].flat().filter((c) => c.changed_at > sinceMs)
+      );
+    }
+  };
+}
+var taladbStoreQueues = /* @__PURE__ */ new WeakMap();
+function taladbSyncStore(db, collectionName = "sync_changes") {
+  const col = db.collection(collectionName);
+  const indexed = (async () => {
+    await col.createIndex("doc_key").catch(() => {
+    });
+    await col.createIndex("changed_at").catch(() => {
+    });
+  })();
+  let queues = taladbStoreQueues.get(db);
+  if (!queues) {
+    queues = /* @__PURE__ */ new Map();
+    taladbStoreQueues.set(db, queues);
+  }
+  return {
+    async push(changeset, scope) {
+      const run = async () => {
+        await indexed;
+        for (const change of JSON.parse(changeset)) {
+          const docKey = `${change.collection}::${change.id}`;
+          const serialized = JSON.stringify(change);
+          const existing = await col.find({ scope, doc_key: docKey });
+          const latest = existing.reduce((n, row) => Math.max(n, row.changed_at), -Infinity);
+          if (change.changed_at > latest) {
+            if (existing.length > 0) await col.deleteMany({ scope, doc_key: docKey });
+            await col.insert({ scope, doc_key: docKey, changed_at: change.changed_at, change: serialized });
+          } else if (change.changed_at === latest && !existing.some((row) => row.change === serialized)) {
+            await col.insert({ scope, doc_key: docKey, changed_at: change.changed_at, change: serialized });
+          }
+        }
+      };
+      const previous = queues.get(collectionName) ?? Promise.resolve();
+      const operation = previous.then(run, run);
+      queues.set(collectionName, operation.catch(() => {
+      }));
+      await operation;
+    },
+    async pull(sinceMs, scope) {
+      await indexed;
+      const rows = await col.find({ scope, changed_at: { $gt: sinceMs } });
+      return `[${rows.map((r) => r.change).join(",")}]`;
+    }
+  };
+}
+export {
+  createSyncHandlers,
+  memorySyncStore,
+  taladbSyncStore
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@taladb/next",
+  "version": "0.9.0",
+  "description": "First-party Next.js integration for TalaDB — sync route handlers for the server, a SyncProvider for the client",
+  "sideEffects": false,
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "database",
+    "local-first",
+    "nextjs",
+    "sync",
+    "offline",
+    "taladb"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thinkgrid-labs/taladb.git",
+    "directory": "packages/integrations/next"
+  },
+  "homepage": "https://taladb.dev/guide/bidirectional-sync",
+  "bugs": {
+    "url": "https://github.com/thinkgrid-labs/taladb/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@taladb/react": "^0.9.0",
+    "react": ">=18.0.0",
+    "taladb": "^0.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@taladb/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.0",
+    "taladb": "0.9.0",
+    "@taladb/react": "0.9.0",
+    "@taladb/node": "0.9.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}