synqlite 0.1.0

package/dist/index.cjs

@@ -0,0 +1,241 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SynqliteClient: () => SynqliteClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var WRITE_PREFIXES = ["INSERT", "UPDATE", "DELETE", "CREATE", "DROP", "ALTER"];
+function isWriteQuery(sql) {
+  const trimmed = sql.trim().toUpperCase();
+  return WRITE_PREFIXES.some((p) => trimmed.startsWith(p));
+}
+var SynqliteClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = "https://api.synqlite.io";
+  }
+  async request(path, options = {}) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body?.error?.message ?? `Request failed: ${res.status}`);
+    }
+    return res.json();
+  }
+  async requestRaw(path) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body?.error?.message ?? `Request failed: ${res.status}`);
+    }
+    return res;
+  }
+  async listDatabases() {
+    return this.request("/v1/databases");
+  }
+  async createDatabase(name) {
+    return this.request("/v1/databases", {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
+  async deleteDatabase(id) {
+    await this.request(`/v1/databases/${id}`, { method: "DELETE" });
+  }
+  async query(databaseId, sql, params) {
+    return this.request("/v1/query", {
+      method: "POST",
+      body: JSON.stringify({ databaseId, sql, params })
+    });
+  }
+  /** Remote-only database handle. Every query goes over the network. */
+  db(databaseId) {
+    return {
+      query: (sql, params) => this.query(databaseId, sql, params),
+      tables: async () => {
+        const result = await this.query(
+          databaseId,
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        );
+        return result.rows.map((r) => r.name);
+      }
+    };
+  }
+  /**
+   * Embedded replica with incremental sync.
+   *
+   * Downloads the database once on init, then uses a lightweight operation log
+   * to stay in sync. Reads run locally (~0ms). Writes go to the server, get
+   * applied locally immediately, and any concurrent changes from other writers
+   * are pulled automatically.
+   *
+   * Supports multiple concurrent writers (5-10) — the server serializes all
+   * writes and each replica replays the same ordered operation log.
+   *
+   * Requires `sql.js` as a peer dependency:
+   * ```
+   * npm install sql.js
+   * ```
+   */
+  async embeddedDb(databaseId, options = {}) {
+    const { syncInterval = 5e3 } = options;
+    const initSqlJs = await import("sql.js").then((m) => m.default ?? m);
+    const SQL = await initSqlJs();
+    let localDb = null;
+    let localSeq = 0;
+    let syncing = false;
+    let syncTimer = null;
+    const fullDownload = async () => {
+      const res = await this.requestRaw(`/v1/databases/${databaseId}/dump`);
+      const buf = await res.arrayBuffer();
+      const seq = Number(res.headers.get("X-Synqlite-Seq") ?? "0");
+      if (localDb) localDb.close();
+      localDb = new SQL.Database(new Uint8Array(buf));
+      localSeq = seq;
+    };
+    const applyLocal = (sql, params) => {
+      if (!localDb) return;
+      const stmt = localDb.prepare(sql);
+      if (params.length > 0) {
+        stmt.bind(params);
+      }
+      stmt.step();
+      stmt.free();
+    };
+    const incrementalSync = async () => {
+      if (syncing || !localDb) return;
+      syncing = true;
+      try {
+        const data = await this.request(
+          `/v1/databases/${databaseId}/changes?since=${localSeq}`
+        );
+        if (data.fullSync) {
+          await fullDownload();
+          return;
+        }
+        if (data.changes && data.changes.length > 0) {
+          for (const change of data.changes) {
+            if (change.seq <= localSeq) continue;
+            applyLocal(change.sql, change.params);
+          }
+          localSeq = data.currentSeq;
+        }
+      } finally {
+        syncing = false;
+      }
+    };
+    const executeLocal = (sql, params) => {
+      if (!localDb) throw new Error("Database is closed");
+      const start = performance.now();
+      const stmt = localDb.prepare(sql);
+      if (params && params.length > 0) {
+        stmt.bind(params);
+      }
+      const columns = stmt.getColumnNames();
+      const rows = [];
+      while (stmt.step()) {
+        const values = stmt.get();
+        const row = {};
+        columns.forEach((col, i) => {
+          row[col] = values[i];
+        });
+        rows.push(row);
+      }
+      stmt.free();
+      return {
+        columns,
+        rows,
+        rowsAffected: 0,
+        duration: Math.round(performance.now() - start)
+      };
+    };
+    await fullDownload();
+    if (syncInterval > 0) {
+      syncTimer = setInterval(() => {
+        incrementalSync().catch(() => {
+        });
+      }, syncInterval);
+    }
+    const handle = {
+      get localSeq() {
+        return localSeq;
+      },
+      query: async (sql, params) => {
+        if (isWriteQuery(sql)) {
+          const result = await this.query(databaseId, sql, params);
+          applyLocal(sql, params ?? []);
+          if (result.seq !== void 0) {
+            localSeq = result.seq;
+          }
+          await incrementalSync();
+          return result;
+        }
+        return executeLocal(sql, params);
+      },
+      tables: async () => {
+        const result = executeLocal(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        );
+        return result.rows.map((r) => r.name);
+      },
+      sync: () => incrementalSync(),
+      close: () => {
+        if (syncTimer) {
+          clearInterval(syncTimer);
+          syncTimer = null;
+        }
+        if (localDb) {
+          localDb.close();
+          localDb = null;
+        }
+      }
+    };
+    return handle;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SynqliteClient
+});

package/dist/index.d.cts

@@ -0,0 +1,66 @@
+interface SynqliteConfig {
+    apiKey: string;
+}
+interface Database {
+    id: string;
+    name: string;
+    slug: string;
+    sizeBytes: number;
+    createdAt: string;
+}
+interface QueryResult<T = Record<string, unknown>> {
+    columns: string[];
+    rows: T[];
+    rowsAffected: number;
+    duration: number;
+    /** Server sequence number (present for write queries) */
+    seq?: number;
+}
+interface DatabaseHandle {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    tables(): Promise<string[]>;
+}
+interface EmbeddedDatabaseHandle extends DatabaseHandle {
+    /** Pull the latest changes from the server (incremental sync) */
+    sync(): Promise<void>;
+    /** Close the local database and free memory */
+    close(): void;
+    /** Current local sequence number */
+    readonly localSeq: number;
+}
+interface EmbeddedOptions {
+    /** Auto-sync interval in milliseconds. Set to 0 to disable. Default: 5000 */
+    syncInterval?: number;
+}
+declare class SynqliteClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: SynqliteConfig);
+    private request;
+    private requestRaw;
+    listDatabases(): Promise<Database[]>;
+    createDatabase(name: string): Promise<Database>;
+    deleteDatabase(id: string): Promise<void>;
+    query<T = Record<string, unknown>>(databaseId: string, sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    /** Remote-only database handle. Every query goes over the network. */
+    db(databaseId: string): DatabaseHandle;
+    /**
+     * Embedded replica with incremental sync.
+     *
+     * Downloads the database once on init, then uses a lightweight operation log
+     * to stay in sync. Reads run locally (~0ms). Writes go to the server, get
+     * applied locally immediately, and any concurrent changes from other writers
+     * are pulled automatically.
+     *
+     * Supports multiple concurrent writers (5-10) — the server serializes all
+     * writes and each replica replays the same ordered operation log.
+     *
+     * Requires `sql.js` as a peer dependency:
+     * ```
+     * npm install sql.js
+     * ```
+     */
+    embeddedDb(databaseId: string, options?: EmbeddedOptions): Promise<EmbeddedDatabaseHandle>;
+}
+
+export { type Database, type DatabaseHandle, type EmbeddedDatabaseHandle, type EmbeddedOptions, type QueryResult, SynqliteClient, type SynqliteConfig };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+interface SynqliteConfig {
+    apiKey: string;
+}
+interface Database {
+    id: string;
+    name: string;
+    slug: string;
+    sizeBytes: number;
+    createdAt: string;
+}
+interface QueryResult<T = Record<string, unknown>> {
+    columns: string[];
+    rows: T[];
+    rowsAffected: number;
+    duration: number;
+    /** Server sequence number (present for write queries) */
+    seq?: number;
+}
+interface DatabaseHandle {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    tables(): Promise<string[]>;
+}
+interface EmbeddedDatabaseHandle extends DatabaseHandle {
+    /** Pull the latest changes from the server (incremental sync) */
+    sync(): Promise<void>;
+    /** Close the local database and free memory */
+    close(): void;
+    /** Current local sequence number */
+    readonly localSeq: number;
+}
+interface EmbeddedOptions {
+    /** Auto-sync interval in milliseconds. Set to 0 to disable. Default: 5000 */
+    syncInterval?: number;
+}
+declare class SynqliteClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: SynqliteConfig);
+    private request;
+    private requestRaw;
+    listDatabases(): Promise<Database[]>;
+    createDatabase(name: string): Promise<Database>;
+    deleteDatabase(id: string): Promise<void>;
+    query<T = Record<string, unknown>>(databaseId: string, sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+    /** Remote-only database handle. Every query goes over the network. */
+    db(databaseId: string): DatabaseHandle;
+    /**
+     * Embedded replica with incremental sync.
+     *
+     * Downloads the database once on init, then uses a lightweight operation log
+     * to stay in sync. Reads run locally (~0ms). Writes go to the server, get
+     * applied locally immediately, and any concurrent changes from other writers
+     * are pulled automatically.
+     *
+     * Supports multiple concurrent writers (5-10) — the server serializes all
+     * writes and each replica replays the same ordered operation log.
+     *
+     * Requires `sql.js` as a peer dependency:
+     * ```
+     * npm install sql.js
+     * ```
+     */
+    embeddedDb(databaseId: string, options?: EmbeddedOptions): Promise<EmbeddedDatabaseHandle>;
+}
+
+export { type Database, type DatabaseHandle, type EmbeddedDatabaseHandle, type EmbeddedOptions, type QueryResult, SynqliteClient, type SynqliteConfig };

package/dist/index.js

@@ -0,0 +1,204 @@
+// src/client.ts
+var WRITE_PREFIXES = ["INSERT", "UPDATE", "DELETE", "CREATE", "DROP", "ALTER"];
+function isWriteQuery(sql) {
+  const trimmed = sql.trim().toUpperCase();
+  return WRITE_PREFIXES.some((p) => trimmed.startsWith(p));
+}
+var SynqliteClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = "https://api.synqlite.io";
+  }
+  async request(path, options = {}) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        ...options.headers
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body?.error?.message ?? `Request failed: ${res.status}`);
+    }
+    return res.json();
+  }
+  async requestRaw(path) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body?.error?.message ?? `Request failed: ${res.status}`);
+    }
+    return res;
+  }
+  async listDatabases() {
+    return this.request("/v1/databases");
+  }
+  async createDatabase(name) {
+    return this.request("/v1/databases", {
+      method: "POST",
+      body: JSON.stringify({ name })
+    });
+  }
+  async deleteDatabase(id) {
+    await this.request(`/v1/databases/${id}`, { method: "DELETE" });
+  }
+  async query(databaseId, sql, params) {
+    return this.request("/v1/query", {
+      method: "POST",
+      body: JSON.stringify({ databaseId, sql, params })
+    });
+  }
+  /** Remote-only database handle. Every query goes over the network. */
+  db(databaseId) {
+    return {
+      query: (sql, params) => this.query(databaseId, sql, params),
+      tables: async () => {
+        const result = await this.query(
+          databaseId,
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        );
+        return result.rows.map((r) => r.name);
+      }
+    };
+  }
+  /**
+   * Embedded replica with incremental sync.
+   *
+   * Downloads the database once on init, then uses a lightweight operation log
+   * to stay in sync. Reads run locally (~0ms). Writes go to the server, get
+   * applied locally immediately, and any concurrent changes from other writers
+   * are pulled automatically.
+   *
+   * Supports multiple concurrent writers (5-10) — the server serializes all
+   * writes and each replica replays the same ordered operation log.
+   *
+   * Requires `sql.js` as a peer dependency:
+   * ```
+   * npm install sql.js
+   * ```
+   */
+  async embeddedDb(databaseId, options = {}) {
+    const { syncInterval = 5e3 } = options;
+    const initSqlJs = await import("sql.js").then((m) => m.default ?? m);
+    const SQL = await initSqlJs();
+    let localDb = null;
+    let localSeq = 0;
+    let syncing = false;
+    let syncTimer = null;
+    const fullDownload = async () => {
+      const res = await this.requestRaw(`/v1/databases/${databaseId}/dump`);
+      const buf = await res.arrayBuffer();
+      const seq = Number(res.headers.get("X-Synqlite-Seq") ?? "0");
+      if (localDb) localDb.close();
+      localDb = new SQL.Database(new Uint8Array(buf));
+      localSeq = seq;
+    };
+    const applyLocal = (sql, params) => {
+      if (!localDb) return;
+      const stmt = localDb.prepare(sql);
+      if (params.length > 0) {
+        stmt.bind(params);
+      }
+      stmt.step();
+      stmt.free();
+    };
+    const incrementalSync = async () => {
+      if (syncing || !localDb) return;
+      syncing = true;
+      try {
+        const data = await this.request(
+          `/v1/databases/${databaseId}/changes?since=${localSeq}`
+        );
+        if (data.fullSync) {
+          await fullDownload();
+          return;
+        }
+        if (data.changes && data.changes.length > 0) {
+          for (const change of data.changes) {
+            if (change.seq <= localSeq) continue;
+            applyLocal(change.sql, change.params);
+          }
+          localSeq = data.currentSeq;
+        }
+      } finally {
+        syncing = false;
+      }
+    };
+    const executeLocal = (sql, params) => {
+      if (!localDb) throw new Error("Database is closed");
+      const start = performance.now();
+      const stmt = localDb.prepare(sql);
+      if (params && params.length > 0) {
+        stmt.bind(params);
+      }
+      const columns = stmt.getColumnNames();
+      const rows = [];
+      while (stmt.step()) {
+        const values = stmt.get();
+        const row = {};
+        columns.forEach((col, i) => {
+          row[col] = values[i];
+        });
+        rows.push(row);
+      }
+      stmt.free();
+      return {
+        columns,
+        rows,
+        rowsAffected: 0,
+        duration: Math.round(performance.now() - start)
+      };
+    };
+    await fullDownload();
+    if (syncInterval > 0) {
+      syncTimer = setInterval(() => {
+        incrementalSync().catch(() => {
+        });
+      }, syncInterval);
+    }
+    const handle = {
+      get localSeq() {
+        return localSeq;
+      },
+      query: async (sql, params) => {
+        if (isWriteQuery(sql)) {
+          const result = await this.query(databaseId, sql, params);
+          applyLocal(sql, params ?? []);
+          if (result.seq !== void 0) {
+            localSeq = result.seq;
+          }
+          await incrementalSync();
+          return result;
+        }
+        return executeLocal(sql, params);
+      },
+      tables: async () => {
+        const result = executeLocal(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        );
+        return result.rows.map((r) => r.name);
+      },
+      sync: () => incrementalSync(),
+      close: () => {
+        if (syncTimer) {
+          clearInterval(syncTimer);
+          syncTimer = null;
+        }
+        if (localDb) {
+          localDb.close();
+          localDb = null;
+        }
+      }
+    };
+    return handle;
+  }
+};
+export {
+  SynqliteClient
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "synqlite",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "peerDependencies": {
+    "sql.js": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sql.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "@types/sql.js": "^1.4.9",
+    "sql.js": "^1.12.0"
+  }
+}