Module: values - Bijection

Utilities for working with values stored in Bijection. You can see the full set of supported types at Types.

Namespaces

Base64

Classes

Type Aliases

GenericValidator

Ƭ GenericValidator: Validator<any, any, any> The type that all validators must extend.

AsObjectValidator

Ƭ AsObjectValidator<V>: V extends Validator<any, any, any> ? V : V extends PropertyValidators ? Validator<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`<`any`, `any`, `any`> \| `PropertyValidators`

PropertyValidators

Ƭ PropertyValidators: Record<string, Validator<any, OptionalProperty, any>> Validators for each property of an object. This is represented as an object mapping the property name to its Validator.

ObjectType

Ƭ ObjectType<Fields>: 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.

Type parameters

Name	Type
`Fields`	extends `PropertyValidators`

Infer

Ƭ Infer<T>: T["type"] Extract a TypeScript type from a validator. Example usage:

const objectSchema = v.object({
  property: v.string(),
});
type MyObject = Infer<typeof objectSchema>; // { property: string }

Type Param The type of a Validator constructed with v.

Type parameters

Name	Type
`T`	extends `Validator`<`any`, `OptionalProperty`, `any`>

VOptional

Ƭ VOptional<T>: T extends VId<infer Type, OptionalProperty> ? VId<Type | undefined, "optional"> : T extends VString<infer Type, OptionalProperty> ? VString<Type | undefined, "optional"> : T extends VFloat64<infer Type, OptionalProperty> ? VFloat64<Type | undefined, "optional"> : T extends VInt64<infer Type, OptionalProperty> ? VInt64<Type | undefined, "optional"> : T extends VCommitTs<infer Type, OptionalProperty> ? VCommitTs<Type | undefined, "optional"> : T extends VBoolean<infer Type, OptionalProperty> ? VBoolean<Type | undefined, "optional"> : T extends VNull<infer Type, OptionalProperty> ? VNull<Type | undefined, "optional"> : T extends VAny<infer Type, OptionalProperty> ? VAny<Type | undefined, "optional"> : T extends VLiteral<infer Type, OptionalProperty> ? VLiteral<Type | undefined, "optional"> : T extends VBytes<infer Type, OptionalProperty> ? VBytes<Type | undefined, "optional"> : T extends VObject<infer Type, infer Fields, OptionalProperty, infer FieldPaths> ? VObject<Type | undefined, Fields, "optional", FieldPaths> : T extends VArray<infer Type, infer Element, OptionalProperty> ? VArray<Type | undefined, Element, "optional"> : T extends VRecord<infer Type, infer Key, infer Value, OptionalProperty, infer FieldPaths> ? VRecord<Type | undefined, Key, Value, "optional", FieldPaths> : T extends VUnion<infer Type, infer Members, OptionalProperty, infer FieldPaths> ? VUnion<Type | undefined, Members, "optional", FieldPaths> : never

Type parameters

Name	Type
`T`	extends `Validator`<`any`, `OptionalProperty`, `any`>

OptionalProperty

Ƭ OptionalProperty: "optional" | "required" Type representing whether a property in an object is optional or required.

Validator

Ƭ Validator<Type, IsOptional, FieldPaths>: VId<Type, IsOptional> | VString<Type, IsOptional> | VFloat64<Type, IsOptional> | VInt64<Type, IsOptional> | VCommitTs<Type, IsOptional> | VBoolean<Type, IsOptional> | VNull<Type, IsOptional> | VAny<Type, IsOptional> | VLiteral<Type, IsOptional> | VBytes<Type, IsOptional> | VObject<Type, Record<string, Validator<any, OptionalProperty, any>>, IsOptional, FieldPaths> | VArray<Type, Validator<any, "required", any>, IsOptional> | VRecord<Type, Validator<string, "required", any>, Validator<any, "required", any>, IsOptional, FieldPaths> | VUnion<Type, Validator<any, "required", any>[], IsOptional, FieldPaths> A validator for a Bijection value. This should be constructed using the validator builder, 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` = `"required"`
`FieldPaths`	extends `string` = `never`

ObjectFieldType

Ƭ ObjectFieldType: Object

Type declaration

Name	Type
`fieldType`	`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 } | { type: "id" ; tableName: string } | { type: "array" ; value: ValidatorJSON } | { type: "record" ; keys: RecordKeyValidatorJSON ; values: RecordValueValidatorJSON } | { type: "object" ; value: Record<string, ObjectFieldType> } | { type: "union" ; value: ValidatorJSON[] }

RecordKeyValidatorJSON

Ƭ RecordKeyValidatorJSON: { type: "string" } | { type: "id" ; tableName: string } | { type: "union" ; value: RecordKeyValidatorJSON[] }

RecordValueValidatorJSON

Ƭ RecordValueValidatorJSON: ObjectFieldType & { optional: false }

JSONValue

Ƭ JSONValue: null | boolean | number | string | JSONValue[] | { [key: string]: 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. 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 | Value[] | { [key: string]: undefined | 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.

NumericValue

Ƭ NumericValue: bigint | number The types of 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:

Schema definitions - to define the shape of documents in your tables.
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

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

Type declaration

Name	Type
`id`	<TableName>(`tableName`: `TableName`) => `VId`<`GenericId`<`TableName`>, `"required"`>
`null`	() => `VNull`<`null`, `"required"`>
`number`	() => `VFloat64`<`number`, `"required"`>
`float64`	() => `VFloat64`<`number`, `"required"`>
`bigint`	() => `VInt64`<`bigint`, `"required"`>
`int64`	() => `VInt64`<`bigint`, `"required"`>
`commitTs`	() => `VCommitTs`<`bigint` \| `CommitTsPlaceholder`, `"required"`>
`boolean`	() => `VBoolean`<`boolean`, `"required"`>
`string`	() => `VString`<`string`, `"required"`>
`bytes`	() => `VBytes`<`ArrayBuffer`, `"required"`>
`literal`	<T>(`literal`: `T`) => `VLiteral`<`T`, `"required"`>
`array`	<T>(`element`: `T`) => `VArray`<`T`[`"type"`][], `T`, `"required"`>
`object`	<T>(`fields`: `T`) => `VObject`<`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`<`Record`<`Infer`<`Key`>, `Value`[`"type"`]>, `Key`, `Value`, `"required"`, `string`>
`union`	<T>(…`members`: `T`) => `VUnion`<`T`[`number`][`"type"`], `T`, `"required"`, `T`[`number`][`"fieldPaths"`]>
`any`	() => `VAny`<`any`, `"required"`, `string`>
`optional`	<T>(`value`: `T`) => `VOptional`<`T`>
`nullable`	<T>(`value`: `T`) => `VUnion`<`T` \| `VNull`<`null`, `"required"`>[`"type"`], [`T`, `VNull`<`null`, `"required"`>], `"required"`, `T` \| `VNull`<`null`, `"required"`>[`"fieldPaths"`]>

Functions

compareValues

▸ compareValues(k1, k2): number

Parameters

Name	Type
`k1`	`undefined` \| `Value`
`k2`	`undefined` \| `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`	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`>	A Bijection object (document body)
`options?`	`Object`	Options for size calculation

Returns

number The size in bytes

asObjectValidator

▸ asObjectValidator<V>(obj): V extends Validator<any, any, any> ? V : V extends PropertyValidators ? Validator<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` \| `Validator`<`any`, `any`, `any`>

Parameters

Name	Type
`obj`	`V`

Returns

V extends Validator<any, any, any> ? V : V extends PropertyValidators ? Validator<ObjectType<V>> : never

jsonToBijection

▸ jsonToBijection(value): Value Parse a Bijection value from its JSON representation. This function will deserialize serialized Int64s to BigInts, Bytes to ArrayBuffers etc. To learn more about Bijection values, see Types.

Parameters

Name	Type	Description
`value`	`JSONValue`	The JSON representation of a Bijection value previously created with bijectionToJson.

Returns

Value The JavaScript representation of the Bijection value.

bijectionToJson

▸ bijectionToJson(value): JSONValue Convert a Bijection value to its JSON representation. Use jsonToBijection to recreate the original value. To learn more about Bijection values, see Types.

Parameters

Name	Type	Description
`value`	`Value`	A Bijection value to convert into JSON.

Returns

JSONValue The JSON representation of value.

​Namespaces

​Classes

​Type Aliases

​GenericValidator

​AsObjectValidator

​Type parameters

​PropertyValidators

​ObjectType

​Type parameters

​Infer

​Type parameters

​VOptional

​Type parameters

​OptionalProperty

​Validator

​Type parameters

​ObjectFieldType

​Type declaration

​ValidatorJSON

​RecordKeyValidatorJSON

​RecordValueValidatorJSON

​JSONValue

​GenericId

​Type parameters

​Value

​NumericValue

​Variables

​v

​Type declaration

​Functions

​compareValues

​Parameters

​Returns

​getBijectionSize

​Parameters

​Returns

​getDocumentSize

​Parameters

​Returns

​asObjectValidator

​Type parameters

​Parameters

​Returns

​jsonToBijection

​Parameters

​Returns

​bijectionToJson

​Parameters

​Returns

Namespaces

Classes

Type Aliases

GenericValidator

AsObjectValidator

Type parameters

PropertyValidators

ObjectType

Type parameters

Infer

Type parameters

VOptional

Type parameters

OptionalProperty

Validator

Type parameters

ObjectFieldType

Type declaration

ValidatorJSON

RecordKeyValidatorJSON

RecordValueValidatorJSON

JSONValue

GenericId

Type parameters

Value

NumericValue

Variables

v

Type declaration

Functions

compareValues

Parameters

Returns

getBijectionSize

Parameters

Returns

getDocumentSize

Parameters

Returns

asObjectValidator

Type parameters

Parameters

Returns

jsonToBijection

Parameters

Returns

bijectionToJson

Parameters

Returns