<!--
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
-->

# Field Selection

Field selection is a core concept in AshTypescript that lets you precisely specify which data you need from your Ash resources.

## Why Field Selection?

- **Reduced payload size** - Only requested fields are returned
- **Better performance** - Ash only loads and processes requested data
- **Full type safety** - TypeScript infers exact return types based on selected fields
- **Explicit data requirements** - No over-fetching or under-fetching

## Basic Field Selection

### Simple Fields

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

const todo = await getTodo({
  fields: ["id", "title", "completed", "priority"],
  input: { id: "todo-123" }
});

if (todo.success) {
  // TypeScript knows exact shape:
  // { id: string, title: string, completed: boolean, priority: string }
  console.log(todo.data.title);
}
```

**Note**: There is no "select all" option. This is intentional to prevent over-fetching and ensure explicit data requirements for full type-safety.

## Nested Field Selection

### Relationships

Select fields from related resources:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    "title",
    { user: ["name", "email", "avatarUrl"] }
  ],
  input: { id: "todo-123" }
});

if (todo.success) {
  console.log("Todo:", todo.data.title);
  console.log("Created by:", todo.data.user.name);
}
```

### Multiple Relationships

```typescript
const todo = await getTodo({
  fields: [
    "id",
    "title",
    {
      user: ["name", "email"],
      assignee: ["name", "email"],
      tags: ["name", "color"]
    }
  ],
  input: { id: "todo-123" }
});
```

### Deep Nesting

Select fields from nested relationships:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    "title",
    {
      comments: [
        "id",
        "text",
        {
          author: [
            "name",
            { profile: ["bio", "avatarUrl"] }
          ]
        }
      ]
    }
  ],
  input: { id: "todo-123" }
});
```

## Calculations

### Basic Calculations

Request calculated fields computed by your Ash resource:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    "title",
    "completionPercentage",  // Calculated field
    "timeRemaining"          // Calculated field
  ],
  input: { id: "todo-123" }
});
```

### Calculations Returning Complex Types

For calculations returning complex types (unions, embedded resources) without arguments, use nested syntax:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    {
      relatedItem: ["article", { article: ["id", "title"] }]
    }
  ],
  input: { id: "todo-123" }
});
```

### Calculations with Arguments

Pass arguments to calculation fields:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    {
      priorityScore: {
        args: { multiplier: 2.5, includeSubtasks: true },
        fields: ["score", "rank", "category"]
      }
    }
  ],
  input: { id: "todo-123" }
});
```

## Embedded Resources

### Basic Embedded Resources

```typescript
const todo = await getTodo({
  fields: [
    "id",
    { settings: ["theme", "notifications", "timezone"] }
  ],
  input: { id: "todo-123" }
});
```

### Embedded Arrays

```typescript
const todo = await getTodo({
  fields: [
    "id",
    { attachments: ["filename", "size", "url"] }
  ],
  input: { id: "todo-123" }
});

if (todo.success) {
  todo.data.attachments.forEach(attachment => {
    console.log(`${attachment.filename} (${attachment.size} bytes)`);
  });
}
```

## Union Types

For union type fields, select fields from specific union members:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    {
      content: [
        "text",
        {
          textContent: ["text", "formatting"],
          imageContent: ["url", "caption"],
          videoContent: ["url", "thumbnail"]
        }
      ]
    }
  ],
  input: { id: "todo-123" }
});
```

See [Union Types](../advanced/union-types.md) for detailed union type handling.

## Load Restrictions

Actions can restrict which relationships/calculations clients can load using `allowed_loads` or `denied_loads`:

```typescript
// If action has: allowed_loads: [:user]
const result = await listTodosLimited({
  fields: ["id", "title", { user: ["name"] }]  // OK
  // { comments: ["text"] }  // Would fail - not in allowed_loads
});
```

See [RPC Action Options](../features/rpc-action-options.md) for configuring load restrictions.

## Common Patterns

### List vs Detail Views

```typescript
// List view: minimal fields
async function fetchTodoList() {
  return await listTodos({
    fields: ["id", "title", "completed", "priority"]
  });
}

// Detail view: full fields with relationships
async function fetchTodoDetail(id: string) {
  return await getTodo({
    fields: [
      "id", "title", "description", "completed", "priority",
      "dueDate", "createdAt", "updatedAt",
      {
        user: ["name", "email", "avatarUrl"],
        comments: ["id", "text", { author: ["name"] }],
        tags: ["name", "color"]
      }
    ],
    input: { id }
  });
}
```

### Reusable Field Definitions

```typescript
const TodoFields = {
  basic: ["id", "title", "completed"] as const,

  withUser: [
    "id", "title", "completed",
    { user: ["name", "email"] }
  ] as const,

  full: [
    "id", "title", "description", "completed", "priority",
    {
      user: ["name", "email", "avatarUrl"],
      tags: ["name", "color"]
    }
  ] as const
};

// Usage
const todos = await listTodos({ fields: TodoFields.withUser });
```

### Conditional Field Selection

```typescript
type ViewMode = "list" | "grid" | "detail";

function getTodoFields(mode: ViewMode) {
  const baseFields = ["id", "title", "completed"];

  switch (mode) {
    case "list":
      return [...baseFields, { user: ["name"] }];
    case "grid":
      return [...baseFields, "priority", { tags: ["color"] }];
    case "detail":
      return [
        ...baseFields,
        "description", "priority", "dueDate",
        {
          user: ["name", "email"],
          comments: ["id", "text", { author: ["name"] }]
        }
      ];
  }
}
```

## Next Steps

- [Querying Data](querying-data.md) - Pagination, sorting, and filtering
- [Typed Queries](typed-queries.md) - Predefined field selections for SSR
- [RPC Action Options](../features/rpc-action-options.md) - Load restrictions
- [Union Types](../advanced/union-types.md) - Complex union type handling
- [Embedded Resources](../advanced/embedded-resources.md) - Embedded resource patterns