Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

4.5 KB
Raw Blame
import type { ApiContract } from '@papra/app-server/api/contract';
import type {
  ClientMethod,
  ClientRequest,
  ClientResponse,
  ContractClient,
} from './contract-client.types';
import * as v from 'valibot';
import { describe, expectTypeOf, test } from 'vitest';

const contracts = {
  getItemContract: {
    operationId: 'getItem',
    method: 'GET',
    path: '/api/items',
    responses: {
      200: {
        description: 'An item.',
        content: { 'application/json': { schema: v.object({ name: v.string() }) } },
      },
    },
  },
  updateItemContract: {
    operationId: 'updateItem',
    method: 'PUT',
    path: '/api/items/:id',
    request: {
      params: v.object({ id: v.pipe(v.string(), v.transform(Number)) }),
      query: v.object({ page: v.optional(v.pipe(v.string(), v.transform(Number)), '1') }),
      body: { 'application/json': v.object({ count: v.pipe(v.string(), v.transform(Number)) }) },
    },
    responses: {
      200: {
        description: 'A count.',
        content: {
          'application/json': {
            schema: v.object({ count: v.pipe(v.string(), v.transform(Number)) }),
          },
        },
      },
      201: {
        description: 'An id.',
        content: { 'application/json': { schema: v.object({ id: v.string() }) } },
      },
      204: { description: 'No content.', content: {} },
      400: {
        description: 'Invalid input.',
        content: { 'application/json': { schema: v.object({ error: v.string() }) } },
      },
    },
  },
  searchItemsContract: {
    operationId: 'searchItems',
    method: 'GET',
    path: '/api/items/search',
    request: { query: v.object({ search: v.string() }) },
    responses: { 204: { description: 'No content.', content: {} } },
  },
} as const satisfies Record<string, ApiContract>;

describe('contract client types', () => {
  test('request types use schema inputs, before transformations and defaults', () => {
    expectTypeOf<ClientRequest<typeof contracts.updateItemContract>>().toEqualTypeOf<
      {
        params: { id: string };
      } & {
        query?: { page?: string };
      } & {
        body: { count: string };
      }
    >();
  });

  test('response types contain parsed successful bodies, excluding HTTP errors', () => {
    expectTypeOf<ClientResponse<typeof contracts.updateItemContract>>().toEqualTypeOf<
      { count: number } | { id: string } | void
    >();
    expectTypeOf<ClientResponse<typeof contracts.searchItemsContract>>().toEqualTypeOf<void>();
  });

  test('methods require only their declared inputs and use operation IDs', () => {
    expectTypeOf<keyof ContractClient<typeof contracts>>().toEqualTypeOf<
      'getItem' | 'updateItem' | 'searchItems'
    >();
    expectTypeOf<ClientMethod<typeof contracts.getItemContract>>().toBeCallableWith();
    expectTypeOf<ClientMethod<typeof contracts.updateItemContract>>().toBeCallableWith({
      params: { id: '123' },
      body: { count: '2' },
    });
    expectTypeOf<ClientMethod<typeof contracts.searchItemsContract>>().toBeCallableWith({
      query: { search: 'Alice' },
    });

    // Compile-only calls: invalid invocations must not issue real requests.
    function checkInputs(client: ContractClient<typeof contracts>) {
      // @ts-expect-error An update requires its body and path parameters.
      void client.updateItem();
      // @ts-expect-error Path parameters cannot be omitted.
      void client.updateItem({ body: { count: '2' } });
      // @ts-expect-error The body accepts the wire string, not the server's parsed number.
      void client.updateItem({ params: { id: '123' }, body: { count: 2 } });
      // @ts-expect-error This endpoint has no request body.
      void client.getItem({ body: { name: 'Alice' } });
      // @ts-expect-error A required query cannot be omitted.
      void client.searchItems();
      // @ts-expect-error Methods cannot override the contract's HTTP method.
      void client.getItem({ method: 'POST' });
      // @ts-expect-error Unknown methods are not exposed.
      void client.deleteItem();
      // @ts-expect-error Registry export names are not exposed as methods.
      void client.getItemContract();
    }

    expectTypeOf(checkInputs).toBeFunction();
  });

  test('a query consisting only of optional fields allows a no-argument call', () => {
    const contract = {
      ...contracts.getItemContract,
      request: { query: v.object({ limit: v.optional(v.string(), '10') }) },
    };

    expectTypeOf<ClientMethod<typeof contract>>().toBeCallableWith();
    expectTypeOf<ClientMethod<typeof contract>>().toBeCallableWith({ query: { limit: '20' } });
  });
});