@backloghq/opslog 0.5.0 → 0.5.1

package/README.md

@@ -134,7 +134,7 @@ await store.open(dir, {
   version: 1,                     // Schema version
   migrate: (record, fromVersion) => record, // Migration function
   readOnly: false,                // Open in read-only mode (default: false)
-  writeMode: "immediate",         // "immediate" (default) or "group" (buffered, ~12x faster)
+  writeMode: "immediate",         // "immediate" (default), "group" (~12x faster), or "async" (~50x faster, lossy on crash)
   groupCommitSize: 50,            // Group: flush after N ops (default: 50)
   groupCommitMs: 100,             // Group: flush after N ms (default: 100)
   agentId: "agent-A",             // Enable multi-writer mode (optional)
@@ -165,9 +165,34 @@ await store.flush();
 await store.close();
 ```
 
-**Safety:** Forced to `"immediate"` when `agentId` is set (multi-writer mode). Other agents can't see buffered ops, so group commit is single-writer only.
+### Async Mode
 
-**Tradeoff:** A crash can lose ops that haven't been flushed yet (up to `groupCommitMs` milliseconds of data). Use `"immediate"` (default) when every write must be durable.
+For maximum write throughput, use `writeMode: "async"`. Writes resolve immediately after buffering in memory — no disk I/O on the hot path. ~50x faster than immediate mode.
+
+```typescript
+const store = new Store();
+await store.open("./data", {
+  writeMode: "async",
+  groupCommitSize: 50,
+  groupCommitMs: 100,
+});
+
+await store.set("a", valueA);  // Returns instantly — buffered in memory
+await store.set("b", valueB);  // Same
+
+// Ensure durability before exit
+await store.sync();
+await store.close();
+```
+
+**Crash semantics:** Data buffered since the last flush is **lost** on unclean shutdown. Call `sync()` before process exit for durability. `close()` always flushes.
+
+**Safety:** Forced to `"immediate"` when `agentId` is set (multi-writer mode). Other agents can't see buffered ops, so group/async commit is single-writer only.
+
+**When to use which mode:**
+- `"immediate"` (default) — every write is durable. Use when data loss is unacceptable.
+- `"group"` — writes are batched but caller still waits for flush. ~12x faster. Crash loses up to `groupCommitMs` ms of data.
+- `"async"` — writes return instantly. ~50x faster. Crash loses all unflushed data. Best for high-throughput, latency-sensitive, crash-tolerant workloads.
 
 ## Multi-Writer Mode
 

package/dist/store.d.ts

@@ -18,6 +18,7 @@ export declare class Store<T = Record<string, unknown>> {
     private agentId?;
     private clock;
     private groupCommit;
+    private asyncMode;
     private groupBuffer;
     private groupSize;
     private groupMs;
@@ -93,8 +94,18 @@ export declare class Store<T = Record<string, unknown>> {
     private applyOp;
     private reverseOp;
     private persistOp;
-    /** Flush buffered group commit ops to disk in a single write. */
+    /**
+     * Flush buffered ops to disk in a single write.
+     * In group/async mode: drains the in-memory buffer to disk.
+     * Safe to call at any time. No-op if nothing is buffered.
+     */
     flush(): Promise<void>;
+    /**
+     * Ensure all buffered operations are durably persisted to disk.
+     * Alias for flush(). Use before process exit when using async write mode
+     * to prevent data loss.
+     */
+    sync(): Promise<void>;
     private flushGroupBuffer;
     private defaultPeriod;
 }

package/dist/store.js

@@ -29,6 +29,7 @@ export class Store {
     clock = null;
     // Group commit state
     groupCommit = false;
+    asyncMode = false;
     groupBuffer = [];
     groupSize = 50;
     groupMs = 100;
@@ -58,13 +59,14 @@ export class Store {
                 this.backend = backend;
             if (agentId)
                 this.agentId = agentId;
-            // Group commit: enabled when writeMode is "group" AND not multi-writer
-            if (writeMode === "group") {
+            // Group/async commit: enabled when writeMode is "group"/"async" AND not multi-writer
+            if (writeMode === "group" || writeMode === "async") {
                 if (agentId) {
-                    console.error("opslog: writeMode 'group' is not compatible with multi-writer (agentId). Using 'immediate'.");
+                    console.error(`opslog: writeMode '${writeMode}' is not compatible with multi-writer (agentId). Using 'immediate'.`);
                 }
                 else {
                     this.groupCommit = true;
+                    this.asyncMode = writeMode === "async";
                     if (groupCommitSize)
                         this.groupSize = groupCommitSize;
                     if (groupCommitMs)
@@ -687,13 +689,22 @@ export class Store {
             // Buffer the op, flush when buffer is full or timer fires
             this.groupBuffer.push(op);
             if (this.groupBuffer.length >= this.groupSize) {
-                await this.flushGroupBuffer();
+                if (this.asyncMode) {
+                    // Async: trigger flush in background, don't await
+                    this.serialize(() => this.flushGroupBuffer()).catch(() => { });
+                }
+                else {
+                    await this.flushGroupBuffer();
+                }
             }
             else if (!this.groupTimer) {
                 this.groupTimer = setTimeout(() => {
                     this.serialize(() => this.flushGroupBuffer()).catch(() => { });
                 }, this.groupMs);
             }
+            // Async mode: return immediately without waiting for disk I/O
+            if (this.asyncMode)
+                return;
         }
         else {
             // Immediate: write to disk now
@@ -703,12 +714,24 @@ export class Store {
             await this._compact();
         }
     }
-    /** Flush buffered group commit ops to disk in a single write. */
+    /**
+     * Flush buffered ops to disk in a single write.
+     * In group/async mode: drains the in-memory buffer to disk.
+     * Safe to call at any time. No-op if nothing is buffered.
+     */
     async flush() {
         if (!this.groupCommit || this.groupBuffer.length === 0)
             return;
         return this.serialize(() => this.flushGroupBuffer());
     }
+    /**
+     * Ensure all buffered operations are durably persisted to disk.
+     * Alias for flush(). Use before process exit when using async write mode
+     * to prevent data loss.
+     */
+    async sync() {
+        return this.flush();
+    }
     async flushGroupBuffer() {
         if (this.groupBuffer.length === 0)
             return;

package/dist/types.d.ts

@@ -58,8 +58,8 @@ export interface StoreOptions {
     backend?: StorageBackend;
     /** Agent ID for multi-writer mode. Enables per-agent WAL streams and LWW conflict resolution. */
     agentId?: string;
-    /** Write mode: "immediate" flushes every op (default, safe for multi-writer). "group" buffers ops and flushes periodically (~50x faster writes). Forced to "immediate" when agentId is set. */
-    writeMode?: "immediate" | "group";
+    /** Write mode: "immediate" flushes every op (default, safe for multi-writer). "group" buffers ops and flushes periodically (~12x faster writes). "async" buffers ops and resolves immediately without waiting for flush (~50x faster, data lost on crash). Forced to "immediate" when agentId is set. */
+    writeMode?: "immediate" | "group" | "async";
     /** Group commit: max ops to buffer before flush (default: 50). Only used when writeMode is "group". */
     groupCommitSize?: number;
     /** Group commit: max milliseconds before flush (default: 100). Only used when writeMode is "group". */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backloghq/opslog",
-  "version": "0.5.0",
+  "version": "0.5.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",