npm package: @holix/config
Description: Type-safe configuration schema for Holix framework using Zod
Author: zhaogongchengsi
Latest version: 1.0.1

# @holix/config

Type-safe configuration schema for Holix framework using Zod.

## 特性

- 🔒 **类型安全** - 使用 Zod 定义的强类型配置
- ✅ **运行时验证** - 自动验证配置的正确性
- 📝 **详细错误** - 提供清晰的验证错误信息
- 🔧 **灵活配置** - 支持多种配置模式
- 🎯 **智能推断** - TypeScript 类型自动推断

## 安装

```bash
pnpm add @holix/config
```

## 使用

### 基础用法

```typescript
import { parseConfig, validateConfig } from '@holix/config'

// 验证配置（返回结果对象）
const result = validateConfig({
  appID: 'my-app',
  app: { entry: 'src/index.ts' },
  outDir: 'dist'
})

if (result.success) {
  console.log('Valid config:', result.data)
}
else {
  console.error('Validation errors:', result.error.issues)
}

// 解析配置（抛出异常）
try {
  const config = parseConfig({
    appID: 'my-app',
    app: { entry: 'src/index.ts' }
  })
  console.log('Parsed config:', config)
}
catch (error) {
  console.error('Invalid config:', error)
}
```

### 配置类型

```typescript
import type { HolixConfig } from '@holix/config'

const config: HolixConfig = {
  appID: 'my-app',

  // 单入口模式
  app: {
    entry: 'src/index.ts'
  },

  // 或者多页面模式（与 app 互斥）
  // directories: {
  //   pages: 'src/pages'
  // },

  // 预加载脚本（多种格式）
  preload: 'src/preload.ts',
  // 或 preload: ['src/preload1.ts', 'src/preload2.ts']
  // 或 preload: { main: 'src/preload-main.ts', worker: 'src/preload-worker.ts' }

  outDir: 'dist',
  plugins: []
}
```

### 合并配置

```typescript
import { defaultHolixConfig, mergeConfig } from '@holix/config'

// 用户配置会与默认配置合并
const config = mergeConfig({
  appID: 'my-app',
  app: { entry: 'src/main.ts' }
})

console.log(config)
// {
//   appID: 'my-app',
//   app: { entry: 'src/main.ts' },
//   outDir: 'dist',  // 来自默认配置
//   directories: { pages: 'src/pages' },  // 来自默认配置
//   preload: null,
//   plugins: []
// }
```

### 在配置文件中使用

```typescript
// holix.config.ts
import { defineConfig } from '@holix/config'

export default defineConfig({
  appID: 'my-app',
  app: {
    entry: 'src/index.ts'
  },
  outDir: 'dist',
  preload: {
    main: 'src/preload-main.ts',
    renderer: 'src/preload-renderer.ts'
  }
})
```

## 配置 Schema

### HolixConfig

| 字段 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| `appID` | `string` | 否 | `'default.app'` | 应用 ID，用于区分不同应用 |
| `app` | `AppConfig \| null` | 否 | `null` | 单入口应用配置 |
| `directories` | `DirectoriesConfig` | 否 | `{ pages: 'src/pages' }` | 多页面目录配置 |
| `preload` | `PreloadConfig` | 否 | `null` | 预加载脚本配置 |
| `outDir` | `string` | 否 | `'dist'` | 输出目录 |
| `plugins` | `string[]` | 否 | `[]` | 插件列表 |

### AppConfig

单入口模式配置：

```typescript
{
  entry: string // 应用入口文件
}
```

### DirectoriesConfig

多页面模式配置：

```typescript
{
  pages: string | null // 页面目录路径
}
```

### PreloadConfig

预加载脚本配置，支持多种格式：

```typescript
// 单个文件
preload: 'src/preload.ts'

// 多个文件
preload: ['src/preload1.ts', 'src/preload2.ts']

// 命名映射
preload: {
  main: 'src/preload-main.ts',
  renderer: 'src/preload-renderer.ts'
}

// 不使用预加载
preload: null
```

## 配置验证规则

1. **app 和 directories 互斥**：不能同时定义 `app` 和 `directories`
2. **必填字段**：`app.entry` 和 `directories.pages` 是各自模式下的必填字段
3. **类型检查**：所有字段都有严格的类型检查
4. **额外属性**：配置对象不允许有未定义的额外属性（使用 `.strict()`）

## API

### validateConfig(config)

验证配置对象，返回结果对象（不抛出异常）。

```typescript
function validateConfig(config: unknown): SafeParseReturnType<unknown, HolixConfig>
```

### parseConfig(config)

解析配置对象，如果无效则抛出 ZodError。

```typescript
function parseConfig(config: unknown): HolixConfig
```

### mergeConfig(userConfig)

合并用户配置和默认配置。

```typescript
function mergeConfig(userConfig: Partial<HolixConfig>): HolixConfig
```

### holixConfigSchema

Zod schema 对象，可用于自定义验证。

```typescript
import { holixConfigSchema } from '@holix/config'

// 扩展 schema
const extendedSchema = holixConfigSchema.extend({
  customField: z.string()
})
```

## 错误处理

```typescript
import { parseConfig } from '@holix/config'
import { ZodError } from 'zod'

try {
  const config = parseConfig({
    app: { entry: 'src/index.ts' },
    directories: { pages: 'src/pages' } // 错误：不能同时定义 app 和 directories
  })
}
catch (error) {
  if (error instanceof ZodError) {
    console.error('Validation errors:')
    error.issues.forEach((issue) => {
      console.error(`- ${issue.path.join('.')}: ${issue.message}`)
    })
  }
}
```

## License

MIT