Guard narrowing doesn't override class getters (guild: Guild | null)

[UniquePixels]

Problem

The inCachedGuild guard promises type narrowing via GuildInteraction<T> = T & { guild: Guild; ... }, but TypeScript's intersection types cannot override class getters. When BaseInteraction defines get guild(): Guild | null, the intersection & { guild: Guild } doesn't narrow the return type — TypeScript resolves the getter's declared return type from the class, not the intersection member.

This means in spark actions, interaction.guild is still Guild | null even after the guard has validated it at runtime:

export const ping = defineCommand({
  command: builder,
  guards: [g.inCachedGuild],
  action: async (interaction) => {
    interaction.guild; // Still Guild | null — TS doesn't narrow getters via intersection
  },
});

This affects guild, member, guildId, and channel — all defined as getters on BaseInteraction.

Why discord.js <'cached'> doesn't help here

discord.js solves this at the class level with Interaction<'cached'> where guild is typed as Guild (non-null) via CacheTypeReducer. However, the guard system's NarrowedBy type utility is fundamentally intersection-based (TBase & TOut). Switching to discord.js's generic parameter approach would require rethinking NarrowedBy with conditional type mapping — a deep architectural change that doesn't compose well with the current guard system.

Proposed fix

Add a typed accessor helper to in-cached-guild.ts that bridges the gap:

/** Extracts the guaranteed-non-null guild from a guard-narrowed interaction. */
export function guildFrom(interaction: GuildInteraction): Guild {
  return interaction.guild as Guild;
}

Usage

import * as g from '@/guards/built-in';

export const ping = defineCommand({
  command: builder,
  guards: [g.inCachedGuild],
  action: async (interaction) => {
    const guild = g.guildFrom(interaction);
    // guild: Guild — no null, no assertion
    await interaction.reply(`Server: ${guild.name}`);
  },
});

The function signature constrains the input to GuildInteraction, so it can't be called without the guard in the chain — TypeScript errors if inCachedGuild is missing from the guards array.

Scope

• Add guildFrom() helper to in-cached-guild.ts
• Consider similar helpers for member and channel if needed (memberFrom, channelFrom)
• Export from @/guards/built-in barrel
• Update docs/guards.md with the pattern
• Add tests

Root cause

This is a TypeScript language limitation, not a bug in the guard system. See TypeScript#33014 for background on intersection types not narrowing accessors/getters.

[coderabbitai]

Coding Plan

Summary

• Add guildFrom and memberFrom helpers to in-cached-guild.ts for extracting non-null guild and member from GuildInteraction
• Add channelFrom helper to in-text-channel.ts for extracting non-null channel from TextChannelInteraction (semantically correct placement)
• Create dedicated test files following established patterns with minimal mock objects
• Document the pattern in docs/guards.md with clear explanation of the TypeScript limitation being addressed

Design Choices

Design Choice 1: Where should `channelFrom` be defined given channel nullability semantics?

Options Considered:

1. Place channelFrom in in-cached-guild.ts accepting GuildInteraction with nullable return
2. Place channelFrom in in-text-channel.ts accepting TextChannelInteraction with non-null return
3. Skip channelFrom entirely since it requires a different guard

Chosen Option: 2

Rationale: Placing channelFrom in in-text-channel.ts maintains semantic correctness—the helper accepts TextChannelInteraction and returns the guaranteed non-null channel, consistent with the guard's purpose and matching how guildFrom/memberFrom work with GuildInteraction.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Helper Functions

Add the three accessor helpers to their semantically appropriate guard files, following the established pattern of co-locating helpers with their associated types.

Task 1: Add `guildFrom` and `memberFrom` helpers to in-cached-guild.ts

Add two helper functions that extract the guaranteed non-null guild and member from a GuildInteraction, bridging the TypeScript intersection type limitation.

• Add guildFrom(interaction: GuildInteraction): Guild function that returns interaction.guild with type assertion
• Add memberFrom(interaction: GuildInteraction): GuildMember function that returns interaction.member with type assertion
• Include JSDoc comments explaining the purpose (workaround for TS getter limitation) and that the guard constraint enforces compile-time safety
• Place functions after the inCachedGuild guard definition, before the file ends

Task 2: Add `channelFrom` helper to in-text-channel.ts

Add a helper function that extracts the guaranteed non-null channel from a TextChannelInteraction.

• Add channelFrom(interaction: TextChannelInteraction): GuildBasedChannel & TextBasedChannel function
• Include JSDoc explaining this requires inTextChannel guard (not just inCachedGuild) since channel is only guaranteed non-null after that guard
• Place function after the inTextChannel guard definition

Task 3: Update barrel exports

Export all new helper functions from the guards barrel file.

• Update src/guards/built-in/index.ts to export guildFrom and memberFrom from ./in-cached-guild
• Update same file to export channelFrom from ./in-text-channel

🤖 Prompt for AI agents

Add typed accessor helper functions to their respective guard files and update
the barrel exports. The goal is to provide type-safe access to properties that
TypeScript's intersection types cannot narrow due to class getter semantics.

**`src/guards/built-in/in-cached-guild.ts`**
- After the `inCachedGuild` guard definition, add two exported helper functions:
- `guildFrom(interaction: GuildInteraction): Guild` — returns
`interaction.guild` with a type assertion
- `memberFrom(interaction: GuildInteraction): GuildMember` — returns
`interaction.member` with a type assertion
- Add JSDoc comments to each function explaining:
  - They are a workaround for the TypeScript getter/intersection-type limitation
  - The guard constraint enforces compile-time safety

**`src/guards/built-in/in-text-channel.ts`**
- After the `inTextChannel` guard definition, add one exported helper function:
- `channelFrom(interaction: TextChannelInteraction): GuildBasedChannel &
TextBasedChannel` — returns the channel with a type assertion
- Add JSDoc explaining that this helper requires the `inTextChannel` guard (not
just `inCachedGuild`), since `channel` is only guaranteed non-null after that
guard

**`src/guards/built-in/index.ts`**
- Export `guildFrom` and `memberFrom` from `./in-cached-guild`
- Export `channelFrom` from `./in-text-channel`

Phase 2: Add Tests

Create dedicated test files for the new helper functions following the established pattern of per-guard test files for complex functionality.

Task 1: Create tests for guildFrom and memberFrom

Add a dedicated test file for the in-cached-guild helpers following patterns from has-channel.test.ts.

• Create src/guards/built-in/in-cached-guild.test.ts
• Add local mock helper function to create minimal GuildInteraction objects with mock guild and member
• Add describe('guildFrom', ...) block with test verifying it returns the guild object from the interaction
• Add describe('memberFrom', ...) block with test verifying it returns the member object from the interaction
• Use minimal mock objects cast via as unknown as Type pattern consistent with other guard tests

Task 2: Create tests for channelFrom

Add tests for the channelFrom helper, either in existing in-text-channel tests in index.test.ts or a dedicated file.

• Check if inTextChannel tests exist in index.test.ts—if so, add channelFrom tests there; otherwise create in-text-channel.test.ts
• Add describe('channelFrom', ...) block with test verifying it returns the channel object from a TextChannelInteraction
• Use minimal mock objects following established patterns

🤖 Prompt for AI agents

Create dedicated test files for the new helper functions, following the
established patterns from `has-channel.test.ts` and other guard test files.

**`src/guards/built-in/in-cached-guild.test.ts`** (new file)
- Add a local mock helper function that creates minimal `GuildInteraction`
objects with mock `guild` and `member` properties, using the `as unknown as
Type` cast pattern
- Add a `describe('guildFrom', ...)` block with a test verifying the function
returns the guild object from the interaction
- Add a `describe('memberFrom', ...)` block with a test verifying the function
returns the member object from the interaction

**`channelFrom` tests**
- First check whether `inTextChannel` tests already exist in `index.test.ts`
  - If yes, add a `describe('channelFrom', ...)` block there
- If no, create `src/guards/built-in/in-text-channel.test.ts` and add the block
there
- The `describe('channelFrom', ...)` block should contain a test verifying the
function returns the channel object from a `TextChannelInteraction`
- Use minimal mock objects following the `as unknown as Type` pattern consistent
with other guard tests

Phase 3: Update Documentation

Document the new helper functions and the pattern for working around TypeScript's getter limitation.

Task 1: Add accessor helpers section to guards.md

Document the new pattern in the guards documentation with clear explanation of when and why to use these helpers.

• Add new section "Accessor Helpers" after the "Built-in Guards" section (around line 494)
• Explain the TypeScript limitation: intersection types cannot narrow class getters
• Document guildFrom(interaction), memberFrom(interaction), channelFrom(interaction) with signatures
• Include usage example showing the pattern within a defineCommand action
• Note which guard each helper requires (inCachedGuild for guild/member, inTextChannel for channel)
• Keep consistent with existing documentation style (code blocks, explanation paragraphs)

Task 2: Update API reference table

Add the new helpers to the API reference section at the end of guards.md.

• Add entries to the "Built-in Guards" quick reference table (around line 820)
• Include helper name, required input type, and return type for each

🤖 Prompt for AI agents

Update `docs/guards.md` to document the new accessor helper functions and the
TypeScript limitation they address.

**New "Accessor Helpers" section** (insert after the "Built-in Guards" section,
around line 494)
- Explain the TypeScript limitation: intersection types cannot narrow class
getters
- Document each helper with its signature:
  - `guildFrom(interaction)` — requires `inCachedGuild` guard
  - `memberFrom(interaction)` — requires `inCachedGuild` guard
  - `channelFrom(interaction)` — requires `inTextChannel` guard
- Include a usage example showing the pattern within a `defineCommand` action
- Note which guard each helper requires
- Match the existing documentation style (explanation paragraphs followed by
code blocks)

**API reference table** (around line 820)
- Add entries to the "Built-in Guards" quick reference table for each new helper
- Each entry should include: helper name, required input type, and return type

Research

The guards system lives in src/guards/built-in/ with individual guard files exporting both guard functions and associated types. The in-cached-guild.ts file defines GuildInteraction<T> which guarantees guild, guildId, and member are non-null, while channel remains nullable. The in-text-channel.ts file defines TextChannelInteraction<T> which additionally guarantees channel is non-null. Helper functions like resolveChannelFromGuard in has-channel.ts demonstrate the pattern for exporting utility functions alongside guards. All exports flow through index.ts barrel, and documentation lives in docs/guards.md.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Add typed accessor helper functions to their respective guard files and update
the barrel exports. The goal is to provide type-safe access to properties that
TypeScript's intersection types cannot narrow due to class getter semantics.

**`src/guards/built-in/in-cached-guild.ts`**
- After the `inCachedGuild` guard definition, add two exported helper functions:
- `guildFrom(interaction: GuildInteraction): Guild` — returns
`interaction.guild` with a type assertion
- `memberFrom(interaction: GuildInteraction): GuildMember` — returns
`interaction.member` with a type assertion
- Add JSDoc comments to each function explaining:
  - They are a workaround for the TypeScript getter/intersection-type limitation
  - The guard constraint enforces compile-time safety

**`src/guards/built-in/in-text-channel.ts`**
- After the `inTextChannel` guard definition, add one exported helper function:
- `channelFrom(interaction: TextChannelInteraction): GuildBasedChannel &
TextBasedChannel` — returns the channel with a type assertion
- Add JSDoc explaining that this helper requires the `inTextChannel` guard (not
just `inCachedGuild`), since `channel` is only guaranteed non-null after that
guard

**`src/guards/built-in/index.ts`**
- Export `guildFrom` and `memberFrom` from `./in-cached-guild`
- Export `channelFrom` from `./in-text-channel`
===============================================================================

Task: 2

Create dedicated test files for the new helper functions, following the
established patterns from `has-channel.test.ts` and other guard test files.

**`src/guards/built-in/in-cached-guild.test.ts`** (new file)
- Add a local mock helper function that creates minimal `GuildInteraction`
objects with mock `guild` and `member` properties, using the `as unknown as
Type` cast pattern
- Add a `describe('guildFrom', ...)` block with a test verifying the function
returns the guild object from the interaction
- Add a `describe('memberFrom', ...)` block with a test verifying the function
returns the member object from the interaction

**`channelFrom` tests**
- First check whether `inTextChannel` tests already exist in `index.test.ts`
  - If yes, add a `describe('channelFrom', ...)` block there
- If no, create `src/guards/built-in/in-text-channel.test.ts` and add the block
there
- The `describe('channelFrom', ...)` block should contain a test verifying the
function returns the channel object from a `TextChannelInteraction`
- Use minimal mock objects following the `as unknown as Type` pattern consistent
with other guard tests
===============================================================================

Task: 3

Update `docs/guards.md` to document the new accessor helper functions and the
TypeScript limitation they address.

**New "Accessor Helpers" section** (insert after the "Built-in Guards" section,
around line 494)
- Explain the TypeScript limitation: intersection types cannot narrow class
getters
- Document each helper with its signature:
  - `guildFrom(interaction)` — requires `inCachedGuild` guard
  - `memberFrom(interaction)` — requires `inCachedGuild` guard
  - `channelFrom(interaction)` — requires `inTextChannel` guard
- Include a usage example showing the pattern within a `defineCommand` action
- Note which guard each helper requires
- Match the existing documentation style (explanation paragraphs followed by
code blocks)

**API reference table** (around line 820)
- Add entries to the "Built-in Guards" quick reference table for each new helper
- Each entry should include: helper name, required input type, and return type

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!