Data types

This page describes how we map Liquid data types to JavaScript, and how to define your own objects that play nicely with Liquid tags, filters and operators.

Primitive types

In "standard" Liquid, primitive literals are Boolean, Null, Integer, Float, String and Range. Internally, LiquidScript maps these Liquid literals to JavaScript types as follows:

Primitive literal	JavaScript type	Example Liquid literal
Boolean	boolean	true or false
Null	null	null or nil
Integer	Integer	123, 0, -7
Float	Float	1.23, 0.1
String	string	"Hello" or 'Hello'
Range		(1..5) or (x..y)

Although there is no literal syntax for creating arrays or objects (aka Hash), many Liquid tags and filters operate on or expect arrays and objects, and standard variable path notation is designed to traverse nested arrays and objects.

note

Liquid has weak typing. Anywhere a particular type is expected, Liquid with automatically try to convert a value to the required type.

Number wrapper

Unlike JavaScript's number type, Liquid has distinct integer and float types. The type of a number literal effects the result of some math filters and the number's string representation when output. Additionally, math filters exclusively perform decimal arithmetic, not floating point arithmetic.

For these reasons, LiquidScript stores all literal numbers as instances of LiquidNumber, and coerces JavaScript numbers to LiquidNumber when given as inputs to tags and filters.

User defined types

A drop is a developer-defined type that plays nicely with Liquid tags, filters and/or operators. Drops are often used to implement lazy data retrieval or dynamic logic depending on the active render context.

All drops extend Drop and override one or more methods. The base drop is falsy, is an empty iterable, is equal to nothing and renders as an empty string.

note

All default async methods delegate to their sync equivalents. So, if you don't need to perform IO in your drop, you can safely implement sync methods only.

Each overridable method is a symbol according to the following table. Refer to the Drop API for details of arguments passed to each method.

Methods	Description
[toLiquid], [toLiquidSync]	Coerce the drop to a primitive Liquid type given a context hint.
[toHTMLSafeString], [toHTMLSafeStringSync]	Returns an HTML-safe string (it's either trusted or already escaped) that will not be escaped when autoEscape is enabled.
[dispatch] and [dispatchSync]	The method called when Liquid attempts to resolve an otherwise undefined property name against a drop.
[isInvocable]	Return true if the argument string is the name of a method that Liquid is allowed to call.
[length], [slice], [sliceSync], [Symbol.asyncIterator] and [Symbol.iterator]	These methods make up the (possibly lazy) iterator protocol for use with the built-in {% for %} tag.
[equals], [contains], [containsSync], [lessThan] and [lessThanSync]	These methods allow for drops to be compared to primitives and other drops using operators such as =, < and contains.