ping

Purpose

Provides Zod schemas for the admin ping endpoint (GET /admin/ping). The ping endpoint is the simplest possible health indicator — it verifies that the server is alive, the request pipeline is functional, and the clock is ticking. These schemas are used by server route handlers, monitoring systems, and the OpenAPI generator to define the contract for this sentinel endpoint.

Features

AdminPingInput schema — empty object (no input required); useful as a typed placeholder for framework plugins that require a body schema
AdminPingOutput schema — {pong: true, timestamp} where pong is a typed literal and timestamp is an ISO 8601 string with timezone offset
pong: z.literal(true) ensures TypeScript narrows the field to true, not boolean
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { AdminPingOutput } from "@suaveplan/api-schemas/admin";

const response = AdminPingOutput.parse({
  pong: true,
  timestamp: new Date().toISOString(),
});
// → { pong: true, timestamp: "2024-06-01T12:00:00.000Z" }

Usage: Advanced Example

import { AdminPingInput, AdminPingOutput } from "@suaveplan/api-schemas/admin";

// Route handler using both input and output schemas
async function handlePing(_rawBody: unknown): Promise<AdminPingOutput> {
  AdminPingInput.parse(_rawBody); // no-op for empty body, ensures shape check
  return AdminPingOutput.parse({
    pong: true,
    timestamp: new Date().toISOString(),
  });
}

API Reference

`AdminPingInput`

Zod object schema — empty input (no fields).

Type export: type AdminPingInput = z.infer<typeof AdminPingInput>

`AdminPingOutput`

Zod object schema — ping response.

Field	Type	Description
`pong`	`true` (literal)	Confirms endpoint reachability
`timestamp`	`string` (ISO 8601 with offset)	Server clock time at request processing

Type export: type AdminPingOutput = z.infer<typeof AdminPingOutput>

Implementation Notes

The pong field uses z.literal(true) rather than z.boolean() to make the success state an unambiguous type-level fact — TypeScript will infer pong: true not pong: boolean, enabling exhaustiveness checks. The timestamp is included so monitoring tools can detect clock skew between the client and server without an additional round-trip to a time endpoint. The AdminPingInput empty-object schema exists to keep route plugin signatures uniform: every endpoint has both an input and an output schema.

2.7 KiB Raw Blame History