WebSocket API (Planned)

Real-time data subscriptions via WebSocket — planned feature with current workarounds

Planned Feature — WebSocket support is not yet implemented in ObjectQL. This page describes the planned API design and provides working alternatives you can use today.

Current Alternatives

ObjectQL's hook system provides the foundation for real-time updates today. Here are three production-ready approaches:

Server-Sent Events (SSE)

The most lightweight option — unidirectional server-to-client streaming:

// Express endpoint
app.get('/api/events/:object', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const objectName = req.params.object;

  const onChanged = (ctx) => {
    res.write(`event: change\ndata: ${JSON.stringify({
      action: ctx.action,
      record: ctx.result
    })}\n\n`);
  };

  objectql.on('after:create', objectName, onChanged);
  objectql.on('after:update', objectName, onChanged);
  objectql.on('after:delete', objectName, onChanged);

  req.on('close', () => {
    objectql.off('after:create', onChanged);
    objectql.off('after:update', onChanged);
    objectql.off('after:delete', onChanged);
  });
});

Client usage:

const events = new EventSource('/api/events/orders');
events.addEventListener('change', (e) => {
  const { action, record } = JSON.parse(e.data);
  console.log(`${action}: ${record.id}`);
});

External Real-time Service

Integrate Pusher, Socket.io, or Ably using hooks:

import Pusher from 'pusher';
const pusher = new Pusher({ /* config */ });

objectql.on('after:create', 'orders', async (ctx) => {
  pusher.trigger('orders', 'created', { record: ctx.result });
});

objectql.on('after:update', 'orders', async (ctx) => {
  pusher.trigger('orders', 'updated', { id: ctx.id, record: ctx.result });
});

Polling

Simplest approach — poll at regular intervals:

setInterval(async () => {
  const orders = await ctx.object('orders').find({
    filters: [['status', '=', 'pending']],
    sort: [{ field: 'updated_at', order: 'desc' }]
  });
  updateUI(orders);
}, 5000);

Planned WebSocket API Design

The planned native WebSocket API will follow this design:

const ws = new WebSocket('ws://localhost:3000/api/realtime');

// Authenticate
ws.send(JSON.stringify({ type: 'auth', token: 'your_jwt_token' }));

// Subscribe to data changes
ws.send(JSON.stringify({
  type: 'subscribe',
  id: 'sub_1',
  object: 'orders',
  filters: [['status', '=', 'pending']],
  fields: ['id', 'status', 'total']
}));

// Receive real-time updates
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'change') {
    console.log(`${msg.action} on ${msg.object}:`, msg.record);
  }
};

Planned Subscription Types

Type	Description
Record subscription	Watch a specific record by ID
Query subscription	Watch results matching a filter
Presence	Track online users in a channel

GraphQL Subscriptions

If you need real-time features today, ObjectQL's GraphQL API supports subscriptions through the GraphQL plugin. See the GraphQL guide for setup details.

See Implementation Status for the latest development status and roadmap.

Hooks - Use hooks to trigger notifications
Server Integration - Setup your server
Implementation Status - Current feature status

WebSocket API (Planned)

On this page