@happyvertical/sql 0.102.2 → 0.102.4

package/dist/shared/postgres-dialect.d.ts

@@ -0,0 +1,153 @@
+/**
+ * PostgreSQL dialect logic shared by every adapter that speaks to a Postgres
+ * server: the `pg` adapter (`../postgres`) and the PGlite adapter
+ * (`../pglite`).
+ *
+ * Everything here runs on a {@link PostgresQueryExecutor}, so the SQL the two
+ * adapters emit is the same code rather than two copies that drift. The module
+ * must stay browser-safe: no `node:` built-ins and no import of `pg`, because
+ * the PGlite adapter's import graph reaches it.
+ */
+import type { QueryResult as BaseQueryResult, ColumnDefinitionWithName, DatabaseInterface, IndexDefinition, TableInterface, TableSchemaInfo, UpsertOptions, VectorCapabilities } from "./types.js";
+/** The one method every statement runs through. */
+export type PostgresQueryExecutor = {
+    query: (sql: string, values?: any[]) => Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+};
+export declare function normalizePostgresRawQuery(sql: string, values: any[]): {
+    sql: string;
+    values: any[];
+};
+export declare function createVectorCapabilities(pool: PostgresQueryExecutor): VectorCapabilities;
+/**
+ * Keeps the first PostgreSQL statement failure attached to a transaction.
+ *
+ * PostgreSQL reports every later statement in an aborted transaction as
+ * 25P02. Replacing the first failure with that generic state error hides the
+ * actionable code and diagnostics from callers, so the tracker rethrows the
+ * first failure whenever PostgreSQL reports 25P02, and exposes the recorded
+ * failure so a swallowed statement error cannot make COMMIT's implicit
+ * rollback look successful: PostgreSQL answers COMMIT on an aborted
+ * transaction with a ROLLBACK tag and no error.
+ *
+ * @param isStatementError - Recognizes the driver's server-reported error
+ *   class (`pg`'s or PGlite's `DatabaseError`). Anything else is an
+ *   unconfirmed failure — it may be the transport, not the statement.
+ */
+export declare function createTransactionErrorTracker(isStatementError: (error: unknown) => boolean): {
+    pending: Set<Promise<unknown>>;
+    preserve: (error: unknown) => unknown;
+    confirm: (query: unknown) => void;
+    track: <T>(operation: Promise<T>, query: unknown) => Promise<T>;
+    clearError: () => void;
+    drain: () => Promise<void>;
+    getError: () => unknown;
+    getUnconfirmedError: () => unknown;
+};
+/**
+ * What an adapter supplies to the shared dialect.
+ */
+export interface PostgresDialectHost {
+    /** Executor for statements outside any transaction. */
+    client: PostgresQueryExecutor;
+    /**
+     * Runs `work` inside a short transaction of its own. Used by a null-aware
+     * upsert issued outside a transaction, which needs its advisory lock and the
+     * following update/insert to share one.
+     */
+    runInTransaction<T>(work: (executor: PostgresQueryExecutor) => Promise<T>): Promise<T>;
+    /**
+     * Executor for read-only catalog probes (server version, index flags).
+     *
+     * A pooled adapter answers with the pool, so a failing probe cannot abort the
+     * caller's transaction. A single-connection adapter has no second connection
+     * and must answer with the executor it was handed.
+     */
+    probeExecutor(executor: PostgresQueryExecutor): PostgresQueryExecutor;
+}
+/** One level of nested-transaction queueing. */
+export interface NestedScope {
+    tail: Promise<void>;
+}
+/**
+ * Ambient scope tracking for nested transactions.
+ *
+ * With one, a nested callback may call the *outer* transaction handle and still
+ * be queued under its own scope (the `pg` adapter uses `AsyncLocalStorage`).
+ * Without one (browsers have no `AsyncLocalStorage`), each nested callback is
+ * handed a handle bound to its own scope instead, so nested work must use the
+ * handle it is given.
+ */
+export interface NestedScopeContext {
+    getStore(): NestedScope | undefined;
+    run<R>(scope: NestedScope, fn: () => R): R;
+}
+export type NestedTransaction = (<T>(callback: (tx: DatabaseInterface) => Promise<T>) => Promise<T>) & {
+    drain: () => Promise<void>;
+};
+/**
+ * Creates the dialect: every statement-level method plus nested-transaction
+ * and schema-introspection builders, all bound to `host`.
+ */
+export declare function createPostgresDialect(host: PostgresDialectHost): {
+    serializeRecord: (record: Record<string, any>) => Record<string, any>;
+    createClientMethods: (executor: PostgresQueryExecutor, inTransaction: boolean, serialize: (record: Record<string, any>) => Record<string, any>, clearTransactionError?: () => void) => {
+        insert: (table: string, data: Record<string, any> | Record<string, any>[]) => Promise<BaseQueryResult>;
+        get: (table: string, where: Record<string, any>) => Promise<Record<string, any> | null>;
+        list: (table: string, where: Record<string, any>) => Promise<Record<string, any>[]>;
+        update: (table: string, where: Record<string, any>, data: Record<string, any>) => Promise<BaseQueryResult>;
+        upsert: (table: string, conflictColumns: string[], data: Record<string, any>, options?: UpsertOptions) => Promise<BaseQueryResult>;
+        getOrInsert: (table: string, where: Record<string, any>, data: Record<string, any>) => Promise<Record<string, any>>;
+        delete: (table: string, where: Record<string, any>) => Promise<BaseQueryResult>;
+        count: (table: string, where?: Record<string, any>) => Promise<number>;
+        table: (tableName: string) => TableInterface;
+        many: (strings: TemplateStringsArray, ...vars: any[]) => Promise<Record<string, any>[]>;
+        single: (strings: TemplateStringsArray, ...vars: any[]) => Promise<Record<string, any> | null>;
+        pluck: (strings: TemplateStringsArray, ...vars: any[]) => Promise<any>;
+        execute: (strings: TemplateStringsArray, ...vars: any[]) => Promise<void>;
+        query: (sql: string, ...values: any[]) => Promise<{
+            rows: Record<string, any>[];
+            rowCount: number;
+        }>;
+        oo: (strings: TemplateStringsArray, ...vars: any[]) => Promise<Record<string, any>[]>;
+        oO: (strings: TemplateStringsArray, ...vars: any[]) => Promise<Record<string, any> | null>;
+        ox: (strings: TemplateStringsArray, ...vars: any[]) => Promise<any>;
+        xx: (strings: TemplateStringsArray, ...vars: any[]) => Promise<void>;
+        tableExists: (tableName: string) => Promise<boolean>;
+        syncSchema: (schema: string) => Promise<void>;
+    };
+    createNestedTransaction: (executor: PostgresQueryExecutor, scopeFor: (override?: NestedTransaction) => DatabaseInterface, clearTransactionError: () => void, scopes?: NestedScopeContext) => NestedTransaction;
+};
+/**
+ * Builds `getTableSchema` on top of a dialect's statement methods.
+ */
+export declare function createGetTableSchema(methods: {
+    many: (strings: TemplateStringsArray, ...vars: any[]) => Promise<Record<string, any>[]>;
+    tableExists: (tableName: string) => Promise<boolean>;
+}): (table: string) => Promise<TableSchemaInfo | null>;
+/**
+ * Builds the `alterTable` operations on top of a statement executor.
+ */
+export declare function createAlterTable(client: PostgresQueryExecutor): {
+    /**
+     * Adds a new column to an existing table
+     *
+     * @param table - Table name
+     * @param column - Column definition with name
+     * @returns Promise that resolves when column is added
+     * @throws Error if the alter operation fails
+     */
+    addColumn: (table: string, column: ColumnDefinitionWithName) => Promise<void>;
+    /**
+     * Adds a new index to an existing table
+     *
+     * @param table - Table name
+     * @param index - Index definition
+     * @returns Promise that resolves when index is created
+     * @throws Error if the create index operation fails
+     */
+    addIndex: (table: string, index: IndexDefinition) => Promise<void>;
+};
+//# sourceMappingURL=postgres-dialect.d.ts.map

package/dist/shared/postgres-dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-dialect.d.ts","sourceRoot":"","sources":["../../src/shared/postgres-dialect.ts"],"names":[],"mappings":"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"}

package/dist/shared/types.d.ts

@@ -93,7 +93,7 @@ export interface DatabaseOptions extends DatabaseCacheOptions {
      * How long a queued transaction waits for the connection, in milliseconds.
      *
      * Applies to the single-connection adapters — SQLite (both the LibSQL and
-     * native paths), DuckDB and JSON. Those drive one connection, so transactions
+     * native paths), DuckDB, JSON and PGlite. Those drive one connection, so transactions
      * run one at a time and an overlapping `transaction()` waits its turn.
      * PostgreSQL pools and ignores this.
      *
@@ -212,7 +212,7 @@ export interface JSONOptions extends DatabaseOptions {
      * How long a queued transaction waits for the connection, in milliseconds.
      *
      * Applies to the single-connection adapters — SQLite (both the LibSQL and
-     * native paths), DuckDB and JSON. Those drive one connection, so transactions
+     * native paths), DuckDB, JSON and PGlite. Those drive one connection, so transactions
      * run one at a time and an overlapping `transaction()` waits its turn.
      * PostgreSQL pools and ignores this.
      *
@@ -961,8 +961,8 @@ export interface DatabaseInterface {
      * parameter rather than opening a nested one.
      *
      * **Transactions are serialized per connection on the single-connection
-     * adapters** — SQLite (both paths), DuckDB and JSON drive one connection, and
-     * a connection can only be in one transaction at a time, so a concurrent
+     * adapters** — SQLite (both paths), DuckDB, JSON and PGlite drive one
+     * connection, and a connection can only be in one transaction at a time, so a concurrent
      * `transaction()` waits for the one in progress rather than corrupting it. A
      * queued call that waits longer than `transactionQueueTimeout` (30s by
      * default) rejects rather than stalling indefinitely. Re-entrant calls do not

package/metadata.json

@@ -17,6 +17,7 @@
     "externalHappyVertical": [],
     "external": [
       "@duckdb/node-api",
+      "@electric-sql/pglite",
       "@libsql/client",
       "@russellthehippo/honker-node",
       "@sqliteai/sqlite-vector",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/sql",
-  "version": "0.102.2",
+  "version": "0.102.4",
   "description": "Database interface with support for SQLite, PostgreSQL, and DuckDB",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,6 +36,10 @@
     "./backup": {
       "import": "./dist/backup/index.js",
       "types": "./dist/backup/index.d.ts"
+    },
+    "./pglite": {
+      "import": "./dist/pglite.js",
+      "types": "./dist/pglite.d.ts"
     }
   },
   "keywords": [],
@@ -43,16 +47,20 @@
   "license": "ISC",
   "dependencies": {
     "@duckdb/node-api": "1.4.3-r.3",
-    "@happyvertical/utils": "0.102.2",
+    "@happyvertical/utils": "0.102.4",
     "@libsql/client": "0.17.2",
     "pg": "^8.20.0",
     "sqlite-vss": "^0.1.2"
   },
   "peerDependencies": {
+    "@electric-sql/pglite": ">=0.5.0 <1",
     "@russellthehippo/honker-node": "^0.3.3",
     "@sqliteai/sqlite-vector": "^1.0.0"
   },
   "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
     "@russellthehippo/honker-node": {
       "optional": true
     },
@@ -61,6 +69,9 @@
     }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@electric-sql/pglite-pgvector": "^0.0.9",
+    "@types/emscripten": "^1.41.1",
     "@types/node": "25.0.10",
     "@types/pg": "^8.20.0",
     "typescript": "5.9.3",