@palbase/db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Palbase
+
+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/index.cjs

@@ -0,0 +1,647 @@
+"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 index_exports = {};
+__export(index_exports, {
+  DatabaseClient: () => DatabaseClient,
+  QueryBuilder: () => QueryBuilder,
+  TransactionClient: () => TransactionClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../../../modules/db/dist/chunk-AQ6ZQNXC.js
+var IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+function validateIdentifier(value, label) {
+  if (!IDENTIFIER_RE.test(value)) {
+    throw new Error(
+      `Invalid ${label}: "${value}". Identifiers must match ${IDENTIFIER_RE.source}`
+    );
+  }
+}
+var ColumnsClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /**
+   * Create a new column on the given table. Sends `POST /v1/meta/columns`.
+   *
+   * The column name is validated against the standard SQL identifier regex.
+   * The `type` field is forwarded as-is to postgres-meta — callers SHOULD
+   * restrict types to a known allowlist before calling this.
+   */
+  async create(def) {
+    validateIdentifier(def.name, "column name");
+    const response = await this.httpClient.request("POST", "/v1/meta/columns", {
+      body: def
+    });
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+  /**
+   * Drop a column. Sends `DELETE /v1/meta/columns/:tableId.:ordinalPosition`.
+   *
+   * postgres-meta identifies columns by `{tableId}.{ordinalPosition}` (the
+   * column's 1-based attnum within its table). Use `TablesClient.get(id)` to
+   * find a column id from a column name if needed.
+   */
+  async drop(columnId, options) {
+    if (!/^\d+\.\d+$/.test(columnId)) {
+      throw new Error(
+        `Invalid column id: "${columnId}". Expected format "{tableId}.{ordinalPosition}"`
+      );
+    }
+    const params = new URLSearchParams();
+    if (options?.cascade) {
+      params.set("cascade", "true");
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/v1/meta/columns/${columnId}?${queryString}` : `/v1/meta/columns/${columnId}`;
+    const response = await this.httpClient.request("DELETE", path);
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+};
+var SchemasClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async list() {
+    const response = await this.httpClient.request("GET", "/v1/meta/schemas");
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data ?? [];
+  }
+  async create(name) {
+    validateIdentifier(name, "schema name");
+    const response = await this.httpClient.request("POST", "/v1/meta/schemas", {
+      body: { name }
+    });
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+  async drop(name, options) {
+    validateIdentifier(name, "schema name");
+    const schemas = await this.list();
+    const schema = schemas.find((s) => s.name === name);
+    if (!schema) {
+      throw new Error(`Schema "${name}" not found`);
+    }
+    const params = new URLSearchParams();
+    if (options?.cascade) {
+      params.set("cascade", "true");
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/v1/meta/schemas/${schema.id}?${queryString}` : `/v1/meta/schemas/${schema.id}`;
+    const response = await this.httpClient.request("DELETE", path);
+    if (response.error) {
+      throw response.error;
+    }
+  }
+};
+var TablesClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options?.schema) {
+      validateIdentifier(options.schema, "schema name");
+      params.set("included_schemas", options.schema);
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/v1/meta/tables?${queryString}` : "/v1/meta/tables";
+    const response = await this.httpClient.request("GET", path);
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data ?? [];
+  }
+  async get(id) {
+    const response = await this.httpClient.request("GET", `/v1/meta/tables/${id}`);
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+  async create(def) {
+    validateIdentifier(def.name, "table name");
+    if (def.schema) {
+      validateIdentifier(def.schema, "schema name");
+    }
+    const response = await this.httpClient.request("POST", "/v1/meta/tables", {
+      body: def
+    });
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+  /**
+   * Apply table-level updates (rename, schema move, RLS toggle, comment, etc).
+   * Sends `PATCH /v1/meta/tables/:id`.
+   *
+   * Note: this does NOT add or drop columns. For column changes, use
+   * `ColumnsClient.create()` / `ColumnsClient.drop()`.
+   */
+  async update(id, patch) {
+    if (patch.name !== void 0) {
+      validateIdentifier(patch.name, "table name");
+    }
+    if (patch.schema !== void 0) {
+      validateIdentifier(patch.schema, "schema name");
+    }
+    if (patch.primary_keys) {
+      for (const pk of patch.primary_keys) {
+        validateIdentifier(pk.name, "primary key column name");
+      }
+    }
+    const response = await this.httpClient.request("PATCH", `/v1/meta/tables/${id}`, {
+      body: patch
+    });
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data;
+  }
+  async drop(id, options) {
+    const params = new URLSearchParams();
+    if (options?.cascade) {
+      params.set("cascade", "true");
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/v1/meta/tables/${id}?${queryString}` : `/v1/meta/tables/${id}`;
+    const response = await this.httpClient.request("DELETE", path);
+    if (response.error) {
+      throw response.error;
+    }
+  }
+};
+var AdminClient = class {
+  schemas;
+  tables;
+  columns;
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+    this.schemas = new SchemasClient(httpClient);
+    this.tables = new TablesClient(httpClient);
+    this.columns = new ColumnsClient(httpClient);
+  }
+  /**
+   * Execute a raw SQL query with full privileges (service role).
+   *
+   * Always use parameterized queries to prevent SQL injection.
+   * Never interpolate user input directly into the SQL string.
+   *
+   * @example
+   * ```ts
+   * // GOOD — parameterized
+   * await admin.query('SELECT * FROM users WHERE id = $1', [userId]);
+   *
+   * // BAD — string interpolation (SQL injection risk)
+   * await admin.query(`SELECT * FROM users WHERE id = '${userId}'`);
+   * ```
+   */
+  async query(sql, params) {
+    const response = await this.httpClient.request("POST", "/v1/meta/query", {
+      body: { query: sql, params }
+    });
+    if (response.error) {
+      throw response.error;
+    }
+    return response.data ?? [];
+  }
+};
+
+// ../../../modules/db/dist/index.js
+var import_core = require("@palbase/core");
+var TABLE_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+var COLUMN_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_.:\->#]*$/;
+function validateTableName(table) {
+  if (!TABLE_NAME_RE.test(table)) {
+    throw new Error(`Invalid table name: "${table}". Table names must match ${TABLE_NAME_RE.source}`);
+  }
+}
+function validateColumnName(column) {
+  if (!COLUMN_NAME_RE.test(column)) {
+    throw new Error(`Invalid column name: "${column}". Column names must match ${COLUMN_NAME_RE.source}`);
+  }
+}
+function encodeFilterValue(value) {
+  return String(value).replace(/[&#]/g, (c) => encodeURIComponent(c));
+}
+var SingleQueryBuilder = class {
+  constructor(builder) {
+    this.builder = builder;
+  }
+  builder;
+  then(onfulfilled, onrejected) {
+    return this.builder["execute"]().then(
+      (res) => onfulfilled ? onfulfilled(res) : res,
+      onrejected ?? void 0
+    );
+  }
+};
+var MaybeSingleQueryBuilder = class {
+  constructor(builder) {
+    this.builder = builder;
+  }
+  builder;
+  then(onfulfilled, onrejected) {
+    return this.builder["execute"]().then(
+      (res) => onfulfilled ? onfulfilled(res) : res,
+      onrejected ?? void 0
+    );
+  }
+};
+var QueryBuilder = class {
+  httpClient;
+  basePath;
+  signal;
+  state;
+  constructor(httpClient, table, options) {
+    validateTableName(table);
+    this.httpClient = httpClient;
+    this.basePath = options?.basePath ?? `/v1/db/${table}`;
+    this.signal = options?.signal;
+    this.state = {
+      method: "GET",
+      headers: {},
+      filters: [],
+      params: {},
+      isSingle: false,
+      isMaybeSingle: false
+    };
+  }
+  // --- Operation methods ---
+  select(columns) {
+    this.state = {
+      ...this.state,
+      // Only set GET if no mutation method (POST/PATCH/DELETE) is already set
+      // insert().select() should stay POST with Prefer: return=representation
+      method: this.state.body !== void 0 ? this.state.method : "GET",
+      params: { ...this.state.params, select: columns ?? "*" }
+    };
+    return this;
+  }
+  insert(data) {
+    this.state = {
+      ...this.state,
+      method: "POST",
+      body: data,
+      headers: {
+        ...this.state.headers,
+        Prefer: "return=representation"
+      }
+    };
+    return this;
+  }
+  update(data) {
+    this.state = {
+      ...this.state,
+      method: "PATCH",
+      body: data,
+      headers: {
+        ...this.state.headers,
+        Prefer: "return=representation"
+      }
+    };
+    return this;
+  }
+  delete() {
+    this.state = {
+      ...this.state,
+      method: "DELETE"
+    };
+    return this;
+  }
+  upsert(data) {
+    this.state = {
+      ...this.state,
+      method: "POST",
+      body: data,
+      headers: {
+        ...this.state.headers,
+        Prefer: "resolution=merge-duplicates,return=representation"
+      }
+    };
+    return this;
+  }
+  // --- Filter methods ---
+  eq(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=eq.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  neq(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=neq.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  gt(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=gt.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  gte(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=gte.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  lt(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=lt.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  lte(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=lte.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  like(column, pattern) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=like.${encodeFilterValue(pattern)}`]
+    };
+    return this;
+  }
+  ilike(column, pattern) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=ilike.${encodeFilterValue(pattern)}`]
+    };
+    return this;
+  }
+  in(column, values) {
+    validateColumnName(column);
+    const encoded = values.map((v) => encodeFilterValue(v).replace(/[),]/g, (c) => encodeURIComponent(c)));
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=in.(${encoded.join(",")})`]
+    };
+    return this;
+  }
+  is(column, value) {
+    validateColumnName(column);
+    this.state = {
+      ...this.state,
+      filters: [...this.state.filters, `${column}=is.${encodeFilterValue(value)}`]
+    };
+    return this;
+  }
+  // --- Modifier methods ---
+  order(column, options) {
+    validateColumnName(column);
+    const direction = options?.ascending === false ? "desc" : "asc";
+    this.state = {
+      ...this.state,
+      params: { ...this.state.params, order: `${column}.${direction}` }
+    };
+    return this;
+  }
+  limit(count) {
+    this.state = {
+      ...this.state,
+      params: { ...this.state.params, limit: String(count) }
+    };
+    return this;
+  }
+  range(from, to) {
+    this.state = {
+      ...this.state,
+      headers: {
+        ...this.state.headers,
+        Range: `${from}-${to}`
+      }
+    };
+    return this;
+  }
+  single() {
+    this.state = {
+      ...this.state,
+      isSingle: true,
+      headers: {
+        ...this.state.headers,
+        Accept: "application/vnd.pgrst.object+json"
+      }
+    };
+    return new SingleQueryBuilder(this);
+  }
+  maybeSingle() {
+    this.state = {
+      ...this.state,
+      isMaybeSingle: true,
+      headers: {
+        ...this.state.headers,
+        Accept: "application/vnd.pgrst.object+json"
+      }
+    };
+    return new MaybeSingleQueryBuilder(this);
+  }
+  // --- Execution ---
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  buildPath() {
+    const parts = [];
+    for (const [key, value] of Object.entries(this.state.params)) {
+      parts.push(`${key}=${value}`);
+    }
+    for (const filter of this.state.filters) {
+      parts.push(filter);
+    }
+    return parts.length > 0 ? `${this.basePath}?${parts.join("&")}` : this.basePath;
+  }
+  async execute() {
+    const path = this.buildPath();
+    const { method, body, headers } = this.state;
+    const response = await this.httpClient.request(method, path, {
+      body,
+      headers: Object.keys(headers).length > 0 ? headers : void 0,
+      signal: this.signal
+    });
+    if (this.state.isMaybeSingle && response.error && response.status === 406) {
+      return { data: null, error: null, status: 200 };
+    }
+    return response;
+  }
+};
+var DEFAULT_TIMEOUT_MS = 3e4;
+var TX_ID_RE = /^[a-zA-Z0-9_\-]+$/;
+var TransactionClient = class {
+  httpClient;
+  txId;
+  signal;
+  constructor(httpClient, txId, signal) {
+    this.httpClient = httpClient;
+    this.txId = txId;
+    this.signal = signal;
+  }
+  from(table) {
+    return new QueryBuilder(this.httpClient, table, {
+      basePath: `/v1/db/transaction/${this.txId}/query/${table}`,
+      signal: this.signal
+    });
+  }
+};
+async function executeTransaction(httpClient, fn, options) {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let txId;
+  try {
+    const beginResponse = await httpClient.request(
+      "POST",
+      "/v1/db/transaction/begin",
+      { signal: controller.signal }
+    );
+    if (beginResponse.error || !beginResponse.data) {
+      clearTimeout(timer);
+      return {
+        data: null,
+        error: beginResponse.error ?? new import_core.PalbaseError(
+          "transaction_error",
+          "Failed to begin transaction",
+          beginResponse.status
+        ),
+        status: beginResponse.status
+      };
+    }
+    txId = beginResponse.data.txId;
+    if (!TX_ID_RE.test(txId)) {
+      clearTimeout(timer);
+      return {
+        data: null,
+        error: new import_core.PalbaseError(
+          "transaction_error",
+          `Invalid transaction ID format: "${txId}"`,
+          0
+        ),
+        status: 0
+      };
+    }
+    const tx = new TransactionClient(httpClient, txId, controller.signal);
+    const result = await fn(tx);
+    const commitResponse = await httpClient.request(
+      "POST",
+      `/v1/db/transaction/${txId}/commit`,
+      { signal: controller.signal }
+    );
+    clearTimeout(timer);
+    if (commitResponse.error) {
+      return {
+        data: null,
+        error: commitResponse.error,
+        status: commitResponse.status
+      };
+    }
+    return { data: result, error: null, status: 200 };
+  } catch (error) {
+    clearTimeout(timer);
+    if (txId) {
+      try {
+        await httpClient.request(
+          "POST",
+          `/v1/db/transaction/${txId}/rollback`,
+          { signal: void 0 }
+        );
+      } catch {
+      }
+    }
+    if (error instanceof import_core.PalbaseError) {
+      return { data: null, error, status: error.status };
+    }
+    const isAbort = error instanceof DOMException && error.name === "AbortError";
+    const code = isAbort ? "transaction_timeout" : "transaction_error";
+    const message = isAbort ? `Transaction timed out after ${timeoutMs}ms` : error instanceof Error ? error.message : "Transaction failed";
+    const status = isAbort ? 408 : 0;
+    return {
+      data: null,
+      error: new import_core.PalbaseError(code, message, status),
+      status
+    };
+  }
+}
+var FN_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;
+var DatabaseClient = class {
+  httpClient;
+  pathPrefix;
+  admin;
+  constructor(httpClient, options) {
+    this.httpClient = httpClient;
+    this.pathPrefix = options?.pathPrefix ?? "/v1/db";
+    if (options?.enableAdmin) {
+      this.admin = new AdminClient(httpClient);
+    }
+  }
+  from(table) {
+    return new QueryBuilder(this.httpClient, table, {
+      basePath: `${this.pathPrefix}/${table}`
+    });
+  }
+  async rpc(fnName, params) {
+    if (!FN_NAME_RE.test(fnName)) {
+      throw new Error(`Invalid function name: "${fnName}". Function names must match ${FN_NAME_RE.source}`);
+    }
+    return this.httpClient.request("POST", `${this.pathPrefix}/rpc/${fnName}`, {
+      body: params
+    });
+  }
+  async transaction(fn, options) {
+    return executeTransaction(this.httpClient, fn, options);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DatabaseClient,
+  QueryBuilder,
+  TransactionClient
+});
+//# sourceMappingURL=index.cjs.map