Module: values
Utilities for working with values stored in Convex.
You can see the full set of supported types at Types.
Namespaces
Classes
- ConvexError
- VId
- VFloat64
- VInt64
- VBoolean
- VBytes
- VString
- VNull
- VAny
- VObject
- VLiteral
- VArray
- VRecord
- VUnion
Type Aliases
GenericValidator
Ƭ GenericValidator: Validator<any, any, any>
The type that all validators must extend.
Defined in
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 |
Defined in
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.
Defined in
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 |
Defined in
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> |
Defined in
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 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> |
Defined in
OptionalProperty
Ƭ OptionalProperty: "optional" | "required"
Type representing whether a property in an object is optional or required.
Defined in
Validator
Ƭ Validator<Type, IsOptional, FieldPaths>: VId<Type, IsOptional> | VString<Type, IsOptional> | VFloat64<Type, IsOptional> | VInt64<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 Convex 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 Convex.
Type parameters
| Name | Type |
|---|---|
Type | Type |
IsOptional | extends OptionalProperty = "required" |
FieldPaths | extends string = never |
Defined in
ObjectFieldType
Ƭ ObjectFieldType: Object
Type declaration
| Name | Type |
|---|---|
fieldType | ValidatorJSON |
optional | boolean |
Defined in
ValidatorJSON
Ƭ ValidatorJSON: { type: "null" } | { type: "number" } | { type: "bigint" } | { 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[] }
Defined in
JSONValue
Ƭ JSONValue: null | boolean | number | string | JSONValue[] | { [key: string]: JSONValue; }
The type of JavaScript values serializable to JSON.
Defined in
GenericId
Ƭ GenericId<TableName>: string & { __tableName: TableName }
An identifier for a document in Convex.
Convex 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(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
convex/_generated/dataModel.d.ts.
Type parameters
| Name | Type | Description |
|---|---|---|
TableName | extends string | A string literal type of the table name (like "users"). |
Defined in
Value
Ƭ Value: null | bigint | number | boolean | string | ArrayBuffer | Value[] | { [key: string]: undefined | Value; }
A value supported by Convex.
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.
Defined in
NumericValue
Ƭ NumericValue: bigint | number
The types of Value that can be used to represent numbers.
Defined in
Variables
v
• Const v: Object
The validator builder.
This builder allows you to build validators for Convex values.
Validators can be used in schema definitions and as input validators for Convex functions.
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"> |
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> |
Defined in
Functions
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 Validator<any, any, any> | PropertyValidators |
Parameters
| Name | Type |
|---|---|
obj | V |
Returns
V extends Validator<any, any, any> ? V : V extends PropertyValidators ? Validator<ObjectType<V>> : never
Defined in
jsonToConvex
▸ jsonToConvex(value): Value
Parse a Convex value from its JSON representation.
This function will deserialize serialized Int64s to BigInts, Bytes to ArrayBuffers etc.
To learn more about Convex values, see Types.
Parameters
| Name | Type | Description |
|---|---|---|
value | JSONValue | The JSON representation of a Convex value previously created with convexToJson. |
Returns
The JavaScript representation of the Convex value.
Defined in
convexToJson
▸ convexToJson(value): JSONValue
Convert a Convex value to its JSON representation.
Use jsonToConvex to recreate the original value.
To learn more about Convex values, see Types.
Parameters
| Name | Type | Description |
|---|---|---|
value | Value | A Convex value to convert into JSON. |
Returns
The JSON representation of value.