Content Adapters Reference

Content adapters provide the storage layer for the content system, abstracting different storage mechanisms behind a common interface. This reference documents the adapter system, its core interfaces, and available implementations.

Adapter System Overview

The adapter system follows these core principles:

1. Common Interface: All adapters implement the same ContentAdapter interface
2. Storage Abstraction: Each adapter abstracts a specific storage mechanism
3. URI-Based Addressing: Content is identified by URIs across all adapters
4. Environment Awareness: Adapters are selected based on the runtime environment
5. Factory Pattern: Adapters are created through factory functions

Adapter Selection

The content system automatically selects appropriate adapters based on:

• Runtime environment (Node.js vs. browser)
• URI scheme (file:, http:, memory:, etc.)
• Configuration options
• Feature requirements

Core Adapter Types

The content system includes several categories of adapters:

Environment-Specific Adapters

• Node.js Adapters: Designed for server environments
  • FileSystemAdapter: Local filesystem storage
  • WatcherAdapter: Filesystem watching capabilities
• Browser Adapters: Designed for client environments
  • IndexedDBAdapter: Persistent browser storage
  • LocalStorageAdapter: Simple key-value browser storage
  • ServiceWorkerAdapter: Offline-capable browser storage

Environment-Agnostic Adapters

• Common Adapters: Work in any environment
  • MemoryAdapter: In-memory content storage
  • HttpAdapter: Remote content via HTTP/HTTPS
  • CacheAdapter: Content caching layer

Special-Purpose Adapters

• Composite Adapters: Combine multiple adapters
  • FallbackAdapter: Try primary adapter, fall back to secondary
  • MirrorAdapter: Write to multiple adapters simultaneously
• Transformation Adapters: Modify content during operations
  • TransformAdapter: Apply transformations during read/write
  • ValidationAdapter: Validate content during operations

Adapter Factory System

Adapters are created using factory functions:

import { createAdapter, createFileSystemAdapter } from '@lib/content/adapters'

// Generic adapter creation
const adapter = createAdapter({
  read: async uri => {
    /* ... */
  },
  write: async (uri, content) => {
    /* ... */
  },
  delete: async uri => {
    /* ... */
  },
  list: async pattern => {
    /* ... */
  },
  // Optional methods
  watch: (pattern, callback) => {
    /* ... */
  },
  exists: async uri => {
    /* ... */
  },
})

// Specific adapter creation
const fsAdapter = createFileSystemAdapter({
  basePath: '/content',
  caseSensitive: true,
})

Adapter Interface

All adapters implement the ContentAdapter interface:

interface ContentAdapter {
  // Required methods
  read(uri: string, options?: ReadOptions): Promise<Content>
  write(uri: string, content: Content, options?: WriteOptions): Promise<void>
  delete(uri: string, options?: DeleteOptions): Promise<void>
  list(pattern?: string, options?: ListOptions): Promise<string[]>

  // Optional methods
  watch?(
    pattern: string,
    callback: WatchCallback,
    options?: WatchOptions
  ): Unsubscribe
  exists?(uri: string, options?: ExistsOptions): Promise<boolean>

  // Resources
  events?: EventEmitter
  dispose?(): Promise<void>
}

Adapter Metadata

Adapters expose metadata about their capabilities:

interface AdapterMetadata {
  id: string
  name: string
  description?: string
  schemes: string[]

  capabilities: {
    read: boolean
    write: boolean
    delete: boolean
    list: boolean
    watch: boolean
    exists: boolean
    transactions: boolean
  }

  performance: {
    readLatency: 'low' | 'medium' | 'high'
    writeLatency: 'low' | 'medium' | 'high'
    concurrency: number
  }

  constraints: {
    maxContentSize?: number
    supportedContentTypes?: string[]
    requiresAuthentication?: boolean
    maxConcurrentOperations?: number
  }
}

Adapter Error Handling

Adapters throw standardized error types:

• ContentNotFoundError: Content not found at the specified URI
• ContentAccessError: Permission or access issues
• ContentValidationError: Content failed validation
• ContentOperationError: Generic operation failures
• ContentAdapterError: Adapter-specific issues

Related Sections

• Content Adapter API Documentation
• URI System Concepts
• Adapter Implementation Guides