yaml-flow 8.6.4 → 8.7.1

package/examples/board-firestore/browser/board-runtime.js

@@ -0,0 +1,263 @@
+/**
+ * board-firestore/browser/board-runtime.js
+ *
+ * Shows how to instantiate the ServerRuntimeControlface IIFE in a browser
+ * backed by the Firebase JS SDK (v9 modular) instead of the Admin SDK.
+ *
+ * This file is NOT bundled — it is a plain ES module that your build tool
+ * (Vite, webpack, etc.) would process. Import it from your SPA's main entry.
+ *
+ * Architecture:
+ *   Browser <──Firestore JS SDK──> Cloud Firestore
+ *       │                                │
+ *       │  ServerRuntimeControlface      │
+ *       └── createSingleBoardServerRuntime() reads/writes Firestore directly
+ *
+ * The worker (server/worker.js) runs the queue lanes and can process AI card
+ * requests without exposing any service account credentials to the browser.
+ */
+
+import { initializeApp } from 'firebase/app';
+import {
+  getFirestore,
+  doc,
+  getDoc,
+  setDoc,
+  deleteDoc,
+  collection,
+  query,
+  where,
+  orderBy,
+  getDocs,
+} from 'firebase/firestore';
+
+// ── IMPORTANT: ServerRuntimeControlface is loaded as a browser IIFE ───────────
+// Add this to your HTML: <script src="/browser/server-runtime-controlface.js"></script>
+// Then window.ServerRuntimeControlface is available.
+const { createSingleBoardServerRuntime } = window.ServerRuntimeControlface;
+
+// ── Firebase config — replace with your project values ────────────────────────
+const firebaseConfig = {
+  apiKey: 'YOUR_API_KEY',
+  authDomain: 'YOUR_PROJECT.firebaseapp.com',
+  projectId: 'YOUR_PROJECT_ID',
+  storageBucket: 'YOUR_PROJECT.appspot.com',
+  appId: 'YOUR_APP_ID',
+};
+
+const app = initializeApp(firebaseConfig);
+const db = getFirestore(app);
+
+const BOARD_ID = 'default';
+
+// ── Browser-compatible base64url helpers ───────────────────────────────────────
+function encodeDocId(key) {
+  return btoa(encodeURIComponent(key).replace(/%([0-9A-F]{2})/g, (_, p1) => String.fromCharCode(parseInt(p1, 16))))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function makeRef(kind, value) {
+  const json = JSON.stringify({ kind, value });
+  const b64 = btoa(unescape(encodeURIComponent(json)))
+    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  return `b64:${b64}`;
+}
+
+// ── Minimal Firestore KV adapter for the browser (Firebase JS SDK) ─────────────
+function createBrowserKvStorage(colRef) {
+  return {
+    async read(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      if (!snap.exists()) return null;
+      return snap.data()?.value ?? null;
+    },
+    async write(key, value) {
+      await setDoc(doc(colRef, encodeDocId(key)), { k: key, value });
+    },
+    async delete(key) {
+      await deleteDoc(doc(colRef, encodeDocId(key)));
+    },
+    async listKeys(prefix = '') {
+      let q = colRef;
+      if (prefix) {
+        q = query(colRef, where('k', '>=', prefix), where('k', '<', prefix + '\uf8ff'), orderBy('k'));
+      } else {
+        q = query(colRef, orderBy('k'));
+      }
+      const snap = await getDocs(q);
+      return snap.docs.map((d) => d.data().k ?? d.id);
+    },
+  };
+}
+
+// ── Minimal Firestore blob adapter for the browser ────────────────────────────
+function createBrowserBlobStorage(colRef) {
+  return {
+    async read(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      if (!snap.exists()) return null;
+      return snap.data()?.content ?? null;
+    },
+    async write(key, content) {
+      await setDoc(doc(colRef, encodeDocId(key)), { k: key, content });
+    },
+    async exists(key) {
+      const snap = await getDoc(doc(colRef, encodeDocId(key)));
+      return snap.exists();
+    },
+    async remove(key) {
+      await deleteDoc(doc(colRef, encodeDocId(key)));
+    },
+    async listKeys(prefix = '') {
+      let q = prefix
+        ? query(colRef, where('k', '>=', prefix), where('k', '<', prefix + '\uf8ff'), orderBy('k'))
+        : query(colRef, orderBy('k'));
+      const snap = await getDocs(q);
+      return snap.docs.map((d) => d.data().k ?? d.id);
+    },
+  };
+}
+
+// ── Board platform adapter shim for browser use ────────────────────────────────
+// NOTE: The browser adapter is read-heavy (renders current card state) and
+// delegates writes to the worker. The runtime will route execution dispatch
+// to the worker via HTTP if you configure invocationAdapter with an http:post ref.
+function createBrowserFirestoreAdapter() {
+  const boardDoc = (name) => collection(db, 'boards', BOARD_ID, name);
+
+  return {
+    kvStorage: (namespace) => createBrowserKvStorage(boardDoc(`kv-${namespace || 'root'}`)),
+    kvStorageForRef: (ref) => createBrowserKvStorage(boardDoc('kv-root')),
+    blobStorage: (namespace) => createBrowserBlobStorage(boardDoc(`blobs-${namespace || 'root'}`)),
+    scratchStorage: () => ({
+      ...createBrowserBlobStorage(boardDoc('scratch')),
+      getUniqueKey: (prefix = 'scratch-') => `${prefix}${Date.now()}-${Math.random().toString(36).slice(2)}`,
+      create: async (data, prefix = 'scratch-') => {
+        const key = `${prefix}${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        await createBrowserBlobStorage(boardDoc('scratch')).write(key, data);
+        return key;
+      },
+      keyRef: (key) => ({ kind: 'firestore-blob', value: key }),
+      config: {
+        get: async (k) => {
+          const v = await createBrowserBlobStorage(boardDoc('scratch')).read(`__config__/${k}`);
+          if (v == null) return null;
+          try { return JSON.parse(v); } catch { return v; }
+        },
+        set: async (k, v) =>
+          createBrowserBlobStorage(boardDoc('scratch')).write(`__config__/${k}`, JSON.stringify(v)),
+      },
+    }),
+    scratchStorageForRef: () => ({ read: async () => null, write: async () => {}, exists: async () => false, remove: async () => {}, listKeys: async () => [], getUniqueKey: () => `${Date.now()}`, create: async () => `${Date.now()}`, keyRef: () => ({ kind: 'unknown', value: '' }), config: { get: async () => null, set: async () => {} } }),
+    journalStorage: () => ({
+      append: async (payload) => {
+        const id = `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`;
+        await setDoc(doc(db, 'boards', BOARD_ID, 'journal', id), { id, createdAt: new Date().toISOString(), payload });
+        return { id, payload };
+      },
+      readAll: async () => {
+        const snap = await getDocs(query(collection(db, 'boards', BOARD_ID, 'journal'), orderBy('id')));
+        return snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+      },
+      readAfter: async (cursor) => {
+        let q = cursor
+          ? query(collection(db, 'boards', BOARD_ID, 'journal'), where('id', '>', cursor), orderBy('id'))
+          : query(collection(db, 'boards', BOARD_ID, 'journal'), orderBy('id'));
+        const snap = await getDocs(q);
+        const entries = snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+        return { entries, newCursor: entries.at(-1)?.id ?? cursor };
+      },
+    }),
+    archiveFactory: () => ({
+      stream: (name) => ({
+        append: async (payload) => {
+          const id = `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`;
+          await setDoc(doc(db, 'boards', BOARD_ID, `archive-stream-${name}`, id), { id, createdAt: new Date().toISOString(), payload });
+          return { id, payload };
+        },
+        readAll: async () => {
+          const snap = await getDocs(query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), orderBy('id')));
+          return snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+        },
+        readAfter: async (cursor) => {
+          const q = cursor
+            ? query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), where('id', '>', cursor), orderBy('id'))
+            : query(collection(db, 'boards', BOARD_ID, `archive-stream-${name}`), orderBy('id'));
+          const snap = await getDocs(q);
+          const entries = snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+          return { entries, newCursor: entries.at(-1)?.id ?? cursor };
+        },
+      }),
+      blob: (name) => createBrowserBlobStorage(collection(db, 'boards', BOARD_ID, `archive-blob-${name}`)),
+      listStreams: async () => [],   // Not available in JS SDK — use Admin SDK or maintain an index
+      listBlobs: async () => [],
+      config: {
+        get: async (k) => { const s = await getDoc(doc(db, 'boards', BOARD_ID, 'archive-config', 'main')); return s.data()?.[k] ?? null; },
+        set: async (k, v) => setDoc(doc(db, 'boards', BOARD_ID, 'archive-config', 'main'), { [k]: v }, { merge: true }),
+      },
+    }),
+    archiveFactoryForRef: () => null,
+
+    // Queue storage: browser-side is read-only; the worker handles leasing
+    // Use null for browser-only apps; the worker processes queued tasks.
+    boardWorkerStore: () => null,
+    chatAgentStore: () => null,
+    processAccumulatedStore: () => null,
+
+    // Lock: no-op in browser (worker holds the real lock)
+    lock: { tryAcquire: async () => async () => {} },
+
+    hashFn: (value) => {
+      // Browser-safe hash (djb2 — for display only, not crypto security)
+      const str = JSON.stringify(value);
+      let hash = 5381;
+      for (let i = 0; i < str.length; i++) hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+      return (hash >>> 0).toString(16).padStart(8, '0');
+    },
+
+    genId: () => `${String(Date.now()).padStart(13, '0')}-${Math.random().toString(36).slice(2, 10)}`,
+
+    dispatchExecution: async (_ref, _args) => ({ dispatched: false, error: 'browser-only' }),
+  };
+}
+
+// ── Bootstrap the in-browser runtime ──────────────────────────────────────────
+export function createBoardRuntime() {
+  const boardAdapter = createBrowserFirestoreAdapter();
+
+  const runtime = createSingleBoardServerRuntime({
+    boardId: BOARD_ID,
+    boards: [
+      {
+        label: `Board — ${BOARD_ID}`,
+        boardAdapter,
+        baseRef: { kind: 'firestore', value: `boards/${BOARD_ID}` },
+        cardStoreRef: makeRef('firestore', `boards/${BOARD_ID}/cards`),
+        outputsStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime-out`),
+      },
+    ],
+    invocationAdapter: {
+      // Dispatch executions to the worker via HTTP
+      async invoke(ref, args) {
+        const workerUrl = window.__BOARD_WORKER_URL__ ?? 'http://localhost:7900';
+        const res = await fetch(`${workerUrl}/api/board/invoke`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ref, args }),
+        });
+        if (!res.ok) return { dispatched: false, error: `worker HTTP ${res.status}` };
+        return res.json();
+      },
+    },
+  });
+
+  return runtime;
+}
+
+// ── Usage example ──────────────────────────────────────────────────────────────
+// const runtime = createBoardRuntime();
+// const boardStatus = await runtime.handleRuntimeApi(fakeReq, fakeRes, url);
+//
+// Or call runtime methods directly:
+// await runtime.processAccumulatedLane();   // trigger a card computation pass
+// const cards = await runtime.cardStore?.list();  // read current card state

package/examples/board-firestore/firestore.indexes.json

@@ -0,0 +1,29 @@
+{
+  "indexes": [
+    {
+      "collectionGroup": "worker-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "chat-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    },
+    {
+      "collectionGroup": "process-queue",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "dead", "order": "ASCENDING" },
+        { "fieldPath": "visibleAfter", "order": "ASCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}

package/examples/board-firestore/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "board-firestore",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "worker": "node server/worker.js",
+    "agents": "node server/agents.js"
+  },
+  "dependencies": {
+    "firebase-admin": "^12.0.0",
+    "yaml-flow": "*"
+  }
+}

package/examples/board-firestore/server/adapters/firestore-archive-factory.js

@@ -0,0 +1,59 @@
+/**
+ * firestore-archive-factory.js
+ *
+ * AsyncArchiveFactory backed by Firestore.
+ * Each named stream is a subcollection: boards/{boardId}/archive-stream-{name}
+ * Each named blob collection: boards/{boardId}/archive-blob-{name}
+ *
+ * NOTE: listStreams / listBlobs use Admin SDK's listCollections() — not available
+ * in the browser Firestore JS SDK. In the browser, skip or maintain an index manually.
+ *
+ * @param {import('@google-cloud/firestore').Firestore} db
+ * @param {string} boardId
+ * @returns {import('yaml-flow/cloud-storage').AsyncArchiveFactory}
+ */
+
+import { createFirestoreJournalStorage } from './firestore-journal-storage.js';
+import { createFirestoreBlobStorage } from './firestore-blob-storage.js';
+
+export function createFirestoreArchiveFactory(db, boardId) {
+  const boardDoc = db.collection('boards').doc(boardId);
+
+  return {
+    stream(name) {
+      return createFirestoreJournalStorage(boardDoc.collection(`archive-stream-${name}`));
+    },
+
+    blob(name) {
+      return createFirestoreBlobStorage(boardDoc.collection(`archive-blob-${name}`));
+    },
+
+    async listStreams(prefix = '') {
+      const cols = await boardDoc.listCollections();
+      const tag = `archive-stream-${prefix}`;
+      return cols
+        .map((c) => c.id)
+        .filter((id) => id.startsWith(tag))
+        .map((id) => id.slice('archive-stream-'.length));
+    },
+
+    async listBlobs(prefix = '') {
+      const cols = await boardDoc.listCollections();
+      const tag = `archive-blob-${prefix}`;
+      return cols
+        .map((c) => c.id)
+        .filter((id) => id.startsWith(tag))
+        .map((id) => id.slice('archive-blob-'.length));
+    },
+
+    config: {
+      async get(k) {
+        const snap = await boardDoc.collection('archive-config').doc('main').get();
+        return snap.data()?.[k] ?? null;
+      },
+      async set(k, v) {
+        await boardDoc.collection('archive-config').doc('main').set({ [k]: v }, { merge: true });
+      },
+    },
+  };
+}

package/examples/board-firestore/server/adapters/firestore-blob-storage.js

@@ -0,0 +1,82 @@
+/**
+ * firestore-blob-storage.js
+ *
+ * AsyncBlobStorage backed by Firestore for text/small blobs.
+ * Document shape: { k, content, contentType?, bytesBase64? }
+ *
+ * Binary blobs (readBytes/writeBytes) are stored as base64-encoded strings.
+ * For production use with files > 1 MB, replace writeBytes/readBytes with
+ * Firebase Storage (Cloud Storage for Firebase) and store the GCS path here.
+ *
+ * @param {import('@google-cloud/firestore').CollectionReference} col
+ * @returns {import('yaml-flow/cloud-storage').AsyncBlobStorage}
+ */
+
+function encodeDocId(key) {
+  return Buffer.from(key).toString('base64url');
+}
+
+function decodeDocId(docId) {
+  return Buffer.from(docId, 'base64url').toString();
+}
+
+export function createFirestoreBlobStorage(col) {
+  return {
+    async read(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      return snap.data()?.content ?? null;
+    },
+
+    async write(key, content) {
+      await col.doc(encodeDocId(key)).set({ k: key, content });
+    },
+
+    async exists(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      return snap.exists;
+    },
+
+    async remove(key) {
+      await col.doc(encodeDocId(key)).delete();
+    },
+
+    async readBytes(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      const data = snap.data();
+      if (data?.bytesBase64) return Buffer.from(data.bytesBase64, 'base64');
+      if (data?.content) return Buffer.from(data.content);
+      return null;
+    },
+
+    async writeBytes(key, bytes) {
+      // NOTE: Firestore 1 MB doc limit. For larger files use Firebase Storage.
+      const bytesBase64 = Buffer.from(bytes).toString('base64');
+      await col.doc(encodeDocId(key)).set({ k: key, bytesBase64 });
+    },
+
+    async listKeys(prefix = '') {
+      let q = col;
+      if (prefix) {
+        q = col.where('k', '>=', prefix).where('k', '<', prefix + '\uf8ff');
+      }
+      const snap = await q.orderBy('k').get();
+      return snap.docs.map((d) => d.data().k ?? decodeDocId(d.id));
+    },
+
+    async stat(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      const data = snap.data();
+      const size = data?.bytesBase64
+        ? Math.floor((data.bytesBase64.length * 3) / 4)
+        : (data?.content?.length ?? 0);
+      return { key, size, contentType: data?.contentType ?? 'application/octet-stream' };
+    },
+
+    keyRef(key) {
+      return { kind: 'firestore-blob', value: `${col.path}/${encodeDocId(key)}` };
+    },
+  };
+}

package/examples/board-firestore/server/adapters/firestore-board-adapter.js

@@ -0,0 +1,127 @@
+/**
+ * firestore-board-adapter.js
+ *
+ * Composes all Firestore-backed storage primitives into an AsyncBoardPlatformAdapter
+ * using createHostedAsyncBoardPlatformAdapter from yaml-flow/cloud-storage.
+ *
+ * Firestore collection layout under boards/{boardId}/:
+ *   kv-{namespace}/          AsyncKVStorage per namespace
+ *   journal/                 single board journal
+ *   worker-queue/            board worker task queue
+ *   chat-queue/              chat agent dispatch queue
+ *   process-queue/           processAccumulated trigger queue
+ *   blobs-{namespace}/       AsyncBlobStorage per namespace
+ *   scratch/                 ephemeral scratch storage
+ *   archive-stream-{name}/   archive journal streams
+ *   archive-blob-{name}/     archive blob collections
+ *   archive-config/          archive config KV
+ *   locks/board-lock         AtomicRelayLock document
+ *
+ * @param {import('@google-cloud/firestore').Firestore} db
+ * @param {string} boardId
+ * @param {{ holderId?: string, requestProcessAccumulated?: () => void }} [options]
+ * @returns {import('yaml-flow/cloud-storage').AsyncBoardPlatformAdapter}
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { createHostedAsyncBoardPlatformAdapter } from 'yaml-flow/cloud-storage';
+
+import { createFirestoreKvStorage } from './firestore-kv-storage.js';
+import { createFirestoreJournalStorage } from './firestore-journal-storage.js';
+import { createFirestoreQueueStorage } from './firestore-queue-storage.js';
+import { createFirestoreBlobStorage } from './firestore-blob-storage.js';
+import { createFirestoreScratchStorage } from './firestore-scratch-storage.js';
+import { createFirestoreArchiveFactory } from './firestore-archive-factory.js';
+import { createFirestoreLock } from './firestore-lock.js';
+
+function parseKindValueRef(ref) {
+  const PREFIX = 'b64:';
+  if (!ref.startsWith(PREFIX)) return { kind: 'unknown', value: ref };
+  const b64 = ref.slice(PREFIX.length)
+    .replace(/-/g, '+').replace(/_/g, '/')
+    + '='.repeat((4 - (ref.length - PREFIX.length) % 4) % 4);
+  return JSON.parse(Buffer.from(b64, 'base64').toString());
+}
+
+function lexicalId() {
+  const ts = String(Date.now()).padStart(13, '0');
+  const rand = Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+  return `${ts}-${rand}`;
+}
+
+export function createFirestoreBoardAdapter(db, boardId, options = {}) {
+  const boardDoc = db.collection('boards').doc(boardId);
+
+  return createHostedAsyncBoardPlatformAdapter({
+    boardId,
+
+    // ── KV storage ────────────────────────────────────────────────────────
+    kvStorage(namespace) {
+      return createFirestoreKvStorage(boardDoc.collection(`kv-${namespace || 'root'}`));
+    },
+    kvStorageForRef(ref) {
+      const parsed = parseKindValueRef(ref);
+      // ref.value is treated as a full Firestore collection path when kind='firestore'
+      const col = parsed.kind === 'firestore'
+        ? db.collection(parsed.value)
+        : boardDoc.collection(`kv-ref-${Buffer.from(ref).toString('base64url').slice(0, 16)}`);
+      return createFirestoreKvStorage(col);
+    },
+
+    // ── Blob storage ──────────────────────────────────────────────────────
+    blobStorage(namespace) {
+      return createFirestoreBlobStorage(boardDoc.collection(`blobs-${namespace || 'root'}`));
+    },
+
+    // ── Scratch storage ───────────────────────────────────────────────────
+    scratchStorage() {
+      return createFirestoreScratchStorage(boardDoc.collection('scratch'));
+    },
+    scratchStorageForRef(ref) {
+      const parsed = parseKindValueRef(ref);
+      const col = parsed.kind === 'firestore'
+        ? db.collection(parsed.value)
+        : boardDoc.collection('scratch');
+      return createFirestoreScratchStorage(col);
+    },
+
+    // ── Archive factory ───────────────────────────────────────────────────
+    archiveFactory() {
+      return createFirestoreArchiveFactory(db, boardId);
+    },
+    archiveFactoryForRef(ref) {
+      const parsed = parseKindValueRef(ref);
+      const altBoardId = parsed.kind === 'firestore' ? parsed.value : `${boardId}-archive`;
+      return createFirestoreArchiveFactory(db, altBoardId);
+    },
+
+    // ── Journal storage ───────────────────────────────────────────────────
+    journalStorage() {
+      return createFirestoreJournalStorage(boardDoc.collection('journal'));
+    },
+
+    // ── Queue storage ─────────────────────────────────────────────────────
+    queueStorage: createFirestoreQueueStorage(boardDoc.collection('worker-queue')),
+    chatAgentQueueStorage: createFirestoreQueueStorage(boardDoc.collection('chat-queue')),
+    processAccumulatedQueueStorage: createFirestoreQueueStorage(boardDoc.collection('process-queue')),
+
+    // ── Lock ──────────────────────────────────────────────────────────────
+    lock: createFirestoreLock(
+      boardDoc.collection('locks').doc('board-lock'),
+      { holderId: options.holderId ?? randomUUID() },
+    ),
+
+    // ── Utilities ─────────────────────────────────────────────────────────
+    hashFn(value) {
+      return createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+    },
+
+    genId() {
+      return lexicalId();
+    },
+
+    requestProcessAccumulated: options.requestProcessAccumulated,
+    publishBoardChangeNotifications: options.publishBoardChangeNotifications,
+    onWarn: (msg) => console.warn(`[firestore-board-adapter:${boardId}] ${msg}`),
+  });
+}

package/examples/board-firestore/server/adapters/firestore-journal-storage.js

@@ -0,0 +1,54 @@
+/**
+ * firestore-journal-storage.js
+ *
+ * AsyncJournalStorage backed by a Firestore CollectionReference.
+ * Each entry is stored as: { id, createdAt, payload }
+ * IDs are lexicographically sortable (timestamp prefix) so ORDER BY id
+ * gives insertion order.
+ *
+ * @param {import('@google-cloud/firestore').CollectionReference} col
+ * @returns {import('yaml-flow/cloud-storage').AsyncJournalStorage}
+ */
+
+function lexicalId() {
+  const ts = String(Date.now()).padStart(13, '0');
+  const rand = Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+  return `${ts}-${rand}`;
+}
+
+export function createFirestoreJournalStorage(col) {
+  return {
+    async append(payload) {
+      const id = lexicalId();
+      const doc = { id, createdAt: new Date().toISOString(), payload };
+      await col.doc(id).set(doc);
+      return { id, payload };
+    },
+
+    async readAll() {
+      const snap = await col.orderBy('id').get();
+      return snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+    },
+
+    async readAfter(cursor) {
+      let q = col.orderBy('id');
+      if (cursor) q = col.where('id', '>', cursor).orderBy('id');
+      const snap = await q.get();
+      const entries = snap.docs.map((d) => ({ id: d.data().id, payload: d.data().payload }));
+      return {
+        entries,
+        newCursor: entries.length > 0 ? entries[entries.length - 1].id : cursor,
+      };
+    },
+
+    async clear() {
+      const snap = await col.get();
+      const batchSize = 500;
+      for (let i = 0; i < snap.docs.length; i += batchSize) {
+        const batch = col.firestore.batch();
+        for (const doc of snap.docs.slice(i, i + batchSize)) batch.delete(doc.ref);
+        await batch.commit();
+      }
+    },
+  };
+}

package/examples/board-firestore/server/adapters/firestore-kv-storage.js

@@ -0,0 +1,47 @@
+/**
+ * firestore-kv-storage.js
+ *
+ * AsyncKVStorage backed by a Firestore CollectionReference.
+ * Each key is stored as a document with fields: { k, value }
+ * where k = original key string, value = arbitrary JSON value.
+ *
+ * Document ID: base64url(key)  — avoids '/' and other Firestore-forbidden chars.
+ *
+ * @param {import('@google-cloud/firestore').CollectionReference} col
+ * @returns {import('yaml-flow/cloud-storage').AsyncKVStorage}
+ */
+
+function encodeDocId(key) {
+  return Buffer.from(key).toString('base64url');
+}
+
+function decodeDocId(docId) {
+  return Buffer.from(docId, 'base64url').toString();
+}
+
+export function createFirestoreKvStorage(col) {
+  return {
+    async read(key) {
+      const snap = await col.doc(encodeDocId(key)).get();
+      if (!snap.exists) return null;
+      return snap.data()?.value ?? null;
+    },
+
+    async write(key, value) {
+      await col.doc(encodeDocId(key)).set({ k: key, value });
+    },
+
+    async delete(key) {
+      await col.doc(encodeDocId(key)).delete();
+    },
+
+    async listKeys(prefix = '') {
+      let q = col;
+      if (prefix) {
+        q = col.where('k', '>=', prefix).where('k', '<', prefix + '\uf8ff');
+      }
+      const snap = await q.orderBy('k').get();
+      return snap.docs.map((d) => d.data().k ?? decodeDocId(d.id));
+    },
+  };
+}