# Playground

### 1. Initialize dcupl

Connect to dcupl and load data

One-time load: Data is fetched once and cached in browser memory. All subsequent queries are instant.

```text
import { Dcupl } from '@dcupl/core';
import { DcuplAppLoader } from '@dcupl/loader';

const dcupl = new Dcupl({
  config: { projectId: 'YOUR_PROJECT_ID', apiKey: 'YOUR_API_KEY' },
});
const loader = new DcuplAppLoader();
dcupl.loaders.add(loader);
await loader.config.fetch(); // loader config from the dcupl CDN
await loader.process();
await dcupl.init();
```

### 2. Create list

Create a list to display Style data

Create a queryable list from your Style model for filtering and display.

```text
const list = dcupl.lists.create({
  modelKey: 'Style'
});
```

### 3. Get facets

Retrieve available filter options

Get filter options (facets) with item counts for each value.

```text
// Facets: each value of an attribute with its item count
const genderFacets = list.catalog.fn.facets({
  attribute: 'gender'
});
// Returns: [{ value: 'Men', size: 22165, ... }, ...]
```

### 4. Apply filters

Filter data instantly - all processing happens client-side.

```text
list.catalog.query.addCondition({
  attribute: 'gender',
  operator: 'eq',
  value: 'Men'
});
```

Advanced features (optional)

### 5. Search by name

Search products by name instantly

```text
list.catalog.query.addCondition({
  attribute: 'productDisplayName',
  operator: 'find',
  value: '/shirt/', // '/…/' = contains
  options: { regexFlags: 'i' }
});
```

### 6. Sort results

Order by any attribute

```text
list.catalog.query.items({
  sort: { attributes: ['articleType'], order: ['ASC'] }
});
```

### 7. Count items & values

Count matching items and distinct values

```text
// Count all items matching current filters
// (query.count() would only count the current page)
const totalItems = list.catalog.fn.metadata().currentSize;

// Get unique values per attribute
const categories = list.catalog.fn.facets({
  attribute: 'masterCategory'
});
```

## Query 44,000+ items instantly

No backend setup. All processing in your browser.

Instant queries

No backend

44,000+ items

**dcupl Way**

You ask your client for a simple data export. You create a data model, upload it to the dcupl console, and start coding immediately. **Within hours, you're getting feedback on the actual application — not mockups or wireframes.**

When the proof of concept is validated, you decide: keep working with static exports, or connect directly to their API. Either way, your frontend code stays exactly the same.

All data loading, queries, and aggregations happen in the browser — fast and performant.

```mermaid
sequenceDiagram
    participant UI
    participant SDK
    participant Server
    Note over UI,Server: One-time load
    UI->>Server: Load models + data
    Server-->>UI: Models & Data
    UI->>SDK: Initialize
    Note over UI,Server: All interactions = instant
    UI->>SDK: filter(category)
    SDK-->>UI: Instant results
    UI->>SDK: sort(price)
    SDK-->>UI: Instant results
    UI->>SDK: search(term)
    SDK-->>UI: Instant results
    Note over UI,Server: No more server calls!
```

**Traditional Way**

First, you need to get access to the client's PIM system. Then you set up servers and databases to handle the query and facet logic. You build out the backend infrastructure. Only then can you start on the actual frontend.

Weeks pass before you can even validate if the idea works — and you haven't written a single line of frontend code yet.

```mermaid
sequenceDiagram
    participant UI
    participant Server
    participant DB
    Note over UI,DB: Every interaction = server calls
    UI->>Server: Query products
    Server->>DB: SELECT...
    DB-->>Server: Results
    Server-->>UI: Products
    UI->>Server: Get facets
    Server->>DB: COUNT BY...
    Server-->>UI: Facets
    Note over UI,DB: User filters...
    UI->>Server: Query + filter
    Server->>DB: SELECT WHERE...
    Server-->>UI: Products
    UI->>Server: Update facets
    Server-->>UI: Facets
```

```mermaid
flowchart LR
    subgraph Source
        PIM[PIM System]
    end
    subgraph Cloud["dcupl Console"]
        Export[Data Export]
        Model[Auto-gen Model]
    end
    subgraph Browser
        SDK[dcupl SDK]
        Memory[(Browser Memory)]
        UI[Your App]
    end
    PIM -->|export| Export
    Export --> Model
    Model -->|one-time load| SDK
    SDK --> Memory
    UI <-->|instant queries| Memory
```

- **In-browser processing:** 44,000+ products loaded into browser memory
- **No network round trips:** Queries, filters, search, sorting & aggregations all run client-side
- **Larger datasets:** Query time grows with data size. Measured with 1 million items: indexed queries took 25–65 ms, facets about 2.7 s