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();
});

Update records

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

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

This:

1. Stores the new value in Redis
2. Increments the version
3. Computes a patch
4. 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 user profiles
server.enableRecordPersistence({
  writePattern: /^profile:user:.+$/,  // Matches records for runtime access control
  restorePattern: "profile:user:%"    // SQL LIKE pattern for database restoration
});
 
// Enable persistence with custom options
server.enableRecordPersistence({
  writePattern: "game:state:global",
  restorePattern: "game:state:global"
}, {
  maxBufferSize: 50,
  flushInterval: 1000, // 1 second
});

Write vs Restore Patterns

The enableRecordPersistence() method requires both patterns to be explicit:

• writePattern: RegExp or string used at runtime to check if a record should be persisted when it’s updated
• restorePattern: String used as a raw SQL LIKE pattern to query the database for records to restore on server startup

Common Pattern Examples

// Persist all user data
server.enableRecordPersistence({
  writePattern: /^user:.+$/,
  restorePattern: "user:%"
});
 
// Persist specific document types with complex matching
server.enableRecordPersistence({
  writePattern: /^doc:(article|post):[A-Za-z0-9_-]+$/,
  restorePattern: "doc:%"  // Restore all docs, regardless of type
});
 
// Persist exact match
server.enableRecordPersistence({
  writePattern: "app:config:main",
  restorePattern: "app:config:main"
});

Persistence 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: uses server’s configured adapter)

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.

Configuring persistence storage

To ensure your records truly persist across server restarts, configure a database in your server options. Mesh supports both SQLite and PostgreSQL adapters:

SQLite (default)

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

PostgreSQL

import { MeshServer } from "@mesh-kit/server";
 
const server = new MeshServer({
  port: 3000,
  redisOptions: {
    /* your Redis options */
  },
  persistenceAdapter: "postgres",
  persistenceOptions: {
    host: "localhost",
    port: 5432,
    database: "mesh_db",
    user: "mesh_user",
    password: "mesh_password",
    // Optional: use connection string instead
    // connectionString: "postgresql://mesh_user:mesh_password@localhost:5432/mesh_db"
  },
});
 
server.enableRecordPersistence({
  writePattern: /^profile:user:.+$/,
  restorePattern: "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:

1. When a record is updated, it’s stored in Redis
2. If persistence is enabled for that record, it’s also queued for storage in the persistence database
3. 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).