Adapter Implementations
This section provides detailed documentation for each content adapter implementation available in the content system. Each adapter implements the common ContentAdapter interface while providing specialized functionality for specific storage mechanisms.
Adapter Categories
The available adapters are organized into several categories based on their environment compatibility and purpose:
Node.js Adapters
These adapters are designed to work in Node.js environments:
- [TODO]
Filesystem Adapter: Local filesystem storage with POSIX/Windows path support - [TODO]
Watcher Adapter: Enhanced filesystem adapter with file watching capabilities
Browser Adapters
These adapters are designed to work in browser environments:
- [TODO]
IndexedDB Adapter: Persistent browser storage using IndexedDB - [TODO]
LocalStorage Adapter: Simple key-value browser storage - [TODO]
ServiceWorker Adapter: Enhanced browser storage with offline capabilities
Common Adapters
These adapters work in any JavaScript environment:
- [TODO]
Memory Adapter: In-memory ephemeral content storage - [TODO]
HTTP Adapter: Remote content access via HTTP/HTTPS
Composite Adapters
These meta-adapters combine or enhance other adapters:
- [TODO]
Fallback Adapter: Chain of adapters with fallback behavior - [TODO]
Mirror Adapter: Replication across multiple adapters - [TODO]
Transform Adapter: Content transformation layer
Adapter Selection
The content system provides several ways to select appropriate adapters:
Manual Selection
Create specific adapters directly:
import { createFileSystemAdapter } from '@lib/content/adapters/node'
import { createMemoryAdapter } from '@lib/content/adapters/common'
// Node.js environment
const fsAdapter = createFileSystemAdapter({
basePath: '/content',
})
// Any environment
const memoryAdapter = createMemoryAdapter({
initialContent: {
'welcome.md': {
data: '# Welcome',
contentType: 'text/markdown',
metadata: {},
},
},
})Environment Detection
Use automatic environment detection:
import { createAdapter } from '@lib/content/adapters'
// Automatically selects appropriate adapter based on environment
const adapter = createAdapter({
detectEnvironment: true,
})URI Scheme Based
Select adapter based on URI scheme:
import { createContentStore } from '@lib/content'
const store = createContentStore({
adapters: {
file: createFileSystemAdapter({ basePath: '/content' }),
http: createHttpAdapter({ baseUrl: 'https://api.example.com' }),
memory: createMemoryAdapter(),
},
})
// Uses file: adapter
await store.read('file:///content/article.md')
// Uses http: adapter
await store.read('http://api.example.com/content/data.json')
// Uses memory: adapter
await store.read('memory:temp/draft.md')Common Features
While each adapter has unique characteristics, they share common features:
Event Emission
Most adapters emit events when content changes:
adapter.events.on('change', (uri, content, changeType) => {
console.log(`Content ${changeType}: ${uri}`)
})Resource Management
Adapters may hold resources that should be released:
// When done with adapter
await adapter.dispose()Content Watching
Many adapters support watching for content changes:
const unsubscribe = adapter.watch('**/*.md', (uri, content, changeType) => {
console.log(`Markdown file ${changeType}: ${uri}`)
})
// Later
unsubscribe()Implementation Considerations
When choosing or implementing adapters, consider:
- Environment compatibility: Ensure adapter works in target environment
- Performance characteristics: Consider read/write latency and concurrency
- Persistence requirements: Temporary vs. durable storage needs
- Offline capabilities: Required for disconnected operation
- Synchronization needs: Consider multiple client scenarios
- Security considerations: Authentication and authorization requirements
- Content size limitations: Maximum supported content size
Extending the Adapter System
Create custom adapters by implementing the ContentAdapter interface:
import { createAdapter } from '@lib/content/adapters'
const customAdapter = createAdapter({
read: async uri => {
// Custom read implementation
},
write: async (uri, content) => {
// Custom write implementation
},
delete: async uri => {
// Custom delete implementation
},
list: async pattern => {
// Custom list implementation
},
// Optional methods
watch: (pattern, callback) => {
// Custom watch implementation
return () => {
// Unsubscribe function
}
},
events: createEventEmitter(),
dispose: async () => {
// Resource cleanup
},
})