@appurist/offlinedb 1.0.0

package/src/index.js

@@ -0,0 +1,19 @@
+export {
+  OfflineDbClient,
+  IndexedDbPersistence,
+  InMemoryPersistence,
+  LocalStoragePersistence,
+  createNeonHttpTransport
+} from "./client.js";
+export {
+  createOdbAuthClient,
+  createOdbDataClient,
+  createOdbSyncTransport
+} from "./neon.js";
+export {
+  defineTable
+} from "./schema.js";
+export {
+  createOfflinedbInstallSql,
+  createSyncedTableSql
+} from "./sql.js";

package/src/neon.js

@@ -0,0 +1,209 @@
+/**
+ * Thin fetch-based wrappers for Neon Auth and the Neon Data API.
+ *
+ * The auth endpoint defaults below are inferred from Better Auth's
+ * documented email/password routes because Neon Auth is built on Better Auth.
+ * Consumers can override endpoint paths if their Neon project uses different
+ * URLs or proxy routing.
+ */
+
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   fetchImpl?: typeof fetch,
+ *   endpoints?: Partial<{
+ *     loginWithPassword: string,
+ *     signUpWithPassword: string,
+ *     logout: string
+ *   }>
+ * }} options
+ */
+export function createOdbAuthClient(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const endpoints = {
+    loginWithPassword: "sign-in/email",
+    signUpWithPassword: "sign-up/email",
+    logout: "sign-out",
+    ...(options.endpoints ?? {})
+  };
+
+  return {
+    /**
+     * @param {{email: string, password: string, rememberMe?: boolean, callbackURL?: string}} args
+     */
+    async odbLoginWithPassword(args) {
+      return odbPostJson(fetchImpl, joinUrl(options.baseUrl, endpoints.loginWithPassword), args);
+    },
+
+    /**
+     * @param {{email: string, password: string, name?: string, callbackURL?: string, image?: string}} args
+     */
+    async odbSignUpWithPassword(args) {
+      return odbPostJson(fetchImpl, joinUrl(options.baseUrl, endpoints.signUpWithPassword), args);
+    },
+
+    async odbLogout() {
+      return odbPostJson(fetchImpl, joinUrl(options.baseUrl, endpoints.logout), {});
+    }
+  };
+}
+
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   fetchImpl?: typeof fetch,
+ *   getAuthToken?: () => Promise<string | null> | string | null,
+ *   headers?: HeadersInit
+ * }} options
+ */
+export function createOdbDataClient(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  return {
+    /**
+     * @param {{path: string, method?: string, body?: unknown, headers?: HeadersInit}} args
+     */
+    async odbRequest(args) {
+      const token = await options.getAuthToken?.();
+      const response = await fetchImpl(joinUrl(options.baseUrl, args.path), {
+        method: args.method ?? "GET",
+        headers: {
+          ...(args.body != null ? { "content-type": "application/json" } : {}),
+          ...(options.headers ?? {}),
+          ...(args.headers ?? {}),
+          ...(token ? { authorization: `Bearer ${token}` } : {})
+        },
+        body: args.body == null ? undefined : JSON.stringify(args.body)
+      });
+
+      if (!response.ok) {
+        throw new Error(`Neon Data API request failed with status ${response.status}`);
+      }
+
+      return readJsonIfPossible(response);
+    },
+
+    /**
+     * PostgREST-style RPC call.
+     *
+     * @param {string} fn
+     * @param {Record<string, unknown>=} args
+     */
+    async odbRpc(fn, args = {}) {
+      return this.odbRequest({
+        path: `rpc/${fn}`,
+        method: "POST",
+        body: args
+      });
+    }
+  };
+}
+
+/**
+ * Direct Neon-native sync transport.
+ *
+ * It uses PostgREST-style RPC calls against database functions rather than a
+ * custom app-owned sync service.
+ *
+ * @param {{
+ *   dataClient: ReturnType<typeof createOdbDataClient>,
+ *   mutateFunctionName?: ((table: string) => string) | string,
+ *   pullFunctionName?: string
+ * }} options
+ */
+export function createOdbSyncTransport(options) {
+  const mutateFunctionName =
+    typeof options.mutateFunctionName === "function"
+      ? options.mutateFunctionName
+      : (table) => options.mutateFunctionName ?? `mutate_${table}`;
+  const pullFunctionName = options.pullFunctionName ?? "pull_changes";
+
+  return {
+    async sync(request) {
+      const accepted = [];
+      const conflicts = [];
+
+      for (const mutation of request.mutations) {
+        const result = normalizeRpcResult(
+          await options.dataClient.odbRpc(mutateFunctionName(mutation.table), {
+            p_local_id: mutation.localId,
+            p_row_key: mutation.key,
+            p_base_revision: mutation.baseRevision,
+            p_values: mutation.values
+          })
+        );
+
+        if (result?.ok === false) {
+          conflicts.push({
+            localId: mutation.localId,
+            code: result.code ?? "revision_conflict",
+            serverRow: result.row ?? null
+          });
+          continue;
+        }
+
+        accepted.push({
+          localId: result?.localId ?? mutation.localId,
+          globalId: Number(result?.globalId ?? 0),
+          row: result?.row ?? null
+        });
+      }
+
+      const pull = normalizeRpcResult(
+        await options.dataClient.odbRpc(pullFunctionName, {
+          p_last_global_id: request.lastGlobalId,
+          p_tables: request.tables?.length ? request.tables : null
+        })
+      ) ?? { changes: [], lastGlobalId: request.lastGlobalId };
+
+      return {
+        accepted,
+        conflicts,
+        changes: (pull.changes ?? []).map((entry) => ({
+          table: entry.table,
+          key: entry.key,
+          row: entry.row ?? null
+        })),
+        lastGlobalId: Number(pull.lastGlobalId ?? request.lastGlobalId ?? 0)
+      };
+    }
+  };
+}
+
+async function odbPostJson(fetchImpl, url, body) {
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+
+  if (!response.ok) {
+    throw new Error(`Auth request failed with status ${response.status}`);
+  }
+
+  return readJsonIfPossible(response);
+}
+
+async function readJsonIfPossible(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return response.json();
+  }
+
+  return response.text();
+}
+
+function normalizeRpcResult(value) {
+  if (Array.isArray(value)) {
+    return value[0] ?? null;
+  }
+
+  return value ?? null;
+}
+
+function joinUrl(baseUrl, path) {
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(path, normalizedBase);
+}

package/src/schema.js

@@ -0,0 +1,40 @@
+/**
+ * @typedef {{
+ *   name: string,
+ *   primaryKey?: string,
+ *   ownerColumn?: string,
+ *   revisionColumn?: string,
+ *   updatedAtColumn?: string,
+ *   localIdColumn?: string,
+ *   globalIdColumn?: string
+ * }} TableDefinitionInput
+ */
+
+/**
+ * @param {TableDefinitionInput} input
+ */
+export function defineTable(input) {
+  if (!input || typeof input !== "object") {
+    throw new Error("Table definition must be an object.");
+  }
+
+  const name = assertIdentifier(input.name, "table name");
+  return Object.freeze({
+    kind: "table",
+    name,
+    primaryKey: assertIdentifier(input.primaryKey ?? "id", "primary key"),
+    ownerColumn: assertIdentifier(input.ownerColumn ?? "owner_id", "owner column"),
+    revisionColumn: assertIdentifier(input.revisionColumn ?? "revision", "revision column"),
+    updatedAtColumn: assertIdentifier(input.updatedAtColumn ?? "updated_at", "updated_at column"),
+    localIdColumn: assertIdentifier(input.localIdColumn ?? "local_id", "local id column"),
+    globalIdColumn: assertIdentifier(input.globalIdColumn ?? "global_id", "global id column")
+  });
+}
+
+function assertIdentifier(value, label) {
+  if (typeof value !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`Invalid ${label}: ${String(value)}`);
+  }
+
+  return value;
+}

package/src/sql.js

@@ -0,0 +1,335 @@
+import { defineTable } from "./schema.js";
+
+/**
+ * @param {{schema?: string}=} options
+ */
+export function createOfflinedbInstallSql(options = {}) {
+  const schema = assertIdentifier(options.schema ?? "offlinedb", "schema");
+
+  return `
+CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schema)};
+
+CREATE TABLE IF NOT EXISTS ${qualified(schema, "global_mutation")} (
+  global_id BIGSERIAL PRIMARY KEY,
+  table_name TEXT NOT NULL,
+  row_key TEXT NOT NULL,
+  owner_id TEXT,
+  local_id TEXT,
+  revision BIGINT NOT NULL,
+  accepted_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  operation TEXT NOT NULL,
+  row_data JSONB
+);
+
+CREATE TABLE IF NOT EXISTS ${qualified(schema, "applied_mutation")} (
+  user_id TEXT NOT NULL,
+  local_id TEXT NOT NULL,
+  global_id BIGINT,
+  table_name TEXT NOT NULL,
+  row_key TEXT NOT NULL,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, local_id)
+);
+
+CREATE OR REPLACE FUNCTION ${qualified(schema, "current_user_id")}()
+RETURNS TEXT
+LANGUAGE SQL
+STABLE
+AS $$
+  SELECT COALESCE(
+    NULLIF(current_setting('request.jwt.claim.sub', true), ''),
+    NULLIF(current_setting('request.jwt.claims.sub', true), '')
+  )::TEXT
+$$;
+
+CREATE OR REPLACE FUNCTION ${qualified(schema, "record_change")}()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  next_owner_id TEXT;
+  next_revision BIGINT;
+  next_key TEXT;
+  next_payload JSONB;
+  next_local_id TEXT;
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    next_owner_id := OLD.owner_id;
+    next_revision := OLD.revision;
+    next_key := OLD.id::TEXT;
+    next_payload := NULL;
+    next_local_id := OLD.local_id;
+  ELSE
+    next_owner_id := NEW.owner_id;
+    next_revision := NEW.revision;
+    next_key := NEW.id::TEXT;
+    next_payload := to_jsonb(NEW);
+    next_local_id := NEW.local_id;
+  END IF;
+
+  INSERT INTO ${qualified(schema, "global_mutation")} (
+    global_id,
+    table_name,
+    row_key,
+    owner_id,
+    local_id,
+    revision,
+    operation,
+    row_data
+  )
+  VALUES (
+    CASE WHEN TG_OP = 'DELETE' THEN OLD.global_id ELSE NEW.global_id END,
+    TG_TABLE_NAME,
+    next_key,
+    next_owner_id,
+    next_local_id,
+    next_revision,
+    lower(TG_OP),
+    next_payload
+  );
+
+  IF TG_OP = 'DELETE' THEN
+    RETURN OLD;
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION ${qualified(schema, "pull_changes")}(
+  p_last_global_id BIGINT DEFAULT 0,
+  p_tables TEXT[] DEFAULT NULL
+)
+RETURNS JSONB
+LANGUAGE SQL
+STABLE
+AS $$
+  WITH selected AS (
+    SELECT
+      gm.global_id,
+      gm.table_name,
+      gm.row_key,
+      gm.row_data
+    FROM ${qualified(schema, "global_mutation")} gm
+    WHERE gm.global_id > COALESCE(p_last_global_id, 0)
+      AND (p_tables IS NULL OR gm.table_name = ANY(p_tables))
+    ORDER BY gm.global_id ASC
+  )
+  SELECT jsonb_build_object(
+    'changes',
+    COALESCE(
+      jsonb_agg(
+        jsonb_build_object(
+          'globalId', selected.global_id,
+          'table', selected.table_name,
+          'key', selected.row_key,
+          'row', selected.row_data
+        )
+        ORDER BY selected.global_id
+      ),
+      '[]'::jsonb
+    ),
+    'lastGlobalId',
+    COALESCE(MAX(selected.global_id), COALESCE(p_last_global_id, 0))
+  )
+  FROM selected
+$$;
+`.trim();
+}
+
+/**
+ * @param {{table: ReturnType<typeof defineTable> | string, schema?: string, metadataSchema?: string}} options
+ */
+export function createSyncedTableSql(options) {
+  const schema = assertIdentifier(options.schema ?? "public", "schema");
+  const metadataSchema = assertIdentifier(options.metadataSchema ?? "offlinedb", "metadata schema");
+  const table = typeof options.table === "string" ? defineTable({ name: options.table }) : options.table;
+  const tableName = qualified(schema, table.name);
+  const mutateFunctionName = qualified(metadataSchema, `mutate_${table.name}`);
+  const touchTriggerName = quoteIdentifier(`offlinedb_touch_${table.name}`);
+  const changeTriggerName = quoteIdentifier(`offlinedb_record_${table.name}`);
+
+  return `
+ALTER TABLE ${tableName}
+  ADD COLUMN IF NOT EXISTS ${quoteIdentifier(table.ownerColumn)} TEXT,
+  ADD COLUMN IF NOT EXISTS ${quoteIdentifier(table.revisionColumn)} BIGINT NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS ${quoteIdentifier(table.updatedAtColumn)} TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  ADD COLUMN IF NOT EXISTS ${quoteIdentifier(table.localIdColumn)} TEXT,
+  ADD COLUMN IF NOT EXISTS ${quoteIdentifier(table.globalIdColumn)} BIGINT NOT NULL DEFAULT 0;
+
+UPDATE ${tableName}
+SET ${quoteIdentifier(table.ownerColumn)} = COALESCE(${quoteIdentifier(table.ownerColumn)}, ${qualified(metadataSchema, "current_user_id")}())
+WHERE ${quoteIdentifier(table.ownerColumn)} IS NULL;
+
+ALTER TABLE ${tableName}
+  ALTER COLUMN ${quoteIdentifier(table.ownerColumn)} SET NOT NULL;
+
+CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${table.name}_owner_global_id_idx`)}
+  ON ${tableName} (${quoteIdentifier(table.ownerColumn)}, ${quoteIdentifier(table.globalIdColumn)});
+
+CREATE OR REPLACE FUNCTION ${qualified(metadataSchema, `touch_${table.name}`)}()
+RETURNS TRIGGER
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  NEW.${table.updatedAtColumn} := NOW();
+  IF TG_OP = 'INSERT' THEN
+    IF COALESCE(NEW.${table.globalIdColumn}, 0) <= 0 THEN
+      NEW.${table.globalIdColumn} := nextval(pg_get_serial_sequence('${qualified(metadataSchema, "global_mutation")}', 'global_id'));
+    END IF;
+  ELSE
+    IF COALESCE(NEW.${table.globalIdColumn}, 0) <= COALESCE(OLD.${table.globalIdColumn}, 0) THEN
+      NEW.${table.globalIdColumn} := nextval(pg_get_serial_sequence('${qualified(metadataSchema, "global_mutation")}', 'global_id'));
+    END IF;
+  END IF;
+  IF TG_OP = 'INSERT' THEN
+    NEW.${table.revisionColumn} := COALESCE(NEW.${table.revisionColumn}, 0) + 1;
+  ELSE
+    NEW.${table.revisionColumn} := OLD.${table.revisionColumn} + 1;
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS ${touchTriggerName} ON ${tableName};
+CREATE TRIGGER ${touchTriggerName}
+BEFORE INSERT OR UPDATE ON ${tableName}
+FOR EACH ROW
+EXECUTE FUNCTION ${qualified(metadataSchema, `touch_${table.name}`)}();
+
+DROP TRIGGER IF EXISTS ${changeTriggerName} ON ${tableName};
+CREATE TRIGGER ${changeTriggerName}
+AFTER INSERT OR UPDATE OR DELETE ON ${tableName}
+FOR EACH ROW
+EXECUTE FUNCTION ${qualified(metadataSchema, "record_change")}();
+
+ALTER TABLE ${tableName} ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS ${quoteIdentifier(`${table.name}_owner_select`)} ON ${tableName};
+CREATE POLICY ${quoteIdentifier(`${table.name}_owner_select`)} ON ${tableName}
+  FOR SELECT
+  USING (${quoteIdentifier(table.ownerColumn)} = ${qualified(metadataSchema, "current_user_id")}());
+
+DROP POLICY IF EXISTS ${quoteIdentifier(`${table.name}_owner_insert`)} ON ${tableName};
+CREATE POLICY ${quoteIdentifier(`${table.name}_owner_insert`)} ON ${tableName}
+  FOR INSERT
+  WITH CHECK (${quoteIdentifier(table.ownerColumn)} = ${qualified(metadataSchema, "current_user_id")}());
+
+DROP POLICY IF EXISTS ${quoteIdentifier(`${table.name}_owner_write`)} ON ${tableName};
+CREATE POLICY ${quoteIdentifier(`${table.name}_owner_write`)} ON ${tableName}
+  FOR UPDATE
+  USING (${quoteIdentifier(table.ownerColumn)} = ${qualified(metadataSchema, "current_user_id")}())
+  WITH CHECK (${quoteIdentifier(table.ownerColumn)} = ${qualified(metadataSchema, "current_user_id")}());
+
+DROP POLICY IF EXISTS ${quoteIdentifier(`${table.name}_owner_delete`)} ON ${tableName};
+CREATE POLICY ${quoteIdentifier(`${table.name}_owner_delete`)} ON ${tableName}
+  FOR DELETE
+  USING (${quoteIdentifier(table.ownerColumn)} = ${qualified(metadataSchema, "current_user_id")}());
+
+CREATE OR REPLACE FUNCTION ${mutateFunctionName}(
+  p_local_id TEXT,
+  p_row_key TEXT,
+  p_base_revision BIGINT,
+  p_values JSONB
+)
+RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY INVOKER
+AS $$
+DECLARE
+  existing_row ${tableName}%ROWTYPE;
+  next_row ${tableName}%ROWTYPE;
+  set_clause TEXT;
+  upsert_sql TEXT;
+BEGIN
+  SELECT *
+  INTO existing_row
+  FROM ${tableName}
+  WHERE ${table.primaryKey}::TEXT = p_row_key
+  FOR UPDATE;
+
+  IF FOUND AND existing_row.${table.revisionColumn} <> p_base_revision THEN
+    RETURN jsonb_build_object(
+      'ok', false,
+      'code', 'revision_conflict',
+      'row', to_jsonb(existing_row)
+    );
+  END IF;
+
+  INSERT INTO ${qualified(metadataSchema, "applied_mutation")} (user_id, local_id, table_name, row_key)
+  VALUES (${qualified(metadataSchema, "current_user_id")}(), p_local_id, ${quoteText(table.name)}, p_row_key)
+  ON CONFLICT (user_id, local_id) DO NOTHING;
+
+  SELECT string_agg(
+    format('%1$I = EXCLUDED.%1$I', column_name),
+    ', '
+    ORDER BY ordinal_position
+  )
+  INTO set_clause
+  FROM information_schema.columns
+  WHERE table_schema = ${quoteText(schema)}
+    AND table_name = ${quoteText(table.name)}
+    AND column_name <> ${quoteText(table.primaryKey)};
+
+  upsert_sql := format(
+    'INSERT INTO %1$s SELECT * FROM jsonb_populate_record(NULL::%1$s, $1) ON CONFLICT (%2$I) DO UPDATE SET %3$s RETURNING *',
+    ${quoteText(tableName)},
+    ${quoteText(table.primaryKey)},
+    set_clause
+  );
+
+  EXECUTE upsert_sql
+    USING jsonb_set(
+      jsonb_set(
+        jsonb_set(
+          p_values,
+          ${quoteText(`{${table.localIdColumn}}`)},
+          to_jsonb(p_local_id)
+        ),
+        ${quoteText(`{${table.ownerColumn}}`)},
+        to_jsonb(COALESCE(p_values ->> ${quoteText(table.ownerColumn)}, ${qualified(metadataSchema, "current_user_id")}()))
+      ),
+      ${quoteText(`{${table.globalIdColumn}}`)},
+      COALESCE(
+        p_values -> ${quoteText(table.globalIdColumn)},
+        '0'::jsonb
+      )
+    )
+    INTO next_row;
+
+  UPDATE ${qualified(metadataSchema, "applied_mutation")}
+  SET global_id = next_row.${table.globalIdColumn}
+  WHERE user_id = ${qualified(metadataSchema, "current_user_id")}()
+    AND local_id = p_local_id;
+
+  RETURN jsonb_build_object(
+    'ok', true,
+    'localId', p_local_id,
+    'globalId', next_row.${table.globalIdColumn},
+    'row', to_jsonb(next_row)
+  );
+END;
+$$;
+`.trim();
+}
+
+function assertIdentifier(value, label) {
+  if (typeof value !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new Error(`Invalid ${label}: ${String(value)}`);
+  }
+
+  return value;
+}
+
+function quoteIdentifier(value) {
+  return `"${value.replaceAll('"', '""')}"`;
+}
+
+function quoteText(value) {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function qualified(schema, name) {
+  return `${quoteIdentifier(schema)}.${quoteIdentifier(name)}`;
+}
+