@@ -95,6 +95,8 @@ import {
9595 BOUNDED_STRING_FIELD_TYPES ,
9696 VALUE_DOMAIN_FIELD_TYPES ,
9797 REFERENCE_VALUE_TYPES ,
98+ SINGLE_OPTION_TYPES ,
99+ expandEmptyOperator ,
98100 FILE_REFERENCE_TYPES ,
99101 STRUCTURED_JSON_TYPES ,
100102 NUMERIC_VALUE_TYPES ,
@@ -717,8 +719,9 @@ function isInReadonlyScope(name: string, def: FieldDef, scope: ReadonlyValueScop
717719/**
718720 * [#20308] A BLANK string on a non-string-typed column is that column's typed
719721 * blank, `null` — the write door's one reading of it. [#29176] So is `''` on
720- * an optional text-like column a unique constraint covers (its own section
721- * below).
722+ * an optional text-like column a unique constraint covers, and [#29277] `''`
723+ * on an optional single-value option or reference column (each its own
724+ * section below).
722725 *
723726 * "Blank" is exactly what {@link isMissing} calls missing: `''` or a string of
724727 * whitespace. "Non-string-typed" is the spec's `NON_TEXT_STORED_VALUE_TYPES` —
@@ -756,13 +759,28 @@ function isInReadonlyScope(name: string, def: FieldDef, scope: ReadonlyValueScop
756759 * - a blank here also takes a declared `defaultValue` on insert, as the typed
757760 * arm's does — the door runs before the defaults, by design.
758761 *
762+ * ## [#29277] Single-value option and reference columns
763+ *
764+ * Exactly `''` on a column that is ALL of: string-stored single-value on the
765+ * `$empty` table's `null_only` row ({@link isSingleValueCodeColumn}: a
766+ * `SINGLE_OPTION_TYPES` or `REFERENCE_VALUE_TYPES` member that
767+ * `expandEmptyOperator` puts on `null_only`, so `multiple: true` is out), and
768+ * not `required: true` — is `null` from the door on, unique or not
769+ * (maintainer ruling B on #29346, record 6579813296). `''` is neither an
770+ * option code nor a record id, so it holds no value there; the ruled table
771+ * reads only `null` as empty on that row, and is unchanged — a row that
772+ * already stores `''` keeps answering as a value until a data step cleans it.
773+ * On a unique column the second record cleared is no longer refused `409`.
774+ * The same edges as the text arm: never whitespace (a value), never a
775+ * `required` column, and a blank on insert takes a declared `defaultValue`.
776+ *
759777 * ## What it does NOT touch
760778 *
761- * ⛔ Every other string-stored column — text no unique constraint covers,
762- * lookup ids, select values. There `''` is a value, and the spec 's value
763- * round-trip fixture pins it (`str_empty`: an empty string must not become
764- * null). What "empty" means for those columns is a separate question, not
765- * answered here . ⛔ A non-blank value, and every non-string value, of any
779+ * ⛔ Every other string-stored column — text no unique constraint covers, a
780+ * `multiple: true` option or reference column ( the table 's `multi_value`
781+ * row), a file reference, a computed column. There `''` is a value, and the
782+ * spec's value round-trip fixture pins it on text (`str_empty`: an empty
783+ * string must not become null) . ⛔ A non-blank value, and every non-string value, of any
766784 * type: `null`, `0`, `false`, `'abc'` pass through untouched, so every type
767785 * check and refusal downstream sees what it saw.
768786 *
@@ -793,22 +811,22 @@ export function normalizeBlankTypedValues<T>(
793811 const fields = objectSchema ?. fields ;
794812 if ( ! fields || ! data || typeof data !== 'object' ) return data ;
795813 // Read once per call, and only when a row carries an `''` at all.
796- let uniqueBlank : ReadonlySet < string > | undefined ;
797- const uniqueBlankColumns = ( ) => ( uniqueBlank ??= optionalUniqueTextColumns ( fields , objectSchema ?. indexes ) ) ;
814+ let blankNull : ReadonlySet < string > | undefined ;
815+ const blankNullColumns = ( ) => ( blankNull ??= blankAsNullColumns ( fields , objectSchema ?. indexes ) ) ;
798816 if ( Array . isArray ( data ) ) {
799817 let rows : unknown [ ] | undefined ;
800818 for ( let i = 0 ; i < data . length ; i ++ ) {
801- const row = normalizeBlankTypedRow ( fields , uniqueBlankColumns , data [ i ] ) ;
819+ const row = normalizeBlankTypedRow ( fields , blankNullColumns , data [ i ] ) ;
802820 if ( row !== data [ i ] ) ( rows ??= data . slice ( ) ) [ i ] = row ;
803821 }
804822 return ( rows ?? data ) as T ;
805823 }
806- return normalizeBlankTypedRow ( fields , uniqueBlankColumns , data ) as T ;
824+ return normalizeBlankTypedRow ( fields , blankNullColumns , data ) as T ;
807825}
808826
809827function normalizeBlankTypedRow (
810828 fields : Record < string , FieldDef > ,
811- uniqueBlankColumns : ( ) => ReadonlySet < string > ,
829+ blankNullColumns : ( ) => ReadonlySet < string > ,
812830 row : unknown ,
813831) : unknown {
814832 if ( ! isPlainRecord ( row ) ) return row ;
@@ -818,7 +836,7 @@ function normalizeBlankTypedRow(
818836 // Own-property: a field name may be `constructor` / `valueOf`.
819837 const def = Object . prototype . hasOwnProperty . call ( fields , name ) ? fields [ name ] : undefined ;
820838 if ( ! def ) continue ;
821- if ( ! NON_TEXT_STORED_VALUE_TYPES . has ( def . type ) && ! ( value === '' && uniqueBlankColumns ( ) . has ( name ) ) ) continue ;
839+ if ( ! NON_TEXT_STORED_VALUE_TYPES . has ( def . type ) && ! ( value === '' && blankNullColumns ( ) . has ( name ) ) ) continue ;
822840 ( out ??= { ...row } ) [ name ] = null ;
823841 }
824842 return out ?? row ;
@@ -835,25 +853,46 @@ function normalizeBlankTypedRow(
835853 * (`EmptyCredentialWriteError`) while `null` means "clear", so rewriting the
836854 * blank here would turn that refusal into a silent clear.
837855 *
838- * ⛔ Not `select` / `radio` / `lookup` / `user` and the other single-value
839- * string-stored types: the same `$empty` table reads their `''` as a value,
840- * so rewriting it would change an `is_empty` answer. That is a separate
841- * question from this one.
856+ * The single-value option and reference types are not text-like: their arm
857+ * is {@link isSingleValueCodeColumn} (#29277), which needs no unique
858+ * constraint.
842859 */
843860const UNIQUE_BLANK_TEXT_TYPES : ReadonlySet < string > = new Set (
844861 [ ...STRING_VALUE_TYPES ] . filter ( ( t ) => t !== 'password' && t !== 'secret' ) ,
845862) ;
846863
847864/**
848- * [#29176] The columns of one object whose `''` the write door stores as
849- * `null`: text-like ({@link UNIQUE_BLANK_TEXT_TYPES}), not `required: true`,
850- * not a lifecycle column the engine owns, and covered by a unique constraint
851- * on either surface the drivers build one from — a field's own `unique`, or a
852- * declared `indexes[]` entry whose `unique` asks for one. Both surfaces are
853- * read through `isUniqueDeclared`, the drivers' own predicate, so a column
854- * the store does not constrain is never rewritten.
865+ * [#29277] The string-stored single-value classes: an option code
866+ * (`SINGLE_OPTION_TYPES`) or a record id (`REFERENCE_VALUE_TYPES`), read as
867+ * the spec's constants, never re-listed.
868+ */
869+ const SINGLE_VALUE_CODE_TYPES : ReadonlySet < string > = new Set ( [ ...SINGLE_OPTION_TYPES , ...REFERENCE_VALUE_TYPES ] ) ;
870+
871+ /**
872+ * [#29277] Is `def` a string-stored single-value column on the `$empty`
873+ * table's `null_only` row? The row is the table's own answer
874+ * (`expandEmptyOperator`), so a `multiple: true` column — the `multi_value`
875+ * row — is never one, and a type the table moves is followed without an edit.
855876 */
856- function optionalUniqueTextColumns ( fields : Record < string , FieldDef > , indexes : unknown ) : ReadonlySet < string > {
877+ function isSingleValueCodeColumn ( def : FieldDef ) : boolean {
878+ return SINGLE_VALUE_CODE_TYPES . has ( def . type ) && expandEmptyOperator ( def ) . arm === 'null_only' ;
879+ }
880+
881+ /**
882+ * The columns of one object whose `''` the write door stores as `null`. Each
883+ * is not `required: true` and not a lifecycle column the engine owns, and is
884+ * ONE of:
885+ *
886+ * - [#29176] text-like ({@link UNIQUE_BLANK_TEXT_TYPES}) and covered by a
887+ * unique constraint on either surface the drivers build one from — a
888+ * field's own `unique`, or a declared `indexes[]` entry whose `unique` asks
889+ * for one. Both surfaces are read through `isUniqueDeclared`, the drivers'
890+ * own predicate, so a text column the store does not constrain is never
891+ * rewritten;
892+ * - [#29277] a single-value option or reference column
893+ * ({@link isSingleValueCodeColumn}), unique or not.
894+ */
895+ function blankAsNullColumns ( fields : Record < string , FieldDef > , indexes : unknown ) : ReadonlySet < string > {
857896 const covered = new Set < string > ( ) ;
858897 for ( const [ name , def ] of Object . entries ( fields ) ) {
859898 if ( def && isUniqueDeclared ( def . unique ) ) covered . add ( name ) ;
@@ -865,12 +904,9 @@ function optionalUniqueTextColumns(fields: Record<string, FieldDef>, indexes: un
865904 }
866905 }
867906 const out = new Set < string > ( ) ;
868- for ( const name of covered ) {
869- if ( SKIP_FIELDS . has ( name ) ) continue ;
870- // Own-property: a field name may be `constructor` / `valueOf`.
871- const def = Object . prototype . hasOwnProperty . call ( fields , name ) ? fields [ name ] : undefined ;
872- if ( ! def || def . required === true || ! UNIQUE_BLANK_TEXT_TYPES . has ( def . type ) ) continue ;
873- out . add ( name ) ;
907+ for ( const [ name , def ] of Object . entries ( fields ) ) {
908+ if ( ! def || SKIP_FIELDS . has ( name ) || def . required === true ) continue ;
909+ if ( UNIQUE_BLANK_TEXT_TYPES . has ( def . type ) ? covered . has ( name ) : isSingleValueCodeColumn ( def ) ) out . add ( name ) ;
874910 }
875911 return out ;
876912}
0 commit comments