@rex0220/kintone-sql-tools 3.75.0 → 3.77.0

package/README.md

@@ -188,6 +188,10 @@ Options:
   --var <name=value>         Override a DECLARE variable (repeatable; not for secrets)
   --import-csv <name=path>   Supply named CSV and enable IMPORT (repeatable)
   --import-json <name=path>  Supply named JSON and enable IMPORT (repeatable)
+  --export-csv <name=path>   Export temp table #<name> as RFC 4180 CSV after the batch succeeds (repeatable)
+  --export-csv <path>        Export the result of a single SELECT as CSV (no name; path must not contain '=')
+  --export-encoding <type>   CSV export encoding: utf8 | sjis (default: utf8; unrepresentable characters fail)
+  --export-timezone <zone>   IANA timezone for DATETIME cells in CSV export (default: keep UTC)
   --format <type>            Output format: table | json | jsonl | csv | markdown | md
                              (batch + json: prints one JSON envelope for the whole batch)
   --max-records <n>          Max records to fetch (default: 500)
@@ -238,6 +242,12 @@ Options:
 ```
 <!-- END_HELP_SYNC -->
 
+`--export-csv` の引数規則: 最初の `=` で `name` と `path` に分割し、`=` を含む引数は必ず名前付き（左辺が temp table
+識別子でなければ ArgumentError。`C:\...` の `:` は区切りではない）。名前なし `<path>` は単文 SELECT のときだけ・1 件だけで、
+`=` を含む path には使えない。同じ名前・同じ path の重複、`--output` と同じ path、`--dry-run` との併用は実行前に拒否。
+SQL 全文が成功した後にだけ全 sink を serialize し、同一 directory の一時 file → fsync → close → rename で書く
+（失敗時は旧 file 維持・一時 file 削除）。既存 file を他プロセスが開いている Windows では `EPERM` で失敗し旧 file が残る。
+
 ## 最低限のトラブルシュート
 
 1. `ArgumentError: no APPxxx found...`
@@ -267,7 +277,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 +318,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 +331,41 @@ 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つだけです。
+
+CSV export（B179）は temp table を名前付きシンクとして事前宣言し、全文実行後に serialize します。
+engine は path を持たず bytes と receipt を返すだけで、file 書込みと sha256 は呼出側の責務です:
+
+```ts
+import {
+  createExecutionContext, executeStatement, exportSinkStatus, serializeExportSink,
+  serializeSelectResultAsCsv, disposeExecutionContext,
+} from "@rex0220/kintone-sql-tools/flow";
+
+const ctx = createExecutionContext({
+  client, script: "CREATE TEMP TABLE #export AS SELECT code, amount FROM APP1; UPDATE APP1 SET 状態 = '済' WHERE ...",
+  exportSinks: [{ name: "export" }],   // #export の CREATE TEMP TABLE がちょうど 1 文なければ同期 throw
+});
+for (const statement of statements) await executeStatement(statement, ctx);   // EXIT 後の skipped も回収
+if (exportSinkStatus(ctx, "export") === "materialized") {          // not-created = EXIT で未生成（file を作らない）
+  const csv = serializeExportSink(ctx, "export", { encoding: "utf8", timezone: "Asia/Tokyo" });
+  // csv.data (Uint8Array) を書く／sha256 を取る。csv.receipt = { rows, columns, bytes, encoding }
+}
+await disposeExecutionContext(ctx);
+// 単文 SELECT: serializeSelectResultAsCsv(await executeStatement(stmt, ctx))
+```
+
+CSV は RFC 4180（CRLF・header あり・BOM なし）。複数値は LF 連結、user 系は `code`、SUBTABLE / FILE 列は
+`ExportSinkUnsupportedColumnError`、計算列の指数表記は 10 進展開、DATETIME は `timezone` 指定時だけ offset 付き。
+Shift_JIS は `encoding: "sjis"` と `encoder: { encoding: "sjis", encode(text) }` の注入で、encoder は表現不能文字で
+throw する義務を負います（encoding-japanese / iconv-lite は黙って `?` 置換するため、encode → decode → 完全一致検査を
+wrapper で行ってください）。
+
 読取上限は既定 10,000 件（`maxRecords`）です。一時テーブルの実体化には**独立の** `tempTableMaxRows`（既定 10,000 行・超過は常にエラー）が適用されるため、大きなバッチでは両方を併せて指定してください:
 
 ```ts