Designing with states

Standard TypeScript models runtime conditions with untyped exceptions (throw), missing pointers (null/undefined), and raw promises (Promise). In multi-step pipelines, these primitives force defensive branching and obscure edge cases in type signatures.

---

Synchronous Data Containers

Absent Values: Maybe<A>

Accessing missing properties, dictionary keys, or query results yields undefined or null. Handling these with manual if guards interrupts linear pipeline composition.

Maybe<A> represents optionality as a discriminated union: Some<A> (value present) or None (empty). Subsequent mapping steps run only when a value exists:

import { Maybe, pipe } from "@pplnd/core";

const city = pipe(
  users.get(userId),                 // User | undefined
  Maybe.from.nullable,                // Maybe<User>
  Maybe.map((u) => u.address),       // Maybe<Address>
  Maybe.map((a) => a.city),          // Maybe<string>
  Maybe.getOrElse(() => "Unknown"),  // string
);

Typed Synchronous Failures: Result<E, A>

Functions can throw exceptions of type unknown at any statement without indicating the failure in their return type. Callers must either wrap calls in try/catch or risk unhandled runtime crashes.

Result<E, A> brings failure into the return type: Ok<A> for success or Err<E> for typed errors.

import { pipe, Result } from "@pplnd/core";

const parseId = (raw: string): Result<string, number> => {
  const n = Number(raw);
  return isNaN(n) ? Result.make.err("Input is not a valid number") : Result.make.ok(n);
};

const route = pipe(
  parseId(input),
  Result.map((id) => `/users/${id}`),
  Result.getOrElse(() => "/users/unknown"),
);

Accumulating Multiple Errors: Validation<E, A>

Result short-circuits on the first failure. While correct for sequential steps, this is counterproductive for form validation and schema parsing where users need a list of all invalid fields at once.

Validation<E, A> evaluates independent checks and accumulates all failures into a non-empty array (NonEmptyArr<E>):

import { Validation } from "@pplnd/core";

const validateName = (s: string): Validation<string, string> =>
  s.trim() ? Validation.make.passed(s.trim()) : Validation.make.failed("Name is required");

const validateAge = (n: number): Validation<string, number> =>
  n >= 0 ? Validation.make.passed(n) : Validation.make.failed("Age must be non-negative");

---

Asynchronous Execution and UI States

Lazy Infallible Blueprints: Task.Result<E, A>

Standard Promise<T> begins execution immediately upon instantiation and rejects with untyped errors.

Task.Result<E, A> is a zero-argument function that executes only when called and resolves to a Result<E, A>, guaranteeing the outer promise never rejects:

import { pipe, Task } from "@pplnd/core";

const fetchUser = (id: string): Task.Result<string, User> =>
  Task.Result.tryCatch(
    (signal) => fetch(`/users/${id}`, { signal }).then((r) => r.json()),
    { onError: (e) => `Network failure: ${e}` },
  );

const greeting = pipe(
  fetchUser("42"),
  Task.Result.map((user) => `Hello, ${user.name}`),
  Task.Result.getOrElse(() => "Welcome, guest"),
);

// Execution occurs on invocation; always resolves
const result = await greeting(); // "Hello, Alice"

Explicit UI Lifecycle States: RemoteData<E, A>

Modeling async request state with multiple boolean flags (isLoading, error, data) permits invalid combinations, such as displaying a stale error message while a new request is loading.

RemoteData<E, A> defines the four mutually exclusive states of an asynchronous operation:

import { RemoteData } from "@pplnd/core";

const renderUI = RemoteData.match({
  notAsked: () => renderPlaceholder(),
  loading:  () => renderSpinner(),
  failure:  (err) => renderError(err),
  success:  (user) => renderProfile(user),
});

---

Concurrency Strategies and Event Pipelines

Declarative Async Concurrency: Op<I, E, A>

Managing in-flight request cancellation, debouncing, and retries in UI components typically requires manual AbortController handles and state flags.

Op<I, E, A> separates the async task definition from its execution policy:

import { Op, Task } from "@pplnd/core";

// 1. Define the task once
const searchApi = Op.make((query: string) =>
  Task.Result.tryCatch(
    (signal) => fetch(`/api/search?q=${query}`, { signal }).then((r) => r.json()),
    { onError: (err) => `Search failed: ${err}` },
  )
);

// 2. Configure execution strategy (cancels previous request on new input)
const searchRunner = Op.interpret(searchApi, {
  strategy: "restartable",
  retry: { attempts: 2 },
});

Typed Event Sequences: EventBus<S>

Standard event emitters leave message payloads untyped, while complex reactive stream frameworks introduce heavy operators for basic event coordination.

EventBus<S> provides a type-safe event pipeline for matching event sequences and accumulating state over time:

import { EventBus } from "@pplnd/core";

type AppEvents = {
  login: { userId: string };
  logout: void;
};

const authBus = EventBus.make<AppEvents>();

// Subscribe to typed events
EventBus.subscribe(authBus, "login").tap(({ value }) => {
  console.log(`User logged in: ${value.userId}`);
});

Where to go next

The choosing guide turns these families into per-situation decisions, Reading the types explains how a container carries its channels, and the recipes build a feature from several modules at once.