postgrejs 3.11.1 → 3.12.1

package/connection/prepared-statement.js

@@ -1,4 +1,4 @@
-import { DataTypeOIDs } from '../constants.js';
+import { DataTypeNames, DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -8,20 +8,54 @@ import { resolveColumnFormats } from '../util/resolve-column-formats.js';
 import { resolveRowType } from '../util/row-decoder.js';
 import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
+import { BindParam } from './bind-param.js';
 import { Cursor } from './cursor.js';
 import { getIntlConnection } from './intl-connection.js';
 import { Portal } from './portal.js';
 let statementCounter = 0;
 let portalCounter = 0;
+/**
+ * A statement parsed once by the server and executed as many times as
+ * the caller likes.
+ *
+ * Obtained from `Connection.prepare()` or `Pool.prepare()`. Each
+ * `execute()` then costs a Bind and an Execute instead of a full Parse,
+ * and the server plans it once - which is what makes it worth naming a
+ * statement that runs in a loop. `executeBatch()` goes further and sends
+ * every parameter set before waiting for any of them.
+ *
+ * ```ts
+ * const statement = await connection.prepare(
+ *   'update customers set city = $1 where id = $2',
+ * );
+ * await statement.execute({ params: ['Berlin', 1] });
+ * await statement.execute({ params: ['Paris', 2] });
+ * await statement.close();
+ * ```
+ *
+ * A statement holds a server-side name until `close()`, and one taken
+ * from a `Pool` holds that pool's connection with it, so it must be
+ * closed - `await using` does it at the end of the scope.
+ *
+ * Emits `close` and `notice`.
+ */
 export class PreparedStatement extends SafeEventEmitter {
     _connection;
     _sql = '';
     _name = '';
     _paramTypes;
+    _resolvedParamTypes;
     _fields;
     _onErrorSavePoint;
     _refCount = 0;
     _closed = false;
+    /**
+     * Builds the handle; `prepare()` is what sends anything.
+     *
+     * @param connection The connection this statement lives on.
+     * @param sql The statement text.
+     * @param paramTypes Declared parameter types, if the caller named any.
+     */
     constructor(connection, sql, paramTypes) {
         super();
         this._connection = connection;
@@ -30,31 +64,82 @@ export class PreparedStatement extends SafeEventEmitter {
         this._paramTypes = paramTypes;
         this._onErrorSavePoint = 'SP_' + Math.round(Math.random() * 100000000);
     }
+    /**
+     * Parses the statement on the server and describes it, in one round
+     * trip, so the first `execute()` already knows what its columns are.
+     *
+     * `Connection.prepare()` is the way to call this.
+     *
+     * @param connection The connection to prepare on.
+     * @param sql The statement text.
+     * @param options Declared parameter types.
+     * @returns The prepared statement.
+     * @throws DatabaseError When the server refuses to parse it.
+     */
     static async prepare(connection, sql, options) {
         const intoCon = getIntlConnection(connection);
         intoCon.assertConnected();
         const statement = new PreparedStatement(connection, sql, options?.paramTypes);
-        const { fields } = await intoCon.prepareOnce(sql, statement.paramTypes, statement.name);
+        const { fields, resolvedParamTypes } = await intoCon.prepareOnce(sql, statement.paramTypes, statement.name);
         statement._fields = fields;
+        statement._resolvedParamTypes = resolvedParamTypes;
         statement._refCount = 1;
         return statement;
     }
+    /** The connection this statement was prepared on. */
     get connection() {
         return this._connection;
     }
+    /** The name the server knows this statement by. */
     get name() {
         return this._name;
     }
+    /** The statement text, as it was prepared. */
     get sql() {
         return this._sql;
     }
+    /**
+     * The parameter types the caller declared at `prepare()`, if any -
+     * `resolvedParamTypes` is what the server made of them.
+     */
     get paramTypes() {
         return this._paramTypes;
     }
+    /**
+     * What the server made of each parameter, in order, as its Describe
+     * answered - not what was asked for in `paramTypes`.
+     *
+     * A parameter the caller declared nothing for is resolved by the
+     * server from where it appears: the column it is inserted into, the
+     * operator it sits beside, the function it is passed to. It never
+     * looks at the value, which is still three messages away, so this is
+     * a property of the statement and does not change between executions.
+     *
+     * Useful for two things. It says what a parameter with no context
+     * became - `select $1` resolves to `text`, which is why an array
+     * there comes back as an array literal rather than an array. And it
+     * is the type to name with `new BindParam(oid, v)` for a caller who
+     * wants the binary encoding a large numeric array gives up by going
+     * out untyped (see `isUnspecifiedParam`).
+     */
+    get resolvedParamTypes() {
+        return this._resolvedParamTypes;
+    }
+    /**
+     * Runs the statement once, with one set of parameters.
+     *
+     * Takes the same options `Connection.query()` does, minus the SQL -
+     * parameters, row shape, type mapping, `cursor`, a signal.
+     *
+     * @param options Parameters and how to read the result.
+     * @returns The rows, the command tag, and what the columns were.
+     * @throws DatabaseError When the server refuses the execution.
+     */
+    /* The options are merged with the connection's defaults here rather
+       than deeper down, because a cursor keeps them and decodes its own
+       rows with them long after this call is over. */
     async execute(options = {}) {
         const intlCon = getIntlConnection(this.connection);
-        // Folded in here rather than deeper: a cursor keeps these options
-        // and decodes its own rows with them long after this call is over.
         options = intlCon.withDefaults(options);
         if (options.signal)
             return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeWithTransaction(options));
@@ -130,13 +215,58 @@ export class PreparedStatement extends SafeEventEmitter {
      * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
      * does not normally raise one - which is why there is no test for it.
      */
+    /**
+     * Takes the value out of a `BindParam`, and refuses one that names a
+     * type this statement is not.
+     *
+     * A prepared statement's parameter types are fixed by its Parse, so a
+     * `BindParam` here cannot change one: the Bind's format code says
+     * binary or text, and the server decodes with the type it already
+     * resolved. Naming a different one and being believed would read the
+     * bytes as something else - which is why the mismatch is an error
+     * rather than something to quietly honour.
+     *
+     * It used to be neither: nothing unwrapped the object, so it reached
+     * the encoder as a value with no type of its own and went out as
+     * `'' + v`. A text column took `"[object Object]"` and said nothing.
+     *
+     * What it is compared against is what the caller declared at
+     * `prepare()`, or failing that what the server resolved - which is the
+     * same type either way, and is why an agreeing `BindParam` is simply
+     * unwrapped. Where there is nothing to compare against, the value is
+     * taken as given.
+     */
+    _unwrapBindParams(params) {
+        if (!params)
+            return params;
+        let out;
+        const l = params.length;
+        let i;
+        let prm;
+        let expected;
+        for (i = 0; i < l; i++) {
+            prm = params[i];
+            if (!(prm instanceof BindParam))
+                continue;
+            expected = this._paramTypes?.[i] ?? this._resolvedParamTypes?.[i];
+            if (expected != null && prm.oid !== expected)
+                throw new TypeError(`Parameter $${i + 1} was given as ${typeLabel(prm.oid)}, but this ` +
+                    `prepared statement's $${i + 1} is ${typeLabel(expected)}. A ` +
+                    'prepared statement takes its parameter types at ' +
+                    'prepare(sql, { paramTypes }), and they cannot be changed per ' +
+                    'execution.');
+            out = out || params.slice();
+            out[i] = prm.value;
+        }
+        return out || params;
+    }
     _emitNotice(msg) {
         this.emit('notice', msg);
         getIntlConnection(this.connection).emit('notice', msg);
     }
     _executeBatchWithTransaction(paramSets, options) {
         const intlCon = getIntlConnection(this.connection);
-        return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets, options));
+        return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets.map(set => this._unwrapBindParams(set)), options));
     }
     async _executeWithTransaction(options = {}) {
         // The Bind+Execute+Sync path can carry the rollbackOnError savepoint
@@ -219,6 +349,13 @@ export class PreparedStatement extends SafeEventEmitter {
             throw e;
         }
     }
+    /**
+     * Closes the statement on the server and releases what it was holding
+     * - the connection too, when it came from a pool.
+     *
+     * Idempotent, and deferred while a cursor of this statement is still
+     * open. Emits `close`.
+     */
     async close() {
         if (this._closed)
             return;
@@ -238,6 +375,7 @@ export class PreparedStatement extends SafeEventEmitter {
     }
     async _execute(options = {}, savepoint) {
         const intlCon = getIntlConnection(this.connection);
+        const params = this._unwrapBindParams(options.params);
         if (options.cursor && this._fields) {
             intlCon.ref();
             let portal = new Portal(this, 'P_' + ++portalCounter);
@@ -247,7 +385,7 @@ export class PreparedStatement extends SafeEventEmitter {
                 // codes on the Bind below with no round trip of its own.
                 const typeMap = options.typeMap || GlobalTypeMap;
                 const columnFormat = resolveColumnFormats(this._fields, options, typeMap);
-                const fields = await portal.bindAndRetrieveFields(options.params, options, columnFormat);
+                const fields = await portal.bindAndRetrieveFields(params, options, columnFormat);
                 const parsers = getParsers(typeMap, fields, options);
                 const resultFields = wrapRowDescription(typeMap, fields, columnFormat, options);
                 const result = {
@@ -270,7 +408,7 @@ export class PreparedStatement extends SafeEventEmitter {
         // unnamed portal, reusing the RowDescription prepare() already fetched
         // instead of re-Describing (and re-Close-ing) a fresh named portal on
         // every call.
-        return intlCon.executeReused(this.name, this._fields, this.paramTypes, options.params, options, savepoint);
+        return intlCon.executeReused(this.name, this._fields, this.paramTypes, params, options, savepoint);
     }
     /**
      * Called by Cursor.close() instead of separately awaiting
@@ -372,3 +510,8 @@ export class PreparedStatement extends SafeEventEmitter {
         return this.close();
     }
 }
+/** `int2 (21)` - the name when there is one, and always the oid. */
+function typeLabel(oid) {
+    const name = DataTypeNames[oid];
+    return name ? `${name} (${oid})` : String(oid);
+}

package/constants.d.ts

@@ -1,7 +1,16 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
+export declare const version = "3.12.1";
 export { DataFormat };
+/**
+ * What columns come back in unless something asks otherwise.
+ *
+ * Binary: fewer bytes on the wire and no text to parse for most types.
+ * A column named by `fetchAsString`, and the types that have no binary
+ * decoder, come back as text regardless.
+ */
 export declare const DEFAULT_COLUMN_FORMAT = DataFormat.binary;
+/** Where a connection is between `connect()` and `close()`. */
 export declare enum ConnectionState {
     CLOSED = 0,
     CONNECTING = 1,
@@ -9,6 +18,14 @@ export declare enum ConnectionState {
     READY = 2,
     CLOSING = 10
 }
+/**
+ * Every type this client knows, by name, as `pg_type.oid` gives it - the
+ * scalar types and their array counterparts, which are named with a
+ * leading underscore the way the catalog names them.
+ *
+ * These are the numbers `BindParam`, `fetchAsString` and a
+ * `DataTypeMap`'s own registrations are written with.
+ */
 export declare const DataTypeOIDs: {
     bool: number;
     bytea: number;
@@ -185,4 +202,5 @@ export declare const DataTypeOIDs: {
     _datemultirange: number;
     _int8multirange: number;
 };
+/** The name of each type by its OID, for reporting a column's type back to a caller. */
 export declare const DataTypeNames: Record<string, string>;

package/constants.js

@@ -2,8 +2,17 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
+export const version = '3.12.1';
 export { DataFormat };
+/**
+ * What columns come back in unless something asks otherwise.
+ *
+ * Binary: fewer bytes on the wire and no text to parse for most types.
+ * A column named by `fetchAsString`, and the types that have no binary
+ * decoder, come back as text regardless.
+ */
 export const DEFAULT_COLUMN_FORMAT = DataFormat.binary;
+/** Where a connection is between `connect()` and `close()`. */
 export var ConnectionState;
 (function (ConnectionState) {
     ConnectionState[ConnectionState["CLOSED"] = 0] = "CLOSED";
@@ -12,6 +21,14 @@ export var ConnectionState;
     ConnectionState[ConnectionState["READY"] = 2] = "READY";
     ConnectionState[ConnectionState["CLOSING"] = 10] = "CLOSING";
 })(ConnectionState || (ConnectionState = {}));
+/**
+ * Every type this client knows, by name, as `pg_type.oid` gives it - the
+ * scalar types and their array counterparts, which are named with a
+ * leading underscore the way the catalog names them.
+ *
+ * These are the numbers `BindParam`, `fetchAsString` and a
+ * `DataTypeMap`'s own registrations are written with.
+ */
 export const DataTypeOIDs = {
     bool: 16,
     bytea: 17,
@@ -188,6 +205,7 @@ export const DataTypeOIDs = {
     _datemultirange: 6155,
     _int8multirange: 6157,
 };
+/** The name of each type by its OID, for reporting a column's type back to a caller. */
 export const DataTypeNames = {
     [DataTypeOIDs.bool]: 'bool',
     [DataTypeOIDs.bytea]: 'bytea',

package/data-type-map.d.ts

@@ -1,5 +1,20 @@
 import type { DataType } from './interfaces/data-type.js';
 import type { OID } from './types.js';
+/**
+ * Which `DataType` answers for which OID.
+ *
+ * `GlobalTypeMap` is the one every connection uses unless it was given
+ * its own, and it already holds every type this client knows. A caller
+ * registers into it to add a type - a PostGIS geometry, a composite of
+ * their own - or copies it and registers into the copy to change one
+ * type for one connection without touching anyone else's.
+ *
+ * ```ts
+ * const typeMap = new DataTypeMap(GlobalTypeMap);
+ * typeMap.register(MyGeometryType);
+ * const connection = new Connection({ ...config, typeMap });
+ * ```
+ */
 export declare class DataTypeMap {
     protected _inferScalars: DataType[];
     protected _inferArrays: DataType[];
@@ -17,7 +32,22 @@ export declare class DataTypeMap {
      * nothing reported.
      */
     constructor(other?: DataTypeMap);
+    /**
+     * The type registered for an OID.
+     *
+     * @param oid The type to look up.
+     * @returns Its `DataType`, or `undefined` when nothing is registered -
+     * in which case values of that type come back as raw `Buffer`s.
+     */
     get(oid: OID): DataType;
+    /**
+     * Registers a type, or replaces the one already holding its OID.
+     *
+     * The array counterpart is its own registration: register both to have
+     * both read and written.
+     *
+     * @param dataTypes The type, or several at once.
+     */
     register(dataTypes: DataType | DataType[]): void;
     /**
      * The two lists determine() actually walks, newest-registered first.
@@ -35,4 +65,12 @@ export declare class DataTypeMap {
     protected _rebuildInferenceLists(): void;
     determine(value: any): OID;
 }
+/**
+ * The map every connection reads unless it was given one of its own -
+ * already holding every type this client knows.
+ *
+ * Registering here changes what every connection in the process does,
+ * which is what makes it the place for a type the whole application
+ * shares, and the wrong place for one connection's exception.
+ */
 export declare const GlobalTypeMap: DataTypeMap;

package/data-type-map.js

@@ -40,6 +40,21 @@ import { ArrayUuidType, UuidType } from './data-types/uuid-type.js';
 import { ArrayVarcharType, VarcharType } from './data-types/varchar-type.js';
 import { ArrayCidType, ArrayXid8Type, ArrayXidType, CidType, Xid8Type, XidType, } from './data-types/xid-type.js';
 import { arrayLeaf } from './util/array-leaf.js';
+/**
+ * Which `DataType` answers for which OID.
+ *
+ * `GlobalTypeMap` is the one every connection uses unless it was given
+ * its own, and it already holds every type this client knows. A caller
+ * registers into it to add a type - a PostGIS geometry, a composite of
+ * their own - or copies it and registers into the copy to change one
+ * type for one connection without touching anyone else's.
+ *
+ * ```ts
+ * const typeMap = new DataTypeMap(GlobalTypeMap);
+ * typeMap.register(MyGeometryType);
+ * const connection = new Connection({ ...config, typeMap });
+ * ```
+ */
 export class DataTypeMap {
     _inferScalars = [];
     _inferArrays = [];
@@ -67,9 +82,24 @@ export class DataTypeMap {
             this._inferArrays = other._inferArrays;
         }
     }
+    /**
+     * The type registered for an OID.
+     *
+     * @param oid The type to look up.
+     * @returns Its `DataType`, or `undefined` when nothing is registered -
+     * in which case values of that type come back as raw `Buffer`s.
+     */
     get(oid) {
         return this._itemsByOID[oid];
     }
+    /**
+     * Registers a type, or replaces the one already holding its OID.
+     *
+     * The array counterpart is its own registration: register both to have
+     * both read and written.
+     *
+     * @param dataTypes The type, or several at once.
+     */
     register(dataTypes) {
         dataTypes = Array.isArray(dataTypes) ? dataTypes : [dataTypes];
         for (const t of dataTypes) {
@@ -155,6 +185,14 @@ export class DataTypeMap {
         return DataTypeOIDs.unknown;
     }
 }
+/**
+ * The map every connection reads unless it was given one of its own -
+ * already holding every type this client knows.
+ *
+ * Registering here changes what every connection in the process does,
+ * which is what makes it the place for a type the whole application
+ * shares, and the wrong place for one connection's exception.
+ */
 export const GlobalTypeMap = new DataTypeMap();
 GlobalTypeMap.register([OidType, ArrayOidType]);
 GlobalTypeMap.register([OidVectorType, ArrayOidVectorType]);

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

@@ -1,5 +1,9 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `bit(n)`, as a string of `0`s and `1`s - its own text form, and the only lossless one for a length the server chose. */
 export declare const BitType: DataType;
+/** The `_bit` array of {@link BitType}. */
 export declare const ArrayBitType: DataType;
+/** `varbit` (bit varying), as a string of `0`s and `1`s. */
 export declare const VarbitType: DataType;
+/** The `_varbit` array of {@link VarbitType}. */
 export declare const ArrayVarbitType: DataType;

package/data-types/bit-type.js

@@ -75,14 +75,18 @@ function createType(name, oid) {
         },
     };
 }
+/** `bit(n)`, as a string of `0`s and `1`s - its own text form, and the only lossless one for a length the server chose. */
 export const BitType = createType('bit', DataTypeOIDs.bit);
+/** The `_bit` array of {@link BitType}. */
 export const ArrayBitType = {
     ...BitType,
     name: '_bit',
     oid: DataTypeOIDs._bit,
     elementsOID: DataTypeOIDs.bit,
 };
+/** `varbit` (bit varying), as a string of `0`s and `1`s. */
 export const VarbitType = createType('varbit', DataTypeOIDs.varbit);
+/** The `_varbit` array of {@link VarbitType}. */
 export const ArrayVarbitType = {
     ...VarbitType,
     name: '_varbit',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `bool`, as a JavaScript boolean. Its text form is the `t`/`f` the server itself writes. */
 export declare const BoolType: DataType;
+/** The `_bool` array of {@link BoolType}. */
 export declare const ArrayBoolType: DataType;

package/data-types/bool-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+/** `bool`, as a JavaScript boolean. Its text form is the `t`/`f` the server itself writes. */
 export const BoolType = {
     name: 'bool',
     oid: DataTypeOIDs.bool,
@@ -25,6 +26,7 @@ export const BoolType = {
         return typeof v === 'boolean';
     },
 };
+/** The `_bool` array of {@link BoolType}. */
 export const ArrayBoolType = {
     ...BoolType,
     name: '_bool',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `box`, as a {@link Box}. Its array literal separates elements with a semicolon rather than a comma, which is what `arraySeparator` is for. */
 export declare const BoxType: DataType;
+/** The `_box` array of {@link BoxType}. */
 export declare const ArrayBoxType: DataType;

package/data-types/box-type.js

@@ -3,6 +3,7 @@ import { Box, TwoPoints } from './classes/geometric.js';
 const BOX_PATTERN1 = /^\( *\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *, *\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *\)$/;
 const BOX_PATTERN2 = /^\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *, *\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\)$/;
 const BOX_PATTERN3 = /^(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *, *(-?\d+\.?\d*)$/;
+/** `box`, as a {@link Box}. Its array literal separates elements with a semicolon rather than a comma, which is what `arraySeparator` is for. */
 export const BoxType = {
     name: 'box',
     oid: DataTypeOIDs.box,
@@ -37,6 +38,7 @@ export const BoxType = {
         return v instanceof Box || TwoPoints.isTwoPointsLike(v);
     },
 };
+/** The `_box` array of {@link BoxType}. */
 export const ArrayBoxType = {
     ...BoxType,
     name: '_box',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
 export declare const ByteaType: DataType;
+/** The `_bytea` array of {@link ByteaType}. */
 export declare const ArrayByteaType: DataType;

package/data-types/bytea-type.js

@@ -1,5 +1,6 @@
 import { DataTypeOIDs } from '../constants.js';
 import { parseBytea, parseByteaBuffer } from '../util/parse-bytea.js';
+/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
 export const ByteaType = {
     name: 'bytea',
     oid: DataTypeOIDs.bytea,
@@ -22,6 +23,7 @@ export const ByteaType = {
         return v instanceof Buffer;
     },
 };
+/** The `_bytea` array of {@link ByteaType}. */
 export const ArrayByteaType = {
     ...ByteaType,
     name: '_bytea',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `char` - the single-byte internal type, not `char(n)` - as a one-character string. */
 export declare const CharType: DataType;
+/** The `_char` array of {@link CharType}. */
 export declare const ArrayCharType: DataType;

package/data-types/char-type.js

@@ -1,4 +1,5 @@
 import { DataTypeOIDs } from '../constants.js';
+/** `char` - the single-byte internal type, not `char(n)` - as a one-character string. */
 export const CharType = {
     name: 'char',
     oid: DataTypeOIDs.char,
@@ -37,6 +38,7 @@ export const CharType = {
      */
     inferrable: false,
 };
+/** The `_char` array of {@link CharType}. */
 export const ArrayCharType = {
     ...CharType,
     name: '_char',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `circle`, as a {@link Circle} - a centre point and a radius, named as PostgreSQL names them. */
 export declare const CircleType: DataType;
+/** The `_circle` array of {@link CircleType}. */
 export declare const ArrayCircleType: DataType;

package/data-types/circle-type.js

@@ -4,6 +4,7 @@ const CIRCLE_PATTERN1 = /^< *\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *, *(-?\d+\
 const CIRCLE_PATTERN2 = /^\( *\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *, *(-?\d+\.?\d*) *\)$/;
 const CIRCLE_PATTERN3 = /^\( *(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *\) *, *(-?\d+\.?\d*)$/;
 const CIRCLE_PATTERN4 = /^(-?\d+\.?\d*) *, *(-?\d+\.?\d*) *, *(-?\d+\.?\d*)$/;
+/** `circle`, as a {@link Circle} - a centre point and a radius, named as PostgreSQL names them. */
 export const CircleType = {
     name: 'circle',
     oid: DataTypeOIDs.circle,
@@ -40,6 +41,7 @@ export const CircleType = {
         return v instanceof Circle || Circle.isCircleLike(v);
     },
 };
+/** The `_circle` array of {@link CircleType}. */
 export const ArrayCircleType = {
     ...CircleType,
     name: '_circle',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `date`, as a `Date` at local midnight - or at UTC midnight with `utcDates`. */
 export declare const DateType: DataType;
+/** The `_date` array of {@link DateType}. */
 export declare const ArrayDateType: DataType;

package/data-types/date-type.js

@@ -3,6 +3,7 @@ import { formatDate } from '../util/format-datetime.js';
 import { utcPartsAsLocal } from '../util/local-date.js';
 import { parseDate } from '../util/parse-datetime.js';
 const timeShift = 946684800000;
+/** `date`, as a `Date` at local midnight - or at UTC midnight with `utcDates`. */
 export const DateType = {
     name: 'date',
     oid: DataTypeOIDs.date,
@@ -56,6 +57,7 @@ export const DateType = {
             v.getMilliseconds() === 0);
     },
 };
+/** The `_date` array of {@link DateType}. */
 export const ArrayDateType = {
     ...DateType,
     name: '_date',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `float4` (real), as a number - the shortest decimal that reads back as the same 32-bit float. */
 export declare const Float4Type: DataType;
+/** The `_float4` array of {@link Float4Type}. */
 export declare const ArrayFloat4Type: DataType;

package/data-types/float4-type.js

@@ -1,6 +1,7 @@
 import { DataTypeOIDs } from '../constants.js';
 import { assertCoercedNumber } from '../util/assert-integer.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
+/** `float4` (real), as a number - the shortest decimal that reads back as the same 32-bit float. */
 export const Float4Type = {
     name: 'float4',
     oid: DataTypeOIDs.float4,
@@ -20,6 +21,7 @@ export const Float4Type = {
         return typeof v === 'number';
     },
 };
+/** The `_float4` array of {@link Float4Type}. */
 export const ArrayFloat4Type = {
     ...Float4Type,
     name: '_float4',

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

@@ -1,3 +1,5 @@
 import type { DataType } from '../interfaces/data-type.js';
+/** `float8` (double precision), as a number. */
 export declare const Float8Type: DataType;
+/** The `_float8` array of {@link Float8Type}. */
 export declare const ArrayFloat8Type: DataType;

package/data-types/float8-type.js

@@ -1,6 +1,7 @@
 import { DataTypeOIDs } from '../constants.js';
 import { assertCoercedNumber } from '../util/assert-integer.js';
 import { fastParseFloatBuffer } from '../util/fast-parsefloat.js';
+/** `float8` (double precision), as a number. */
 export const Float8Type = {
     name: 'float8',
     oid: DataTypeOIDs.float8,
@@ -21,6 +22,7 @@ export const Float8Type = {
         return typeof v === 'number';
     },
 };
+/** The `_float8` array of {@link Float8Type}. */
 export const ArrayFloat8Type = {
     ...Float8Type,
     name: '_float8',