imodel 0.19.0 → 0.19.2

package/index.d.mts

@@ -1,5 +1,5 @@
 /*!
- * imodel v0.19.0
+ * imodel v0.19.2
  * (c) 2019-2026 undefined
  * @license undefined
  */
@@ -620,6 +620,7 @@ interface Hook<T extends Hooks[keyof Hooks]> {
  */
 declare function toNot(items?: WhereValue[] | null): WhereValue[] | null;
 type WhereItem = {
+    exists?: false | null | undefined;
     where?: null | undefined;
     or?: null | undefined;
     field: string | {
@@ -634,7 +635,16 @@ type WhereItem = {
     not?: boolean | undefined;
     operator?: string | null | undefined;
 };
+type WhereExists = {
+    where?: null | undefined;
+    or?: null | undefined;
+    field?: null | undefined;
+    exists: true;
+    subquery: SelectItem[];
+    not?: boolean | undefined;
+};
 type WhereRaw = {
+    exists?: false | null | undefined;
     field?: null | undefined;
     or?: null | undefined;
     where: readonly string[];
@@ -642,12 +652,13 @@ type WhereRaw = {
     not?: boolean | undefined;
 };
 type WhereOr = {
+    exists?: false | null | undefined;
     where?: null | undefined;
     field?: null | undefined;
     or: WhereValue[][];
     not?: boolean | undefined;
 };
-type WhereValue = WhereItem | WhereRaw | WhereOr;
+type WhereValue = WhereItem | WhereExists | WhereRaw | WhereOr;
 type WhereLike = {
     toWhereValue(): WhereValue[][];
 };
@@ -738,6 +749,58 @@ declare class Where {
      * @returns {Where}
      */
     static and(items: [Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]): Where;
+    /**
+     * @overload
+     * @param {Wheres} matches
+     * @returns {Where}
+     */
+    static where(matches: Wheres): Where;
+    /**
+     *
+     * @overload
+     * @param {TemplateStringsArray} where
+     * @param  {...any} values
+     * @returns {Where}
+     */
+    static where(where: TemplateStringsArray, ...values: any[]): Where;
+    /**
+     * @overload
+     * @param {string} field
+     * @param {any} value
+     * @returns {Where}
+     */
+    static where(field: string, value: any): Where;
+    /**
+     * @overload
+     * @param {string[]} field
+     * @param {any[]} value
+     * @returns {Where}
+     */
+    static where(field: string[], value: any[]): Where;
+    /**
+     * @overload
+     * @param {string} field
+     * @param {string} operator
+     * @param {any} value
+     * @param {boolean} [not]
+     * @returns {Where}
+     */
+    static where(field: string, operator: string, value: any, not?: boolean | undefined): Where;
+    /**
+     * @overload
+     * @param {string[]} field
+     * @param {string} operator
+     * @param {any[]} value
+     * @param {boolean} [not]
+     * @returns {Where}
+     */
+    static where(field: string[], operator: string, value: any[], not?: boolean | undefined): Where;
+    /**
+     * @overload
+     * @param {[Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]} items
+     * @returns {Where}
+     */
+    static where(items: [Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]): Where;
     /**
      * @overload
      * @param {Wheres} matches
@@ -894,6 +957,18 @@ declare class Where {
      * @returns {Where}
      */
     static orNot(items: [Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]): Where;
+    /**
+     *
+     * @param  {...SelectItem} subquery
+     * @returns {Where}
+     */
+    static exists(...subquery: SelectItem[]): Where;
+    /**
+     *
+     * @param  {...SelectItem} subquery
+     * @returns {Where}
+     */
+    static notExists(...subquery: SelectItem[]): Where;
     toWhereValue(): WhereValue[][];
     /**
      * @overload
@@ -1103,6 +1178,18 @@ declare class Where {
      * @returns {this}
      */
     orNot(items: [Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]): this;
+    /**
+     *
+     * @param  {...SelectItem} subquery
+     * @returns {this}
+     */
+    exists(...subquery: SelectItem[]): this;
+    /**
+     *
+     * @param  {...SelectItem} subquery
+     * @returns {this}
+     */
+    notExists(...subquery: SelectItem[]): this;
     #private;
 }
 
@@ -1286,6 +1373,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;
@@ -1310,6 +1398,7 @@ interface JOIN {
     alias?: string;
     condition?: WhereValue[];
 }
+type LockType = 'S' | 'X';
 interface SelectItem {
     distinct?: boolean;
     select: [string, Select][];
@@ -1326,6 +1415,7 @@ interface SelectItem {
     offset?: number;
     /** 最大返回数 */
     limit?: number;
+    lock?: LockType | null;
 }
 type GetName = (table?: string) => string;
 interface DBColumn {
@@ -1399,6 +1489,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 {
@@ -1904,9 +2005,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;
 }
 
@@ -1927,8 +2029,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> = {
@@ -1995,10 +2101,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]
@@ -2132,6 +2238,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
@@ -2587,4 +2698,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 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, 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 LockType, 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 TransactionHandler, type TransactionHandlerArray, 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.0
+ * imodel v0.19.2
  * (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 方法未在子类中实现');
   }
 }
@@ -26,6 +30,7 @@ class Subquery {
 /** @typedef {WhereLike | Record<string, any> | (WhereLike | Record<string, any>)[]} Wheres */
 /**
  * @typedef {object} WhereItem
+ * @prop {false?} [exists]
  * @prop {null} [where]
  * @prop {null} [or]
  * @prop {string | {table?: string; field: string} | (string | {table?: string; field: string})[]} field
@@ -34,8 +39,18 @@ class Subquery {
  * @prop {boolean} [not]
  * @prop {string?} [operator]
  */
+/**
+ * @typedef {object} WhereExists
+ * @prop {null} [where]
+ * @prop {null} [or]
+ * @prop {null} [field]
+ * @prop {true} exists
+ * @prop {SelectItem[]} subquery
+ * @prop {boolean} [not]
+ */
 /**
  * @typedef {object} WhereRaw
+ * @prop {false?} [exists]
  * @prop {null} [field]
  * @prop {null} [or]
  * @prop {readonly string[]} where
@@ -44,12 +59,13 @@ class Subquery {
  */
 /**
  * @typedef {object} WhereOr
+ * @prop {false?} [exists]
  * @prop {null} [where]
  * @prop {null} [field]
  * @prop {WhereValue[][]} or
  * @prop {boolean} [not]
  */
-/** @typedef {WhereItem | WhereRaw | WhereOr} WhereValue */
+/** @typedef {WhereItem | WhereExists | WhereRaw | WhereOr} WhereValue */
 /**
  *
  * @param {*} v
@@ -317,6 +333,58 @@ class Where {
   static and(...items) {
     return new Where().#and(parse(items));
   }
+  /**
+   * @overload
+   * @param {Wheres} matches
+   * @returns {Where}
+   */
+  /**
+   *
+   * @overload
+   * @param {TemplateStringsArray} where
+   * @param  {...any} values
+   * @returns {Where}
+   */
+  /**
+   * @overload
+   * @param {string} field
+   * @param {any} value
+   * @returns {Where}
+   */
+  /**
+   * @overload
+   * @param {string[]} field
+   * @param {any[]} value
+   * @returns {Where}
+   */
+  /**
+   * @overload
+   * @param {string} field
+   * @param {string} operator
+   * @param {any} value
+   * @param {boolean} [not]
+   * @returns {Where}
+   */
+  /**
+   * @overload
+   * @param {string[]} field
+   * @param {string} operator
+   * @param {any[]} value
+   * @param {boolean} [not]
+   * @returns {Where}
+   */
+  /**
+   * @overload
+   * @param {[Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]} items
+   * @returns {Where}
+   */
+  /**
+   * @param {[Wheres] | [TemplateStringsArray, ...any] | [string | string[], any] | [string | string[], string, any, boolean?]} items
+   * @returns {Where}
+   */
+  static where(...items) {
+    return new Where().#and(parse(items));
+  }
   /**
    * @overload
    * @param {Wheres} matches
@@ -629,6 +697,52 @@ class Where {
   static orNot(...items) {
     return new Where().#or(toNot(parse(items)));
   }
+  /**
+   *
+   * @param  {...SelectItem} subquery
+   * @returns {this}
+   */
+  exists(...subquery) {
+    return this.#and([{
+      exists: true,
+      subquery
+    }]);
+  }
+  /**
+   *
+   * @param  {...SelectItem} subquery
+   * @returns {Where}
+   */
+  static exists(...subquery) {
+    return new Where().#and([{
+      exists: true,
+      subquery
+    }]);
+  }
+  /**
+   *
+   * @param  {...SelectItem} subquery
+   * @returns {this}
+   */
+  notExists(...subquery) {
+    return this.#and([{
+      exists: true,
+      subquery,
+      not: true
+    }]);
+  }
+  /**
+   *
+   * @param  {...SelectItem} subquery
+   * @returns {Where}
+   */
+  static notExists(...subquery) {
+    return new Where().#and([{
+      exists: true,
+      subquery,
+      not: true
+    }]);
+  }
 }
 
 const deleted = Symbol();
@@ -693,28 +807,33 @@ var values = /*#__PURE__*/Object.freeze({
 /** @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
     }];
@@ -2026,6 +2145,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) : [];
@@ -2068,11 +2188,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;
   }
@@ -2080,7 +2203,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]
  */
@@ -2138,10 +2261,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;
   }
@@ -2181,13 +2305,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));
@@ -2222,7 +2347,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);
@@ -2234,7 +2360,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 : '',
@@ -2243,16 +2369,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;
 }
@@ -2274,10 +2401,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);
@@ -2292,14 +2419,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;
   }
@@ -2471,9 +2599,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
@@ -2481,7 +2610,8 @@ function toSelect(queryable) {
   const options = getOptions(queryable);
   const {
     offset,
-    limit
+    limit,
+    lock
   } = options;
   const where = where2column(options.where, fieldColumns);
   where.push(...getFixedValueWhere(columns));
@@ -2497,10 +2627,11 @@ 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;
 }
@@ -3357,7 +3488,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;
   }
@@ -3526,6 +3657,9 @@ class Connection {
     }
     return false;
   }
+  [Symbol.dispose]() {
+    this.abort();
+  }
   /**
    * @param {string} table
    * @returns {Promise<DBTable?>}
@@ -3566,12 +3700,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') {
@@ -3601,13 +3742,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;
   }
 }
 
@@ -4868,7 +5020,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' */
 /**
  *
@@ -4971,8 +5123,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
@@ -5048,7 +5201,7 @@ class Query extends Subquery {
   }
   /**
    * 增加排序项
-   * @param {...string | boolean | [string, boolean?]} sort
+   * @param {...string | null | boolean | [string, boolean?]} sort
    * @returns {this}
    */
   sort(...sort) {
@@ -5065,10 +5218,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];
@@ -5389,6 +5551,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' */

package/migrate.d.mts

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

package/migrate.mjs

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

package/package.json

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