MC Modeler Persistence: Repository Pattern Deep Dive

// /src/persistence/IDiagramRepository.ts

/**
 * Thrown when an optimistic CAS save detects that the diagram was modified
 * by another writer since this client loaded it (the expected updated_at no
 * longer matches). The caller decides: re-sync and retry, or notify the user.
 */
export class DiagramConflictError extends Error {
  constructor(public readonly diagramId: string) {
    super(
      `Conflicto de guardado: el diagrama ${diagramId} fue modificado por otro usuario`
    )
    this.name = 'DiagramConflictError'
  }
}

export interface IDiagramRepository {
  // ── Diagrams ──────────────────────────────────────────────────────────────

  getAll(): Promise<Diagram[]>
  getById(id: string): Promise<Diagram | null>

  /**
   * Saves the diagram. If `expectedUpdatedAt` is provided, applies optimistic
   * CAS: only updates if the DB's updated_at matches the expected value; if not,
   * throws DiagramConflictError. Returns the persisted updated_at
   * (server-authoritative). Callers MUST adopt this as their new CAS token.
   */
  save(diagram: Diagram, expectedUpdatedAt?: string): Promise<string>

  /** Soft delete: sets deleted_at (moves to trash). Preserves thumbnail and images. */
  delete(id: string): Promise<void>

  /** Removes from trash (sets deleted_at = null). */
  restore(id: string): Promise<void>

  /** PERMANENT delete (real DELETE + thumbnail). Irreversible. */
  purge(id: string): Promise<void>

  /**
   * Renames WITHOUT touching current_xml. Never use save() to rename:
   * it would write the in-memory XML (possibly stale) without CAS,
   * silently clobbering another user's work.
   * Returns the new updated_at if the row changed (trigger bumps it), or null.
   */
  setDiagramName(id: string, name: string): Promise<string | null>

  // ── Projects ──────────────────────────────────────────────────────────────

  getProjects(): Promise<Project[]>
  saveProject(project: Project): Promise<void>

  /** Soft delete of the project AND its diagrams together. */
  deleteProject(id: string): Promise<void>

  /** Restores the project and its soft-deleted diagrams. */
  restoreProject(id: string): Promise<void>

  /** PERMANENT delete of the project and all its diagrams. Irreversible. */
  purgeProject(id: string): Promise<void>

  /** Trash contents (diagrams + projects with deleted_at set). */
  getTrash(): Promise<{ diagrams: Diagram[]; projects: Project[] }>

  /** Empties trash: PERMANENT delete of everything with deleted_at set. */
  purgeAll(): Promise<void>

  /** Returns new updated_at if the row changed, or null. */
  setDiagramProject(diagramId: string, projectId: string | null): Promise<string | null>

  // ── Thumbnails ────────────────────────────────────────────────────────────

  getThumbnail(id: string): Promise<string | null>

  /**
   * Returns new updated_at if it had to touch the diagrams row
   * (thumbnail_path change triggers updated_at bump). Callers MUST
   * adopt this as their CAS version; ignoring it leaves the client
   * stale after its own save (phantom conflicts).
   */
  saveThumbnail(id: string, dataUrl: string): Promise<string | null>

  // Sub-process overlay thumbnails — keyed separately
  getSubProcessThumbnail(parentId: string, elementId: string): Promise<string | null>
  saveSubProcessThumbnail(parentId: string, elementId: string, dataUrl: string): Promise<void>
  deleteSubProcessThumbnail(parentId: string, elementId: string): Promise<void>

  // Recursively soft-deletes a diagram and all its sub-process descendants
  deleteWithChildren(id: string): Promise<void>

  // ── Folders ───────────────────────────────────────────────────────────────

  getFolders(): Promise<Folder[]>
  saveFolder(folder: Folder): Promise<void>
  deleteFolder(id: string): Promise<void>

  // ── Preferences ───────────────────────────────────────────────────────────

  getPreferences(): Promise<UserPreferences>
  savePreferences(prefs: UserPreferences): Promise<void>
}

// /src/persistence/index.ts

import { LocalRepository }        from './LocalRepository'
import { SupabaseRepository }     from './SupabaseRepository'
import { LocalImageRepository }   from './LocalImageRepository'
import { SupabaseImageRepository } from './SupabaseImageRepository'
import { isSupabaseConfigured }   from '@/lib/supabase'
import type { IDiagramRepository } from './IDiagramRepository'
import type { IImageRepository }   from './IImageRepository'

/**
 * Backend selection:
 *  - Supabase configured (VITE_SUPABASE_*) → cloud persistence.
 *  - Otherwise → local IndexedDB (offline/anonymous mode).
 *
 * A single exported instance so no call site needs to change.
 */
export const diagramRepository: IDiagramRepository = isSupabaseConfigured
  ? new SupabaseRepository()
  : new LocalRepository()

export const imageRepository: IImageRepository = isSupabaseConfigured
  ? new SupabaseImageRepository()
  : new LocalImageRepository()

// expectedUpdatedAt is ignored in local mode — single device, no concurrency
async save(diagram: Diagram, _expectedUpdatedAt?: string): Promise<string> {
  const all = await this.readDiagramsRaw()
  const idx = all.findIndex((d) => d.id === diagram.id)
  if (idx >= 0) {
    all[idx] = diagram
  } else {
    all.push(diagram)
  }
  await store.setItem('flujo:diagrams', all)
  return diagram.updatedAt
}

-- Helper functions (security definer — break RLS recursion)
public.can_access_diagram(d_id uuid)  → bool  -- owner OR collaborator
public.can_edit_diagram(d_id uuid)    → bool  -- owner OR editor/owner collaborator
public.is_diagram_owner(d_id uuid)    → bool  -- owner only

// Columns used for list view — current_xml is intentionally absent
private static readonly LIST_COLUMNS =
  'id, owner_id, folder_id, name, element_count, thumbnail_path, ' +
  'schema_version, parent_diagram_id, sub_process_element_id, ' +
  'project_id, created_at, updated_at, deleted_at'

const bumped = await diagramRepository.saveThumbnail(id, thumbnail ?? '')
if (bumped) persistedUpdatedAt = bumped

export function useAutoSave(
  getXml: () => Promise<string>,
  getSvg: () => Promise<string>,
  getThumbCrop?: () => CropRect | null,
  intervalSeconds = 20
)

const save = async () => {
  const id = useDiagramStore.getState().activeTabId
  const dirty = useUIStore.getState().unsavedChanges
  if (!id || !dirty) return

  // Guard 1: viewer role — never write
  if (!useCollabStore.getState().canEdit(id)) return

  // Guard 2: canvas fencing — canvas may still show the previous diagram
  // during a tab switch; saving now would persist the wrong content under the
  // new tab's ID
  if (!isCanvasReadyFor(id)) return

  const [xml, thumbnail] = await Promise.all([
    getXml(),
    buildThumbnail(getSvg, getThumbCrop).catch(() => null),
  ])
  await saveDiagram(id, xml, undefined, thumbnail)
  setUnsavedChanges(false)
}

let saveChain: Promise<unknown> = Promise.resolve()

// Each save is appended to the chain, so they run in sequence
const task = saveChain.then(run, run)
saveChain = task.catch(() => {})
return task

// deleteProject: soft-deletes project + all its diagrams together
async deleteProject(id: string): Promise<void>

// restoreProject: restores project + all its diagrams
async restoreProject(id: string): Promise<void>

// purgeProject: permanent delete of project + all its diagrams + thumbnails
async purgeProject(id: string): Promise<void>