Repository files navigation

An env agnostic serializer and deserializer with recursion ability and types beyondJSON from theHTML standard itself.

• Supported Types
  • not supported yet: Blob, File, FileList, ImageBitmap, ImageData or others nonJS types but typed arrays are supported without major issues, but u/int8, u/int16, and u/int32 are the only safely suppored (right now).
  • not possible to implement: the{transfer: []} option can be passed but it's completely ignored.
• MDN Documentation
• Serializer
• Deserializer

Serialized values can be safely stringified asJSON too, and deserialization resurrect all values, even recursive, or more complex than whatJSON allows.

Check the100% test coverage to know even more.

// as default exportimportstructuredClonefrom'@ungap/structured-clone';constcloned=structuredClone({any:'serializable'});// as independent serializer/deserializerimport{serialize,deserialize}from'@ungap/structured-clone';// the result can be stringified as JSON without issues// even if there is recursive data, bigint values,// typed arrays, and so onconstserialized=serialize({any:'serializable'});// the result will be a replica of the original objectconstdeserialized=deserialize(serialized);

Note: Only monkey patch the global if needed. This polyfill works just fine as an explicit import:import structuredClone from "@ungap/structured-clone"

// Attach the polyfill as a Global functionimportstructuredClonefrom"@ungap/structured-clone";if(!("structuredClone"inglobalThis)){globalThis.structuredClone=structuredClone;}// Or don't monkey patchimportstructuredClonefrom"@ungap/structured-clone"// Just use it in the filestructuredClone()

Note: Do not attach this module's default export directly to the global scope, whithout a conditional guard to detect a native implementation. In environments where there is a native global implementation ofstructuredClone() already, assignment to the global object will result in an infinite loop whenglobalThis.structuredClone() is called. See the example above for a safe way to provide the polyfill globally in your project.

There is no middle-ground between the structured clone algorithm and JSON:

• JSON is more relaxed about incompatible values: it just ignores these
• Structured clone is inflexible regarding incompatible values, yet it makes specialized instances impossible to reconstruct, plus it doesn't offer any helper, such astoJSON(), to make serialization possible, or better, with specific cases

This module specializedserialize export offers, within the optional extra argument, alossy property to avoid throwing when incompatible types are found down the road (function, symbol, ...), so that it is possible to send with less worrying about thrown errors.

// as default exportimportstructuredClonefrom'@ungap/structured-clone';constcloned=structuredClone({method(){// ignored, won't be cloned},special:Symbol('also ignored')},{// avoid throwinglossy:true,// avoid throwing *and* looks for toJSONjson:true});

The behavior is the same found inJSON when it comes toArray, so that unsupported values will result asnull placeholders instead.

Iflossy option is not enough,json will actually enforcelossy and also check fortoJSON method when objects are parsed.

Alternative, thejson exports combines all features:

import{stringify,parse}from'@ungap/structured-clone/json';parse(stringify({any:'serializable'}));