Result Type Pattern

How BlindCast uses Result discriminated unions instead of thrown exceptions. Covers the three main consumption patterns with TypeScript narrowing examples.

Every fallible operation in BlindCast returns Result<T, E> — a discriminated union — instead of throwing exceptions. This makes error handling explicit, type-safe, and impossible to accidentally ignore.

The CLI is the exception — it uses Unix exit codes instead of Result types. See CLI Error Codes.

The type

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

• When ok is true, value holds the success payload.
• When ok is false, error holds the typed error.

TypeScript narrows the type automatically based on the ok check.

Why not throw?

BlindCast uses Result in the player, uploader, and internal packages for these reasons:

1. Errors are part of the API contract. A function’s return type documents what can go wrong — callers can’t miss it.
2. No unexpected try/catch. You won’t accidentally swallow a crypto error in a generic catch block.
3. TypeScript narrowing works naturally. After if (!result.ok), TypeScript knows result.error is typed and result.value is not accessible.
4. Compatible with async/await. Result composes cleanly with Promise<Result<T, E>> — no need to mix try/catch with await.

Pattern 1: Early return

The simplest pattern — bail out immediately on failure:

import { createPlayer } from "@blindcast/player"

const result = createPlayer(videoEl, {
  keyServerUrl: "https://keys.example.com/keys",
})

if (!result.ok) {
  console.error("Player creation failed:", result.error.code)
  return
}

const player = result.value // TypeScript knows this is BlindcastPlayer here
player.load(manifestUrl)

Pattern 2: Switch on error code

When different errors need different handling:

import { createPlayer } from "@blindcast/player"
import type { PlayerErrorCode } from "@blindcast/player"

const result = createPlayer(videoEl, { keyServerUrl })

if (!result.ok) {
  switch (result.error.code as PlayerErrorCode) {
    case "UNSUPPORTED_BROWSER":
      showFallbackMessage("Your browser does not support encrypted video")
      break
    case "INVALID_VIDEO_ELEMENT":
      console.error("Bug: video element not found in DOM")
      break
    case "KEY_FETCH_FAILED":
      showRetryButton()
      break
    default:
      console.error("Unexpected error:", result.error.code, result.error.message)
  }
  return
}

const player = result.value

Pattern 3: Unwrap helper

If you prefer to throw in contexts where any error is fatal (e.g., scripts, tests):

function unwrap<T, E extends { code: string; message: string }>(
  result: { ok: true; value: T } | { ok: false; error: E },
  context?: string,
): T {
  if (!result.ok) {
    throw new Error(`${context ? context + ": " : ""}${result.error.code} — ${result.error.message}`)
  }
  return result.value
}

// Usage
const player = unwrap(createPlayer(videoEl, opts), "createPlayer")

Where you’ll encounter Result types

Deliverable	Uses Result?	Error type
Player	Yes	PlayerError with PlayerErrorCode
Uploader	Yes	UploaderError with UploaderErrorCode
CLI	No — uses exit codes	See CLI exit codes
Key Server Docker	No — uses HTTP status codes	400, 401, 403, 500
Crypto (internal)	Yes	CryptoError with CryptoErrorCode

TypeScript tips

Never access .value without checking .ok first

// TypeScript will error — value might not exist
const key = result.value

// Narrow first
if (result.ok) {
  const key = result.value // CryptoKey
}

The error type varies per deliverable

Each library defines its own error type with a specific code union:

import type { PlayerError, PlayerErrorCode } from "@blindcast/player"
import type { UploaderError, UploaderErrorCode } from "@blindcast/uploader"

All error types share the shape { code: ErrorCode; message: string }. PlayerError additionally has an optional cause?: unknown field for wrapping underlying hls.js errors.