Type Reference

This section provides detailed documentation for the core type definitions used throughout the ReX content system.

Overview

The type system is designed around a consistent set of interfaces that enable the compositional architecture. These types define the contracts between different parts of the system, ensuring consistent behavior across implementations.

Type Categories

The type system is organized into the following categories:

Content Types

• Content Types: Core content representation interfaces
• Metadata Types: Content metadata structure and specialized fields

Operation Types

• Operation Types: Content operation interfaces and options
• Event Types: Event handling and observer patterns

Error Types

• Error Types: Error hierarchy and recovery options

Utility Types

• [TODO] Utility Types: Helper types and type utilities

Type Consistency

The type system follows several important principles:

1. Generic Data Representation: Content interfaces use generics to support different data types
2. Explicit Options: Operations accept explicit option objects rather than numerous parameters
3. Composition-Friendly: Types are designed to work with functional composition patterns
4. Environment-Agnostic: Core types don’t depend on specific runtime environments
5. Progressive Enhancement: Optional capabilities are expressed through optional properties

Using the Type System

Type Imports

The preferred way to import types is from the main module:

// Recommended
import type { Content, ContentMetadata } from '@lib/content'

// Avoid direct imports from internal paths
// Not recommended: import type { Content } from '@lib/content/types';

Type Extensions

When extending the core types, follow these patterns:

// Extending Content with specialized metadata
interface BlogPost extends Content<string> {
  metadata: ContentMetadata & {
    author: string
    publishDate: Date
    tags: string[]
  }
}

// Extending operation options
interface EnhancedReadOptions extends ContentReadOptions {
  includeReferences?: boolean
  resolveLinks?: boolean
}

Type Guards

The system provides type guards for checking content types:

import { isTextContent, isBinaryContent, isJsonContent } from '@lib/content'

function processContent(content: Content<unknown>) {
  if (isTextContent(content)) {
    // content is now typed as Content<string>
    return processText(content.data)
  }

  if (isBinaryContent(content)) {
    // content is now typed as Content<Uint8Array>
    return processBinary(content.data)
  }

  if (isJsonContent(content)) {
    // content is now typed as Content<object>
    return processJson(content.data)
  }

  throw new Error(`Unsupported content type: ${content.contentType}`)
}

Type Migration

The type system has evolved with the ADR-009 Unified Type System. When migrating older code:

1. Replace RawContent with Content<string>
2. Replace BinaryContent with Content<Uint8Array> or Content<Buffer>
3. Replace JsonContent with Content<object>
4. Ensure metadata follows the ContentMetadata interface
5. Update type guards to use the provided utility functions

Related Documentation

• ADR-009: Unified Type System
• Content Model
• API Reference