Lists

A DcuplList is a filtered view of your model data. Think of it as a live, queryable dataset that updates automatically.

Each list:

• Represents a specific model's data
• Provides a query interface (via catalog)
• Can have filters applied to it
• Updates when data or filters change
• Manages its own state independently

Multiple Views of Same Data

Create multiple lists for the same model, each with different filters. Great for dashboards, comparison views, or different user contexts.

Independent State

Each list maintains its own query filters, sort order, and cache. Filtering one list doesn't affect others.

Lists can be created with various options:

Option	Description
modelKey	Required. The model to create a view of
listKey	Named identifier for later retrieval
query	Initial query/filter to apply
options.autoUpdate	Auto-refresh when underlying data changes

Lists emit events when their state changes. Subscribe to react to these changes.

Event Properties

Property	Description
action	'init' or 'update' - what happened
trigger	What caused the event (e.g., 'query', 'data')
listKey	The list's unique identifier

When to Update the UI

In most cases, only re-render when action === 'update':

• init - List was just created, initial data ready
• update - Internal data changed (filters, data reload)

Lists go through several states during their lifetime:

1. Created - lists.create() called
2. Active - Ready for queries
3. Filtering - Filters being applied
4. Updating - Data changes being processed
5. Destroyed - list.destroy() called

Always destroy lists when done to prevent memory leaks.

dcupl provides methods to manage all your lists:

• get(key) - Retrieve a list by its key
• getAll() - Get all lists
• getAll({ modelKey }) - Get lists for a specific model
• destroy({ listKey }) - Destroy a specific list

Use Named Lists for Retrieval

Give lists a listKey so you can retrieve them anywhere in your app without passing references.

Destroy Lists in Component Cleanup

Always destroy lists when components unmount to prevent memory leaks.

Reuse Lists Instead of Creating New Ones

Change filters on an existing list rather than creating new lists for each filter change.