storage

@xnetjs/storage

Storage adapters and blob persistence for xNet.

Installation

pnpm add @xnetjs/storage

Features

• SQLite adapter -- Cross-platform blob storage via @xnetjs/sqlite
• Memory adapter -- In-memory blob storage for tests and local flows
• Blob store -- Content-addressed binary storage
• Chunk manager -- Chunk and reassemble large payloads
• Batch writer -- Buffered blob writes for higher throughput

Usage

SQLite Storage (Recommended)

import { SQLiteStorageAdapter } from '@xnetjs/storage'
import { createMemorySQLiteAdapter } from '@xnetjs/sqlite/memory'

// Create SQLite adapter (use appropriate adapter for platform)
const sqliteDb = await createMemorySQLiteAdapter()
const storage = new SQLiteStorageAdapter(sqliteDb)

await storage.open()

// Blob operations
await storage.setBlob(cid, bytes)
const loaded = await storage.getBlob(cid)
const exists = await storage.hasBlob(cid)

Platform-Specific SQLite Adapters

// Electron (better-sqlite3)
import { createElectronSQLiteAdapter } from '@xnetjs/sqlite/electron'
const db = await createElectronSQLiteAdapter({ path: 'xnet.db' })

// Web (sqlite-wasm + OPFS)
import { createWebSQLiteAdapter } from '@xnetjs/sqlite/web'
const db = await createWebSQLiteAdapter({ path: 'xnet.db' })

// Expo (expo-sqlite)
import { createExpoSQLiteAdapter } from '@xnetjs/sqlite/expo'
const db = await createExpoSQLiteAdapter({ path: 'xnet.db' })

Telemetry Integration

Storage adapters support optional telemetry for tracking read/write operations and performance:

import { SQLiteStorageAdapter } from '@xnetjs/storage'
import { TelemetryCollector, ConsentManager } from '@xnetjs/telemetry'

const consent = new ConsentManager()
const telemetry = new TelemetryCollector({ consent })

const storage = new SQLiteStorageAdapter(sqliteDb, {
  telemetry // <-- Add telemetry collector
})

// Same for MemoryAdapter
const memoryStorage = new MemoryAdapter({ telemetry })

When telemetry is enabled, storage adapters automatically report:

• Performance metrics: storage.getBlob, storage.setBlob, storage.hasBlob
• Usage metrics: storage.read, storage.write
• Crash reports: All errors with context

All telemetry respects user consent settings and privacy buckets.

Memory Adapter

import { MemoryAdapter } from '@xnetjs/storage'

const storage = new MemoryAdapter()
await storage.open()

await storage.setBlob(cid, bytes)
const loaded = await storage.getBlob(cid)

import { BlobStore } from '@xnetjs/storage'

// Store and retrieve binary data
const blobStore = new BlobStore(adapter)
const blobId = await blobStore.put(data)
const blob = await blobStore.get(blobId)

import { ChunkManager } from '@xnetjs/storage'

// Chunked storage for large files
const chunks = new ChunkManager(adapter)
await chunks.store(fileId, largeBuffer)
const restored = await chunks.retrieve(fileId)

Adapters

Adapter	Platform	Backing store	Status
SQLiteStorageAdapter	All	SQLite	Recommended
MemoryAdapter	Any	In-memory Map	Lightweight

Modules

Module	Description
adapters/sqlite.ts	SQLite-backed storage adapter
adapters/memory.ts	In-memory storage adapter
adapters/batch-writer.ts	Buffered write utilities
blob-store.ts	Content-addressed blob storage
chunk-manager.ts	Chunked large-file storage
types.ts	Storage adapter interfaces

Dependencies

• @xnetjs/core -- Core types
• @xnetjs/crypto -- Content hashing
• @xnetjs/sqlite -- SQLite adapters (for SQLiteStorageAdapter)

Testing

pnpm --filter @xnetjs/storage test