postgrejs 3.12.0 → 3.12.1

package/data-types/macaddr-type.js

@@ -79,14 +79,18 @@ function createType(name, oid, size) {
         },
     };
 }
+/** `macaddr`, as its six-group colon-separated text. */
 export const MacaddrType = createType('macaddr', DataTypeOIDs.macaddr, 6);
+/** The `_macaddr` array of {@link MacaddrType}. */
 export const ArrayMacaddrType = {
     ...MacaddrType,
     name: '_macaddr',
     oid: DataTypeOIDs._macaddr,
     elementsOID: DataTypeOIDs.macaddr,
 };
+/** `macaddr8`, as its eight-group colon-separated text. */
 export const Macaddr8Type = createType('macaddr8', DataTypeOIDs.macaddr8, 8);
+/** The `_macaddr8` array of {@link Macaddr8Type}. */
 export const ArrayMacaddr8Type = {
     ...Macaddr8Type,
     name: '_macaddr8',

package/data-types/money-type.d.ts

@@ -35,4 +35,5 @@ export declare function moneyToString(minorUnits: bigint, scale: number): string
  * knows the server or is reading a value some other server rendered.
  */
 export declare const MoneyType: DataType;
+/** The `_money` array of {@link MoneyType}. */
 export declare const ArrayMoneyType: DataType;

package/data-types/money-type.js

@@ -61,18 +61,24 @@ export function moneyToString(minorUnits, scale) {
 }
 /**
  * Below this many minor units the decimal has at most fifteen
- * significant digits, which a double both holds and prints back exactly
- * - so the round trip below can only agree, and asking it is the most
- * expensive thing in the decode: measured over values that vary,
- * `parseFloat` plus the comparison is 241 ns against 113 ns without it,
- * on a decode whose string-building is 109 ns of that.
- *
- * The scale bound is the other half: the test is about *printed* digits,
- * and JavaScript switches to exponential notation below 1e-6, which
- * PostgreSQL never writes. At scale 6 the smallest non-zero value is
- * exactly 1e-6, and no currency has more.
+ * significant digits, which a double both holds and prints back exactly.
  */
+/* So the round trip below can only agree, and asking it is the most
+   expensive thing in the decode: measured over values that vary,
+   parseFloat plus the comparison is 241 ns against 113 ns without it, on
+   a decode whose string-building is 109 ns of that.
+
+   The scale bound is the other half: the test is about *printed* digits,
+   and JavaScript switches to exponential notation below 1e-6, which
+   PostgreSQL never writes. At scale 6 the smallest non-zero value is
+   exactly 1e-6, and no currency has more. */
 const FAITHFUL_LIMIT = 1000000000000000n; // 10^15
+/**
+ * Whether this value is small enough that a double is exact for it.
+ *
+ * @param minorUnits The amount, in the currency's smallest unit.
+ * @param scale How many decimal places that currency has.
+ */
 function isFaithful(minorUnits, scale) {
     return (scale <= 6 && minorUnits < FAITHFUL_LIMIT && minorUnits > -FAITHFUL_LIMIT);
 }
@@ -225,6 +231,7 @@ function toExactMinor(v, scale) {
     const out = BigInt(digits || '0');
     return neg ? -out : out;
 }
+/** The `_money` array of {@link MoneyType}. */
 export const ArrayMoneyType = {
     ...MoneyType,
     name: '_money',

package/data-types/numeric-type.d.ts

@@ -1,7 +1,9 @@
 import type { DataType } from '../interfaces/data-type.js';
 /** The decimal without the zeroes a declared scale pads it out to. */
 export declare function trimTrailingZeros(s: string): string;
+/** `numeric`, as a number while one is exact, a {@link Numeric} when it is not, and a string with `decimalAsString`. */
 export declare const NumericType: DataType;
+/** The `_numeric` array of {@link NumericType}. */
 export declare const ArrayNumericType: DataType;
 /**
  * Turns a JS exponential-notation number string (e.g. "1e+21", "-1.5e-7")

package/data-types/numeric-type.js

@@ -45,6 +45,7 @@ function toNumberOrNumeric(s) {
     const n = parseFloat(s);
     return String(n) === trimTrailingZeros(s) ? n : new Numeric(s);
 }
+/** `numeric`, as a number while one is exact, a {@link Numeric} when it is not, and a string with `decimalAsString`. */
 export const NumericType = {
     name: 'numeric',
     oid: DataTypeOIDs.numeric,
@@ -200,6 +201,7 @@ export const NumericType = {
         return typeof v === 'number' || v instanceof Numeric;
     },
 };
+/** The `_numeric` array of {@link NumericType}. */
 export const ArrayNumericType = {
     ...NumericType,
     name: '_numeric',

package/data-types/oid-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `oid`, as a number. */
 export declare const OidType: DataType;
+/** The `_oid` array of {@link OidType}. */
 export declare const ArrayOidType: DataType;

package/data-types/oid-type.js

@@ -1,6 +1,7 @@
 import { DataTypeNames, DataTypeOIDs } from '../constants.js';
 import { assertInteger } from '../util/assert-integer.js';
 import { fastParseInt, fastParseIntBuffer } from '../util/fast-parseint.js';
+/** `oid`, as a number. */
 export const OidType = {
     name: 'oid',
     oid: DataTypeOIDs.oid,
@@ -20,6 +21,7 @@ export const OidType = {
         return typeof v === 'number' && Number.isInteger(v) && !!DataTypeNames[v];
     },
 };
+/** The `_oid` array of {@link OidType}. */
 export const ArrayOidType = {
     ...OidType,
     name: '_oid',

package/data-types/oid-vector-type.d.ts

@@ -6,4 +6,5 @@ import type { DataType } from '../interfaces/data-type.js';
  * space-separated rather than braced.
  */
 export declare const OidVectorType: DataType;
+/** The `_oidvector` array of {@link OidVectorType}. */
 export declare const ArrayOidVectorType: DataType;

package/data-types/oid-vector-type.js

@@ -47,6 +47,7 @@ export const OidVectorType = {
                 x <= 4294967295)));
     },
 };
+/** The `_oidvector` array of {@link OidVectorType}. */
 export const ArrayOidVectorType = {
     ...OidVectorType,
     name: '_oidvector',

package/data-types/path-type.d.ts

@@ -1,5 +1,9 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `path`, as a {@link Path}: the points, and whether the path is closed. */
 export declare const PathType: DataType;
+/** The `_path` array of {@link PathType}. */
 export declare const ArrayPathType: DataType;
+/** `polygon`, as a {@link Polygon}. */
 export declare const PolygonType: DataType;
+/** The `_polygon` array of {@link PolygonType}. */
 export declare const ArrayPolygonType: DataType;

package/data-types/path-type.js

@@ -62,6 +62,7 @@ function toPoints(v, name) {
         return v.points;
     throw new TypeError(`"${typeof v}" cannot be encoded as a ${name} - pass a ${name === 'path' ? 'Path' : 'Polygon'} or an array of points`);
 }
+/** `path`, as a {@link Path}: the points, and whether the path is closed. */
 export const PathType = {
     name: 'path',
     oid: DataTypeOIDs.path,
@@ -97,12 +98,14 @@ export const PathType = {
         return v instanceof Path;
     },
 };
+/** The `_path` array of {@link PathType}. */
 export const ArrayPathType = {
     ...PathType,
     name: '_path',
     oid: DataTypeOIDs._path,
     elementsOID: DataTypeOIDs.path,
 };
+/** `polygon`, as a {@link Polygon}. */
 export const PolygonType = {
     name: 'polygon',
     oid: DataTypeOIDs.polygon,
@@ -131,6 +134,7 @@ export const PolygonType = {
         return v instanceof Polygon;
     },
 };
+/** The `_polygon` array of {@link PolygonType}. */
 export const ArrayPolygonType = {
     ...PolygonType,
     name: '_polygon',

package/data-types/pg-lsn-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `pg_lsn`, as the `16/B374D848` text the server prints - the spelling every tool and every catalog column uses. */
 export declare const PgLsnType: DataType;
+/** The `_pg_lsn` array of {@link PgLsnType}. */
 export declare const ArrayPgLsnType: DataType;

package/data-types/pg-lsn-type.js

@@ -37,6 +37,7 @@ function writeHalf(value, p) {
         TEXT[p++] = HEX_UPPER[(value >>> shift) & 15];
     return p;
 }
+/** `pg_lsn`, as the `16/B374D848` text the server prints - the spelling every tool and every catalog column uses. */
 export const PgLsnType = {
     name: 'pg_lsn',
     oid: DataTypeOIDs.pg_lsn,
@@ -71,6 +72,7 @@ export const PgLsnType = {
         return typeof v === 'string' && LSN_PATTERN.test(v);
     },
 };
+/** The `_pg_lsn` array of {@link PgLsnType}. */
 export const ArrayPgLsnType = {
     ...PgLsnType,
     name: '_pg_lsn',

package/data-types/point-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `point`, as a {@link Point}. */
 export declare const PointType: DataType;
+/** The `_point` array of {@link PointType}. */
 export declare const ArrayPointType: DataType;

package/data-types/point-type.js

@@ -2,6 +2,7 @@ import { DataTypeOIDs } from '../constants.js';
 import { Point } from './classes/geometric.js';
 const POINT_PATTERN1 = /^\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\)$/;
 const POINT_PATTERN2 = /^(-?\d+\.?\d*) *, *(-?\d+\.?\d*)$/;
+/** `point`, as a {@link Point}. */
 export const PointType = {
     name: 'point',
     oid: DataTypeOIDs.point,
@@ -33,6 +34,7 @@ export const PointType = {
         return v instanceof Point || Point.isPointLike(v);
     },
 };
+/** The `_point` array of {@link PointType}. */
 export const ArrayPointType = {
     ...PointType,
     name: '_point',

package/data-types/range-type.d.ts

@@ -20,4 +20,8 @@ export declare function createRangeType(name: string, oid: OID, element: DataTyp
  * repeating it.
  */
 export declare function createMultiRangeType(name: string, oid: OID, range: DataType): DataType;
+/**
+ * Every range and multirange type, built from the types they are ranges
+ * of, and registered together.
+ */
 export declare const RangeTypes: DataType[];

package/data-types/range-type.js

@@ -328,6 +328,10 @@ const BUILT_IN = [
         TimestamptzType,
     ],
 ];
+/**
+ * Every range and multirange type, built from the types they are ranges
+ * of, and registered together.
+ */
 export const RangeTypes = [];
 for (const [name, oid, arrayOid, multiOid, multiArrayOid, , element,] of BUILT_IN) {
     const rangeType = createRangeType(name, oid, element);

package/data-types/snapshot-type.d.ts

@@ -1,5 +1,9 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `pg_snapshot`, as the `xmin:xmax:xip_list` text it is written as. */
 export declare const PgSnapshotType: DataType;
+/** The `_pg_snapshot` array of {@link PgSnapshotType}. */
 export declare const ArrayPgSnapshotType: DataType;
+/** `txid_snapshot`, the older spelling of {@link PgSnapshotType}, as the same text. */
 export declare const TxidSnapshotType: DataType;
+/** The `_txid_snapshot` array of {@link TxidSnapshotType}. */
 export declare const ArrayTxidSnapshotType: DataType;

package/data-types/snapshot-type.js

@@ -80,14 +80,18 @@ function createType(name, oid) {
         },
     };
 }
+/** `pg_snapshot`, as the `xmin:xmax:xip_list` text it is written as. */
 export const PgSnapshotType = createType('pg_snapshot', DataTypeOIDs.pg_snapshot);
+/** The `_pg_snapshot` array of {@link PgSnapshotType}. */
 export const ArrayPgSnapshotType = {
     ...PgSnapshotType,
     name: '_pg_snapshot',
     oid: DataTypeOIDs._pg_snapshot,
     elementsOID: DataTypeOIDs.pg_snapshot,
 };
+/** `txid_snapshot`, the older spelling of {@link PgSnapshotType}, as the same text. */
 export const TxidSnapshotType = createType('txid_snapshot', DataTypeOIDs.txid_snapshot);
+/** The `_txid_snapshot` array of {@link TxidSnapshotType}. */
 export const ArrayTxidSnapshotType = {
     ...TxidSnapshotType,
     name: '_txid_snapshot',

package/data-types/tid-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `tid`, a physical row address, as the `(block,offset)` text the server prints. */
 export declare const TidType: DataType;
+/** The `_tid` array of {@link TidType}. */
 export declare const ArrayTidType: DataType;

package/data-types/tid-type.js

@@ -11,6 +11,7 @@ import { DataTypeOIDs } from '../constants.js';
  * leaves it a string too.
  */
 const TID_PATTERN = /^\(\s*(\d+)\s*,\s*(\d+)\s*\)$/;
+/** `tid`, a physical row address, as the `(block,offset)` text the server prints. */
 export const TidType = {
     name: 'tid',
     oid: DataTypeOIDs.tid,
@@ -42,6 +43,7 @@ export const TidType = {
         return typeof v === 'string' && TID_PATTERN.test(v);
     },
 };
+/** The `_tid` array of {@link TidType}. */
 export const ArrayTidType = {
     ...TidType,
     name: '_tid',

package/data-types/time-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `time`, as a `Date` on the epoch day carrying that clock time. */
 export declare const TimeType: DataType;
+/** The `_time` array of {@link TimeType}. */
 export declare const ArrayTimeType: DataType;

package/data-types/time-type.js

@@ -3,6 +3,7 @@ import { formatTime } from '../util/format-datetime.js';
 import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseTime, STRICT_TIME_PATTERN } from '../util/parse-time.js';
 const timeMul = 4294967296;
+/** `time`, as a `Date` on the epoch day carrying that clock time. */
 export const TimeType = {
     name: 'time',
     oid: DataTypeOIDs.time,
@@ -46,6 +47,7 @@ export const TimeType = {
             (typeof v === 'string' && STRICT_TIME_PATTERN.test(v)));
     },
 };
+/** The `_time` array of {@link TimeType}. */
 export const ArrayTimeType = {
     ...TimeType,
     name: '_time',

package/data-types/timestamp-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `timestamp` (without time zone), as a `Date` reading that wall clock locally - or in UTC with `utcDates`. */
 export declare const TimestampType: DataType;
+/** The `_timestamp` array of {@link TimestampType}. */
 export declare const ArrayTimestampType: DataType;

package/data-types/timestamp-type.js

@@ -5,6 +5,7 @@ import { parseDateTime } from '../util/parse-datetime.js';
 import { parsePgTimestampBuffer } from '../util/parse-pg-timestamp.js';
 const timeShift = 946684800000;
 const timeMul = 4294967296;
+/** `timestamp` (without time zone), as a `Date` reading that wall clock locally - or in UTC with `utcDates`. */
 export const TimestampType = {
     name: 'timestamp',
     oid: DataTypeOIDs.timestamp,
@@ -72,6 +73,7 @@ export const TimestampType = {
             !(v.getFullYear() === 1970 && v.getMonth() === 0 && v.getDate() === 1));
     },
 };
+/** The `_timestamp` array of {@link TimestampType}. */
 export const ArrayTimestampType = {
     ...TimestampType,
     name: '_timestamp',

package/data-types/timestamptz-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `timestamptz`, as a `Date` at the instant it names, which is what the type stores. */
 export declare const TimestamptzType: DataType;
+/** The `_timestamptz` array of {@link TimestamptzType}. */
 export declare const ArrayTimestamptzType: DataType;

package/data-types/timestamptz-type.js

@@ -5,6 +5,7 @@ import { parseDateTimeTz } from '../util/parse-datetime.js';
 import { parsePgTimestampBuffer } from '../util/parse-pg-timestamp.js';
 const timeShift = 946684800000;
 const timeMul = 4294967296;
+/** `timestamptz`, as a `Date` at the instant it names, which is what the type stores. */
 export const TimestamptzType = {
     name: 'timestamptz',
     oid: DataTypeOIDs.timestamptz,
@@ -80,6 +81,7 @@ export const TimestamptzType = {
         return v instanceof Date;
     },
 };
+/** The `_timestamptz` array of {@link TimestamptzType}. */
 export const ArrayTimestamptzType = {
     ...TimestamptzType,
     name: '_timestamptz',

package/data-types/timetz-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `timetz`, as a string: the clock time and its offset, which a `Date` has nowhere to keep. */
 export declare const TimeTzType: DataType;
+/** The `_timetz` array of {@link TimeTzType}. */
 export declare const ArrayTimeTzType: DataType;

package/data-types/timetz-type.js

@@ -117,6 +117,7 @@ function formatTimeTz(micros, zone) {
         out += ':' + pad(zs);
     return out;
 }
+/** `timetz`, as a string: the clock time and its offset, which a `Date` has nowhere to keep. */
 export const TimeTzType = {
     name: 'timetz',
     oid: DataTypeOIDs.timetz,
@@ -176,6 +177,7 @@ export const TimeTzType = {
         }
     },
 };
+/** The `_timetz` array of {@link TimeTzType}. */
 export const ArrayTimeTzType = {
     ...TimeTzType,
     name: '_timetz',

package/data-types/tsvector-type.d.ts

@@ -1,5 +1,9 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `tsvector`, as its own text - the lexemes with their positions and weights. */
 export declare const TsVectorType: DataType;
+/** The `_tsvector` array of {@link TsVectorType}. */
 export declare const ArrayTsVectorType: DataType;
+/** `tsquery`, as its own text. */
 export declare const TsQueryType: DataType;
+/** The `_tsquery` array of {@link TsQueryType}. */
 export declare const ArrayTsQueryType: DataType;

package/data-types/tsvector-type.js

@@ -170,6 +170,7 @@ function printQuery(node, parentPriority, rightPhraseOp) {
         ? '( ' + out + ' )'
         : out;
 }
+/** `tsvector`, as its own text - the lexemes with their positions and weights. */
 export const TsVectorType = {
     name: 'tsvector',
     oid: DataTypeOIDs.tsvector,
@@ -190,12 +191,14 @@ export const TsVectorType = {
         return typeof v === 'string';
     },
 };
+/** The `_tsvector` array of {@link TsVectorType}. */
 export const ArrayTsVectorType = {
     ...TsVectorType,
     name: '_tsvector',
     oid: DataTypeOIDs._tsvector,
     elementsOID: DataTypeOIDs.tsvector,
 };
+/** `tsquery`, as its own text. */
 export const TsQueryType = {
     ...TsVectorType,
     name: 'tsquery',
@@ -208,6 +211,7 @@ export const TsQueryType = {
         return printQuery(readQueryNode(v, { p: offset + 4 }), 0, false);
     },
 };
+/** The `_tsquery` array of {@link TsQueryType}. */
 export const ArrayTsQueryType = {
     ...TsQueryType,
     name: '_tsquery',

package/data-types/uuid-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `uuid`, as its canonical 36-character text. */
 export declare const UuidType: DataType;
+/** The `_uuid` array of {@link UuidType}. */
 export declare const ArrayUuidType: DataType;

package/data-types/uuid-type.js

@@ -11,6 +11,7 @@ TEXT[8] = TEXT[13] = TEXT[18] = TEXT[23] = 45; /* - */
 /** Where each of the sixteen bytes writes its two characters. */
 const POSITIONS = [0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34];
 const GUID_PATTERN = /^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$/;
+/** `uuid`, as its canonical 36-character text. */
 export const UuidType = {
     name: 'uuid',
     oid: DataTypeOIDs.uuid,
@@ -41,6 +42,7 @@ export const UuidType = {
         return typeof v === 'string' && GUID_PATTERN.test(v);
     },
 };
+/** The `_uuid` array of {@link UuidType}. */
 export const ArrayUuidType = {
     ...UuidType,
     name: '_uuid',

package/data-types/varchar-type.d.ts

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `varchar`, `text`, `name` and the other string types, as strings. */
 export declare const VarcharType: DataType;
+/** The `_varchar` array of {@link VarcharType}. */
 export declare const ArrayVarcharType: DataType;

package/data-types/varchar-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+/** `varchar`, `text`, `name` and the other string types, as strings. */
 export const VarcharType = {
     name: 'varchar',
     oid: DataTypeOIDs.varchar,
@@ -28,6 +29,7 @@ export const VarcharType = {
         return typeof v === 'string';
     },
 };
+/** The `_varchar` array of {@link VarcharType}. */
 export const ArrayVarcharType = {
     ...VarcharType,
     name: '_varchar',

package/data-types/xid-type.d.ts

@@ -1,7 +1,13 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `xid`, a 32-bit transaction id, as a number. */
 export declare const XidType: DataType;
+/** The `_xid` array of {@link XidType}. */
 export declare const ArrayXidType: DataType;
+/** `cid`, a command id within a transaction, as a number. */
 export declare const CidType: DataType;
+/** The `_cid` array of {@link CidType}. */
 export declare const ArrayCidType: DataType;
+/** `xid8`, the 64-bit transaction id, as a number while one is exact and a `BigInt` beyond. */
 export declare const Xid8Type: DataType;
+/** The `_xid8` array of {@link Xid8Type}. */
 export declare const ArrayXid8Type: DataType;

package/data-types/xid-type.js

@@ -57,20 +57,25 @@ function createUInt32Type(name, oid) {
         },
     };
 }
+/** `xid`, a 32-bit transaction id, as a number. */
 export const XidType = createUInt32Type('xid', DataTypeOIDs.xid);
+/** The `_xid` array of {@link XidType}. */
 export const ArrayXidType = {
     ...XidType,
     name: '_xid',
     oid: DataTypeOIDs._xid,
     elementsOID: DataTypeOIDs.xid,
 };
+/** `cid`, a command id within a transaction, as a number. */
 export const CidType = createUInt32Type('cid', DataTypeOIDs.cid);
+/** The `_cid` array of {@link CidType}. */
 export const ArrayCidType = {
     ...CidType,
     name: '_cid',
     oid: DataTypeOIDs._cid,
     elementsOID: DataTypeOIDs.cid,
 };
+/** `xid8`, the 64-bit transaction id, as a number while one is exact and a `BigInt` beyond. */
 export const Xid8Type = {
     name: 'xid8',
     oid: DataTypeOIDs.xid8,
@@ -103,6 +108,7 @@ export const Xid8Type = {
             (typeof v === 'number' && Number.isInteger(v) && v >= 0));
     },
 };
+/** The `_xid8` array of {@link Xid8Type}. */
 export const ArrayXid8Type = {
     ...Xid8Type,
     name: '_xid8',

package/interfaces/command-result.d.ts

@@ -1,5 +1,12 @@
 import type { Row } from '../types.js';
 import type { FieldInfo } from './field-info.js';
+/**
+ * What one statement answered with: its rows, what its columns were, and
+ * what the server said it did.
+ *
+ * `QueryResult` is this plus a cursor; a script's results are a list of
+ * these, one per statement in it.
+ */
 export interface CommandResult {
     /**
      * Name of the command (INSERT, SELECT, UPDATE, etc.)

package/interfaces/copy-from-rows-options.d.ts

@@ -1,6 +1,10 @@
 import type { DataTypeMap } from '../data-type-map.js';
 import type { OID } from '../types.js';
 import type { DataMappingOptions } from './data-mapping-options.js';
+/**
+ * What `copyFromRows()` takes: which columns the rows line up with, how
+ * to encode their values, and how to stop.
+ */
 export interface CopyFromRowsOptions extends DataMappingOptions {
     /** Type registry used to encode values; defaults to GlobalTypeMap. */
     typeMap?: DataTypeMap;

package/interfaces/data-mapping-options.d.ts

@@ -34,6 +34,12 @@ export interface FetchAsStringSelector {
      */
     ranges?: boolean;
 }
+/**
+ * How values are turned into JavaScript and back.
+ *
+ * Set on the connection to apply to everything it runs, or per call to
+ * apply to one - a call that says nothing takes the connection's.
+ */
 export interface DataMappingOptions {
     /**
      * Decode `numeric` and `money` into the exact decimal string they

package/interfaces/data-type.d.ts

@@ -1,11 +1,34 @@
 import type { DecodeBinaryFunction, DecodeTextBufferFunction, DecodeTextFunction, EncodeAsNullFunction, EncodeBinaryFunction, EncodeCalculateDimFunction, EncodeTextFunction, OID } from '../types.js';
+/**
+ * How one PostgreSQL type is read and written.
+ *
+ * One of these per type in a `DataTypeMap`, and the extension point for
+ * a type this client does not know: register it on the global map or on
+ * one of a connection's own, and every column and parameter of that OID
+ * goes through it.
+ *
+ * A type needs to decode - both formats, since which one arrives depends
+ * on what the column asked for - and needs to encode only what callers
+ * will send. Registering the array counterpart is a separate entry, with
+ * `elementsOID` pointing back at this one.
+ */
 export interface DataType {
+    /** The type's own OID, as `pg_type` gives it. */
     oid: OID;
+    /** The type's name, for `FieldInfo.dataTypeName` and for errors. */
     name: string;
+    /** For an array type, the OID of what it is an array of. */
     elementsOID?: OID;
+    /** Whether this entry is the array counterpart. */
     isArray?: boolean;
+    /** What a decoded value is, named for `FieldInfo.jsType`. */
     jsType: string;
+    /** What separates elements in this type's array literal - a comma for all but `box`. */
     arraySeparator?: string;
+    /**
+     * Whether a JavaScript value could be of this type, asked when nothing
+     * declared one - see `inferrable` for when it is asked at all.
+     */
     isType: (v: any) => boolean;
     /**
      * Whether DataTypeMap.determine() may pick this type for a value, which
@@ -18,12 +41,22 @@ export interface DataType {
      * `new BindParam(oid, value)`.
      */
     inferrable?: boolean;
+    /** Reads a value out of the binary wire format. */
     decodeBinary: DecodeBinaryFunction;
+    /** Reads a value out of the text the server rendered. */
     decodeText: DecodeTextFunction;
+    /**
+     * Reads a text value straight from the wire buffer, when the type can
+     * do better than being handed a string.
+     */
     decodeTextBuffer?: DecodeTextBufferFunction;
+    /** Whether a value should go out as SQL NULL rather than be encoded. */
     encodeAsNull?: EncodeAsNullFunction;
+    /** Writes a value in the binary wire format. */
     encodeBinary?: EncodeBinaryFunction;
+    /** Renders a value as the text the server parses. */
     encodeText?: EncodeTextFunction;
+    /** Measures an array's dimensions, for a type whose values are arrays themselves. */
     encodeCalculateDim?: EncodeCalculateDimFunction;
 }
 /**
@@ -35,8 +68,12 @@ export interface DataType {
  *   object of these four numbers is still accepted as a parameter.
  */
 export interface Rectangle {
+    /** First corner's x. */
     x1: number;
+    /** First corner's y. */
     y1: number;
+    /** Second corner's x. */
     x2: number;
+    /** Second corner's y. */
     y2: number;
 }