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

# Mix Tasks Reference

This document provides a comprehensive reference for all AshTypescript Mix tasks.

## Installation Commands

### `mix igniter.install ash_typescript`

**Automated installer** that sets up everything you need to get started with AshTypescript.

#### Usage

```bash
# Basic installation (RPC setup only)
mix igniter.install ash_typescript

# Full-stack React + TypeScript setup
mix igniter.install ash_typescript --framework react
```

#### What It Does

The installer performs the following tasks:

1. **Dependency Setup**
   - Adds AshTypescript to your `mix.exs` dependencies
   - Runs `mix deps.get` to install the package

2. **Configuration**
   - Configures AshTypescript settings in `config/config.exs`
   - Sets default output paths and RPC endpoints

3. **RPC Controller**
   - Creates RPC controller at `lib/*_web/controllers/ash_typescript_rpc_controller.ex`
   - Implements handlers for run and validate endpoints

4. **Phoenix Router**
   - Adds RPC routes to your Phoenix router
   - Configures `/rpc/run` and `/rpc/validate` endpoints

5. **React Setup** (with `--framework react`)
   - Sets up complete React + TypeScript environment
   - Configures esbuild or vite for frontend builds
   - Creates welcome page with getting started guide
   - Installs necessary npm packages

#### Options

| Option | Description |
|--------|-------------|
| `--framework react` | Set up React + TypeScript environment |

#### When to Use

- ✅ New projects starting with AshTypescript
- ✅ Adding AshTypescript to existing Phoenix projects
- ✅ Setting up frontend with React integration
- ❌ Projects that already have AshTypescript installed

**This is the recommended approach for initial setup.**

## Code Generation Commands

### `mix ash.codegen`

**Recommended approach** for most projects. This command runs code generation for all Ash extensions in your project, including AshTypescript.

```bash
# Generate types for all Ash extensions including AshTypescript
mix ash.codegen --dev
```

For detailed information about `mix ash.codegen`, see the [Ash documentation](https://hexdocs.pm/ash/Mix.Tasks.Ash.Codegen.html).

### `mix ash_typescript.codegen`

Generate TypeScript types, RPC clients, Zod schemas, and validation functions **only for AshTypescript**.

#### Usage

```bash
# Basic generation (AshTypescript only)
mix ash_typescript.codegen

# Custom output location
mix ash_typescript.codegen --output "frontend/src/api/ash.ts"

# Custom RPC endpoints
mix ash_typescript.codegen \
  --run_endpoint "/api/rpc/run" \
  --validate_endpoint "/api/rpc/validate"

# Check if generated code is up to date (CI usage)
mix ash_typescript.codegen --check

# Preview generated code without writing to file
mix ash_typescript.codegen --dry_run
```

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--output FILE` | `string` | `assets/js/ash_rpc.ts` | Output file path for generated TypeScript |
| `--run_endpoint PATH` | `string` | `/rpc/run` | RPC run endpoint path |
| `--validate_endpoint PATH` | `string` | `/rpc/validate` | RPC validate endpoint path |
| `--check` | `boolean` | `false` | Check if generated code is up to date (exit 1 if not) |
| `--dry_run` | `boolean` | `false` | Print generated code to stdout without writing file |

#### Generated Content

When run, this task generates:

1. **TypeScript Interfaces**
   - Resource types with field metadata
   - Schema types for field selection
   - Result types for each action

2. **RPC Client Functions**
   - HTTP-based RPC functions for each action
   - Channel-based RPC functions (if enabled)
   - Type-safe configuration objects

3. **Filter Input Types**
   - Comprehensive filter operators
   - Type-safe query building
   - Nested relationship filtering

4. **Zod Validation Schemas** (if enabled)
   - Runtime type validation
   - Schema for each resource
   - Nested validation support

5. **Form Validation Functions**
   - Client-side validation helpers
   - Error message handling
   - Field-level validation

6. **Typed Query Constants**
   - Pre-configured field selections
   - SSR-optimized types
   - Type-safe result extraction

7. **Custom Type Imports**
   - Imports for custom types
   - Integration with external types
   - Type mapping support

#### Examples

**Basic Generation:**
```bash
mix ash_typescript.codegen
```

**Custom Output Location:**
```bash
mix ash_typescript.codegen --output "frontend/src/api/ash.ts"
```

**Custom RPC Endpoints:**
```bash
mix ash_typescript.codegen \
  --run_endpoint "/api/rpc/run" \
  --validate_endpoint "/api/rpc/validate"
```

**CI Check:**
```bash
# In CI pipeline - fails if generated code is out of date
mix ash_typescript.codegen --check
```

**Preview Without Writing:**
```bash
# See what would be generated
mix ash_typescript.codegen --dry_run | less
```

#### When to Use

- ✅ Want to run codegen specifically for AshTypescript
- ✅ Need custom output paths or endpoints
- ✅ Debugging generated TypeScript code
- ✅ CI/CD pipelines with `--check` flag
- ❌ Have other Ash extensions that need codegen (use `mix ash.codegen`)

## Test Environment Code Generation

For projects using test-only resources (common in library development), use the test environment:

```bash
# Generate types in test environment
MIX_ENV=test mix ash_typescript.codegen

# Or use the test.codegen alias (if defined)
mix test.codegen
```

### Setting Up Test Codegen Alias

Add to your `mix.exs`:

```elixir
defp aliases do
  [
    "test.codegen": ["cmd MIX_ENV=test mix ash_typescript.codegen"],
    # ... other aliases
  ]
end
```

## Workflow Integration

### Development Workflow

```bash
# 1. Make changes to resources or domain configuration
vim lib/my_app/resources/todo.ex

# 2. Generate TypeScript types
mix ash.codegen --dev

# 3. Verify TypeScript compilation (in frontend directory)
cd assets && npm run typecheck

# 4. Run tests
mix test
```

### CI/CD Workflow

```bash
# In your CI pipeline (.github/workflows/ci.yml, etc.)

# Check generated code is up to date
mix ash_typescript.codegen --check

# If out of date, CI fails with:
# "Generated TypeScript code is out of date. Run: mix ash_typescript.codegen"
```

**Example GitHub Actions:**

```yaml
- name: Check TypeScript codegen
  run: mix ash_typescript.codegen --check

- name: Type check generated code
  run: |
    cd assets
    npm run typecheck
```

### Pre-commit Hook

Add to `.git/hooks/pre-commit`:

```bash
#!/bin/bash
# Regenerate TypeScript on commit
mix ash_typescript.codegen --check || {
  echo "TypeScript code out of date. Regenerating..."
  mix ash_typescript.codegen
  git add assets/js/ash_rpc.ts
}
```

## Troubleshooting

### Common Issues

#### "No domains found"

**Problem:** Command runs but generates empty output or reports no domains.

**Solution:** Ensure you're in the correct MIX_ENV:

```bash
# Wrong - uses dev environment
mix ash_typescript.codegen

# Correct - uses test environment for test resources
MIX_ENV=test mix ash_typescript.codegen
```

#### Generated code doesn't compile

**Problem:** TypeScript compilation fails after generation.

**Solution:** Check for:
1. Invalid field names (use field name mapping)
2. Custom types not defined in imported modules
3. Missing type mapping overrides for dependency types

See [Configuration Reference](configuration.md) for field name mapping and type overrides.

#### Changes not reflected

**Problem:** Made changes to resources but generated TypeScript unchanged.

**Solution:**
1. Recompile Elixir code: `mix compile --force`
2. Regenerate TypeScript: `mix ash_typescript.codegen`
3. Verify output file path matches configuration

#### Permission errors

**Problem:** Cannot write to output file.

**Solution:** Check file permissions and directory structure:

```bash
# Ensure directory exists
mkdir -p assets/js

# Check permissions
ls -la assets/js

# Fix if needed
chmod 755 assets/js
```

## See Also

- [Configuration Reference](configuration.md) - Configure code generation
- [Getting Started Tutorial](../tutorials/getting-started.md) - Initial setup guide
- [Troubleshooting Reference](troubleshooting.md) - Common problems and solutions