catalog.fn.metadata()

Returns metadata about the list and its data. Provides information about the model, current query state, item counts, available attributes, and views.

Syntax

list.catalog.fn.metadata()

Return type

Returns a ListMetadata object:

// Can be imported from @dcupl/common
type ListMetadata = {
  key: string;           // Model key
  currentSize: number;   // Items matching the current query (ignores start/count)
  initialSize: number;   // Items in the list
  attributes: ModelAttribute[]; // Model properties and references
  views: ViewDefinition[]; // Views defined for the model
  appliedQuery: DcuplGlobalQueryOptions; // Current query, including sort/start/count
}

Usage notes

Use currentSize vs initialSize to show "X of Y items" in filter UIs
currentSize is the total number of matches even when start/count are applied; query.count() returns the length of the current page then
attributes array describes all available fields for filtering and display
appliedQuery reflects the current filter state for debugging or persistence
No parameters required - returns metadata for the list in its current state

Related methods

catalog.query.count() — Get count of matching items (respects applied start/count)
catalog.fn.facets() — Get filter options for an attribute
catalog.query.current() — Get current query state

Related guides/docs

Functions API reference: global dcupl.fn.* form and errors

Examples

Building a pagination component

Calculate current page, total pages, and page range using metadata for custom pagination UI.

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

// Set page size
productList.catalog.query.applyOptions({ count: 20, start: 0 });

function getPaginationInfo() {
  const meta = productList.catalog.fn.metadata();
  const { currentSize, appliedQuery } = meta;
  const { start = 0, count = 20 } = appliedQuery;

  const totalPages = Math.ceil(currentSize / count);
  const currentPage = Math.floor(start / count) + 1;
  const from = start + 1;
  const to = Math.min(start + count, currentSize);

  return {
    currentPage,
    totalPages,
    pageSize: count,
    totalItems: currentSize,
    from,
    to,
    hasPrevious: currentPage > 1,
    hasNext: currentPage < totalPages,
  };
}

// Navigate to a specific page
function goToPage(page: number) {
  const meta = productList.catalog.fn.metadata();
  const count = meta.appliedQuery.count || 20;
  const start = (page - 1) * count;
  productList.catalog.query.applyOptions({ start, count });
}

// Usage
const info = getPaginationInfo();
console.log(`Page ${info.currentPage} of ${info.totalPages}`);
console.log(`Showing ${info.from}-${info.to} of ${info.totalItems}`);

// Get list metadata
const meta = list.catalog.fn.metadata();

console.log(meta.key);         // Model key
console.log(meta.currentSize); // Filtered count
console.log(meta.initialSize); // Total count
console.log(meta.attributes);  // Model attributes
console.log(meta.appliedQuery); // Current query

{}