Add BrandedType and name the upgrade window's nullability with it

Merged
WE
16h ago
+80-2

A column can be NOT NULL at the current version and still have to accept null while a released upgrade command runs against an older schema. Today the only way to say that is to type the column string | null and explain it in a comment, which outlives the window it describes.

That situation is rare enough to be worth naming rather than commenting: of the 135 columns carrying @WasIntroducedInUpgrade, workflowVersion.coreWorkflowId is the only one declared nullable: false on the column and typed string | null. Every other introduced-in-upgrade column agrees with its own schema.

What it adds

BrandedType<TValue, TBrand> in twenty-shared/src/types, a phantom tag on an optional unique symbol. Three properties matter and are pinned by type assertions in the file:

  • the tag holds the brand name itself rather than a record of names. A record would make brands composable, but it defeats inference through the intersection, so a brand leaks through any helper that unwraps one by inference, which is exactly what UnwrapWasRemovedInUpgrade does. One brand per type is the trade, and the assertions pin that a second brand does not work;
  • it leaves assignability alone, so a branded string is still a string and a plain string still satisfies the branded type;
  • HasBrandedType detects a brand, and returns a literal true/false rather than boolean, so it can drive a satisfies check.

It marks and detects. It does not enforce, and the assertions say so rather than leaving someone to discover it.

NullableUntilUpgrade<TValue> uses it for the case above: the type is BrandedType<TValue, 'nullableUntilUpgrade'> | null, so null stays assignable to the column while the name records why. The cleanup is grep-able and dated: drop the wrapper once the commands that write null fall out of TWENTY_CROSS_UPGRADE_SUPPORTED_VERSIONS, which nx version:bump maintains.

The load-bearing change

ALL_MANY_TO_ONE_METADATA_RELATIONS now derives isNullable from the foreign key column rather than from the relation property.

That is what makes the brand useful: a relation can stay non-nullable while the column it reads still accepts null during an upgrade, instead of the relation property having to carry | null forever to keep the runtime resolvers from throwing.

It is behaviour-neutral today. The constant's satisfies check covers all 79 relations, and it still typechecks, which it would not if any relation property disagreed with its own foreign key column.

Verification

The three touched files typecheck, each checked on its own against the package tsconfig, and the type assertions are part of that: BrandedType.ts pins the brand's behaviour, nullable-until-upgrade.type.ts pins that null is assignable and that a plain value still satisfies the wrapper. Lint and format are clean. The full suites run in CI.

workflowVersion.coreWorkflowId carries the wrapper here, so the isNullable change can be judged against a real column. The PR stacked on this one declares that column's relation to workflow and is what makes the non-nullable relation property observable; a second one moves WasRemovedInUpgrade onto BrandedType.