forgedb-types 0.2.0

Core type definitions for ForgeDB
Documentation

ForgeDB Types

Core type definitions for ForgeDB schemas and generated code.

Overview

The forgedb-types crate provides type definitions that match ForgeDB's schema language types, enabling type-safe serialization, validation, and storage operations. This is a foundational crate used by generated code and other ForgeDB runtime libraries.

Features

  • Type-safe primitives - Wrappers for all ForgeDB schema types
  • Serde support - Automatic JSON/binary serialization
  • Zero-cost abstractions - Minimal runtime overhead
  • Comprehensive documentation - Full API docs with examples
  • Extensive testing - >80% test coverage

Supported Types

Primitive Types

ForgeDB Type Rust Type Description
i32 i32 32-bit signed integer
i64 i64 64-bit signed integer
f64 f64 64-bit floating point
bool bool Boolean value
string String UTF-8 encoded text
uuid Uuid Universally unique identifier
timestamp Timestamp Unix timestamp (seconds since epoch)

Special Types

Timestamp

A wrapper around i64 that represents Unix timestamps (seconds since January 1, 1970 00:00:00 UTC).

use forgedb_types::Timestamp;

// Create from current time
let now = Timestamp::now();

// Create from seconds
let ts = Timestamp::from_seconds(1234567890);

// Get underlying value
let seconds = ts.as_seconds();

// Convert to/from i64
let ts: Timestamp = 1234567890_i64.into();
let seconds: i64 = ts.into();

Value

A generic enum that can hold any ForgeDB primitive type, useful for working with heterogeneous data.

use forgedb_types::{Value, Uuid};

// Create values
let int_val = Value::I32(42);
let str_val = Value::String("hello".to_string());
let uuid_val = Value::Uuid(Uuid::new_v4());

// Query type information
assert_eq!(int_val.type_name(), "i32");
assert!(int_val.is_numeric());
assert!(str_val.is_string());

// Serialize to JSON
let json = serde_json::to_string(&int_val).unwrap();

Installation

Add this to your Cargo.toml:

[dependencies]
forgedb-types = "0.1"

Usage Examples

Basic Types

use forgedb_types::{Timestamp, Value, Uuid};

// Work with timestamps
let ts = Timestamp::now();
println!("Current timestamp: {}", ts.as_seconds());

// Create typed values
let values = vec![
    Value::I32(42),
    Value::F64(3.14159),
    Value::Bool(true),
    Value::String("hello world".to_string()),
    Value::Uuid(Uuid::new_v4()),
    Value::Timestamp(Timestamp::now()),
];

// Check types
for val in &values {
    println!("Type: {}", val.type_name());
}

Serialization

use forgedb_types::{Value, Timestamp};
use serde_json;

// Serialize a value
let val = Value::I32(42);
let json = serde_json::to_string(&val).unwrap();
println!("JSON: {}", json);

// Deserialize back
let deserialized: Value = serde_json::from_str(&json).unwrap();
assert_eq!(val, deserialized);

// Timestamps serialize as plain i64
let ts = Timestamp::from_seconds(1234567890);
let json = serde_json::to_string(&ts).unwrap();
assert_eq!(json, "1234567890");

Type Conversions

use forgedb_types::Value;

// Convenient From implementations
let val: Value = 42_i32.into();
let val: Value = 3.14_f64.into();
let val: Value = true.into();
let val: Value = "hello".into();

// Type checking
if val.is_numeric() {
    println!("This is a numeric value");
}
if val.is_string() {
    println!("This is a string value");
}

API Documentation

Core Types

Timestamp

  • Timestamp::from_seconds(i64) -> Timestamp - Create from seconds since epoch
  • Timestamp::now() -> Timestamp - Get current timestamp
  • ts.as_seconds() -> i64 - Get seconds value
  • Implements: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize

Value

  • Value::type_name() -> &str - Get type name string
  • Value::is_numeric() -> bool - Check if numeric type (i32/i64/f64)
  • Value::is_string() -> bool - Check if string type
  • Implements: Debug, Clone, PartialEq, Serialize, Deserialize
  • Variants: I32(i32), I64(i64), F64(f64), Bool(bool), String(String), Uuid(Uuid), Timestamp(Timestamp)

Uuid

Re-exported from the uuid crate. See its documentation for full API.

Design Decisions

Why Wrap Timestamps?

While ForgeDB stores timestamps as plain i64 values, we provide a Timestamp wrapper type for:

  • Type safety (prevents mixing timestamps with other integers)
  • Convenient constructors (now(), from_seconds())
  • Clear intent in APIs
  • Future extensibility (e.g., different time units)

The wrapper has zero runtime overhead due to #[repr(transparent)] and is serialized as a plain i64.

Why Use Value Enum?

The Value enum provides:

  • Type-safe heterogeneous collections
  • Runtime type information
  • Generic storage for dynamic data
  • JSON/binary serialization with type tags

Testing

# Run all tests
cargo test -p forgedb-types

# Run with output
cargo test -p forgedb-types -- --nocapture

# Run doc tests
cargo test -p forgedb-types --doc

Performance

All types are designed for zero or minimal overhead:

  • Timestamp is #[repr(transparent)] over i64
  • No heap allocations except for String and Value::String
  • Copy types where appropriate for stack efficiency
  • Serde uses derive macros for optimal code generation

Dependencies

  • serde - Serialization framework
  • uuid - UUID generation and parsing

Dev dependencies:

Contributing

This crate is part of the ForgeDB project.

Documentation

For more information about ForgeDB:

License

Licensed under either of:

at your option.