Events reference

// Subscribe to all events
const unsubscribe = dcupl.on((message) => {
  console.log('Event:', message.type, message);
});

// Later: unsubscribe
unsubscribe();

const list = dcupl.lists.create({ modelKey: 'Product' });

// Re-render when the list's result changes
const unsubscribe = list.onResultChange(() => {
  renderProducts(list.catalog.query.items());
});

// Or receive every event of the list, including reads
const off = list.on((message) => {
  console.log('List event:', message.type);
});

type DcuplUpdateMessage = {
  key: number; // Unique per event (assigned when the call starts, not in delivery order)
  type: DcuplUpdateType; // Event type (see below)
  scope: 'all' | 'global' | 'list' | 'list$'; // emitted events use 'global' or 'list'
  action?: 'update'; // Set on update messages (e.g. result_updated, dcupl_updated_manually)
  origin?: 'user' | 'loader';
  modelKey?: string; // Related model
  listKey?: string; // Related list
  method?: string; // Method that triggered the event
  args?: any[]; // Arguments passed to the method
  result?: any; // Return value of the call: on query_*, fn_* and filter_* events (not query_get, query_has)
  duration?: number; // Execution time in ms, never negative (see below)
  start?: number; // Start timestamp
  end?: number; // End timestamp
};

dcupl.on((msg) => {
  if (msg.type === 'dcupl_initialized') {
    // Fires even when init() failed: check the value init() resolved with
    console.log('dcupl.init() finished');
  }
  if (msg.type === 'dcupl_partial_update') {
    console.log('Changed models:', msg.args[0].changedModels);
  }
});

// Track all list creations
dcupl.on((msg) => {
  if (msg.type === 'list_created') {
    const { listKey, modelKey } = msg.args[0];
    console.log('New list:', listKey, 'for model:', modelKey);
  }
});

// Re-render a list when its result changes
const list = dcupl.lists.create({ modelKey: 'Product' });
list.onResultChange(() => {
  updateProductDisplay();
});

list.on((msg) => {
  switch (msg.type) {
    case 'query_apply':
      console.log('Filter applied:', msg.args);
      break;
    case 'result_updated':
      console.log('Results updated, refreshing...');
      refreshUI();
      break;
  }
});

const unsubscribe = list.onResultChange(() => refreshUI());
// later
unsubscribe();

dcupl.on((msg) => {
  if (msg.type === 'data_change') {
    const { model, type } = msg.args[0]; // the staged data container
    console.log(`Staged ${type} for model:`, model);
  }
});

list.on((msg) => {
  if (msg.type === 'fn_facets') {
    console.log(`Facets computed in ${msg.duration}ms`);
  }
});

dcupl.on((msg) => {
  if (msg.type === 'loader_added') {
    console.log('Loader registered:', msg.args[0]);
  }
});

// Loading progress comes from the loader itself
loader.on((progress) => {
  console.log(`${progress.processed}/${progress.total} resources processed`);
});

showLoadingSpinner();

const unsubscribe = loader.on((progress) => {
  updateProgressBar(progress.processed, progress.total);
});

await loader.process();
await dcupl.init();

unsubscribe();
hideLoadingSpinner();

// duration: milliseconds the call took (see Event Message Structure)
dcupl.on((msg) => {
  if (msg.duration && msg.duration > 100) {
    console.warn(`Slow operation: ${msg.type} took ${msg.duration}ms`, {
      model: msg.modelKey,
      list: msg.listKey,
      args: msg.args,
    });
  }
});

// Log all events in development
if (process.env.NODE_ENV === 'development') {
  dcupl.on((msg) => {
    console.log(`[dcupl] ${msg.type}`, {
      scope: msg.scope,
      model: msg.modelKey,
      list: msg.listKey,
      duration: msg.duration ? `${msg.duration}ms` : undefined,
    });
  });
}

dcupl.on(async (msg) => {
  if (msg.type !== 'data_change') return;

  const { model, type, data } = msg.args[0];
  if (model === 'Order') {
    // A change to Order was staged, sync it to the server
    await syncToServer(model, type, data);
  }
});

function useDcuplEvent(dcupl: Dcupl | null, eventType: DcuplUpdateType) {
  const [lastEvent, setLastEvent] = useState<DcuplUpdateMessage | null>(null);

  useEffect(() => {
    if (!dcupl) return;

    const unsubscribe = dcupl.on((msg) => {
      if (msg.type === eventType) {
        setLastEvent(msg);
      }
    });

    return unsubscribe;
  }, [dcupl, eventType]);

  return lastEvent;
}

// Usage: dcupl_updated_manually fires after each dcupl.update() has been applied
function ProductList() {
  const event = useDcuplEvent(dcupl, 'dcupl_updated_manually');

  useEffect(() => {
    if (event) {
      refetchProducts();
    }
  }, [event]);
}

type DcuplUpdateType =
  // Lifecycle
  | 'dcupl_initialized'
  | 'dcupl_destroyed'
  | 'dcupl_updated_manually'
  | 'dcupl_partial_update'
  | 'dcupl_handle_datacontainer'
  // Data
  | 'data_change'
  | 'model_add'
  | 'view_add'
  // Lists
  | 'list_created'
  | 'list_updated'
  | 'list_destroyed'
  // Queries
  | 'query_apply'
  | 'query_apply_options'
  | 'query_remove'
  | 'query_reset'
  | 'query_execute'
  | 'query_get'
  | 'query_has'
  | 'query_one'
  | 'query_many'
  | 'result_updated'
  // Analytics
  | 'fn_facets'
  | 'fn_aggregate'
  | 'fn_suggest'
  | 'fn_groupBy'
  | 'fn_pivot'
  | 'fn_metadata'
  | 'filter_one'
  | 'filter_many'
  // Loaders
  | 'loader_added'
  | 'loader_removed'
  | 'loader_config_fetched'
  | 'loader_data_fetched'
  | 'loader_models_fetched'
  | 'loader_scripts_fetched'
  | 'loader_processed';