libqp

libqp

Encode and decode quoted-printable strings according to RFC2045.

Usage

Install with npm

npm install libqp

libqp requires Node.js 20 or newer. It is written in TypeScript and ships both an ES module and a CommonJS build, each with type declarations.

// ES modules
import libqp from 'libqp';
// or
import { encode, decode, wrap, Encoder, Decoder } from 'libqp';

// CommonJS
const libqp = require('libqp');

Encode values

Encode Buffer objects or unicode strings with

libqp.encode(val) → String

Where

• val is a Buffer, an Uint8Array or an unicode string (encoded as UTF-8)

encode escapes whitespace at the end of a line and a hyphen at the start of a line, so the output never contains a line that could be read as a MIME boundary.

Example

libqp.encode('jõgeva');
// j=C3=B5geva

Decode values

Decode Quoted-Printable encoded strings with

libqp.decode(str) → Buffer

Where

• str is a Quoted-Printable encoded string, Buffer or Uint8Array. A Buffer is read byte for byte, so raw 8-bit bytes in the input are kept as they are. A char of a string is read as the low byte of its char code, so pass a binary string (buf.toString('binary')) rather than a unicode one

Example

libqp.decode('j=C3=B5geva').toString();
// jõgeva

Wrap encoded values

Quoted-Printable encoded lines are limited to 76 characters but encode method might return lines longer than the limit.

To enforce soft line breaks on lines longer than 76 (or any other length) characters, use wrap

libqp.wrap(str[, lineLength]) → String

Where

• str is a Quoted-Printable encoded string
• lineLength (defaults to 76) is the maximum allowed line length. Any longer line will be soft wrapped. Values below 4 are raised to 4, the shortest line that fits an escape sequence and a soft line break. Every line is wrapped on its own and a line break does not count towards the line length

Example

libqp.wrap('abc j=C3=B5geva', 10);
// abc j=\r\n
// =C3=B5geva

Transform Streams

libqp makes it possible to encode and decode streams with libqp.Encoder and libqp.Decoder constructors.

Encoder Stream

Create new Encoder Stream with

const encoder = new libqp.Encoder([options])

Where

• options is the optional stream options object with additional options:
  • lineLength if you want to use any other line length than the default 76 characters (or set to false to turn the soft wrapping off completely)
  • binary set to true if the input is binary data. A CR or LF that is not part of a CRLF pair is then encoded, so that line ending conversions on the way can not change the data

Example

The following example script reads in a file, encodes it to Quoted-Printable and saves the output to a file.

import fs from 'node:fs';
import { Encoder } from 'libqp';

const source = fs.createReadStream('source.txt');
const encoded = fs.createWriteStream('encoded.txt');

source.pipe(new Encoder()).pipe(encoded);

Decoder Stream

Create new Decoder Stream with

const decoder = new libqp.Decoder([options])

Where

• options is the optional stream options object

The Decoder collects its input and decodes it once the input ends, so escape sequences and soft line breaks split between chunks are decoded correctly.

Example

The following example script reads in a file in Quoted-Printable encoding, decodes it and saves the output to a file.

import fs from 'node:fs';
import { Decoder } from 'libqp';

const encoded = fs.createReadStream('encoded.txt');
const dest = fs.createWriteStream('dest.txt');

encoded.pipe(new Decoder()).pipe(dest);

License

MIT