Skip to main content

TypeScript Shared

Defines Zod validation schemas, TypeScript types, and API contracts shared across backend and frontend in the so1-shared repository.

Quick Reference

PropertyValue
DomainEngineering
FORGE Stage2 (Implementation)
Repositoryso1-shared
StackTypeScript 5.7, Zod 3

Core Capabilities

Zod Schemas

Runtime validation schemas

Type Inference

Inferred TypeScript types from schemas

Error Envelopes

Standard error response formats

API Contracts

Request/response type definitions

Usage Example

Use the TypeScript Shared agent to define the Workflow schema:
- ID field with 'wf_' prefix validation
- Name string (1-100 chars)
- Status enum (draft, active, inactive)
- Trigger type enum
- Created/updated timestamps
- Export both schema and inferred type

Output

// src/schemas/workflow.ts
import { z } from 'zod';

export const WorkflowSchema = z.object({
  id: z.string().startsWith('wf_'),
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  status: z.enum(['draft', 'active', 'inactive']),
  triggerType: z.enum(['manual', 'webhook', 'schedule', 'event']),
  triggerConfig: z.record(z.unknown()),
  createdAt: z.string().datetime(),
  updatedAt: z.string().datetime(),
});

export type Workflow = z.infer<typeof WorkflowSchema>;

// API Request/Response schemas
export const CreateWorkflowSchema = WorkflowSchema.omit({
  id: true,
  createdAt: true,
  updatedAt: true,
});

export type CreateWorkflowRequest = z.infer<typeof CreateWorkflowSchema>;

// Error envelope
export const ErrorResponseSchema = z.object({
  success: z.literal(false),
  error: z.object({
    code: z.string(),
    message: z.string(),
    details: z.record(z.unknown()).optional(),
  }),
});

export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

Best Practices

  • Define schemas before implementing backend/frontend
  • Use .infer to derive TypeScript types from Zod schemas
  • Export both schema (for validation) and type (for TypeScript)
  • Use .omit(), .pick(), .partial() to create variations
  • Prefix IDs with entity type (wf_, org_, user_)

Agent Definition

View full agent markdown