convex-macros

Macros to help make Convex in Rust nice

Installation

[dependencies]
ragkit_convex_macros = "0.0.4"

# Required by code this macro generates.
anyhow = "1.0.80"
convex = "0.6.0"
serde = "1.0.185"
serde_json = "1.0"

Usage

Create models using the same Convex validator syntax as your schema definition.

convex_model!(User {
  _id: v.id("users"),
  name: v.string(),
  age: v.optional(v.int64()),
  platform: v.union(
    v.object({
      platform: v.literal("google"),
      verified: v.boolean(),
    }),
    v.object({
      platform: v.literal("github"),
      username: v.string(),
    }),
  ),
});

This generates pub struct User {} with various methods to convert from convex::Value and to serde_json::Value.

let user = User::from_convex_value(&Value::Object(btreemap! {
  "_id".into() => Value::String("1234".into()),
  "name".into() => Value::String("Alice".into()),
  "age".into() => Value::Int64(42),
  "platform".into() => Value::Object(btreemap! {
    "platform".into() => Value::String("github".into()),
    "username".into() => Value::String("alicecodes".into()),
  }),
}))
.expect("it should parse");

assert_eq!("1234", user._id);
assert_eq!("alicecodes", user.platform.as_2().unwrap().username);
assert_eq!(
  json!({
    "_id": "1234",
    "name": "Alice",
    "age": 42,
    "platform": {
      "platform": "github",
      "username": "alicecodes",
    },
  }),
  json!(user),
);

Features

let user = User::from_convex_value(value)?; to parse a value from Convex client.
json!(user) to serialize as json.
Discriminated unions are automatically handled.
Helper functions for each union branch: user.platform.as_2()?.username.

Validator List

Validator Name	Rust Type	Notes
`v.string()`	`String`
`v.id("tableName")`	`String`	Ids are not validated against your tables
`v.null()`	`()`
`v.int64()`	`i64`
`v.number()`	`f64`
`v.boolean()`	`bool`
`v.optional(...)`	`Option<T>`
`v.union(...)`	Generated `enum`
`v.object({field: ...})`	Generated `struct`	Field names can't be rust keywords (like `type`)
`v.bytes()`	not implemented
`v.array(values)`	not implemented
`v.any()`	not implemented

Limitations

This is experimental and may not be "production quality", use with caution.
v.bytes(), v.array(), v.any() are not yet supported.
Field names must be valid Rust identifiers, so keywords like type cannot be a field name. Map it to _type, kind, t, etc.
Union variant names are always named like: Variant1, Variant2, etc.
The first acceptable union branch will be used if there are multiples that could validly parse data.
This package generates code that expects anyhow, convex, serde, and serde_json to be available.
Ints and Floats may be coerced into each other. Please test out your use cases and open an issue if you believe the behavior should change.

License

MIT