ts-prorm-orm 2.0.0 → 2.1.0

package/dist/types/index.d.ts

@@ -520,6 +520,11 @@ export interface DropPolicyOptions {
     /** Schema (for PostgreSQL) */
     schema?: string;
 }
+/**
+ * Every SQL dialect prorm can target. The value chosen here decides which
+ * `Dialect` implementation compiles your `FindOptions` into SQL, so it governs
+ * identifier quoting, pagination syntax and which clauses are legal.
+ */
 export type Dialect = 'mysql' | 'postgres' | 'sqlite' | 'mssql' | 'mariadb' | 'oracle' | 'cockroachdb' | 'redshift' | 'db2' | 'snowflake' | 'clickhouse' | 'duckdb' | 'hana' | 'spanner' | 'turso' | 'tidb' | 'singlestore' | 'yugabytedb' | 'timescaledb' | 'greenplum' | 'vertica' | 'trino' | 'exasol' | 'questdb' | 'cratedb' | 'firebird' | 'databricks';
 /**
  * Query event data emitted when a query is executed
@@ -564,6 +569,11 @@ export interface PrormEvents {
     /** Fired when there's an error */
     error: (error: Error) => void;
 }
+/**
+ * Everything needed to construct a `Prorm` instance: which engine to
+ * talk to, how to reach it, and the cross-cutting behaviour (pooling, retries,
+ * logging, caching) that applies to every query it runs.
+ */
 export interface PrormOptions {
     dialect: Dialect;
     database?: string;
@@ -656,6 +666,11 @@ export interface SlowQueryEvent extends QueryEvent {
     /** The threshold that was exceeded (in ms) */
     threshold: number;
 }
+/**
+ * Connection-pool sizing and lifecycle. A pooled connection is shared, so
+ * session state set on one query is not guaranteed to be visible to the next —
+ * use `onConnect` for settings that must apply to every connection.
+ */
 export interface PoolOptions {
     /** Maximum number of connections in the pool */
     max?: number;
@@ -678,6 +693,11 @@ export interface PoolOptions {
     /** Log pool operations (acquire, release, etc.) */
     logPoolOperations?: boolean;
 }
+/**
+ * Automatic retry policy for transient connection failures. `match` decides
+ * which errors are considered transient; anything unmatched fails immediately
+ * rather than being retried.
+ */
 export interface RetryOptions {
     /** Maximum number of retry attempts (default: 3) */
     max?: number;
@@ -692,6 +712,10 @@ export interface RetryOptions {
     /** Maximum backoff time in ms (default: 10000) */
     backoffMax?: number;
 }
+/**
+ * Per-model configuration: the table it maps to, whether timestamps and soft
+ * deletes are managed, and how attribute names are converted to column names.
+ */
 export interface ModelOptions {
     tableName?: string;
     /** Schema to use for this model (PostgreSQL) or database (MySQL) */
@@ -768,12 +792,20 @@ export declare enum SortDirection {
     ASC = "ASC",
     DESC = "DESC"
 }
+/**
+ * One column within an index, with the per-column modifiers (sort direction,
+ * collation, prefix length) that the engine supports.
+ */
 export interface IndexField {
     name: string;
     length?: number;
     order?: SortDirection | 'ASC' | 'DESC';
     collate?: string;
 }
+/**
+ * An index to create alongside the table. `where` produces a partial index,
+ * which several engines do not support — see the indexes guide for the matrix.
+ */
 export interface IndexOptions {
     name?: string;
     /** Single field name or array of field names for composite indexes */
@@ -809,6 +841,10 @@ export interface IndexExpression {
     /** Optional name for the expression */
     name?: string;
 }
+/**
+ * A table constraint: primary key, unique, check, foreign key or exclusion.
+ * Composite constraints list every participating column in `fields`.
+ */
 export interface ConstraintOptions {
     /** Custom constraint name (auto-generated if not provided) */
     name?: string;
@@ -1021,6 +1057,10 @@ export interface InstanceValidateOptions {
     /** Validate on update only (for instance validation) */
     validateOnUpdate?: boolean;
 }
+/**
+ * A named, reusable fragment of `FindOptions` that a model can apply by name,
+ * either always (the default scope) or on request.
+ */
 export interface ScopeOptions {
     attributes?: FindOptions['attributes'];
     where?: WhereOptions;
@@ -1030,10 +1070,21 @@ export interface ScopeOptions {
     offset?: number;
     transaction?: Transaction;
 }
+/**
+ * Model-level validators, which run after per-attribute validation and can
+ * therefore see the whole instance — the place for rules that span fields.
+ */
 export interface ModelValidationOptions {
     [key: string]: ValidationMethod | ValidationChain;
 }
+/**
+ * The name of a built-in validator, or a custom function.
+ */
 export type ValidationMethod = (value: any) => boolean | string | Error;
+/**
+ * An ordered list of validators applied to one attribute, evaluated until one
+ * fails.
+ */
 export interface ValidationChain {
     is: [RegExp | string, string?];
     not: [RegExp | string, string?];
@@ -1063,89 +1114,164 @@ export interface ValidationChain {
     max: number;
     min: number;
 }
+/**
+ * Any column type. The union covers the built-in `DataTypes` factories and the
+ * dialect-specific types layered on top of them.
+ */
 export type DataType = DataTypeString | DataTypeChar | DataTypeText | DataTypeNumber | DataTypeInteger | DataTypeBigInt | DataTypeFloat | DataTypeDouble | DataTypeDecimal | DataTypeBoolean | DataTypeDate | DataTypeDateOnly | DataTypeTime | DataTypeBlob | DataTypeEnum | DataTypeJSON | DataTypeJSONB | DataTypeUUID | DataTypeGeometry | DataTypeSET | DataTypeHStore | DataTypeRange | DataTypeInet | DataTypeCidr | DataTypeMacAddr | string;
+/**
+ * The shape every data type shares: a `key` identifying it and a `toSql()`
+ * that renders the engine-specific column type.
+ */
 export interface DataTypeAbstract {
     key: string;
     toSql?: () => string;
 }
+/**
+ * Variable-length character data, `VARCHAR(n)` on most engines.
+ */
 export interface DataTypeString extends DataTypeAbstract {
     key: 'STRING';
     length: number;
 }
+/**
+ * Fixed-length character data, `CHAR(n)`; shorter values are space-padded.
+ */
 export interface DataTypeChar extends DataTypeAbstract {
     key: 'CHAR';
     length: number;
 }
+/**
+ * Unbounded character data. The size variants map to the engine's own
+ * `TINYTEXT`/`MEDIUMTEXT`/`LONGTEXT` where those exist.
+ */
 export interface DataTypeText extends DataTypeAbstract {
     key: 'TEXT';
     length?: number;
 }
+/**
+ * Shared options for the numeric types: precision, scale, sign and zero-fill.
+ */
 export interface DataTypeNumber extends DataTypeAbstract {
     key: 'NUMBER';
     precision: number;
     scale: number;
 }
+/**
+ * A 32-bit integer.
+ */
 export interface DataTypeInteger extends DataTypeAbstract {
     key: 'INTEGER';
     length?: number;
     unsigned?: boolean;
     zerofill?: boolean;
 }
+/**
+ * A 64-bit integer. Values beyond `Number.MAX_SAFE_INTEGER` are returned as
+ * strings by most drivers, so treat the result as a string when the range
+ * matters.
+ */
 export interface DataTypeBigInt extends DataTypeAbstract {
     key: 'BIGINT';
     length?: number;
     unsigned?: boolean;
 }
+/**
+ * Single-precision floating point. Inexact — do not use for money.
+ */
 export interface DataTypeFloat extends DataTypeAbstract {
     key: 'FLOAT';
     length?: number;
     decimals?: number;
     unsigned?: boolean;
 }
+/**
+ * Double-precision floating point. Inexact — do not use for money.
+ */
 export interface DataTypeDouble extends DataTypeAbstract {
     key: 'DOUBLE';
     length?: number;
     decimals?: number;
     unsigned?: boolean;
 }
+/**
+ * Exact fixed-point numeric with the given precision and scale. The type to
+ * use for money.
+ */
 export interface DataTypeDecimal extends DataTypeAbstract {
     key: 'DECIMAL';
     precision: number;
     scale: number;
     unsigned?: boolean;
 }
+/**
+ * A boolean. Engines without a native boolean store it as a small integer or
+ * a single character; the dialect handles the conversion.
+ */
 export interface DataTypeBoolean extends DataTypeAbstract {
     key: 'BOOLEAN';
 }
+/**
+ * A timestamp, with time zone where the engine supports one.
+ */
 export interface DataTypeDate extends DataTypeAbstract {
     key: 'DATE';
     precision?: number;
     timezone?: boolean;
 }
+/**
+ * A calendar date with no time component.
+ */
 export interface DataTypeDateOnly extends DataTypeAbstract {
     key: 'DATEONLY';
 }
+/**
+ * A time of day with no date component.
+ */
 export interface DataTypeTime extends DataTypeAbstract {
     key: 'TIME';
     precision?: number;
 }
+/**
+ * Binary data. The size variants map to the engine's own blob types.
+ */
 export interface DataTypeBlob extends DataTypeAbstract {
     key: 'BLOB';
     length?: 'tiny' | 'medium' | 'long';
 }
+/**
+ * A column restricted to a fixed set of string values. Engines without native
+ * enums emit a check constraint instead.
+ */
 export interface DataTypeEnum extends DataTypeAbstract {
     key: 'ENUM';
     values: string[];
 }
+/**
+ * A JSON document. Values round-trip as parsed JavaScript values on every
+ * dialect — the write side encodes and the read side parses, so a string is
+ * returned as the string it was stored as.
+ */
 export interface DataTypeJSON extends DataTypeAbstract {
     key: 'JSON';
 }
+/**
+ * PostgreSQL's binary JSON: indexable and faster to query than {@link
+ * DataTypeJSON}, at the cost of not preserving key order or whitespace.
+ */
 export interface DataTypeJSONB extends DataTypeAbstract {
     key: 'JSONB';
 }
+/**
+ * A UUID, stored natively where the engine has the type and as a 36-character
+ * string where it does not.
+ */
 export interface DataTypeUUID extends DataTypeAbstract {
     key: 'UUID';
 }
+/**
+ * A spatial value (point, polygon and so on), with an optional SRID.
+ */
 export interface DataTypeGeometry extends DataTypeAbstract {
     key: 'GEOMETRY';
     type: string;
@@ -1175,6 +1301,10 @@ export interface SetColumnOptions {
     /** Optional name for the SET type (useful for custom types) */
     name?: string;
 }
+/**
+ * A computed attribute that exists on the instance but has no column. Declare
+ * the fields it reads so a query that selects it also selects its inputs.
+ */
 export interface DataTypeVirtual extends DataTypeAbstract {
     key: 'VIRTUAL';
     returnType?: DataType;
@@ -1223,6 +1353,10 @@ export interface DataTypeHStore extends DataTypeAbstract {
  * - daterange: Range of date
  */
 export type RangeSubtype = 'int4range' | 'int8range' | 'numrange' | 'tsrange' | 'tstzrange' | 'daterange';
+/**
+ * A PostgreSQL range type over another type, such as `int4range` or
+ * `tstzrange`.
+ */
 export interface DataTypeRange extends DataTypeAbstract {
     key: 'RANGE';
     subtype: RangeSubtype;
@@ -1321,6 +1455,10 @@ export interface ArrayOperatorOptions {
     /** Array ALL operator */
     $arrayAll?: any;
 }
+/**
+ * One column of a model: its type, nullability, default, key membership and
+ * the name it maps to in the database.
+ */
 export interface AttributeOptions {
     type: DataType;
     allowNull?: boolean;
@@ -1352,6 +1490,10 @@ export interface AttributeOptions {
     hidden?: boolean;
     virtual?: boolean;
 }
+/**
+ * The target of a foreign key — which table and column it points at, and what
+ * happens on update or delete.
+ */
 export interface ReferenceOptions {
     model: string | ModelStatic<any>;
     key?: string;
@@ -1359,6 +1501,11 @@ export interface ReferenceOptions {
     onDelete?: ReferentialAction | 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT';
     onUpdate?: ReferentialAction | 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION' | 'SET DEFAULT';
 }
+/**
+ * The lifecycle callbacks a model can declare. `beforeSave`/`afterSave` wrap
+ * both create and update, so shared logic belongs there rather than duplicated
+ * across the pair.
+ */
 export interface ModelHooks {
     beforeValidate?: HookHandler;
     afterValidate?: HookHandler;
@@ -1379,10 +1526,25 @@ export interface ModelHooks {
     beforeFind?: FindHookHandler;
     afterFind?: AfterFindHookHandler;
 }
+/**
+ * A hook that runs before a read, and may modify the options in place.
+ */
 export type FindHookHandler = (options: FindOptions, model: ModelStatic<any>) => Promise<void> | void;
+/**
+ * A hook that runs after a read, receiving the instances it produced.
+ */
 export type AfterFindHookHandler = (instances: Model[], options: FindOptions, model: ModelStatic<any>) => Promise<void> | void;
+/**
+ * A hook receiving a single instance and the options for the operation.
+ */
 export type HookHandler = (instance: Model, options?: HookOptions) => Promise<void> | void;
+/**
+ * A hook receiving every instance in a bulk operation at once.
+ */
 export type BulkHookHandler = (instances?: Model[], options?: HookOptions) => Promise<void> | void;
+/**
+ * Controls whether hooks run for an operation, and which ones.
+ */
 export interface HookOptions {
     transaction?: Transaction;
     hooks?: boolean;
@@ -1394,9 +1556,16 @@ export interface HookOptions {
     model?: any;
     instances?: Model[];
 }
+/**
+ * A `WHERE` clause: attribute/value pairs, operator objects, or nested
+ * `and`/`or`/`not` groups.
+ */
 export type WhereOptions<T = any> = {
     [key: string]: any;
 } | WhereLogical<T>;
+/**
+ * The logical combinators available inside a `WHERE` clause.
+ */
 export interface WhereLogical<T> {
     $and?: WhereOptions<T>[];
     $or?: WhereOptions<T>[];
@@ -1468,6 +1637,10 @@ export interface SubqueryOptions {
 export type HavingOptions<T = any> = {
     [key: string]: any;
 } | HavingLogical<T>;
+/**
+ * The logical combinators available inside a `HAVING` clause, applied after
+ * grouping rather than before it.
+ */
 export interface HavingLogical<T> {
     $and?: HavingOptions<T>[];
     $or?: HavingOptions<T>[];
@@ -1482,6 +1655,9 @@ export interface HavingLogical<T> {
  * - Literal SQL with alias: [['COUNT(*)', 'count']]
  */
 export type AttributeValue = string | [any, string] | [any, any, string];
+/**
+ * Which columns to select — a list, or an include/exclude pair.
+ */
 export type AttributesOptions = string[] | {
     include?: string[];
     exclude?: string[];
@@ -1533,6 +1709,11 @@ export interface UnpivotOptions {
     /** Name for the column name column in the result */
     nameColumn: string;
 }
+/**
+ * The single options object every finder compiles into SQL. `where`,
+ * `include`, `order`, `limit`, locking and the rest behave identically
+ * whichever finder you call.
+ */
 export interface FindOptions {
     where?: WhereOptions;
     attributes?: AttributesOptions;
@@ -1734,6 +1915,10 @@ export interface FindOptions {
      */
     streamHighWatermark?: number;
 }
+/**
+ * Options for `findOrCreate`: the search criteria plus the `defaults` used
+ * only when nothing matched.
+ */
 export interface FindOrCreateOptions<T = any> extends FindOptions {
     /** Default values to use when creating a new record if not found */
     defaults?: Partial<T>;
@@ -1742,6 +1927,10 @@ export interface FindOrCreateOptions<T = any> extends FindOptions {
     /** Whether to validate the model before creation (default: true) */
     validate?: boolean;
 }
+/**
+ * An `ORDER BY` clause. Use the array-of-arrays form — a bare string is not
+ * parsed into column and direction.
+ */
 export type Order = OrderItem[] | string | [string, string][] | import('../operators').OrderExpression[];
 /**
  * Options for JSON path extraction
@@ -1854,6 +2043,9 @@ export interface DWithinOptions {
  * GROUP BY clause format
  */
 export type GroupBy = string | string[] | GroupByItem[];
+/**
+ * One `GROUP BY` term: a column, a literal, or a function call.
+ */
 export interface GroupByItem {
     model?: ModelStatic<any>;
     as?: string;
@@ -1929,6 +2121,10 @@ export interface NowaitOptions {
 export interface SkipLockedOptions {
     skipLocked: true;
 }
+/**
+ * An association to eager-load, given as the model, its alias, or a full
+ * {@link IncludeOptions}.
+ */
 export interface Includeable {
     /** The model to include */
     model: ModelStatic<any>;
@@ -1954,6 +2150,10 @@ export interface Includeable {
      */
     as?: string;
 }
+/**
+ * A single eager-loaded association: which one, what to select from it,
+ * whether it filters the parent (`required`), and any nesting beneath it.
+ */
 export interface IncludeOptions extends Includeable {
     where?: WhereOptions;
     attributes?: string[] | {
@@ -2136,6 +2336,10 @@ export interface AntiJoinOptions {
      */
     type?: 'notExists' | 'notIn' | 'leftJoinIsNull';
 }
+/**
+ * Options for inserting one row: which fields to write, whether to validate,
+ * and the transaction to run inside.
+ */
 export interface CreateOptions extends SaveOptions {
     include?: Includeable[] | IncludeOptions[];
     ignoreDuplicates?: boolean;
@@ -2150,6 +2354,10 @@ export interface CreateOptions extends SaveOptions {
      */
     using?: string;
 }
+/**
+ * Options for updating rows: the `where` that selects them, which fields may
+ * be written, and whether hooks run per row.
+ */
 export interface UpdateOptions extends SaveOptions {
     where: WhereOptions;
     limit?: number;
@@ -2168,6 +2376,10 @@ export interface UpdateOptions extends SaveOptions {
      */
     using?: string;
 }
+/**
+ * Options for deleting rows. On a paranoid model this soft-deletes unless
+ * `force` is set.
+ */
 export interface DestroyOptions extends HookOptions {
     where: WhereOptions;
     limit?: number;
@@ -2190,6 +2402,9 @@ export interface DestroyOptions extends HookOptions {
      */
     using?: string;
 }
+/**
+ * Options for persisting an instance, whether that is an insert or an update.
+ */
 export interface SaveOptions {
     transaction?: Transaction;
     hooks?: boolean;
@@ -2199,6 +2414,9 @@ export interface SaveOptions {
     logging?: boolean | ((sql: string, time?: number) => void);
     benchmark?: boolean;
 }
+/**
+ * Options for refetching an instance's current database state.
+ */
 export interface ReloadOptions extends FindOptions {
     /**
      * Specify attributes to select when reloading from the database.
@@ -2210,6 +2428,10 @@ export interface ReloadOptions extends FindOptions {
      */
     hooks?: boolean;
 }
+/**
+ * Shared options for every association: the alias it is exposed under, the
+ * foreign key, and what happens to children when the parent goes.
+ */
 export interface AssociationOptions {
     as?: string;
     /**
@@ -2253,6 +2475,10 @@ export interface AssociationOptions {
     through?: string | ThroughOptions;
     scope?: AssociationScope;
 }
+/**
+ * Foreign-key specifics for an association, when the defaults derived from
+ * the model names are not what you want.
+ */
 export interface AssociationForeignKeyOptions {
     /** Custom name for the foreign key constraint */
     name?: string;
@@ -2270,6 +2496,10 @@ export interface AssociationForeignKeyOptions {
     /** Custom constraint name for the foreign key (alternative to 'name') */
     constraintName?: string;
 }
+/**
+ * The join table of a many-to-many association, and any extra attributes
+ * carried on it.
+ */
 export interface ThroughOptions {
     model: string | ModelStatic<any>;
     as?: string;
@@ -2278,6 +2508,10 @@ export interface ThroughOptions {
     scope?: AssociationScope;
     timestamps?: boolean;
 }
+/**
+ * A filter applied to every query through an association — the mechanism
+ * behind polymorphic associations.
+ */
 export interface AssociationScope {
     [key: string]: any;
 }
@@ -2294,6 +2528,10 @@ export declare class Transaction {
     commit(): Promise<void>;
     rollback(): Promise<void>;
 }
+/**
+ * Options for a transaction: isolation level, type, and whether it nests as a
+ * savepoint inside an outer transaction.
+ */
 export interface TransactionOptions {
     autocommit?: boolean;
     /**
@@ -2347,6 +2585,10 @@ export declare enum IsolationLevel {
     RepeatableRead = "REPEATABLE READ",
     Serializable = "SERIALIZABLE"
 }
+/**
+ * The static side of a model class — the finders, writers and association
+ * declarations, as opposed to an instance of it.
+ */
 export interface ModelStatic<T extends Model> {
     name: string;
     tableName: string;
@@ -2742,6 +2984,10 @@ export interface ToJSONOptions {
      */
     clone?: boolean;
 }
+/**
+ * The instance side of a model: the attribute accessors plus `save`,
+ * `update`, `destroy`, `reload` and the association helpers.
+ */
 export interface Model {
     getDataValue(key: string): any;
     setDataValue(key: string, value: any): void;
@@ -2765,6 +3011,10 @@ export interface Model {
     reload(options?: FindOptions): Promise<this>;
     toJSON(options?: ToJSONOptions): Record<string, any>;
 }
+/**
+ * A declared relationship between two models, and the metadata the query
+ * builder needs to join them.
+ */
 export interface Association {
     source: ModelStatic<any>;
     target: ModelStatic<any>;
@@ -2775,6 +3025,10 @@ export interface Association {
     targetKey?: string | string[];
     sourceKey?: string | string[];
 }
+/**
+ * Options for inserting many rows in one statement, including upsert
+ * behaviour and whether each row is validated.
+ */
 export interface BulkCreateOptions extends CreateOptions {
     ignoreDuplicates?: boolean;
     validate?: boolean;
@@ -2789,10 +3043,17 @@ export interface BulkCreateOptions extends CreateOptions {
     /** Fields to update on conflict in upsert */
     updateOnDuplicate?: string[];
 }
+/**
+ * Options for `count`, including `distinct` and the `where`/`include` that
+ * narrow what is counted.
+ */
 export interface CountOptions extends FindOptions {
     distinct?: boolean;
     col?: string;
 }
+/**
+ * Options for `sum`, `min`, `max` and friends.
+ */
 export interface AggregateOptions extends FindOptions {
     plain?: boolean;
 }
@@ -2824,6 +3085,10 @@ export interface WindowFunctionOptions {
     /** Default value for LAG/LEAD functions when the offset goes beyond the partition */
     defaultValue?: any;
 }
+/**
+ * Options for an insert-or-update, including which columns decide whether a
+ * row already exists.
+ */
 export interface UpsertOptions extends Omit<UpdateOptions, 'where'>, CreateOptions {
     /** Fields to use for conflict resolution (ON CONFLICT for PostgreSQL/SQLite, ON DUPLICATE KEY for MySQL) */
     conflictFields?: string[];
@@ -2846,22 +3111,38 @@ export interface UpsertOptions extends Omit<UpdateOptions, 'where'>, CreateOptio
     /** Whether to use paranoid mode when fetching the instance after upsert */
     paranoid?: boolean;
 }
+/**
+ * Options for emptying a table, including whether to cascade to dependents
+ * and restart identity sequences.
+ */
 export interface TruncateOptions extends HookOptions {
     cascade?: boolean;
     restartIdentity?: boolean;
 }
+/**
+ * Options for dropping a table.
+ */
 export interface DropOptions extends HookOptions {
     cascade?: boolean;
 }
+/**
+ * Which validations to run, and whether to stop at the first failure.
+ */
 export interface ValidationOptions {
     fields?: string[];
     validate?: boolean;
     hooks?: boolean;
 }
+/**
+ * Options for undoing a soft delete on a paranoid model.
+ */
 export interface RestoreOptions extends HookOptions {
     where?: WhereOptions;
     limit?: number;
 }
+/**
+ * Shared options for atomic increment and decrement.
+ */
 export interface IncrementDecrementOptions extends HookOptions {
     /** Amount to increment/decrement by (default: 1) */
     by?: number;
@@ -2870,21 +3151,39 @@ export interface IncrementDecrementOptions extends HookOptions {
     /** Whether to reload the instance after the operation (default: true) */
     reload?: boolean;
 }
+/**
+ * Options for atomically adding to numeric columns, done in SQL so concurrent
+ * writers do not lose updates.
+ */
 export interface IncrementOptions extends IncrementDecrementOptions {
 }
+/**
+ * Options for atomically subtracting from numeric columns.
+ */
 export interface DecrementOptions extends IncrementDecrementOptions {
 }
+/**
+ * Raised when one or more validators reject an instance; `errors` holds one
+ * entry per failure.
+ */
 export interface ValidationError extends Error {
     name: string;
     message: string;
     errors: ValidationErrorItem[];
 }
+/**
+ * A single validation failure: which attribute, which validator, and the
+ * message it produced.
+ */
 export interface ValidationErrorItem {
     message: string;
     type: string;
     path: string;
     value: any;
 }
+/**
+ * The rows and metadata returned by a query.
+ */
 export interface QueryResult {
     rows: any[];
     rowCount: number;
@@ -2904,6 +3203,9 @@ export interface QueryResult {
      */
     resultSets?: any[][];
 }
+/**
+ * Column metadata a driver reports for a result set.
+ */
 export interface FieldInfo {
     name: string;
     type: string;
@@ -2914,6 +3216,10 @@ export interface FieldInfo {
     isEnum: boolean;
     isPrimaryKey: boolean;
 }
+/**
+ * The result of `query()`, whose shape depends on the statement and the
+ * `type` given in {@link QueryOptions}.
+ */
 export interface RawQueryResult {
     rows: any[];
     count: number;
@@ -2927,6 +3233,10 @@ export interface RawQueryResult {
  */
 import { QueryTypes } from './query-types';
 export { QueryTypes };
+/**
+ * Options for a raw query: how to interpret the result, what to bind, and
+ * whether to map rows onto a model.
+ */
 export interface QueryOptions {
     plain?: boolean;
     raw?: boolean;
@@ -3004,12 +3314,20 @@ export interface StreamOptions {
      */
     logging?: boolean | ((sql: string, time?: number) => void);
 }
+/**
+ * Raised when the database rejects a statement; carries the driver's own
+ * error alongside the SQL that produced it.
+ */
 export interface QueryError extends Error {
     parent?: Error;
     original?: Error;
     sql?: string;
     parameters?: any[];
 }
+/**
+ * Options for `sync()`. `force` drops and recreates; `alter` tries to migrate
+ * an existing table in place.
+ */
 export interface SyncOptions {
     /**
      * If true, drop all tables first before recreating them.
@@ -3132,16 +3450,28 @@ export interface ReplicationOptions {
     /** Whether to automatically fail over to master on all replicas unhealthy */
     autoFailover?: boolean;
 }
+/**
+ * A row materialised as an object, with its attributes and instance methods.
+ */
 export type ModelInstance<T = any> = any;
+/**
+ * One node of a Redis cluster used as a cache backend.
+ */
 export interface RedisClusterNode {
     host: string;
     port: number;
     tls?: boolean;
 }
+/**
+ * The in-process first-level cache that sits in front of a shared cache.
+ */
 export interface L1CacheOptions {
     maxItems: number;
     ttl: number;
 }
+/**
+ * Configuration for using a Redis cluster as the shared cache.
+ */
 export interface RedisClusterCacheOptions {
     nodes: RedisClusterNode[];
     maxRedirects?: number;
@@ -3152,6 +3482,10 @@ export interface RedisClusterCacheOptions {
     lazyConnect?: boolean;
     l1?: L1CacheOptions;
 }
+/**
+ * How query results are cached: which backend, for how long, and how entries
+ * are invalidated when a write touches the same table.
+ */
 export interface CacheManagerOptions {
     keyPrefix?: string;
     defaultTtl?: number;