Orchestre

Appearance

TypeScript Types Reference ​

Complete reference for TypeScript types and interfaces used throughout Orchestre.

Core Types ​

Project Types ​

typescript
// Project configuration
export interface ProjectConfig {
  name: string;
  template: TemplateName;
  version: string;
  description?: string;
  created: string;
  settings?: ProjectSettings;
}

export interface ProjectSettings {
  parallelAgents?: number;
  autoReview?: boolean;
  knowledgeBase?: boolean;
  llm?: LLMSettings;
}

export interface LLMSettings {
  primary?: ModelName;
  planning?: ModelName;
  review?: ModelName[];
}

// Template types
export type TemplateName = 
  | "makerkit-nextjs"
  | "cloudflare-hono" 
  | "react-native-expo";

export interface TemplateConfig {
  name: string;
  displayName: string;
  description: string;
  version: string;
  author?: string;
  repository?: string;
  keywords: string[];
  requirements: {
    node: string;
    orchestreVersion: string;
  };
  setupCommands: string[];
  structure: {
    sourceDir: string;
    commandsDir: string;
    patternsDir?: string;
  };
  features: string[];
}

Tool Types ​

typescript
// MCP tool definition
export interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties: Record<string, SchemaProperty>;
    required?: string[];
  };
}

export interface SchemaProperty {
  type: "string" | "number" | "boolean" | "array" | "object";
  description?: string;
  enum?: any[];
  items?: SchemaProperty;
  properties?: Record<string, SchemaProperty>;
  minimum?: number;
  maximum?: number;
  pattern?: string;
}

// Tool response
export interface ToolResponse {
  content: Array<{
    type: "text";
    text: string;
  }>;
  isError?: boolean;
}

// Tool handlers
export type ToolHandler<T = any> = (
  params: T
) => Promise<ToolResponse>;

Analysis Types ​

typescript
export interface AnalysisRequest {
  requirements: string;
  context?: {
    existingProject?: boolean;
    projectType?: string;
    constraints?: string[];
  };
}

export interface AnalysisResult {
  complexity: ComplexityLevel;
  estimatedHours: number;
  technologies: Technology[];
  risks: Risk[];
  recommendations: string[];
  breakdown: {
    phases: Phase[];
  };
}

export type ComplexityLevel = 
  | "simple" 
  | "moderate" 
  | "complex" 
  | "very-complex";

export interface Technology {
  name: string;
  purpose: string;
  required: boolean;
}

export interface Risk {
  type: string;
  description: string;
  mitigation: string;
  severity: "low" | "medium" | "high";
}

Planning Types ​

typescript
export interface PlanRequest {
  analysis: AnalysisResult;
  preferences?: {
    approach?: "iterative" | "waterfall" | "agile";
    priority?: "speed" | "quality" | "learning";
    teamSize?: number;
  };
}

export interface PlanResult {
  title: string;
  overview: string;
  phases: Phase[];
  timeline: Timeline;
  resources?: Resource[];
}

export interface Phase {
  id: string;
  name: string;
  description: string;
  tasks: Task[];
  milestone: string;
  duration: Duration;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  type: TaskType;
  priority: Priority;
  estimatedHours: number;
  dependencies?: string[];
  assignee?: string;
  status: TaskStatus;
}

export type TaskType = 
  | "setup" 
  | "feature" 
  | "bugfix" 
  | "refactor" 
  | "test" 
  | "docs";

export type Priority = 
  | "critical" 
  | "high" 
  | "medium" 
  | "low";

export type TaskStatus = 
  | "pending" 
  | "in-progress" 
  | "blocked" 
  | "completed";

export interface Timeline {
  start?: string;
  end?: string;
  totalHours: number;
}

export interface Duration {
  min: number;
  max: number;
  unit: "hours" | "days" | "weeks";
}

export interface Resource {
  type: string;
  description: string;
  required: boolean;
}

Review Types ​

typescript
export interface ReviewRequest {
  scope?: ReviewScope;
  focus?: string;
  compare?: string;
  files?: string[];
}

export type ReviewScope = 
  | "full" 
  | "security" 
  | "performance" 
  | "architecture" 
  | "specific";

export interface ReviewResult {
  summary: ReviewSummary;
  findings: ReviewFinding[];
  consensus: ConsensusResult;
  recommendations: Recommendation[];
}

export interface ReviewSummary {
  score: number;
  strengths: string[];
  improvements: string[];
}

export interface ReviewFinding {
  type: FindingType;
  severity: Severity;
  file?: string;
  line?: number;
  description: string;
  suggestion: string;
  example?: string;
}

export type FindingType = 
  | "security" 
  | "performance" 
  | "bug" 
  | "style" 
  | "architecture" 
  | "best-practice";

export type Severity = 
  | "critical" 
  | "high" 
  | "medium" 
  | "low" 
  | "info";

export interface ConsensusResult {
  agreed: string[];
  disputed: DisputedItem[];
}

export interface DisputedItem {
  issue: string;
  perspectives: Record<string, string>;
}

export interface Recommendation {
  priority: "immediate" | "short-term" | "long-term";
  action: string;
  impact: string;
}

Command Types ​

typescript
export interface CommandDefinition {
  name: string;
  description: string;
  category: CommandCategory;
  availability?: {
    templates?: string[];
    condition?: string;
  };
  parameters?: CommandParameter[];
  examples: CommandExample[];
}

export type CommandCategory = 
  | "core" 
  | "template" 
  | "utility" 
  | "advanced";

export interface CommandParameter {
  name: string;
  type: ParameterType;
  description: string;
  required?: boolean;
  default?: any;
  enum?: any[];
}

export type ParameterType = 
  | "string" 
  | "number" 
  | "boolean" 
  | "array" 
  | "object";

export interface CommandExample {
  description: string;
  command: string;
  result?: string;
}

State Types ​

typescript
export interface MemoryDocument {
  title: string;
  type: DocumentType;
  created: string;
  updated: string;
  content: DocumentContent;
  metadata?: Record<string, any>;
}

export type DocumentType = 
  | "project" 
  | "feature" 
  | "decision" 
  | "pattern" 
  | "learning";

export interface DocumentContent {
  overview?: string;
  context?: string;
  decisions?: Decision[];
  patterns?: Pattern[];
  learnings?: Learning[];
}

export interface Decision {
  title: string;
  rationale: string;
  alternatives?: string[];
  date: string;
}

export interface Pattern {
  id: string;
  name: string;
  category: PatternCategory;
  description: string;
  problem: string;
  solution: string;
  example: {
    before?: string;
    after: string;
  };
  benefits: string[];
  tradeoffs?: string[];
  related?: string[];
  tags: string[];
}

export type PatternCategory = 
  | "architecture" 
  | "code" 
  | "testing" 
  | "deployment" 
  | "security";

export interface Learning {
  insight: string;
  context: string;
  application: string;
}

API Types ​

typescript
// MCP Protocol types
export interface MCPRequest {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: any;
}

export interface MCPResponse {
  jsonrpc: "2.0";
  id: string | number;
  result?: any;
  error?: MCPError;
}

export interface MCPError {
  code: number;
  message: string;
  data?: any;
}

// External API types
export interface GeminiRequest {
  contents: Array<{
    parts: Array<{
      text: string;
    }>;
  }>;
  generationConfig?: {
    temperature?: number;
    topK?: number;
    topP?: number;
    maxOutputTokens?: number;
  };
}

export interface OpenAIRequest {
  model: string;
  messages: Array<{
    role: "system" | "user" | "assistant";
    content: string;
  }>;
  temperature?: number;
  max_tokens?: number;
}

Utility Types ​

typescript
// Helper types
export type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

export type Nullable<T> = T | null;

export type Optional<T> = T | undefined;

export type AsyncResult<T> = Promise<
  | { success: true; data: T }
  | { success: false; error: Error }
>;

// String manipulation
export type CamelCase<S extends string> = 
  S extends `${infer P1}_${infer P2}${infer P3}`
    ? `${Lowercase<P1>}${Uppercase<P2>}${CamelCase<P3>}`
    : Lowercase<S>;

export type KebabCase<S extends string> = 
  S extends `${infer C}${infer T}`
    ? T extends Uncapitalize<T>
      ? `${Lowercase<C>}${KebabCase<T>}`
      : `${Lowercase<C>}-${KebabCase<T>}`
    : S;

// Object manipulation
export type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;

export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  {
    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
  }[Keys];

export type RequireOnlyOne<T, Keys extends keyof T = keyof T> =
  Pick<T, Exclude<keyof T, Keys>> &
  {
    [K in Keys]-?: Required<Pick<T, K>> &
      Partial<Record<Exclude<Keys, K>, undefined>>;
  }[Keys];

Error Types ​

typescript
export class OrchestreError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message);
    this.name = "OrchestreError";
  }
}

export class ValidationError extends OrchestreError {
  constructor(message: string, details?: any) {
    super(message, "VALIDATION_ERROR", details);
    this.name = "ValidationError";
  }
}

export class APIError extends OrchestreError {
  constructor(
    message: string,
    public statusCode: number,
    details?: any
  ) {
    super(message, "API_ERROR", details);
    this.name = "APIError";
  }
}

export class ConfigurationError extends OrchestreError {
  constructor(message: string, details?: any) {
    super(message, "CONFIG_ERROR", details);
    this.name = "ConfigurationError";
  }
}

Generic Patterns ​

typescript
// Result type for operations that can fail
export type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E };

// Builder pattern
export class Builder<T> {
  private data: Partial<T> = {};

  set<K extends keyof T>(key: K, value: T[K]): this {
    this.data[key] = value;
    return this;
  }

  build(): T {
    // Validate required fields
    return this.data as T;
  }
}

// Event emitter types
export interface EventMap {
  [event: string]: any;
}

export interface TypedEventEmitter<Events extends EventMap> {
  on<E extends keyof Events>(
    event: E,
    listener: (data: Events[E]) => void
  ): void;
  
  emit<E extends keyof Events>(
    event: E,
    data: Events[E]
  ): void;
}

// Repository pattern
export interface Repository<T, ID = string> {
  find(id: ID): Promise<T | null>;
  findAll(filter?: Partial<T>): Promise<T[]>;
  create(data: Omit<T, "id">): Promise<T>;
  update(id: ID, data: Partial<T>): Promise<T>;
  delete(id: ID): Promise<void>;
}

Type Guards ​

typescript
// Type guard functions
export function isString(value: unknown): value is string {
  return typeof value === "string";
}

export function isNumber(value: unknown): value is number {
  return typeof value === "number" && !isNaN(value);
}

export function isArray<T>(value: unknown): value is Array<T> {
  return Array.isArray(value);
}

export function isDefined<T>(value: T | undefined): value is T {
  return value !== undefined;
}

export function isNotNull<T>(value: T | null): value is T {
  return value !== null;
}

export function hasProperty<T extends object, K extends PropertyKey>(
  obj: T,
  key: K
): obj is T & Record<K, unknown> {
  return key in obj;
}

// Complex type guards
export function isToolResponse(value: unknown): value is ToolResponse {
  return (
    typeof value === "object" &&
    value !== null &&
    "content" in value &&
    Array.isArray((value as any).content)
  );
}

export function isError(value: unknown): value is Error {
  return value instanceof Error;
}

export function isOrchestreError(value: unknown): value is OrchestreError {
  return value instanceof OrchestreError;
}

Usage Examples ​

typescript
// Using types with inference
import type { ProjectConfig, AnalysisResult } from "@/types";

const config: ProjectConfig = {
  name: "my-project",
  template: "cloudflare-hono",
  version: "1.0.0",
  created: new Date().toISOString()
};

// Type-safe function
async function analyzeComplexity(
  result: AnalysisResult
): Promise<ComplexityLevel> {
  if (result.estimatedHours > 100) return "very-complex";
  if (result.estimatedHours > 40) return "complex";
  if (result.estimatedHours > 16) return "moderate";
  return "simple";
}

// Using utility types
type PartialProject = DeepPartial<ProjectConfig>;
type ProjectResult = AsyncResult<ProjectConfig>;

// Type guards in practice
function processResponse(response: unknown) {
  if (isToolResponse(response)) {
    // response is typed as ToolResponse
    console.log(response.content[0].text);
  } else if (isError(response)) {
    // response is typed as Error
    console.error(response.message);
  }
}

Best Practices ​

  1. Use Type Inference

    typescript
    // Let TypeScript infer when possible
const tasks = []; // any[]
const tasks: Task[] = []; // Better: explicit type

  2. Avoid any

    typescript
    // Bad
function process(data: any) { }

// Good
function process<T>(data: T) { }
// Or be specific
function process(data: unknown) { }

  3. Use Const Assertions

    typescript
    // Mutable
const config = { name: "test" };

// Immutable
const config = { name: "test" } as const;

  4. Discriminated Unions

    typescript
    type Response = 
  | { status: "success"; data: any }
  | { status: "error"; error: Error };

function handle(response: Response) {
  if (response.status === "success") {
    // TypeScript knows response.data exists
  }
}

Resources ​

Built with ❤️ for the AI Coding community, by Praney Behl

Copyright © 2025 Orchestre