imodel 0.19.1 → 0.19.3

package/index.d.mts

@@ -1,5 +1,5 @@
 /*!
- * imodel v0.19.1
+ * imodel v0.19.3
  * (c) 2019-2026 undefined
  * @license undefined
  */
@@ -508,10 +508,126 @@ type FieldDecorator<T> = (val: {
 }, ctx: ClassAccessorDecoratorContext) => any;
 type MethodDecorator<T extends Function> = (val: T, ctx: ClassMethodDecoratorContext<any, T>) => any;
 
+declare class ConnectionError extends Error {
+    /**
+     * @param {string} code - 自定义通用错误码 (例如 constraint:unique)
+     * @param {string} message - 原始错误信息或自定义信息
+     */
+    constructor(code: string, message: string);
+    /** @type {string} */
+    code: string;
+}
+/**
+ * 非空约束违规
+ * 对应 PG 23502 / MySQL 1048
+ * 场景：插入数据时，必填字段为空
+ */
+declare class NotNullViolationError extends ConnectionError {
+    /** @type {string} */
+    table: string;
+    /** @type {string} */
+    column: string;
+}
+/**
+ * 唯一性约束违规
+ * 对应 PG 23505 / MySQL 1062
+ * 支持单字段和多字段组合冲突
+ */
+declare class UniqueViolationError extends ConnectionError {
+    /**
+     * @param {string} table - 表名
+     * @param {string | string[]} columns - 冲突的列名（可以是字符串或字符串数组）
+     * @param {any} [values] - 导致冲突的值（可选，多字段时为对象或数组）
+     */
+    constructor(table: string, columns: string | string[], values?: any);
+    /** @type {string} */
+    table: string;
+    /** @type {string[]} */
+    columns: string[];
+    /** @type {any} */
+    values: any;
+}
+/**
+ * 外键约束违规
+ * 对应 PG 23503 / MySQL 1452
+ * 场景：插入了一个不存在的 user_id
+ */
+declare class ForeignKeyViolationError extends ConnectionError {
+    /**
+     * @param {string} table - 当前操作的表
+     * @param {string | string[]} columns - 当前操作的外键列
+     * @param {string} [referencedTable] - 被引用的父表
+     */
+    constructor(table: string, columns: string | string[], referencedTable?: string);
+    /** @type {string} */
+    table: string;
+    /** @type {string[]} */
+    columns: string[];
+    /** @type {string} */
+    referencedTable: string;
+}
+/**
+ * 检查约束违规
+ * 对应 PG 23514
+ * 场景：年龄字段要求 > 0，但插入了 -5
+ */
+declare class CheckViolationError extends ConnectionError {
+    /**
+     * @param {string} table - 当前操作的表
+     * @param {string} [constraint] - 当前操作的外键列
+     */
+    constructor(table: string, constraint?: string);
+    /** @type {string} */
+    table: string;
+    /** @type {string} */
+    constraint: string;
+}
+/**
+ * 无效的类型输入语法错误
+ * 对应 PG 22P02
+ * 场景：无效的 UUID、日期格式错误等
+ */
+declare class InvalidInputSyntaxError extends ConnectionError {
+    /**
+     * @param {string} message - 目标数据类型
+     */
+    constructor(message: string);
+}
+/**
+ * 操作符不匹配错误
+ * 对应 PG 42883
+ * 场景：uuid = integer 等类型不兼容的操作
+ */
+declare class OperatorMismatchError extends ConnectionError {
+    /**
+     * @param {string} message
+     */
+    constructor(message: string);
+}
+
+type errors_CheckViolationError = CheckViolationError;
+declare const errors_CheckViolationError: typeof CheckViolationError;
+type errors_ConnectionError = ConnectionError;
+declare const errors_ConnectionError: typeof ConnectionError;
+type errors_ForeignKeyViolationError = ForeignKeyViolationError;
+declare const errors_ForeignKeyViolationError: typeof ForeignKeyViolationError;
+type errors_InvalidInputSyntaxError = InvalidInputSyntaxError;
+declare const errors_InvalidInputSyntaxError: typeof InvalidInputSyntaxError;
+type errors_NotNullViolationError = NotNullViolationError;
+declare const errors_NotNullViolationError: typeof NotNullViolationError;
+type errors_OperatorMismatchError = OperatorMismatchError;
+declare const errors_OperatorMismatchError: typeof OperatorMismatchError;
+type errors_UniqueViolationError = UniqueViolationError;
+declare const errors_UniqueViolationError: typeof UniqueViolationError;
+declare namespace errors {
+  export { errors_CheckViolationError as CheckViolationError, errors_ConnectionError as ConnectionError, errors_ForeignKeyViolationError as ForeignKeyViolationError, errors_InvalidInputSyntaxError as InvalidInputSyntaxError, errors_NotNullViolationError as NotNullViolationError, errors_OperatorMismatchError as OperatorMismatchError, errors_UniqueViolationError as UniqueViolationError };
+}
+
 interface Environment<T extends object> {
     transaction: T | null;
     isDevelopment: boolean;
     values: typeof values;
+    errors: typeof errors;
 }
 
 /** 特性支持情况 */
@@ -1373,6 +1489,7 @@ interface Options {
     update?: Record<string, SetValue>;
     alias?: string;
     group?: string[];
+    lock?: 'S' | 'X' | null;
 }
 interface Queryable<T extends Fields = Fields> extends TableDefine<T> {
     readonly options: Options;
@@ -1397,6 +1514,7 @@ interface JOIN {
     alias?: string;
     condition?: WhereValue[];
 }
+type LockType = 'S' | 'X';
 interface SelectItem {
     distinct?: boolean;
     select: [string, Select][];
@@ -1413,6 +1531,7 @@ interface SelectItem {
     offset?: number;
     /** 最大返回数 */
     limit?: number;
+    lock?: LockType | null;
 }
 type GetName = (table?: string) => string;
 interface DBColumn {
@@ -1486,6 +1605,17 @@ interface Skip {
 interface TransactionFn {
     <T>(fn: (t: Connection) => PromiseLike<T> | T): Promise<T>;
 }
+type TransactionHandlerArray = [
+    promise: TransactionHandler['promise'],
+    commit: TransactionHandler['commit'],
+    rollback: TransactionHandler['rollback']
+];
+interface TransactionHandler extends TransactionHandlerArray {
+    promise: Promise<void>;
+    commit(): Promise<void>;
+    rollback(e?: any): Promise<void>;
+    [Symbol.dispose](): void;
+}
 
 declare const Destroy: unique symbol;
 interface Destroy {
@@ -1991,9 +2121,10 @@ declare class Connection<E extends {} = {}> {
     transaction<T>(fn: (t: Connection) => PromiseLike<T> | T): Promise<T>;
     /**
      * @overload
-     * @returns {[Promise<void>, commit: () => Promise<void>, rollback: (e?: any) => Promise<void>]}
+     * @returns {TransactionHandler}
      */
-    transaction(): [Promise<void>, commit: () => Promise<void>, rollback: (e?: any) => Promise<void>];
+    transaction(): TransactionHandler;
+    [Symbol.dispose](): void;
     #private;
 }
 
@@ -2014,8 +2145,12 @@ declare function isPseudo(model: Queryable): boolean;
 
 /** @import { SelectItem } from './types' */
 declare class Subquery {
-    /** @returns {SelectItem[]} */
-    toSubquery(): SelectItem[];
+    /**
+     *
+     * @param {boolean?} [lockable]
+     * @returns {SelectItem[]}
+     */
+    toSubquery(lockable?: boolean | null): SelectItem[];
 }
 
 type QueryOptions<T extends Fields, TB extends unknown = any> = {
@@ -2082,10 +2217,10 @@ declare class Query<T extends Fields, TB extends unknown = any> extends Subquery
     withDeleted(): this;
     /**
      * 增加排序项
-     * @param {...string | boolean | [string, boolean?]} sort
+     * @param {...string | null | boolean | [string, boolean?]} sort
      * @returns {this}
      */
-    sort(...sort: (string | boolean | [string, boolean?])[]): this;
+    sort(...sort: (string | null | boolean | [string, boolean?])[]): this;
     /**
      * 设置获取到的最大数量
      * @param {number} [limit]
@@ -2219,6 +2354,11 @@ declare class Query<T extends Fields, TB extends unknown = any> extends Subquery
      * @param  {boolean} [distinct]
      */
     distinct(distinct?: boolean): this;
+    /**
+     *
+     * @param {LockType?} [lock]
+     */
+    lock(lock?: LockType | null): this;
     /**
      *
      * @param {object} a
@@ -2674,4 +2814,4 @@ declare function toBool(v: any): boolean;
 declare function setDevelopment(d?: boolean): void;
 declare let isDevelopment: boolean;
 
-export { Build, type ClassDecorator, type Column, type ColumnOptions, Connection, type Constraint, Create, type DBColumn, type DBIndex, type DBTable, Destroy, type Environment, type FieldDecorator, type FieldDefine, type FieldDefineOption, type FieldDefineType, type FieldSpecific, type FieldSpecificValue, type FieldType, type FieldTypeDefine, type FieldValue, type Fields, type FindArg, type FindRange, type GetName, type Hook, type Hooks, type IConnection, type Index, type IndexInfo, type IndexOptions, type JOIN, type Join, type JoinType, type MainFieldType, type MaybePromise, type MethodDecorator, Model, type Options, PseudoDestroy, Query, type QueryOptions, type Queryable, Save, Scene, Select, type SelectItem, SetValue, type Skip, Submodel, type Support, type TableConnect, type TableConnection, type TableDefine, type TableType, type TableValue, type ToFieldType, type ToType, type TransactionFn, type VirtualTable, Where, type WhereExists, type WhereItem, type WhereLike, type WhereOr, type WhereRaw, type WhereValue, type Wheres, afterCreate, afterCreateMany, afterDelete, afterUpdate, beforeCreate, beforeCreateMany, beforeDelete, beforeUpdate, bindHooks, coefficient, column, creating, decrement, defaultValue, field as define, deleted, deleting, divide, field$1 as field, getPrimaryFields, getPrimaryKeys, hooks, immutable, increment, index, isDevelopment, isPseudo, mergeHooks, model, multiply, now, primary, prop, pseudo, setDevelopment, sort, model as submodel, toBool, toNot, toPrimaries, toPrimary, uncreatable, undeleted, updating, uuid, values, where, withDeleted };
+export { Build, CheckViolationError, type ClassDecorator, type Column, type ColumnOptions, Connection, ConnectionError, type Constraint, Create, type DBColumn, type DBIndex, type DBTable, Destroy, type Environment, type FieldDecorator, type FieldDefine, type FieldDefineOption, type FieldDefineType, type FieldSpecific, type FieldSpecificValue, type FieldType, type FieldTypeDefine, type FieldValue, type Fields, type FindArg, type FindRange, ForeignKeyViolationError, type GetName, type Hook, type Hooks, type IConnection, type Index, type IndexInfo, type IndexOptions, InvalidInputSyntaxError, type JOIN, type Join, type JoinType, type LockType, type MainFieldType, type MaybePromise, type MethodDecorator, Model, NotNullViolationError, OperatorMismatchError, type Options, PseudoDestroy, Query, type QueryOptions, type Queryable, Save, Scene, Select, type SelectItem, SetValue, type Skip, Submodel, type Support, type TableConnect, type TableConnection, type TableDefine, type TableType, type TableValue, type ToFieldType, type ToType, type TransactionFn, type TransactionHandler, type TransactionHandlerArray, UniqueViolationError, type VirtualTable, Where, type WhereExists, type WhereItem, type WhereLike, type WhereOr, type WhereRaw, type WhereValue, type Wheres, afterCreate, afterCreateMany, afterDelete, afterUpdate, beforeCreate, beforeCreateMany, beforeDelete, beforeUpdate, bindHooks, coefficient, column, creating, decrement, defaultValue, field as define, deleted, deleting, divide, field$1 as field, getPrimaryFields, getPrimaryKeys, hooks, immutable, increment, index, isDevelopment, isPseudo, mergeHooks, model, multiply, now, primary, prop, pseudo, setDevelopment, sort, model as submodel, toBool, toNot, toPrimaries, toPrimary, uncreatable, undeleted, updating, uuid, values, where, withDeleted };

package/index.mjs

@@ -1,5 +1,5 @@
 /*!
- * imodel v0.19.1
+ * imodel v0.19.3
  * (c) 2019-2026 undefined
  * @license undefined
  */
@@ -15,8 +15,12 @@ function setDevelopment(d) {
 
 /** @import { SelectItem } from './types' */
 class Subquery {
-  /** @returns {SelectItem[]} */
-  toSubquery() {
+  /**
+   *
+   * @param {boolean?} [lockable]
+   * @returns {SelectItem[]}
+   */
+  toSubquery(lockable) {
     throw new Error('toSubquery 方法未在子类中实现');
   }
 }
@@ -800,31 +804,192 @@ var values = /*#__PURE__*/Object.freeze({
     uuid: uuid
 });
 
+class ConnectionError extends Error {
+  /** @type {string} */
+
+  /**
+   * @param {string} code - 自定义通用错误码 (例如 constraint:unique)
+   * @param {string} message - 原始错误信息或自定义信息
+   */
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+/**
+ * 非空约束违规
+ * 对应 PG 23502 / MySQL 1048
+ * 场景：插入数据时，必填字段为空
+ */
+class NotNullViolationError extends ConnectionError {
+  /** @type {string} */
+
+  /** @type {string} */
+
+  /**
+   * @param {string} table - 表名
+   * @param {string} column - 列名
+   */
+  constructor(table, column) {
+    const msg = `Column '${column}' in table '${table}' cannot be null`;
+    super('constraint:notNull', msg);
+    this.table = table;
+    this.column = column;
+  }
+}
+/**
+ * 唯一性约束违规
+ * 对应 PG 23505 / MySQL 1062
+ * 支持单字段和多字段组合冲突
+ */
+class UniqueViolationError extends ConnectionError {
+  /** @type {string} */
+
+  /** @type {string[]} */
+
+  /** @type {any} */
+
+  /**
+   * @param {string} table - 表名
+   * @param {string | string[]} columns - 冲突的列名（可以是字符串或字符串数组）
+   * @param {any} [values] - 导致冲突的值（可选，多字段时为对象或数组）
+   */
+  constructor(table, columns, values = undefined) {
+    // 确保 columns 始终是数组，方便后续处理
+    const cols = Array.isArray(columns) ? columns : [columns];
+    let msg = `Duplicate value for ${cols.join(', ')} in table '${table}'`;
+    if (values !== undefined) {
+      msg += ` (values: ${JSON.stringify(values)})`;
+    }
+    super('constraint:unique', msg);
+    this.table = table;
+    this.columns = cols;
+    this.values = values;
+  }
+}
+/**
+ * 外键约束违规
+ * 对应 PG 23503 / MySQL 1452
+ * 场景：插入了一个不存在的 user_id
+ */
+class ForeignKeyViolationError extends ConnectionError {
+  /** @type {string} */
+
+  /** @type {string[]} */
+
+  /** @type {string} */
+
+  /**
+   * @param {string} table - 当前操作的表
+   * @param {string | string[]} columns - 当前操作的外键列
+   * @param {string} [referencedTable] - 被引用的父表
+   */
+  constructor(table, columns, referencedTable) {
+    // 确保 columns 始终是数组，方便后续处理
+    const cols = Array.isArray(columns) ? columns : [columns];
+    let msg = `Foreign key constraint failed for column ${cols.join(', ')}`;
+    msg += ` in table '${table}'`;
+    if (referencedTable) {
+      msg += ` (references '${referencedTable}')`;
+    }
+    super('constraint:foreignKey', msg);
+    this.table = table;
+    this.columns = cols;
+    this.referencedTable = referencedTable || '';
+  }
+}
+/**
+ * 检查约束违规
+ * 对应 PG 23514
+ * 场景：年龄字段要求 > 0，但插入了 -5
+ */
+class CheckViolationError extends ConnectionError {
+  /** @type {string} */
+
+  /** @type {string} */
+
+  /**
+   * @param {string} table - 当前操作的表
+   * @param {string} [constraint] - 当前操作的外键列
+   */
+  constructor(table, constraint) {
+    let msg = `Check constraint failed in table '${table}'`;
+    if (constraint) {
+      msg += ` (${constraint})`;
+    }
+    super('constraint:check', msg);
+    this.table = table;
+    this.constraint = constraint || '';
+  }
+}
+/**
+ * 无效的类型输入语法错误
+ * 对应 PG 22P02
+ * 场景：无效的 UUID、日期格式错误等
+ */
+class InvalidInputSyntaxError extends ConnectionError {
+  /**
+   * @param {string} message - 目标数据类型
+   */
+  constructor(message) {
+    super('data:type:invalidInputSyntax', message);
+  }
+}
+/**
+ * 操作符不匹配错误
+ * 对应 PG 42883
+ * 场景：uuid = integer 等类型不兼容的操作
+ */
+class OperatorMismatchError extends ConnectionError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super('syntax:operator:mismatch', message);
+  }
+}
+
+var errors = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    CheckViolationError: CheckViolationError,
+    ConnectionError: ConnectionError,
+    ForeignKeyViolationError: ForeignKeyViolationError,
+    InvalidInputSyntaxError: InvalidInputSyntaxError,
+    NotNullViolationError: NotNullViolationError,
+    OperatorMismatchError: OperatorMismatchError,
+    UniqueViolationError: UniqueViolationError
+});
+
 /** @import { Options, Queryable } from '../types' */
 /**
  *
- * @param {Queryable} model
+ * @param {Partial<Queryable>} queryable
  * @returns {Options}
  */
-function getOptions(model) {
+function getOptions({
+  fields,
+  pseudo,
+  options: modelOptions
+}) {
   const options = {
-    ...model.options
+    where: [],
+    ...modelOptions
   };
-  if (!model.pseudo) {
+  if (!pseudo || !fields) {
     return options;
   }
-  if (!(model.pseudo in model.fields)) {
+  if (!(pseudo in fields)) {
     return options;
   }
   if (options.range === undeleted) {
     options.where = [...options.where, {
-      field: model.pseudo,
+      field: pseudo,
       operator: '<>',
       value: 0
     }];
   } else if (options.range !== withDeleted) {
     options.where = [...options.where, {
-      field: model.pseudo,
+      field: pseudo,
       operator: '=',
       value: 0
     }];
@@ -2136,6 +2301,7 @@ function toSelectItem(select, fieldColumns) {
  */
 function select2column(columns, fieldColumns, select) {
   /** @type {[string, Select][]} */
+  // eslint-disable-next-line no-nested-ternary
   const list = Array.isArray(select) ? select.map(v => typeof v === 'string' ? [v, {
     field: v
   }] : v) : select ? Object.entries(select) : [];
@@ -2178,11 +2344,14 @@ function getDefaultSort(columns, noColumn) {
 
 /**
  *
- * @param {[field: string, desc: boolean][]} sort
- * @param {Record<string, string>?} fieldColumns
+ * @param {[field: string, desc: boolean][]?} [sort]
+ * @param {Record<string, string>?} [fieldColumns]
  * @returns {[field: string, desc: boolean][]}
  */
 function sort2column(sort, fieldColumns) {
+  if (!sort) {
+    return [];
+  }
   if (!fieldColumns) {
     return sort;
   }
@@ -2190,7 +2359,7 @@ function sort2column(sort, fieldColumns) {
 }
 
 /** @import Connection from './index.mjs' */
-/** @import { Environment, FieldDefine, Fields, Skip, TableDefine, FieldType, TableConnection, SelectItem } from '../types' */
+/** @import { Environment, FieldDefine, Fields, Skip, TableDefine, FieldType, TableConnection, SelectItem, LockType } from '../types' */
 /**
  * @param {string[] | boolean | null} [items]
  */
@@ -2248,10 +2417,11 @@ function getSelectFields(select, columns, tableFields, baseFieldSet) {
  * @param {[string, FieldDefine<TableDefine>][]} fields
  * @param {Set<string>} baseParentFieldSet
  * @param {Environment} env
+ * @param {LockType?} [lock]
  * @param {Record<string, string[] | undefined>?} [returnFields]
  * @returns {Promise<any[]>}
  */
-async function findSub(conn, list, fields, baseParentFieldSet, env, returnFields) {
+async function findSub(conn, list, fields, baseParentFieldSet, env, lock, returnFields) {
   if (!list.length) {
     return list;
   }
@@ -2291,13 +2461,14 @@ async function findSub(conn, list, fields, baseParentFieldSet, env, returnFields
       columns,
       select,
       where,
-      sort: getDefaultSort(columns, noColumn) || [],
+      sort: getDefaultSort(columns, noColumn),
       group: [],
-      having: []
+      having: [],
+      lock
     }];
     /** @type {PromiseLike<object[]>} */
     const result = table && typeof table === 'object' ? table.select(env, conn, selects) : conn.select(env, selects);
-    let promise = result.then(list => findSub(conn, list, tableFields, baseFieldSet, env, fieldMap));
+    let promise = result.then(list => findSub(conn, list, tableFields, baseFieldSet, env, lock, fieldMap));
     promises.push(array ? promise.then(subList => {
       for (const item of list) {
         item[key] = subList.filter(createFilter(item, mapList));
@@ -2332,7 +2503,8 @@ async function search(conn, that, p, env, returnFields, skip) {
   const {
     sort,
     offset,
-    limit
+    limit,
+    lock
   } = options;
   const [columns, fieldColumns, tableFields] = toColumns(fields);
   const where = where2column(options.where, fieldColumns);
@@ -2344,7 +2516,7 @@ async function search(conn, that, p, env, returnFields, skip) {
   const baseFieldSet = new Set(Object.keys(fieldColumns || columns));
   const selected = fieldMap && getSelectFields(fieldMap[''] || [], columns, tableFields, baseFieldSet) || null;
   const select = select2column(columns, fieldColumns, selected);
-  const sorted = sort?.length ? sort2column(sort, fieldColumns) : getDefaultSort(columns);
+  const sorted = sort2column(sort, fieldColumns);
   /** @type {SelectItem[]} */
   const selects = [{
     table: typeof table === 'string' ? table : '',
@@ -2353,16 +2525,17 @@ async function search(conn, that, p, env, returnFields, skip) {
     where,
     offset,
     limit,
-    sort: sorted || [],
+    sort: sorted,
     group: [],
-    having: []
+    having: [],
+    lock
   }];
   const list = table && typeof table === 'object' ? await table.select(env, conn, selects) : await conn.select(env, selects);
   if (!list.length) {
     return [];
   }
   if (returnFields) {
-    await findSub(conn, list, tableFields, baseFieldSet, env, fieldMap);
+    await findSub(conn, list, tableFields, baseFieldSet, env, lock, fieldMap);
   }
   return list;
 }
@@ -2384,10 +2557,10 @@ async function first(conn, that, p, env, skip) {
     table,
     fields
   } = p;
-  // @ts-ignore
   const options = getOptions(p);
   const {
-    sort
+    sort,
+    lock
   } = options;
   const [columns, fieldColumns, tableFields] = toColumns(fields);
   const where = where2column(options.where, fieldColumns);
@@ -2402,14 +2575,15 @@ async function first(conn, that, p, env, skip) {
     columns,
     where,
     limit: 1,
-    sort: sort?.length ? sort2column(sort, fieldColumns) || [] : getDefaultSort(columns) || [],
+    sort: sort2column(sort, fieldColumns),
     select: select2column(columns, fieldColumns),
     group: [],
-    having: []
+    having: [],
+    lock
   }];
   const list = table && typeof table === 'object' ? await table.select(env, conn, selects) : await conn.select(env, selects);
   const baseFieldSet = new Set(Object.keys(fieldColumns || columns));
-  const [item] = await findSub(conn, list, tableFields, baseFieldSet, env);
+  const [item] = await findSub(conn, list, tableFields, baseFieldSet, env, lock);
   if (!item) {
     return null;
   }
@@ -2581,9 +2755,10 @@ function table2db(tables) {
 /**
  * @template {Fields} T
  * @param {Queryable<T>} queryable
+ * @param {boolean?} [lockable]
  * @returns {SelectItem[]}
  */
-function toSelect(queryable) {
+function toSelect(queryable, lockable) {
   const [columns, fieldColumns, tableFields] = toColumns(queryable.fields);
   const {
     table
@@ -2591,7 +2766,8 @@ function toSelect(queryable) {
   const options = getOptions(queryable);
   const {
     offset,
-    limit
+    limit,
+    lock
   } = options;
   const where = where2column(options.where, fieldColumns);
   where.push(...getFixedValueWhere(columns));
@@ -2607,16 +2783,24 @@ function toSelect(queryable) {
     limit,
     where,
     select,
-    sort: sort?.length ? sort2column(sort, fieldColumns) : getDefaultSort(columns),
+    sort: sort2column(sort, fieldColumns),
     group: options.group || [],
     distinct: Boolean(options.distinct),
-    having: []
+    having: [],
+    lock: lockable ? lock : null
   }];
   return result;
 }
 
 /* eslint-disable max-lines */
 /* eslint-disable max-len */
+/** @import { Wheres } from '../Where.mjs' */
+/** @import { SetValue } from '../set.mjs' */
+/** @import { Environment, TableConnection, TableValue } from '../types' */
+/** @import { Fields, FieldType, FieldValue, IndexOptions, MainFieldType, TableDefine } from '../types/table' */
+/** @import { Queryable } from '../types/options' */
+/** @import { Column, ColumnOptions } from '../types/column' */
+/** @import { DBTable, IConnection, Skip, TableConnect, TableType, TransactionHandler } from '../types/connection' */
 /**
  *
  * @param {Fields<keyof FieldType>} fields
@@ -2675,7 +2859,8 @@ class Connection {
     this.#env = {
       isDevelopment,
       values,
-      transaction
+      transaction,
+      errors
     };
   }
   /**
@@ -3302,11 +3487,11 @@ class Connection {
   }, data, keys, conflictKeys, conflictSet) {
     const [columns, fieldColumns, baseFields] = toColumns(fields);
     const isArray = Array.isArray(data);
-    const insertValues = (isArray ? data : [data]
+    const insertValues = await Promise.all((isArray ? data : [data]
     // @ts-ignore
     ).map(d => getInsertValue(d, columns, fieldColumns, {
       uncreatable: true
-    }));
+    })));
     if (!insertValues.length) {
       throw new Error();
     }
@@ -3467,7 +3652,7 @@ class Connection {
       table
     } = queryable;
     const conn = await this.#getTableConnection(queryable.connect);
-    const selects = toSelect(queryable);
+    const selects = toSelect(queryable, true);
     const result = table && typeof table === 'object' ? await table.select(this.#env, conn, selects) : await conn.select(this.#env, selects);
     return result;
   }
@@ -3636,6 +3821,9 @@ class Connection {
     }
     return false;
   }
+  [Symbol.dispose]() {
+    this.abort();
+  }
   /**
    * @param {string} table
    * @returns {Promise<DBTable?>}
@@ -3676,12 +3864,19 @@ class Connection {
    */
   /**
    * @overload
-   * @returns {[Promise<void>, commit: () => Promise<void>, rollback: (e?: any) => Promise<void>]}
+   * @returns {TransactionHandler}
    */
   /**
    *
-   * @param {(t: Connection, signal: AbortSignal) => any} [fn]
-   * @returns {any}
+   * @template T
+   * @param {(t: Connection, signal: AbortSignal) => PromiseLike<T> | T} [fn]
+   * @returns {Promise<T> | TransactionHandler}
+   */
+  /**
+   *
+   * @template T
+   * @param {(t: Connection, signal: AbortSignal) => PromiseLike<T> | T} [fn]
+   * @returns {Promise<T> | TransactionHandler}
    */
   transaction(fn) {
     if (typeof fn === 'function') {
@@ -3711,13 +3906,24 @@ class Connection {
       }
       return donePromise;
     }).then(() => {}, () => {});
-    return [abortedPromise, async () => {
+    const handler = /** @type {TransactionHandler} */[abortedPromise, () => {
       commit();
       return dbiPromise;
-    }, async () => {
-      rollback();
+    }, e => {
+      rollback(e);
       return dbiPromise;
     }];
+    handler.promise = abortedPromise;
+    handler.commit = () => {
+      commit();
+      return dbiPromise;
+    };
+    handler.rollback = e => {
+      rollback(e);
+      return dbiPromise;
+    };
+    handler[Symbol.dispose] = commit;
+    return handler;
   }
 }
 
@@ -4978,7 +5184,7 @@ function toBool(v) {
   return !falseValues.has(v.toLowerCase());
 }
 
-/** @import { FieldDefine, Fields, Options, Queryable, Select, TableConnect, VirtualTable } from './types' */
+/** @import { FieldDefine, Fields, LockType, Options, Queryable, Select, TableConnect, VirtualTable } from './types' */
 /** @import { WhereValue, Wheres } from './Where.mjs' */
 /**
  *
@@ -5081,8 +5287,9 @@ class Query extends Subquery {
   get options() {
     return this.#options;
   }
-  toSubquery() {
-    return toSelect(this);
+  /** @param {boolean?} [lockable] */
+  toSubquery(lockable) {
+    return toSelect(this, lockable);
   }
   /**
    * @param {QueryOptions<T, TB> | Query<T, TB>} options
@@ -5158,7 +5365,7 @@ class Query extends Subquery {
   }
   /**
    * 增加排序项
-   * @param {...string | boolean | [string, boolean?]} sort
+   * @param {...string | null | boolean | [string, boolean?]} sort
    * @returns {this}
    */
   sort(...sort) {
@@ -5175,10 +5382,19 @@ class Query extends Subquery {
         desc = value[1] === true;
         [value] = value;
       }
-      if (typeof value !== 'string') {
+      if (typeof value === 'string') {
+        list.push([value, desc]);
+        continue;
+      }
+      if (value !== null) {
         continue;
       }
-      list.push([value, desc]);
+      /** @type {[string, boolean, number][]} */
+      const sorted = Object.entries(this.fields).map(([f, d]) => [f, (d.sort || 0) < 0, Math.abs(d.sort || 0)]);
+      const sortFields = sorted.filter(v => v[2]).sort(([,, a], [,, b]) => a - b);
+      for (const [field, desc] of sortFields) {
+        list.push([field, desc]);
+      }
     }
     if (list.length) {
       this.#options.sort = [...(this.#options.sort || []), ...list];
@@ -5499,6 +5715,15 @@ class Query extends Subquery {
     this.#options.distinct = Boolean(distinct);
     return this;
   }
+  /**
+   *
+   * @param {LockType?} [lock]
+   */
+  lock(lock) {
+    const type = typeof lock === 'string' && lock.toUpperCase() || null;
+    this.#options.lock = type === 'S' || type === 'X' ? type : null;
+    return this;
+  }
 }
 
 /** @import { Fields, IndexInfo, FieldDefine } from './types' */
@@ -6833,4 +7058,4 @@ function field(type, {
   };
 }
 
-export { Build, Connection, Create, Destroy, Model, PseudoDestroy, Query, Save, Scene, Submodel, Where, afterCreate, afterCreateMany, afterDelete, afterUpdate, beforeCreate, beforeCreateMany, beforeDelete, beforeUpdate, bindHooks, coefficient, column, creating, decrement, defaultValue, field as define, deleted, deleting, divide, field$1 as field, getPrimaryFields, getPrimaryKeys, hooks, immutable, increment, index, isDevelopment, isPseudo, mergeHooks, model, multiply, now, primary, prop, pseudo, setDevelopment, sort, model as submodel, toBool, toNot, toPrimaries, toPrimary, uncreatable, undeleted, updating, uuid, values, where, withDeleted };
+export { Build, CheckViolationError, Connection, ConnectionError, Create, Destroy, ForeignKeyViolationError, InvalidInputSyntaxError, Model, NotNullViolationError, OperatorMismatchError, PseudoDestroy, Query, Save, Scene, Submodel, UniqueViolationError, Where, afterCreate, afterCreateMany, afterDelete, afterUpdate, beforeCreate, beforeCreateMany, beforeDelete, beforeUpdate, bindHooks, coefficient, column, creating, decrement, defaultValue, field as define, deleted, deleting, divide, field$1 as field, getPrimaryFields, getPrimaryKeys, hooks, immutable, increment, index, isDevelopment, isPseudo, mergeHooks, model, multiply, now, primary, prop, pseudo, setDevelopment, sort, model as submodel, toBool, toNot, toPrimaries, toPrimary, uncreatable, undeleted, updating, uuid, values, where, withDeleted };

package/migrate.d.mts

@@ -1,5 +1,5 @@
 /*!
- * imodel v0.19.1
+ * imodel v0.19.3
  * (c) 2019-2026 undefined
  * @license undefined
  */

package/migrate.mjs

@@ -1,5 +1,5 @@
 /*!
- * imodel v0.19.1
+ * imodel v0.19.3
  * (c) 2019-2026 undefined
  * @license undefined
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imodel",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "main": "index.mjs",
   "type": "module",
   "repository": {