Adapter Types

This document provides comprehensive documentation of the type system for content adapters. These types define the interface and behavior of storage adapters in the content system.

Core Adapter Types

ContentAdapter

The fundamental interface that all storage adapters must implement:

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>
}

AdapterImplementation

Defines the core implementation methods for an adapter:

interface AdapterImplementation {
  read: ContentAdapter['read']
  write: ContentAdapter['write']
  delete: ContentAdapter['delete']
  list: ContentAdapter['list']
  watch?: ContentAdapter['watch']
  exists?: ContentAdapter['exists']
  events?: EventEmitter
  dispose?: ContentAdapter['dispose']
}

ContentAdapterFactory

A factory function type for creating adapter instances:

type ContentAdapterFactory<T extends ContentAdapter = ContentAdapter> = (
  options?: ContentAdapterOptions
) => T

Adapter Options

BaseAdapterOptions

Base options common to all adapters:

interface BaseAdapterOptions {
  // Base path for relative URIs
  basePath?: string

  // URI processing
  caseSensitive?: boolean
  defaultContentType?: string

  // Monitoring
  enableEvents?: boolean
  logging?: LoggingOptions

  // Environment
  detectEnvironment?: boolean

  // Performance
  concurrency?: number
  timeout?: number

  // Hooks
  beforeRead?: BeforeReadHook
  afterRead?: AfterReadHook
  beforeWrite?: BeforeWriteHook
  afterWrite?: AfterWriteHook
  beforeDelete?: BeforeDeleteHook
  afterDelete?: AfterDeleteHook

  // Extensions
  extensions?: Record<string, any>
}

ContentAdapterOptions

Generic options for content adapters:

interface ContentAdapterOptions extends BaseAdapterOptions {
  // Default is required when using the adapter directly
  defaultAdapter?: string | ContentAdapter

  // Validation
  validateContent?: boolean
  contentSchema?: ContentSchema

  // Authentication
  authentication?: {
    type: 'none' | 'basic' | 'bearer' | 'custom'
    credentials?: {
      username: string
      password: string
    }
    token?: string
    headerFactory?: () => Promise<Record<string, string>>
  }
}

EnvironmentSpecificOptions

FileSystemAdapterOptions

Options specific to filesystem adapters:

interface FileSystemAdapterOptions extends ContentAdapterOptions {
  basePath: string
  encoding?: string
  createMissingDirectories?: boolean
  followSymlinks?: boolean
  watchOptions?: {
    ignoreInitial?: boolean
    ignorePermissionErrors?: boolean
    interval?: number
  }
}

IndexedDBAdapterOptions

Options specific to IndexedDB adapters:

interface IndexedDBAdapterOptions extends ContentAdapterOptions {
  databaseName?: string
  storeName?: string
  version?: number
  upgradeCallback?: (
    db: IDBDatabase,
    oldVersion: number,
    newVersion: number
  ) => void
  useCompression?: boolean
  maxBatchSize?: number
}

HttpAdapterOptions

Options specific to HTTP adapters:

interface HttpAdapterOptions extends ContentAdapterOptions {
  baseUrl?: string
  headers?: Record<string, string>
  fetchOptions?: RequestInit
  retryOptions?: {
    maxRetries?: number
    retryDelay?: number
    retryStatusCodes?: number[]
  }
  cacheOptions?: {
    enabled?: boolean
    maxAge?: number
    maxItems?: number
  }
}

Operation Options

The adapter interface provides options for customizing operations:

ReadOptions

Options for read operations:

interface ReadOptions {
  // Format and transformation
  format?: string
  transformations?: ContentTransformation[]

  // Caching
  noCache?: boolean
  maxAge?: number

  // Version handling
  version?: string | number

  // Error handling
  failIfNotFound?: boolean

  // Authentication
  authentication?: AuthenticationOptions

  // Performance
  timeout?: number
  signal?: AbortSignal

  // Extensions
  [key: string]: any
}

WriteOptions

Options for write operations:

interface WriteOptions {
  // Creation
  createDirectories?: boolean
  failIfExists?: boolean

  // Update
  overwrite?: boolean

  // Versioning
  createVersion?: boolean
  versionId?: string

  // Metadata
  updateMetadata?: boolean
  mergeMetadata?: boolean

  // Validation
  validate?: boolean
  schema?: ContentSchema

  // Authentication
  authentication?: AuthenticationOptions

  // Performance
  timeout?: number
  signal?: AbortSignal

  // Extensions
  [key: string]: any
}

DeleteOptions

Options for delete operations:

interface DeleteOptions {
  // Delete behavior
  failIfNotFound?: boolean
  recursive?: boolean

  // Versioning
  softDelete?: boolean

  // Authentication
  authentication?: AuthenticationOptions

  // Performance
  timeout?: number
  signal?: AbortSignal

  // Extensions
  [key: string]: any
}

ListOptions

Options for list operations:

interface ListOptions {
  // Filtering
  recursive?: boolean
  depth?: number
  contentTypes?: string[]
  metadataFilter?: (metadata: ContentMetadata) => boolean

  // Sorting
  sortBy?: 'name' | 'createdAt' | 'updatedAt' | 'size'
  sortDirection?: 'asc' | 'desc'

  // Pagination
  limit?: number
  offset?: number

  // Performance
  timeout?: number
  signal?: AbortSignal

  // Extensions
  [key: string]: any
}

WatchOptions

Options for watch operations:

interface WatchOptions {
  // Watching behavior
  recursive?: boolean
  ignoreInitial?: boolean

  // Event filtering
  events?: ('create' | 'update' | 'delete')[]

  // Debouncing
  debounce?: number

  // Monitoring
  reportProgress?: boolean

  // Extensions
  [key: string]: any
}

Event Types

Types related to the adapter event system:

ContentChangeEvent

Represents a content change event:

interface ContentChangeEvent {
  uri: string
  content?: Content
  type: 'create' | 'update' | 'delete'
  timestamp: number
}

WatchCallback

Callback function for content watching:

type WatchCallback = (
  uri: string,
  content: Content | null,
  type: 'create' | 'update' | 'delete'
) => void

Unsubscribe

Function to stop watching for changes:

type Unsubscribe = () => void

Adapter Metadata

Types for adapter introspection:

AdapterCapabilities

Describes adapter capabilities:

interface AdapterCapabilities {
  read: boolean
  write: boolean
  delete: boolean
  list: boolean
  watch: boolean
  exists: boolean
  transactions: boolean
}

AdapterMetadata

Provides metadata about an adapter:

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

  capabilities: AdapterCapabilities

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

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

Hook Types

Hook functions for intercepting adapter operations:

type BeforeReadHook = (
  uri: string,
  options?: ReadOptions
) => Promise<void> | void
type AfterReadHook = (
  uri: string,
  content: Content,
  options?: ReadOptions
) => Promise<Content> | Content

type BeforeWriteHook = (
  uri: string,
  content: Content,
  options?: WriteOptions
) => Promise<Content> | Content
type AfterWriteHook = (
  uri: string,
  content: Content,
  options?: WriteOptions
) => Promise<void> | void

type BeforeDeleteHook = (
  uri: string,
  options?: DeleteOptions
) => Promise<void> | void
type AfterDeleteHook = (
  uri: string,
  options?: DeleteOptions
) => Promise<void> | void

Type Guards

Type guard functions for adapter functionality:

/**
 * Checks if an adapter supports content watching
 */
function isWatchableAdapter(
  adapter: ContentAdapter
): adapter is ContentAdapter & {
  watch: NonNullable<ContentAdapter['watch']>
}

/**
 * Checks if an adapter supports existence checking
 */
function supportsExists(adapter: ContentAdapter): adapter is ContentAdapter & {
  exists: NonNullable<ContentAdapter['exists']>
}

/**
 * Checks if an adapter has events
 */
function hasEvents(adapter: ContentAdapter): adapter is ContentAdapter & {
  events: NonNullable<ContentAdapter['events']>
}

/**
 * Checks if an adapter supports disposal
 */
function isDisposable(adapter: ContentAdapter): adapter is ContentAdapter & {
  dispose: NonNullable<ContentAdapter['dispose']>
}

Utility Types

Additional utility types for the adapter system:

/**
 * Represents an adapter factory registry
 */
interface AdapterFactoryRegistry {
  get(scheme: string): ContentAdapterFactory | undefined
  register(scheme: string, factory: ContentAdapterFactory): void
  unregister(scheme: string): void
  getSchemes(): string[]
}

/**
 * Represents a URI mapping function
 */
type UriMapper = (uri: string) => string

/**
 * Represents a content transformation function
 */
type ContentTransformer = (
  content: Content,
  uri: string
) => Promise<Content> | Content

Related Resources

• Content Types
• Operation Types
• Error Types
• Event Types