<!--
SPDX-FileCopyrightText: 2025 Torkild G. Kjevik
SPDX-FileCopyrightText: 2025 ash_typescript contributors <https://github.com/ash-project/ash_typescript/graphs/contributors>

SPDX-License-Identifier: MIT
-->

# Querying Data

This guide covers pagination, sorting, and filtering when working with AshTypescript RPC actions.

## Pagination

AshTypescript supports both offset-based and keyset (cursor-based) pagination.

### Offset-based Pagination

Use offset and limit for traditional page-based pagination:

```typescript
import { listTodos } from './ash_rpc';

// First page
const page1 = await listTodos({
  fields: ["id", "title", "completed"],
  page: { offset: 0, limit: 20 }
});

if (page1.success) {
  console.log("Total items:", page1.data.count);
  console.log("Items:", page1.data.results);
  console.log("Has more:", page1.data.hasMore);
}

// Second page
const page2 = await listTodos({
  fields: ["id", "title", "completed"],
  page: { offset: 20, limit: 20 }
});
```

**Response includes:**
- `results`: Array of items for the current page
- `count`: Total number of items
- `hasMore`: Boolean indicating if more results exist

### Keyset (Cursor-based) Pagination

For better performance with large datasets:

```typescript
// First page
const page1 = await listTodos({
  fields: ["id", "title", "completed"],
  page: { limit: 20 }
});

if (page1.success && page1.data.hasMore) {
  // Next page using 'after' cursor
  const page2 = await listTodos({
    fields: ["id", "title", "completed"],
    page: { after: page1.data.nextPage, limit: 20 }
  });
}
```

**Response includes:**
- `results`: Array of items
- `previousPage`: Cursor for backwards pagination
- `nextPage`: Cursor for forwards pagination
- `hasMore`: Boolean indicating if more results exist

### When to Use Each Type

| Pagination Type | Use When | Advantages |
|----------------|----------|------------|
| **Offset** | Small/medium datasets, page numbers needed | Simple, direct page access |
| **Keyset** | Large datasets, infinite scroll | Consistent performance, no skipped items |

### Optional vs Required Pagination

Actions can have **required** or **optional** pagination:

```typescript
// Optional pagination - return type changes based on usage
const simpleResult = await listTodos({
  fields: ["id", "title"]
  // No page parameter - returns simple array
});

const paginatedResult = await listTodos({
  fields: ["id", "title"],
  page: { offset: 0, limit: 20 }
  // With page parameter - returns paginated response
});
```

TypeScript automatically infers the correct return type.

## Sorting

Sort results using typed sort strings with direction prefixes. AshTypescript generates per-resource sort field types, so your IDE autocompletes valid field names and catches typos at compile time.

### Type-Safe Sort Fields

For each resource, AshTypescript generates:
- A `{Resource}SortField` union type of all sortable field names
- A `{resource}SortFields` runtime const array for iteration

The `sort` parameter accepts `SortString<TodoSortField>` — a template literal type that allows bare field names or prefixed variants:

```typescript
// Sort by priority descending
const byPriority = await listTodos({
  fields: ["id", "title", "priority"],
  sort: "-priority"       // Type-checked: "priority" must be a valid TodoSortField
});

// Sort by created date ascending
const byDate = await listTodos({
  fields: ["id", "title", "createdAt"],
  sort: "+createdAt"      // Autocompleted by your IDE
});

// sort: "-nonExistent"   // TypeScript error: not a valid TodoSortField
```

**Sort syntax:**
- `fieldName` or `+fieldName`: ascending order
- `-fieldName`: descending order
- `++fieldName`: ascending, nulls first
- `--fieldName`: descending, nulls first

### Multiple Sort Fields

Pass an array for multi-field sorting:

```typescript
// Sort by priority (desc), then by title (asc)
const sorted = await listTodos({
  fields: ["id", "title", "priority"],
  sort: ["-priority", "+title"]   // Each element is type-checked
});
```

### Disabling Client-Side Sorting

Use `enable_sort?: false` when the server should control ordering:

```elixir
typescript_rpc do
  resource MyApp.Todo do
    # Standard action with sorting
    rpc_action :list_todos, :read

    # Server-controlled order - no client sorting
    rpc_action :list_ranked_todos, :read, enable_sort?: false
  end
end
```

When disabled:
- The `sort` parameter is **not included** in TypeScript types
- Any sort sent by client is **silently ignored**
- Filtering and pagination remain available

```typescript
// With enable_sort?: false
const rankedTodos = await listRankedTodos({
  fields: ["id", "title", "rank"],
  filter: { status: { eq: "active" } },  // Still available
  page: { limit: 20 }                    // Still available
  // sort: "-rank"                       // Not available in types
});
```

## Filtering

Filter results using type-safe filter objects.

### Basic Filters

```typescript
// Filter by completed status
const completedTodos = await listTodos({
  fields: ["id", "title", "completed"],
  filter: { completed: { eq: true } }
});

// Filter using "in" operator
const highPriorityTodos = await listTodos({
  fields: ["id", "title", "priority"],
  filter: { priority: { in: ["high", "urgent"] } }
});
```

### Comparison Operators

```typescript
// Find overdue tasks
const overdueTodos = await listTodos({
  fields: ["id", "title", "dueDate"],
  filter: {
    dueDate: { lessThan: new Date().toISOString() }
  }
});
```

**Available operators:**
- `eq`, `notEq`: Equals, not equals
- `in`: Value in array
- `greaterThan`, `greaterThanOrEqual`: Greater than (numbers, dates)
- `lessThan`, `lessThanOrEqual`: Less than (numbers, dates)
- `isNil`: Check for null/nil values (boolean)

### Logical Operators

```typescript
// AND: High priority AND not completed
const activePriority = await listTodos({
  fields: ["id", "title"],
  filter: {
    and: [
      { priority: { in: ["high", "urgent"] } },
      { completed: { eq: false } }
    ]
  }
});

// OR: Completed OR high priority
const completedOrPriority = await listTodos({
  fields: ["id", "title"],
  filter: {
    or: [
      { completed: { eq: true } },
      { priority: { eq: "high" } }
    ]
  }
});

// NOT: Exclude completed
const incomplete = await listTodos({
  fields: ["id", "title"],
  filter: {
    not: [{ completed: { eq: true } }]
  }
});
```

### Null Checks with isNil

Use `isNil` to filter for null or non-null values:

```typescript
// Find todos without a due date
const noDueDate = await listTodos({
  fields: ["id", "title"],
  filter: { dueDate: { isNil: true } }
});

// Find todos that have a due date set
const hasDueDate = await listTodos({
  fields: ["id", "title", "dueDate"],
  filter: { dueDate: { isNil: false } }
});
```

The `isNil` operator is available on nullable fields and accepts a boolean value.

### Filtering on Aggregates

Aggregates (count, sum, avg, etc.) are filterable just like regular fields:

```typescript
// Find todos with highly-rated comments
const popularTodos = await listTodos({
  fields: ["id", "title"],
  filter: {
    commentCount: { greaterThan: 10 }
  }
});
```

### Filtering on Relationships

```typescript
// Filter by related user's name
const johnsTodos = await listTodos({
  fields: ["id", "title", { user: ["name"] }],
  filter: {
    user: { name: { eq: "John Doe" } }
  }
});
```

### Disabling Client-Side Filtering

Use `enable_filter?: false` when filtering should be server-controlled:

```elixir
typescript_rpc do
  resource MyApp.Todo do
    # Standard action with filtering
    rpc_action :list_todos, :read

    # Server applies filtering via action arguments
    rpc_action :list_recent_todos, :list_recent, enable_filter?: false
  end
end
```

When disabled:
- The `filter` parameter is **not included** in TypeScript types
- Filter types for this action are **not generated**
- Any filter sent by client is **silently ignored**

```typescript
// With enable_filter?: false - use action arguments instead
const recentTodos = await listRecentTodos({
  fields: ["id", "title"],
  input: { daysBack: 14 },  // Server-side filtering via argument
  sort: "-createdAt"        // Sorting still available
});
```

### Disabling Both Sorting and Filtering

```elixir
# Curated list with server-controlled order and filtering
rpc_action :list_curated_todos, :read,
  enable_filter?: false,
  enable_sort?: false
```

## Combining All Features

```typescript
const result = await listTodos({
  fields: ["id", "title", "priority", "dueDate", "completed"],
  filter: {
    and: [
      { completed: { eq: false } },
      { priority: { in: ["high", "urgent"] } }
    ]
  },
  sort: "-priority,+dueDate",
  page: { offset: 0, limit: 20 }
});

if (result.success) {
  console.log(`Showing ${result.data.results.length} of ${result.data.count}`);
}
```

## Custom Filtering with Action Arguments

For advanced filtering (text search, pattern matching), use action arguments:

```elixir
# In your Ash resource
read :read do
  argument :search, :string, allow_nil?: true

  prepare fn query, _context ->
    case Ash.Query.get_argument(query, :search) do
      nil -> query
      term -> Ash.Query.filter(query, contains(name, ^term) or contains(email, ^term))
    end
  end
end
```

```typescript
// Use action argument for text search
const results = await listUsers({
  fields: ["id", "name", "email"],
  input: { search: "john" },
  filter: { active: { eq: true } }  // Combine with standard filters
});
```

## Type Safety

### Filter Field Arrays

For each resource, AshTypescript generates runtime arrays and union types of all filterable field names:

```typescript
import type { TodoFilterField } from './ash_types';
import { todoFilterFields } from './ash_types';

// Runtime array for building dynamic filter UIs
todoFilterFields.forEach(field => {
  console.log(`Can filter by: ${field}`);
});

// Type-safe field reference
const field: TodoFilterField = "priority";  // Autocompleted by IDE
```

These include attributes, relationships, and aggregates that are filterable on the resource.

### Filter Operators

All filter operators are fully type-safe:

```typescript
const result = await listTodos({
  fields: ["id", "title"],
  filter: {
    priority: { eq: "invalid" }  // TypeScript error if not valid enum value
  }
});
```

## Next Steps

- [Field Selection](field-selection.md) - Advanced field selection patterns
- [Typed Queries](typed-queries.md) - Predefined queries for SSR
- [RPC Action Options](../features/rpc-action-options.md) - Configure action behavior
- [Error Handling](error-handling.md) - Handle query errors