Arguments

On this page

Declaring a signature, and reading the values that arrive.

interface ArgumentConstraints

source

export interface ArgumentConstraints

Description

Raw per-argument constraint declarations, as authored on a function’s argument descriptor. Encoded into the pre-computed {@link ArgumentSpec} constraint fields via {@link constraintSpecFields}.

Fields

choicesreadonly unknown[]optional

Closed set of allowed values (JSON-encoded into vgi_choices).

genumberoptional

Inclusive lower bound (>=).

lenumberoptional

Inclusive upper bound (<=).

gtnumberoptional

Exclusive lower bound (>).

ltnumberoptional

Exclusive upper bound (<).

patternstringoptional

Regex the value must match (surfaced as vgi_pattern, as-is).

defaultunknownoptional

Default value (JSON-encoded into vgi_default); optional args only.

class Arguments

source

export class Arguments

Properties

property positional

source

readonly positional: (any | null)[];

property named

source

readonly named: Map<string, any | null>;

property argumentsSchema

source

readonly argumentsSchema: VgiSchema | null;

Schema of the arguments batch (preserves original Arrow types).

property length

source

get length(): number

Methods

method get

source

get(position: number | string, defaultValue?: any): any

Get an argument by position (number) or name (string).

interface ArgumentSpec

source

export interface ArgumentSpec

Fields

namestring

positionnumber | string

arrowTypeVgiDataType

isTableInputbooleanoptional

isAnyTypebooleanoptional

isVarargsbooleanoptional

isConstbooleanoptional

docstringoptional

defaultJsonstringoptional

Discovery-facing constraint metadata, pre-encoded to their surfaced UTF-8 forms (presence-only — undefined means the constraint is absent and the corresponding field-metadata key is omitted entirely). Mirrors Python’s ArgumentSpec.default_json / choices_json / range_notation / pattern so argumentSpecsToSchema/schemaToArgumentSpecs round-trip symmetrically.

choicesJsonstringoptional

rangeNotationstringoptional

patternstringoptional

function argumentSpecsToSchema

source

export function argumentSpecsToSchema(specs: ArgumentSpec[]): VgiSchema

Description

Convert ArgumentSpecs to an Arrow Schema with VGI metadata keys. Positional arguments come first (in order), named arguments follow.

function constraintSpecFields

source

export function constraintSpecFields(
constraints: ArgumentConstraints | undefined,
): Pick<ArgumentSpec, "defaultJson" | "choicesJson" | "rangeNotation" | "pattern">

Description

Encode raw {@link ArgumentConstraints} into the pre-computed constraint fields of an {@link ArgumentSpec} (presence-only — absent constraints yield no field). Mirrors Python’s _constraint_kwargs.

function formatRange

source

export function formatRange(
ge?: number,
le?: number,
gt?: number,
lt?: number,
): string | undefined

Description

Build interval notation from an argument’s numeric bounds.

Inclusive bounds (ge/le) render as square brackets, exclusive bounds (gt/lt) as parentheses, and an open side as -inf/+inf. Returns undefined when the argument has no numeric bound at all.

Examples: ge=0,le=10 -> "[0, 10]"; gt=0 -> "(0, +inf)"; ge=1,lt=10 -> "[1, 10)".

function macroArgumentsSchema

source

export function macroArgumentsSchema(
parameters: string[],
parameterDefaultValues?: Uint8Array | null,
parameterDocs?: Record<string, string>,
): VgiSchema

Description

Build a macro arguments_schema describing macro parameters.

Mirrors the function arguments_schema mechanism: one Arrow field per macro parameter, in parameters order, each nullable. The per-parameter description is carried via the same vgi_doc field-metadata key functions use (UTF-8, presence-only — the key is omitted entirely when there is no doc). A parameter’s field type is the type of its default value when one is known (decoded from parameterDefaultValues, a one-row RecordBatch serialized as IPC bytes), else nullType().

Parameters

parameters

Ordered list of macro parameter names.

parameterDefaultValues

Optional one-row RecordBatch (IPC bytes) whose columns are parameter names with typed default values; used to infer each parameter’s field type.

parameterDocs

Optional mapping of parameter name to description. Empty or missing descriptions yield no vgi_doc metadata on the field.

Returns

Arrow schema with one nullable field per parameter, in order.

function macroParameterDocsFromSchema

source

export function macroParameterDocsFromSchema(schema: VgiSchema): Record<string, string>

Description

Extract per-parameter descriptions from a macro arguments_schema.

Inverse of {@link macroArgumentsSchema}’s vgi_doc handling: reads the vgi_doc field metadata (UTF-8) for each field. Fields without the key (undocumented) are omitted from the result.

Parameters

schema

A macro arguments_schema (one field per parameter).

Returns

Mapping of parameter name to description, for documented parameters only.

function schemaToArgumentSpecs

source

export function schemaToArgumentSpecs(schema: VgiSchema): ArgumentSpec[]

Description

Convert an Arrow Schema back to ArgumentSpecs.