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:

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

Route Properties

`path` (required)

The endpoint path. Supports Express-style route parameters:

{ path: '/users', ... }           // /api/users
{ path: '/users/:id', ... }       // /api/users/123
{ path: '/posts/:id/comments', ... } // /api/posts/123/comments

`method` (required)

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

{ method: 'GET', ... }    // GET request
{ method: 'POST', ... }   // POST request
{ method: 'PUT', ... }    // PUT request
{ method: 'DELETE', ... } // DELETE request

`type` (required)

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

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

`file` (optional)

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

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

`count` (optional)

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

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

Examples

Single Object Route

{
  path: '/users/:id',
  method: 'GET',
  type: 'User',
}

Returns a single User object.

Array Route

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

Returns an array of 3 User objects.

POST Route

{
  path: '/posts',
  method: 'POST',
  type: 'Post',
}

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

PUT Route

{
  path: '/users/:id',
  method: 'PUT',
  type: 'User',
}

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

DELETE Route

{
  path: '/users/:id',
  method: 'DELETE',
  type: 'User',
}

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

Route with Parameters

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

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

Complete Example

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',
    },
  ],
});

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:

// ✅ Good - exported
export interface User { ... }

// ❌ Bad - not exported
interface User { ... }

Routes

On this page