Carrot

Appearance

Carrot.Data.Scaffold.Compilers.Modules.TypescriptClient ​

net

Scaffold compiler module that generates TypeScript client libraries for consuming Carrot APIs, producing complete npm packages with typed endpoints, models, commands, enums, and types.

Installation ​

xml
<ProjectReference Include="..\Carrot.Data.Scaffold.Compilers.Modules.TypescriptClient\Carrot.Data.Scaffold.Compilers.Modules.TypescriptClient.csproj" />

Architecture ​

Compiler Module ​

ScaffoldCompilerTypescriptClient extends ScaffoldCompilerModule<ScaffoldApi, ScaffoldCompilerTypescriptClientOptions>. For each API in the scaffold graph, it:

  1. Calculates the output package path under Platform/Web/packages/.generated/carrot-api-client-{api}
  2. Ensures the directory structure exists: src/endpoints, src/enums, src/types, src/models
  3. Registers renderers for the package root, src barrel, and per-item source files

Directory Structure ​

Each API produces a complete npm package:

carrot-api-client-{api}/
  package.json
  tsconfig.json
  src/
    index.ts                           # Barrel export
    endpoints/
      {Controller}.ts                  # Endpoint class per controller
    enums/
      {Enum}.ts                        # Enum type per API enum
    types/
      {Type}.ts                        # Type class per API type
    models/
      {Model}.ts                       # Model interfaces + serializer
    commands/
      {Command}.ts                     # Command types

Scoped Rendering ​

Each renderer receives a scoped context carrying:

  • FilePath - the target directory for output
  • ScaffoldApiGraphApi - the API being rendered
  • The specific graph node (controller, enum, type, model, or command)

This allows each renderer to resolve its output path relative to the package root.

Model Generation ​

Models generate TypeScript interfaces for each supported CQRS role (Get, Reference, Create, Update, Patch). The ~Serializer partial generates serialization/deserialization functions for each model variant.

Endpoint Generation ​

Each controller produces a TypeScript class with methods for every action. Methods include:

  • Typed parameters (route params, query params, request bodies)
  • Search/Sort/Pagination capability types when declared on the action
  • Typed return values matching the action's response model and CQRS role

Type Mapping ​

TypescriptTypeExtensions handles CLR-to-TypeScript type mapping (e.g. string -> string, CarrotId -> string, int -> number, bool -> boolean, DateTime/Instant -> string, etc.).

Dependencies ​

DependencyKind
Carrot.Data.Scaffold.Compilersproject (scaffold compiler framework)

Build ​

bash
dotnet build

Targets net10.0.

Usage Guide ​

Generate TypeScript client npm packages for consuming Carrot APIs from web applications.

Getting Started ​

Register the TypescriptClient module on a scaffold compiler:

csharp
IScaffoldCompiler compiler = scaffold.CreateCompiler()
    .AddModuleTypescriptClient();

Then compile:

csharp
IScaffoldCompilerResult result = compiler.Compile();

The generated packages are output to Platform/Web/packages/.generated/carrot-api-client-{api}/.

Common Patterns ​

Using a Generated Client ​

typescript
import { CarrotApi_Platform_Client } from '@carrot/api-client-platform';

const client = new CarrotApi_Platform_Client({ baseUrl: 'https://api.example.com' });

// Typed endpoint call
const response = await client.users.getUsers({
  search: { text: 'john' },
  pagination: { page: 1 },
});

Working with Generated Models ​

typescript
import { UserGet, UserCreate, UserReference } from '@carrot/api-client-platform';

// Get model (read projection)
const user: UserGet = response.data;
console.log(user.id, user.name, user.email);

// Create model (write projection)
const newUser: UserCreate = {
  name: 'Jane Doe',
  email: 'jane@example.com',
};

// Reference model (lightweight read projection)
const ref: UserReference = { id: user.id, name: user.name };

Generated Enums ​

typescript
import { UserStatus } from '@carrot/api-client-platform';

if (user.status === UserStatus.Active) {
  // ...
}

Search, Sort, and Pagination ​

When an endpoint supports these capabilities, typed parameter interfaces are generated:

typescript
import {
  UsersEndpoint_GetUsers_Search,
  UsersEndpoint_GetUsers_Sort,
  UsersEndpoint_GetUsers_Pagination,
} from '@carrot/api-client-platform';

const search: UsersEndpoint_GetUsers_Search = { text: 'john' };
const sort: UsersEndpoint_GetUsers_Sort = { sortBy: 'name', sortDirection: 'ASC' };
const pagination: UsersEndpoint_GetUsers_Pagination = { page: 1 };

Tips ​

  • Packages are generated under .generated/ - do not manually edit files in this directory; they will be overwritten on the next scaffold compile.
  • Each API gets its own npm package named carrot-api-client-{api} (lowercased). Import from the specific package for tree-shaking.
  • Model serializers are generated alongside model interfaces to handle any necessary JSON serialization/deserialization transforms.
  • The client package depends on the Carrot API client runtime - ensure @carrot/api-client-core (or equivalent) is available in your frontend project.

Carrot