@powerdata/pd4 0.1.0

package/dist/index.cjs

@@ -0,0 +1,356 @@
+"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/index.ts
+var src_exports = {};
+__export(src_exports, {
+  PD4Buffer: () => PD4Buffer,
+  PD4Client: () => PD4Client,
+  PD4Error: () => PD4Error,
+  flattenRow: () => flattenRow,
+  toColumnValues: () => toColumnValues,
+  toColumnar: () => toColumnar
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+var PD4Error = class extends Error {
+  constructor(message, status, url) {
+    super(message);
+    this.name = "PD4Error";
+    this.status = status;
+    this.url = url;
+  }
+};
+
+// src/utils.ts
+function flattenRow(row) {
+  const flat = { _pk: row.key };
+  for (const cv of row.values) {
+    flat[cv.column] = cv.value;
+  }
+  return flat;
+}
+function toColumnar(flatRows, columnNames) {
+  if (flatRows.length === 0) return { columns: [], rows: [] };
+  const cols = columnNames ?? Object.keys(flatRows[0]).filter((k) => k !== "_pk");
+  const rows = flatRows.map((row) => cols.map((c) => row[c] ?? null));
+  return { columns: cols, rows };
+}
+function toColumnValues(flat) {
+  return Object.entries(flat).filter(([k]) => k !== "_pk").map(([column, value]) => ({ column, value }));
+}
+
+// src/buffer.ts
+var PD4Buffer = class {
+  constructor(client, handle, table) {
+    this.client = client;
+    this.handle = handle;
+    this.table = table;
+  }
+  /** Update a row within the buffer (not visible to others until commit). */
+  async update(key, values) {
+    const pairs = toColumnValues(values);
+    await this._request(`views/${this.handle}/rows/update`, {
+      method: "POST",
+      body: JSON.stringify({ key, values: pairs })
+    });
+  }
+  /** Fetch rows from the buffer (sees uncommitted changes). */
+  async fetch(offset = 0, limit = 100) {
+    const data = await this._request(
+      `views/${this.handle}/rows?offset=${offset}&limit=${limit}`
+    );
+    return {
+      rows: data.rows.map(flattenRow),
+      total: data.total
+    };
+  }
+  /** Commit all buffered writes atomically. Fires SSE events. */
+  async commit() {
+    await this._request(`views/${this.handle}/commit`, { method: "POST" });
+  }
+  /** Rollback all buffered writes (discard pending changes). */
+  async rollback() {
+    await this._request(`views/${this.handle}/rollback`, { method: "POST" });
+  }
+  // --- Internal ----------------------------------------------------------
+  async _request(path, init) {
+    const url = `${this.client.url}/v1/${this.client.db}/${path}`;
+    const res = await fetch(url, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init?.headers }
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`PD4 Buffer ${init?.method ?? "GET"} ${url}: ${res.status} ${text}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+};
+
+// src/client.ts
+var PD4Client = class {
+  constructor(url, db, options) {
+    this.eventSource = null;
+    this.handlers = /* @__PURE__ */ new Map();
+    this.statusHandlers = [];
+    this._status = "connecting";
+    this.url = url.replace(/\/$/, "");
+    this.db = db;
+    this.EventSourceCtor = options?.EventSource ?? (typeof globalThis !== "undefined" && globalThis.EventSource ? globalThis.EventSource : null);
+  }
+  // --- URL helpers -------------------------------------------------------
+  get v1() {
+    return `${this.url}/v1/${this.db}`;
+  }
+  get api() {
+    return `${this.url}/api/${this.db}`;
+  }
+  // --- HTTP helper -------------------------------------------------------
+  async request(url, init) {
+    const res = await fetch(url, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init?.headers }
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new PD4Error(
+        `PD4 ${init?.method ?? "GET"} ${url}: ${res.status} ${text}`,
+        res.status,
+        url
+      );
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  // --- Health ------------------------------------------------------------
+  /** Check if PD4 is reachable */
+  async ping() {
+    try {
+      const res = await fetch(`${this.url}/health`);
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+  // --- Database ----------------------------------------------------------
+  /** Ensure the database is open */
+  async ensureDatabase() {
+    await this.request(`${this.url}/v1/db`, {
+      method: "POST",
+      body: JSON.stringify({ name: this.db })
+    });
+  }
+  // --- Tables ------------------------------------------------------------
+  /** List all table names */
+  async listTables() {
+    const data = await this.request(`${this.v1}/tables`);
+    return data.tables;
+  }
+  /** Get table info */
+  async getTable(name) {
+    return this.request(`${this.v1}/tables/${name}`);
+  }
+  /** Create a table (with auto_pk) */
+  async createTable(name) {
+    await this.request(`${this.v1}/tables`, {
+      method: "POST",
+      body: JSON.stringify({ name, auto_pk: true })
+    });
+  }
+  /** Drop a table */
+  async dropTable(name) {
+    await this.request(`${this.v1}/tables/${name}`, { method: "DELETE" });
+  }
+  /** Add a column to a table */
+  async addColumn(table, name, dtype) {
+    await this.request(`${this.v1}/tables/${table}/columns`, {
+      method: "POST",
+      body: JSON.stringify({ name, dtype })
+    });
+  }
+  // --- Rows (flat objects in, flat objects out) ---------------------------
+  /** Insert one or more rows (flat objects). Returns keys and count. */
+  async insert(table, rows) {
+    const arr = Array.isArray(rows) ? rows : [rows];
+    const { columns, rows: colRows } = toColumnar(arr);
+    return this.request(`${this.v1}/tables/${table}/rows`, {
+      method: "POST",
+      body: JSON.stringify({ columns, rows: colRows })
+    });
+  }
+  /** Update a single row by key with a flat object of changed columns. */
+  async update(table, key, values) {
+    const pairs = toColumnValues(values);
+    await this.request(`${this.v1}/views/${table}/rows/update`, {
+      method: "POST",
+      body: JSON.stringify({ key, values: pairs })
+    });
+  }
+  /** Delete rows by keys. */
+  async delete(table, keys) {
+    const arr = Array.isArray(keys) ? keys : [keys];
+    await this.request(`${this.v1}/views/${table}/rows/delete`, {
+      method: "POST",
+      body: JSON.stringify({ keys: arr })
+    });
+  }
+  /** Fetch rows from a table/view. Returns flat Row objects. */
+  async fetch(table, opts) {
+    const offset = opts?.offset ?? 0;
+    const limit = opts?.limit ?? 1e3;
+    const data = await this.request(
+      `${this.v1}/views/${table}/rows?offset=${offset}&limit=${limit}`
+    );
+    return {
+      rows: data.rows.map(flattenRow),
+      total: data.total
+    };
+  }
+  // --- Raw row access (PD4 wire format) ----------------------------------
+  /** Insert rows in columnar format (low-level). */
+  async insertColumnar(table, columns, rows) {
+    return this.request(`${this.v1}/tables/${table}/rows`, {
+      method: "POST",
+      body: JSON.stringify({ columns, rows })
+    });
+  }
+  /** Update a row by key with column-value pairs (low-level). */
+  async updateRaw(table, key, values) {
+    await this.request(`${this.v1}/views/${table}/rows/update`, {
+      method: "POST",
+      body: JSON.stringify({ key, values })
+    });
+  }
+  /** Fetch rows in PD4 wire format (low-level). */
+  async fetchRaw(table, offset = 0, limit = 1e3) {
+    return this.request(`${this.v1}/views/${table}/rows?offset=${offset}&limit=${limit}`);
+  }
+  // --- Buffer ------------------------------------------------------------
+  /** Create a buffered view wrapping a table. */
+  async buffer(table) {
+    const info = await this.request(
+      `${this.v1}/views/${table}/buffer`,
+      { method: "POST" }
+    );
+    return new PD4Buffer(this, info.handle, table);
+  }
+  // --- SSE ---------------------------------------------------------------
+  /** Get current SSE connection status. */
+  get status() {
+    return this._status;
+  }
+  /** Connect to the SSE event stream. Called automatically on first on(). */
+  connect() {
+    if (this.eventSource) return;
+    if (!this.EventSourceCtor) {
+      throw new Error(
+        'EventSource is not available. In Node.js, pass { EventSource } from the "eventsource" package to the PD4Client constructor.'
+      );
+    }
+    this._setStatus("connecting");
+    const sse = new this.EventSourceCtor(`${this.api}/events`);
+    this.eventSource = sse;
+    sse.addEventListener("session", () => {
+      this._setStatus("connected");
+    });
+    sse.addEventListener("insert", (e) => {
+      const data = JSON.parse(e.data);
+      const table = data.handle;
+      const keys = data.keys ?? [];
+      const newValues = data.new_values ?? [];
+      this._dispatch(table, "insert", keys, newValues, []);
+    });
+    sse.addEventListener("update", (e) => {
+      const data = JSON.parse(e.data);
+      const table = data.handle;
+      const keys = data.keys ?? [];
+      const newValues = data.new_values ?? [];
+      const oldValues = data.old_values ?? [];
+      this._dispatch(table, "update", keys, newValues, oldValues);
+    });
+    sse.addEventListener("delete", (e) => {
+      const data = JSON.parse(e.data);
+      const table = data.handle;
+      const keys = data.keys ?? [];
+      this._dispatch(table, "delete", keys, [], []);
+    });
+    sse.onerror = () => {
+      this._setStatus("error");
+    };
+  }
+  /** Disconnect from the SSE event stream. */
+  disconnect() {
+    this.eventSource?.close();
+    this.eventSource = null;
+    this._setStatus("connecting");
+  }
+  on(table, event, handler) {
+    if (!this.eventSource) this.connect();
+    let tableHandlers = this.handlers.get(table);
+    if (!tableHandlers) {
+      tableHandlers = { insert: [], update: [], delete: [] };
+      this.handlers.set(table, tableHandlers);
+    }
+    const list = tableHandlers[event];
+    list.push(handler);
+    return () => {
+      const idx = list.indexOf(handler);
+      if (idx >= 0) list.splice(idx, 1);
+    };
+  }
+  /** Subscribe to connection status changes. Returns an unsubscribe function. */
+  onStatus(handler) {
+    this.statusHandlers.push(handler);
+    return () => {
+      const idx = this.statusHandlers.indexOf(handler);
+      if (idx >= 0) this.statusHandlers.splice(idx, 1);
+    };
+  }
+  // --- SSE internals -----------------------------------------------------
+  _setStatus(status) {
+    this._status = status;
+    for (const handler of this.statusHandlers) {
+      handler(status);
+    }
+  }
+  _dispatch(table, event, keys, newValues, oldValues) {
+    const tableHandlers = this.handlers.get(table);
+    if (!tableHandlers) return;
+    if (event === "insert") {
+      for (const h of tableHandlers.insert) h(keys, newValues);
+    } else if (event === "update") {
+      for (const h of tableHandlers.update) h(keys, newValues, oldValues);
+    } else {
+      for (const h of tableHandlers.delete) h(keys);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PD4Buffer,
+  PD4Client,
+  PD4Error,
+  flattenRow,
+  toColumnValues,
+  toColumnar
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/utils.ts","../src/buffer.ts","../src/client.ts"],"sourcesContent":["export { PD4Client } from './client'\nexport { PD4Buffer } from './buffer'\nexport { PD4Error } from './errors'\nexport { flattenRow, toColumnar, toColumnValues } from './utils'\nexport type {\n  ColumnInfo,\n  TableInfo,\n  ColumnValue,\n  PD4Row,\n  Row,\n  SseEventType,\n  ConnectionStatus,\n  InsertHandler,\n  UpdateHandler,\n  DeleteHandler,\n  StatusHandler,\n  FetchOptions,\n  FetchResult,\n  InsertResult,\n  BufferInfo,\n  ViewInfo,\n  PD4ClientOptions,\n} from './types'\n","/** Base error class for PD4 client errors */\nexport class PD4Error extends Error {\n  readonly status: number | undefined\n  readonly url: string | undefined\n\n  constructor(message: string, status?: number, url?: string) {\n    super(message)\n    this.name = 'PD4Error'\n    this.status = status\n    this.url = url\n  }\n}\n","import type { PD4Row, Row } from './types'\n\n/** Convert PD4 row format to flat record */\nexport function flattenRow(row: PD4Row): Row {\n  const flat: Row = { _pk: row.key }\n  for (const cv of row.values) {\n    flat[cv.column] = cv.value\n  }\n  return flat\n}\n\n/**\n * Convert flat row objects to PD4's columnar insert format.\n * Returns { columns, rows } suitable for the insert endpoint.\n */\nexport function toColumnar(\n  flatRows: Row[],\n  columnNames?: string[],\n): { columns: string[]; rows: (string | number | boolean | null)[][] } {\n  if (flatRows.length === 0) return { columns: [], rows: [] }\n  const cols = columnNames ?? Object.keys(flatRows[0]).filter((k) => k !== '_pk')\n  const rows = flatRows.map((row) => cols.map((c) => row[c] ?? null))\n  return { columns: cols, rows }\n}\n\n/**\n * Convert a flat row object to PD4's column-value pairs for update.\n * Filters out the _pk field.\n */\nexport function toColumnValues(\n  flat: Row,\n): { column: string; value: string | number | boolean | null }[] {\n  return Object.entries(flat)\n    .filter(([k]) => k !== '_pk')\n    .map(([column, value]) => ({ column, value }))\n}\n","import type { PD4Client } from './client'\nimport { flattenRow, toColumnValues } from './utils'\nimport type { Row, FetchResult, PD4Row } from './types'\n\n/**\n * A buffered view wrapping a PD4 table.\n * Changes are accumulated locally and only become visible\n * to other clients after commit().\n */\nexport class PD4Buffer {\n  private client: PD4Client\n  readonly handle: string\n  readonly table: string\n\n  constructor(client: PD4Client, handle: string, table: string) {\n    this.client = client\n    this.handle = handle\n    this.table = table\n  }\n\n  /** Update a row within the buffer (not visible to others until commit). */\n  async update(key: number, values: Row): Promise<void> {\n    const pairs = toColumnValues(values)\n    await this._request(`views/${this.handle}/rows/update`, {\n      method: 'POST',\n      body: JSON.stringify({ key, values: pairs }),\n    })\n  }\n\n  /** Fetch rows from the buffer (sees uncommitted changes). */\n  async fetch(offset = 0, limit = 100): Promise<FetchResult> {\n    const data = await this._request<{ rows: PD4Row[]; total: number }>(\n      `views/${this.handle}/rows?offset=${offset}&limit=${limit}`,\n    )\n    return {\n      rows: data.rows.map(flattenRow),\n      total: data.total,\n    }\n  }\n\n  /** Commit all buffered writes atomically. Fires SSE events. */\n  async commit(): Promise<void> {\n    await this._request(`views/${this.handle}/commit`, { method: 'POST' })\n  }\n\n  /** Rollback all buffered writes (discard pending changes). */\n  async rollback(): Promise<void> {\n    await this._request(`views/${this.handle}/rollback`, { method: 'POST' })\n  }\n\n  // --- Internal ----------------------------------------------------------\n\n  private async _request<T>(path: string, init?: RequestInit): Promise<T> {\n    const url = `${this.client.url}/v1/${this.client.db}/${path}`\n    const res = await fetch(url, {\n      ...init,\n      headers: { 'Content-Type': 'application/json', ...init?.headers },\n    })\n    if (!res.ok) {\n      const text = await res.text()\n      throw new Error(`PD4 Buffer ${init?.method ?? 'GET'} ${url}: ${res.status} ${text}`)\n    }\n    if (res.status === 204) return undefined as T\n    return res.json()\n  }\n}\n","import { PD4Error } from './errors'\nimport { flattenRow, toColumnar, toColumnValues } from './utils'\nimport { PD4Buffer } from './buffer'\nimport type {\n  ColumnInfo,\n  TableInfo,\n  PD4Row,\n  Row,\n  FetchOptions,\n  FetchResult,\n  InsertResult,\n  ConnectionStatus,\n  InsertHandler,\n  UpdateHandler,\n  DeleteHandler,\n  StatusHandler,\n  PD4ClientOptions,\n} from './types'\n\n// ---------------------------------------------------------------------------\n// Internal types for SSE handler registry\n// ---------------------------------------------------------------------------\n\ninterface TableHandlers {\n  insert: InsertHandler[]\n  update: UpdateHandler[]\n  delete: DeleteHandler[]\n}\n\n// ---------------------------------------------------------------------------\n// PD4Client\n// ---------------------------------------------------------------------------\n\nexport class PD4Client {\n  readonly url: string\n  readonly db: string\n\n  private EventSourceCtor: (new (url: string) => EventSource) | null\n  private eventSource: EventSource | null = null\n  private handlers = new Map<string, TableHandlers>()\n  private statusHandlers: StatusHandler[] = []\n  private _status: ConnectionStatus = 'connecting'\n\n  constructor(url: string, db: string, options?: PD4ClientOptions) {\n    this.url = url.replace(/\\/$/, '')\n    this.db = db\n    this.EventSourceCtor = options?.EventSource\n      ?? (typeof globalThis !== 'undefined' && globalThis.EventSource\n        ? globalThis.EventSource\n        : null)\n  }\n\n  // --- URL helpers -------------------------------------------------------\n\n  private get v1() {\n    return `${this.url}/v1/${this.db}`\n  }\n\n  private get api() {\n    return `${this.url}/api/${this.db}`\n  }\n\n  // --- HTTP helper -------------------------------------------------------\n\n  private async request<T>(url: string, init?: RequestInit): Promise<T> {\n    const res = await fetch(url, {\n      ...init,\n      headers: { 'Content-Type': 'application/json', ...init?.headers },\n    })\n    if (!res.ok) {\n      const text = await res.text()\n      throw new PD4Error(\n        `PD4 ${init?.method ?? 'GET'} ${url}: ${res.status} ${text}`,\n        res.status,\n        url,\n      )\n    }\n    if (res.status === 204) return undefined as T\n    return res.json()\n  }\n\n  // --- Health ------------------------------------------------------------\n\n  /** Check if PD4 is reachable */\n  async ping(): Promise<boolean> {\n    try {\n      const res = await fetch(`${this.url}/health`)\n      return res.ok\n    } catch {\n      return false\n    }\n  }\n\n  // --- Database ----------------------------------------------------------\n\n  /** Ensure the database is open */\n  async ensureDatabase(): Promise<void> {\n    await this.request(`${this.url}/v1/db`, {\n      method: 'POST',\n      body: JSON.stringify({ name: this.db }),\n    })\n  }\n\n  // --- Tables ------------------------------------------------------------\n\n  /** List all table names */\n  async listTables(): Promise<string[]> {\n    const data = await this.request<{ tables: string[] }>(`${this.v1}/tables`)\n    return data.tables\n  }\n\n  /** Get table info */\n  async getTable(name: string): Promise<TableInfo> {\n    return this.request<TableInfo>(`${this.v1}/tables/${name}`)\n  }\n\n  /** Create a table (with auto_pk) */\n  async createTable(name: string): Promise<void> {\n    await this.request(`${this.v1}/tables`, {\n      method: 'POST',\n      body: JSON.stringify({ name, auto_pk: true }),\n    })\n  }\n\n  /** Drop a table */\n  async dropTable(name: string): Promise<void> {\n    await this.request(`${this.v1}/tables/${name}`, { method: 'DELETE' })\n  }\n\n  /** Add a column to a table */\n  async addColumn(table: string, name: string, dtype: string): Promise<void> {\n    await this.request(`${this.v1}/tables/${table}/columns`, {\n      method: 'POST',\n      body: JSON.stringify({ name, dtype }),\n    })\n  }\n\n  // --- Rows (flat objects in, flat objects out) ---------------------------\n\n  /** Insert one or more rows (flat objects). Returns keys and count. */\n  async insert(table: string, rows: Row | Row[]): Promise<InsertResult> {\n    const arr = Array.isArray(rows) ? rows : [rows]\n    const { columns, rows: colRows } = toColumnar(arr)\n    return this.request<InsertResult>(`${this.v1}/tables/${table}/rows`, {\n      method: 'POST',\n      body: JSON.stringify({ columns, rows: colRows }),\n    })\n  }\n\n  /** Update a single row by key with a flat object of changed columns. */\n  async update(table: string, key: number, values: Row): Promise<void> {\n    const pairs = toColumnValues(values)\n    await this.request(`${this.v1}/views/${table}/rows/update`, {\n      method: 'POST',\n      body: JSON.stringify({ key, values: pairs }),\n    })\n  }\n\n  /** Delete rows by keys. */\n  async delete(table: string, keys: number | number[]): Promise<void> {\n    const arr = Array.isArray(keys) ? keys : [keys]\n    await this.request(`${this.v1}/views/${table}/rows/delete`, {\n      method: 'POST',\n      body: JSON.stringify({ keys: arr }),\n    })\n  }\n\n  /** Fetch rows from a table/view. Returns flat Row objects. */\n  async fetch(table: string, opts?: FetchOptions): Promise<FetchResult> {\n    const offset = opts?.offset ?? 0\n    const limit = opts?.limit ?? 1000\n    const data = await this.request<{ rows: PD4Row[]; total: number }>(\n      `${this.v1}/views/${table}/rows?offset=${offset}&limit=${limit}`,\n    )\n    return {\n      rows: data.rows.map(flattenRow),\n      total: data.total,\n    }\n  }\n\n  // --- Raw row access (PD4 wire format) ----------------------------------\n\n  /** Insert rows in columnar format (low-level). */\n  async insertColumnar(\n    table: string,\n    columns: string[],\n    rows: (string | number | boolean | null)[][],\n  ): Promise<InsertResult> {\n    return this.request<InsertResult>(`${this.v1}/tables/${table}/rows`, {\n      method: 'POST',\n      body: JSON.stringify({ columns, rows }),\n    })\n  }\n\n  /** Update a row by key with column-value pairs (low-level). */\n  async updateRaw(\n    table: string,\n    key: number,\n    values: { column: string; value: string | number | boolean | null }[],\n  ): Promise<void> {\n    await this.request(`${this.v1}/views/${table}/rows/update`, {\n      method: 'POST',\n      body: JSON.stringify({ key, values }),\n    })\n  }\n\n  /** Fetch rows in PD4 wire format (low-level). */\n  async fetchRaw(\n    table: string,\n    offset = 0,\n    limit = 1000,\n  ): Promise<{ rows: PD4Row[]; total: number }> {\n    return this.request(`${this.v1}/views/${table}/rows?offset=${offset}&limit=${limit}`)\n  }\n\n  // --- Buffer ------------------------------------------------------------\n\n  /** Create a buffered view wrapping a table. */\n  async buffer(table: string): Promise<PD4Buffer> {\n    const info = await this.request<{ handle: string; source: string; row_count: number }>(\n      `${this.v1}/views/${table}/buffer`,\n      { method: 'POST' },\n    )\n    return new PD4Buffer(this, info.handle, table)\n  }\n\n  // --- SSE ---------------------------------------------------------------\n\n  /** Get current SSE connection status. */\n  get status(): ConnectionStatus {\n    return this._status\n  }\n\n  /** Connect to the SSE event stream. Called automatically on first on(). */\n  connect(): void {\n    if (this.eventSource) return\n    if (!this.EventSourceCtor) {\n      throw new Error(\n        'EventSource is not available. In Node.js, pass { EventSource } from the \"eventsource\" package to the PD4Client constructor.',\n      )\n    }\n\n    this._setStatus('connecting')\n    const sse = new this.EventSourceCtor(`${this.api}/events`)\n    this.eventSource = sse\n\n    sse.addEventListener('session', () => {\n      this._setStatus('connected')\n    })\n\n    sse.addEventListener('insert', (e: MessageEvent) => {\n      const data = JSON.parse(e.data)\n      const table = data.handle as string\n      const keys: number[] = data.keys ?? []\n      const newValues: Row[] = data.new_values ?? []\n      this._dispatch(table, 'insert', keys, newValues, [])\n    })\n\n    sse.addEventListener('update', (e: MessageEvent) => {\n      const data = JSON.parse(e.data)\n      const table = data.handle as string\n      const keys: number[] = data.keys ?? []\n      const newValues: Row[] = data.new_values ?? []\n      const oldValues: Row[] = data.old_values ?? []\n      this._dispatch(table, 'update', keys, newValues, oldValues)\n    })\n\n    sse.addEventListener('delete', (e: MessageEvent) => {\n      const data = JSON.parse(e.data)\n      const table = data.handle as string\n      const keys: number[] = data.keys ?? []\n      this._dispatch(table, 'delete', keys, [], [])\n    })\n\n    sse.onerror = () => {\n      this._setStatus('error')\n    }\n  }\n\n  /** Disconnect from the SSE event stream. */\n  disconnect(): void {\n    this.eventSource?.close()\n    this.eventSource = null\n    this._setStatus('connecting')\n  }\n\n  /**\n   * Subscribe to SSE events for a table.\n   * Auto-connects on first call. Returns an unsubscribe function.\n   */\n  on(table: string, event: 'insert', handler: InsertHandler): () => void\n  on(table: string, event: 'update', handler: UpdateHandler): () => void\n  on(table: string, event: 'delete', handler: DeleteHandler): () => void\n  on(\n    table: string,\n    event: 'insert' | 'update' | 'delete',\n    handler: InsertHandler | UpdateHandler | DeleteHandler,\n  ): () => void {\n    // Auto-connect\n    if (!this.eventSource) this.connect()\n\n    let tableHandlers = this.handlers.get(table)\n    if (!tableHandlers) {\n      tableHandlers = { insert: [], update: [], delete: [] }\n      this.handlers.set(table, tableHandlers)\n    }\n\n    const list = tableHandlers[event] as unknown[]\n    list.push(handler)\n\n    return () => {\n      const idx = list.indexOf(handler)\n      if (idx >= 0) list.splice(idx, 1)\n    }\n  }\n\n  /** Subscribe to connection status changes. Returns an unsubscribe function. */\n  onStatus(handler: StatusHandler): () => void {\n    this.statusHandlers.push(handler)\n    return () => {\n      const idx = this.statusHandlers.indexOf(handler)\n      if (idx >= 0) this.statusHandlers.splice(idx, 1)\n    }\n  }\n\n  // --- SSE internals -----------------------------------------------------\n\n  private _setStatus(status: ConnectionStatus) {\n    this._status = status\n    for (const handler of this.statusHandlers) {\n      handler(status)\n    }\n  }\n\n  private _dispatch(\n    table: string,\n    event: 'insert' | 'update' | 'delete',\n    keys: number[],\n    newValues: Row[],\n    oldValues: Row[],\n  ) {\n    const tableHandlers = this.handlers.get(table)\n    if (!tableHandlers) return\n\n    if (event === 'insert') {\n      for (const h of tableHandlers.insert) h(keys, newValues)\n    } else if (event === 'update') {\n      for (const h of tableHandlers.update) h(keys, newValues, oldValues)\n    } else {\n      for (const h of tableHandlers.delete) h(keys)\n    }\n  }\n}\n\n// Re-export for convenience\nexport type { ColumnInfo, TableInfo, PD4Row, Row, FetchOptions, FetchResult, InsertResult }\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,185 @@
+/** PD4 column info from table details */
+interface ColumnInfo {
+    name: string;
+    dtype: string;
+}
+/** PD4 table info returned by GET /v1/tables/:name */
+interface TableInfo {
+    name: string;
+    columns: ColumnInfo[];
+    row_count: number;
+}
+/** A column-value pair in PD4's row format */
+interface ColumnValue {
+    column: string;
+    value: string | number | boolean | null;
+}
+/** A row as returned by PD4 */
+interface PD4Row {
+    key: number;
+    values: ColumnValue[];
+}
+/** Flat row for display: column name -> value, plus _pk */
+type Row = Record<string, string | number | boolean | null>;
+/** SSE event types */
+type SseEventType = 'insert' | 'update' | 'delete';
+/** SSE connection status */
+type ConnectionStatus = 'connecting' | 'connected' | 'error';
+/** Callback for insert events: (keys, rows) */
+type InsertHandler = (keys: number[], rows: Row[]) => void;
+/** Callback for update events: (keys, newValues, oldValues) */
+type UpdateHandler = (keys: number[], newValues: Row[], oldValues: Row[]) => void;
+/** Callback for delete events: (keys) */
+type DeleteHandler = (keys: number[]) => void;
+/** Callback for status changes */
+type StatusHandler = (status: ConnectionStatus) => void;
+/** Options for fetch */
+interface FetchOptions {
+    offset?: number;
+    limit?: number;
+}
+/** Result from fetch */
+interface FetchResult {
+    rows: Row[];
+    total: number;
+}
+/** Result from insert */
+interface InsertResult {
+    keys: number[];
+    count: number;
+}
+/** Buffer info returned when opening a buffer */
+interface BufferInfo {
+    handle: string;
+    source: string;
+    row_count: number;
+}
+/** View info returned when opening a session view */
+interface ViewInfo {
+    handle: string;
+    row_count: number;
+}
+/** Constructor options for PD4Client */
+interface PD4ClientOptions {
+    /**
+     * Custom EventSource constructor for environments without a global EventSource
+     * (e.g. Node.js). Pass the `EventSource` class from the `eventsource` npm package.
+     */
+    EventSource?: new (url: string) => EventSource;
+}
+
+/**
+ * A buffered view wrapping a PD4 table.
+ * Changes are accumulated locally and only become visible
+ * to other clients after commit().
+ */
+declare class PD4Buffer {
+    private client;
+    readonly handle: string;
+    readonly table: string;
+    constructor(client: PD4Client, handle: string, table: string);
+    /** Update a row within the buffer (not visible to others until commit). */
+    update(key: number, values: Row): Promise<void>;
+    /** Fetch rows from the buffer (sees uncommitted changes). */
+    fetch(offset?: number, limit?: number): Promise<FetchResult>;
+    /** Commit all buffered writes atomically. Fires SSE events. */
+    commit(): Promise<void>;
+    /** Rollback all buffered writes (discard pending changes). */
+    rollback(): Promise<void>;
+    private _request;
+}
+
+declare class PD4Client {
+    readonly url: string;
+    readonly db: string;
+    private EventSourceCtor;
+    private eventSource;
+    private handlers;
+    private statusHandlers;
+    private _status;
+    constructor(url: string, db: string, options?: PD4ClientOptions);
+    private get v1();
+    private get api();
+    private request;
+    /** Check if PD4 is reachable */
+    ping(): Promise<boolean>;
+    /** Ensure the database is open */
+    ensureDatabase(): Promise<void>;
+    /** List all table names */
+    listTables(): Promise<string[]>;
+    /** Get table info */
+    getTable(name: string): Promise<TableInfo>;
+    /** Create a table (with auto_pk) */
+    createTable(name: string): Promise<void>;
+    /** Drop a table */
+    dropTable(name: string): Promise<void>;
+    /** Add a column to a table */
+    addColumn(table: string, name: string, dtype: string): Promise<void>;
+    /** Insert one or more rows (flat objects). Returns keys and count. */
+    insert(table: string, rows: Row | Row[]): Promise<InsertResult>;
+    /** Update a single row by key with a flat object of changed columns. */
+    update(table: string, key: number, values: Row): Promise<void>;
+    /** Delete rows by keys. */
+    delete(table: string, keys: number | number[]): Promise<void>;
+    /** Fetch rows from a table/view. Returns flat Row objects. */
+    fetch(table: string, opts?: FetchOptions): Promise<FetchResult>;
+    /** Insert rows in columnar format (low-level). */
+    insertColumnar(table: string, columns: string[], rows: (string | number | boolean | null)[][]): Promise<InsertResult>;
+    /** Update a row by key with column-value pairs (low-level). */
+    updateRaw(table: string, key: number, values: {
+        column: string;
+        value: string | number | boolean | null;
+    }[]): Promise<void>;
+    /** Fetch rows in PD4 wire format (low-level). */
+    fetchRaw(table: string, offset?: number, limit?: number): Promise<{
+        rows: PD4Row[];
+        total: number;
+    }>;
+    /** Create a buffered view wrapping a table. */
+    buffer(table: string): Promise<PD4Buffer>;
+    /** Get current SSE connection status. */
+    get status(): ConnectionStatus;
+    /** Connect to the SSE event stream. Called automatically on first on(). */
+    connect(): void;
+    /** Disconnect from the SSE event stream. */
+    disconnect(): void;
+    /**
+     * Subscribe to SSE events for a table.
+     * Auto-connects on first call. Returns an unsubscribe function.
+     */
+    on(table: string, event: 'insert', handler: InsertHandler): () => void;
+    on(table: string, event: 'update', handler: UpdateHandler): () => void;
+    on(table: string, event: 'delete', handler: DeleteHandler): () => void;
+    /** Subscribe to connection status changes. Returns an unsubscribe function. */
+    onStatus(handler: StatusHandler): () => void;
+    private _setStatus;
+    private _dispatch;
+}
+
+/** Base error class for PD4 client errors */
+declare class PD4Error extends Error {
+    readonly status: number | undefined;
+    readonly url: string | undefined;
+    constructor(message: string, status?: number, url?: string);
+}
+
+/** Convert PD4 row format to flat record */
+declare function flattenRow(row: PD4Row): Row;
+/**
+ * Convert flat row objects to PD4's columnar insert format.
+ * Returns { columns, rows } suitable for the insert endpoint.
+ */
+declare function toColumnar(flatRows: Row[], columnNames?: string[]): {
+    columns: string[];
+    rows: (string | number | boolean | null)[][];
+};
+/**
+ * Convert a flat row object to PD4's column-value pairs for update.
+ * Filters out the _pk field.
+ */
+declare function toColumnValues(flat: Row): {
+    column: string;
+    value: string | number | boolean | null;
+}[];
+
+export { type BufferInfo, type ColumnInfo, type ColumnValue, type ConnectionStatus, type DeleteHandler, type FetchOptions, type FetchResult, type InsertHandler, type InsertResult, PD4Buffer, PD4Client, type PD4ClientOptions, PD4Error, type PD4Row, type Row, type SseEventType, type StatusHandler, type TableInfo, type UpdateHandler, type ViewInfo, flattenRow, toColumnValues, toColumnar };