types

Types Package Rules & Instructions

Package Overview

The types package contains shared type definitions, Zod schemas, and interfaces used across the entire Adaline Gateway ecosystem. This package serves as the single source of truth for all data structures.

Type Definition Rules

1. Schema-First Approach

• ALWAYS define Zod schemas first, then derive TypeScript types
• ALWAYS export both the schema and the inferred type
• ALWAYS use descriptive schema names ending with descriptive suffixes
• NEVER define types without corresponding schemas

2. Naming Conventions

• ALWAYS use PascalCase for schema names: ChatResponse, MessageContent
• ALWAYS use PascalCase + Type suffix for type names: ChatResponseType, MessageContentType
• ALWAYS use descriptive names that clearly indicate purpose
• ALWAYS follow the pattern: {SchemaName} and {SchemaName}Type

Schema Definition Instructions

1. Basic Schema Structure

// ✅ CORRECT: Define schema first, then type
const ChatResponse = z.object({
  messages: z.array(Message()),
  usage: ChatUsage.optional(),
  logProbs: ChatLogProbs.optional(),
});
type ChatResponseType = z.infer<typeof ChatResponse>;

// ❌ INCORRECT: Define type without schema
type ChatResponseType = {
  messages: MessageType[];
  usage?: ChatUsageType;
  logProbs?: ChatLogProbsType;
};

2. Schema Composition

// ✅ CORRECT: Compose schemas from smaller parts
const ChatUsage = z.object({
  promptTokens: z.number().nonnegative(),
  completionTokens: z.number().nonnegative(),
  totalTokens: z.number().nonnegative(),
});

const ChatResponse = z.object({
  messages: z.array(Message()),
  usage: ChatUsage.optional(),
});

// ❌ INCORRECT: Duplicate schema definitions
const ChatResponse = z.object({
  messages: z.array(Message()),
  usage: z.object({
    promptTokens: z.number().nonnegative(),
    completionTokens: z.number().nonnegative(),
    totalTokens: z.number().nonnegative(),
  }).optional(),
});