UTF-8 FDF Generator

A modern ESM library for generating FDF (PDF Form Data Format) files with full Unicode support.

Features

• Full Unicode Support: Properly encodes non-ASCII characters using UTF-16BE with BOM
• Modern ESM: Native ES modules with import/export syntax
• TypeScript Support: Includes type definitions
• Node.js 22+: Built for modern Node.js with native test runner
• Zero Dependencies: No external dependencies
• Async/Await: Promise-based API for file operations
• Buffer API: Get FDF content as a Buffer for streaming or HTTP responses

Installation

npm install utf8-fdf-generator

Usage

Basic Usage

import { generator } from 'utf8-fdf-generator';

// Generate FDF file with form field data
await generator({
  firstName: 'John',
  lastName: 'Doe',
  email: '[email protected]'
}, 'output.fdf');

Unicode Characters

The library properly handles any Unicode characters including:

• Spanish: Ciudad Juárez, México
• Japanese: 東京, こんにちは
• Chinese: 北京, 张三
• Arabic: القاهرة
• Cyrillic: Москва
• And more...

import { generator } from 'utf8-fdf-generator';

await generator({
  name: 'José García',
  city: '東京',
  greeting: 'Привет мир'
}, 'international.fdf');

Get FDF as Buffer

If you need the FDF content without writing to a file (e.g., for HTTP responses):

import { generateFdfBuffer } from 'utf8-fdf-generator';

const buffer = generateFdfBuffer({
  field1: 'value1',
  field2: 'value2'
});

// Use with Express
res.type('application/vnd.fdf').send(buffer);

Special Characters

Parentheses and backslashes are automatically escaped:

await generator({
  path: 'C:\\Users\\Documents\\file.pdf',
  note: 'See section (a) and (b)'
}, 'output.fdf');

API Reference

generator(data, fileName)

Generates an FDF file and writes it to disk.

Parameters:

• data (Record<string, string | boolean | number>) - Object with field names and values
• fileName (string) - Output file path

Returns: Promise<void>

Throws: TypeError if data is not an object or fileName is not a string

generateFdf(data)

Generates FDF content and returns it as a Buffer.

Parameters:

• data (Record<string, string | boolean | number>) - Object with field names and values

Returns: Buffer - Complete FDF file content

Throws: TypeError if data is not an object

generateFdfBuffer(data)

Alias for generateFdf(). Generates FDF content and returns it as a Buffer.

Using with pdftk

After generating an FDF file, you can use it to fill a PDF form:

pdftk template.pdf fill_form generated.fdf output filled.pdf flatten

Where:

• template.pdf - Original PDF form with fillable fields
• generated.fdf - FDF file generated by this library
• filled.pdf - Output PDF with form fields filled
• flatten - (Optional) Makes form fields non-editable

FDF Format

FDF (Forms Data Format) is an Adobe format for representing form data. This library generates FDF files that:

• Use version FDF-1.2
• Include binary indicator bytes for proper handling
• Encode non-ASCII text using UTF-16BE with BOM (Byte Order Mark)
• Properly escape special characters (parentheses, backslashes)

Requirements

• Node.js 22.0.0 or higher

Testing

npm test

TypeScript

Type definitions are included. Import types if needed:

import type { FdfFieldData } from 'utf8-fdf-generator';

const data: FdfFieldData = {
  name: 'John Doe',
  active: true,
  count: 42
};

Migration from v0.x

If upgrading from version 0.x:

1. ESM Import: Change require() to import

   // Old
   const { generator } = require('utf8-fdf-generator');
   
   // New
   import { generator } from 'utf8-fdf-generator';

2. Async/Await: The generator function now returns a Promise (it was always async, but the docs said otherwise)

   // Old (worked but wasn't properly awaited)
   generator(data, 'output.fdf');
   
   // New (properly await the result)
   await generator(data, 'output.fdf');

3. Node.js Version: Requires Node.js 22+ (was "any" version)

License

MIT

Author

Vlado Velichkovski [email protected]

Links

• Repository
• Issues