The v Namespace — Baseflare Validator API Reference

The v namespace is exported from baseflare/values and is the primary validator toolkit used throughout Baseflare. You use it in defineTable() to declare field types, in query(), mutation(), and action() argument shapes to validate incoming data, and in return value contracts to enforce outgoing types. Every validator enforces its constraints at runtime — calling .validate() either returns a typed output or throws a ValidationError — and simultaneously carries full TypeScript type information so your handlers receive correctly-typed arguments without any extra casting.

Import

import { v } from 'baseflare/values'

Primitive Validators

`v.string()`

Validates that a value is a JavaScript string.

	Type
Input	`string`
Output	`string`

Modifiers: .min(n), .max(n), .searchable()

v.string()               // any string
v.string().min(1)        // non-empty string
v.string().max(100)      // up to 100 characters
v.string().searchable()  // mark for FTS5 full-text search index

`v.number()`

Validates that a value is a finite, non-NaN JavaScript number. Rejects Infinity, -Infinity, and NaN.

	Type
Input	`number`
Output	`number`

Modifiers: .min(n), .max(n), .integer()

v.number()                         // any finite number
v.number().min(0)                  // non-negative
v.number().min(0).max(100)         // range 0–100
v.number().integer()               // safe integer only
v.number().min(0).max(100).integer() // integer in range

`v.boolean()`

Validates that a value is a JavaScript boolean (true or false).

	Type
Input	`boolean`
Output	`boolean`

v.boolean()               // true or false
v.boolean().default(false) // defaults to false if field is absent

`v.bytes()`

Validates that a value is a Uint8Array. Suitable for binary blobs, hashes, or encrypted payloads.

	Type
Input	`Uint8Array`
Output	`Uint8Array`

Modifiers: .min(n), .max(n) (measured in bytes via .byteLength)

v.bytes()          // any Uint8Array
v.bytes().min(16)  // at least 16 bytes
v.bytes().max(512) // at most 512 bytes

`v.null()`

Validates the exact value null. Commonly used inside v.union() to create nullable fields.

	Type
Input	`null`
Output	`null`

v.null()
v.union(v.string(), v.null()) // string | null

`v.any()`

Accepts any value without type-checking. The TypeScript output type is unknown, so you must narrow the type yourself before using the value.

	Type
Input	`unknown`
Output	`unknown`

v.any() // pass-through — no runtime checks performed

Prefer a specific validator over v.any() wherever possible. v.any() disables both runtime validation and TypeScript type narrowing for that field.

ID Validator

`v.id(tableName)`

Validates that a value is a valid UUIDv7 string and brands the TypeScript type with the given table name. The branded Id<TTableName> type prevents accidentally passing an ID from one table where an ID from a different table is expected.

	Type
Input	`Id<TTableName>`
Output	`Id<TTableName>`

Parameters:

tableName

string

required

The name of the table this ID belongs to. Used for the TypeScript brand only — not checked against the schema at runtime.

v.id('todos')   // validates a UUIDv7 and types it as Id<'todos'>
v.id('users')   // validates a UUIDv7 and types it as Id<'users'>

// TypeScript prevents mixing IDs from different tables:
const todoId: Id<'todos'> = args.todoId  // ✅
const userId: Id<'users'> = args.todoId  // ❌ Type error

Composite Validators

`v.array(item)`

Validates that a value is a JavaScript array where every element passes the given item validator. Each element is validated in order; the error path includes the array index (e.g., value[2]).

	Type
Input	`InputOf<TItem>[]`
Output	`OutputOf<TItem>[]`

Modifiers: .min(n), .max(n) (measured in array .length)

item

Validator

required

The validator to apply to each element of the array.

v.array(v.string())           // string[]
v.array(v.number()).min(1)    // number[] with at least 1 element
v.array(v.id('tags')).max(10) // at most 10 tag IDs
v.array(v.object({
  label: v.string(),
  value: v.number(),
}))

`v.object(shape)`

Validates a plain JavaScript object whose keys exactly match shape. Unknown keys are rejected — any key present on the input that is not declared in shape throws a ValidationError. Each value is validated by its corresponding validator in shape.

	Type
Input	`ObjectInput<TShape>` (required keys required, optional keys optional)
Output	`ObjectOutput<TShape>`

shape

Record<string, Validator>

required

An object mapping field names to validators.

v.object({
  title:     v.string().min(1).max(200),
  priority:  v.enum(['low', 'medium', 'high']),
  dueDate:   v.number().integer().optional(),
  completed: v.boolean().default(false),
})

`v.record(valueValidator)`

Validates a plain JavaScript object treated as a Record<string, T> — any string keys are allowed, but each value must pass valueValidator. Unlike v.object(), no specific keys are required or checked.

	Type
Input	`Record<string, InputOf<TValue>>`
Output	`Record<string, OutputOf<TValue>>`

valueValidator

Validator

required

The validator applied to every value in the record.

v.record(v.number())           // Record<string, number>
v.record(v.array(v.string()))  // Record<string, string[]>

`v.union(...members)`

Validates that a value matches at least one of the given member validators. Members are tried in order; the first one that succeeds wins. If all members fail, a ValidationError is thrown listing all failure reasons.

	Type
Input	`InputOf<TMembers[number]>`
Output	`OutputOf<TMembers[number]>`

Members are passed as rest arguments (spread), not as an array.

v.union(v.string(), v.null())              // string | null
v.union(v.number(), v.boolean())           // number | boolean
v.union(
  v.literal('pending'),
  v.literal('active'),
  v.literal('archived'),
)                                          // 'pending' | 'active' | 'archived'

`v.literal(value)`

Validates that the value is exactly equal (===) to the given literal. The TypeScript output type is the narrowed literal type.

	Type
Input	`TValue` (the literal itself)
Output	`TValue`

value

string | number | boolean | null

required

The exact value to match. Must be a primitive.

v.literal('active')   // only the string 'active'
v.literal(42)         // only the number 42
v.literal(true)       // only true
v.literal(null)       // equivalent to v.null()

`v.enum(values)`

Validates that a value is a string matching one of the entries in values. Prefer v.enum() over v.union(v.literal(...), ...) when all variants are strings — it produces a cleaner error message and stores the allowed values in the schema definition.

	Type
Input	`TValues[number]`
Output	`TValues[number]`

values

[string, ...string[]]

required

A non-empty tuple of allowed string values.

v.enum(['low', 'medium', 'high'])
// input/output type: 'low' | 'medium' | 'high'

v.enum(['draft', 'published', 'archived'])

`v.vector({ dimensions })`

Validates a number[] of exactly dimensions elements where every element is a finite, non-NaN number. Used for storing embedding vectors (e.g., from OpenAI or Workers AI) in a Baseflare table.

	Type
Input	`number[]`
Output	`number[]`

Modifiers: .min(n), .max(n) (vector lengths are fixed by dimensions, so these are rarely needed)

options.dimensions

number

required

The exact required length of the vector array.

v.vector({ dimensions: 1536 })  // OpenAI text-embedding-3-small
v.vector({ dimensions: 768 })   // Workers AI embedding

Optional Helper

`v.optional(validator)`

Shorthand for validator.optional(). Makes the field optional — the input may be undefined, and the output type becomes T | undefined.

v.optional(v.string())   // equivalent to v.string().optional()
v.optional(v.number())   // number | undefined

Modifier Methods

All validators expose these chainable modifier methods. Not every modifier is supported by every validator kind — unsupported combinations throw a SchemaError at definition time.

.optional()

method

Makes the field optional in input. The output type becomes T | undefined. When the field is absent, undefined is returned without error.

v.string().optional()  // input: string | undefined → output: string | undefined

.default(value)

method

Provides a fallback value when the field is absent from input. Makes the field optional in input but guarantees the output is always T (never undefined).

v.boolean().default(false)    // input: boolean | undefined → output: boolean
v.array(v.string()).default([]) // array always present in output
v.number().default(0)

.min(n)

method

Validates a minimum. Supported kinds and what is measured:

Kind	Measured
`string`	`.length` (character count)
`number`	numeric value
`array`	`.length` (element count)
`bytes`	`.byteLength`
`vector`	`.length` (element count)

.max(n)

method

Validates a maximum, following the same per-kind rules as .min(n).

.searchable()

method

Schema-level hint that marks a string field for inclusion in a SQLite FTS5 full-text search index. Has no effect at runtime validation — the hint is read by the schema differ when creating or migrating tables.

v.string().searchable()  // field included in FTS5 index

.integer()

method

Available on v.number() only. Validates that the number passes Number.isSafeInteger(). Combine with .min() and .max() to constrain integer ranges.

v.number().integer()               // any safe integer
v.number().integer().min(1)        // positive integer
v.number().integer().min(0).max(255) // byte value

Combined example:

v.string().min(1).max(280)             // 1–280 character string
v.number().min(0).max(100).integer()   // integer 0–100
v.boolean().default(false)             // optional in input, always false if missing
v.array(v.string()).default([])        // optional array, defaults to []
v.string().optional()                  // may be undefined

`Validator<TInput, TOutput>` Interface

Every value returned by the v namespace implements the Validator interface. The full generic signature is:

interface Validator<
  TInput,
  TOutput,
  TKind extends ValidatorKind = ValidatorKind,
  TOptional extends boolean = false,
  THasDefault extends boolean = false,
>

validate(value, path?)

(value: unknown, path?: string) => TOutput

Runs the validator against value. Returns TOutput on success, or throws a ValidationError on failure. The optional path argument is used in the error message to identify where in a nested structure the failure occurred (e.g., "args.address.zip"). Defaults to "value" when called directly.

v.string().min(1).validate('hello')    // → 'hello'
v.string().min(1).validate('')         // throws ValidationError: "Value must have length at least 1"
v.number().validate('oops')            // throws ValidationError: "Value must be a finite number"

definition

ValidatorDefinition

The schema definition object carrying the validator’s kind, constraints (min, max, integer, searchable), and structural metadata (shape, item, members, etc.). This is read by Baseflare’s schema differ to compute migrations and by the query engine to enforce schema constraints.

Exported Utility Types

The following TypeScript types are exported from baseflare/values alongside the v namespace and Validator interface.

import type {
  Infer,
  InputOf,
  OutputOf,
  AnyValidator,
  NumberValidator,
  ValidatorKind,
  ValidatorShape,
  ValidatorDefinition,
  ObjectInput,
  ObjectOutput,
  Primitive,
} from 'baseflare/values'

Infer<TValidator>

type

Extracts the output TypeScript type of a validator. Equivalent to OutputOf<TValidator>. Use this to derive a type from a validator definition without duplicating the type manually.

const todoFields = v.object({
  title: v.string(),
  done:  v.boolean(),
})

type TodoFields = Infer<typeof todoFields>
// { title: string; done: boolean }

InputOf<TValidator>

type

Extracts the input TypeScript type accepted by a validator — i.e., the type that .validate() takes as its first argument. For optional or default-carrying validators this may be wider than the output type (e.g., string | undefined).

OutputOf<TValidator>

type

Extracts the output TypeScript type produced by a validator on a successful .validate() call. Identical to Infer<TValidator>.

AnyValidator

type

The widest validator type: Validator<unknown, unknown, ValidatorKind, boolean, boolean>. Used in generic code that accepts any validator regardless of its specific input/output types.

NumberValidator<TInput, TOutput, TOptional, THasDefault>

interface

The specialised validator interface returned by v.number(). Extends Validator with the extra .integer() method, and ensures that .min(), .max(), .optional(), .default(), and .searchable() all return a NumberValidator rather than the base Validator type.

ValidatorKind

type

A string union of all recognised validator kinds:

"string" | "number" | "boolean" | "bytes" | "null" | "id" | "array" | "object" | "record" | "union" | "literal" | "enum" | "vector" | "any"

ValidatorShape

type

Record<string, AnyValidator> — the type of the shape argument to v.object().

ValidatorDefinition

interface

The plain-object schema representation stored on validator.definition. Carries kind, optional, hasDefault, searchable, and optional constraint fields (min, max, integer, dimensions, tableName, value, values, item, members, shape, recordValue).

ObjectInput<TShape>

type

Derives the input object type from a ValidatorShape. Required keys are those whose validators do not accept undefined; optional keys are those with optional or default validators.

ObjectOutput<TShape>

type

Derives the output object type from a ValidatorShape. Keys backed by an .optional() validator are optional in the output; all others are required.

Primitive

type

string | number | boolean | null — the set of JavaScript primitives accepted by v.literal().

baseflare/values

baseflare/server

The v Namespace — Baseflare Validator API Reference

Import

Primitive Validators

`v.string()`

`v.number()`

`v.boolean()`

`v.bytes()`

`v.null()`

`v.any()`

ID Validator

`v.id(tableName)`

Composite Validators

`v.array(item)`

`v.object(shape)`

`v.record(valueValidator)`

`v.union(...members)`

`v.literal(value)`

`v.enum(values)`

`v.vector({ dimensions })`

Optional Helper

`v.optional(validator)`

Modifier Methods

`Validator<TInput, TOutput>` Interface

Exported Utility Types

Build docs developers (and LLMs) love

baseflare/values

baseflare/server

Documentation Index

​Import

​Primitive Validators

​v.string()

​v.number()

​v.boolean()

​v.bytes()

​v.null()

​v.any()

​ID Validator

​v.id(tableName)

​Composite Validators

​v.array(item)

​v.object(shape)

​v.record(valueValidator)

​v.union(...members)

​v.literal(value)

​v.enum(values)

​v.vector({ dimensions })

​Optional Helper

​v.optional(validator)

​Modifier Methods

​Validator<TInput, TOutput> Interface

​Exported Utility Types

Build docs developers (and LLMs) love

Import

Primitive Validators

`v.string()`

`v.number()`

`v.boolean()`

`v.bytes()`

`v.null()`

`v.any()`

ID Validator

`v.id(tableName)`

Composite Validators

`v.array(item)`

`v.object(shape)`

`v.record(valueValidator)`

`v.union(...members)`

`v.literal(value)`

`v.enum(values)`

`v.vector({ dimensions })`

Optional Helper

`v.optional(validator)`

Modifier Methods

`Validator<TInput, TOutput>` Interface

Exported Utility Types