Types API

Reference for TypeScript interfaces and types used throughout ao-forge.

Overview

ao-forge uses TypeScript for type safety and better developer experience. This document provides a comprehensive reference for all types and interfaces.

Core Types

Project Types

interface Project {
  name: string
  version: string
  description?: string
  framework: Framework
  packageManager: PackageManager
  config: ProjectConfig
}

type Framework = 'nextjs' | 'nuxtjs'
type PackageManager = 'npm' | 'pnpm' | 'yarn'

Configuration Types

interface ProjectConfig {
  name: string
  version: string
  description?: string
  framework: Framework
  packageManager: PackageManager
  luaFiles: string[]
  autoStart: boolean
  processName?: string
  ports: PortConfig
  build: BuildConfig
  deploy: DeployConfig
}

interface PortConfig {
  dev: number
  ao: number
  monitoring: number
}

interface BuildConfig {
  output: string
  optimize: boolean
  sourceMaps: boolean
  minify: boolean
  compression: boolean
}

interface DeployConfig {
  platform: DeployPlatform
  environment: Environment
  domain?: string
  customDomain?: string
}

type DeployPlatform = 'vercel' | 'netlify' | 'github' | 'docker'
type Environment = 'development' | 'staging' | 'production'

Process Types

Process Management

interface Process {
  name: string
  status: ProcessStatus
  pid?: number
  startTime?: Date
  endTime?: Date
  config: ProcessConfig
}

type ProcessStatus = 'running' | 'stopped' | 'error' | 'starting' | 'stopping'

interface ProcessConfig {
  name: string
  file: string
  autoStart: boolean
  monitoring: boolean
  wallet?: string
  module?: string
  cron?: string
  sqlite?: boolean
  tags?: ProcessTag[]
}

interface ProcessTag {
  name: string
  value: string
}

Process Operations

interface StartProcessOptions {
  name: string
  wallet?: string
  module?: string
  cron?: string
  sqlite?: boolean
  monitor?: boolean
  tagName?: string
  tagValue?: string
}

interface ProcessResult {
  success: boolean
  output?: string
  error?: string
  pid?: number
}

Build Types

Build Configuration

interface BuildOptions {
  framework?: Framework
  output?: string
  optimize?: boolean
  sourceMaps?: boolean
  minify?: boolean
  static?: boolean
  server?: boolean
  env?: Environment
  platform?: DeployPlatform
}

interface BuildResult {
  success: boolean
  output: string
  errors: string[]
  warnings: string[]
  duration: number
  size: number
}

Optimization Types

interface OptimizationOptions {
  treeshaking: boolean
  codesplitting: boolean
  deadCodeElimination: boolean
  constantFolding: boolean
  minification: boolean
  compression: boolean
}

interface AssetInfo {
  name: string
  size: number
  type: string
  optimized: boolean
  originalSize?: number
}

Deployment Types

Deployment Configuration

interface DeployOptions {
  platform: DeployPlatform
  environment: Environment
  domain?: string
  customDomain?: string
  buildCommand?: string
  publishDirectory?: string
}

interface DeployResult {
  success: boolean
  url?: string
  deploymentId?: string
  errors: string[]
  warnings: string[]
}

Platform-Specific Types

interface VercelConfig {
  projectId: string
  teamId?: string
  environment: Environment
  domain?: string
}

interface NetlifyConfig {
  siteId: string
  buildCommand: string
  publishDirectory: string
  environment: Environment
}

interface GitHubConfig {
  repository: string
  branch: string
  token: string
  environment: Environment
}

interface DockerConfig {
  image: string
  tag: string
  registry?: string
  environment: Environment
}

AI Types

AI Configuration

interface AIConfig {
  defaultModel: AIModel
  apiKey: string
  maxTokens: number
  temperature: number
  timeout: number
}

type AIModel = 'gpt-4' | 'gpt-3.5-turbo' | 'claude-3'

interface AIGenerationOptions {
  model?: AIModel
  maxTokens?: number
  temperature?: number
  includeDocs?: boolean
  generateTypes?: boolean
  prompt?: string
  promptFile?: string
}

AI Generation Results

interface AIGenerationResult {
  success: boolean
  code: string
  metadata: {
    model: string
    tokens: number
    duration: number
  }
  error?: string
}

interface AIProcessGeneration {
  name: string
  description: string
  code: string
  types?: string
  documentation?: string
}

Template Types

Template System

interface Template {
  name: string
  description: string
  framework: Framework
  features: string[]
  files: TemplateFile[]
  dependencies: string[]
  scripts: Record<string, string>
}

interface TemplateFile {
  path: string
  content: string
  type: 'text' | 'binary'
  executable?: boolean
}

interface TemplateOptions {
  name: string
  framework: Framework
  packageManager: PackageManager
  features: string[]
  customizations: Record<string, any>
}

Error Types

Error Handling

interface AOForgeError {
  code: string
  message: string
  details?: any
  stack?: string
  timestamp: Date
}

class AOForgeError extends Error {
  constructor(code: string, message: string, details?: any) {
    super(message)
    this.code = code
    this.details = details
    this.timestamp = new Date()
  }
}

Error Codes

type ErrorCode = 
  | 'PROJECT_NOT_FOUND'
  | 'INVALID_CONFIG'
  | 'PROCESS_FAILED'
  | 'BUILD_FAILED'
  | 'DEPLOYMENT_FAILED'
  | 'AOS_NOT_INSTALLED'
  | 'TEMPLATE_NOT_FOUND'
  | 'INVALID_FRAMEWORK'
  | 'INVALID_PACKAGE_MANAGER'
  | 'PORT_ALREADY_IN_USE'
  | 'INSUFFICIENT_PERMISSIONS'
  | 'NETWORK_ERROR'
  | 'VALIDATION_ERROR'

Utility Types

Common Utilities

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
type Required<T, K extends keyof T> = T & Required<Pick<T, K>>
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
}

interface Logger {
  info(message: string, ...args: any[]): void
  warn(message: string, ...args: any[]): void
  error(message: string, ...args: any[]): void
  debug(message: string, ...args: any[]): void
}

interface FileSystem {
  readFile(path: string): Promise<string>
  writeFile(path: string, content: string): Promise<void>
  exists(path: string): Promise<boolean>
  mkdir(path: string): Promise<void>
  rm(path: string): Promise<void>
}

Event Types

Event System

interface Event {
  type: string
  data: any
  timestamp: Date
  source: string
}

type EventHandler<T = any> = (event: Event & { data: T }) => void

interface EventEmitter {
  on<T>(event: string, handler: EventHandler<T>): void
  off<T>(event: string, handler: EventHandler<T>): void
  emit(event: string, data: any): void
}

Validation Types

Schema Validation

interface ValidationRule {
  required?: boolean
  type?: string
  min?: number
  max?: number
  pattern?: RegExp
  enum?: any[]
  custom?: (value: any) => boolean
}

interface ValidationSchema {
  [key: string]: ValidationRule | ValidationSchema
}

interface ValidationResult {
  valid: boolean
  errors: ValidationError[]
  warnings: ValidationWarning[]
}

interface ValidationError {
  path: string
  message: string
  value: any
  rule: string
}

interface ValidationWarning {
  path: string
  message: string
  value: any
}

Usage Examples

Type-Safe Configuration

import { ProjectConfig, Framework, PackageManager } from '@ao-forge/types'

const config: ProjectConfig = {
  name: 'my-ao-app',
  version: '1.0.0',
  framework: 'nextjs' as Framework,
  packageManager: 'pnpm' as PackageManager,
  luaFiles: ['counter.lua'],
  autoStart: false,
  ports: {
    dev: 3000,
    ao: 8080,
    monitoring: 9090
  },
  build: {
    output: './dist',
    optimize: true,
    sourceMaps: false,
    minify: true,
    compression: true
  },
  deploy: {
    platform: 'vercel',
    environment: 'production'
  }
}

Type-Safe Process Management

import { Process, ProcessStatus, StartProcessOptions } from '@ao-forge/types'

const process: Process = {
  name: 'my-process',
  status: 'stopped' as ProcessStatus,
  config: {
    name: 'my-process',
    file: './ao/counter.lua',
    autoStart: false,
    monitoring: true
  }
}

const startOptions: StartProcessOptions = {
  name: 'my-process',
  monitor: true,
  sqlite: true
}

Best Practices

  1. Type Safety - Use TypeScript for all code
  2. Interface Design - Design clear, consistent interfaces
  3. Error Handling - Use typed error classes
  4. Validation - Validate data at runtime
  5. Documentation - Document all types and interfaces
Table of Contents