@drawnagency/primitives 0.1.114 → 0.1.116

package/src/storage/types.ts

@@ -34,16 +34,29 @@ export interface StorageProvider {
     options?: { baseVersion?: string | null },
   ): Promise<{ version: string }>;
 
+  // `draft` reads the draft branch by name: null when there is no draft — a
+  // caller that wants "draft, else main" falls back itself. `at` reads as of a
+  // commit and wins over `draft`. Two reads by branch name can see two different
+  // commits moments after a write, so a read that must agree with another read
+  // (an index and the listing it is diffed against) pins both to one commit.
   readFile(
     path: string,
-    options?: { draft?: boolean },
+    options?: { draft?: boolean; at?: string },
   ): Promise<Uint8Array | null>;
 
   promoteDraft(): Promise<{ version: string }>;
 
+  /** The published branch's head. Never a valid `baseVersion`. */
   getVersion(): Promise<string>;
 
-  listDirectory(path: string, options?: { draft?: boolean }): Promise<string[]>;
+  /**
+   * The draft branch's head, or null when no draft exists — exactly the value
+   * `writeFiles` accepts as `baseVersion`.
+   */
+  getDraftVersion(): Promise<string | null>;
+
+  /** File basenames directly under `path` (no subdirectories); `[]` when absent. Same options as `readFile`. */
+  listDirectory(path: string, options?: { draft?: boolean; at?: string }): Promise<string[]>;
 
   /**
    * Find a recent commit on the draft branch whose message carries the given