Advanced TypeScript for Harness Builders
0d. Type Assertions & Non-Null Assertions
Escape hatches: when you know more about a value than TypeScript does.
Sometimes you know more than TypeScript about a value’s type. These are escape hatches.
as keyword (type assertion):
File: packages/ai/src/env-api-keys.ts L16
_existsSync = (m as typeof import("node:fs")).existsSync;
m is typed as unknown (from a dynamic import). We assert it’s the node:fs module because we know what we imported.
as unknown as T (double assertion for incompatible types):
File: packages/ai/src/providers/openai-codex-responses.ts L455
yield event as unknown as ResponseStreamEvent;
When types are too far apart for a direct assertion, go through unknown first. This is a smell — use sparingly.
! non-null assertion:
File: packages/ai/src/utils/event-stream.ts L39
yield this.queue.shift()!;
Array.shift() returns T | undefined. We checked this.queue.length > 0 on the line above, so we know it won’t be undefined. The ! tells TypeScript “trust me, this isn’t null/undefined.”
Rule of thumb: Prefer narrowing (chapter 0e) over assertions. Use ! only when you’ve provably checked the condition but TypeScript can’t see it.