@rex0220/kintone-sql-tools 3.74.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` / `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
 
@@ -289,6 +289,45 @@ try {
 }
 ```
 
+`/flow` から named `IMPORT` source を使う場合は、全APIへ `enableImport: true` を明示し、
+pathではなくlazy loaderが返す `Uint8Array` を登録します。省略または `false` は従来どおり
+`KSQL1202` で拒否し、resolverを渡すだけでは有効になりません。
+
+```ts
+import {
+  createImportSourceResolver,
+  parseScript,
+  createExecutionContext,
+} from "@rex0220/kintone-sql-tools/flow";
+
+const capability = { enableImport: true } as const;
+const importSource = createImportSourceResolver([{
+  name: "orders",
+  loader: { async load() { return { bytes, encoding: "sjis" }; } },
+}]);
+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);
+  },
+});
+```
+
+source名は完全一致・case-sensitiveです。loaderは対象文の実行到達時だけ呼ばれます。
+CSVの文字コードは `SQL ENCODING` > loader metadata > UTF-8、payload上限は10 MiBです。
+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

@@ -17606,19 +17606,86 @@ var ImportSourceError = class extends Error {
     this.name = "ImportSourceError";
   }
 };
+var ImportSourceBoundaryError = class extends Error {
+  constructor(code, message, cause) {
+    super(`${code}: ${message}`);
+    this.name = code;
+    this.code = code;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: false,
+        writable: false
+      });
+    }
+  }
+};
+function providerError(error) {
+  if (error === null || typeof error !== "object") return void 0;
+  const shaped = error;
+  const code = shaped.code === "ImportSourceReadError" || shaped.code === "ImportSourceNotRegularFileError" ? shaped.code : shaped.name === "ImportSourceReadError" || shaped.name === "ImportSourceNotRegularFileError" ? shaped.name : void 0;
+  if (!code) return void 0;
+  const fallback = code === "ImportSourceReadError" ? "IMPORT source could not be read." : "IMPORT source is not a regular file.";
+  return new ImportSourceBoundaryError(
+    code,
+    typeof shaped.message === "string" && shaped.message.length > 0 ? shaped.message : fallback,
+    error
+  );
+}
+function isUint8Array(value) {
+  return value !== null && typeof value === "object" && ArrayBuffer.isView(value) && Object.prototype.toString.call(value) === "[object Uint8Array]";
+}
 function resolveImportSource(name, resolver) {
-  if (!resolver) throw new ImportSourceError("IMPORT source capability is not available.");
-  const handle = resolver(name);
-  if (!handle) throw new ImportSourceError(`source "${name}" is not supplied.`);
-  return handle;
+  if (!resolver) {
+    throw new ImportSourceBoundaryError(
+      "ImportSourceNotSuppliedError",
+      `the named IMPORT source ${JSON.stringify(name)} was not supplied.`
+    );
+  }
+  try {
+    const handle = resolver(name);
+    if (!handle) {
+      throw new ImportSourceBoundaryError(
+        "ImportSourceNotSuppliedError",
+        `the named IMPORT source ${JSON.stringify(name)} was not supplied.`
+      );
+    }
+    if (typeof handle !== "object" || typeof handle.load !== "function") {
+      throw new ImportSourceBoundaryError(
+        "ImportSourceInvalidPayloadError",
+        "resolver must return a handle with a load function."
+      );
+    }
+    return handle;
+  } catch (error) {
+    if (error instanceof ImportSourceBoundaryError) throw error;
+    throw providerError(error) ?? new ImportSourceBoundaryError("ImportSourceReadError", "IMPORT source resolution failed.", error);
+  }
 }
 async function loadImportSource(handle, cache) {
   let pending = cache.get(handle);
   if (!pending) {
-    pending = handle.load().then((payload) => {
-      if (!(payload.bytes instanceof Uint8Array)) throw new ImportSourceError("loader must return Uint8Array bytes.");
+    pending = Promise.resolve().then(() => handle.load()).catch((error) => {
+      throw providerError(error) ?? new ImportSourceBoundaryError("ImportSourceReadError", "IMPORT source could not be read.", error);
+    }).then((payload) => {
+      if (payload === null || typeof payload !== "object" || !isUint8Array(payload.bytes)) {
+        throw new ImportSourceBoundaryError(
+          "ImportSourceInvalidPayloadError",
+          "loader must return Uint8Array bytes."
+        );
+      }
+      if (payload.encoding !== void 0 && payload.encoding !== "utf8" && payload.encoding !== "sjis") {
+        throw new ImportSourceBoundaryError(
+          "ImportSourceInvalidPayloadError",
+          "loader returned an unsupported encoding."
+        );
+      }
       if (payload.bytes.byteLength > IMPORT_MAX_BYTES) {
-        throw new ImportSourceError(`source exceeds the ${IMPORT_MAX_BYTES} byte limit.`);
+        throw new ImportSourceBoundaryError(
+          "ImportSourceTooLargeError",
+          `source exceeds the ${IMPORT_MAX_BYTES} byte limit.`
+        );
       }
       return payload;
     });
@@ -17979,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 }])),
@@ -17988,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
   });
@@ -18054,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" }])),
@@ -18064,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.
@@ -18083,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).");
@@ -18118,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
   });
@@ -18175,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
@@ -18466,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) {
@@ -18495,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;
@@ -24705,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);
@@ -25007,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);
@@ -25143,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;
@@ -29172,6 +29253,23 @@ function isSubtableRow(v) {
   return typeof obj.id === "string" && typeof obj.value === "object" && obj.value !== null;
 }
 
+// src/flow-library/importSources.ts
+var FlowImportProviderError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.name = code;
+    this.code = code;
+    if (cause !== void 0) {
+      Object.defineProperty(this, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: false,
+        writable: false
+      });
+    }
+  }
+};
+
 // src/output/batchEnvelope.ts
 function toMutationSummary(result) {
   if (result.type === "INSERT") {
@@ -32960,7 +33058,38 @@ async function run() {
     const importEnabled = Object.keys(args.importCsv).length > 0 || Object.keys(args.importJson).length > 0;
     const importSource = importEnabled ? (name) => {
       const sourcePath = args.importCsv[name] ?? args.importJson[name];
-      return sourcePath === void 0 ? void 0 : { load: async () => ({ bytes: new Uint8Array((0, import_fs2.readFileSync)(sourcePath)) }) };
+      if (sourcePath === void 0) return void 0;
+      return {
+        load: async () => {
+          let sourceStat;
+          try {
+            sourceStat = (0, import_fs2.statSync)(sourcePath);
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new FlowImportProviderError(
+              "ImportSourceReadError",
+              `failed to inspect IMPORT source "${sourcePath}": ${reason}`,
+              error
+            );
+          }
+          if (!sourceStat.isFile()) {
+            throw new FlowImportProviderError(
+              "ImportSourceNotRegularFileError",
+              `IMPORT source "${sourcePath}" is not a regular file.`
+            );
+          }
+          try {
+            return { bytes: new Uint8Array((0, import_fs2.readFileSync)(sourcePath)) };
+          } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new FlowImportProviderError(
+              "ImportSourceReadError",
+              `failed to read IMPORT source "${sourcePath}": ${reason}`,
+              error
+            );
+          }
+        }
+      };
     } : void 0;
     const confirm = async (count, operation, context) => {
       if (count > dmlMaxRows) {