@backloghq/opslog 0.7.1 → 0.8.1

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/snapshot.js

@@ -27,9 +27,19 @@ export async function loadSnapshot(dir, relativePath) {
     // Detect format: JSONL (first line is header without "records" key) vs legacy JSON
     const firstNewline = content.indexOf("\n");
     const firstLine = firstNewline === -1 ? content : content.slice(0, firstNewline);
-    const parsed = JSON.parse(firstLine);
+    let parsed;
+    try {
+        parsed = JSON.parse(firstLine);
+    }
+    catch {
+        // First line isn't valid JSON (e.g., pretty-printed legacy JSON starts with "{")
+        // Fall back to parsing the full content as legacy JSON
+        const snapshot = validateSnapshot(JSON.parse(content));
+        const records = new Map(Object.entries(snapshot.records));
+        return { records, version: snapshot.version };
+    }
     if ("records" in parsed) {
-        // Legacy monolithic JSON format
+        // Legacy monolithic JSON format (single-line)
         const snapshot = validateSnapshot(parsed);
         const records = new Map(Object.entries(snapshot.records));
         return { records, version: snapshot.version };
@@ -58,7 +68,14 @@ export async function* streamSnapshotFile(dir, relativePath) {
     const content = await readFile(path, "utf-8");
     const firstNewline = content.indexOf("\n");
     const firstLine = firstNewline === -1 ? content : content.slice(0, firstNewline);
-    const parsed = JSON.parse(firstLine);
+    let parsed;
+    try {
+        parsed = JSON.parse(firstLine);
+    }
+    catch {
+        // Pretty-printed legacy JSON — first line isn't valid JSON
+        parsed = JSON.parse(content);
+    }
     if ("records" in parsed) {
         // Legacy JSON: must load all, then yield
         const snapshot = validateSnapshot(parsed);

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.1",
   "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",