@backloghq/opslog 0.7.1 → 0.8.0

package/README.md

@@ -140,6 +140,18 @@ store.stats()                     // { activeRecords, opsCount, archiveSegments
 await store.refresh()             // Reload from all agent WALs (multi-writer only)
 ```
 
+### Blob Storage (via StorageBackend)
+
+```typescript
+await backend.writeBlob("data/file.jsonl", buffer);  // Write at relative path
+const buf = await backend.readBlob("data/file.jsonl"); // Read full file
+const range = await backend.readBlobRange("data/file.jsonl", 1024, 256); // Byte-range read
+const names = await backend.listBlobs("data");         // List files under prefix
+await backend.deleteBlob("data/file.jsonl");            // Delete file
+```
+
+`readBlobRange` enables O(1) point lookups in JSONL record stores — seek to byte offset, read exact length. FsBackend uses `fs.read` with file offset. S3Backend uses HTTP Range header.
+
 ## Options
 
 ```typescript

package/dist/backend.d.ts

@@ -29,6 +29,7 @@ export declare class FsBackend implements StorageBackend {
     getManifestVersion(): Promise<string | null>;
     writeBlob(relativePath: string, content: Buffer): Promise<void>;
     readBlob(relativePath: string): Promise<Buffer>;
+    readBlobRange(relativePath: string, offset: number, length: number): Promise<Buffer>;
     listBlobs(prefix: string): Promise<string[]>;
     deleteBlob(relativePath: string): Promise<void>;
     deleteBlobDir(prefix: string): Promise<void>;

package/dist/backend.js

@@ -140,6 +140,21 @@ export class FsBackend {
     async readBlob(relativePath) {
         return readFile(join(this.dir, relativePath));
     }
+    async readBlobRange(relativePath, offset, length) {
+        if (offset < 0 || length < 0)
+            throw new Error("readBlobRange: offset and length must be non-negative");
+        if (length === 0)
+            return Buffer.alloc(0);
+        const fd = await open(join(this.dir, relativePath), "r");
+        try {
+            const buf = Buffer.alloc(length);
+            const { bytesRead } = await fd.read(buf, 0, length, offset);
+            return bytesRead < length ? buf.subarray(0, bytesRead) : buf;
+        }
+        finally {
+            await fd.close();
+        }
+    }
     async listBlobs(prefix) {
         try {
             return await readdir(join(this.dir, prefix));

package/dist/types.d.ts

@@ -115,6 +115,8 @@ export interface StorageBackend {
     writeBlob(relativePath: string, content: Buffer): Promise<void>;
     /** Read a blob from a relative path. */
     readBlob(relativePath: string): Promise<Buffer>;
+    /** Read a byte range from a blob. For O(1) point lookups in record stores. */
+    readBlobRange(relativePath: string, offset: number, length: number): Promise<Buffer>;
     /** List blob names under a prefix directory. */
     listBlobs(prefix: string): Promise<string[]>;
     /** Delete a single blob. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backloghq/opslog",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Embedded event-sourced document store. Append-only operation log with immutable snapshots, zero native dependencies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",