Add putByUniqueKey to ReadOnlyTabularStorage

src/storage/ReadOnlyTabularStorage.test.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, it } from "vitest";
+import { InMemoryTabularStorage } from "workglow";
+import { CikNamePrimaryKeyNames, CikNameSchema } from "./entity/CikNameSchema";
+import { ReadOnlyTabularStorage } from "./ReadOnlyTabularStorage";
+
+describe("ReadOnlyTabularStorage", () => {
+  it("putByUniqueKey writes nothing and reports an overwrite", async () => {
+    const inner = new InMemoryTabularStorage(CikNameSchema, CikNamePrimaryKeyNames, []);
+    await inner.put({ cik: 1, name: "Before" });
+    const readOnly = new ReadOnlyTabularStorage(inner);
+
+    const result = await readOnly.putByUniqueKey({ cik: 1, name: "After" }, ["cik"]);
+
+    expect(result).toEqual({ entity: { cik: 1, name: "After" }, inserted: false });
+    expect(await inner.get({ cik: 1 })).toEqual({ cik: 1, name: "Before" });
+    expect(await readOnly.size()).toBe(1);
+  });
+});

src/storage/ReadOnlyTabularStorage.ts

@@ -20,6 +20,7 @@ import type {
   TabularEventParameters,
   TabularSubscribeOptions,
   TypedArraySchemaOptions,
+  UniqueKeyPutResult,
 } from "workglow";
 
 /**
@@ -45,6 +46,18 @@ export class ReadOnlyTabularStorage<
     return _value as unknown as Entity;
   }
 
+  /**
+   * Reports an overwrite rather than an insert: `inserted: true` tells a caller
+   * nothing can be keyed by the row yet, so it would skip reading back rows that
+   * the underlying storage does hold.
+   */
+  async putByUniqueKey(
+    value: InsertType,
+    _uniqueKey: ReadonlyArray<keyof Entity>
+  ): Promise<UniqueKeyPutResult<Entity>> {
+    return { entity: value as unknown as Entity, inserted: false };
+  }
+
   async putBulk(values: InsertType[]): Promise<Entity[]> {
     return values as unknown as Entity[];
   }