Key vs Value Optional

If you're working with TypeScript and large language models (LLMs), there's a crucial distinction you need to understand: the difference between key optional andvalue optional properties. This seemingly small detail can make or break your application's reliability, especially when dealing with telemetry, logging, or any data that needs to flow through multiple function calls.

The Problem: When Optional Goes Wrong

Let's start with a real-world example. Imagine you have a module that handles telemetry tracing - think OpenTelemetry where you need to pass trace IDs through your application to track what happens across different functions.

❌ The problematic approach

// This looks innocent, but it's a trap!
type Context = {
  traceId?: string; // Key optional - can be omitted entirely
};

function main(ctx: Context) {
  // Uh oh - we're not passing traceId down!
  doThing({}); // No telemetry data flows through
  doAnotherThing({}); // Still no telemetry data
}

function doThing(ctx: Context) {
  // This function might fail, but we won't know why
  // because traceId was omitted and we have no telemetry
}

function doAnotherThing(ctx: Context) {
  // Same problem here
}

The issue here is subtle but critical. In production, when main is called with a traceId, that valuable telemetry data gets lost because the internal functions don't receive it. If doThing or doAnotherThing fail, you'll have no trace of what went wrong.

Understanding the Two Approaches

type Context = {
  traceId?: string;
}

// Can be called like:
someFunction({})
someFunction({ traceId: "abc123" })

type Context = {
  traceId: string | undefined;
}

// Must be called like:
someFunction({ traceId: undefined })
someFunction({ traceId: "abc123" })

The Solution: Value Optional for Data Flow

Here's how to fix our telemetry example using value optional types:

✅ The correct approach

type Context = {
  traceId: string | undefined; // Value optional - must be provided
};

function main(ctx: Context) {
  // Now we're forced to pass the traceId down
  doThing({ traceId: ctx.traceId });
  doAnotherThing({ traceId: ctx.traceId });
}

function doThing(ctx: Context) {
  // We can be confident that traceId was explicitly passed
  // Even if it's undefined, it was intentionally passed as undefined
  if (ctx.traceId) {
    // Add telemetry with the trace ID
    console.log(`Starting doThing with trace: ${ctx.traceId}`);
  }
}

function doAnotherThing(ctx: Context) {
  // Same confidence here
  if (ctx.traceId) {
    console.log(`Starting doAnotherThing with trace: ${ctx.traceId}`);
  }
}

With this approach, TypeScript forces us to explicitly pass the traceIdthrough each function call. Even if it's undefined, we know it was intentionally passed as undefined, not accidentally omitted.

When to Use Each Approach

The Hybrid Approach: Best of Both Worlds

In practice, you often want a clean public API (key optional) but reliable internal data flow (value optional). Here's how to achieve both:

🎯 Hybrid approach example

// Public API - clean and optional
type PublicContext = {
  traceId?: string;
};

// Internal API - explicit and required
type InternalContext = {
  traceId: string | undefined;
};

// Public entry point - key optional for clean API
export function main(ctx: PublicContext) {
  const internalCtx: InternalContext = {
    traceId: ctx.traceId ?? undefined
  };
  
  // Now internal functions get explicit values
  doThing(internalCtx);
  doAnotherThing(internalCtx);
}

// Internal functions - value optional for reliability
function doThing(ctx: InternalContext) {
  // We know traceId was explicitly considered
}

function doAnotherThing(ctx: InternalContext) {
  // Same confidence here
}

This gives you a clean public interface while ensuring that internal data flow is explicit and reliable. Your users can call main() cleanly, but internally you have guarantees about data flow.

Practical Tips for Teams

Key Takeaways

Understanding this distinction will make your TypeScript code more reliable and help you avoid subtle bugs where important data gets lost in function calls. It's a small detail that makes a big difference in application reliability.