@rex0220/kintone-sql-tools 3.28.0 → 3.30.0

package/dist-engine/meta/umd.json

@@ -95,7 +95,7 @@
       "format": "esm"
     },
     "src/core/dmlGuard.ts": {
-      "bytes": 8488,
+      "bytes": 9379,
       "imports": [
         {
           "path": "src/types/ast.ts",
@@ -159,7 +159,7 @@
       "format": "esm"
     },
     "src/converter/selectToKintone.ts": {
-      "bytes": 28156,
+      "bytes": 29239,
       "imports": [
         {
           "path": "../types/ast",
@@ -560,7 +560,7 @@
       "format": "esm"
     },
     "src/core/existingRecordValidation.ts": {
-      "bytes": 6056,
+      "bytes": 6562,
       "imports": [
         {
           "path": "src/core/dmlValidationCandidates.ts",
@@ -1161,7 +1161,7 @@
       "format": "esm"
     },
     "src/execute.ts": {
-      "bytes": 453813,
+      "bytes": 461839,
       "imports": [
         {
           "path": "src/lexer/lexer.ts",
@@ -1497,7 +1497,7 @@
       "format": "esm"
     },
     "src/engine-library/errors.ts": {
-      "bytes": 3031,
+      "bytes": 3714,
       "imports": [
         {
           "path": "src/api/fetchAll.ts",
@@ -1623,10 +1623,21 @@
       "format": "esm"
     },
     "src/engine-library/options.ts": {
-      "bytes": 3253,
+      "bytes": 5024,
       "imports": [],
       "format": "esm"
     },
+    "src/engine-library/resultMapping.ts": {
+      "bytes": 1867,
+      "imports": [
+        {
+          "path": "src/execute.ts",
+          "kind": "import-statement",
+          "original": "../execute"
+        }
+      ],
+      "format": "esm"
+    },
     "src/core/sql.ts": {
       "bytes": 858,
       "imports": [
@@ -1648,14 +1659,29 @@
       ],
       "format": "esm"
     },
+    "src/core/applyGuard.ts": {
+      "bytes": 638,
+      "imports": [],
+      "format": "esm"
+    },
     "src/engine-library/statementGuard.ts": {
-      "bytes": 3420,
+      "bytes": 4597,
       "imports": [
         {
           "path": "src/core/sql.ts",
           "kind": "import-statement",
           "original": "../core/sql"
         },
+        {
+          "path": "src/core/applyGuard.ts",
+          "kind": "import-statement",
+          "original": "../core/applyGuard"
+        },
+        {
+          "path": "src/core/dmlGuard.ts",
+          "kind": "import-statement",
+          "original": "../core/dmlGuard"
+        },
         {
           "path": "src/core/klikeValidation.ts",
           "kind": "import-statement",
@@ -1669,8 +1695,49 @@
       ],
       "format": "esm"
     },
+    "src/engine-library/batch.ts": {
+      "bytes": 3529,
+      "imports": [
+        {
+          "path": "src/execute.ts",
+          "kind": "import-statement",
+          "original": "../execute"
+        },
+        {
+          "path": "src/engine-library/errors.ts",
+          "kind": "import-statement",
+          "original": "./errors"
+        },
+        {
+          "path": "src/engine-library/cursorScope.ts",
+          "kind": "import-statement",
+          "original": "./cursorScope"
+        },
+        {
+          "path": "src/engine-library/options.ts",
+          "kind": "import-statement",
+          "original": "./options"
+        },
+        {
+          "path": "src/engine-library/readonlyClient.ts",
+          "kind": "import-statement",
+          "original": "./readonlyClient"
+        },
+        {
+          "path": "src/engine-library/resultMapping.ts",
+          "kind": "import-statement",
+          "original": "./resultMapping"
+        },
+        {
+          "path": "src/engine-library/statementGuard.ts",
+          "kind": "import-statement",
+          "original": "./statementGuard"
+        }
+      ],
+      "format": "esm"
+    },
     "src/engine-library/query.ts": {
-      "bytes": 3614,
+      "bytes": 2547,
       "imports": [
         {
           "path": "src/execute.ts",
@@ -1697,6 +1764,11 @@
           "kind": "import-statement",
           "original": "./readonlyClient"
         },
+        {
+          "path": "src/engine-library/resultMapping.ts",
+          "kind": "import-statement",
+          "original": "./resultMapping"
+        },
         {
           "path": "src/engine-library/statementGuard.ts",
           "kind": "import-statement",
@@ -1706,7 +1778,7 @@
       "format": "esm"
     },
     "src/engine-library/index.ts": {
-      "bytes": 985,
+      "bytes": 1160,
       "imports": [
         {
           "path": "src/engine-library/errors.ts",
@@ -1718,6 +1790,11 @@
           "kind": "import-statement",
           "original": "./browserClient"
         },
+        {
+          "path": "src/engine-library/batch.ts",
+          "kind": "import-statement",
+          "original": "./batch"
+        },
         {
           "path": "src/engine-library/query.ts",
           "kind": "import-statement",
@@ -1727,12 +1804,12 @@
       "format": "esm"
     },
     "src/engine-library/versionRegistry.ts": {
-      "bytes": 2952,
+      "bytes": 3002,
       "imports": [],
       "format": "esm"
     },
     "src/engine-library/umd.ts": {
-      "bytes": 509,
+      "bytes": 529,
       "imports": [
         {
           "path": "src/engine-library/index.ts",
@@ -1770,7 +1847,7 @@
           "bytesInOutput": 139
         },
         "src/core/grouping.ts": {
-          "bytesInOutput": 1281
+          "bytesInOutput": 1284
         },
         "src/core/aggregateExpression.ts": {
           "bytesInOutput": 2592
@@ -1782,7 +1859,7 @@
           "bytesInOutput": 92192
         },
         "src/core/dmlGuard.ts": {
-          "bytesInOutput": 1881
+          "bytesInOutput": 2857
         },
         "src/core/applyPatchScope.ts": {
           "bytesInOutput": 12612
@@ -1797,7 +1874,7 @@
           "bytesInOutput": 5075
         },
         "src/converter/selectToKintone.ts": {
-          "bytesInOutput": 8913
+          "bytesInOutput": 9186
         },
         "src/core/cteInlining.ts": {
           "bytesInOutput": 1224
@@ -1818,7 +1895,10 @@
           "bytesInOutput": 559
         },
         "src/core/groupingValidation.ts": {
-          "bytesInOutput": 5173
+          "bytesInOutput": 5175
+        },
+        "src/core/batch.ts": {
+          "bytesInOutput": 5518
         },
         "src/core/fieldSemantics.ts": {
           "bytesInOutput": 1368
@@ -1830,7 +1910,7 @@
           "bytesInOutput": 11162
         },
         "src/engine/evalWhere.ts": {
-          "bytesInOutput": 5516
+          "bytesInOutput": 5752
         },
         "src/core/dmlCustomCheck.ts": {
           "bytesInOutput": 1250
@@ -1845,7 +1925,7 @@
           "bytesInOutput": 9946
         },
         "src/converter/applyPatchToKintone.ts": {
-          "bytesInOutput": 4478
+          "bytesInOutput": 4501
         },
         "src/core/numberPrecision.ts": {
           "bytesInOutput": 870
@@ -1857,7 +1937,7 @@
           "bytesInOutput": 2802
         },
         "src/core/existingRecordValidation.ts": {
-          "bytesInOutput": 3341
+          "bytesInOutput": 3491
         },
         "src/core/postImageValidation.ts": {
           "bytesInOutput": 2207
@@ -1883,11 +1963,14 @@
         "src/core/applyUpsertExecutePrepared.ts": {
           "bytesInOutput": 1487
         },
+        "src/core/batchVariables.ts": {
+          "bytesInOutput": 667
+        },
         "src/core/outerJoinSearchAbortGuard.ts": {
           "bytesInOutput": 366
         },
         "src/core/explainMetadata.ts": {
-          "bytesInOutput": 626
+          "bytesInOutput": 627
         },
         "src/core/optimization/sharedPlanner.ts": {
           "bytesInOutput": 339
@@ -1923,7 +2006,7 @@
           "bytesInOutput": 2656
         },
         "src/engine/process.ts": {
-          "bytesInOutput": 19953
+          "bytesInOutput": 19954
         },
         "src/converter/subtableAdapter.ts": {
           "bytesInOutput": 643
@@ -1983,10 +2066,10 @@
           "bytesInOutput": 412
         },
         "src/execute.ts": {
-          "bytesInOutput": 163191
+          "bytesInOutput": 176457
         },
         "src/engine-library/errors.ts": {
-          "bytesInOutput": 1116
+          "bytesInOutput": 1306
         },
         "src/api/cursorLeaseManager.ts": {
           "bytesInOutput": 1777
@@ -2013,16 +2096,25 @@
           "bytesInOutput": 766
         },
         "src/engine-library/options.ts": {
-          "bytesInOutput": 1584
+          "bytesInOutput": 2212
+        },
+        "src/engine-library/resultMapping.ts": {
+          "bytesInOutput": 777
         },
         "src/core/sql.ts": {
-          "bytesInOutput": 84
+          "bytesInOutput": 186
+        },
+        "src/core/applyGuard.ts": {
+          "bytesInOutput": 236
         },
         "src/engine-library/statementGuard.ts": {
-          "bytesInOutput": 1082
+          "bytesInOutput": 1704
+        },
+        "src/engine-library/batch.ts": {
+          "bytesInOutput": 896
         },
         "src/engine-library/query.ts": {
-          "bytesInOutput": 1231
+          "bytesInOutput": 603
         },
         "src/engine-library/index.ts": {
           "bytesInOutput": 16
@@ -2031,10 +2123,10 @@
           "bytesInOutput": 1000
         },
         "src/engine-library/umd.ts": {
-          "bytesInOutput": 115
+          "bytesInOutput": 127
         }
       },
-      "bytes": 504254
+      "bytes": 528205
     }
   }
 }

package/dist-engine/publicTypes.d.ts

@@ -31,12 +31,29 @@ export interface ReadonlyAppInfo {
     name: string;
     description: string;
 }
+/**
+ * Read-only field metadata supplied to the engine.
+ *
+ * `VALIDATE` only checks constraints present in this metadata. If a BYO client
+ * omits `optionOrder`, `required`, or the min/max metadata below, those
+ * constraints are not validated and the result can silently contain zero
+ * errors. BYO clients must pass the corresponding values from
+ * `/k/v1/app/form/fields.json`.
+ *
+ * `createReadonlyKintoneClient()` supplies these values automatically, so its
+ * users do not need to change their client.
+ */
 export interface ReadonlyFieldInfo {
     code: string;
     label: string;
     fieldType: string;
     optionOrder?: Record<string, number>;
     sortKind?: "number" | "string";
+    required?: boolean;
+    minValue?: string;
+    maxValue?: string;
+    minLength?: string;
+    maxLength?: string;
     inSubtable?: boolean;
     subtableCode?: string;
 }
@@ -69,6 +86,33 @@ export interface RunQueryOptions {
     fetchParallel?: number;
     cursorMaxActive?: number;
 }
+/**
+ * Options for one read-only runBatch invocation.
+ *
+ * Temporary tables and variables exist only for that invocation. A batch is
+ * fail-closed: any failed statement makes runBatch throw instead of returning
+ * a partial BatchResult.
+ */
+export interface RunBatchOptions {
+    client: ReadonlyKintoneClient;
+    maxRecords?: number;
+    onLimitReached?: "error" | "truncate";
+    fetchParallel?: number;
+    cursorMaxActive?: number;
+    /**
+     * DECLARE されたバッチ変数へ渡す文字列値。
+     * キーは @ を付けず、大文字小文字を区別しない。SET 変数には注入できない。
+     */
+    variables?: Readonly<Record<string, string>>;
+    /**
+     * CREATE TEMP TABLE 1 表あたりの実体化行数上限（既定 10,000）。
+     * 超過は onLimitReached: "truncate" でも常に error となる。
+     *
+     * 一時テーブルは利用者アプリのプロセス内メモリに runBatch 呼び出し単位で実体化される。
+     * 同時に存在できるのは最大 16 表で、DROP TEMP TABLE により解放された枠は同じバッチ内で再利用できる。
+     */
+    tempTableMaxRows?: number;
+}
 export interface QueryColumn {
     name: string;
     valueType: "string";
@@ -85,14 +129,68 @@ export interface QueryMetrics {
     elapsedMs: number;
     cursorRecordsScanned: number;
 }
+export type ValidateConstraintCategory = "required" | "length" | "range" | "choice";
+export interface ValidateConstraintMetadata {
+    /** Constraint categories present on the fields targeted by VALIDATE. */
+    present: ValidateConstraintCategory[];
+    /** Known constraint categories absent from the fields targeted by VALIDATE. */
+    absent: ValidateConstraintCategory[];
+}
 export interface QueryResult {
     type: "query";
     rows: readonly Readonly<Record<string, string>>[];
     columns: readonly QueryColumn[];
     rowCount: number;
     warnings: readonly string[];
+    /** Present only for an existing-record VALIDATE query. */
+    validateStats?: {
+        errorRecords: number;
+        errorCount: number;
+        constraintMetadata?: ValidateConstraintMetadata;
+    };
     metrics: QueryMetrics;
 }
+/** Named now so a future DML VALIDATE ONLY result can extend this union additively. */
+export type BatchResultItem = QueryResult;
+export interface BatchStatementInfo {
+    /** Zero-based statement index in the submitted batch. */
+    readonly index: number;
+    /** Parser statement type, such as SELECT or CREATE_TEMP_TABLE. */
+    readonly type: string;
+    /**
+     * Successful BatchResult values contain successful statements only.
+     * A statement error makes runBatch throw instead of returning this DTO.
+     */
+    readonly status: "success" | "error" | "skipped";
+    readonly tempTable?: string;
+    readonly rowCount?: number;
+    readonly resultIndex?: number;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    readonly skippedReason?: string;
+}
+/**
+ * Successful read-only batch result.
+ *
+ * There is intentionally no `ok` field: if any statement fails, runBatch
+ * throws KsqlEngineError and returns no partial results. The error identifies
+ * the failed statement through statementIndex and statementType.
+ */
+export interface BatchResult {
+    readonly type: "batch";
+    readonly batch: true;
+    readonly statementCount: number;
+    readonly statements: readonly BatchStatementInfo[];
+    /**
+     * Row-returning statement results.
+     * Every metrics object is the same batch-wide aggregate, not a per-statement
+     * measurement; do not use it to attribute cost to an individual statement.
+     */
+    readonly results: readonly BatchResultItem[];
+    readonly warnings: readonly string[];
+}
 export interface ExplainResult {
     type: "explain";
     lines: readonly string[];

package/dist-engine/query.d.ts

@@ -1,3 +1,11 @@
 import type { ExplainResult, QueryResult, RunQueryOptions } from "./publicTypes";
+/**
+ * Executes one row-returning read-only statement: SELECT, WITH, UNION,
+ * SHOW APPS, DESCRIBE, or existing-record VALIDATE.
+ */
 export declare function runQuery(sql: string, options: RunQueryOptions): Promise<QueryResult>;
+/**
+ * Explains one SELECT, WITH, or UNION query without reading records.
+ * CREATE TEMP TABLE is not accepted; explain its source SELECT instead.
+ */
 export declare function explainQuery(sql: string, options: Omit<RunQueryOptions, "onLimitReached">): Promise<ExplainResult>;