The minimalistic document archiving platform.
import type { ApiHandlerInput, ApiHandlerResult, ApiRoute } from './api.routes';
import * as v from 'valibot';
import { describe, expectTypeOf, test } from 'vitest';
import { defineApiContract } from './api.contracts';
import { defineApiRoute } from './api.routes';
const wireDateSchema = v.pipe(
v.union([v.date(), v.string()]),
v.transform((value) => new Date(value).toISOString()),
);
const contract = defineApiContract({
operationId: 'updateItem',
method: 'POST',
path: '/api/items/:id',
request: {
params: v.object({ id: v.pipe(v.string(), v.transform(Number)) }),
query: v.object({ limit: v.optional(v.pipe(v.string(), v.transform(Number)), '10') }),
body: {
'application/json': v.object({
name: v.string(),
count: v.pipe(v.string(), v.transform(Number)),
}),
},
},
responses: {
200: {
description: 'An item or its name.',
content: {
'application/json': {
schema: v.object({
name: v.string(),
createdAt: wireDateSchema,
tags: v.array(v.string()),
}),
},
'text/plain': { schema: v.string() },
},
},
400: {
description: 'An error.',
content: { 'application/json': { schema: v.object({ error: v.string() }) } },
},
204: { description: 'No content.', content: {} },
205: { description: 'Reset content.', content: {} },
304: { description: 'Not modified.', content: {} },
},
});
describe('defineApiRoute types', () => {
test('handlers infer parsed request outputs and retain their contract', () => {
const route = defineApiRoute({
contract,
handler: async ({ body, query, params, request }) => {
expectTypeOf(body).toEqualTypeOf<{ name: string; count: number }>();
expectTypeOf(query).toEqualTypeOf<{ limit: number }>();
expectTypeOf(params).toEqualTypeOf<{ id: number }>();
expectTypeOf(request).toEqualTypeOf<Request>();
return {
status: 200,
contentType: 'application/json',
body: { name: body.name, createdAt: new Date().toISOString(), tags: ['item'] },
};
},
});
expectTypeOf(route).toEqualTypeOf<ApiRoute<typeof contract>>();
expectTypeOf(route.contract.operationId).toEqualTypeOf<'updateItem'>();
expectTypeOf(route.contract.method).toEqualTypeOf<'POST'>();
expectTypeOf(route.contract.path).toEqualTypeOf<'/api/items/:id'>();
expectTypeOf(route.contract.responses[200].content['application/json'].schema).toEqualTypeOf<
(typeof contract.responses)[200]['content']['application/json']['schema']
>();
});
test('missing schemas produce empty query and params objects and an undefined body, without inferring the path', () => {
defineApiRoute({
contract: defineApiContract({
operationId: 'getItem',
method: 'GET',
path: '/api/items/:id',
responses: { 204: { description: 'No content.', content: {} } },
}),
handler: async ({ body, query, params, context }) => {
expectTypeOf(context).toEqualTypeOf<undefined>();
expectTypeOf(body).toEqualTypeOf<undefined>();
expectTypeOf(query).toEqualTypeOf<Record<string, never>>();
expectTypeOf(params).toEqualTypeOf<Record<string, never>>();
return { status: 204 };
},
});
});
test('async context resolvers infer a required handler context without changing request or response inference', () => {
const route = defineApiRoute({
contract,
resolveContext: async (input) => {
expectTypeOf(input).toEqualTypeOf<{ request: Request }>();
return { requestId: input.request.headers.get('X-Request-Id') ?? 'unknown' };
},
handler: async ({ context, body, params, query }) => {
expectTypeOf(context).toEqualTypeOf<{ requestId: string }>();
expectTypeOf(body).toEqualTypeOf<{ name: string; count: number }>();
expectTypeOf(params).toEqualTypeOf<{ id: number }>();
expectTypeOf(query).toEqualTypeOf<{ limit: number }>();
return { status: 200, contentType: 'text/plain', body: context.requestId };
},
});
expectTypeOf<Parameters<typeof route.handler>[0]['context']>().toEqualTypeOf<{
requestId: string;
}>();
});
test('reusable synchronous context resolvers retain their context type', () => {
const resolveContext = ({ request }: { request: Request }) => ({ url: new URL(request.url) });
const route = defineApiRoute({
contract,
resolveContext,
handler: async ({ context }) => {
expectTypeOf(context).toEqualTypeOf<{ url: URL }>();
return { status: 200, contentType: 'text/plain', body: context.url.pathname };
},
});
expectTypeOf(route).toEqualTypeOf<ApiRoute<typeof contract, typeof resolveContext>>();
expectTypeOf(route.resolveContext).toEqualTypeOf<typeof resolveContext>();
expectTypeOf<{ contract: typeof contract; handler: typeof route.handler }>().not.toMatchTypeOf<
typeof route
>();
});
test('a possibly absent resolver makes the handler context possibly undefined', () => {
function createRoute(resolveContext: (() => { requestId: string }) | undefined) {
return defineApiRoute({
contract,
resolveContext,
handler: async ({ context }) => {
expectTypeOf(context).toEqualTypeOf<{ requestId: string } | undefined>();
return { status: 200, contentType: 'text/plain', body: context?.requestId ?? 'unknown' };
},
});
}
createRoute(undefined);
createRoute(() => ({ requestId: 'request-1' }));
});
test('an optional resolver in route options preserves the possibility of an undefined context', () => {
function createRoute(options: { resolveContext?: () => { requestId: string } }) {
return defineApiRoute({
contract,
...options,
handler: async ({ context }) => {
expectTypeOf(context).toEqualTypeOf<{ requestId: string } | undefined>();
return { status: 200, contentType: 'text/plain', body: context?.requestId ?? 'unknown' };
},
});
}
createRoute({});
createRoute({ resolveContext: () => ({ requestId: 'request-1' }) });
});
test('handlers cannot invent context fields or bypass response types when a resolver is present', () => {
const resolveContext = () => ({ requestId: 'request-1' });
const invalidContextHandler = async ({
context,
}: ApiHandlerInput<typeof contract, { requestId: string; extra: boolean }>) => ({
status: 200 as const,
contentType: 'text/plain' as const,
body: context.requestId,
});
const invalidResponseHandler = async ({
context,
}: ApiHandlerInput<typeof contract, { requestId: string }>) => ({
status: 201 as const,
contentType: 'text/plain' as const,
body: context.requestId,
});
// @ts-expect-error The resolver does not provide the extra context field.
defineApiRoute({ contract, resolveContext, handler: invalidContextHandler });
// @ts-expect-error Context resolution does not permit an undeclared response status.
defineApiRoute({ contract, resolveContext, handler: invalidResponseHandler });
});
test('multiple request content types produce a union of parsed body outputs', () => {
defineApiRoute({
contract: defineApiContract({
operationId: 'createItem',
method: 'POST',
path: '/api/items',
request: {
body: {
'application/json': v.object({ count: v.pipe(v.string(), v.transform(Number)) }),
'text/plain': v.string(),
},
},
responses: { 204: { description: 'No content.', content: {} } },
}),
handler: async ({ body, query, params }) => {
expectTypeOf(body).toEqualTypeOf<{ count: number } | string>();
expectTypeOf(query).toEqualTypeOf<Record<string, never>>();
expectTypeOf(params).toEqualTypeOf<Record<string, never>>();
return { status: 204 };
},
});
});
test('response status and content type discriminate schema outputs, including bodyless statuses', () => {
expectTypeOf<ApiHandlerResult<typeof contract>>().toEqualTypeOf<
| {
status: 200;
contentType: 'application/json';
body: { name: string; createdAt: string; tags: string[] };
headers?: Record<string, string>;
}
| { status: 200; contentType: 'text/plain'; body: string; headers?: Record<string, string> }
| {
status: 400;
contentType: 'application/json';
body: { error: string };
headers?: Record<string, string>;
}
| { status: 204; contentType?: never; body?: never; headers?: Record<string, string> }
| { status: 205; contentType?: never; body?: never; headers?: Record<string, string> }
| { status: 304; contentType?: never; body?: never; headers?: Record<string, string> }
>();
defineApiRoute({
contract,
handler: async ({ body }) => {
if (body.count < 0) {
return { status: 400, contentType: 'application/json', body: { error: 'Invalid count' } };
}
if (body.count === 0) {
return { status: 204, headers: { 'X-Empty': 'true' } };
}
return { status: 200, contentType: 'text/plain', body: body.name };
},
});
});
test('handlers cannot widen the contract by returning an undeclared status or content type', () => {
defineApiRoute({
contract,
// @ts-expect-error Only statuses declared by the contract are allowed.
handler: async () => ({
status: 201,
contentType: 'application/json',
body: { error: 'Invalid' },
}),
});
defineApiRoute({
contract,
// @ts-expect-error This content type exists for 200, not 400.
handler: async () => ({ status: 400, contentType: 'text/plain', body: 'Invalid' }),
});
defineApiRoute({
contract,
// @ts-expect-error Undeclared content types cannot be returned.
handler: async () => ({ status: 200, contentType: 'text/html', body: 'Invalid' }),
});
});
test('response bodies must match the output schema for their status and content type', () => {
defineApiRoute({
contract,
// @ts-expect-error Schema input accepts Date, but handlers must return the string output.
handler: async () => ({
status: 200,
contentType: 'application/json',
body: { name: 'Item', createdAt: new Date(), tags: [] },
}),
});
defineApiRoute({
contract,
// @ts-expect-error This JSON body belongs to status 400, not 200.
handler: async () => ({
status: 200,
contentType: 'application/json',
body: { error: 'Invalid' },
}),
});
defineApiRoute({
contract,
// @ts-expect-error Plain text responses must use the declared string output.
handler: async () => ({ status: 200, contentType: 'text/plain', body: { name: 'Item' } }),
});
});
test('contentful responses require both a content type and a body', () => {
defineApiRoute({
contract,
// @ts-expect-error Content-Type cannot be omitted for a contentful response.
handler: async () => ({ status: 200, body: 'Item' }),
});
defineApiRoute({
contract,
// @ts-expect-error A body cannot be omitted for a contentful response.
handler: async () => ({ status: 200, contentType: 'text/plain' }),
});
});
test('bodyless statuses reject bodies and content types', () => {
defineApiRoute({
contract,
// @ts-expect-error Bodyless statuses cannot carry a body.
handler: async () => ({ status: 204, body: 'Item' }),
});
defineApiRoute({
contract,
// @ts-expect-error Bodyless statuses cannot specify a content type.
handler: async () => ({ status: 304, contentType: 'application/json' }),
});
});
test('bodyless statuses cannot declare response content in their contract', () => {
defineApiContract({
operationId: 'deleteItem',
method: 'DELETE',
path: '/api/items/:id',
responses: {
204: {
description: 'No content.',
content: {
// @ts-expect-error Bodyless statuses cannot declare a payload schema.
'application/json': { schema: v.string() },
},
},
},
});
});
test('HEAD handlers return only status and headers regardless of status code', () => {
const headContract = defineApiContract({
operationId: 'headItem',
method: 'HEAD',
path: '/api/items/:id',
responses: {
200: { description: 'Item metadata.', content: {} },
404: { description: 'Item not found.', content: {} },
},
});
expectTypeOf<ApiHandlerResult<typeof headContract>>().toEqualTypeOf<
| { status: 200; contentType?: never; body?: never; headers?: Record<string, string> }
| { status: 404; contentType?: never; body?: never; headers?: Record<string, string> }
>();
const route = defineApiRoute({
contract: headContract,
handler: async () => ({
status: 200,
headers: { 'Content-Type': 'application/json', 'Content-Length': '123' },
}),
});
expectTypeOf(route.contract.method).toEqualTypeOf<'HEAD'>();
defineApiRoute({
contract: headContract,
// @ts-expect-error HEAD responses cannot carry a body, even with a contentful status.
handler: async () => ({ status: 200, body: 'Item' }),
});
defineApiRoute({
contract: headContract,
// @ts-expect-error Representation metadata belongs in headers, not a body content type.
handler: async () => ({ status: 200, contentType: 'text/plain' }),
});
defineApiRoute({
contract: headContract,
// @ts-expect-error HEAD responses still require a declared status.
handler: async () => ({ status: 201 }),
});
});
test('HEAD contracts cannot declare response payload schemas', () => {
// @ts-expect-error All HEAD response statuses are bodyless.
defineApiContract({
operationId: 'headItem',
method: 'HEAD',
path: '/api/items/:id',
responses: {
200: {
description: 'Item metadata.',
content: { 'text/plain': { schema: v.string() } },
},
},
});
});
test('exported input types preserve request outputs', () => {
expectTypeOf<ApiHandlerInput<typeof contract>>().toEqualTypeOf<{
body: { name: string; count: number };
query: { limit: number };
params: { id: number };
request: Request;
context: undefined;
}>();
});
});