Structured clone

This is the structured-clone section of niso_runtime.h, owned by niso-structured-clone and kept in crates/niso-structured-clone/include/structured-clone.h. The build composes it with the other sections in the order crates/niso-compose/sections.txt gives.

Functions: niso_structured_clone_decode, niso_structured_clone_free, niso_structured_clone_value, niso_structured_clone_entry

Structured serialization (docs/structured-clone.md): how an IDL any value crosses the C API (history.state, a PerformanceMark’s detail, a message’s niso_message_event_serialized_data). A decoded serialization is a graph: the value, and objects a value refers to by number, each with entries. Every reference to one object has its number, so shared objects and cycles can be rebuilt. Strings are UTF-8, with a JS string’s lone surrogates as U+FFFD. Decoding needs no DOM and works on any thread.

typedef struct niso_structured_clone niso_structured_clone;

enum {
    NISO_CLONE_UNDEFINED = 0,
    NISO_CLONE_NULL = 1,
    NISO_CLONE_BOOLEAN = 2,         /* number: 0 or 1 */
    NISO_CLONE_NUMBER = 3,          /* number */
    NISO_CLONE_BIGINT = 4,          /* bytes: magnitude, least significant byte first; negative */
    NISO_CLONE_STRING = 5,          /* string */
    /* Objects, from here on: object is the object's number. */
    NISO_CLONE_BOOLEAN_OBJECT = 16, /* number: 0 or 1 */
    NISO_CLONE_NUMBER_OBJECT = 17,  /* number */
    NISO_CLONE_BIGINT_OBJECT = 18,  /* bytes, negative, as NISO_CLONE_BIGINT */
    NISO_CLONE_STRING_OBJECT = 19,  /* string */
    NISO_CLONE_DATE = 20,           /* number: ms since the epoch */
    NISO_CLONE_REGEXP = 21,         /* string: the source; entry "flags" */
    NISO_CLONE_ARRAY_BUFFER = 22,   /* bytes; number: a resizable one's max byte length, else -1 */
    NISO_CLONE_VIEW = 23,           /* string: "Uint8Array", "DataView", ...; bytes: what it views
                                       (none when its buffer was transferred); entry "buffer" */
    NISO_CLONE_MAP = 24,            /* entries: each key and value */
    NISO_CLONE_SET = 25,            /* entries: each value, its key undefined */
    NISO_CLONE_ERROR = 26,          /* string: "Error", "TypeError", ...; entries "message", "stack"
                                       and "cause", those it has */
    NISO_CLONE_ARRAY = 27,          /* number: its length; entries: its properties ("0", "1", ...) */
    NISO_CLONE_OBJECT = 28,         /* entries: its properties */
    NISO_CLONE_PLATFORM = 29,       /* string: its interface ("DOMException", "DOMRect", ...); entry "data" */
    NISO_CLONE_TRANSFERRED = 30,    /* number: its index among a message's ports */
};

typedef struct niso_clone_value {
    uint32_t kind;    /* a NISO_CLONE_* value */
    uint32_t object;  /* an object's number */
    double number;
    niso_str string;
    niso_bytes bytes;
    bool negative;
    size_t entries;   /* an object's entry count, for niso_structured_clone_entry */
} niso_clone_value;

Decodes a serialization, or returns NULL when the bytes are not one (or nest objects more than 256 deep, or are NULL). What it hands out lives until niso_structured_clone_free.

niso_structured_clone* niso_structured_clone_decode(const uint8_t* bytes, size_t len);
void niso_structured_clone_free(niso_structured_clone* clone);

The serialized value; NISO_CLONE_UNDEFINED for a NULL clone.

niso_clone_value niso_structured_clone_value(const niso_structured_clone* clone);

An object’s entry: a property’s key is a string, as are the named entries above; a Map’s is any value. Returns NISO_NOT_FOUND_ERROR when there is no such entry, or no clone.

int32_t niso_structured_clone_entry(const niso_structured_clone* clone, uint32_t object, size_t index, niso_clone_value* key,
                                    niso_clone_value* value);