@wovin/storage-fs

Local filesystem storage backend for wovin using LMDB (Lightning Memory-Mapped Database).

Persists wovin threads (applogs/blocks) to the local filesystem.

Features

• StorageConnector interface - Store CAR files in LMDB
• RetrievalConnector interface - Retrieve CAR files by CID
• Single file storage - Stores all blocks in one LMDB database file
• ACID transactions - Atomic writes via LMDB transactions
• Built on LMDB - Leverages Lightning Memory-Mapped Database for reliability

Installation

pnpm add @wovin/storage-fs

Usage

Basic Storage

import { LmdbConnector } from '@wovin/storage-fs'
import { makeCarBlob, encodeBlockOriginal } from '@wovin/core/ipfs'

// Initialize connector
const connector = await LmdbConnector.init('./data/wovin-storage')

// Create and store a block
const testData = { hello: 'world', ts: Date.now() }
const block = await encodeBlockOriginal(testData)
const carBlob = await makeCarBlob(block.cid, [block])

// Store the CAR file
const rootCid = await connector.storeCar(carBlob)
console.log('Stored with CID:', rootCid.toString())

// Verify block exists
console.log('Block exists:', connector.has(rootCid))

// Retrieve the block
const retrievedBytes = connector.get(rootCid)

// Retrieve as CAR
const car = await connector.retrieveCar(rootCid)

// Clean up
connector.close()

Thread Snapshots

import { LmdbConnector } from '@wovin/storage-fs'
import { makeCarBlob, encodeBlock } from '@wovin/core/ipfs'
import { ThreadInMemory } from '@wovin/core/thread'

const connector = await LmdbConnector.init('./data/wovin-storage')

// Create applogs
const applogs = [
  { ag: 'alice', en: 'thread-123', at: 'text', vl: 'Hello' },
  { ag: 'alice', en: 'thread-123', at: 'text', vl: 'World' },
]

// Encode as blocks
const blocks = applogs.map(applog => encodeBlock(applog))

// Create thread snapshot CAR
const snapshotRoot = blocks[0]
const snapshotCar = await makeCarBlob(snapshotRoot.cid, blocks)

// Store thread snapshot
const snapshotCid = await connector.storeCar(snapshotCar)

// Later: retrieve and restore thread
const retrievedCar = await connector.retrieveCar(snapshotCid)
// Use CarReader to decode applogs...

connector.close()

API

LmdbConnector.init(path: string): Promise<LmdbConnector>

Initialize the connector with an LMDB database at the specified path.

Parameters:

• path - Filesystem path where LMDB data will be stored

Returns: Promise resolving to LmdbConnector instance

storeCar(car: Blob): Promise<CID>

Store a CAR (Content Addressable aRchive) file. Extracts all blocks and stores them individually in LMDB.

Parameters:

• car - CAR file as Blob

Returns: Promise resolving to the root CID

retrieveCar(cid: CID): Promise<CarReader>

Retrieve a CAR file by CID. Reconstructs the CAR from stored blocks.

Parameters:

• cid - The CID to retrieve

Returns: Promise resolving to CarReader

get(cid: CID): Uint8Array | undefined

Get a single block's bytes by CID.

Parameters:

• cid - The CID to retrieve

Returns: Block bytes or undefined if not found

has(cid: CID): boolean

Check if a block exists in the store.

Parameters:

• cid - The CID to check

Returns: boolean

close(): void

Close the LMDB database and clean up resources.

Storage Backend: LMDB

This package uses lmdb-js as the storage backend:

• Memory-mapped - OS-level memory mapping for efficient data access
• ACID - Atomic, consistent, isolated, durable transactions
• Single file - Stores entire database in one file
• Cross-process - Shared memory allows multiple processes to access simultaneously
• Compression - Optional compression for small values

When to Use

• ✅ Local development environments
• ✅ Desktop/Electron apps
• ✅ Node.js servers with persistent storage
• ✅ Testing and integration tests
• ✅ Offline-first applications

When NOT to Use

• ❌ Browser/WASM environments (use @wovin/connect-web3storage instead)
• ❌ Cloud-only deployments (use @wovin/connect-nftstorage instead)
• ❌ Multi-machine clusters (use @wovin/connect-s3 instead)

Related Packages

• @wovin/core - Core wovin types and utilities
• @wovin/connect-nftstorage - Cloud storage via NFT.storage
• @wovin/connect-s3 - Cloud storage via AWS S3
• @wovin/connect-web3storage - Cloud storage via Web3.storage

License

Same as wovin monorepo