ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/spanner/index.js

@@ -39,11 +39,10 @@
  * INTO ... VALUES (...)` upsert statement (Spanner has no `ON CONFLICT`
  * clause - verified against the GoogleSQL DML reference - but it does support
  * `INSERT OR UPDATE` / `INSERT OR IGNORE` / `INSERT OR REPLACE` as distinct
- * conflict-action variants at the language level). **Only `INSERT OR UPDATE
- * INTO` is currently implemented here** - there is no `conflictAction` option
- * to select `IGNORE`/`REPLACE` semantics from `buildInsertQuery()`/
- * `buildUpsertQuery()` yet; that's a gap, not a claim that this dialect wires
- * up all three. Additionally, `mutationUpsert()`/`mutationInsert()`/
+ * conflict-action variants at the language level). All three are selectable
+ * via the `conflictAction` option (`'UPDATE' | 'IGNORE' | 'REPLACE'`) on
+ * `buildInsertQuery()`/`buildUpsertQuery()`; `upsert: true` remains a legacy
+ * alias for `conflictAction: 'UPDATE'`. Additionally, `mutationUpsert()`/`mutationInsert()`/
  * `mutationUpdate()`/`mutationDelete()` and `bulkInsert()` are implemented
  * using the Mutation API directly and are the **recommended, primary**
  * mechanism for bulk/blind writes - they are simpler, avoid a SQL round-trip,
@@ -1525,14 +1524,34 @@ class SpannerDialect {
         return sql;
     }
     /**
-     * Build an INSERT statement. When `options.upsert` is set, emits
-     * GoogleSQL's `INSERT OR UPDATE INTO` upsert DML (verified: Spanner has no
-     * `ON CONFLICT` clause; GoogleSQL's DML upsert extension also offers
-     * `INSERT OR IGNORE` / `INSERT OR REPLACE` conflict-action variants, but
-     * only `OR UPDATE` is wired up here - there is no `conflictAction` option
-     * to select the other two). For bulk/blind writes prefer
-     * `mutationInsert()`/`mutationUpsert()` (the Mutation API) instead - see
-     * the file header.
+     * Map a Spanner conflict action (or the legacy `upsert: true` boolean) onto
+     * the corresponding GoogleSQL insert verb. GoogleSQL's DML upsert extension
+     * offers three distinct conflict-action variants (verified against the
+     * GoogleSQL DML reference - Spanner has no `ON CONFLICT` clause):
+     *  - `UPDATE`  → `INSERT OR UPDATE INTO`  (insert, or overwrite the row's non-key columns on PK collision)
+     *  - `IGNORE`  → `INSERT OR IGNORE INTO`  (insert, or silently skip on PK collision)
+     *  - `REPLACE` → `INSERT OR REPLACE INTO` (insert, or delete-then-reinsert the whole row on PK collision)
+     */
+    insertVerb(action) {
+        const normalized = action === true ? 'UPDATE' : action || undefined;
+        switch (normalized) {
+            case 'UPDATE':
+                return 'INSERT OR UPDATE INTO';
+            case 'IGNORE':
+                return 'INSERT OR IGNORE INTO';
+            case 'REPLACE':
+                return 'INSERT OR REPLACE INTO';
+            default:
+                return 'INSERT INTO';
+        }
+    }
+    /**
+     * Build an INSERT statement. Set `options.upsert` (legacy boolean, ⇒
+     * `INSERT OR UPDATE INTO`) or `options.conflictAction`
+     * (`'UPDATE' | 'IGNORE' | 'REPLACE'`) to emit one of GoogleSQL's three DML
+     * conflict-action upsert variants (Spanner has no `ON CONFLICT` clause). For
+     * bulk/blind writes prefer `mutationInsert()`/`mutationUpsert()` (the
+     * Mutation API) instead - see the file header.
      */
     buildInsertQuery(tableName, values, options) {
         const columns = Object.keys(values);
@@ -1547,7 +1566,7 @@ class SpannerDialect {
                 placeholders.push(`@p${processedValues.length}`);
             }
         }
-        const verb = options?.upsert ? 'INSERT OR UPDATE INTO' : 'INSERT INTO';
+        const verb = this.insertVerb(options?.conflictAction ?? options?.upsert);
         const sql = `${verb} ${this.escapeId(tableName)} (${columns.map((c) => this.escapeId(c)).join(', ')}) VALUES (${placeholders.join(', ')})`;
         if (options?.returning) {
             console.warn('Spanner: GoogleSQL DML has no RETURNING clause; ignoring options.returning.');
@@ -1555,15 +1574,18 @@ class SpannerDialect {
         return { sql, values: processedValues };
     }
     /**
-     * Build an upsert statement using GoogleSQL's `INSERT OR UPDATE INTO`.
-     * Note this is a *SQL DML* fallback for interface parity - the primary,
-     * recommended mechanism for upserts on this dialect is the Mutation API
-     * (`mutationUpsert()` / `database.table(name).upsert(rows)`); see the file
-     * header for why.
+     * Build an upsert statement using one of GoogleSQL's `INSERT OR ...` DML
+     * variants. Defaults to `INSERT OR UPDATE INTO`; pass
+     * `options.conflictAction` (`'UPDATE' | 'IGNORE' | 'REPLACE'`) to select
+     * ignore/replace semantics instead. Note this is a *SQL DML* path for
+     * interface parity - the primary, recommended mechanism for upserts on this
+     * dialect is the Mutation API (`mutationUpsert()` /
+     * `database.table(name).upsert(rows)`); see the file header for why.
      */
     buildUpsertQuery(tableName, values, options) {
-        void options;
-        return this.buildInsertQuery(tableName, values, { upsert: true });
+        return this.buildInsertQuery(tableName, values, {
+            conflictAction: options?.conflictAction ?? 'UPDATE',
+        });
     }
     buildIncrementQuery(tableName, fields, where, options) {
         const by = options?.by ?? 1;