Result Type Pattern

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:

Errors are part of the API contract. A function’s return type documents what can go wrong — callers can’t miss it.
No unexpected try/catch. You won’t accidentally swallow a crypto error in a generic catch block.
TypeScript narrowing works naturally. After if (!result.ok), TypeScript knows result.error is typed and result.value is not accessible.
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.

Introduction

Getting Started

Server

Player

CLI

Uploader

Key Server

Serverless

Going to Production

Reference

Result Type Pattern

The type

Why not throw?

Pattern 1: Early return

Pattern 2: Switch on error code

Pattern 3: Unwrap helper

Where you’ll encounter Result types

TypeScript tips

Never access `.value` without checking `.ok` first

The error type varies per deliverable

​The type

​Why not throw?

​Pattern 1: Early return

​Pattern 2: Switch on error code

​Pattern 3: Unwrap helper

​Where you’ll encounter Result types

​TypeScript tips

​Never access .value without checking .ok first

​The error type varies per deliverable

The type

Why not throw?

Pattern 1: Early return

Pattern 2: Switch on error code

Pattern 3: Unwrap helper

Where you’ll encounter Result types

TypeScript tips

Never access `.value` without checking `.ok` first

The error type varies per deliverable