Node.js Buffers

Node.js’s custom Buffer HostObjects.

extensions.NodeJsArrayBufferViewHostObjectHandler

extensions.NodeJsArrayBufferViewHostObjectHandler()

Support for deserializing ArrayBuffer views from NodeJS’s custom serialization.

NodeJS uses its own method of serializing ArrayBuffer views instead of the default V8 serialization. It encodes them in HostObject tag data (HostObject tags are the V8 serialization format’s way to allow an application to insert their own custom data into the serialized data).

Tip

Support for Node.js custom ArrayBuffer views is enabled by default (using this) by loads() and can be controlled by its nodejs option.

It’s not required to enable Node.js’s custom ArrayBuffer view serialization to send buffers to Node.js, because Node.js also supports the default ArrayBuffer view encoding V8 serialization format, so it’s not enabling it results in wider compatibility. However it can be enabled using serialize_js_array_buffer_views_as_nodejs_host_object with the encode_steps option of dumps().

Examples

Serialize a Buffer from Node.JS something like:

$ node --version
v22.4.0
$ node -e 'console.log(
    require("v8").serialize(Uint8Array.from([1, 2, 3]))
        .toString("base64"))'
/w9cAQMBAgM=

>>> from v8serialize import loads, TagReader
>>> from base64 import b64decode
>>> decode_steps = [TagReader(
...   host_object_deserializer=NodeJsArrayBufferViewHostObjectHandler()
... )]
>>> loads(b64decode('/w9cAQMBAgM='), decode_steps=decode_steps)
JSUint8Array(JSArrayBuffer(b'\x01\x02\x03'))

Methods

Name	Description
deserialize_host_object	Read a HostObject from the stream as a Node.JS ArrayBuffer/TypedArray.
serialize_host_object	Serialize JSDataView and JSTypedArray using Node.js’s custom HostObject format.

deserialize_host_object

extensions.NodeJsArrayBufferViewHostObjectHandler.deserialize_host_object(
    stream: ReadableTagStream,
)

Read a HostObject from the stream as a Node.JS ArrayBuffer/TypedArray.

Returns

Name	Type	Description
	JSDataView | JSTypedArray	The buffer wrapped in a view.

Raises

Name	Type	Description
	NodeJsArrayBufferViewHostObjectHandlerDecodeError	When the stream’s HostObject data is not a valid Node.JS Buffer.

serialize_host_object

extensions.NodeJsArrayBufferViewHostObjectHandler.serialize_host_object(
    stream: WritableTagStream,
    value: JSDataView | JSTypedArray,
)

Serialize JSDataView and JSTypedArray using Node.js’s custom HostObject format.

See Also

serialize_js_array_buffer_views_as_nodejs_host_object

extensions.serialize_js_array_buffer_views_as_nodejs_host_object

extensions.serialize_js_array_buffer_views_as_nodejs_host_object(
    value: object,
    /,
    ctx: EncodeContext,
    next: EncodeNextFn,
)

Serialize JSDataView and JSTypedArray using node.js’s custom HostObject format.

Notes

This is an encode step that can be used as one of the encode_steps with dumps() or Encoder().

It encodes JSDataView and JSTypedArray in the same custom HostObject format that Node.JS writes using the Node.JS v8.serialize() function.

Because Node.JS is capable of reading the normal encoding of JSArrayBuffer, JSDataView and JSTypedArray, this doesn’t need to be used to send data to Node.JS (unlike on the deserializing side, where NodeJsArrayBufferViewHostObjectHandler must be used to read Node.JS’s custom encoding).

extensions.ViewFormat

extensions.ViewFormat(
    nodejs_code: int,
    view_format: ArrayBufferViewStructFormat,
)

extensions.NodeBufferFormat

extensions.NodeBufferFormat(value: int | ArrayBufferViewTag | NodeBufferFormat)

extensions.NodeJsArrayBufferViewHostObjectHandlerDecodeError

extensions.NodeJsArrayBufferViewHostObjectHandlerDecodeError(
    message: str,
    *args: object,
    position: int,
    data: ReadableBinary,
)

Raised when decoding a HostObject as a Node.JS Buffer fails.