API Reference

This section provides detailed documentation for the core APIs of the ReX content system.

Overview

The API reference documents the public interfaces, functions, and classes that make up the content system. It serves as the definitive reference for developers working with the system.

Core APIs

The content system exposes several key APIs:

• Content Store: High-level API for content operations
• Content Adapter: Storage-specific implementations
• Content Registry: Management of multiple content stores
• [TODO] Plugin API: Extensibility mechanisms
• [TODO] Utilities: Helper functions and utilities

API Design Principles

The APIs follow several important design principles:

1. Simplicity: Core interfaces are kept minimal and focused
2. Composability: APIs are designed to be composed together
3. Promise-based: Asynchronous operations use Promises
4. Type Safety: Strong TypeScript typings throughout
5. Environment Agnostic: Core APIs work in any JavaScript environment
6. Progressive Enhancement: Optional capabilities are exposed as needed

API Versioning

The content system follows semantic versioning:

• Major versions: Breaking API changes
• Minor versions: New features without breaking changes
• Patch versions: Bug fixes and non-breaking improvements

API compatibility notes are included in the documentation for each function or class.

Default Exports

The main package exports the most commonly used APIs:

// Core store creation
import { createContentStore } from '@lib/content'

// Core adapter creation
import { createAdapter } from '@lib/content/adapters'

// Middleware composition
import { pipe } from '@lib/content/middleware'

Importing Specific APIs

For more specific APIs, you can import from submodules:

// Adapter implementations
import { createMemoryAdapter } from '@lib/content/adapters/common'
import { createFileSystemAdapter } from '@lib/content/adapters/node'
import { createIndexedDBAdapter } from '@lib/content/adapters/browser'

// Middleware implementations
import {
  withValidation,
  withLogging,
  withCaching,
} from '@lib/content/middleware'

// Content processing
import { extractFrontmatter, transformMarkdown } from '@lib/content/processors'

Environment Support

The APIs adapt to different environments:

• Node.js: Full support, including filesystem operations
• Browser: Full support, with browser-specific adapters
• Service Worker: Support for offline-capable applications
• React Native: Limited support (requires custom adapters)

Error Handling

All APIs follow a consistent error handling pattern:

try {
  await store.read('path/to/content.md')
} catch (error) {
  if (error instanceof ContentNotFoundError) {
    // Handle not found errors
  } else if (error instanceof ContentAccessError) {
    // Handle access errors
  } else {
    // Handle other errors
  }
}

API Stability

APIs are marked with stability indicators:

• Stable: Well-tested, unlikely to change
• Experimental: May change in future versions
• Deprecated: Will be removed in a future version

Related Documentation

• Type Reference
• Content Model
• Implementation Patterns