Skip to content
Query.Farm
Talk with Us

Value representations

On this page

rich vs raw, the branded unit types, and the codec that converts between them.

function asDate32

Section titled “function asDate32”
source
export function asDate32(days: number): Date32

Description

date32 days: validated as a 32-bit integer day-number, then branded.

function asDate64Ms

Section titled “function asDate64Ms”
source
export function asDate64Ms(ms: bigint): Date64Ms

Description

date64 ms: validated as a 64-bit integer, then branded.

function asDurationMicros

Section titled “function asDurationMicros”
source
const asDurationMicros = (b: bigint): DurationMicros =>
validateBigInt(int64Type(), b) as unknown as DurationMicros

Description

duration[us].

function asDurationMillis

Section titled “function asDurationMillis”
source
const asDurationMillis = (b: bigint): DurationMillis =>
validateBigInt(int64Type(), b) as unknown as DurationMillis

Description

duration[ms].

function asDurationNanos

Section titled “function asDurationNanos”
source
const asDurationNanos = (b: bigint): DurationNanos =>
validateBigInt(int64Type(), b) as unknown as DurationNanos

Description

duration[ns].

function asDurationSeconds

Section titled “function asDurationSeconds”
source
const asDurationSeconds = (b: bigint): DurationSeconds =>
validateBigInt(int64Type(), b) as unknown as DurationSeconds

Description

duration[s].

function asInt64

Section titled “function asInt64”
source
const asInt64 = (b: bigint): Int64 =>
validateBigInt(int64Type(), b) as unknown as Int64

Description

int64 (validated for signed 64-bit range).

function asTime32Ms

Section titled “function asTime32Ms”
source
const asTime32Ms = (n: number): Time32Ms => asTime32(“asTime32Ms”, n) as Time32Ms

Description

time32[ms].

function asTime32S

Section titled “function asTime32S”
source
const asTime32S = (n: number): Time32S => asTime32(“asTime32S”, n) as Time32S

Description

time32[s].

function asTime64Ns

Section titled “function asTime64Ns”
source
const asTime64Ns = (b: bigint): Time64Ns =>
validateBigInt(int64Type(), b) as unknown as Time64Ns

Description

time64[ns].

function asTime64Us

Section titled “function asTime64Us”
source
const asTime64Us = (b: bigint): Time64Us =>
validateBigInt(int64Type(), b) as unknown as Time64Us

Description

time64[us].

function asTimestampMicros

Section titled “function asTimestampMicros”
source
const asTimestampMicros = (b: bigint): TimestampMicros =>
validateBigInt(int64Type(), b) as unknown as TimestampMicros

Description

timestamp[us].

function asTimestampMillis

Section titled “function asTimestampMillis”
source
const asTimestampMillis = (b: bigint): TimestampMillis =>
validateBigInt(int64Type(), b) as unknown as TimestampMillis

Description

timestamp[ms].

function asTimestampNanos

Section titled “function asTimestampNanos”
source
const asTimestampNanos = (b: bigint): TimestampNanos =>
validateBigInt(int64Type(), b) as unknown as TimestampNanos

Description

timestamp[ns].

function asTimestampSeconds

Section titled “function asTimestampSeconds”
source
const asTimestampSeconds = (b: bigint): TimestampSeconds =>
validateBigInt(int64Type(), b) as unknown as TimestampSeconds

Description

timestamp[s].

function asUint64

Section titled “function asUint64”
source
const asUint64 = (b: bigint): Uint64 =>
validateBigInt(uint64Type(), b) as unknown as Uint64

Description

uint64 (validated for unsigned 64-bit range).

function asUnscaledDecimal

Section titled “function asUnscaledDecimal”
source
export function asUnscaledDecimal(unscaled: bigint): UnscaledDecimal

Description

A decimal’s unscaled integer (validated as a bigint, then branded).

interface BinaryType

Section titled “interface BinaryType”
source
export interface BinaryType extends VgiDataType

Fields

typeIdtypeof TypeId.Binary

interface BoolType

Section titled “interface BoolType”
source
export interface BoolType extends VgiDataType

Fields

typeIdtypeof TypeId.Bool

type Branded

Section titled “type Branded”
source
export type Branded<Base, Tag extends string> = Base & {
readonly [__brand]: Tag;
};

Description

A nominal brand over a base primitive. Branded<number, 'date32'> is a number at runtime but a distinct type at compile time.

interface Codec

Section titled “interface Codec”
source
export interface Codec

Description

Codec for a single Arrow type. Converts between the author-facing rich representation and the internal canonical pivot. Both directions validate and throw on invalid/lossy input. null/undefined pass through as null.

(Raw<->canonical conversions are reserved for a later phase. When added they belong here as rawToCanonical / canonicalToRaw.)

Fields

labelstring

Human-readable type label, used in error messages.

richToCanonical(value: unknown): unknown

rich author value -> canonical pivot.

canonicalToRich(value: unknown): unknown

canonical pivot -> rich author value.

rawToCanonical(value: unknown): unknown

branded raw author value -> canonical pivot. Largely identity on the underlying number/bigint (raw === canonical for every type), but validates and unbrands. Date32/Date64 raw values are plain day-number / ms-bigint, so this differs from richToCanonical only in NOT accepting a JS Date.

canonicalToRaw(value: unknown): unknown

canonical pivot -> branded raw author value. Validates and brands (identity at runtime).

function codecFor

Section titled “function codecFor”
source
export function codecFor(type: VgiDataType): Codec

Description

Resolve the {@link Codec} for an Arrow type. Dispatches by typeId and reads unit / bitWidth / scale off the type. Composite types recurse into their child codecs.

type Date32

Section titled “type Date32”
source
export type Date32 = Branded<number, “date32”>;

Description

date32 raw: days since the Unix epoch.

interface Date32Type

Section titled “interface Date32Type”
source
export interface Date32Type extends VgiDataType

Description

date32 (unit DAY) — days.

Fields

typeIdtypeof TypeId.Date

type Date64Ms

Section titled “type Date64Ms”
source
export type Date64Ms = Branded<bigint, “date64ms”>;

Description

date64 raw: milliseconds since the Unix epoch.

interface Date64Type

Section titled “interface Date64Type”
source
export interface Date64Type extends VgiDataType

Description

date64 (unit MILLISECOND) — ms.

Fields

typeIdtypeof TypeId.Date

interface DecimalType

Section titled “interface DecimalType”
source
export interface DecimalType extends VgiDataType

Fields

typeIdtypeof TypeId.Decimal

interface DictionaryType

Section titled “interface DictionaryType”
source
export interface DictionaryType<V extends VgiDataType> extends VgiDataType

Fields

typeIdtypeof TypeId.Dictionary

type DurationMicros

Section titled “type DurationMicros”
source
export type DurationMicros = Branded<bigint, “dur_us”>;

Description

duration[us] raw.

type DurationMillis

Section titled “type DurationMillis”
source
export type DurationMillis = Branded<bigint, “dur_ms”>;

Description

duration[ms] raw.

type DurationNanos

Section titled “type DurationNanos”
source
export type DurationNanos = Branded<bigint, “dur_ns”>;

Description

duration[ns] raw.

type DurationSeconds

Section titled “type DurationSeconds”
source
export type DurationSeconds = Branded<bigint, “dur_s”>;

Description

duration[s] raw.

interface DurationType

Section titled “interface DurationType”
source
export interface DurationType<U extends TUnit> extends VgiDataType

Fields

typeIdtypeof TypeId.Duration

interface FixedSizeBinaryType

Section titled “interface FixedSizeBinaryType”
source
export interface FixedSizeBinaryType extends VgiDataType

Fields

typeIdtypeof TypeId.FixedSizeBinary

interface FixedSizeListType

Section titled “interface FixedSizeListType”
source
export interface FixedSizeListType<T extends VgiDataType> extends VgiDataType

Fields

typeIdtypeof TypeId.FixedSizeList

interface FloatType

Section titled “interface FloatType”
source
export interface FloatType extends VgiDataType

Fields

typeIdtypeof TypeId.Float

function fromBranded

Section titled “function fromBranded”
source
export function fromBranded<Base, Tag extends string>(v: Branded<Base, Tag>): Base

Description

Generic unbrand for either base type.

function fromBrandedBigInt

Section titled “function fromBrandedBigInt”
source
export function fromBrandedBigInt(v: Branded<bigint, string>): bigint

Description

Strip a bigint brand, returning the plain bigint.

function fromBrandedNumber

Section titled “function fromBrandedNumber”
source
export function fromBrandedNumber(v: Branded<number, string>): number

Description

Strip a numeric brand, returning the plain number.

type Int16Type

Section titled “type Int16Type”
source
export type Int16Type = IntType<16, true>;

type Int32Type

Section titled “type Int32Type”
source
export type Int32Type = IntType<32, true>;

type Int64Raw

Section titled “type Int64Raw”
source
export type Int64 = Branded<bigint, “int64”>;

Description

int64 raw. (Rich int64 is already a plain bigint; the brand makes the declared width explicit in raw mode.)

type Int64Type

Section titled “type Int64Type”
source
export type Int64Type = IntType<64, true>;

type Int8Type

Section titled “type Int8Type”
source
export type Int8Type = IntType<8, true>;

interface IntervalType

Section titled “interface IntervalType”
source
export interface IntervalType extends VgiDataType

Fields

typeIdtypeof TypeId.Interval

interface IntType

Section titled “interface IntType”
source
export interface IntType<BW extends 8 | 16 | 32 | 64, Signed extends boolean>
extends VgiDataType

Fields

typeIdtypeof TypeId.Int

interface LargeBinaryType

Section titled “interface LargeBinaryType”
source
export interface LargeBinaryType extends VgiDataType

Fields

typeIdtypeof TypeId.LargeBinary

interface LargeUtf8Type

Section titled “interface LargeUtf8Type”
source
export interface LargeUtf8Type extends VgiDataType

Fields

typeIdtypeof TypeId.LargeUtf8

interface ListType

Section titled “interface ListType”
source
export interface ListType<T extends VgiDataType> extends VgiDataType

Fields

typeIdtypeof TypeId.List

interface MapType

Section titled “interface MapType”
source
export interface MapType<K extends VgiDataType, V extends VgiDataType> extends VgiDataType

Fields

typeIdtypeof TypeId.Map

interface NullDescriptor

Section titled “interface NullDescriptor”
source
export interface NullDescriptor extends VgiDataType

Fields

typeIdtypeof TypeId.Null

type RawValue

Section titled “type RawValue”
source
export type RawValue<T extends VgiDataType> =
T extends NullDescriptor ? null :
T extends BoolType ? boolean :
T extends IntType<64, infer S> ? RawInt64<S> :
T extends IntType<8 | 16 | 32, infer _S> ? number :
T extends FloatType ? number :
T extends Utf8Type ? string :
T extends LargeUtf8Type ? string :
T extends BinaryType ? Uint8Array :
T extends LargeBinaryType ? Uint8Array :
T extends FixedSizeBinaryType ? Uint8Array :
T extends DecimalType ? UnscaledDecimal :
T extends Date32Type ? Date32 :
T extends Date64Type ? Date64Ms :
T extends Time32Type<infer U> ? RawTime32<U> :
T extends Time64Type<infer U> ? RawTime64<U> :
T extends TimestampType<infer U> ? RawTimestamp<U> :
T extends DurationType<infer U> ? RawDuration<U> :
T extends StructType<infer C> ? RawStruct<C> :
T extends ListType<infer E> ? Array<RawValue<E> | null> :
T extends FixedSizeListType<infer E> ? Array<RawValue<E> | null> :
T extends MapType<infer K, infer V> ? Array<[RawValue<K>, RawValue<V> | null]> :
T extends DictionaryType<infer V> ? RawValue<V> :
unknown;

Description

The branded raw JS value for the Arrow type T.

type Repr

Section titled “type Repr”
source
export type Repr = “rich” | “raw”;

Description

Representation mode selector.

type RichValue

Section titled “type RichValue”
source
export type RichValue<T extends VgiDataType> =
T extends NullDescriptor ? null :
T extends BoolType ? boolean :
T extends IntType<64, infer _S> ? bigint :
T extends IntType<8 | 16 | 32, infer _S> ? number :
T extends FloatType ? number :
T extends Utf8Type ? string :
T extends LargeUtf8Type ? string :
T extends BinaryType ? Uint8Array :
T extends LargeBinaryType ? Uint8Array :
T extends FixedSizeBinaryType ? Uint8Array :
T extends DecimalType ? bigint :
// date32 / date64 -> JS Date (the ONLY rich != canonical case)
T extends Date32Type ? Date :
T extends Date64Type ? Date :
T extends Time32Type<"s" | "ms"> ? number :
T extends Time64Type<"us" | "ns"> ? bigint :
T extends TimestampType<TUnit> ? bigint :
T extends DurationType<TUnit> ? bigint :
T extends StructType<infer C> ? RichStruct<C> :
T extends ListType<infer E> ? Array<RichValue<E> | null> :
T extends FixedSizeListType<infer E> ? Array<RichValue<E> | null> :
T extends MapType<infer K, infer V> ? Array<[RichValue<K>, RichValue<V> | null]> :
T extends DictionaryType<infer V> ? RichValue<V> :
unknown;

Description

The default author-facing JS value for the Arrow type T.

interface StructType

Section titled “interface StructType”
source
export interface StructType<Children extends readonly TypedField<string, VgiDataType>[]>
extends VgiDataType

Description

Struct descriptor carrying its children as a tuple of TypedFields so the value mapping can build a precise { name: value } shape.

Fields

typeIdtypeof TypeId.Struct

type Time32Ms

Section titled “type Time32Ms”
source
export type Time32Ms = Branded<number, “time32ms”>;

Description

time32[ms] raw: milliseconds since midnight.

type Time32S

Section titled “type Time32S”
source
export type Time32S = Branded<number, “time32s”>;

Description

time32[s] raw: seconds since midnight.

interface Time32Type

Section titled “interface Time32Type”
source
export interface Time32Type<U extends “s” | “ms”> extends VgiDataType

Description

time32 (bitWidth 32; unit s or ms).

Fields

typeIdtypeof TypeId.Time

type Time64Ns

Section titled “type Time64Ns”
source
export type Time64Ns = Branded<bigint, “time64ns”>;

Description

time64[ns] raw: nanoseconds since midnight.

interface Time64Type

Section titled “interface Time64Type”
source
export interface Time64Type<U extends “us” | “ns”> extends VgiDataType

Description

time64 (bitWidth 64; unit us or ns).

Fields

typeIdtypeof TypeId.Time

type Time64Us

Section titled “type Time64Us”
source
export type Time64Us = Branded<bigint, “time64us”>;

Description

time64[us] raw: microseconds since midnight.

type TimestampMicros

Section titled “type TimestampMicros”
source
export type TimestampMicros = Branded<bigint, “ts_us”>;

Description

timestamp[us] raw.

type TimestampMillis

Section titled “type TimestampMillis”
source
export type TimestampMillis = Branded<bigint, “ts_ms”>;

Description

timestamp[ms] raw.

type TimestampNanos

Section titled “type TimestampNanos”
source
export type TimestampNanos = Branded<bigint, “ts_ns”>;

Description

timestamp[ns] raw.

type TimestampSeconds

Section titled “type TimestampSeconds”
source
export type TimestampSeconds = Branded<bigint, “ts_s”>;

Description

timestamp[s] raw.

interface TimestampType

Section titled “interface TimestampType”
source
export interface TimestampType<U extends TUnit> extends VgiDataType

Fields

typeIdtypeof TypeId.Timestamp

type TUnit

Section titled “type TUnit”
source
export type TUnit = “s” | “ms” | “us” | “ns”;

Description

Time/timestamp/duration unit tag (matches the facade TimeUnit integers, but expressed as a string literal so it can flow through the type level).

interface TypedField

Section titled “interface TypedField”
source
export interface TypedField<Name extends string, T extends VgiDataType> extends VgiField

Description

A typed field carrying its child’s precise descriptor in the static type.

Fields

nameName
typeT

type Uint16Type

Section titled “type Uint16Type”
source
export type Uint16Type = IntType<16, false>;

type Uint32Type

Section titled “type Uint32Type”
source
export type Uint32Type = IntType<32, false>;

type Uint64Raw

Section titled “type Uint64Raw”
source
export type Uint64 = Branded<bigint, “uint64”>;

Description

uint64 raw.

type Uint64Type

Section titled “type Uint64Type”
source
export type Uint64Type = IntType<64, false>;

type Uint8Type

Section titled “type Uint8Type”
source
export type Uint8Type = IntType<8, false>;

interface UnionType

Section titled “interface UnionType”
source
export interface UnionType extends VgiDataType

Fields

typeIdtypeof TypeId.Union

type UnscaledDecimal

Section titled “type UnscaledDecimal”
source
export type UnscaledDecimal = Branded<bigint, “decimal_unscaled”>;

Description

A decimal’s UNSCALED integer (the on-wire representation).

interface Utf8Type

Section titled “interface Utf8Type”
source
export interface Utf8Type extends VgiDataType

Fields

typeIdtypeof TypeId.Utf8

type ValueFor

Section titled “type ValueFor”
source
export type ValueFor<T extends VgiDataType, M extends Repr> = M extends "raw"
? RawValue<T>
: RichValue<T>;

Description

The JS value for the Arrow type T under representation mode M.