# TypeServe - Full Documentation Context for LLMs

TypeServe is the first and only tool that generates live mock APIs directly from your TypeScript types. No schema files, no OpenAPI definitions, no manual configuration—just your existing TypeScript interfaces, types, and enums.

## Quick Links

- Home: https://typeserve.com
- Documentation index: https://typeserve.com/docs
- GitHub: https://github.com/emmanueltaiwo/typeserve
- npm: https://www.npmjs.com/package/typeserve
- TypeServe Live (create instant mock APIs in browser): https://typeserve.live

---

# SECTION: Getting started

## Installation
URL: https://typeserve.com/docs/getting-started/installation
Description: Install TypeServe in your project in seconds

#
Installation

TypeServe is installed as a development dependency in your project.

##
Install with npm

[CODE BLOCK]
npm install -D typeserve
[/CODE BLOCK]

##
Initialize Configuration

After installation, initialize your configuration file:

[CODE BLOCK]
npx typeserve init
[/CODE BLOCK]

This creates a typeserve.config.ts file in your project root with default settings. If the file already exists, you'll be prompted to confirm before overriding.

##
Verify Installation

You can verify TypeServe is installed correctly:

[CODE BLOCK]
npx typeserve --version
[/CODE BLOCK]

---

## Introduction
URL: https://typeserve.com/docs/getting-started/introduction
Description: Generate live mock APIs from your TypeScript types. No backend needed.

#
Introduction

TypeServe is the first and only tool that generates live mock APIs directly from your TypeScript types. No schema files, no OpenAPI definitions, no manual configuration—just your existing TypeScript interfaces, types, and enums.

##
What is TypeServe?

TypeServe automatically creates a fully-functional Express server that generates realistic mock data from your TypeScript types. It's perfect for frontend developers who want to build without waiting for backend endpoints.

##
Why TypeServe?

###
TypeScript-First Approach

Unlike other mock API tools, TypeServe uses your existing TypeScript types. You don't need to:
• Write OpenAPI schemas
• Create JSON Schema files
• Manually define mock data structures
• Maintain separate type definitions

Just use the types you already have in your codebase.

###
Lightning Fast

TypeServe parses your types at startup, ensuring all routes are ready before the server starts accepting requests. This initial parsing may take a moment depending on the number of types and project size, but once complete, responses are delivered in 2ms-200ms. Perfect for rapid development and testing.

###
Hot Reload

The server automatically reloads when your types or configuration change. Just save your file and keep coding.

###
Smart Data Generation

TypeServe intelligently detects common field patterns:
• Emails → user@example.com
• IDs → UUIDs
• Dates → ISO date strings
• Names → Full names
• URLs → Valid URLs
• Addresses → Street addresses

##
How It Works
Define your types in TypeScript files
Create a config that maps routes to your types
Start the server with npx typeserve dev
Use your API just like a real backend

That's it! Your mock API is ready to use.

##
Use Cases
• Frontend Development - Build your UI without waiting for backend endpoints
• API Design - Prototype your API structure and share with your team
• Testing - Generate consistent mock data for integration tests
• Demos & Prototypes - Quickly spin up working APIs for presentations

---

## Quick Start
URL: https://typeserve.com/docs/getting-started/quick-start
Description: Create your first mock API in 3 simple steps

#
Quick Start

Get your first mock API running in under 2 minutes.

##
Step 1: Define Your Types

Create your TypeScript types anywhere in your project:

[CODE BLOCK]
// src/types.ts
export interface User {
  id: string;
  email: string;
  name: string;
  age: number;
  isActive: boolean;
  createdAt: string;
}

export interface Post {
  id: string;
  user: User;
  title: string;
  description: string;
  tags: string[];
  publishedAt: string;
  views: number;
}
[/CODE BLOCK]

##
Step 2: Create Configuration

Initialize your config file using the init command:

[CODE BLOCK]
npx typeserve init
[/CODE BLOCK]

This creates a typeserve.config.ts file with default settings. Then edit it to add your routes:

Or create typeserve.config.ts manually in your project root:

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  port: 7002,
  basePath: '/api',
  routes: [
    {
      path: '/users',
      method: 'GET',
      type: 'User[]',
      count: 5, // Generate 5 users (optional)
    },
    {
      path: '/users/:id',
      method: 'GET',
      type: 'User',
    },
    {
      path: '/posts',
      method: 'GET',
      type: 'Post[]',
    },
    {
      path: '/posts',
      method: 'POST',
      type: 'Post',
    },
    {
      path: '/users/:id',
      method: 'PUT',
      type: 'User',
    },
    {
      path: '/users/:id',
      method: 'DELETE',
      type: 'User',
    },
  ],
});
[/CODE BLOCK]

##
Step 3: Start the Server

Run the development server:

[CODE BLOCK]
npx typeserve dev
[/CODE BLOCK]

You'll see output like:

[CODE BLOCK]
📖 Loading configuration...
✅ Configuration loaded successfully
📖 Parsing types...
   This may take a while depending on the number of types and project size.
✅ Types parsed in 29181ms
🚀 Attempting to start your server on port 7002...
✅ TypeServe running on http://localhost:7002/api (started in 29903ms)
📋 Available routes:
   GET /api/users → User[]
   GET /api/users/:id → User
   GET /api/posts → Post[]
   POST /api/posts → Post
[/CODE BLOCK]

TypeServe parses all your types at startup to ensure fast response times. The initial parsing may take a moment depending on your project size, but once complete, all API requests will be lightning fast.

##
Test Your API

Open your browser or use curl:

[CODE BLOCK]
curl http://localhost:7002/api/users
[/CODE BLOCK]

You'll get realistic mock data that matches your TypeScript types!

[CODE BLOCK]
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "age": 28,
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
  // ... 4 more users
]
[/CODE BLOCK]

---

# SECTION: Configuration

## Config File
URL: https://typeserve.com/docs/configuration/config-file
Description: Learn how to configure TypeServe

#
Configuration File

TypeServe uses a typeserve.config.ts file in your project root to define your mock API routes.

##
Basic Structure

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  port: 7002,
  basePath: '/api',
  routes: [
    // Your routes here
  ],
});
[/CODE BLOCK]

##
Configuration Options

###
port (optional)

The port number for your mock server. Defaults to 7002.

[CODE BLOCK]
export default defineMock({
  port: 4000, // Server will run on port 4000
  routes: [...],
});
[/CODE BLOCK]

If the port is already in use, TypeServe will automatically try the next available port.

###
basePath (optional)

The base path for all your API routes. Defaults to '/api'.

[CODE BLOCK]
export default defineMock({
  basePath: '/api/v1', // All routes will be prefixed with /api/v1
  routes: [
    { path: '/users', ... }, // Becomes /api/v1/users
  ],
});
[/CODE BLOCK]

###
routes (required)

An array of route configurations. Each route maps an HTTP endpoint to a TypeScript type.

[CODE BLOCK]
routes: [
  {
    path: '/users',
    method: 'GET',
    type: 'User[]',
  },
]
[/CODE BLOCK]

Learn more about route configuration (https://typeserve.com/docs/configuration/docs/configuration/routes).

##
Type Safety

The defineMock function provides full TypeScript IntelliSense and type checking:

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  // TypeScript will autocomplete and validate your config
  port: 7002,
  routes: [
    {
      path: '/users',
      method: 'GET', // Autocomplete: 'GET' | 'POST' | 'PUT' | 'DELETE'
      type: 'User[]',
      count: 3, // Autocomplete: 1 | 2 | 3 | 4 | 5
    },
  ],
});
[/CODE BLOCK]

##
Creating the Config File

###
Using the Init Command

The easiest way to create your config file is using the init command:

[CODE BLOCK]
npx typeserve init
[/CODE BLOCK]

This will create a typeserve.config.ts file with default settings. If the file already exists, you'll be prompted to confirm before overriding.

###
Manual Creation

You can also create the file manually. The config file must be named typeserve.config.ts and placed in your project root:

[CODE BLOCK]
my-project/
├── typeserve.config.ts  ← Here
├── package.json
├── src/
│   └── types.ts
└── ...
[/CODE BLOCK]

##
Custom Config Path

You can use a custom config file path with the CLI:

[CODE BLOCK]
npx typeserve dev --config ./config/my-typeserve.ts
[/CODE BLOCK]

---

## Configuration Options
URL: https://typeserve.com/docs/configuration/options
Description: Complete reference of all TypeServe configuration options

#
Configuration Options

Complete reference for all TypeServe configuration options.

##
TypeServeConfig

[CODE BLOCK]
interface TypeServeConfig {
  routes: RouteConfig[];  // Required
  port?: number;          // Optional, default: 7002
  basePath?: string;      // Optional, default: '/api'
}
[/CODE BLOCK]

##
RouteConfig

[CODE BLOCK]
interface RouteConfig {
  path: string;                    // Required: endpoint path
  method: 'GET' | 'POST' | 'PUT' | 'DELETE'; // Required: HTTP method
  type: string;                    // Required: TypeScript type name
  file?: string;                   // Optional: explicit file path
  count?: 1 | 2 | 3 | 4 | 5;      // Optional: array item count
}
[/CODE BLOCK]

##
Port Configuration

###
Default Port

[CODE BLOCK]
export default defineMock({
  port: 7002, // Server runs on port 7002
  routes: [...],
});
[/CODE BLOCK]

###
Port Auto-Detection

If the specified port is in use, TypeServe automatically tries the next available port:

[CODE BLOCK]
🚀 Attempting to start your server on port 7002...
⚠️  Port 7002 is already in use. Attempting to start on port 7003...
✅ TypeServe running on http://localhost:7003/api
   (Originally attempted port 7002)
[/CODE BLOCK]

###
CLI Port Override

You can override the port via CLI:

[CODE BLOCK]
npx typeserve dev --port 4000
[/CODE BLOCK]

##
Base Path

###
Default Base Path

[CODE BLOCK]
export default defineMock({
  basePath: '/api', // All routes prefixed with /api
  routes: [
    { path: '/users', ... }, // Becomes /api/users
  ],
});
[/CODE BLOCK]

###
Custom Base Path

[CODE BLOCK]
export default defineMock({
  basePath: '/api/v1',
  routes: [
    { path: '/users', ... }, // Becomes /api/v1/users
  ],
});
[/CODE BLOCK]

###
No Base Path

[CODE BLOCK]
export default defineMock({
  basePath: '',
  routes: [
    { path: '/users', ... }, // Becomes /users
  ],
});
[/CODE BLOCK]

##
Route Paths

###
Simple Paths

[CODE BLOCK]
{ path: '/users', ... }
{ path: '/posts', ... }
{ path: '/comments', ... }
[/CODE BLOCK]

###
Path Parameters

Express-style route parameters:

[CODE BLOCK]
{ path: '/users/:id', ... }              // /api/users/123
{ path: '/posts/:postId/comments', ... } // /api/posts/123/comments
{ path: '/users/:id/posts/:postId', ... } // /api/users/1/posts/2
[/CODE BLOCK]

Note: Path parameters are captured but not used in data generation. All generated data follows the same structure.

##
HTTP Methods

###
GET Requests

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User[]',
}
[/CODE BLOCK]

###
POST Requests

[CODE BLOCK]
{
  path: '/posts',
  method: 'POST',
  type: 'Post',
}
[/CODE BLOCK]

###
PUT Requests

[CODE BLOCK]
{
  path: '/users/:id',
  method: 'PUT',
  type: 'User',
}
[/CODE BLOCK]

###
DELETE Requests

[CODE BLOCK]
{
  path: '/users/:id',
  method: 'DELETE',
  type: 'User',
}
[/CODE BLOCK]

##
Type Names

###
Single Types

[CODE BLOCK]
{ type: 'User', ... }    // Returns a single User object
{ type: 'Post', ... }    // Returns a single Post object
[/CODE BLOCK]

###
Array Types

Use [] suffix for arrays:

[CODE BLOCK]
{ type: 'User[]', ... }  // Returns an array of User objects
{ type: 'Post[]', ... }  // Returns an array of Post objects
[/CODE BLOCK]

##
Array Count

Control how many items are generated for array types:

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User[]',
  count: 1, // Always 1 user
}

{
  path: '/users',
  method: 'GET',
  type: 'User[]',
  count: 5, // Always 5 users
}
[/CODE BLOCK]

If count is not specified, TypeServe randomly generates 1-3 items.

##
File Path

Specify the exact file path if TypeServe can't find your type:

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User',
  file: './src/models/user.ts',
}
[/CODE BLOCK]

Use relative paths from your project root.

##
Complete Example

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  // Server configuration
  port: 7002,
  basePath: '/api',
  
  // Route definitions
  routes: [
    // Array route with count
    {
      path: '/users',
      method: 'GET',
      type: 'User[]',
      count: 5,
    },
    // Single object route
    {
      path: '/users/:id',
      method: 'GET',
      type: 'User',
    },
    // Route with explicit file
    {
      path: '/posts',
      method: 'GET',
      type: 'Post[]',
      file: './src/types/posts.ts',
    },
    // POST route
    {
      path: '/posts',
      method: 'POST',
      type: 'Post',
    },
    // PUT route
    {
      path: '/users/:id',
      method: 'PUT',
      type: 'User',
    },
    // DELETE route
    {
      path: '/users/:id',
      method: 'DELETE',
      type: 'User',
    },
  ],
});
[/CODE BLOCK]

---

## Routes
URL: https://typeserve.com/docs/configuration/routes
Description: Configure API routes and map them to TypeScript types

#
Routes

Routes define your API endpoints and map them to TypeScript types. Each route tells TypeServe what data to generate for a specific HTTP endpoint.

##
Basic Route

A route requires three properties:

[CODE BLOCK]
{
  path: '/users',      // The endpoint path
  method: 'GET',       // HTTP method
  type: 'User[]',      // TypeScript type name
}
[/CODE BLOCK]

##
Route Properties

###
path (required)

The endpoint path. Supports Express-style route parameters:

[CODE BLOCK]
{ path: '/users', ... }           // /api/users
{ path: '/users/:id', ... }       // /api/users/123
{ path: '/posts/:id/comments', ... } // /api/posts/123/comments
[/CODE BLOCK]

###
method (required)

The HTTP method. Supports 'GET', 'POST', 'PUT', or 'DELETE'.

[CODE BLOCK]
{ method: 'GET', ... }    // GET request
{ method: 'POST', ... }   // POST request
{ method: 'PUT', ... }    // PUT request
{ method: 'DELETE', ... } // DELETE request
[/CODE BLOCK]

###
type (required)

The TypeScript type name. Use [] suffix for arrays:

[CODE BLOCK]
{ type: 'User', ... }    // Single object
{ type: 'User[]', ... }  // Array of objects
[/CODE BLOCK]

###
file (optional)

Specify the file path if TypeServe can't find your type automatically:

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User',
  file: './src/models/user.ts', // Optional: explicit file path
}
[/CODE BLOCK]

###
count (optional)

For array types, control how many items to generate (1-5). Defaults to 1-3 random items:

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User[]',
  count: 5, // Always generate exactly 5 users
}
[/CODE BLOCK]

##
Examples

###
Single Object Route

[CODE BLOCK]
{
  path: '/users/:id',
  method: 'GET',
  type: 'User',
}
[/CODE BLOCK]

Returns a single User object.

###
Array Route

[CODE BLOCK]
{
  path: '/users',
  method: 'GET',
  type: 'User[]',
  count: 3, // Generate 3 users
}
[/CODE BLOCK]

Returns an array of 3 User objects.

###
POST Route

[CODE BLOCK]
{
  path: '/posts',
  method: 'POST',
  type: 'Post',
}
[/CODE BLOCK]

Returns a single Post object (simulating a created post).

###
PUT Route

[CODE BLOCK]
{
  path: '/users/:id',
  method: 'PUT',
  type: 'User',
}
[/CODE BLOCK]

Returns a single User object (simulating an updated user).

###
DELETE Route

[CODE BLOCK]
{
  path: '/users/:id',
  method: 'DELETE',
  type: 'User',
}
[/CODE BLOCK]

Returns a single User object (simulating a deleted user).

###
Route with Parameters

[CODE BLOCK]
{
  path: '/users/:userId/posts',
  method: 'GET',
  type: 'Post[]',
}
[/CODE BLOCK]

The :userId parameter is captured but not used in data generation. All generated posts will have the same structure.

##
Complete Example

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  port: 7002,
  basePath: '/api',
  routes: [
    // Get all users
    {
      path: '/users',
      method: 'GET',
      type: 'User[]',
      count: 5,
    },
    // Get single user
    {
      path: '/users/:id',
      method: 'GET',
      type: 'User',
    },
    // Get all posts
    {
      path: '/posts',
      method: 'GET',
      type: 'Post[]',
    },
    // Create a post
    {
      path: '/posts',
      method: 'POST',
      type: 'Post',
    },
    // Update a user
    {
      path: '/users/:id',
      method: 'PUT',
      type: 'User',
    },
    // Delete a user
    {
      path: '/users/:id',
      method: 'DELETE',
      type: 'User',
    },
  ],
});
[/CODE BLOCK]

##
Type Resolution

TypeServe automatically finds your types by:
Searching all TypeScript files in your project
Looking for exported types/interfaces matching the name
Using the file property if specified

Make sure your types are exported:

[CODE BLOCK]
// ✅ Good - exported
export interface User { ... }

// ❌ Bad - not exported
interface User { ... }
[/CODE BLOCK]

---

# SECTION: Api reference

## CLI Commands
URL: https://typeserve.com/docs/api-reference/cli
Description: Complete reference for TypeServe CLI commands

#
CLI Commands

TypeServe provides a simple CLI to start and manage your mock API server.

##
Installation

Install TypeServe as a dev dependency:

[CODE BLOCK]
npm install -D typeserve
[/CODE BLOCK]

##
Basic Usage

Start the development server:

[CODE BLOCK]
npx typeserve dev
[/CODE BLOCK]

This will:
Load your typeserve.config.ts file
Parse your TypeScript types
Start the Express server
Watch for file changes

##
Commands

###
typeserve init

Initialize a new typeserve.config.ts file in your project root.

[CODE BLOCK]
npx typeserve init
[/CODE BLOCK]

What it does:
• Creates a typeserve.config.ts file with default configuration
• If the file already exists, prompts you to confirm before overriding

Example:

[CODE BLOCK]
#
Create new config file
npx typeserve init

#
Output:

#
✅ Created typeserve.config.ts successfully!

#
📝 Edit the file to add your routes and types.
[/CODE BLOCK]

If config exists:

[CODE BLOCK]
npx typeserve init

#
⚠️  typeserve.config.ts already exists. Do you want to override? (y/n):

#
Type 'y' to override or 'n' to cancel
[/CODE BLOCK]

The generated config includes:
• Default port: 7002
• Default basePath: '/api'
• Empty routes array

###
typeserve dev

Start the development server with hot reload.

[CODE BLOCK]
npx typeserve dev
[/CODE BLOCK]

####
Options
• -p, --port <port> - Port number (default: 7002)
• -c, --config <path> - Config file path (default: typeserve.config.ts)

####
Examples

[CODE BLOCK]
#
Start on default port 3000
npx typeserve dev

#
Start on custom port
npx typeserve dev --port 4000

#
Use custom config file
npx typeserve dev --config ./my-config.ts
[/CODE BLOCK]

##
Port Management

If the specified port is already in use, TypeServe automatically tries the next available port:

[CODE BLOCK]
🚀 Attempting to start your server on port 7002...
⚠️  Port 7002 is already in use. Attempting to start on port 7003...
✅ TypeServe running on http://localhost:7003/api
   (Originally attempted port 7002)
[/CODE BLOCK]

##
Hot Reload

TypeServe automatically watches for changes:
• When typeserve.config.ts changes → Server reloads
• When any type used in config changes → Server reloads
• When related type files change → Server reloads

You'll see output like:

[CODE BLOCK]
🔄 File changed: src/types.ts
✅ Server reloaded
[/CODE BLOCK]

##
Request Logging

All requests are logged with timing information:

[CODE BLOCK]
GET /api/users 200 78ms
POST /api/posts 201 52ms
GET /api/users/123 200 38ms
[/CODE BLOCK]

##
Graceful Shutdown

Press Ctrl+C to stop the server:

[CODE BLOCK]
👋 Shutting down TypeServe...
🛑 Stopping TypeServe server...
✅ Server stopped successfully
👋 Goodbye!
[/CODE BLOCK]

##
Global Installation

You can install TypeServe globally:

[CODE BLOCK]
npm install -g typeserve
[/CODE BLOCK]

Then use it directly:

[CODE BLOCK]
typeserve dev
[/CODE BLOCK]

However, we recommend using it as a local dev dependency with npx for version consistency.

##
Troubleshooting

###
Port Already in Use

TypeServe will automatically try the next port. If you want to use a specific port, make sure it's available or use the --port option.

###
Type Not Found

Make sure:
• Your type is exported from the file
• The type name matches exactly (case-sensitive)
• The file is in a location TypeServe can find (or specify file in route config)

###
Config Not Loading
• Ensure typeserve.config.ts is in your project root
• Check that the config exports a default object
• Verify all routes have required fields (path, method, type)

##
Next Steps

---

## Config Reference
URL: https://typeserve.com/docs/api-reference/config
Description: Complete TypeServe configuration API reference

#
Configuration Reference

Complete reference for all TypeServe configuration types and options.

##
TypeServeConfig

Main configuration interface:

[CODE BLOCK]
interface TypeServeConfig {
  routes: RouteConfig[];  // Required: Array of route configurations
  port?: number;          // Optional: Server port (default: 7002)
  basePath?: string;      // Optional: API base path (default: '/api')
}
[/CODE BLOCK]

###
Properties

####
routes (required)

Array of route configurations. Each route maps an HTTP endpoint to a TypeScript type.

[CODE BLOCK]
routes: [
  {
    path: '/users',
    method: 'GET',
    type: 'User[]',
  },
]
[/CODE BLOCK]

####
port (optional)

The port number for the mock server. Defaults to 7002.

[CODE BLOCK]
port: 7002
[/CODE BLOCK]

If the port is in use, TypeServe automatically tries the next available port.

####
basePath (optional)

The base path prefix for all routes. Defaults to '/api'.

[CODE BLOCK]
basePath: '/api'
[/CODE BLOCK]

All route paths will be prefixed with this value.

##
RouteConfig

Route configuration interface:

[CODE BLOCK]
interface RouteConfig {
  path: string;                    // Required: Endpoint path
  method: 'GET' | 'POST' | 'PUT' | 'DELETE'; // Required: HTTP method
  type: string;                    // Required: TypeScript type name
  file?: string;                   // Optional: Explicit file path
  count?: 1 | 2 | 3 | 4 | 5;      // Optional: Array item count
}
[/CODE BLOCK]

###
Properties

####
path (required)

The endpoint path. Supports Express-style route parameters.

[CODE BLOCK]
path: '/users'              // Simple path
path: '/users/:id'          // With parameter
path: '/posts/:id/comments' // Nested path
[/CODE BLOCK]

####
method (required)

HTTP method. Supports 'GET', 'POST', 'PUT', or 'DELETE'.

[CODE BLOCK]
method: 'GET'    // GET request
method: 'POST'   // POST request
method: 'PUT'    // PUT request
method: 'DELETE' // DELETE request
[/CODE BLOCK]

####
type (required)

TypeScript type name. Use [] suffix for arrays.

[CODE BLOCK]
type: 'User'    // Single object
type: 'User[]'  // Array of objects
[/CODE BLOCK]

####
file (optional)

Explicit file path if TypeServe can't find the type automatically.

[CODE BLOCK]
file: './src/types/user.ts'
[/CODE BLOCK]

Use relative paths from your project root.

####
count (optional)

For array types, specify how many items to generate (1-5). Defaults to 1-3 random items.

[CODE BLOCK]
count: 1  // Always 1 item
count: 5  // Always 5 items
[/CODE BLOCK]

##
defineMock

Type-safe helper function for defining your config:

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  // Full TypeScript IntelliSense and type checking
  port: 7002,
  basePath: '/api',
  routes: [...],
});
[/CODE BLOCK]

This function provides:
• Full TypeScript autocomplete
• Type checking for all properties
• IntelliSense support in your IDE

##
Type Definitions

###
ParsedType

Internal type representation (for reference):

[CODE BLOCK]
interface ParsedType {
  name: string;
  properties: Record<string, TypeProperty>;
  isArray: boolean;
  isEnum: boolean;
  enumValues?: string[];
}
[/CODE BLOCK]

###
TypeProperty

Property definition (for reference):

[CODE BLOCK]
interface TypeProperty {
  type: string;
  isOptional: boolean;
  isArray: boolean;
  isEnum: boolean;
  enumValues?: string[];
  nestedType?: ParsedType;
}
[/CODE BLOCK]

##
Complete Example

[CODE BLOCK]
import { defineMock } from '@typeserve/core';

export default defineMock({
  // Server configuration
  port: 7002,
  basePath: '/api',
  
  // Route definitions
  routes: [
    // Array route with count
    {
      path: '/users',
      method: 'GET',
      type: 'User[]',
      count: 5,
    },
    // Single object route
    {
      path: '/users/:id',
      method: 'GET',
      type: 'User',
    },
    // Route with explicit file
    {
      path: '/posts',
      method: 'GET',
      type: 'Post[]',
      file: './src/types/posts.ts',
    },
    // POST route
    {
      path: '/posts',
      method: 'POST',
      type: 'Post',
    },
    // PUT route
    {
      path: '/users/:id',
      method: 'PUT',
      type: 'User',
    },
    // DELETE route
    {
      path: '/users/:id',
      method: 'DELETE',
      type: 'User',
    },
  ],
});
[/CODE BLOCK]

##
Type Resolution

TypeServe resolves types by:
Searching all TypeScript files in your project
Looking for exported types/interfaces matching the name
Using the file property if specified

Make sure your types are exported:

[CODE BLOCK]
// ✅ Good
export interface User { ... }

// ❌ Bad - not exported
interface User { ... }
[/CODE BLOCK]

##
Validation

TypeServe validates your config on startup:
• All required fields must be present
• Route paths must be valid
• HTTP methods must be 'GET', 'POST', 'PUT', or 'DELETE'
• Type names must match exported types
• Array counts must be 1-5

If validation fails, you'll see an error message with details.

---

# SECTION: Features

## Hot Reload
URL: https://typeserve.com/docs/features/hot-reload
Description: TypeServe automatically reloads when your types or config change

#
Hot Reload

TypeServe watches your files and automatically reloads the server when changes are detected. No manual restarts needed!

##
What Triggers Reload

TypeServe automatically reloads when:
Configuration changes - When typeserve.config.ts is modified
Type changes - When any TypeScript type used in your config changes
Related files - When files that contain your types are modified

##
How It Works

When you save a file, TypeServe detects the change and:
Stops the current server
Reloads the configuration
Re-parses your types (this may take a moment depending on project size)
Restarts the server with updated routes

You'll see output like:

[CODE BLOCK]
🔄 File changed: src/types.ts
🔄 Reloading server...
📖 Parsing types...
✅ Types parsed in 37.5s
🚀 Attempting to start your server on port 7002...
✅ TypeServe running on http://localhost:7002/api (started in 37.5s)
📋 Available routes:
   GET /api/users → User[]
✅ Server reloaded in 1m 12.3s
[/CODE BLOCK]

The parsing step ensures all type changes are properly reflected in the generated mock data.

##
Example Workflow

###
Start the Server

[CODE BLOCK]
npx typeserve dev
[/CODE BLOCK]

[CODE BLOCK]
📖 Loading configuration...
✅ Configuration loaded successfully
📖 Parsing types...
   This may take a while depending on the number of types and project size (est 7.0s).
✅ Types parsed in 1m 1.1s
🚀 Attempting to start your server on port 7002...
✅ TypeServe running on http://localhost:7002/api (started in 1m 1.5s)
📋 Available routes:
   GET /api/users → User
[/CODE BLOCK]

###
Modify a Type

[CODE BLOCK]
// src/types.ts
export interface User {
  id: string;
  email: string;
  name: string;
  age: number; // ← Add this field
  isActive: boolean; // ← Add this field
}
[/CODE BLOCK]

###
Save the File

TypeServe automatically detects the change:

[CODE BLOCK]
🔄 File changed: src/types.ts
🔄 Reloading server...
📖 Parsing types...
✅ Types parsed in 37.5s
🚀 Attempting to start your server on port 7002...
✅ TypeServe running on http://localhost:7002/api (started in 37.5s)
📋 Available routes:
   GET /api/users → User[]
✅ Server reloaded in 1m 12.3s
[/CODE BLOCK]

###
Test the Updated API

[CODE BLOCK]
curl http://localhost:7002/api/users
[/CODE BLOCK]

The response now includes the new fields:

[CODE BLOCK]
[
  {
    "id": "...",
    "email": "...",
    "name": "...",
    "age": 28, // ← New field
    "isActive": true // ← New field
  }
]
[/CODE BLOCK]

##
Adding New Routes

When you add a new route to your config:

[CODE BLOCK]
export default defineMock({
  routes: [
    { path: '/users', method: 'GET', type: 'User[]' },
    { path: '/posts', method: 'GET', type: 'Post[]' }, // ← New route
  ],
});
[/CODE BLOCK]

The server reloads and the new route is immediately available:

[CODE BLOCK]
🔄 File changed: src/typeserve.config.ts
🔄 Reloading server...
📖 Parsing types...
✅ Types parsed in 37.5s
🚀 Attempting to start your server on port 7002...
✅ TypeServe running on http://localhost:7002/api (started in 37.5s)
📋 Available routes:
   GET /api/users → User[]
✅ Server reloaded in 1m 12.3s
   GET /api/posts → Post[]  ← New route
[/CODE BLOCK]

##
File Watching

TypeServe watches:
• Your typeserve.config.ts file
• All TypeScript files in your project
• Files that contain types referenced in your config

##
Troubleshooting

###
Changes Not Detected

If changes aren't being detected:
Check file saving - Make sure you've saved the file
Check file location - Ensure files are in watched directories
Restart manually - Press Ctrl+C and restart if needed

###
Type Not Found After Change

If you get a "Type not found" warning:
Check exports - Ensure the type is exported
Check file path - Verify the file is in the project
Check type name - Ensure the name matches exactly (case-sensitive)

##
Best Practices

###
Save Frequently

Save your files frequently to see changes immediately. TypeServe's hot reload makes it easy to iterate quickly.

###
Watch the Console

Keep an eye on the console output to see when reloads happen and catch any errors early.

###
Test After Changes

After making changes, test your API endpoints to ensure everything works as expected.

---

## Nested Types
URL: https://typeserve.com/docs/features/nested-types
Description: TypeServe supports complex nested type structures

#
Nested Types

TypeServe fully supports nested TypeScript types, allowing you to create realistic, interconnected mock data.

##
Basic Nested Types

When a type references another type, TypeServe automatically resolves and generates the nested structure:

[CODE BLOCK]
interface User {
  id: string;
  name: string;
  email: string;
}

interface Post {
  id: string;
  title: string;
  user: User;  // Nested User type
}
[/CODE BLOCK]

Generated data:

[CODE BLOCK]
{
  "id": "123",
  "title": "My First Post",
  "user": {
    "id": "456",
    "name": "John Doe",
    "email": "john@example.com"
  }
}
[/CODE BLOCK]

##
Array of Nested Types

You can nest types in arrays:

[CODE BLOCK]
interface Comment {
  id: string;
  text: string;
  author: User;
}

interface Post {
  id: string;
  title: string;
  comments: Comment[];  // Array of nested types
}
[/CODE BLOCK]

Generated data:

[CODE BLOCK]
{
  "id": "123",
  "title": "My Post",
  "comments": [
    {
      "id": "789",
      "text": "Great post!",
      "author": {
        "id": "456",
        "name": "John Doe",
        "email": "john@example.com"
      }
    }
  ]
}
[/CODE BLOCK]

##
Deep Nesting

TypeServe handles deep nesting levels:

[CODE BLOCK]
interface Address {
  street: string;
  city: string;
  country: string;
}

interface Company {
  name: string;
  address: Address;
}

interface User {
  id: string;
  name: string;
  company: Company;  // Deeply nested
}
[/CODE BLOCK]

Generated data:

[CODE BLOCK]
{
  "id": "123",
  "name": "John Doe",
  "company": {
    "name": "Acme Corp",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "country": "USA"
    }
  }
}
[/CODE BLOCK]

##
Circular References

TypeServe handles circular references intelligently:

[CODE BLOCK]
interface User {
  id: string;
  name: string;
  posts: Post[];  // User has posts
}

interface Post {
  id: string;
  title: string;
  author: User;  // Post has author (circular)
}
[/CODE BLOCK]

When generating data, TypeServe will create the structure but avoid infinite loops by generating new instances at each level.

##
Multiple Nested Types

A single type can reference multiple other types:

[CODE BLOCK]
interface User {
  id: string;
  name: string;
}

interface Category {
  id: string;
  name: string;
}

interface Tag {
  id: string;
  name: string;
}

interface Post {
  id: string;
  title: string;
  author: User;        // Nested User
  category: Category;  // Nested Category
  tags: Tag[];         // Array of nested Tags
}
[/CODE BLOCK]

##
Best Practices

###
Organize Your Types

Keep related types together:

[CODE BLOCK]
// types/user.ts
export interface User {
  id: string;
  name: string;
}

// types/post.ts
import { User } from './user';

export interface Post {
  id: string;
  title: string;
  author: User;
}
[/CODE BLOCK]

###
Use Descriptive Names

Clear type names make nested structures easier to understand:

[CODE BLOCK]
interface BlogPost {
  id: string;
  title: string;
  author: BlogAuthor;      // Clear relationship
  comments: BlogComment[]; // Clear relationship
}
[/CODE BLOCK]

##
Examples

###
Social Media Post

[CODE BLOCK]
interface User {
  id: string;
  username: string;
  email: string;
  profilePicture: string;
}

interface Like {
  id: string;
  user: User;
  createdAt: string;
}

interface Comment {
  id: string;
  text: string;
  author: User;
  likes: Like[];
  createdAt: string;
}

interface Post {
  id: string;
  content: string;
  author: User;
  likes: Like[];
  comments: Comment[];
  createdAt: string;
}
[/CODE BLOCK]

This creates a realistic social media post structure with nested users, likes, and comments.

---

## Smart Data Generation
URL: https://typeserve.com/docs/features/smart-generation
Description: TypeServe automatically detects field patterns and generates realistic data

#
Smart Data Generation

TypeServe intelligently analyzes your TypeScript types and generates realistic mock data based on field names and patterns. No manual configuration needed!

##
How It Works

TypeServe uses pattern matching to detect common field types and generates appropriate data:

##
Detected Patterns

###
Email Fields

Fields containing email generate valid email addresses:

[CODE BLOCK]
interface User {
  email: string;        // → "john.doe@example.com"
  userEmail: string;    // → "jane.smith@example.com"
  contactEmail: string; // → "contact@example.com"
}
[/CODE BLOCK]

###
ID Fields

Fields containing id generate UUIDs:

[CODE BLOCK]
interface User {
  id: string;           // → "550e8400-e29b-41d4-a716-446655440000"
  userId: string;       // → "123e4567-e89b-12d3-a456-426614174000"
  authorId: string;     // → "987fcdeb-51a2-43f7-8b9c-123456789abc"
}
[/CODE BLOCK]

###
Date Fields

Fields containing date-related keywords generate ISO date strings:

[CODE BLOCK]
interface Post {
  createdAt: string;    // → "2024-01-15T10:30:00.000Z"
  updatedAt: string;    // → "2024-01-16T14:22:00.000Z"
  publishedAt: string;  // → "2024-01-17T09:15:00.000Z"
  deletedAt: string;    // → "2024-01-18T16:45:00.000Z"
}
[/CODE BLOCK]

###
Name Fields

Fields containing name or Name generate realistic names:

[CODE BLOCK]
interface User {
  name: string;         // → "John Doe"
  userName: string;     // → "Jane Smith"
  fullName: string;     // → "Michael Johnson"
  displayName: string;  // → "Sarah Williams"
}
[/CODE BLOCK]

###
URL Fields

Fields containing url or Url generate valid URLs:

[CODE BLOCK]
interface Post {
  url: string;          // → "https://example.com/posts/123"
  imageUrl: string;     // → "https://example.com/images/photo.jpg"
  avatarUrl: string;    // → "https://example.com/avatars/user.png"
  thumbnailUrl: string; // → "https://example.com/thumbs/thumb.jpg"
}
[/CODE BLOCK]

###
Address Fields

Fields containing address generate street addresses:

[CODE BLOCK]
interface User {
  address: string;      // → "123 Main Street, New York, NY 10001"
  homeAddress: string;  // → "456 Oak Avenue, Los Angeles, CA 90001"
}
[/CODE BLOCK]

##
Type-Based Generation

###
Strings

String fields generate random text based on context:

[CODE BLOCK]
interface Post {
  title: string;        // → "Lorem ipsum dolor sit amet"
  description: string;  // → "Consectetur adipiscing elit"
  content: string;      // → Longer text content
}
[/CODE BLOCK]

###
Numbers

Number fields generate random numbers:

[CODE BLOCK]
interface Post {
  views: number;        // → 1234
  likes: number;        // → 56
  age: number;          // → 28
  score: number;        // → 7.5
}
[/CODE BLOCK]

###
Booleans

Boolean fields generate true or false randomly:

[CODE BLOCK]
interface User {
  isActive: boolean;    // → true or false
  isVerified: boolean;  // → true or false
  isPremium: boolean;   // → true or false
}
[/CODE BLOCK]

###
Arrays

Array fields generate arrays of the specified type:

[CODE BLOCK]
interface Post {
  tags: string[];       // → ["tag1", "tag2", "tag3"]
  categories: string[]; // → ["tech", "programming"]
}
[/CODE BLOCK]

###
Enums

Enum types generate values from the enum:

[CODE BLOCK]
enum Status {
  ACTIVE = 'active',
  INACTIVE = 'inactive',
  PENDING = 'pending',
}

interface User {
  status: Status;       // → "active", "inactive", or "pending"
}
[/CODE BLOCK]

##
Examples

###
User Profile

[CODE BLOCK]
interface User {
  id: string;              // UUID
  email: string;           // Email address
  name: string;            // Full name
  age: number;             // Random number
  isActive: boolean;       // Random boolean
  createdAt: string;       // ISO date
  avatarUrl: string;       // Valid URL
  address: string;         // Street address
}
[/CODE BLOCK]

Generated data:

[CODE BLOCK]
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "age": 28,
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "avatarUrl": "https://example.com/avatars/user.jpg",
  "address": "123 Main Street, New York, NY 10001"
}
[/CODE BLOCK]

###
Blog Post

[CODE BLOCK]
interface Post {
  id: string;
  title: string;
  content: string;
  authorId: string;        // UUID
  publishedAt: string;     // ISO date
  views: number;
  likes: number;
  tags: string[];
  imageUrl: string;        // Valid URL
}
[/CODE BLOCK]

Generated data:

[CODE BLOCK]
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Getting Started with TypeScript",
  "content": "TypeScript is a powerful language...",
  "authorId": "987fcdeb-51a2-43f7-8b9c-123456789abc",
  "publishedAt": "2024-01-15T10:30:00.000Z",
  "views": 1234,
  "likes": 56,
  "tags": ["typescript", "programming", "web"],
  "imageUrl": "https://example.com/images/post.jpg"
}
[/CODE BLOCK]

##
Best Practices

###
Use Descriptive Field Names

Clear field names help TypeServe generate better data:

[CODE BLOCK]
// ✅ Good - descriptive names
interface User {
  email: string;
  fullName: string;
  createdAt: string;
}

// ❌ Less clear
interface User {
  e: string;
  n: string;
  d: string;
}
[/CODE BLOCK]

###
Leverage Pattern Detection

Use common patterns to get realistic data automatically:

[CODE BLOCK]
interface Order {
  orderId: string;         // → UUID
  customerEmail: string;   // → Email
  orderDate: string;       // → ISO date
  shippingAddress: string; // → Address
  totalAmount: number;     // → Number
}
[/CODE BLOCK]

---