[Upd4ting]

Why

A DMS create request that leaves out a @Localized() field, and sends no x-content-language header, used to answer that field as null (0.2.1). Since 0.2.2 the field is missing from the answer, while every other unset field still answers null. DMS's integration test files/route-answers fails on POST /api/native-attachments/new with 0.2.2 and 0.3.0, and that blocks dms#852. After this change the field answers null again, and the key undefined still stores nothing, as #100 made it.

What changed

• interface-data-api locks and unlocks a localized field with the request's locale as the key, which is undefined when the header is missing.
• In 0.2.1 lock stored the unsent value under the literal key "undefined". MongoDB wrote that undefined as null, and unlock(…, undefined) read the null back. fix(localization): refuse a non-record value under the "*" key #100 stopped lock from storing anything under no key, so unlock found nothing and answered undefined, which JSON leaves out.
• LocalizationModifier.unlock (src/modifiers/localization.ts) now answers the fallbackLocale value for no key, else null. That matches unlockrequest, which already answers null for no key in queries. A defined key reads as before. The base ContainerModifier.unlock still answers undefined for no key.
• The null broke a field with @Localized() over @Encrypted(): EncryptionModifier.unlock (src/modifiers/encryption.ts) destructured it and threw. It now reads null as no value and returns null. The shared modifier chain is unchanged, so custom modifiers read as before.
• docs/3.table-modifiers.md and the shipped skill say a no-key read of a localized field answers null when it has no fallback value.

flowchart TD
  A["read a @Localized field with key undefined"] --> B{"fallbackLocale has a value?"}
  B -- yes --> C["that value"]
  B -- no --> D["null"]
  C --> E["@Encrypted decrypts it"]
  D --> F["@Encrypted passes null through"]

Loading

Proof

src/tests/localized_no_key.test.ts creates a row without a locale, as interface-data-api does for a request without the header: assign, lock(…, undefined), insert into MongoDB, read back, unlock(…, undefined), JSON.stringify. It runs with pnpm exec ajs module test . -f dist/tests/localized_no_key.test.js.

Before, with src/ from origin/main (1d74d32):

  Localized fields - a request without a locale
    1) answers null for a field the request did not send

  0 passing (65ms)
  1 failing

  1) Localized fields - a request without a locale
       answers null for a field the request did not send:
     AssertionError: expected { _id: 'page-1', _instance: null } to have deep property 'title'

With only the LocalizationModifier.unlock change (628bb9e), the encrypted localized field threw:

  1) Localized fields - a request without a locale
       answers null for a field the request did not send:
     TypeError: object null is not iterable (cannot read property Symbol(Symbol.iterator))
      at EncryptionModifier.unlock (dist/modifiers/encryption.js:98:11)

After, on this branch, with the suites that pin the #100 no-key behaviour:

  Localized fields - a request without a locale
    ✔ answers null for a field the request did not send
  ...
    ✔ answers the fallback locale for no key
    ✔ answers the fallback locale when no locale is given
    ✔ stores nothing and finds nothing under no key
  41 passing (81ms)

pnpm run checks: Checks: 11 passed, 0 failed.

Attention

A value a request sends with no locale is still not stored, as since #100. In 0.2.1 it was stored under the "undefined" key and read back by the next request without a locale. This PR does not bring that back.

[Upd4ting]

Known follow-ups (accepted for this patch)

Round 3 of the review left two findings, accepted as-is for 0.3.1 and tracked as a follow-up:

1. A two-way modifier stacked after @Localized() now receives null on a no-key read. Before, the value was undefined and the modifier was skipped. A custom modifier, or a subclass of EncryptionModifier that overrides unlock, can throw there, and so can toJSON for the row. The built-in @Encrypted handles it. No AntelopeJS repo defines its own two-way modifier today.
2. EncryptionModifier.unlock's published parameter widens to LockedType | null, so a type derived as Parameters<EncryptionModifier["unlock"]>[0] now includes null. An override with the old type still compiles.

Both come from producing null inside the modifier chain instead of at the end of it. The follow-up is to make null the end-of-read default in ModifiersDynamicMetadata.get, in a minor release, because a missing locale with no fallback would then read null instead of undefined.