Server: Records

Records are versioned JSON values stored in Redis. Clients can subscribe to them and receive updates in real time—either full values or patches.

Expose records

Clients can only subscribe to records you explicitly expose:


// Specific ID
server.exposeRecord("user:123");
 
// Pattern match
server.exposeRecord(/^product:\d+$/);
 
// With guard
server.exposeRecord(/^private:.+$/, async (conn, recordId) => {
  const meta = await server.connectionManager.getMetadata(conn);
  return !!meta?.userId;
});

Writable records

To allow clients to modify a record, use exposeWritableRecord(...):


// Anyone can write to cursors
server.exposeWritableRecord(/^cursor:user:\d+$/);
 
// Only allow writing to own profile
server.exposeWritableRecord(/^profile:user:\d+$/, async (conn, recordId) => {
  const meta = await server.connectionManager.getMetadata(conn);
  return meta?.userId === id.split(":").pop();
});

💡

Writable records are automatically readable. If you want to apply different access rules for reading vs writing, you can expose the same pattern using both exposeRecord(...) and exposeWritableRecord(...).

Only the matching guard for the operation type (read or write) will be used. This lets you allow read access to some clients while restricting who can publish updates.

Update records

Use publishRecordUpdate(...) to update a record’s value and notify subscribers:


await server.publishRecordUpdate("user:123", {
  name: "Alice",
  status: "active",
});

This:

Stores the new value in Redis
Increments the version
Computes a patch
Broadcasts to all subscribers

To delete a record:


await server.deleteRecord("user:123");

Get current value


const { value, version } = await server.getRecord("user:123");

Versioning & patching

Every update increments a version. Clients in patch mode expect sequential versions. If a version is missed, Mesh auto-resyncs the client with a full update.

Clients in:

Full mode get the entire value
Patch mode get a JSON Patch to apply locally

Use cases

User profiles — synced, editable fields
Collaborative docs — live document state
Game state — board state, player status
Dashboards — metrics and layout configs

Tips

Use structured IDs: "user:123", "doc:456", "game:abc"
Use guards to control read/write access
Keep records small and focused
Use patch mode for large or frequently updated records

Persistent record storage

For long-term record storage beyond Redis’s in-memory storage, you can enable persistence for records:


// Enable persistence for all user profiles
server.enableRecordPersistence(/^profile:user:.+$/);
 
// Enable persistence with custom options
server.enableRecordPersistence("game:state:global", {
  maxBufferSize: 50,
  flushInterval: 1000, // 1 second
});

Persistence stores records in a durable backend (SQLite by default) and can be configured with these options:

flushInterval: How often to flush buffered records to storage in ms (default: 500)
maxBufferSize: Maximum records to buffer before forcing a flush (default: 100)
adapter: Custom persistence adapter (default: SQLite)

When persistence is enabled, records matching the specified patterns are automatically stored and can be retrieved later, even after server restarts.

This lets you selectively persist data for records where state preservation matters—like user profiles, game states, or document content—without storing transient or high-frequency records such as cursor positions or ephemeral status indicators.

💡

By default, the persistence layer uses SQLite with an in-memory database (:memory:), which means data is lost when the server restarts.

Configuring persistence storage

To ensure your records truly persist across server restarts, configure a file-based database in your server options:


import { MeshServer } from "@mesh-kit/core";
 
const server = new MeshServer({
  port: 3000,
  redisOptions: {
    /* your Redis options */
  },
  persistenceOptions: {
    filename: "./data/mesh.db",
  },
});
 
server.enableRecordPersistence(/^profile:user:.+$/);

Relationship with Redis storage

Records are always stored in Redis for immediate access, while the persistence layer provides long-term storage that survives server restarts:

When a record is updated, it’s stored in Redis
If persistence is enabled for that record, it’s also queued for storage in the persistence database
On server restart, persisted records are automatically restored to Redis

This approach provides both fast access to current record values (Redis) and longer-term storage that survives restarts (persistence layer).