# 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

```typescript
list.catalog.fn.metadata()
```

## Return type

Returns a ListMetadata object:

```typescript
// 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](/sdk/api/functions)

## Examples

**Building a pagination component**

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

```typescript
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}`);
```

**SDK**

```typescript
// 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
```