arkyn
ChangelogGuides
docs / server / introduction

Introduction to @arkyn/server

@arkyn/server is a comprehensive server-side utility library designed for building robust HTTP APIs. It provides standardized HTTP responses, validation utilities, form parsing, and debugging tools that integrate seamlessly with modern web frameworks like React Router, Remix, and Hono.

Why @arkyn/server?

Building APIs requires consistent error handling, response formatting, and input validation. @arkyn/server solves these challenges by providing a unified set of tools that ensure your server responses are predictable, well-structured, and easy to debug.
Key benefits:
  • Standardized responses: Pre-built HTTP response classes for both success (200, 201, 204, 302) and error (400, 401, 403, 404, 409, 422, 500, 501, 502) scenarios
  • Built-in debugging: Automatic console logging showing exactly where responses originated in your codebase
  • Form validation: Seamless integration with Zod schemas for both sync and async validation
  • Type-safe: Written in TypeScript with full type definitions for excellent IDE support
  • Framework agnostic: Works with any framework that uses the Web API Request and Response objects

Installation

bash

bun add @arkyn/server
@arkyn/server declares zod (>=4.4.3) and libphonenumber-js (>=1.13.7) as peer dependencies, so install them alongside it:

bash

bun add zod libphonenumber-js
zod is required because SchemaValidator validates data against Zod schemas, and libphonenumber-js is required for phone number validation utilities such as validatePhone.

Module Overview

The library is organized into five main categories, each serving a specific purpose:

Bad Responses

Standardized HTTP error response classes that automatically emit debug logs and provide consistent response structures. Includes BadRequest (400), Unauthorized (401), Forbidden (403), NotFound (404), Conflict (409), UnprocessableEntity (422), ServerError (500), NotImplemented (501), and BadGateway (502).

ts

import { BadRequest } from "@arkyn/server/badRequest";
import { NotFound } from "@arkyn/server/notFound";
import { UnprocessableEntity } from "@arkyn/server/unprocessableEntity";


// Throw errors with descriptive messages
throw new NotFound("User not found");


// Form validation errors with field-specific messages
throw new UnprocessableEntity({
    message: "Validation failed",
    fieldErrors: { email: "Invalid email format" },
    fields: { email: "invalid-email" },
});

Success Responses

Standardized HTTP success response classes for successful operations. Includes Success (200), Created (201), NoContent (204), Updated (200), and Found (302).

ts

import { Created } from "@arkyn/server/created";
import { Success } from "@arkyn/server/success";
import { NoContent } from "@arkyn/server/noContent";


// Return created resource
return new Created("User created successfully", {
    id: "123",
    name: "John",
}).toResponse();


// Return data
return new Success("Users retrieved", users).toJson();


// No content response
return new NoContent("Resource deleted").toResponse();

Services

Service classes for API communication, debugging, and logging configuration.

ts

import { ApiService } from "@arkyn/server/apiService";
import { DebugService } from "@arkyn/server/debugService";
import { LogService } from "@arkyn/server/logService";


// Configure API client
const api = new ApiService({
    baseUrl: "https://api.example.com",
    baseHeaders: { "Content-Type": "application/json" },
    enableDebug: true,
});


const users = await api.get("/users", { urlParams: { page: "1" } });


// Configure debug service for accurate caller detection
DebugService.setIgnoreFile("httpAdapter.ts");


// Configure log service for centralized logging
LogService.setConfig({
    trafficSourceId: "my-app",
    serviceToken: "auth-token",
});

Utilities

Functions for form parsing, schema validation, request handling, and debugging.

ts

import { SchemaValidator } from "@arkyn/server/schemaValidator";
import { formParse } from "@arkyn/server/formParse";
import { getScopedParams } from "@arkyn/server/getScopedParams";
import { z } from "zod";


// Schema validation with multiple strategies
const schema = z.object({ name: z.string().min(1), email: z.string().email() });
const validator = new SchemaValidator(schema);


validator.isValid(data); // Boolean check
validator.validate(data); // Throws ServerError
validator.formValidate(data); // Throws UnprocessableEntity


// Extract scoped query parameters
const filters = getScopedParams(request, "filter");
// ?filter:status=active&filter:type=user → { status: "active", type: "user" }

Validations

Async validation functions for common data types including email (with DNS verification), Brazilian documents (CPF, CNPJ, CEP, RG), phone numbers, passwords, and dates.

ts

import { validateEmail } from "@arkyn/server/validateEmail";
import { validateCpf } from "@arkyn/server/validateCpf";
import { validateCnpj } from "@arkyn/server/validateCnpj";


// Email validation with DNS verification
const isValidEmail = await validateEmail("user@example.com");


// Document validation
const isValidCpf = await validateCpf("123.456.789-09");
const isValidCnpj = await validateCnpj("12.345.678/0001-90");

Design Philosophy

@arkyn/server follows these core principles:
  1. Consistency: All responses follow the same structure, making API consumption predictable
  2. Debuggability: Built-in debug logging shows exactly where responses originated
  3. Flexibility: Use toResponse() for standard responses or toJson() for Response.json() alternative
  4. Integration ready: Works seamlessly with Arkyn's frontend components for form error handling

Using with AI coding assistants

@arkyn/server ships its own AGENTS.md file inside the published package (available at node_modules/@arkyn/server/AGENTS.md after install), a reference written specifically for AI coding assistants like Claude Code, Cursor, or Copilot. It documents every response class, service, utility, and validation function's exact signature and behavior, so your assistant doesn't need to read the source to use the library correctly.
Run @arkyn/cli once in your project to link it in:

bash

npx @arkyn/cli init --agents
This writes a marked block into your project's AGENTS.md pointing at @arkyn/server's bundled docs (and those of any other installed @arkyn/* package). Rerun it whenever you add or remove Arkyn packages. See the @arkyn/cli introduction for details.
On this page
    arkyn