@atscript/db-postgres 0.1.146 → 0.1.148

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
-import { TSqlFragment } from "@atscript/db-sql-tools";
+import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 
 //#region src/types.d.ts
 /**
@@ -89,7 +89,7 @@ declare class PostgresAdapter extends BaseDbAdapter {
   private _vectorThresholds;
   /**
    * Schema name for catalog queries and qualification — `@db.schema` of the
-   * bound table, or `null` (→ `'public'`, the same default the bound path
+   * bound table, or `null` (→ the connection's `current_schema()`, the same default the bound path
    * uses) when the table declares none or the adapter is an administrative
    * one with no readable (the name-taking schema-sync primitives run on such
    * an adapter).
@@ -108,6 +108,13 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * otherwise the pool-based driver.
    */
   private _exec;
+  /**
+   * Relational predicates (`$some` / `$none`) render as correlated
+   * `[NOT] EXISTS` subqueries — in reads and in mutation filters alike.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /** PostgreSQL enforces FK constraints natively. */
   supportsNativeForeignKeys(): boolean;
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -118,8 +125,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * server's tz database (an unknown one maps to `BUCKET_TZ_UNAVAILABLE`).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  supportsAggregateExpressions(): boolean;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
   onAfterFlatten(): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
@@ -140,22 +151,35 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * - 23503 = foreign_key_violation
    */
   private _wrapConstraintError;
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  private _mapConstraintError;
   private _extractFieldFromConstraint;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  supportsInsertIgnore(): boolean;
+  /**
+   * Batched `INSERT … VALUES (…), (…) ON CONFLICT DO NOTHING RETURNING <pk +
+   * unique key columns>`: one statement per chunk (a conflict never raises, so
+   * the surrounding transaction survives). Skipped rows are the ones missing
+   * from RETURNING — mapped back by key values, see {@link mapIgnoredBatch}.
+   * Each chunk runs inside a SAVEPOINT: when the mapping is ambiguous (a key
+   * the server returns in another form than it was sent) the chunk is rolled
+   * back to the savepoint and redone row by row with the same
+   * `ON CONFLICT DO NOTHING`, so the result is always exact.
+   */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
-  count(query: DbQuery): Promise<number>;
-  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   /**
-   * Maps PostgreSQL's unknown-zone error — SQLSTATE 22023
-   * (`invalid_parameter_value`), `time zone "…" not recognized` — raised by a
-   * calendar bucket's `AT TIME ZONE '<tz>'` to `BUCKET_TZ_UNAVAILABLE`. The
-   * zone passed the core's IANA validation, so the server's tz database is
-   * older than the runtime's. Other errors propagate unchanged.
+   * `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+   * window over `partitionBy` (the generic `$with` loader's per-parent page).
    */
-  private _wrapBucketZoneError;
+  findManyPerPartition(query: DbQuery, partitionBy: readonly string[]): Promise<Array<Record<string, unknown>>>;
+  count(query: DbQuery): Promise<number>;
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /** Physical primary-key columns (`@db.column` renames applied). */
+  private _pkColumns;
   /**
    * The predicate that narrows a single-row UPDATE/DELETE to the first row
    * matching `whereSql`: `<key> <op> (SELECT <cols> … LIMIT 1)`. Single-col
@@ -329,6 +353,8 @@ declare class PgDriver implements TPgDriver {
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
   exec(sql: string): Promise<void>;
   getConnection(): Promise<TPgConnection>;
+  private _closing?;
+  /** Idempotent: every call returns the first call's promise. */
   close(): Promise<void>;
 }
 //#endregion
@@ -342,8 +368,14 @@ declare class PgDriver implements TPgDriver {
  *
  * Case-insensitive columns (`@db.collate 'nocase'`) are handled by CITEXT
  * column type at the storage level — no query-side wrapping needed.
+ *
+ * Relational predicates (`$some` / `$none`) render as correlated `EXISTS`
+ * subqueries referencing the outer table by `opts.qualifier` (default: the
+ * source table) — a statement with an aliased FROM must pass its alias.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(filter: FilterExpr): TSqlFragment;
+declare function buildWhere(filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/index.d.ts
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
-import { TSqlFragment } from "@atscript/db-sql-tools";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { TFilterVisitorOptions, TSqlFragment } from "@atscript/db-sql-tools";
 import { TMetadataMap } from "@atscript/typescript/utils";
 
 //#region src/types.d.ts
@@ -89,7 +89,7 @@ declare class PostgresAdapter extends BaseDbAdapter {
   private _vectorThresholds;
   /**
    * Schema name for catalog queries and qualification — `@db.schema` of the
-   * bound table, or `null` (→ `'public'`, the same default the bound path
+   * bound table, or `null` (→ the connection's `current_schema()`, the same default the bound path
    * uses) when the table declares none or the adapter is an administrative
    * one with no readable (the name-taking schema-sync primitives run on such
    * an adapter).
@@ -108,6 +108,13 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * otherwise the pool-based driver.
    */
   private _exec;
+  /**
+   * Relational predicates (`$some` / `$none`) render as correlated
+   * `[NOT] EXISTS` subqueries — in reads and in mutation filters alike.
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /** PostgreSQL enforces FK constraints natively. */
   supportsNativeForeignKeys(): boolean;
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -118,8 +125,12 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * server's tz database (an unknown one maps to `BUCKET_TZ_UNAVAILABLE`).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  supportsAggregateExpressions(): boolean;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
   onAfterFlatten(): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
@@ -140,22 +151,35 @@ declare class PostgresAdapter extends BaseDbAdapter {
    * - 23503 = foreign_key_violation
    */
   private _wrapConstraintError;
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  private _mapConstraintError;
   private _extractFieldFromConstraint;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  supportsInsertIgnore(): boolean;
+  /**
+   * Batched `INSERT … VALUES (…), (…) ON CONFLICT DO NOTHING RETURNING <pk +
+   * unique key columns>`: one statement per chunk (a conflict never raises, so
+   * the surrounding transaction survives). Skipped rows are the ones missing
+   * from RETURNING — mapped back by key values, see {@link mapIgnoredBatch}.
+   * Each chunk runs inside a SAVEPOINT: when the mapping is ambiguous (a key
+   * the server returns in another form than it was sent) the chunk is rolled
+   * back to the savepoint and redone row by row with the same
+   * `ON CONFLICT DO NOTHING`, so the result is always exact.
+   */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
-  count(query: DbQuery): Promise<number>;
-  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   /**
-   * Maps PostgreSQL's unknown-zone error — SQLSTATE 22023
-   * (`invalid_parameter_value`), `time zone "…" not recognized` — raised by a
-   * calendar bucket's `AT TIME ZONE '<tz>'` to `BUCKET_TZ_UNAVAILABLE`. The
-   * zone passed the core's IANA validation, so the server's tz database is
-   * older than the runtime's. Other errors propagate unchanged.
+   * `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+   * window over `partitionBy` (the generic `$with` loader's per-parent page).
    */
-  private _wrapBucketZoneError;
+  findManyPerPartition(query: DbQuery, partitionBy: readonly string[]): Promise<Array<Record<string, unknown>>>;
+  count(query: DbQuery): Promise<number>;
+  aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /** Physical primary-key columns (`@db.column` renames applied). */
+  private _pkColumns;
   /**
    * The predicate that narrows a single-row UPDATE/DELETE to the first row
    * matching `whereSql`: `<key> <op> (SELECT <cols> … LIMIT 1)`. Single-col
@@ -329,6 +353,8 @@ declare class PgDriver implements TPgDriver {
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
   exec(sql: string): Promise<void>;
   getConnection(): Promise<TPgConnection>;
+  private _closing?;
+  /** Idempotent: every call returns the first call's promise. */
   close(): Promise<void>;
 }
 //#endregion
@@ -342,8 +368,14 @@ declare class PgDriver implements TPgDriver {
  *
  * Case-insensitive columns (`@db.collate 'nocase'`) are handled by CITEXT
  * column type at the storage level — no query-side wrapping needed.
+ *
+ * Relational predicates (`$some` / `$none`) render as correlated `EXISTS`
+ * subqueries referencing the outer table by `opts.qualifier` (default: the
+ * source table) — a statement with an aliased FROM must pass its alias.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(filter: FilterExpr): TSqlFragment;
+declare function buildWhere(filter: FilterExpr, opts?: TFilterVisitorOptions): TSqlFragment;
 //#endregion
 //#region src/index.d.ts
 /**