> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module: values

> Utilities for working with values stored in Bijection.

Utilities for working with values stored in Bijection.

You can see the full set of supported types at
[Types](/database/types).

## Namespaces

* [Base64](/api/namespaces/values.Base64)

## Classes

* [BijectionError](/api/classes/values.BijectionError)
* [VId](/api/classes/values.VId)
* [VFloat64](/api/classes/values.VFloat64)
* [VInt64](/api/classes/values.VInt64)
* [VCommitTs](/api/classes/values.VCommitTs)
* [VBoolean](/api/classes/values.VBoolean)
* [VBytes](/api/classes/values.VBytes)
* [VString](/api/classes/values.VString)
* [VNull](/api/classes/values.VNull)
* [VAny](/api/classes/values.VAny)
* [VObject](/api/classes/values.VObject)
* [VLiteral](/api/classes/values.VLiteral)
* [VArray](/api/classes/values.VArray)
* [VRecord](/api/classes/values.VRecord)
* [VUnion](/api/classes/values.VUnion)
* [CommitTsPlaceholder](/api/classes/values.CommitTsPlaceholder)

## Type Aliases

### GenericValidator

Ƭ **GenericValidator**: [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`>

The type that all validators must extend.

***

### AsObjectValidator

Ƭ **AsObjectValidator**\<`V`>: `V` extends [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values#propertyvalidators) ? [`Validator`](/api/modules/values#validator)\<[`ObjectType`](/api/modules/values#objecttype)\<`V`>> : `never`

Coerce an object with validators as properties to a validator.
If a validator is passed, return it.

#### Type parameters

| Name | Type |
| :- | :- |
| `V` | extends [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`> \| [`PropertyValidators`](/api/modules/values#propertyvalidators) |

***

### PropertyValidators

Ƭ **PropertyValidators**: `Record`\<`string`, [`Validator`](/api/modules/values#validator)\<`any`, [`OptionalProperty`](/api/modules/values#optionalproperty), `any`>>

Validators for each property of an object.

This is represented as an object mapping the property name to its
[Validator](/api/modules/values#validator).

***

### ObjectType

Ƭ **ObjectType**\<`Fields`>: [`Expand`](/api/modules/server#expand)\<\{ \[Property in OptionalKeys\<Fields>]?: Exclude\<Infer\<Fields\[Property]>, undefined> } & \{ \[Property in RequiredKeys\<Fields>]: Infer\<Fields\[Property]> }>

Compute the type of an object from [PropertyValidators](/api/modules/values#propertyvalidators).

#### Type parameters

| Name | Type |
| :- | :- |
| `Fields` | extends [`PropertyValidators`](/api/modules/values#propertyvalidators) |

***

### Infer

Ƭ **Infer**\<`T`>: `T`\[`"type"`]

Extract a TypeScript type from a validator.

Example usage:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const objectSchema = v.object({
  property: v.string(),
});
type MyObject = Infer<typeof objectSchema>; // { property: string }
```

**`Type Param`**

The type of a [Validator](/api/modules/values#validator) constructed with [v](/api/modules/values#v).

#### Type parameters

| Name | Type |
| :- | :- |
| `T` | extends [`Validator`](/api/modules/values#validator)\<`any`, [`OptionalProperty`](/api/modules/values#optionalproperty), `any`> |

***

### VOptional

Ƭ **VOptional**\<`T`>: `T` extends [`VId`](/api/classes/values.VId)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VId`](/api/classes/values.VId)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VString`](/api/classes/values.VString)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VString`](/api/classes/values.VString)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VFloat64`](/api/classes/values.VFloat64)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VFloat64`](/api/classes/values.VFloat64)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VInt64`](/api/classes/values.VInt64)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VInt64`](/api/classes/values.VInt64)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VCommitTs`](/api/classes/values.VCommitTs)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VCommitTs`](/api/classes/values.VCommitTs)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VBoolean`](/api/classes/values.VBoolean)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VBoolean`](/api/classes/values.VBoolean)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VNull`](/api/classes/values.VNull)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VNull`](/api/classes/values.VNull)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VAny`](/api/classes/values.VAny)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VAny`](/api/classes/values.VAny)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VLiteral`](/api/classes/values.VLiteral)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VLiteral`](/api/classes/values.VLiteral)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VBytes`](/api/classes/values.VBytes)\<infer Type, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VBytes`](/api/classes/values.VBytes)\<`Type` | `undefined`, `"optional"`> : `T` extends [`VObject`](/api/classes/values.VObject)\<infer Type, infer Fields, [`OptionalProperty`](/api/modules/values#optionalproperty), infer FieldPaths> ? [`VObject`](/api/classes/values.VObject)\<`Type` | `undefined`, `Fields`, `"optional"`, `FieldPaths`> : `T` extends [`VArray`](/api/classes/values.VArray)\<infer Type, infer Element, [`OptionalProperty`](/api/modules/values#optionalproperty)> ? [`VArray`](/api/classes/values.VArray)\<`Type` | `undefined`, `Element`, `"optional"`> : `T` extends [`VRecord`](/api/classes/values.VRecord)\<infer Type, infer Key, infer Value, [`OptionalProperty`](/api/modules/values#optionalproperty), infer FieldPaths> ? [`VRecord`](/api/classes/values.VRecord)\<`Type` | `undefined`, `Key`, `Value`, `"optional"`, `FieldPaths`> : `T` extends [`VUnion`](/api/classes/values.VUnion)\<infer Type, infer Members, [`OptionalProperty`](/api/modules/values#optionalproperty), infer FieldPaths> ? [`VUnion`](/api/classes/values.VUnion)\<`Type` | `undefined`, `Members`, `"optional"`, `FieldPaths`> : `never`

#### Type parameters

| Name | Type |
| :- | :- |
| `T` | extends [`Validator`](/api/modules/values#validator)\<`any`, [`OptionalProperty`](/api/modules/values#optionalproperty), `any`> |

***

### OptionalProperty

Ƭ **OptionalProperty**: `"optional"` | `"required"`

Type representing whether a property in an object is optional or required.

***

### Validator

Ƭ **Validator**\<`Type`, `IsOptional`, `FieldPaths`>: [`VId`](/api/classes/values.VId)\<`Type`, `IsOptional`> | [`VString`](/api/classes/values.VString)\<`Type`, `IsOptional`> | [`VFloat64`](/api/classes/values.VFloat64)\<`Type`, `IsOptional`> | [`VInt64`](/api/classes/values.VInt64)\<`Type`, `IsOptional`> | [`VCommitTs`](/api/classes/values.VCommitTs)\<`Type`, `IsOptional`> | [`VBoolean`](/api/classes/values.VBoolean)\<`Type`, `IsOptional`> | [`VNull`](/api/classes/values.VNull)\<`Type`, `IsOptional`> | [`VAny`](/api/classes/values.VAny)\<`Type`, `IsOptional`> | [`VLiteral`](/api/classes/values.VLiteral)\<`Type`, `IsOptional`> | [`VBytes`](/api/classes/values.VBytes)\<`Type`, `IsOptional`> | [`VObject`](/api/classes/values.VObject)\<`Type`, `Record`\<`string`, [`Validator`](/api/modules/values#validator)\<`any`, [`OptionalProperty`](/api/modules/values#optionalproperty), `any`>>, `IsOptional`, `FieldPaths`> | [`VArray`](/api/classes/values.VArray)\<`Type`, [`Validator`](/api/modules/values#validator)\<`any`, `"required"`, `any`>, `IsOptional`> | [`VRecord`](/api/classes/values.VRecord)\<`Type`, [`Validator`](/api/modules/values#validator)\<`string`, `"required"`, `any`>, [`Validator`](/api/modules/values#validator)\<`any`, `"required"`, `any`>, `IsOptional`, `FieldPaths`> | [`VUnion`](/api/classes/values.VUnion)\<`Type`, [`Validator`](/api/modules/values#validator)\<`any`, `"required"`, `any`>\[], `IsOptional`, `FieldPaths`>

A validator for a Bijection value.

This should be constructed using the validator builder, [v](/api/modules/values#v).

A validator encapsulates:

* The TypeScript type of this value.
* Whether this field should be optional if it's included in an object.
* The TypeScript type for the set of index field paths that can be used to
  build indexes on this value.
* A JSON representation of the validator.

Specific types of validators contain additional information: for example
an `ArrayValidator` contains an `element` property with the validator
used to validate each element of the list. Use the shared 'kind' property
to identity the type of validator.

More validators can be added in future releases so an exhaustive
switch statement on validator `kind` should be expected to break
in future releases of Bijection.

#### Type parameters

| Name | Type |
| :- | :- |
| `Type` | `Type` |
| `IsOptional` | extends [`OptionalProperty`](/api/modules/values#optionalproperty) = `"required"` |
| `FieldPaths` | extends `string` = `never` |

***

### ObjectFieldType

Ƭ **ObjectFieldType**: `Object`

#### Type declaration

| Name | Type |
| :- | :- |
| `fieldType` | [`ValidatorJSON`](/api/modules/values#validatorjson) |
| `optional` | `boolean` |

***

### ValidatorJSON

Ƭ **ValidatorJSON**: \{ `type`: `"null"`  } | \{ `type`: `"number"`  } | \{ `type`: `"bigint"`  } | \{ `type`: `"commitTs"`  } | \{ `type`: `"boolean"`  } | \{ `type`: `"string"`  } | \{ `type`: `"bytes"`  } | \{ `type`: `"any"`  } | \{ `type`: `"literal"` ; `value`: [`JSONValue`](/api/modules/values#jsonvalue)  } | \{ `type`: `"id"` ; `tableName`: `string`  } | \{ `type`: `"array"` ; `value`: [`ValidatorJSON`](/api/modules/values#validatorjson)  } | \{ `type`: `"record"` ; `keys`: [`RecordKeyValidatorJSON`](/api/modules/values#recordkeyvalidatorjson) ; `values`: [`RecordValueValidatorJSON`](/api/modules/values#recordvaluevalidatorjson)  } | \{ `type`: `"object"` ; `value`: `Record`\<`string`, [`ObjectFieldType`](/api/modules/values#objectfieldtype)>  } | \{ `type`: `"union"` ; `value`: [`ValidatorJSON`](/api/modules/values#validatorjson)\[]  }

***

### RecordKeyValidatorJSON

Ƭ **RecordKeyValidatorJSON**: \{ `type`: `"string"`  } | \{ `type`: `"id"` ; `tableName`: `string`  } | \{ `type`: `"union"` ; `value`: [`RecordKeyValidatorJSON`](/api/modules/values#recordkeyvalidatorjson)\[]  }

***

### RecordValueValidatorJSON

Ƭ **RecordValueValidatorJSON**: [`ObjectFieldType`](/api/modules/values#objectfieldtype) & \{ `optional`: `false`  }

***

### JSONValue

Ƭ **JSONValue**: `null` | `boolean` | `number` | `string` | [`JSONValue`](/api/modules/values#jsonvalue)\[] | \{ `[key: string]`: [`JSONValue`](/api/modules/values#jsonvalue);  }

The type of JavaScript values serializable to JSON.

***

### GenericId

Ƭ **GenericId**\<`TableName`>: `string` & \{ `__tableName`: `TableName`  }

An identifier for a document in Bijection.

Bijection documents are uniquely identified by their `Id`, which is accessible
on the `_id` field. To learn more, see [Document IDs](/database/document-ids).

Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.

IDs are base 32 encoded strings which are URL safe.

IDs are just strings at runtime, but this type can be used to distinguish them from other
strings at compile time.

If you're using code generation, use the `Id` type generated for your data model in
`bijection/_generated/dataModel.d.ts`.

#### Type parameters

| Name | Type | Description |
| :- | :- | :- |
| `TableName` | extends `string` | A string literal type of the table name (like "users"). |

***

### Value

Ƭ **Value**: `null` | `bigint` | `number` | `boolean` | `string` | `ArrayBuffer` | [`CommitTsPlaceholder`](/api/classes/values.CommitTsPlaceholder) | [`Value`](/api/modules/values#value)\[] | \{ `[key: string]`: `undefined` | [`Value`](/api/modules/values#value);  }

A value supported by Bijection.

Values can be:

* stored inside of documents.
* used as arguments and return types to queries and mutation functions.

You can see the full set of supported types at
[Types](/database/types).

***

### NumericValue

Ƭ **NumericValue**: `bigint` | `number`

The types of [Value](/api/modules/values#value) that can be used to represent numbers.

## Variables

### v

• `Const` **v**: `Object`

The validator builder.

This builder allows you to build validators for Bijection values. Validators
are used in two places:

1. **Schema definitions** - to define the shape of documents in your tables.
2. **Function arguments and return values** - to validate inputs and outputs
   of your Bijection queries, mutations, and actions.

Always include `args` and `returns` validators on all Bijection functions. If a
function doesn't return a value, use `returns: v.null()`.

**Bijection type reference:**

| Bijection Type | JS/TS Type | Validator |
| - | - | - |
| Id | `string` | `v.id("tableName")` |
| Null | `null` | `v.null()` |
| Float64 | `number` | `v.number()` |
| Int64 | `bigint` | `v.int64()` |
| Boolean | `boolean` | `v.boolean()` |
| String | `string` | `v.string()` |
| Bytes | `ArrayBuffer` | `v.bytes()` |
| Array | `Array` | `v.array(element)` |
| Object | `Object` | `v.object({ field: value })` |
| Record | `Record` | `v.record(keys, values)` |

**Modifiers and meta-types:**

* `v.union(member1, member2)` - a value matching at least one validator
* `v.literal("value")` - a specific literal string, number, bigint, or boolean
* `v.optional(validator)` - makes a property optional in an object (`T | undefined`)

**Important notes:**

* JavaScript's `undefined` is **not** a valid Bijection value. Functions that
  return `undefined` or have no return will return `null` to the client.
  Objects with `undefined` values will strip those keys during serialization.
  For arrays, use an explicit `null` instead.
* `v.bigint()` is deprecated, use `v.int64()` instead.
* `v.map()` and `v.set()` are not supported. Use `v.array()` of tuples or
  `v.record()` as alternatives.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { v } from "bijection/values";

// Use in function definition:
export const createUser = mutation({
  args: {
    name: v.string(),
    email: v.string(),
    age: v.optional(v.number()),
  },
  returns: v.id("users"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("users", args);
  },
});
```

**`See`**

* [https://docs.bijection.com/database/types](/database/types)
* [https://docs.bijection.com/functions/validation](/functions/validation)

#### Type declaration

| Name | Type |
| :- | :- |
| `id` | \<TableName>(`tableName`: `TableName`) => [`VId`](/api/classes/values.VId)\<[`GenericId`](/api/modules/values#genericid)\<`TableName`>, `"required"`> |
| `null` | () => [`VNull`](/api/classes/values.VNull)\<`null`, `"required"`> |
| `number` | () => [`VFloat64`](/api/classes/values.VFloat64)\<`number`, `"required"`> |
| `float64` | () => [`VFloat64`](/api/classes/values.VFloat64)\<`number`, `"required"`> |
| `bigint` | () => [`VInt64`](/api/classes/values.VInt64)\<`bigint`, `"required"`> |
| `int64` | () => [`VInt64`](/api/classes/values.VInt64)\<`bigint`, `"required"`> |
| `commitTs` | () => [`VCommitTs`](/api/classes/values.VCommitTs)\<`bigint` \| [`CommitTsPlaceholder`](/api/classes/values.CommitTsPlaceholder), `"required"`> |
| `boolean` | () => [`VBoolean`](/api/classes/values.VBoolean)\<`boolean`, `"required"`> |
| `string` | () => [`VString`](/api/classes/values.VString)\<`string`, `"required"`> |
| `bytes` | () => [`VBytes`](/api/classes/values.VBytes)\<`ArrayBuffer`, `"required"`> |
| `literal` | \<T>(`literal`: `T`) => [`VLiteral`](/api/classes/values.VLiteral)\<`T`, `"required"`> |
| `array` | \<T>(`element`: `T`) => [`VArray`](/api/classes/values.VArray)\<`T`\[`"type"`]\[], `T`, `"required"`> |
| `object` | \<T>(`fields`: `T`) => [`VObject`](/api/classes/values.VObject)\<[`Expand`](/api/modules/server#expand)\<\{ \[Property in string \| number \| symbol]?: Exclude\<Infer\<T\[Property]>, undefined> } & \{ \[Property in string \| number \| symbol]: Infer\<T\[Property]> }>, `T`, `"required"`, \{ \[Property in string \| number \| symbol]: Property \| \`$\{Property & string}.$\{T\[Property]\["fieldPaths"]}\` }\[keyof `T`] & `string`> |
| `record` | \<Key, Value>(`keys`: `Key`, `values`: `Value`) => [`VRecord`](/api/classes/values.VRecord)\<`Record`\<[`Infer`](/api/modules/values#infer)\<`Key`>, `Value`\[`"type"`]>, `Key`, `Value`, `"required"`, `string`> |
| `union` | \<T>(...`members`: `T`) => [`VUnion`](/api/classes/values.VUnion)\<`T`\[`number`]\[`"type"`], `T`, `"required"`, `T`\[`number`]\[`"fieldPaths"`]> |
| `any` | () => [`VAny`](/api/classes/values.VAny)\<`any`, `"required"`, `string`> |
| `optional` | \<T>(`value`: `T`) => [`VOptional`](/api/modules/values#voptional)\<`T`> |
| `nullable` | \<T>(`value`: `T`) => [`VUnion`](/api/classes/values.VUnion)\<`T` \| [`VNull`](/api/classes/values.VNull)\<`null`, `"required"`>\[`"type"`], \[`T`, [`VNull`](/api/classes/values.VNull)\<`null`, `"required"`>], `"required"`, `T` \| [`VNull`](/api/classes/values.VNull)\<`null`, `"required"`>\[`"fieldPaths"`]> |

## Functions

### compareValues

▸ **compareValues**(`k1`, `k2`): `number`

#### Parameters

| Name | Type |
| :- | :- |
| `k1` | `undefined` \| [`Value`](/api/modules/values#value) |
| `k2` | `undefined` \| [`Value`](/api/modules/values#value) |

#### Returns

`number`

***

### getBijectionSize

▸ **getBijectionSize**(`value`): `number`

Calculate the size in bytes of a Bijection value.

This matches how Bijection calculates document size for bandwidth tracking
and size limit enforcement.

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `value` | `undefined` \| [`Value`](/api/modules/values#value) | A Bijection value to measure |

#### Returns

`number`

The size in bytes

***

### getDocumentSize

▸ **getDocumentSize**(`value`, `options?`): `number`

Calculate the size of a document including system fields.

If your value already has \_id and \_creationTime fields, this will count them
in the normal size calculation. Otherwise, it adds the constant overhead
for system fields.

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `value` | `Record`\<`string`, [`Value`](/api/modules/values#value)> | A Bijection object (document body) |
| `options?` | `Object` | Options for size calculation |

#### Returns

`number`

The size in bytes

***

### asObjectValidator

▸ **asObjectValidator**\<`V`>(`obj`): `V` extends [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values#propertyvalidators) ? [`Validator`](/api/modules/values#validator)\<[`ObjectType`](/api/modules/values#objecttype)\<`V`>> : `never`

Coerce an object with validators as properties to a validator.
If a validator is passed, return it.

#### Type parameters

| Name | Type |
| :- | :- |
| `V` | extends [`PropertyValidators`](/api/modules/values#propertyvalidators) \| [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`> |

#### Parameters

| Name | Type |
| :- | :- |
| `obj` | `V` |

#### Returns

`V` extends [`Validator`](/api/modules/values#validator)\<`any`, `any`, `any`> ? `V` : `V` extends [`PropertyValidators`](/api/modules/values#propertyvalidators) ? [`Validator`](/api/modules/values#validator)\<[`ObjectType`](/api/modules/values#objecttype)\<`V`>> : `never`

***

### jsonToBijection

▸ **jsonToBijection**(`value`): [`Value`](/api/modules/values#value)

Parse a Bijection value from its JSON representation.

This function will deserialize serialized Int64s to `BigInt`s, Bytes to `ArrayBuffer`s etc.

To learn more about Bijection values, see [Types](/database/types).

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `value` | [`JSONValue`](/api/modules/values#jsonvalue) | The JSON representation of a Bijection value previously created with [bijectionToJson](/api/modules/values#bijectiontojson). |

#### Returns

[`Value`](/api/modules/values#value)

The JavaScript representation of the Bijection value.

***

### bijectionToJson

▸ **bijectionToJson**(`value`): [`JSONValue`](/api/modules/values#jsonvalue)

Convert a Bijection value to its JSON representation.

Use [jsonToBijection](/api/modules/values#jsontobijection) to recreate the original value.

To learn more about Bijection values, see [Types](/database/types).

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `value` | [`Value`](/api/modules/values#value) | A Bijection value to convert into JSON. |

#### Returns

[`JSONValue`](/api/modules/values#jsonvalue)

The JSON representation of `value`.