No base class for ContentBlock

[zastrowm]

Overview

Add a base class for all content blocks to enable runtime type checking using instanceof checks. This will allow developers to easily determine if a value is any type of ContentBlock without needing to check against each individual block type.

Implementation Requirements

Technical Approach

Based on clarification discussion and repository analysis:

• Pattern: Abstract base class with type discriminator
• Naming: Use ContentBlockBase as the base class name, keep ContentBlock as the union type
• Backward Compatibility: MUST maintain - this is a non-breaking, additive change
• Files Affected: src/types/messages.ts, src/types/media.ts, test files, exports

Base Class Design

Create an abstract base class that all content blocks will extend:

/**
 * Base class for all content blocks.
 * Enables runtime type checking using instanceof.
 * 
 * @example
 * ```typescript
 * if (someValue instanceof ContentBlockBase) {
 *   // someValue is definitely a ContentBlock
 *   console.log(someValue.type)
 * }
 * ```
 */
export abstract class ContentBlockBase {
  /**
   * Discriminator for the content block type.
   * Each subclass defines this as a specific string literal.
   */
  abstract readonly type: string
}

Content Block Classes to Update

In src/types/messages.ts (7 classes):

• TextBlock
• ToolUseBlock
• ToolResultBlock
• ReasoningBlock
• CachePointBlock
• GuardContentBlock
• JsonBlock

In src/types/media.ts (3 classes):

• ImageBlock
• VideoBlock
• DocumentBlock

Each class MUST:

1. Extend ContentBlockBase
2. Keep existing readonly type = '{name}Block' as const (TypeScript allows const string literals for abstract string properties)
3. Maintain all existing properties and methods
4. Preserve existing constructor signatures

Example Implementation

// Before:
export class TextBlock implements TextBlockData {
  readonly type = 'textBlock' as const
  readonly text: string
  constructor(data: string) { this.text = data }
}

// After:
export class TextBlock extends ContentBlockBase implements TextBlockData {
  readonly type = 'textBlock' as const  // Still works with abstract type: string
  readonly text: string
  constructor(data: string) { 
    super()
    this.text = data 
  }
}

Type Union (No Changes)

The existing ContentBlock type union MUST remain unchanged for backward compatibility:

export type ContentBlock =
  | TextBlock
  | ToolUseBlock
  | ToolResultBlock
  | ReasoningBlock
  | CachePointBlock
  | GuardContentBlock
  | ImageBlock
  | VideoBlock
  | DocumentBlock

Export Updates

In src/index.ts, add export for the base class:

// Message classes
export {
  ContentBlockBase,  // NEW
  TextBlock,
  ToolUseBlock,
  // ... rest unchanged
} from './types/messages.js'

Testing Requirements

In src/types/__tests__/messages.test.ts:

• Add test suite for ContentBlockBase
• Test instanceof checks for each block type
• Verify type property is accessible
• Test that non-block objects fail instanceof check

In src/types/__tests__/media.test.ts:

• Test instanceof checks for media blocks
• Verify media blocks are instanceof ContentBlockBase

Example test:

describe('ContentBlockBase', () => {
  it('allows instanceof checks for TextBlock', () => {
    const block = new TextBlock('test')
    expect(block instanceof ContentBlockBase).toBe(true)
  })

  it('allows instanceof checks for all block types', () => {
    const blocks = [
      new TextBlock('test'),
      new ToolUseBlock({ name: 'tool', toolUseId: '1', input: {} }),
      new ImageBlock({ format: 'png', source: { bytes: new Uint8Array() } }),
      // ... etc for all block types
    ]
    
    blocks.forEach(block => {
      expect(block instanceof ContentBlockBase).toBe(true)
    })
  })

  it('rejects non-ContentBlock objects', () => {
    const notABlock = { type: 'something', data: 'test' }
    expect(notABlock instanceof ContentBlockBase).toBe(false)
  })
})

Documentation Requirements

• Add TSDoc documentation to ContentBlockBase class
• Include @example showing instanceof usage
• Document the relationship between ContentBlockBase and ContentBlock type union
• Update any existing documentation that references content block type checking patterns

Acceptance Criteria

• ContentBlockBase abstract class is created with abstract type property
• All 9 content block classes extend ContentBlockBase
• All existing tests pass (backward compatibility verified)
• New tests verify instanceof checks work for all block types
• ContentBlockBase is exported from main SDK entry point
• TSDoc documentation is complete with examples
• Type checking passes (npm run type-check)
• Linting passes (npm run lint)
• Test coverage maintained at 80%+
• No breaking changes to public API

Files to Modify

• src/types/messages.ts - Add base class, update 7 block classes
• src/types/media.ts - Update 3 media block classes to extend base
• src/types/__tests__/messages.test.ts - Add tests for instanceof checks
• src/types/__tests__/media.test.ts - Add tests for media block instanceof checks
• src/index.ts - Export ContentBlockBase

Technical Notes

• TypeScript allows a subclass with readonly type = 'textBlock' as const to satisfy an abstract type: string property
• This is a non-breaking change because it only adds functionality, doesn't remove or change existing APIs
• The ContentBlock type union remains the primary type for type annotations
• ContentBlockBase is used specifically for runtime instanceof checks

[zastrowm]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Context

I've analyzed the codebase and found the following:

Current State

• ContentBlock is currently a type union (not a class) defined in src/types/messages.ts:

  export type ContentBlock =
    | TextBlock
    | ToolUseBlock
    | ToolResultBlock
    | ReasoningBlock
    | CachePointBlock
    | GuardContentBlock
    | ImageBlock
    | VideoBlock
    | DocumentBlock

• All 9 block classes are independent with their own implementations
• Each class has a discriminator: readonly type = '{name}Block' as const
• Current pattern: Type discrimination using .type === 'textBlock' checks
• No existing instanceof checks found in the codebase
• ContentBlock is exported as a type from the main SDK entry point

Files Affected

• src/types/messages.ts - Main content block definitions (7 blocks)
• src/types/media.ts - Media block definitions (3 blocks: ImageBlock, VideoBlock, DocumentBlock)
• src/types/__tests__/messages.test.ts - Tests to update
• src/types/__tests__/media.test.ts - Tests to update
• src/index.ts - Export updates

---

Clarifying Questions

1. Use Case for instanceof

Current pattern uses discriminated unions with .type property checks (e.g., block.type === 'textBlock').

• What specific use case requires instanceof checks over the existing .type property pattern?
• Is this for external consumers who prefer class-based type checking?
• Are there scenarios where the type discriminator is insufficient?

2. Implementation Approach

Should this be:

• Abstract base class that all blocks extend?
  • Pros: True instanceof support, can enforce common properties
  • Cons: Breaking change if blocks don't currently extend anything
• Interface that all blocks implement?
  • Pros: Can be non-breaking, TypeScript interfaces support instanceof via type guards
  • Cons: Runtime instanceof won't work (need custom type guard)
• Marker base class with minimal/no properties?

3. Naming Strategy

The name "ContentBlock" is currently used as a type union. Should we:

Option A: Keep ContentBlock as the type union, create new name for base

• Suggested names: BaseContentBlock, AbstractContentBlock, ContentBlockBase
• Non-breaking change
• Example: if (block instanceof BaseContentBlock)

Option B: Repurpose ContentBlock as the base class, rename type union

• Rename union to: ContentBlockTypes, AnyContentBlock, ContentBlockUnion
• Breaking change for consumers using the type union
• Example: if (block instanceof ContentBlock)

Your preference?

4. Base Class Properties

What should the base class include?

• Minimal (marker only for instanceof):

  abstract class BaseContentBlock {}

• With type property (existing common property):

  abstract class BaseContentBlock {
    abstract readonly type: string
  }

• Other common properties?

5. Breaking Change Tolerance

• Are breaking changes acceptable for this feature?
• Should we maintain backward compatibility?
• Target SDK version for this change?

6. Scope Confirmation

Based on my analysis, this is a small, focused change:

• Modify 2 source files (messages.ts, media.ts)
• Update 2 test files
• Update exports
• Add TSDoc documentation
• ~1-2 days of work including tests

Does this scope align with your expectations?

---

Please let me know your preferences on these questions, and I'll refine the task description accordingly.

[zastrowm]

/strands

Clarifying Questions

1. Use Case for instanceof

Current pattern uses discriminated unions with .type property checks (e.g., block.type === 'textBlock').

• What specific use case requires instanceof checks over the existing .type property pattern?
• Is this for external consumers who prefer class-based type checking?
• Are there scenarios where the type discriminator is insufficient?

We want to be check if something is a ContentBlock or not

2. Implementation Approach

Should this be:

• Abstract base class that all blocks extend?

  • Pros: True instanceof support, can enforce common properties
  • Cons: Breaking change if blocks don't currently extend anything

• Interface that all blocks implement?

  • Pros: Can be non-breaking, TypeScript interfaces support instanceof via type guards
  • Cons: Runtime instanceof won't work (need custom type guard)

• Marker base class with minimal/no properties?

Abstract class; we need to support instanceof

3. Naming Strategy

The name "ContentBlock" is currently used as a type union. Should we:

Option A: Keep ContentBlock as the type union, create new name for base

• Suggested names: BaseContentBlock, AbstractContentBlock, ContentBlockBase
• Non-breaking change
• Example: if (block instanceof BaseContentBlock)

Keep union type; use ContentBlockBase

Option B: Repurpose ContentBlock as the base class, rename type union

• Rename union to: ContentBlockTypes, AnyContentBlock, ContentBlockUnion
• Breaking change for consumers using the type union
• Example: if (block instanceof ContentBlock)

Your preference?

4. Base Class Properties

What should the base class include?

• Minimal (marker only for instanceof):
  abstract class BaseContentBlock {}
• With type property (existing common property):
  abstract class BaseContentBlock {
  abstract readonly type: string
  }
• Other common properties?

As long as subclasses can keep their type as constant strings, then with a type property

5. Breaking Change Tolerance

• Are breaking changes acceptable for this feature?
• Should we maintain backward compatibility?
• Target SDK version for this change?

Maintain backwards compatability

6. Scope Confirmation

Based on my analysis, this is a small, focused change:

• Modify 2 source files (messages.ts, media.ts)
• Update 2 test files
• Update exports
• Add TSDoc documentation
• ~1-2 days of work including tests

Does this scope align with your expectations?

Please let me know your preferences on these questions, and I'll refine the task description accordingly.

[github-actions]

Task Refinement Complete

Summary

I've completed the task refinement for issue #24. The issue is now ready for implementation.

What Was Accomplished

1. Repository Analysis

   • Identified all 9 content block classes across 2 files
   • Confirmed current pattern uses discriminated unions with .type property
   • Verified no breaking changes will occur

2. Clarification

   • Confirmed use case: runtime type checking with instanceof
   • Decided on implementation: abstract base class
   • Chose naming: ContentBlockBase (keeps ContentBlock union unchanged)
   • Specified base class should include abstract type: string property
   • Confirmed backward compatibility requirement

3. Task Description Updated

   • Added comprehensive implementation requirements
   • Included technical specifications and code examples
   • Defined all files to modify (2 source files, 2 test files, exports)
   • Specified acceptance criteria (10 checkpoints)
   • Documented testing requirements with example tests
   • Added technical notes about TypeScript compatibility

Implementation Summary

• Approach: Create abstract ContentBlockBase class with abstract type property
• Scope: Update 9 block classes to extend base class, add instanceof tests
• Breaking Changes: None - this is an additive, backward-compatible change
• Estimated Effort: 1-2 days including tests and documentation

Ready for Implementation

✅ The issue description now contains all necessary information for a developer to implement this feature without additional clarification.

The implementation will:

• Enable instanceof ContentBlockBase checks for runtime type detection
• Maintain full backward compatibility with existing code
• Follow existing SDK patterns and conventions
• Include comprehensive tests and documentation