TypeScript Usage

This guide covers TypeScript usage with Flowfull Clients.

Type Safety

All Flowfull Client packages include TypeScript definitions out of the box. No additional @types packages are needed.

Defining Entity Types

Define your entity types for type-safe API calls:

// types/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
  userType: 'admin' | 'user' | 'guest';
  createdAt: string;
  updatedAt: string;
}

Typed API Calls

Use your entity types with the Bridge API hooks:

import { useBridgeApi, useBridgeQuery } from '@pubflow/react';
import { User } from './types/user';

function UserList() {
  const userService = useBridgeApi<User>({
    endpoint: 'users'
  });
  
  const { data, isLoading } = useBridgeQuery(
    userService,
    'list',
    { page: 1, limit: 20 }
  );
  
  // data is typed as User[] | undefined
  return (
    <ul>
      {data?.map(user => (
        <li key={user.id}>
          {user.name} - {user.email}
        </li>
      ))}
    </ul>
  );
}

Typed Mutations

import { useBridgeApi, useBridgeMutation } from '@pubflow/react';
import { User } from './types/user';

function CreateUser() {
  const userService = useBridgeApi<User>({
    endpoint: 'users'
  });
  
  const { mutate: createUser } = useBridgeMutation(
    userService,
    'create'
  );
  
  async function handleCreate() {
    const newUser: Partial<User> = {
      name: 'John Doe',
      email: 'john@example.com',
      userType: 'user'
    };
    
    const result = await createUser({ data: newUser });
    // result.data is typed as User
  }
  
  return <button onClick={handleCreate}>Create User</button>;
}

Typed Authentication

import { useAuth } from '@pubflow/react';
import { User } from './types/user';

function Profile() {
  const { user, isAuthenticated } = useAuth();
  
  // user is typed as User | null
  if (!isAuthenticated || !user) {
    return <div>Not authenticated</div>;
  }
  
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <p>Type: {user.userType}</p>
    </div>
  );
}

Custom Types

Query Parameters

import { QueryParams } from '@pubflow/core';

interface UserQueryParams extends QueryParams {
  userType?: 'admin' | 'user' | 'guest';
  status?: 'active' | 'inactive';
}

function FilteredUserList() {
  const userService = useBridgeApi<User>({ endpoint: 'users' });
  
  const { data } = useBridgeQuery(
    userService,
    'list',
    { 
      userType: 'admin',
      status: 'active',
      limit: 20
    } as UserQueryParams
  );
  
  return <div>{/* ... */}</div>;
}

Mutation Results

import { MutationResult } from '@pubflow/core';

async function handleUpdate(userId: string, data: Partial<User>) {
  const result: MutationResult<User, 'update'> = await updateUser(
    { id: userId, data }
  );
  
  if (result.success) {
    console.log('Updated user:', result.data);
  } else {
    console.error('Error:', result.error);
  }
}

Type Inference

Flowfull Clients provide excellent type inference:

const { data, meta } = useBridgeQuery(
  userService,
  'list',
  { page: 1, limit: 20 }
);

// data is automatically typed as User[] | undefined
// meta is automatically typed as PaginationMeta | null

Generic Components

Create reusable components with generics:

import { useBridgeApi, useBridgeQuery } from '@pubflow/react';

interface EntityListProps<T> {
  endpoint: string;
  renderItem: (item: T) => React.ReactNode;
}

function EntityList<T extends { id: string }>({ 
  endpoint, 
  renderItem 
}: EntityListProps<T>) {
  const service = useBridgeApi<T>({ endpoint });
  const { data, isLoading } = useBridgeQuery(
    service,
    'list',
    { limit: 20 }
  );
  
  if (isLoading) return <div>Loading...</div>;
  
  return (
    <ul>
      {data?.map(item => (
        <li key={item.id}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

// Usage
<EntityList<User>
  endpoint="users"
  renderItem={(user) => <span>{user.name}</span>}
/>

Next Steps

• API Reference: Types - Complete types reference
• Examples - See TypeScript examples in action