@rex0220/kintone-sql-tools 3.75.0 → 3.76.0

package/README.md

@@ -267,7 +267,7 @@ npm パッケージは 2 つのサブパスを **semver 対象の公開 API**
 | サブパス | 用途 | 主な export |
 |---|---|---|
 | `@rex0220/kintone-sql-tools/engine` | **read-only** のクエリ実行（ダッシュボード等）。書込 API は構造的に遮断 | `runQuery` / `runBatch` / `explainQuery` / `createReadonlyKintoneClient` / `KsqlEngineError` / `version` |
-| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript`（`asOf`/`timezone` 注入可） / `createExecutionContext`（`onChunkWritten` 書込チャンク通知） / `executeStatement` / `previewStatement`（dry-run 差分プレビュー・書込 0 回） / `disposeExecutionContext` / `createImportSourceResolver` / `FlowImportProviderError` / `createKintoneClient` / `isDmlResult`（`FlowDmlResult` 型ガード） / `version` |
+| `@rex0220/kintone-sql-tools/flow` | **Flow dialect 1**（→ [言語リファレンス §27](docs/ksql_language_reference.md)）のスクリプト解析・検証・**文単位実行**（バッチランナー向け・書込可能） | `parseScript` / `validateScript` / `explainScript`（`asOf`/`timezone` 注入可） / `createExecutionContext`（`onChunkWritten` 書込チャンク通知・`onImportSourceMaterialized` IMPORT receipt） / `executeStatement` / `previewStatement`（dry-run 差分プレビュー・書込 0 回） / `disposeExecutionContext` / `createImportSourceResolver` / `FlowImportProviderError` / `createKintoneClient` / `isDmlResult`（`FlowDmlResult` 型ガード） / `version` |
 
 バッチ実行ランナー **kSQL Flow**（`/flow` API を使った公式ランナー・別リポジトリ）: https://github.com/rex0220/ksql-flow
 
@@ -308,6 +308,10 @@ const importSource = createImportSourceResolver([{
 const parsed = parseScript(sql, capability);
 const ctx = createExecutionContext({
   ...capability, client, statements: parsed.statements, meta: parsed.meta, importSource,
+  onImportSourceMaterialized(info) {
+    // { statementIndex, name, kind, rows, encoding }
+    inputFiles.push(info);
+  },
 });
 ```
 
@@ -317,6 +321,13 @@ path解決、通常ファイル・symlink・allowlist・hash検査、open/read
 engineはpathを受け取りません。providerは `FlowImportProviderError` でread不能または通常ファイル外を
 分類でき、その他のsource境界エラーも `StatementResult.error.code` の安定codeで返ります。
 
+`onImportSourceMaterialized` はdecode・raw materialize成功直後、projection・validation・
+`ON ERROR SKIP` の選別・mutationより前に1回awaitされます。CSVの `rows` はheaderを除く
+RFC 4180 data record数（subtable CSVは継続行を含む）、JSONはtop-level record数です。
+CSVの `encoding` は上記優先順位の解決後、JSONは `"utf8"` です。callbackがthrow/rejectすると
+当該文はerrorになり、その文のmutation APIは0回です。通知objectのkeyは
+`statementIndex` / `name` / `kind` / `rows` / `encoding` の5つだけです。
+
 読取上限は既定 10,000 件（`maxRecords`）です。一時テーブルの実体化には**独立の** `tempTableMaxRows`（既定 10,000 行・超過は常にエラー）が適用されるため、大きなバッチでは両方を併せて指定してください:
 
 ```ts

package/dist-cli/ksql.js

@@ -18046,6 +18046,7 @@ function materializeJsonDmlSource(_source, payload, targets, maxRows) {
     importPresence.push(present);
   });
   return {
+    receipt: { rows: records.length, encoding: "utf8" },
     rows,
     columns: targets.map((target) => target.code),
     columnMeta: new Map(targets.map((target) => [target.code, { fieldType: target.fieldType }])),
@@ -18055,8 +18056,9 @@ function materializeJsonDmlSource(_source, payload, targets, maxRows) {
 
 // src/import/materializeDmlSource.ts
 function materializeCsvDmlSource(source, payload, maxRows, targetCodes, fieldInfos, recordNumberSourceHeader) {
+  const encoding = source.encoding ?? payload.encoding ?? "utf8";
   const decoded = decodeCsv(payload.bytes, {
-    encoding: source.encoding ?? payload.encoding ?? "utf8",
+    encoding,
     hasHeader: source.hasHeader,
     columns: source.columns
   });
@@ -18121,6 +18123,7 @@ function materializeCsvDmlSource(source, payload, maxRows, targetCodes, fieldInf
       return row;
     });
     return {
+      receipt: { rows: decoded.rows.length, encoding },
       rows: rows2,
       columns: [...targetCodes],
       columnMeta: new Map(targetCodes.map((code) => [code, { fieldType: infoByCode.get(code)?.fieldType ?? "SINGLE_LINE_TEXT" }])),
@@ -18131,6 +18134,7 @@ function materializeCsvDmlSource(source, payload, maxRows, targetCodes, fieldInf
   }
   const rows = decoded.rows.map((values) => Object.fromEntries(decoded.columns.map((column, i) => [column, values[i]])));
   return {
+    receipt: { rows: decoded.rows.length, encoding },
     rows,
     columns: decoded.columns,
     // CSV cells are decoded as strings; projections such as CAST may replace this metadata downstream.
@@ -18150,6 +18154,7 @@ function materializeJsonImportRecords(_source, payload, targets, maxParents, max
   if (targetByCode.size !== targets.length) throw new ImportSourceError("IMPORT targets contain duplicates.");
   let childTotal = 0;
   return {
+    receipt: { rows: decoded.length, encoding: "utf8" },
     records: decoded.map((record, index) => {
       const parentRow = index + 1;
       for (const code of record.keys()) if (!targetByCode.has(code)) sourceFail(parentRow, code, "unknown key (not declared in INTO).");
@@ -18185,8 +18190,9 @@ function materializeJsonImportRecords(_source, payload, targets, maxParents, max
   };
 }
 function materializeCliKintoneCsvImportRecords(source, payload, targets, replacementTables, maxParents, recordNumberSourceHeader) {
+  const encoding = source.encoding ?? payload.encoding ?? "utf8";
   const decoded = decodeCsv(payload.bytes, {
-    encoding: source.encoding ?? payload.encoding ?? "utf8",
+    encoding,
     hasHeader: source.hasHeader,
     columns: source.columns
   });
@@ -18242,7 +18248,7 @@ function materializeCliKintoneCsvImportRecords(source, payload, targets, replace
     }
   });
   if (records.length === 0) throw new ImportSourceError("CSV has no parent rows.");
-  return { records };
+  return { receipt: { rows: decoded.rows.length, encoding }, records };
 }
 
 // src/import/importRecordValidation.ts
@@ -18533,6 +18539,7 @@ var materializedMetaBySelectResult = /* @__PURE__ */ new WeakMap();
 var materializedMetaByValidationResult = /* @__PURE__ */ new WeakMap();
 var importSourceByDmlStatement = /* @__PURE__ */ new WeakMap();
 var statementEvaluationContextKey = /* @__PURE__ */ Symbol("statementEvaluationContext");
+var importSourceMaterializedCallbackKey = /* @__PURE__ */ Symbol("importSourceMaterializedCallback");
 var nativeUpsertExecutionKey = /* @__PURE__ */ Symbol("nativeUpsertExecution");
 var nativeUpsertExplainCapabilityKey = /* @__PURE__ */ Symbol("nativeUpsertExplainCapability");
 function withNativeUpsertExecutionOption(options, enabled, explainClientCapability) {
@@ -18562,6 +18569,10 @@ function bindStatementEvaluationContext(options) {
 function statementEvaluationContext(options) {
   return options[statementEvaluationContextKey] ?? {};
 }
+async function notifyImportSourceMaterialized(options, source, receipt) {
+  const callback = options[importSourceMaterializedCallbackKey];
+  if (callback) await callback({ name: source.sourceName, kind: source.kind, ...receipt });
+}
 var defaultCacheContextByClient = /* @__PURE__ */ new WeakMap();
 var nextDefaultCacheContextId = 1;
 var nextCacheInvocationId = 1;
@@ -24772,6 +24783,7 @@ async function executeImport(stmt, client, options, cacheContext, tempTables) {
     const numberPrecision = fieldInfos.some((info) => targetCodes.includes(info.code) && info.fieldType === "NUMBER") ? await getNumberPrecisionCached(stmt.appId, client, cacheContext) : void 0;
     const payload = await loadImportSource(handle, /* @__PURE__ */ new Map());
     const materialized = stmt.source.kind === "JSON" ? materializeJsonImportRecords(stmt.source, payload, targets, options.maxRecords ?? 1e4) : materializeCliKintoneCsvImportRecords(stmt.source, payload, targets, stmt.replaceSubtables ?? [], options.maxRecords ?? 1e4, stmt.recordNumberSourceHeader);
+    await notifyImportSourceMaterialized(options, stmt.source, materialized.receipt);
     const operation = stmt.source.kind === "CSV" ? "UPDATE" : stmt.keyFields ? "UPSERT" : "INSERT";
     const prepared = prepareImportRecords(materialized, targets, fieldInfos, numberPrecision, operation);
     if (stmt.source.kind === "CSV") return executeCsvSubtableReplacement(stmt, materialized, prepared, fieldInfos, client, options, tempTables);
@@ -25074,6 +25086,7 @@ async function executeImportRecordNumberUpdate(stmt, handle, client, options, ca
     fieldInfos,
     stmt.recordNumberSourceHeader
   );
+  await notifyImportSourceMaterialized(options, stmt.source, sourceTable.receipt);
   const keyValues = sourceTable.recordNumberSourceValues;
   if (!keyValues) throw new Error("InternalError: record-number source values were not materialized.");
   const keyPlan = preflightImportRecordNumbers(keyValues, stmt.recordNumberSourceHeader);
@@ -25210,6 +25223,7 @@ async function materializeDmlSource(stmt, client, options, cacheContext, tempTab
   const targetByCode = new Map((targetFields ?? []).map((info) => [info.code, info]));
   const jsonTargets = stmt.fields.map((code) => ({ code, fieldType: targetByCode.get(code)?.fieldType ?? "SINGLE_LINE_TEXT" }));
   const raw = imported.source.kind === "JSON" ? materializeJsonDmlSource(imported.source, payload, jsonTargets, rowLimit) : materializeCsvDmlSource(imported.source, payload, rowLimit, stmt.fields, targetFields);
+  await notifyImportSourceMaterialized(options, imported.source, raw.receipt);
   imported.audit = raw.importAudit;
   if (imported.source.kind === "JSON") return raw;
   if (!imported.source.projection) return raw;