jsql-neo 6.0.2 → 6.0.5

package/README.md

@@ -835,7 +835,7 @@ CREATE TABLE IF NOT EXISTS orders (
 
 **SELECT grammar**
 
-```sql
+```text
 WITH [RECURSIVE] cte_name [(col, ...)] AS (SELECT ...)[, ...]   -- CTE，见下节
 SELECT [DISTINCT] select_list
 FROM table_reference
@@ -1102,24 +1102,24 @@ ORDER BY avg_sal DESC;
 
 **Bitwise** — `& | ^ ~ << >>`（`^` 是按位异或，`~` 是按位取反）。
 
-> **运算符方言说明。** `^` 与 `~` 在 MySQL（位运算）和 PostgreSQL（`^` 为幂、
-> `~` 为正则匹配）中含义冲突，本实现统一采用 **MySQL 语义**：`^` = 按位异或、
-> `~` = 按位取反。需要幂运算请用 `POWER(x, n)`，需要正则请用 `REGEXP` / `~*`。
-> 因此 PG 风格的 `^`（幂）、`~ ~* !~ !~*`（正则）与 JSON 操作符
-> （`-> ->> #> #>> @> <@`）**暂不支持**。
+> **运算符方言说明。** `^` 与 `~` 在 MySQL 与 PostgreSQL 中含义冲突，本实现按上下文区分：
+> - `^` 统一为**按位异或**（MySQL 语义）；幂运算请用 `POWER(x, n)`。
+> - `~` 在**单目**位置是按位取反（MySQL），在**双目**位置是正则匹配（PG），
+>   另有 `~*`（不敏感）、`!~`、`!~*`。
+> - 需要正则时也可用 `REGEXP` / `RLIKE`；PG 的 `^`（幂）**暂不支持**。
 
-**JSON (PG style)** — `->` (JSON result), `->>` (text), `#>`, `#>>` (paths), `@>` `<@`
-(containment), `?` `?|` `?&` (key existence).
+**JSON (PG style)** — `->` / `->>`（取字段）、`#>` / `#>>`（路径取值）、`@>` / `<@`（包含）、
+`?` / `?|` / `?&`（键存在），可链式（`meta->'addr'->>'city'`）。
 
 ### LIKE / ILIKE / regex
 
-- `%` any length, `_` one char, `\` escape (`ESCAPE` clause)
-- `ILIKE` = LIKE, case-insensitive
-- `REGEXP`/`RLIKE`/`~` use the JS RegExp engine; flags `i/m/s`
+- `%` any length, `_` one char；`ESCAPE '!'` 可自定义转义符（默认 `\`）
+- `ILIKE` = LIKE，大小写不敏感
+- `REGEXP` / `RLIKE` 使用 JS RegExp 引擎；flags `i/m/s`
 
 ```sql
 SELECT * FROM users
-WHERE email ~* '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
+WHERE email REGEXP '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
 ```
 
 ### Indexes & constraints
@@ -1270,16 +1270,17 @@ const result = await executeSQL(db, sql, params);
 ```js
 {
   columns: ['id', 'name', 'age'],
-  columnTypes: ['INTEGER', 'VARCHAR', 'INTEGER'],
+  columnTypes: ['INT', 'VARCHAR(255)', 'INT'],
   rows: [[1, 'Alice', 30]],
-  rowCount: 2, affectedRows: 0, insertId: 1,
-  message: '2 rows selected', command: 'SELECT',
+  rowCount: 1, affectedRows: 0,
+  message: '1 row selected', command: 'SELECT',
   durationMs: 0.42, warnings: [],
 }
 ```
 
-Result matrix: SELECT → `rows`; INSERT → `affectedRows` + `insertId`; UPDATE/DELETE →
-`affectedRows`; DDL/txn → `message`. Params: positional `?`, named `:name`, or object maps.
+Result matrix: SELECT → `rows`（另有 `columnTypes`、`rowCount`、`command`、`message`、
+`durationMs`、`warnings`）；INSERT → `affectedRows` + `insertId`（另有 `ids`）；
+UPDATE/DELETE → `affectedRows`；DDL/txn → `message`。 Params: positional `?`, named `:name`, or object maps.
 Multi-statement supported; `SQLExecutor` class runs batched SQL from a string/stream.
 
 #### 参数绑定：两种方式
@@ -3137,7 +3138,7 @@ DELETE FROM orders WHERE status = 'cancelled' LIMIT 100;
 
 #### 查询语法 SELECT
 
-```sql
+```text
 SELECT [DISTINCT] select_list
 FROM table_reference
 [JOIN table_reference ON condition]
@@ -3403,7 +3404,6 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 | `+` `-` `*` `/` | 四则 | `(a + b) * 2` |
 | `%` / `MOD` | 取模 | `a % 3` |
 | `DIV` | 整数除法（MySQL） | `7 DIV 2` → 3 |
-| `^` | 幂（PG） | `2 ^ 10` → 1024 |
 
 #### 比较运算符
 
@@ -3445,10 +3445,15 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 |---|---|---|
 | `->` | 取 JSON 字段（返回 JSON） | `meta->'name'` |
 | `->>` | 取 JSON 字段（返回文本） | `meta->>'name'` |
-| `#>`, `#>>` | 路径访问 | `meta#>>'{a,b}'` |
+| `#>` | 路径取值（返回 JSON） | `meta#>'{addr,city}'` |
+| `#>>` | 路径取值（返回文本） | `meta#>>'{addr,city}'` |
 | `@>` | 包含 | `meta @> '{"plan":"pro"}'` |
-| `<@` | 被包含 | `'{"a":1}'::jsonb <@ meta` |
-| `?` / `?|` / `?&` | 键存在 | `meta ? 'plan'` |
+| `<@` | 被包含 | `'{"a":1}' <@ meta` |
+| `?` | 含指定键 | `meta ? 'plan'` |
+| `?\|` | 含任一键 | `meta ?\| '{a,b}'` |
+| `?&` | 含全部键 | `meta ?& '{a,b}'` |
+
+可链式取值：`meta->'addr'->>'city'`。
 
 ### LIKE / ILIKE / 正则
 
@@ -3466,14 +3471,12 @@ INTERVAL 单位：`DAY` `HOUR` `MINUTE` `SECOND` `WEEK` `MONTH` `YEAR` 及其组
 
 - 基于 JS RegExp 引擎
 - 支持 flags：`i`（忽略大小写）、`m`（多行）、`s`（点匹配换行）
-- PG 风格的 `~` / `~*` / `!~` / `!~*` 运算符也支持：
-  - `name ~ '^A'`（大小写敏感匹配）
-  - `name ~* '^a'`（不敏感）
-  - `name !~ '^X'`（不匹配）
+- PG 风格的 `~`（大小写敏感）/ `~*`（不敏感）/ `!~` / `!~*` 双目运算符也支持；
+  单目位置的 `~` 仍是按位取反。
 
 ```sql
 SELECT * FROM users
-WHERE email ~* '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
+WHERE email REGEXP '^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$';
 ```
 
 ### 事务 Transactions
@@ -5800,7 +5803,8 @@ expr := literal
       | expr [NOT] LIKE pattern [ESCAPE char]
       | expr [NOT] ILIKE pattern
       | expr [NOT] RLIKE pattern | expr [NOT] REGEXP pattern
-      | expr [NOT] ~ pattern | expr [NOT] ~* pattern | expr !~ pattern
+      | expr ~ pattern | expr ~* pattern | expr !~ pattern | expr !~* pattern
+      | expr ? key | expr ?| keys | expr ?& keys
       | expr IS [NOT] NULL | expr IS [NOT] TRUE | expr IS [NOT] FALSE
       | expr [NOT] IN ( ... )
       | expr [NOT] ANY '(' select_statement ')'
@@ -5846,16 +5850,17 @@ function_call := func_name '(' [DISTINCT] args ')'      -- 普通/聚合
 ### 运算符优先级（从高到低）
 
 ```
-1.  ()  .  []  ->  ->>  #>  #>>
-2.  ::  CAST 一元 + - ~
+1.  ()  .  []  ->  ->>  #>  #>>  ::
+2.  CAST 一元 + - ~
 3.  ^  *  /  %  DIV  MOD
 4.  +  -
 5.  <<  >>  &  |  ^（位）
-6.  =  <>  !=  <  <=  >  >=  <=>  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP  ~  ~*  @>  <@  ?
+6.  =  <>  !=  <  <=  >  >=  <=>  @>  <@  ?  ?|  ?&  BETWEEN  IN  LIKE  ILIKE  RLIKE  REGEXP  ~  ~*  !~  !~*
 7.  NOT
-8.  AND
-9.  OR  XOR
-10. 三元（IF / CASE 解析为函数）
+8.  AND  &&
+9.  XOR
+10. OR  ||
+11. 三元（IF / CASE 解析为函数）
 ```
 
 ### 关键词语法表
@@ -7452,7 +7457,7 @@ jsql import ./data app.sql
 | 字符串字面量 | 单引号 | 单引号 | 单引号（双引号按标识符，PG 语义） |
 | 布尔 | `TRUE/FALSE`（1/0） | `t/f`（三值逻辑） | 兼容两者 |
 | 分页 | `LIMIT off, n` | `LIMIT n OFFSET off` | 两者 |
-| JSON 访问 | `JSON_EXTRACT` | `->` `->>` | 两者 + `#>>` |
+| JSON 访问 | `JSON_EXTRACT` | `->` `->>` `#>>` | 两者 |
 | 类型转换 | `CAST`/`CONVERT` | `::` | 三者 |
 | 条件分支 | `IF()` | `CASE` | `IF` + `CASE` + `IIF` |
 | 空值回退 | `IFNULL()` | `COALESCE` | 两者 |

package/lib/migrate.js

@@ -12,6 +12,15 @@ const path = require('path');
 const { splitStatements, executeSQL } = require('./sql');
 const { parseFieldShorthand } = require('./database');
 
+// 体积护栏（CWE-770）：与 lib/sql.js 的 DEFAULT_MAX_SQL_LENGTH 同风格。
+// 可用 opts.maxInputSize / opts.maxRows 覆盖；传 Infinity 关闭；chunkSize 控制每批 insert 行数。
+const DEFAULT_MAX_CSV_LENGTH = 64 * 1024 * 1024;  // 64 MiB
+const DEFAULT_MAX_JSON_LENGTH = 64 * 1024 * 1024;
+const DEFAULT_MAX_SQL_LENGTH = 64 * 1024 * 1024;  // 与 lib/sql.js 保持一致
+const DEFAULT_MAX_ROWS = 2_000_000;             // 200 万行
+const DEFAULT_MAX_STATEMENTS = 200_000;          // dump 文件最多允许 20 万条语句
+const DEFAULT_CHUNK_SIZE = 1000;
+
 function normalizeSchema(schema) {
   const out = {};
   for (const [name, def] of Object.entries(schema || {})) {
@@ -52,10 +61,31 @@ function parseValue(str, type) {
   return str;
 }
 
-function parseCSV(text) {
+function parseCSV(text, opts = {}) {
+  if (typeof text !== 'string') {
+    throw new Error('parseCSV: csv must be a string');
+  }
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_CSV_LENGTH : opts.maxInputSize;
+  if (typeof maxLen === 'number' && Number.isFinite(maxLen) && text.length > maxLen) {
+    throw new Error(
+      `CSV text too large: ${text.length} chars exceeds limit of ${maxLen} ` +
+      `(raise opts.maxInputSize to allow larger input)`
+    );
+  }
+  const maxRows = opts.maxRows == null ? DEFAULT_MAX_ROWS : opts.maxRows;
+  const isFiniteMaxRows = typeof maxRows === 'number' && Number.isFinite(maxRows);
+
   const rows = [];
+  // 把 `field += c` 改为数组收集中间 join —— 与 splitStatements 同修 O(n²)
+  let fieldBuf = [];
+  const flushField = () => { const s = fieldBuf.join(''); fieldBuf.length = 0; return s; };
   let row = [];
-  let field = '';
+  const flushRow = () => {
+    const r = row;
+    row = [];
+    rows.push(r);
+    return r;
+  };
   let inQuotes = false;
   let i = 0;
   const n = text.length;
@@ -63,32 +93,48 @@ function parseCSV(text) {
     const c = text[i];
     if (inQuotes) {
       if (c === '"') {
-        if (text[i + 1] === '"') { field += '"'; i += 2; continue; }
+        if (text[i + 1] === '"') { fieldBuf.push('"'); i += 2; continue; }
         inQuotes = false;
         i++;
         continue;
       }
-      field += c;
+      fieldBuf.push(c);
       i++;
       continue;
     }
-    if (c === '"' && field === '') { inQuotes = true; i++; continue; }
-    if (c === ',') { row.push(field); field = ''; i++; continue; }
+    if (c === '"' && fieldBuf.length === 0) { inQuotes = true; i++; continue; }
+    if (c === ',') { row.push(flushField()); i++; continue; }
     if (c === '\n' || c === '\r') {
       if (c === '\r' && text[i + 1] === '\n') i++;
-      row.push(field);
-      field = '';
-      if (row.length > 1 || row[0] !== '') rows.push(row);
-      row = [];
+      row.push(flushField());
+      if (row.length > 1 || row[0] !== '') {
+        if (isFiniteMaxRows && rows.length + 1 > maxRows) {
+          throw new Error(
+            `CSV too many rows: ${rows.length + 1} exceeds limit of ${maxRows} ` +
+            `(raise opts.maxRows or split the file)`
+          );
+        }
+        flushRow();
+      } else {
+        row = [];
+      }
       i++;
       continue;
     }
-    field += c;
+    fieldBuf.push(c);
     i++;
   }
-  if (field !== '' || row.length > 0) {
-    row.push(field);
-    if (row.length > 1 || row[0] !== '') rows.push(row);
+  if (fieldBuf.length > 0 || row.length > 0) {
+    row.push(flushField());
+    if (row.length > 1 || row[0] !== '') {
+      if (isFiniteMaxRows && rows.length + 1 > maxRows) {
+        throw new Error(
+          `CSV too many rows: ${rows.length + 1} exceeds limit of ${maxRows} ` +
+          `(raise opts.maxRows or split the file)`
+        );
+      }
+      flushRow();
+    }
   }
   return rows;
 }
@@ -123,7 +169,23 @@ async function exportAllToJSON(engine, tables) {
 
 async function importFromJSON(engine, data, opts = {}) {
   const overwrite = !!(opts && opts.overwrite);
-  let tables = typeof data === 'string' ? JSON.parse(data) : data;
+  let tables;
+  if (typeof data === 'string') {
+    // JSON.parse 吞超长输入也会打爆堆 —— 先加体积护栏，错误带位置
+    const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_JSON_LENGTH : opts.maxInputSize;
+    if (typeof maxLen === 'number' && Number.isFinite(maxLen) && data.length > maxLen) {
+      throw new Error(
+        `JSON text too large: ${data.length} chars exceeds limit of ${maxLen} ` +
+        `(raise opts.maxInputSize to allow larger input)`
+      );
+    }
+    try { tables = JSON.parse(data); }
+    catch (e) {
+      throw new Error(`importFromJSON: invalid JSON: ${e.message}`);
+    }
+  } else {
+    tables = data;
+  }
   // 兼容单表形状：exportTableToJSON 返回 { table, schema, rows }
   if (tables && !Array.isArray(tables) && typeof tables === 'object'
       && tables.table && tables.schema && !tables[tables.table]) {
@@ -142,8 +204,13 @@ async function importFromJSON(engine, data, opts = {}) {
     await engine.createTable(name, normalizeSchema(t.schema));
     created.push(name);
     if (Array.isArray(t.rows) && t.rows.length > 0) {
-      const ids = await engine.insert(name, t.rows.map(r => ({ ...r })));
-      inserted += Array.isArray(ids) ? ids.length : t.rows.length;
+      // 分块 insert —— 避免全量 rows.map 先攒再 insert
+      const chunkSize = opts.chunkSize != null ? opts.chunkSize : DEFAULT_CHUNK_SIZE;
+      for (let i = 0; i < t.rows.length; i += chunkSize) {
+        const chunk = t.rows.slice(i, i + chunkSize).map(r => ({ ...r }));
+        const ids = await engine.insert(name, chunk);
+        inserted += Array.isArray(ids) ? ids.length : chunk.length;
+      }
     }
   }
   return { created, inserted };
@@ -161,7 +228,8 @@ async function exportTableToCSV(engine, table) {
 
 async function importFromCSV(engine, table, csv, opts = {}) {
   const schema = opts.schema || await engine.getTableSchema(table);
-  const rows = parseCSV(csv);
+  // parseCSV 内已有体积/行数护栏，这里传 opts.maxInputSize / opts.maxRows
+  const rows = parseCSV(csv, opts);
   if (rows.length === 0) return { inserted: 0 };
   let columns;
   let start = 0;
@@ -179,24 +247,43 @@ async function importFromCSV(engine, table, csv, opts = {}) {
     }
     await engine.createTable(table, normalizeSchema(schema));
   }
-  const dataRows = [];
-  for (let i = start; i < rows.length; i++) {
-    const row = {};
-    for (let j = 0; j < columns.length; j++) {
-      const type = schema && schema[columns[j]] ? schema[columns[j]].type : 'string';
-      row[columns[j]] = parseValue(rows[i][j], type);
-    }
-    if (row.id === null || row.id === undefined || row.id === '') delete row.id;
-    dataRows.push(row);
+  const chunkSize = opts.chunkSize != null ? opts.chunkSize : DEFAULT_CHUNK_SIZE;
+  let inserted = 0;
+  // 不攒 dataRows 全量，边解析边分块写入 —— 避免 2M 行全在内存里
+  for (let i = start; i < rows.length; i += chunkSize) {
+    const chunk = rows.slice(i, i + chunkSize);
+    const dataRows = chunk.map(raw => {
+      const row = {};
+      for (let j = 0; j < columns.length; j++) {
+        const type = schema && schema[columns[j]] ? schema[columns[j]].type : 'string';
+        row[columns[j]] = parseValue(raw[j], type);
+      }
+      if (row.id === null || row.id === undefined || row.id === '') delete row.id;
+      return row;
+    });
+    const ids = await engine.insert(table, dataRows);
+    inserted += Array.isArray(ids) ? ids.length : dataRows.length;
   }
-  const ids = dataRows.length > 0 ? await engine.insert(table, dataRows) : [];
-  return { inserted: dataRows.length, ids };
+  return { inserted };
 }
 
 /* ---------- mysqldump ---------- */
 
 async function importDump(engine, sqlText, opts = {}) {
-  const statements = splitStatements(sqlText);
+  // splitStatements 自身有体积护栏，但这里要让用户能通过 opts.maxInputSize 覆盖，
+  // 还要额外加「语句数量」护栏 —— 64 MiB 里可能塞几百万条小 INSERT，每条都合法但合起来打爆堆。
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_SQL_LENGTH : opts.maxInputSize;
+  const splitOpts = { maxLength: maxLen };
+  const statements = splitStatements(sqlText, splitOpts);
+
+  const maxStmts = opts.maxStatements == null ? DEFAULT_MAX_STATEMENTS : opts.maxStatements;
+  if (typeof maxStmts === 'number' && Number.isFinite(maxStmts) && statements.length > maxStmts) {
+    throw new Error(
+      `SQL dump too many statements: ${statements.length} exceeds limit of ${maxStmts} ` +
+      `(raise opts.maxStatements or split the dump file)`
+    );
+  }
+
   const created = [];
   let inserted = 0;
   const errors = [];
@@ -221,6 +308,15 @@ async function importDump(engine, sqlText, opts = {}) {
 }
 
 async function importDumpFile(engine, filePath, opts = {}) {
+  // 先看文件大小再决定是否读 —— 避免 fs.readFileSync 把超大 dump 一次性吃进堆
+  const maxLen = opts.maxInputSize == null ? DEFAULT_MAX_SQL_LENGTH : opts.maxInputSize;
+  const stat = fs.statSync(filePath);
+  if (typeof maxLen === 'number' && Number.isFinite(maxLen) && stat.size > maxLen) {
+    throw new Error(
+      `Dump file too large: ${stat.size} bytes exceeds limit of ${maxLen} ` +
+      `(raise opts.maxInputSize or split the file)`
+    );
+  }
   const text = fs.readFileSync(filePath, 'utf8');
   return importDump(engine, text, opts);
 }

package/lib/native_client.js

@@ -17,6 +17,33 @@ function safeParse(str, fallback) {
   try { return JSON.parse(str); } catch (e) { return fallback; }
 }
 
+/**
+ * 序列化对象/数组字段（JSON 列）并给出可读错误。直接 JSON.stringify 遇到循环引用会抛
+ * "Converting circular structure to JSON"，指向不到具体列，这里补上表/列信息。
+ * 与 lib/wasm_client.js 的 safeStringify 保持一致。
+ */
+function safeStringify(value, table, column) {
+  try {
+    return JSON.stringify(value);
+  } catch (e) {
+    const msg = (e && e.message) ? e.message : String(e);
+    throw new Error(`Cannot serialize column '${column}' of table '${table}': ${msg}`);
+  }
+}
+
+/** 插入行必须是普通对象；null/undefined/数组/基本类型在这里就被拦下（与 lib/wasm_client.js 一致） */
+function assertRowObject(row, index, isBatch) {
+  const ok = row !== null && row !== undefined && typeof row === 'object' &&
+    !Array.isArray(row) && !(row instanceof Date);
+  if (ok) return;
+  const got = row === null ? 'null'
+    : Array.isArray(row) ? 'array'
+      : row instanceof Date ? 'Date'
+        : typeof row;
+  const where = isBatch ? ` at index ${index}` : '';
+  throw new TypeError(`insert(): expected a row object${where}, got ${got}`);
+}
+
 const NATIVE_TYPE_MAP = {
   text: 'string',
   varchar: 'string',
@@ -399,8 +426,17 @@ class JSQL {
       rows = rows.map(row => {
         const out = {};
         for (const [k, v] of Object.entries(row)) {
-          if (v instanceof Date) out[k] = v.toISOString();
-          else out[k] = v;
+          const def = schema[k];
+          let t = null;
+          if (typeof def === 'string') t = def.toLowerCase();
+          else if (def && typeof def === 'object' && def.type) t = String(def.type).toLowerCase();
+          if (v !== null && v !== undefined && ['json', 'array', 'object'].includes(t) && typeof v !== 'string') {
+            out[k] = safeStringify(v, table, k);
+          } else if (v instanceof Date) {
+            out[k] = v.toISOString();
+          } else {
+            out[k] = v;
+          }
         }
         return out;
       });
@@ -450,18 +486,39 @@ class JSQL {
   async _flush() {
     this._flushOpsNow();
     if (!this._runHooks('beforeFlush', [])) return null;
-    const flushed = {};
-    for (const [table, rows] of Object.entries(this._buffer)) {
-      if (rows.length === 0) continue;
-      const r = await this._insertBatch(table, rows);
-      flushed[table] = r;
-    }
+    // 先把整个 buffer 原子取出再写入。
+    // 旧写法是遍历 this._buffer、await 之后才清空 —— 期间其他协程继续往同一个数组
+    // push，同一批行会被多个 flush 重复写入（并发 insert 行数暴涨/丢行）。
+    // 与 lib/wasm_client.js 的修法保持一致。
+    const pending = this._buffer;
     this._buffer = {};
     this._bufferSize = 0;
+    const flushed = {};
+    try {
+      for (const [table, rows] of Object.entries(pending)) {
+        if (rows.length === 0) continue;
+        flushed[table] = await this._insertBatch(table, rows);
+      }
+    } catch (e) {
+      // 坏行不回写 buffer：否则 stop() 二次 flush 会再抛同一个错导致进程 exit 1
+      if (!this._flushErrors) this._flushErrors = [];
+      this._flushErrors.push({
+        at: Date.now(),
+        message: (e && e.message) ? e.message : String(e),
+        tables: Object.keys(pending),
+        rowCounts: Object.fromEntries(Object.entries(pending).map(([t, r]) => [t, r.length])),
+      });
+      throw e;
+    }
     this._runHooks('afterFlush', []);
     return flushed;
   }
 
+  /** 返回历次 flush 失败的记录（坏行不会回写 buffer，只能从这里查） */
+  lastFlushErrors() {
+    return (this._flushErrors || []).slice();
+  }
+
   _flushOpsNow() {
     if (this._opTimer) {
       clearTimeout(this._opTimer);
@@ -479,7 +536,11 @@ class JSQL {
   }
 
   async insert(table, data) {
+    // 入参校验：null / undefined / 非对象会在下游 Object.entries() 处炸成
+    // 难以定位的 "Cannot convert undefined or null to object"，这里直接给明确 TypeError
+    // （与 lib/wasm_client.js 的 assertRowObject 保持一致）
     const arr = Array.isArray(data) ? data : [data];
+    arr.forEach((row, i) => assertRowObject(row, i, arr.length > 1 || Array.isArray(data)));
     var filtered = arr;
     if (!this._runHooks('beforeInsert', [table, filtered])) return [];
     if (arr.length > 1) {