@a0dev/types/README.md

Shared TypeScript types for A0 projects

# @a0dev/types

**⚠️ Beta Release** - This package is currently in beta. The API may change in future releases.

Shared TypeScript types for A0 projects.

## Installation

```bash
npm install @a0dev/types
# or
yarn add @a0dev/types

# Install specific beta version
yarn add @a0dev/types@0.1.0-beta.1
```

## Usage

### Direct Imports (Recommended)

Import types and constants directly from the config module:

```typescript
import {
  CONFIG_FILES,
  BuildYamlSchema,
  type ProjectConfigData,
  type BuildYamlConfig,
  type ConfigFilesRecord,
  type ConfigEnvironment,
} from "@a0dev/types/config";

// Use constants
const files = CONFIG_FILES; // ["build.yaml"]

// Use schemas for validation
const validatedConfig = BuildYamlSchema.parse(someData);

// Use types
function processConfig(config: BuildYamlConfig) {
  // ...
}

function saveConfig(files: ConfigFilesRecord, env: ConfigEnvironment) {
  // ...
}
```

### Namespace Import (Alternative)

Import everything as a namespace if you prefer:

```typescript
import * as Config from "@a0dev/types/config";

// Use constants
const files = Config.CONFIG_FILES;

// Use schemas
const validated = Config.BuildYamlSchema.parse(data);

// Use types
type MyConfig = Config.BuildYamlConfig;
type Env = Config.ConfigEnvironment;
```

### Re-exported from Index

All types are also re-exported from the main entry point:

```typescript
import { Config, type ProjectConfigData } from "@a0dev/types";

// Config namespace is available
const files = Config.CONFIG_FILES;
```

## API Reference

### Constants

- `CONFIG_FILES` - Array of supported config file names: `["build.yaml"]`

### Types

- `ConfigFileName` - Union of supported config file names
- `ConfigFile` - Single configuration file representation
  ```typescript
  interface ConfigFile {
    fileName: string;
    content: string;
  }
  ```
- `ConfigEnvironment` - Environment types: `"dev" | "prod"`
- `ConfigFilesRecord` - Record mapping config file names to YAML strings
- `BuildYamlConfig` - TypeScript type for build.yaml configuration
- `ParsedConfigData` - Parsed config data structure
- `ProjectConfigData` - Alias for ParsedConfigData, represents fully parsed project configuration

### Schemas

- `BuildYamlSchema` - Zod schema for build.yaml validation

## Examples

### Validate Build Configuration

```typescript
import { BuildYamlSchema, type BuildYamlConfig } from "@a0dev/types/config";

const userConfig = {
  general: { disableTracking: true },
  ios: { versionName: "1.0.0", supportsTablet: false },
  android: { versionName: "1.0.0", versionCode: 1 },
};

// Validate and get typed result
const validConfig: BuildYamlConfig = BuildYamlSchema.parse(userConfig);
```

### Type-Safe Config Function

```typescript
import type { ProjectConfigData, ConfigEnvironment } from "@a0dev/types/config";

async function updateProjectConfig(
  projectId: string,
  config: ProjectConfigData,
  env: ConfigEnvironment,
): Promise<void> {
  // Implementation
}
```

### Iterate Over Config Files

```typescript
import { CONFIG_FILES, type ConfigFileName } from "@a0dev/types/config";

CONFIG_FILES.forEach((fileName: ConfigFileName) => {
  console.log(`Processing ${fileName}`);
});
```

## License

MIT