Introduction to dcupl

dcupl is a data layer for frontend applications. It lets you filter, sort, search, and aggregate data directly in the browser without building a backend.

What Does dcupl Do?

Think of dcupl as a database engine that runs in your application. You give it your data, and it gives you instant query capabilities:

// Filter products by category and price
const list = dcupl.lists.create({ modelKey: 'Product' });

list.catalog.query.addCondition({ attribute: 'category', operator: 'eq', value: 'Electronics' });
list.catalog.query.addCondition({ attribute: 'price', operator: 'lte', value: 500 });

const results = list.catalog.query.items();
// Returns matching products instantly - no API calls

Every filter, sort, and search operation happens instantly because the data lives in memory on the user's device.

The Problem dcupl Solves

Building a product catalog, data table, or search interface requires a lot of backend work:

flowchart TB
  subgraph traditional["Traditional Approach"]
    direction TB
    FE[Frontend] -->|"filter request"| API[Backend API]
    API -->|"SQL query"| DB[(Database)]
    DB -->|"results"| API
    API -->|"JSON"| FE
  end

For every filter change, the browser sends a request, the server queries the database, and results come back. This creates:

• Network latency - Users wait 100-500ms per interaction
• Server costs - Every user action requires server compute
• Backend dependencies - Frontend teams wait for API endpoints

dcupl eliminates this round-trip:

flowchart LR
  subgraph dcupl["dcupl Approach"]
    direction LR
    DATA[Data Source] -->|"load once"| SDK["dcupl SDK\n(in browser)"]
    SDK -->|"instant queries"| UI[Your UI]
  end

Data loads once. All queries happen locally. Users get immediate feedback.

When Should You Use dcupl?

dcupl works well for applications where users explore and filter data:

dcupl handles datasets from hundreds to hundreds of thousands of items efficiently.

When to Consider Alternatives

dcupl is not the right choice for every project:

• Real-time collaboration - If multiple users edit the same data simultaneously, use a real-time database like Firebase or Supabase
• Sensitive data - Client-side data is visible in browser tools. Keep private data server-side
• Massive datasets - Millions of records need server-side querying. Consider dcupl's server-side RAPIs or a dedicated search service

Who Uses dcupl?

dcupl is used by teams building data-intensive web applications:

Digital agencies building product catalogs and data applications for clients. dcupl's reusable patterns speed up development across projects.

Enterprise teams building internal tools and dashboards. dcupl reduces backend dependencies so frontend teams can move independently.

SaaS companies building data exploration features. dcupl handles filtering and aggregation so teams can focus on unique business logic.

How dcupl Works

dcupl has two main components:

flowchart TB
  subgraph sdk["SDK (Open Source)"]
    MODELS[Models] --> ENGINE[Query Engine]
    DATA[Data] --> ENGINE
    ENGINE --> LISTS[Lists & Catalogs]
  end

  subgraph console["Console (Optional SaaS)"]
    EDITOR[Model Editor] --> WORKFLOWS[Data Workflows]
    WORKFLOWS --> STORAGE[CDN Storage]
    STORAGE -.->|"fetch data"| DATA
  end

SDK (Open Source)

The core @dcupl/core package runs in any JavaScript environment. It provides:

• Models - Define your data structure (like a database schema)
• Query engine - Filter, sort, and search with a flexible query language
• Lists and catalogs - Create queryable views of your data with facets and aggregations

The SDK is free, open source, and works without any backend.

Console (Optional)

The dcupl Console is a web platform that adds:

• Visual model editor - Design data models with a UI, generate them with AI
• Data workflows - Transform and sync data from external sources
• REST API deployment - Run dcupl queries server-side when needed

You can use the SDK alone for simpler projects, or add Console for complex data pipelines.

Key Concepts

Before diving in, here are the terms you will encounter:

Model - A definition of your data structure. Similar to a database table schema or TypeScript interface.

Property - A field in a model (name, price, category). Properties have types like string, int, float, boolean, or date.

List - A queryable view of model data. You create lists, add filter conditions, and retrieve results.

Catalog - The query interface on a list. Use it to filter, sort, get facet counts, and run aggregations.

Facets - Counts of items per value, used for filter UIs (e.g., "Electronics (24), Furniture (12)").

A Simple Example

Here is a complete example that loads products and filters them:

import { Dcupl } from '@dcupl/core';

const dcupl = new Dcupl();

// 1. Define the data structure
dcupl.models.set({
  key: 'Product',
  properties: [
    { key: 'name', type: 'string' },
    { key: 'price', type: 'int' },
    { key: 'category', type: 'string' },
  ],
});

// 2. Load data (can come from an API, file, or inline)
dcupl.data.set(
  [
    { key: 'p1', name: 'Laptop', price: 999, category: 'Electronics' },
    { key: 'p2', name: 'Mouse', price: 29, category: 'Electronics' },
    { key: 'p3', name: 'Desk', price: 299, category: 'Furniture' },
    { key: 'p4', name: 'Chair', price: 199, category: 'Furniture' },
  ],
  { model: 'Product' }
);

// 3. Initialize (builds indexes for fast queries)
await dcupl.init();

// 4. Create a list and filter
const list = dcupl.lists.create({ modelKey: 'Product' });
list.catalog.query.addCondition({
  attribute: 'category',
  operator: 'eq',
  value: 'Electronics',
});

// 5. Get results
console.log(list.catalog.query.items());
// [{ key: 'p1', name: 'Laptop', ... }, { key: 'p2', name: 'Mouse', ... }]

// 6. Get facet counts for a filter UI
console.log(list.catalog.fn.facets({ attribute: 'category' }));
// [{ value: 'Electronics', count: 2 }, { value: 'Furniture', count: 2 }]

Next Steps

Ready to start building? Here is the recommended path:

1. Quick Start - Build your first dcupl application in 5 minutes
2. Core Concepts - Understand models, lists, and queries
3. Querying - Learn all the filter operators
4. Facets - Build filter UIs with counts

Or jump directly to framework-specific guides:

• React Integration
• Vue Integration
• Angular Integration