@wovin/storage-fs 0.0.17 → 0.0.18

package/README.md

@@ -0,0 +1,170 @@
+# @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
+
+```bash
+pnpm add @wovin/storage-fs
+```
+
+## Usage
+
+### Basic Storage
+
+```typescript
+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
+
+```typescript
+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](https://github.com/kriszyp/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) - Core wovin types and utilities
+- [`@wovin/connect-nftstorage`](../connect-nftstorage) - Cloud storage via NFT.storage
+- [`@wovin/connect-s3`](../connect-s3) - Cloud storage via AWS S3
+- [`@wovin/connect-web3storage`](../connect-web3storage) - Cloud storage via Web3.storage
+
+## License
+
+Same as wovin monorepo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wovin/storage-fs",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "type": "module",
   "main": "./dist/index.min.js",
   "module": "./dist/index.min.js",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@ipld/car": "^5.2.6",
-    "@wovin/core": "0.0.17",
+    "@wovin/core": "0.0.18",
     "besonders-logger": "1.0.1",
     "lmdb": "^3.0.0",
     "multiformats": "^13.0.1"