@twilic/fastify

Twilic plugin, parser, and reply helpers for Fastify.

Package: @twilic/fastify
Peer dependencies: fastify, @twilic/core
Source: github.com/twilic/fastify

Install

pnpm add @twilic/fastify fastify @twilic/core

Quick start

import Fastify from "fastify";
import { init } from "@twilic/core";
import { twilicPlugin, twilicParser, twilicReply } from "@twilic/fastify";

await init();

const app = Fastify();
await app.register(twilicPlugin);

app.post("/data", { preHandler: twilicParser() }, (request, reply) => {
  return twilicReply(reply, { ok: true, received: request.twilicBody });
});

Exports

Constants

export const TWILIC_CONTENT_TYPE = "application/vnd.twilic";

Plugin

twilicPlugin(options?)

Registers the reply.twilic() decorator.

const twilicPlugin: FastifyPluginAsync<TwilicPluginOptions>;

After registration:

app.get("/ping", (_request, reply) => reply.twilic({ pong: true }));

Functions

twilicParser(options?)

Pre-handler that decodes body into request.twilicBody.

function twilicParser(
  options?: TwilicParserOptions,
): preHandlerAsyncHookHandler;

twilicReply(reply, value, init?)

Send Twilic response.

function twilicReply(
  reply: FastifyReply,
  value: TwilicValue,
  init?: TwilicReplyInit,
): FastifyReply;

createTwilicFastify(codec?)

Factory with custom codec.

Types

interface TwilicPluginOptions {
  codec?: TwilicCodec;
}

interface TwilicReplyInit {
  statusCode?: number;
  headers?: Record<string, string>;
}

interface TwilicParserOptions {
  requireContentType?: boolean;
}

Content type parser

The plugin registers handling for application/vnd.twilic so Fastify preserves raw binary bodies for Twilic routes.

Custom codec example

import { encodeBatch, decode, encode } from "@twilic/core/advanced";

await app.register(twilicPlugin, {
  codec: {
    encode: (v) => (Array.isArray(v) ? encodeBatch(v) : encode(v)),
    decode,
  },
});

Related

• Express middleware
• Hono middleware
• Examples — HTTP Round-Trip