Primitives

Python equivalents of JavaScript primitives that don’t have a natural Python analogue.

jstypes.JSUndefined

jstypes.JSUndefined

Represents the JavaScript value undefined.

jstypes.JSPrimitiveObject

jstypes.JSPrimitiveObject(
    value: PrimitiveObjectValue | int,
    tag: PrimitiveObjectTag | None = None,
)

Python equivalent of a wrapped/boxed JavaScript primitive.

Tip

This is a low-level type that won’t occur in decoded data by default, and can be ignored.

If you do want it to occur in decoded data, pass the js_primitive_objects=True option to loads() or TagReader.

JavaScript primitives like string and number have object wrapper types like String and Number which are used when calling methods on primitives. JSPrimitiveObject represents primitives wrapped in this way.

In JavaScript, the difference between a wrapped and plain primitive is not visible, and the same is the case by default with v8serialize, as the default decoding behaviour is to unwrap wrapped primitive objects. So users of v8serialize shouldn’t encounter this type in decoded values, and don’t need to handle it.

JSPrimitiveObject has two main uses:

It allows primitive values to be serialized once and referenced multiple times in a V8 serialized data stream. This could be used to de-duplicate strings or bigints.
It allows data streams to be round-tripped exactly.

Each tag has a single value type:

`tag`	JavaScript	Python `value`
kTrueObject	`true`	`True`
kFalseObject	`false`	`False`
kNumberObject	`number`	`float`
kBigIntObject	`bigint`	`JSBigInt`
kStringObject	`string`	`str`

The constructor infers the tag automatically given a value of one of these Python types.

An int value is inferred as kNumberObject if it’s in FLOAT64_SAFE_INT_RANGE, otherwise kBigIntObject. The int is converted to float or JSBigInt according to the inferred tag.

Parameters

Name	Type	Description	Default
value	PrimitiveObjectValue \| int	The Python type representing the wrapped JavaScript primitive value.	required
tag	PrimitiveObjectTag \| None	The serialization tag that identifies the type of the wrapped primitive. Inferred from the value if `None`.	`None`

Attributes

Name	Description
tag	The type of primitive wrapped in this object.
value	The primitive value.

jstypes.PrimitiveObjectValue

jstypes.PrimitiveObjectValue

The types that can be wrapped in a JSPrimitiveObject.