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

# CRUD Operations

This guide covers Create, Read, Update, and Delete operations using AshTypescript-generated RPC functions.

## Overview

All CRUD operations follow a consistent pattern:
- Field selection using the `fields` parameter
- Type-safe input/output based on your Ash resources
- Explicit error handling with `{success: true/false}` return values
- Support for relationships and nested field selection

## List/Read Operations

### List Multiple Records

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

const todos = await listTodos({
  fields: ["id", "title", "completed", "priority"],
  filter: { completed: { eq: false } },
  sort: "-priority,+createdAt"
});

if (todos.success) {
  console.log("Found todos:", todos.data);
}
```

### Get Single Record

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

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

if (todo.success) {
  console.log("Todo:", todo.data);
}
```

### Get by Specific Fields

Use `get_by` actions to lookup records by specific fields:

```elixir
# Elixir configuration
rpc_action :get_user_by_email, :read, get_by: [:email]
```

```typescript
const user = await getUserByEmail({
  getBy: { email: "user@example.com" },
  fields: ["id", "name", "email"]
});
```

### Handling Not Found

Use `not_found_error?: false` to return `null` instead of an error:

```elixir
# Elixir configuration
rpc_action :find_user, :read, get_by: [:email], not_found_error?: false
```

```typescript
const user = await findUser({
  getBy: { email: "maybe@example.com" },
  fields: ["id", "name"]
});

if (user.success) {
  if (user.data) {
    console.log("Found:", user.data.name);
  } else {
    console.log("User not found");
  }
}
```

### With Relationships

Include related data using nested field selection:

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

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

### Calculated Fields

Request calculated fields computed by your Ash resource:

```typescript
const todo = await getTodo({
  fields: [
    "id",
    "title",
    "dueDate",
    "isOverdue",      // Boolean calculation
    "daysUntilDue"    // Integer calculation
  ],
  input: { id: "todo-123" }
});
```

## Create Operations

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

const newTodo = await createTodo({
  fields: ["id", "title", "createdAt"],
  input: {
    title: "Learn AshTypescript",
    priority: "high",
    dueDate: "2024-01-01",
    userId: "user-id-123"
  }
});

if (newTodo.success) {
  console.log("Created todo:", newTodo.data);
} else {
  console.error("Failed to create:", newTodo.errors);
}
```

## Update Operations

Update existing records using a **separate identity parameter**:

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

const updatedTodo = await updateTodo({
  fields: ["id", "title", "priority", "updatedAt"],
  identity: "todo-123",  // Identity as separate parameter
  input: {
    title: "Updated: Learn AshTypescript",
    priority: "urgent"
  }
});
```

**Important**: The `identity` parameter is separate from the `input` object. This ensures identity fields cannot be accidentally modified.

### Update with Named Identities

Configure update actions to use named identities instead of the primary key:

```elixir
# Elixir configuration
rpc_action :update_user_by_email, :update, identities: [:email]
```

```typescript
const updated = await updateUserByEmail({
  identity: { email: "user@example.com" },
  input: { name: "New Name" },
  fields: ["id", "name"]
});
```

See [RPC Action Options](../features/rpc-action-options.md) for detailed identity configuration.

## Delete Operations

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

const deletedTodo = await destroyTodo({
  identity: "todo-123"
});

if (deletedTodo.success) {
  console.log("Todo deleted successfully");
}
```

### Delete with Named Identities

```elixir
# Elixir configuration
rpc_action :destroy_user_by_email, :destroy, identities: [:email]
```

```typescript
await destroyUserByEmail({
  identity: { email: "user@example.com" }
});
```

## Error Handling

All RPC functions return a `{success: true/false}` structure:

```typescript
const result = await createTodo({
  fields: ["id", "title"],
  input: { title: "New Todo", userId: "user-id-123" }
});

if (result.success) {
  console.log("Created:", result.data);
} else {
  result.errors.forEach(error => {
    console.error(`Error: ${error.message}`);
    if (error.fields.length > 0) {
      console.error(`Fields: ${error.fields.join(', ')}`);
    }
  });
}
```

See [Error Handling](error-handling.md) for comprehensive error handling strategies.

## Authentication and Headers

All RPC functions accept optional headers:

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

// With CSRF protection
const todos = await listTodos({
  fields: ["id", "title"],
  headers: buildCSRFHeaders()
});

// With Bearer token
const todos = await listTodos({
  fields: ["id", "title"],
  headers: {
    "Authorization": "Bearer your-token-here"
  }
});

// Combined
const todos = await listTodos({
  fields: ["id", "title"],
  headers: {
    ...buildCSRFHeaders(),
    "Authorization": "Bearer your-token-here"
  }
});
```

## Complete Example

```typescript
import {
  listTodos,
  getTodo,
  createTodo,
  updateTodo,
  destroyTodo,
  buildCSRFHeaders
} from './ash_rpc';

const headers = buildCSRFHeaders();

// 1. Create
const createResult = await createTodo({
  fields: ["id", "title", "createdAt"],
  input: { title: "Learn AshTypescript CRUD", priority: "high", userId: "user-123" },
  headers
});

if (!createResult.success) return;

const todoId = createResult.data.id;

// 2. Read (single)
const getResult = await getTodo({
  fields: ["id", "title", "priority", { user: ["name"] }],
  input: { id: todoId },
  headers
});

// 3. Read (list)
const listResult = await listTodos({
  fields: ["id", "title", "completed"],
  filter: { completed: { eq: false } },
  headers
});

// 4. Update
const updateResult = await updateTodo({
  fields: ["id", "title", "updatedAt"],
  identity: todoId,
  input: { title: "Mastered AshTypescript CRUD" },
  headers
});

// 5. Delete
const deleteResult = await destroyTodo({
  identity: todoId,
  headers
});
```

## Next Steps

- [Field Selection](field-selection.md) - Advanced field selection patterns
- [Querying Data](querying-data.md) - Pagination, sorting, and filtering
- [Error Handling](error-handling.md) - Comprehensive error handling
- [RPC Action Options](../features/rpc-action-options.md) - Identity lookups, load restrictions
- [Custom Fetch](../advanced/custom-fetch.md) - Request customization and interceptors