@nuucognition/mesh-adapter-convex

High-level bridge between mesh-core parsing/building and Convex-backed storage.

What this package owns

• MeshConvexAdapter read and write orchestration.
• MeshConvexSnapshotAdapter full snapshot commit + read orchestration.
• Load flow from raw Convex data into built Mesh state.
• Operations-first mutation application through applyOperations and applyTransaction.
• Convex-backed transaction journaling (persisted in the mesh component) with per-call opt-in.

What this package does not own

• Convex schema and component definitions.
• Mesh parsing internals.
• Low-level blob upload transport details.

Quick start

import { MeshConvex } from "@nuucognition/mesh-convex-component"
import { MeshConvexSnapshot } from "@nuucognition/mesh-convex-component"
import { MeshConvexAdapter } from "@nuucognition/mesh-adapter-convex"
import { MeshConvexSnapshotAdapter } from "@nuucognition/mesh-adapter-convex"
import { components } from "./convex/_generated/api"

const client = new MeshConvex({ component: components.mesh })
const adapter = new MeshConvexAdapter({ client })
const snapshotClient = new MeshConvexSnapshot({ component: components.meshSnapshot })
const snapshotAdapter = new MeshConvexSnapshotAdapter({ client: snapshotClient })

const mesh = await adapter.loadMesh(ctx, "my-mesh-id")
await adapter.applyOperations(ctx, "my-mesh-id", [
  {
    type: "create",
    title: "New Note",
    document: {
      kind: "document",
      id: "new-note-id",
      title: "New Note",
      tags: [],
      frontmatter: {},
      links: [],
      embeds: [],
      content: "# Hello\nContent here",
    },
  },
])

await snapshotAdapter.commitSnapshot(ctx, "my-mesh-id", snapshot)

Key methods

• loadMesh(ctx, meshId) loads and builds runtime mesh state.
• getContent(ctx, meshId, title) and getBlobData(ctx, meshId, blobKey) are read APIs.
• getUploadUrl and saveBlobFromStorageId handle blob upload transport.
• applyOperations(ctx, meshId, operations, options?) applies canonical operation batches and can toggle journal writes via enableTransactions (defaults to off).
• applyTransaction(ctx, meshId, transaction) applies an explicit transaction payload.
• getTransactionsForDocument(ctx, meshId, title, limit?) returns persisted, document-scoped transaction history from Convex.
• getTransactionStatus(ctx, meshId) reports hash-based unobserved-change state for Convex meshes.
• syncTransactions(ctx, meshId, options?) performs Convex-side UUID heal + inferred reconcile append.
• commitSnapshot(ctx, meshId, snapshot) replaces full mesh content for snapshot-profile backends.

Notes

• Blob create, rename, and delete operation kinds are supported through the operations-first bridge.
• Path-level document move operations are not supported for Convex-backed storage.

Related packages

• @nuucognition/mesh-core
• @nuucognition/mesh-convex-component