serovalv1.7.0

Plugins

Using plugins

Add support for more types with plugins, and use the web plugins from seroval-plugins.

Plugins teach seroval new types. Pass them in the plugins option of any function, on both the sending and the receiving side.

JavaScript
import { serializeAsync } from 'seroval';
import { BlobPlugin } from 'seroval-plugins/web';

const blob = new Blob(['Hello'], { type: 'text/plain' });

await serializeAsync(blob, { plugins: [BlobPlugin] });

Every function takes plugins, including fromJSON, fromCrossJSON, createCrossDeserializer and Serializer. The receiver needs a plugin with the same tag as the one the sender used, or decoding throws SerovalMissingPluginError.

When several plugins accept the same value, the first one in the list wins. A plugin can depend on other plugins, which are then added for you.

seroval-plugins

The seroval-plugins package has plugins for common web platform types.

Terminal
npm install seroval-plugins
JavaScript
import {
  FormDataPlugin,
  HeadersPlugin,
  RequestPlugin,
  URLPlugin,
} from 'seroval-plugins/web';

Some types can only be read asynchronously. A Blob's bytes, for example, are only available through a promise. Those plugins work only with the async and streaming functions.

PluginTypeSyncAsyncStreaming
URLPluginURL✅✅✅
URLSearchParamsPluginURLSearchParams✅✅✅
HeadersPluginHeaders✅✅✅
FormDataPluginFormData✅ 1✅✅ 1
BlobPluginBlob❌✅❌ 2
FilePluginFile❌✅❌ 2
ReadableStreamPluginReadableStream❌✅✅
RequestPluginRequest❌✅✅
ResponsePluginResponse❌✅✅
EventPluginEvent✅✅✅
CustomEventPluginCustomEvent✅✅✅
DOMExceptionPluginDOMException✅✅✅
ImageDataPluginImageData✅✅✅
AbortSignalPluginAbortSignal✅✅✅

To use every web plugin at once:

JavaScript
import * as web from 'seroval-plugins/web';

const plugins = Object.values(web);

Writing your own

See Writing plugins. If your plugin decodes data from a client, also read Plugin security.

Footnotes

  1. Only when the FormData contains no Blob or File entries. ↩ ↩2

  2. A Blob is built synchronously but its bytes can only be read asynchronously, so a stream cannot represent it as the same type. ↩ ↩2