These — Inclusive OR

TypeScript models exclusive-OR states with discriminated unions (A | B) and product states with objects ({ a: A; b: B }). However, operations like data synchronization, diff engines, and non-fatal warnings require modeling inclusive-OR states: having a first value, a second value, or both simultaneously.

These<A, B> represents inclusive-OR as a discriminated union of three variants: First<A>, Second<B>, and Both<A, B>: offering three distinct variants:

First(a) — only the first value is present.
Second(b) — only the second value is present.
Both(a, b) — both the first and second values are present.

flowchart TD
    Start([Data Presence Check]) --> Choice{What is present?}
    Choice -->|Only A| First[First A]
    Choice -->|Only B| Second[Second B]
    Choice -->|Both A and B| Both[Both A B]

These is a neutral, structural domain-modeling type. It does not carry any success, failure, or implicit error connotations. Neither side is privileged.

Structural Modeling: Domain Examples

1. Contact Information

Suppose you are designing a notification service that requires contact details. A user can register their email address A, their phone number B, or both Both(A, B). Representing this with standard union types or optional fields is fragile because it permits the invalid state of having neither.

With These, the type system enforces that at least one contact channel is present:

import { These } from "@nlozgachev/pipelined/core";

type ContactDetails = These<EmailAddress, PhoneNumber>;

const emailOnly = These.make.first(email);       // Email only
const phoneOnly = These.make.second(phone);      // Phone only
const both = These.make.both(email, phone);      // Both channels available

2. Local and Remote Synchronization

Suppose you are building a database synchronizer that reconciles local and remote changes. When comparing records, three outcomes are structurally possible:

Only local changes exist: First(local)
Only remote changes exist: Second(remote)
Both local and remote changes exist and must be merged: Both(local, remote)

interface UserRecord { id: string; name: string }

const reconcile = (local: UserRecord | null, remote: UserRecord | null): These<UserRecord, UserRecord> => {
  if (local && !remote) return These.make.first(local);
  if (!local && remote) return These.make.second(remote);
  if (local && remote)  return These.make.both(local, remote);
  throw new Error("Cannot reconcile when both sources are empty");
};

Transforming Values

Because These carries two distinct type parameters, we can map over either or both sides independently.

Mapping the first side with `mapFirst`

mapFirst transforms the value inside a First or a Both container, leaving Second entirely untouched:

import { pipe } from "@nlozgachev/pipelined/composition";

const formatEmail = (email: EmailAddress) => email.toLowerCase();

pipe(These.make.first(email), These.mapFirst(formatEmail));      // First(formattedEmail)
pipe(These.make.both(email, phone), These.mapFirst(formatEmail)); // Both(formattedEmail, phone)
pipe(These.make.second(phone), These.mapFirst(formatEmail));     // Second(phone)

Mapping the second side with `mapSecond`

mapSecond transforms the value inside a Second or a Both container, leaving First untouched:

const formatPhone = (phone: PhoneNumber) => phone.trim();

pipe(These.make.second(phone), These.mapSecond(formatPhone));  // Second(formattedPhone)
pipe(These.make.both(email, phone), These.mapSecond(formatPhone)); // Both(email, formattedPhone)

Mapping both sides with `mapBoth`

mapBoth allows you to transform both paths simultaneously:

pipe(
  These.make.both(email, phone),
  These.mapBoth(formatEmail, formatPhone),
); // Both(formattedEmail, formattedPhone)

Chaining Transformations

Chaining operations over a These requires careful attention to what should happen to coexisting values.

chainFirst passes the first value to the next step, leaving Second unchanged. When the input is a Both variant, the coexisting second value is dropped, and the pipeline yields whatever the next step returns:

const lookupEmailMetaData = (email: string): These<EmailMeta, PhoneNumber> =>
  These.make.first(fetchMetadata(email));

pipe(
  These.make.both("alice@example.com", "+15550199"),
  These.chainFirst(lookupEmailMetaData),
); // First(EmailMeta) — phone number is discarded

If you need the second value to survive the chain, you must use pure maps rather than monadic chains.

chainSecond performs the symmetric operation, chaining over the second value while leaving First unchanged:

const validatePhone = (phone: string): These<EmailAddress, PhoneMeta> => ...

Extracting Values

When you reach the boundary of your pipeline, you must unpack These into standard TypeScript primitives.

Exhaustive matching with `match` and `fold`

match requires you to handle all three possible variants explicitly, ensuring that coexisting values are never accidentally lost:

const notificationTarget = pipe(
  contactDetails,
  These.match({
    first: (email) => `Send email to ${email}`,
    second: (phone) => `Send SMS to ${phone}`,
    both: (email, phone) => `Send email to ${email} and SMS to ${phone}`,
  }),
);

For positional callbacks, fold provides an un-named positional mapping alternative.

Safe fallbacks with `getFirstOrElse` and `getSecondOrElse`

If you only want to extract one side of the container and provide a fallback if it is absent:

// Extract the email (available in First or Both), or fallback
pipe(These.make.second(phone), These.getFirstOrElse(() => defaultEmail)); // defaultEmail

// Extract the phone (available in Second or Both), or fallback
pipe(These.make.first(email), These.getSecondOrElse(() => defaultPhone)); // defaultPhone

Direct Inspection: Type Guards

To check which variant is active without unpacking the full structure, These provides several type guards:

These.is.first(value);  // true if First only
These.is.second(value); // true if Second only
These.is.both(value);   // true if Both

These.hasFirst(value);  // true if First or Both
These.hasSecond(value); // true if Second or Both

Utilities

Flipping roles: swap

swap reverses the first and second values of the container:

These.swap(These.make.first(email));         // Second(email)
These.swap(These.make.both(email, phone));   // Both(phone, email)

Peeking with tap

tap allows you to execute a side-effectful callback on the first value of a First or Both container, leaving the original These unchanged:

pipe(
  These.make.both(email, phone),
  These.tap((e) => console.log(`Sending system check to ${e}`)),
);

Problems it solves

Two-way offline and remote synchronization: When synchronizing records between local offline stores (such as SQLite or IndexedDB) and a remote server, changes may exist exclusively locally (new offline drafts), exclusively remotely (cloud updates), or concurrently on both sides (merge conflicts). These models inclusive three-way states (This, That, Both) without ambiguous nullable flags.
Partial success with non-fatal warnings: In batch processing and API transformations, an operation often successfully parses a payload while also encountering non-fatal warnings or recoverable format issues. These allows functions to return both the valid payload and the collected warnings, avoiding the need to either fail the entire operation or discard diagnostic details.
Reconciling diff patches with custom strategies: When calculating database differences between two snapshot versions, These.fold and These.match handle additions (This), deletions (That), and modifications (Both) with clean, case-specific logic.
Multi-channel communication delivery: In notification systems where alerts can be dispatched via Email, SMS, or both channels simultaneously, These models valid communication options and tracks per-channel delivery statuses cleanly.