# @soda-gql/builder

[![npm version](https://img.shields.io/npm/v/@soda-gql/builder.svg)](https://www.npmjs.com/package/@soda-gql/builder)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Static analysis and artifact generation engine for soda-gql.

## Installation

```bash
bun add -D @soda-gql/builder
```

> **Note**: This package is typically used indirectly via build plugins or the CLI. Direct usage is only needed for advanced integration scenarios.

## Overview

This package provides the core static analysis engine that powers soda-gql's build-time transformations:

- Source code analysis for `gql.default()` calls
- Canonical ID generation for operation tracking
- Artifact generation for runtime transformations
- Support for TypeScript and SWC analyzers

## Features

- **Static Analysis**: Analyzes TypeScript source files to discover GraphQL operations
- **Canonical ID Tracking**: Generates unique identifiers for each operation based on file path and AST location
- **Artifact Generation**: Creates build artifacts used by transformation plugins
- **Multi-Analyzer Support**: Works with both TypeScript and SWC parsers

## Programmatic Usage

For custom build tool integrations:

```typescript
import { createBuilderService } from "@soda-gql/builder";

const service = await createBuilderService({
  config: {
    outdir: "./graphql-system",
    include: ["./src/**/*.ts"],
    analyzer: "ts",
    schemas: {
      default: {
        schema: "./schema.graphql",
        inject: "./default.inject.ts",
      },
    },
  },
});

// Build and analyze source files
const result = await service.buildAsync();

if (result.isOk()) {
  const artifact = result.value;
  // Use artifact for transformations
}
```

## API Reference

### `createBuilderService(options)`

Creates a builder service for static analysis:

```typescript
const service = await createBuilderService({
  config: SodaGqlConfig,
  cwd?: string,
});
```

### Builder Methods

- `build(options?)` - Synchronously analyze source files and generate artifacts
- `buildAsync(options?)` - Asynchronously analyze source files (supports parallel I/O)
- `getGeneration()` - Get the current build generation number
- `getCurrentArtifact()` - Retrieve the current build artifact

### Async Build API

For better performance in large codebases, use the async build API:

```typescript
import { createBuilderService } from "@soda-gql/builder";

const service = await createBuilderService({ config });

// Async build with parallel file I/O
const result = await service.buildAsync();

if (result.isOk()) {
  const artifact = result.value;
  // Use artifact for transformations
}

// Incremental rebuild (only processes changed files)
const incrementalResult = await service.buildAsync();
```

The async API is recommended for:
- Large codebases with many source files
- Build tools that benefit from parallel I/O
- Environments where non-blocking operations are preferred

## Analyzer Options

| Analyzer | Description | Use Case |
|----------|-------------|----------|
| `"ts"` | TypeScript compiler API | Best type accuracy, slower |
| `"swc"` | SWC parser | Faster parsing, good for large codebases |

## Related Packages

- [@soda-gql/tools](../tools) - CLI, codegen, typegen, and formatter
- [@soda-gql/babel](../babel) - Babel transformer and plugin
- [@soda-gql/tsc](../tsc) - TypeScript transformer and plugin
- [@soda-gql/swc](../swc) - SWC-based native transformer

## License

MIT