@workglow/postgres 0.2.30 → 0.2.32

package/dist/storage/PostgresTabularStorage.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Pool } from "@workglow/postgres/storage";
 import { DataPortSchemaObject, FromSchema, JsonSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
-import { BaseSqlTabularStorage, ClientProvidedKeysOption, AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularSubscribeOptions, ValueOptionType } from "@workglow/storage";
+import { BaseSqlTabularStorage, ClientProvidedKeysOption, AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, ITabularMigration, ITabularMigrationApplier, Page, PageRequest, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularSubscribeOptions, ValueOptionType, type VectorIndexOptions } from "@workglow/storage";
 export declare const POSTGRES_TABULAR_REPOSITORY: import("@workglow/util").ServiceToken<AnyTabularStorage>;
 /**
  * A PostgreSQL-based tabular repository implementation that extends BaseSqlTabularStorage.
@@ -28,13 +28,29 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      *                    while each array creates a compound index with columns in the specified order.
      * @param clientProvidedKeys - How to handle client-provided values for auto-generated keys
      */
-    constructor(db: Pool, table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption);
+    constructor(db: Pool, table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], clientProvidedKeys?: ClientProvidedKeysOption, tabularMigrations?: ReadonlyArray<ITabularMigration>);
     /**
      * Initializes the database table with the required schema.
      * Creates the table if it doesn't exist with primary key and value columns.
      * Must be called before using any other methods.
      */
     setupDatabase(): Promise<void>;
+    private tableExistsAsync;
+    private createTableAndIndexes;
+    private createDeclaredIndexes;
+    /**
+     * Runs DDL inside the current transaction. Public so the `withTransaction`
+     * proxy can route the call to the tx-bound client by overriding `this.db`.
+     * Do not call directly; only via the applier's `executeSqlTx`.
+     */
+    runMigrationDdl(sql: string): Promise<void>;
+    /**
+     * Inserts a `(component, version)` row into the bookkeeping table on the
+     * current transaction's client. Public for the same reason as
+     * {@link runMigrationDdl}.
+     */
+    recordMigrationApplied(component: string, version: number, description: string | null): Promise<void>;
+    getMigrationApplier(): ITabularMigrationApplier | null;
     protected isVectorFormat(format?: string): boolean;
     protected getVectorDimensions(typeDef: JsonSchema): number | undefined;
     /**
@@ -80,28 +96,143 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
         dimension: number;
     }>;
     /**
-     * Creates vector-specific indexes (HNSW for pgvector)
-     * Called after table creation if vector columns exist
+     * Subclasses (e.g. {@link PostgresVectorStorage}) override this to tune the
+     * index built by {@link createVectorIndexes}. Returning `{}` (the default)
+     * requests HNSW with cosine distance and pgvector's built-in `m` /
+     * `efConstruction` defaults.
+     */
+    protected getVectorIndexOptions(): VectorIndexOptions;
+    /**
+     * Creates vector-specific indexes for pgvector.
+     *
+     * Called after table creation if vector columns exist. Honours the options
+     * returned by {@link getVectorIndexOptions} — HNSW (default, with optional
+     * `m` / `efConstruction` build-time tuning) or IVFFlat (when `lists` is
+     * provided). See {@link VectorIndexOptions} for recall/latency trade-offs.
      */
     protected createVectorIndexes(): Promise<void>;
+    /**
+     * Builds the parameterized `INSERT … ON CONFLICT … RETURNING *` SQL for a
+     * single entity, applying the auto-generated-key policy. Extracted so
+     * {@link put} and {@link putBulk} can share the column/parameter logic
+     * while routing the actual query through different connections (the pool
+     * vs. a transaction-bound client).
+     */
+    private buildPutSql;
+    /** Hydrate a row returned by Postgres back into entity-shaped JS values. */
+    private hydrateRow;
+    private acquireConnection;
+    /**
+     * Per-instance promise-chain mutex. Only meaningful on single-connection
+     * backends (PGlite / PGLitePool) — there `withTransaction` runs on the
+     * shared session and we need to keep external callers from slipping into
+     * the open transaction. On a real `pg.Pool` (anything exposing
+     * `connect()`) the mutex would serialize independent reads/writes that
+     * Postgres is happy to fan across separate pool clients, turning the
+     * pool's main benefit into a per-instance bottleneck — so we short-circuit
+     * to a no-op on that path. Real-pool isolation comes from
+     * `withTransaction` dedicating its own client via `pool.connect()`.
+     *
+     * The Proxy returned by {@link createTxView} routes back to the private
+     * `_*Internal` methods directly, so calls made *through* the `tx` handle
+     * inside `fn` do not deadlock against the mutex held by `withTransaction`.
+     */
+    private mutexChain;
+    private get serializeOps();
+    private mutex;
+    /**
+     * True while the parent instance is between `BEGIN` and `COMMIT`/`ROLLBACK`.
+     * Used only to fail fast when `fn` captures the *original* storage instead
+     * of the `tx` handle and tries to recursively call `withTransaction` —
+     * that would deadlock against its own mutex on the PGlite path. Calls
+     * routed through `tx` hit the proxy's `withTransaction` override before
+     * reaching here.
+     */
+    private inTransaction;
+    /**
+     * Emits a `put` event. Overridden on the {@link createTxView} proxy to
+     * push into a per-transaction buffer instead, so listeners never observe
+     * rows that are about to roll back.
+     */
+    protected emitPut(entity: Entity): void;
     /**
      * Stores or updates a row in the database.
      * Uses UPSERT (INSERT ... ON CONFLICT DO UPDATE) for atomic operations.
      *
      * @param entity - The entity to store (may be missing auto-generated keys)
      * @returns The entity with any server-generated fields updated
-     * @emits "put" event with the updated entity when successful
+     * @emits "put" event with the updated entity when successful (deferred until
+     *        commit if inside a {@link withTransaction})
      */
     put(entity: InsertType): Promise<Entity>;
+    private _putInternal;
     /**
-     * Stores multiple rows in the database in a bulk operation.
-     * Uses individual put calls to ensure auto-generated keys are handled correctly.
+     * Stores multiple rows atomically inside a single `BEGIN` / `COMMIT`. All
+     * inserts share one connection, which (a) reduces pool churn vs. a
+     * `Promise.all` fan-out, (b) gives all-or-nothing semantics, and (c) lets
+     * Postgres group the writes into a single commit with one fsync rather than
+     * one per row.
      *
-     * @param entities - Array of entities to store (may be missing auto-generated keys)
-     * @returns Array of entities with any server-generated fields updated
-     * @emits "put" event for each entity stored
+     * Per-row UPSERT — instead of a multi-VALUES insert — keeps the
+     * auto-generated key policy and `RETURNING *` shape identical to {@link put}
+     * and stays correct when a batch mixes rows that include the auto-gen key
+     * with rows that omit it.
+     *
+     * `put` events are deferred until after `COMMIT` so listeners do not see
+     * rows that are about to roll back. When this call is nested inside a
+     * {@link withTransaction}, deferral extends to that outer commit.
      */
     putBulk(entities: InsertType[]): Promise<Entity[]>;
+    private _putBulkInternal;
+    /**
+     * Build a Proxy view of `this` for the `withTransaction` callback. The
+     * proxy:
+     *
+     *   - Swaps `db` for the transaction-bound handle so every query inside
+     *     `fn` runs on it: the dedicated client returned by `pool.connect()`
+     *     for a real `pg.Pool`, or the shared session for PGlite/PGLitePool.
+     *   - Routes any public method `foo` whose private sibling `_fooInternal`
+     *     exists to that sibling, so calls made through `tx` bypass the
+     *     mutex (PGlite path) and do not deadlock. The naming convention is
+     *     the only sync mechanism — adding a public method with a matching
+     *     `_fooInternal` is enough; no explicit map to keep in step.
+     *   - Reports `inTransaction === true`, which is what
+     *     {@link _putBulkInternal} keys off to skip its own BEGIN/COMMIT
+     *     and run on the swapped `db` directly.
+     *   - Overrides {@link emitPut} to queue events on a per-transaction
+     *     buffer; the outer `withTransaction` flushes that buffer after
+     *     `COMMIT` (or discards on `ROLLBACK`).
+     *   - Throws on nested `withTransaction` — Postgres has no autonomous
+     *     `BEGIN`. Use SAVEPOINT directly for nested rollback boundaries.
+     */
+    private createTxView;
+    /**
+     * Runs `fn` inside a single Postgres transaction.
+     *
+     * **Real `pg.Pool`** — acquires a dedicated client via `pool.connect()`,
+     * runs `BEGIN`/`COMMIT`/`ROLLBACK` on that client, and routes every
+     * query inside `fn` through it. The parent storage instance keeps fanning
+     * external traffic across the pool, so external callers run *in parallel*
+     * with the open transaction (no per-instance mutex). This is the natural
+     * Postgres concurrency model.
+     *
+     * **PGlite / PGLitePool** — single underlying session: the parent's mutex
+     * is acquired for the duration of `fn` so external callers queue behind
+     * the transaction instead of slipping into it. `BEGIN`/`COMMIT` run on
+     * the shared `this.db`.
+     *
+     * `put` events emitted from inside `fn` (whether via `tx.put`,
+     * `tx.putBulk`, or any other writer) are buffered on a per-transaction
+     * queue and flushed to the parent's event emitter after `COMMIT`. If `fn`
+     * throws, the buffer is discarded along with the rolled-back rows so
+     * listeners never observe writes that did not actually commit.
+     *
+     * Recursive calls — either through the original instance or through `tx`
+     * — throw rather than reusing the outer transaction implicitly. Use
+     * SAVEPOINT directly for nested rollback boundaries.
+     */
+    withTransaction<T>(fn: (tx: this) => Promise<T>): Promise<T>;
+    private runInTransaction;
     /**
      * Retrieves a value from the database by its primary key.
      *
@@ -110,6 +241,7 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @emits "get" event with the key when successful
      */
     get(key: PrimaryKey): Promise<Entity | undefined>;
+    private _getInternal;
     /**
      * Deletes a row from the database.
      *
@@ -117,27 +249,32 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @emits "delete" event with the key when successful
      */
     delete(value: PrimaryKey | Entity): Promise<void>;
+    private _deleteInternal;
     /**
      * Retrieves all entries from the database table, with optional ordering, offset, and limit.
      * @param options - Optional ordering, limit, and offset options
      * @returns Promise resolving to an array of entries or undefined if not found
      */
     getAll(options?: QueryOptions<Entity>): Promise<Entity[] | undefined>;
+    private _getAllInternal;
     /**
      * Deletes all rows from the database table.
      * @emits "clearall" event when successful
      */
     deleteAll(): Promise<void>;
+    private _deleteAllInternal;
     /**
      * Returns the total number of rows in the database.
      *
      * @returns Promise resolving to the count of stored items
      */
     size(): Promise<number>;
+    private _sizeInternal;
     /**
      * Counts rows matching the specified search criteria.
      */
     count(criteria?: SearchCriteria<Entity>): Promise<number>;
+    private _countInternal;
     /**
      * Fetches a page of records from the repository.
      * @param offset - Number of records to skip
@@ -145,6 +282,7 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @returns Array of entities or undefined if no records found
      */
     getBulk(offset: number, limit: number): Promise<Entity[] | undefined>;
+    private _getBulkInternal;
     /**
      * Builds WHERE clause conditions from delete search criteria.
      * @param criteria - The search criteria object
@@ -154,6 +292,30 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
         whereClause: string;
         params: ValueOptionType[];
     };
+    /**
+     * Cursor-paginated read with keyset predicates pushed into SQL.
+     *
+     * Goes through {@link mutex} so on the single-connection PGlite path a
+     * `getPage` issued while a `withTransaction` is in flight queues behind
+     * the transaction's `BEGIN`/`COMMIT` instead of slipping in between them
+     * on the shared session. On a real `pg.Pool`, {@link mutex} is a no-op —
+     * page reads fan out to other pool clients in parallel as expected. The
+     * Proxy returned by {@link createTxView} auto-routes to
+     * {@link _getPageInternal} via the `_*Internal` naming convention, so
+     * calls made through `tx` bypass the mutex (which the transaction holds)
+     * and run on the transaction-bound `db`.
+     */
+    getPage(request?: PageRequest<Entity>): Promise<Page<Entity>>;
+    private _getPageInternal;
+    queryPage(criteria: SearchCriteria<Entity>, request?: PageRequest<Entity>): Promise<Page<Entity>>;
+    private _queryPageInternal;
+    private postgresDialect;
+    /**
+     * Like {@link buildSearchWhere} but also reports the next free placeholder
+     * index — the cursor-pagination machinery needs to chain its own predicates
+     * after the criteria block, so it has to know what `$N` to start at.
+     */
+    private buildSearchWhereWithIndex;
     /**
      * Deletes all entries matching the specified search criteria.
      * Supports multiple columns with optional comparison operators.
@@ -161,6 +323,7 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @param criteria - Object with column names as keys and values or SearchConditions
      */
     deleteSearch(criteria: DeleteSearchCriteria<Entity>): Promise<void>;
+    private _deleteSearchInternal;
     /**
      * Queries entries matching the specified search criteria with optional ordering, limit, and offset.
      *
@@ -169,6 +332,7 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @returns Array of matching entities or undefined if no matches found
      */
     query(criteria: SearchCriteria<Entity>, options?: QueryOptions<Entity>): Promise<Entity[] | undefined>;
+    private _queryInternal;
     /**
      * Queries entries matching the specified search criteria, returning only the selected columns.
      * Requires a covering index that satisfies the criteria, orderBy, and select columns.
@@ -179,6 +343,7 @@ export declare class PostgresTabularStorage<Schema extends DataPortSchemaObject,
      * @throws {CoveringIndexMissingError} when no registered index covers the query
      */
     queryIndex<K extends keyof Entity & string>(criteria: SearchCriteria<Entity>, options: CoveringIndexQueryOptions<Entity, K>): Promise<Pick<Entity, K>[]>;
+    private _queryIndexInternal;
     /**
      * Subscribes to changes in the repository.
      * NOT IMPLEMENTED for PostgreSQL storage.

package/dist/storage/PostgresTabularStorage.d.ts.map

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

package/dist/storage/PostgresVectorStorage.d.ts

@@ -6,12 +6,13 @@
 import type { Pool } from "@workglow/postgres/storage";
 import type { DataPortSchemaObject, FromSchema, TypedArray, TypedArrayConstructor, TypedArraySchemaOptions } from "@workglow/util/schema";
 import { PostgresTabularStorage } from "./PostgresTabularStorage";
-import type { HybridSearchOptions, IVectorStorage, VectorSearchOptions } from "@workglow/storage";
+import type { HybridSearchOptions, IVectorStorage, VectorIndexOptions, VectorSearchOptions } from "@workglow/storage";
 export declare class PostgresVectorStorage<Schema extends DataPortSchemaObject, PrimaryKeyNames extends ReadonlyArray<keyof Schema["properties"]>, Metadata extends Record<string, unknown> = Record<string, unknown>, Entity = FromSchema<Schema, TypedArraySchemaOptions>> extends PostgresTabularStorage<Schema, PrimaryKeyNames, Entity> implements IVectorStorage<Metadata, Schema, Entity, PrimaryKeyNames> {
     private vectorDimensions;
     private readonly vectorCtor;
     private vectorPropertyName;
     private metadataPropertyName;
+    private readonly indexOptions;
     /**
      * Creates a new PostgreSQL vector repository
      * @param db - PostgreSQL connection pool
@@ -21,15 +22,64 @@ export declare class PostgresVectorStorage<Schema extends DataPortSchemaObject,
      * @param indexes - Array of columns or column arrays to make searchable
      * @param dimensions - The number of dimensions of the vector
      * @param vectorCtor - TypedArray constructor used when hydrating vectors from SQL text (e.g. {@link Float32Array})
+     * @param indexOptions - Tuning for the pgvector index (HNSW vs IVFFlat,
+     *                       distance metric, m / efConstruction / lists / probes).
+     *                       See {@link VectorIndexOptions} for the recall/latency
+     *                       trade-offs. Defaults to HNSW with cosine distance and
+     *                       pgvector's built-in `m=16`, `efConstruction=64` defaults.
      */
-    constructor(db: Pool, table: string, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[] | undefined, dimensions: number, vectorCtor?: TypedArrayConstructor);
+    constructor(db: Pool, table: string, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[] | undefined, dimensions: number, vectorCtor?: TypedArrayConstructor, indexOptions?: VectorIndexOptions);
     getVectorDimensions(): number;
+    /** Exposes tuning to {@link PostgresTabularStorage.createVectorIndexes}. */
+    protected getVectorIndexOptions(): VectorIndexOptions;
+    /** Resolved distance metric for this storage (defaults to cosine). */
+    private get distance();
+    /**
+     * pgvector distance operators per metric:
+     *   - cosine:        `<=>`  → cosine distance ∈ [0, 2]
+     *   - l2 (euclidean): `<->` → L2 distance ∈ [0, ∞)
+     *   - ip (inner):     `<#>` → negative inner product (pgvector negates so
+     *                      smaller = "more similar", matching the other ops)
+     */
+    private get distanceOperator();
+    /**
+     * SQL fragment that converts the raw distance from {@link distanceOperator}
+     * into a "higher = more similar" score that the rest of the API exposes.
+     *
+     *   - cosine:  1 - cosine_distance       → similarity in [-1, 1]
+     *   - l2:      1 / (1 + l2_distance)     → ∈ (0, 1], 1 is exact match
+     *   - ip:      -(neg_inner_product)      → the actual dot product
+     */
+    private buildScoreExpr;
+    /**
+     * Returns the `efSearch` / `probes` values configured at construction time.
+     *
+     * NOTE: these are query-time GUCs and must be set on the active session.
+     * With a {@link Pool}, a connection is checked out per `pool.query()`, so a
+     * standalone `SET hnsw.ef_search = N` issued before a SELECT lands on a
+     * different client and has no effect. To apply them, callers should run
+     * search queries against a single checked-out client (using `pool.connect()`)
+     * inside a transaction with `SET LOCAL`, or set them at the role/database
+     * level via `ALTER ROLE ... SET hnsw.ef_search = N`.
+     */
+    getQueryTuning(): {
+        efSearch?: number;
+        probes?: number;
+    };
     similaritySearch(query: TypedArray, options?: VectorSearchOptions<Metadata>): Promise<Array<Entity & {
         score: number;
     }>>;
     hybridSearch(query: TypedArray, options: HybridSearchOptions<Metadata>): Promise<(Entity & {
         score: number;
     })[]>;
+    /**
+     * Throws if the configured distance metric isn't cosine. The in-memory
+     * fallback paths below only know how to compute cosine similarity; if
+     * pgvector is unavailable for an `l2`/`ip` storage, falling back would
+     * silently return wrong scores. Callers using non-cosine distances must
+     * keep pgvector working.
+     */
+    private assertFallbackSupportsDistance;
     private searchFallback;
     private hybridSearchFallback;
     private getPrimaryKeyWhereClause;

package/dist/storage/PostgresVectorStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PostgresVectorStorage.d.ts","sourceRoot":"","sources":["../../src/storage/PostgresVectorStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAoBlG,qBAAa,qBAAqB,CAChC,MAAM,SAAS,oBAAoB,EACnC,eAAe,SAAS,aAAa,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,EACjE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAEpD,SAAQ,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAC9D,YAAW,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC;IAEpE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,oBAAoB,CAA2B;IAEvD;;;;;;;;;OASG;IACH,YACE,EAAE,EAAE,IAAI,EACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,YAAK,EACrF,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,qBAAoC,EAcjD;IAEe,mBAAmB,IAAI,MAAM,CAE5C;IAEY,gBAAgB,CAC3B,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,mBAAmB,CAAC,QAAQ,CAAM,GAC1C,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAwE5C;IAEK,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC;eA1EzC,MAAM;UA8JxC;YAKa,cAAc;YA+Bd,oBAAoB;IA8ClC,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,aAAa;CAQtB"}
+{"version":3,"file":"PostgresVectorStorage.d.ts","sourceRoot":"","sources":["../../src/storage/PostgresVectorStorage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAOlE,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EAEd,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAoB3B,qBAAa,qBAAqB,CAChC,MAAM,SAAS,oBAAoB,EACnC,eAAe,SAAS,aAAa,CAAC,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC,EACjE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAEpD,SAAQ,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,CAC9D,YAAW,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC;IAEpE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,kBAAkB,CAAe;IACzC,OAAO,CAAC,oBAAoB,CAA2B;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD;;;;;;;;;;;;;;OAcG;IACH,YACE,EAAE,EAAE,IAAI,EACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,YAAK,EACrF,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,qBAAoC,EAChD,YAAY,GAAE,kBAAuB,EAetC;IAEe,mBAAmB,IAAI,MAAM,CAE5C;IAED,4EAA4E;IAC5E,UAAmB,qBAAqB,IAAI,kBAAkB,CAE7D;IAED,sEAAsE;IACtE,OAAO,KAAK,QAAQ,GAEnB;IAED;;;;;;OAMG;IACH,OAAO,KAAK,gBAAgB,GAS3B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAYtB;;;;;;;;;;OAUG;IACI,cAAc,IAAI;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAK9D;IAEY,gBAAgB,CAC3B,KAAK,EAAE,UAAU,EACjB,OAAO,GAAE,mBAAmB,CAAC,QAAQ,CAAM,GAC1C,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CA4F5C;IAEK,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,mBAAmB,CAAC,QAAQ,CAAC;eA9FzC,MAAM;UAyLxC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,8BAA8B;YAcxB,cAAc;YAiCd,oBAAoB;IA+ClC,OAAO,CAAC,wBAAwB;IAKhC,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,aAAa;CAQtB"}