Wire Compatibility (DELETE_TOKEN)

Wire compatibility in keyfold enables the use of a specific string token, DELETE_TOKEN, to represent field deletions in environments where the native JavaScript DELETE symbol cannot be transmitted, such as JSON-based network transports. This feature allows for a standardized "wire" protocol to communicate deletions from a client or external service to a keyfold merger.

By default, the DELETE_TOKEN is treated as ordinary string data. When the wireDeletes option is enabled during merger creation, the system interprets this token specifically at object-field positions as a command to remove the field, mirroring the behavior of the in-memory DELETE symbol.

Sources: README.md:104-106, src/sentinels.ts:4-5, test/wire.test.ts:16-18

Implementation and Configuration

The wire compatibility feature is controlled via the MergeOptions provided to createMerger. The wireDeletes flag must be explicitly set to true to enable token interpretation.

Configuration Parameters

Sources: src/types.ts:15-16, src/paths.ts:24-26, README.md:68

The Delete Token

The token is a fixed, exported constant defined within the library:

export const DELETE_TOKEN = "@@keyfold/delete" as const;

Sources: src/sentinels.ts:4-5

Token Interpretation Logic

The interpretation of DELETE_TOKEN is context-dependent. It is only treated as an operator at "interpreted positions"—specifically, as a value for an object field being merged or reconciled.

Flow of Token Interpretation

The following diagram illustrates how the merger decides whether to treat the token as data or an operator.

Interpreted vs. Data Positions

• Interpreted Positions: When wireDeletes is active, the token triggers a deletion if it appears as a field value in a plain object or a keyed list item during reconciliation.
• Data Positions: The token remains a literal string if nested inside a wholesale replace value or within an unkeyed array. It is also treated as data if the merger is at a "replace" boundary.

Sources: src/merge.ts:91-98, test/wire.test.ts:36-44, README.md:112-114

Restrictions and Safety

To prevent ambiguity and maintain data integrity, several restrictions are enforced when wireDeletes is enabled.

Forbidden Identity Values

A keyed item cannot use DELETE_TOKEN as its identity value. If a delta attempts to use the token as a key, the merger throws a KeyfoldMergeError. This prevents a scenario where an item's identity would be "deleted" during the fold, resulting in an item without an identity.

Sources: src/reconcile.ts:121-126, test/wire.test.ts:51-56

Static Typing Limits

While Delta<T> can statically prevent the use of the DELETE symbol on required fields, it cannot provide the same protection for DELETE_TOKEN. Because TypeScript cannot exclude a specific string literal from a broader string type, it is possible to pass the token to a required string field. Validation of wire input remains the responsibility of the caller.

Sources: README.md:191-195, test/wire.test.ts:58-69

Reconciler Validation

The reconciler indexes the delta and checks for the wire token before any output is generated. This ensures that the immutability guarantee is maintained and no partial writes occur if an invalid token usage is detected.

Conclusion

The DELETE_TOKEN system provides a robust mechanism for handling deletions over JSON interfaces. By separating the in-memory symbol (DELETE) from the wire-compatible string (DELETE_TOKEN), keyfold ensures that deletions can be communicated across service boundaries while maintaining strict control over where these tokens are interpreted as operators versus literal data. This design prevents accidental data loss in replacement boundaries while offering full functionality for deep-merging and list reconciliation.