@maiyunnet/kebab 9.19.1 → 9.20.0

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.19.1";
+export declare const VER = "9.20.0";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.19.1';
+export const VER = '9.20.0';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/sql.d.ts

@@ -10,6 +10,8 @@ export declare enum ESERVICE {
     'MYSQL' = 0,
     'PGSQL' = 1
 }
+/** --- 非空游标值；大整数和日期请使用数据库可比较的字符串 --- */
+export type TCursorValue = string | number;
 /** --- JSON 查询操作符 --- */
 export declare enum EJSON {
     /** --- 包含值 (MySQL: JSON_CONTAINS, PG: @>) --- */
@@ -209,6 +211,15 @@ export declare class Sql {
      * @param d 排序规则
      */
     by(c: string | Array<string | string[]>, d?: 'DESC' | 'ASC'): this;
+    /**
+     * --- 按非空、同向排序字段定位游标并设置排序；字段组合须唯一且有匹配索引 ---
+     * --- 使用行比较，让 PostgreSQL 可以从复合索引边界开始扫描 ---
+     * @param c 排序字段，支持表别名；不支持表达式、GROUP BY 或 UNION
+     * @param values 上一页末行的字段值，省略时读取首批
+     * @param d 扫描方向；读取前一批时反转方向并在取回后反转列表
+     * @returns 当前 SQL 对象
+     */
+    seek(c: string | string[], values?: TCursorValue[], d?: 'DESC' | 'ASC'): this;
     /**
      * --- GROUP BY ---
      * @param c 字段字符串或数组
@@ -230,6 +241,10 @@ export declare class Sql {
      */
     copy(f?: string | string[], opt?: {
         'where'?: string | kebab.Json;
+        /** --- false 时移除本查询的排序，不修改子查询 --- */
+        'order'?: false;
+        /** --- false 时移除本查询的 LIMIT/OFFSET，不修改子查询 --- */
+        'limit'?: false;
     }): Sql;
     /**
      * --- 获取 sql 语句 ---

package/lib/sql.js

@@ -55,6 +55,7 @@ export class Sql {
         this._service = opt.service ?? ESERVICE.MYSQL;
         if (opt.data) {
             this._data = opt.data;
+            this._placeholderCounter = opt.data.length + 1;
         }
         if (opt.sql) {
             this._sql = opt.sql;
@@ -770,6 +771,54 @@ export class Sql {
         this._sql.push(sql);
         return this;
     }
+    /**
+     * --- 按非空、同向排序字段定位游标并设置排序；字段组合须唯一且有匹配索引 ---
+     * --- 使用行比较，让 PostgreSQL 可以从复合索引边界开始扫描 ---
+     * @param c 排序字段，支持表别名；不支持表达式、GROUP BY 或 UNION
+     * @param values 上一页末行的字段值，省略时读取首批
+     * @param d 扫描方向；读取前一批时反转方向并在取回后反转列表
+     * @returns 当前 SQL 对象
+     */
+    seek(c, values, d = 'DESC') {
+        const fields = typeof c === 'string' ? [c] : c;
+        if (!fields.length || new Set(fields).size !== fields.length ||
+            fields.some(field => !/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/.test(field)) ||
+            !['ASC', 'DESC'].includes(d)) {
+            throw new Error('Invalid cursor ordering');
+        }
+        if (this._sql.some(part => /^ (ORDER BY|LIMIT|GROUP BY|HAVING|UNION|FOR UPDATE)\b/i.test(part))) {
+            throw new Error('seek requires an ungrouped query without ordering or pagination');
+        }
+        if (values !== undefined) {
+            if (values.length !== fields.length || values.some(value => (typeof value !== 'string' && typeof value !== 'number') ||
+                (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)))))) {
+                throw new Error('Invalid cursor values; use strings for large integers');
+            }
+            const columns = fields.map(field => this.field(field));
+            const placeholders = values.map(() => this._placeholder());
+            const left = columns.length === 1 ? columns[0] : `(${columns.join(', ')})`;
+            const right = placeholders.length === 1 ? placeholders[0] : `(${placeholders.join(', ')})`;
+            let condition = `${left} ${d === 'DESC' ? '<' : '>'} ${right}`;
+            if (columns.length > 1) {
+                // --- 显式收紧首列边界，避免已有较宽范围条件让 PG 在索引内遍历到行比较边界 ---
+                condition += ` AND ${columns[0]} ${d === 'DESC' ? '<=' : '>='} ${this._placeholder()}`;
+            }
+            const index = this._sql.findIndex(part => part.startsWith(' WHERE '));
+            if (index === -1) {
+                this._whereDataPosition[0] = this._data.length;
+                this._sql.push(' WHERE ' + condition);
+            }
+            else {
+                this._sql[index] = ` WHERE (${this._sql[index].slice(7)}) AND ${condition}`;
+            }
+            this._data.push(...values);
+            if (columns.length > 1) {
+                this._data.push(values[0]);
+            }
+            this._whereDataPosition[1] = this._data.length;
+        }
+        return this.by(fields, d);
+    }
     /**
      * --- GROUP BY ---
      * @param c 字段字符串或数组
@@ -918,7 +967,13 @@ export class Sql {
                 sql[i] = sql[i].replace(/\$\d+/g, () => `$${counter++}`);
             }
         }
-        return get({
+        for (let i = sql.length - 1; i >= 0; --i) {
+            if ((opt.order === false && sql[i].startsWith(' ORDER BY ')) ||
+                (opt.limit === false && sql[i].startsWith(' LIMIT '))) {
+                sql.splice(i, 1);
+            }
+        }
+        const result = get({
             'service': this._service,
             'ctr': this._ctr,
             'pre': this._pre,
@@ -926,6 +981,10 @@ export class Sql {
             'sql': sql,
             'alias': lCore.clone(this._alias),
         }).hint(this._hint);
+        if (opt.where === undefined) {
+            result._whereDataPosition = [...this._whereDataPosition];
+        }
+        return result;
     }
     // --- 操作 ---
     /**

package/lib/text.d.ts

@@ -1,4 +1,17 @@
 import * as kebab from '#kebab/index.js';
+/**
+ * --- 解析三段正式发行版本 X.Y.Z，不接受前导零、预发行和构建后缀 ---
+ * @param value 待解析的版本
+ * @returns 三段安全整数，无效时返回 null
+ */
+export declare function parseVersion(value: unknown): [number, number, number] | null;
+/**
+ * --- 逐段比较三段正式发行版本 X.Y.Z，不按字符串或浮点数比较 ---
+ * @param version 待比较的版本
+ * @param target 目标版本
+ * @returns 小于返回 -1，等于返回 0，大于返回 1；任一版本无效时返回 null
+ */
+export declare function compareVersion(version: unknown, target: unknown): -1 | 0 | 1 | null;
 /**
  * --- 将文件大小格式化为带单位的字符串 ---
  * @param size 文件大小

package/lib/text.js

@@ -7,6 +7,42 @@ import * as net from 'net';
 import * as kebab from '#kebab/index.js';
 import * as lFs from './fs.js';
 import * as lCore from './core.js';
+/**
+ * --- 解析三段正式发行版本 X.Y.Z，不接受前导零、预发行和构建后缀 ---
+ * @param value 待解析的版本
+ * @returns 三段安全整数，无效时返回 null
+ */
+export function parseVersion(value) {
+    if ((typeof value !== 'string') || (value.length > 64)) {
+        return null;
+    }
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value);
+    // --- $ 可匹配末尾换行前的位置，必须额外确认匹配完整输入 ---
+    if (match?.[0] !== value) {
+        return null;
+    }
+    const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+    return parts.every(Number.isSafeInteger) ? parts : null;
+}
+/**
+ * --- 逐段比较三段正式发行版本 X.Y.Z，不按字符串或浮点数比较 ---
+ * @param version 待比较的版本
+ * @param target 目标版本
+ * @returns 小于返回 -1，等于返回 0，大于返回 1；任一版本无效时返回 null
+ */
+export function compareVersion(version, target) {
+    const current = parseVersion(version);
+    const other = parseVersion(target);
+    if (!current || !other) {
+        return null;
+    }
+    for (let index = 0; index < current.length; index++) {
+        if (current[index] !== other[index]) {
+            return current[index] < other[index] ? -1 : 1;
+        }
+    }
+    return 0;
+}
 /**
  * --- 将文件大小格式化为带单位的字符串 ---
  * @param size 文件大小

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.19.1",
+  "version": "9.20.0",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/mod.d.ts

@@ -11,6 +11,13 @@ import * as kebab from '#kebab/index.js';
 export type TOnlyProperties<T> = {
     [K in keyof T as T[K] extends (...args: any[]) => any ? never : K]: T[K];
 };
+/** --- 一批游标查询结果，hasMore 表示扫描方向上还有记录 --- */
+export interface ICursorPage<T extends Record<string, unknown> = Record<string, unknown>> {
+    'list': T[];
+    'hasMore': boolean;
+    'next': lSql.TCursorValue[] | null;
+    'previous': lSql.TCursorValue[] | null;
+}
 /** --- 条数列表 --- */
 export declare class Rows<T extends Mod> implements IRows<T> {
     private readonly _items;
@@ -375,6 +382,31 @@ export default class Mod {
      * --- 获取总条数，自动抛弃 LIMIT，仅用于获取数据的情况（select） ---
      */
     total(f?: string): Promise<number>;
+    /**
+     * --- 从 PostgreSQL 执行计划估算查询总行数，移除外层排序和分页，不执行数据扫描 ---
+     * --- 请在应用游标条件前调用；非 PostgreSQL、框架分表联查或查询失败返回 false，绝不回退到 COUNT ---
+     * @returns 近似行数或 false；估算可能偏差很大，不能用于判断有无下一批
+     */
+    totalEstimate(): Promise<number | false>;
+    /**
+     * --- 读取一批游标数据，多取一条判断后续记录，不使用 OFFSET，不修改原查询 ---
+     * --- 排序字段必须全部非空、同向，且组合唯一；SELECT 中须包含对应字段（同名或指定 keys） ---
+     * @param count 本批数量
+     * @param opt 排序、边界和方向；before 为 true 时读取前一批并恢复展示顺序
+     * @param opt.by 排序字段，支持表别名
+     * @param opt.keys SELECT 结果中对应的字段名，默认去掉 by 的表别名
+     * @param opt.order 展示顺序，默认 DESC
+     * @param opt.cursor 边界行的字段值，首批省略
+     * @param opt.before 是否读取边界前一批，须提供 cursor
+     * @returns 列表、首末行游标和扫描方向上的 hasMore，数据库错误返回 false
+     */
+    allCursor<T extends Record<string, unknown> = Record<string, unknown>>(count: number, opt: {
+        'by': string | string[];
+        'keys'?: string[];
+        'order'?: 'DESC' | 'ASC';
+        'cursor'?: lSql.TCursorValue[];
+        'before'?: boolean;
+    }): Promise<ICursorPage<T> | false>;
     /**
      * --- 根据当前条件，筛选出当前条目该有的数据条数 ---
      */

package/sys/mod.js

@@ -1262,6 +1262,89 @@ export default class Mod {
         }
         return count;
     }
+    /**
+     * --- 从 PostgreSQL 执行计划估算查询总行数，移除外层排序和分页，不执行数据扫描 ---
+     * --- 请在应用游标条件前调用；非 PostgreSQL、框架分表联查或查询失败返回 false，绝不回退到 COUNT ---
+     * @returns 近似行数或 false；估算可能偏差很大，不能用于判断有无下一批
+     */
+    async totalEstimate() {
+        if (this._db.getService() !== lDb.ESERVICE.PGSQL || this._index !== null || this._contain) {
+            return false;
+        }
+        const sql = this._sql.copy(undefined, { 'order': false, 'limit': false });
+        const result = await this._db.query('EXPLAIN (FORMAT JSON) ' + sql.getSql(), sql.getData());
+        if (result.rows === null) {
+            lCore.log(this._ctr ?? {}, '[MOD][totalEstimate] Query failed', '-error');
+            return false;
+        }
+        const plan = result.rows[0]?.['QUERY PLAN'];
+        const parsed = typeof plan === 'string' ? lText.parseJson(plan) : plan;
+        if (!Array.isArray(parsed)) {
+            return false;
+        }
+        const root = parsed[0];
+        if (!root || typeof root !== 'object') {
+            return false;
+        }
+        const node = root['Plan'];
+        if (!node || typeof node !== 'object') {
+            return false;
+        }
+        const rows = node['Plan Rows'];
+        return typeof rows === 'number' && Number.isFinite(rows) && rows >= 0 ? Math.round(rows) : false;
+    }
+    /**
+     * --- 读取一批游标数据，多取一条判断后续记录，不使用 OFFSET，不修改原查询 ---
+     * --- 排序字段必须全部非空、同向，且组合唯一；SELECT 中须包含对应字段（同名或指定 keys） ---
+     * @param count 本批数量
+     * @param opt 排序、边界和方向；before 为 true 时读取前一批并恢复展示顺序
+     * @param opt.by 排序字段，支持表别名
+     * @param opt.keys SELECT 结果中对应的字段名，默认去掉 by 的表别名
+     * @param opt.order 展示顺序，默认 DESC
+     * @param opt.cursor 边界行的字段值，首批省略
+     * @param opt.before 是否读取边界前一批，须提供 cursor
+     * @returns 列表、首末行游标和扫描方向上的 hasMore，数据库错误返回 false
+     */
+    async allCursor(count, opt) {
+        if (!Number.isSafeInteger(count) || count < 1 || count >= Number.MAX_SAFE_INTEGER ||
+            this._index !== null || this._contain || (opt.before && !opt.cursor) ||
+            (opt.order !== undefined && !['ASC', 'DESC'].includes(opt.order))) {
+            throw new Error('Invalid cursor page options; framework sharding and contain are unsupported');
+        }
+        const fields = typeof opt.by === 'string' ? [opt.by] : opt.by;
+        const keys = opt.keys ?? fields.map(field => field.split('.').pop());
+        if (keys.length !== fields.length || new Set(keys).size !== keys.length) {
+            throw new Error('Cursor result keys must match ordering fields');
+        }
+        const order = opt.order ?? 'DESC';
+        const direction = opt.before ? (order === 'DESC' ? 'ASC' : 'DESC') : order;
+        const sql = this._sql.copy(undefined, { 'order': false, 'limit': false });
+        sql.seek(fields, opt.cursor, direction).limit(count + 1);
+        const result = await this._db.query(sql.getSql(), sql.getData());
+        if (result.rows === null) {
+            lCore.log(this._ctr ?? {}, '[MOD][allCursor] Query failed', '-error');
+            return false;
+        }
+        const hasMore = result.rows.length > count;
+        const list = result.rows.slice(0, count);
+        if (opt.before) {
+            list.reverse();
+        }
+        const boundary = (row) => keys.map(key => {
+            const value = row[key];
+            if ((typeof value !== 'string' && typeof value !== 'number') ||
+                (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))) {
+                throw new Error('Cursor columns must be non-null strings or safe numbers');
+            }
+            return value;
+        });
+        return {
+            'list': list,
+            'hasMore': hasMore,
+            'next': list.length ? boundary(list[list.length - 1]) : null,
+            'previous': list.length ? boundary(list[0]) : null,
+        };
+    }
     /**
      * --- 根据当前条件，筛选出当前条目该有的数据条数 ---
      */

package/www/example/ctr/test.js

@@ -226,6 +226,7 @@ export default class extends sCtr.Ctr {
             `<br><a href="${this._config.const.urlBase}test/sql?type=json">View "test/sql?type=json"</a> <a href="${this._config.const.urlBase}test/sql?type=json&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=having">View "test/sql?type=having"</a> <a href="${this._config.const.urlBase}test/sql?type=having&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=by">View "test/sql?type=by"</a> <a href="${this._config.const.urlBase}test/sql?type=by&s=pgsql">pgsql</a>`,
+            `<br><a href="${this._config.const.urlBase}test/sql?type=seek">View "test/sql?type=seek"</a> <a href="${this._config.const.urlBase}test/sql?type=seek&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=field">View "test/sql?type=field"</a> <a href="${this._config.const.urlBase}test/sql?type=field&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=hint">View "test/sql?type=hint"</a>`,
             '<br><br><b>Consistent:</b>',
@@ -803,6 +804,10 @@ test.set({
 });
 const result = await test.create();
 JSON.stringify(result));</pre>` + JSON.stringify(result));
+            if (result !== true) {
+                echo.push(`<p>The new test row was not inserted. The fixed test names and tokens may already be in use;
+the cursor demo below reads existing test rows.</p>`);
+            }
             echo.push('<pre>JSON.stringify(test.toArray());</pre>' + lText.htmlescape(JSON.stringify(test.toArray())));
             echo.push('<br><br>Test table:');
             stmt = await db.query(this._get['s'] === 'pgsql' ?
@@ -836,6 +841,90 @@ const r = await ls.explain();</pre>` + lText.htmlescape(JSON.stringify(r)));
             else {
                 echo.push('<div>false</div>');
             }
+            // --- 近似总数与游标分页，复用原始筛选，翻页不重复估算 ---
+            // --- 固定名称和 token 的测试数据可能已占满，不能依赖本次新增成功或只取最近五分钟 ---
+            const isPgsql = db.getService() === lDb.ESERVICE.PGSQL;
+            const query = mTest.select(db, [
+                // --- PG int8 可能超出 Number 精度，投影成文本，排序仍使用原表字段 ---
+                isPgsql ? 't.id::text id' : 't.id', 't.name', 't.time_add',
+            ], {
+                'ctr': this,
+                'pre': isPgsql ? 'm' : undefined,
+                'alias': 't',
+            }).filter([
+                ['t.token', 'LIKE', 'test_%'],
+                ['t.time_add', '<=', time],
+            ]);
+            const estimated = await query.totalEstimate();
+            echo.push(`<br><b>Approximate total / cursor pagination:</b>
+<p>totalEstimate() is PostgreSQL only; false means unavailable, not zero.
+The estimate can be inaccurate; use hasMore to decide whether to fetch the next batch.
+Keep filters and the ending time fixed while paging. Cursor fields must be non-null and jointly unique;
+use a (time_add, id) index for large tables.
+This demo includes existing test rows up to the fixed ending time, without a five-minute restriction.</p>
+<pre>const isPgsql = db.getService() === lDb.ESERVICE.PGSQL;
+const query = mTest.select&lt;mTest&gt;(db, [
+    isPgsql ? 't.id::text id' : 't.id', 't.name', 't.time_add',
+], {
+    'ctr': this,
+    'pre': isPgsql ? 'm' : undefined,
+    'alias': 't',
+}).filter([
+    ['t.token', 'LIKE', 'test_%'],
+    ['t.time_add', '&lt;=', time],
+]);
+const estimated = await query.totalEstimate();</pre>
+<b>estimated:</b> ${lText.htmlescape(lText.stringifyJson(estimated))}`);
+            const first = await query.allCursor(2, {
+                'by': ['t.time_add', 't.id'],
+                'order': 'DESC',
+            });
+            echo.push(`<pre>const first = await query.allCursor(2, {
+    'by': ['t.time_add', 't.id'],
+    'order': 'DESC',
+});</pre><b>first:</b><pre>${lText.htmlescape(lText.stringifyJson(first, 4))}</pre>`);
+            if (first === false) {
+                echo.push('<p>First batch query failed.</p>');
+            }
+            else if (first.hasMore && first.next) {
+                const second = await query.allCursor(2, {
+                    'by': ['t.time_add', 't.id'],
+                    'order': 'DESC',
+                    'cursor': first.next,
+                });
+                echo.push(`<pre>if (first !== false &amp;&amp; first.hasMore &amp;&amp; first.next) {
+    const second = await query.allCursor(2, {
+        'by': ['t.time_add', 't.id'],
+        'order': 'DESC',
+        'cursor': first.next,
+    });
+}</pre><b>second:</b><pre>${lText.htmlescape(lText.stringifyJson(second, 4))}</pre>`);
+                if (second === false) {
+                    echo.push('<p>Next batch query failed.</p>');
+                }
+                else if (second.previous) {
+                    const previous = await query.allCursor(2, {
+                        'by': ['t.time_add', 't.id'],
+                        'order': 'DESC',
+                        'cursor': second.previous,
+                        'before': true,
+                    });
+                    echo.push(`<pre>if (second !== false &amp;&amp; second.previous) {
+    const previous = await query.allCursor(2, {
+        'by': ['t.time_add', 't.id'],
+        'order': 'DESC',
+        'cursor': second.previous,
+        'before': true,
+    });
+}</pre><b>previous:</b><pre>${lText.htmlescape(lText.stringifyJson(previous, 4))}</pre>
+<p>With before: true, rows stay in DESC display order;
+hasMore now indicates whether there are more rows before this batch.</p>`);
+                }
+            }
+            else {
+                echo.push(`<p>No next batch. The first list already contains the complete result;
+its length is the exact total for this query.</p>`);
+            }
             let ft = await mTest.one(db, [
                 ['time_add', '>', '0']
             ], {
@@ -3233,6 +3322,69 @@ Result:<pre id="result">Nothing.</pre>`);
 <b>format() :</b> ${sql.format(s, sd)}`);
                 break;
             }
+            case 'seek': {
+                echo.push(`<p><b>Without cursor values, seek() and by() generate the same first-batch SQL.</b>
+With cursor values, seek() adds a WHERE boundary and sets ORDER BY. Compare the two next-batch examples below:
+by() + OFFSET skips rows by position, while seek() continues after the preceding batch's last row.</p>
+<p>by() only sets ORDER BY;
+do not call by() again after seek(). Call seek() before limit().
+Cursor fields must be non-null and jointly unique. Pass large integer IDs as strings.</p>`);
+                sql.select(['t.id', 't.time_add'], 'test t').where([
+                    ['t.time_add', '>=', 1700000000],
+                    ['t.time_add', '<=', 1700600000],
+                ]);
+                echo.push(`<pre>sql.select(['t.id', 't.time_add'], 'test t').where([
+    ['t.time_add', '&gt;=', 1700000000],
+    ['t.time_add', '&lt;=', 1700600000],
+]);</pre>`);
+                // --- 同一筛选条件，对比普通排序与游标定位 ---
+                const sorted = sql.copy().by(['t.time_add', 't.id'], 'DESC').limit(2);
+                echo.push(`<b>by(): sort only</b>
+<pre>const sorted = sql.copy().by(['t.time_add', 't.id'], 'DESC').limit(2);</pre>
+<b>getSql():</b> ${lText.htmlescape(sorted.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(sorted.getData(), 4))}</pre>
+<p>This always reads the first two rows of the current matching result.</p><hr>`);
+                const offsetNext = sql.copy().by(['t.time_add', 't.id'], 'DESC').limit(2, 2);
+                echo.push(`<b>by() + OFFSET: next batch by position</b>
+<pre>const offsetNext = sql.copy().by(['t.time_add', 't.id'], 'DESC').limit(2, 2);</pre>
+<b>getSql():</b> ${lText.htmlescape(offsetNext.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(offsetNext.getData(), 4))}</pre>
+<p>limit(offset, count) skips the first two matching rows. Larger offsets require skipping more rows;
+new rows inserted before that position can shift subsequent pages.</p><hr>`);
+                const next = sql.copy().seek(['t.time_add', 't.id'], [1700500000, '9007199254740993']).limit(2);
+                echo.push(`<b>seek() with a cursor: next batch after a row</b>
+<pre>const next = sql.copy().seek(
+    ['t.time_add', 't.id'], [1700500000, '9007199254740993']
+).limit(2);</pre>
+<b>getSql():</b> ${lText.htmlescape(next.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(next.getData(), 4))}</pre>
+<p>This adds a WHERE boundary based on the last row's time_add and id, with no OFFSET.
+Use the actual last row from the preceding batch as the cursor; the values here are illustrative.
+A matching composite index lets the database locate that boundary.</p><hr>`);
+                const first = sql.copy().seek(['t.time_add', 't.id']).limit(2);
+                echo.push(`<b>seek() without a cursor: same SQL as by() for the first batch</b>
+<pre>const first = sql.copy().seek(['t.time_add', 't.id']).limit(2);</pre>
+<b>getSql():</b> ${lText.htmlescape(first.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(first.getData(), 4))}</pre>
+<p>Without a cursor, seek() generates the same SQL as the by() first-batch example above.
+It is the cursor values in the preceding seek() example that add the WHERE boundary.</p><hr>`);
+                const previous = sql.copy().seek(['t.time_add', 't.id'], [1700500000, '9007199254740993'], 'ASC').limit(2);
+                echo.push(`<pre>const previous = sql.copy().seek(
+    ['t.time_add', 't.id'], [1700500000, '9007199254740993'], 'ASC'
+).limit(2);</pre>
+<b>getSql():</b> ${lText.htmlescape(previous.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(previous.getData(), 4))}</pre>
+<p>SQL seek() scans the previous batch in ASC order; reverse the rows for DESC display.
+Model allCursor(..., { before: true }) handles that reversal automatically.</p><hr>`);
+                const unpaged = first.copy(undefined, { 'order': false, 'limit': false });
+                echo.push(`<pre>const unpaged = first.copy(undefined, { 'order': false, 'limit': false });</pre>
+<b>getSql():</b> ${lText.htmlescape(unpaged.getSql())}<br>
+<b>getData():</b><pre>${lText.htmlescape(lText.stringifyJson(unpaged.getData(), 4))}</pre>
+<b>first remains:</b> ${lText.htmlescape(first.getSql())}<br><br>
+copy() removes the outer ordering and pagination without changing the original.<br>
+It keeps WHERE conditions, including any cursor boundary; estimate the base filter before adding a cursor.`);
+                break;
+            }
             case 'field': {
                 echo.push(`<pre>sql.field('abc');</pre>` + sql.field('abc'));
                 echo.push(`<pre>sql.field('abc', 'a_');</pre>` + sql.field('abc', 'a_'));
@@ -4512,7 +4664,17 @@ function doUpload() {
      */
     _getEnd() {
         const rt = this._getRunTime();
-        return 'Processed in ' + rt.toString() + ' second(s), ' + (Math.round(rt * 10000000) / 10000).toString() + 'ms, ' + (Math.round(this._getMemoryUsage() / 1024 * 100) / 100).toString() + ' K.<style>*{font-family:Consolas,"Courier New",Courier,FreeMono,monospace;line-height: 1.5;font-size:12px;}pre{padding:10px;background-color:rgba(0,0,0,.07);white-space:pre-wrap;word-break:break-all;}hr{margin:20px 0;border-color:#000;border-style:dashed;border-width:1px 0 0 0;}td,th{padding:5px;border:solid 1px #000;}</style><meta name="viewport" content="width=device-width,initial-scale=1,minimum-scale=1,maximum-scale=1,user-scalable=no">';
+        return 'Processed in ' + rt.toString() + ' second(s), ' + (Math.round(rt * 10000000) / 10000).toString() + 'ms, ' + (Math.round(this._getMemoryUsage() / 1024 * 100) / 100).toString() + ` K.
+<style>
+body{margin:20px;font-family:system-ui,-apple-system,"Segoe UI","Noto Sans",sans-serif;font-size:16px;line-height:1.65;color:#1f2937;background:#fff;overflow-wrap:anywhere;}
+pre,code,kbd,samp{font-family:ui-monospace,"Cascadia Code","SFMono-Regular",Consolas,"Liberation Mono",monospace;font-size:15px;line-height:1.6;}
+pre{margin:16px 0;padding:14px 16px;border:1px solid #e5e7eb;border-radius:6px;background:#f3f4f6;white-space:pre-wrap;word-break:normal;}
+b,strong,th{font-weight:600;}
+input,button,select,textarea{font:inherit;}
+hr{margin:24px 0;border:0;border-top:1px solid #d1d5db;}
+td,th{padding:8px 10px;border:1px solid #d1d5db;}
+@media(max-width:600px){body{margin:12px;}pre{padding:12px;}}
+</style><meta name="viewport" content="width=device-width,initial-scale=1">`;
     }
 }
 // --- 下面是测试代码 ---