Document API Reference

The Document struct is the primary data unit stored in PocketDB collections.

Installation

Add PocketDB to your Cargo.toml:

[dependencies]
pocketdb = "0.1"

Or via the command line:

cargo add pocketdb

Import

use pocketdb::Document;
use pocketdb::PocketValue;
use pocketdb::ObjectId;

Creating Documents

Document::new

pub fn new() -> Self

Creates a new Document with a fresh ObjectId and current timestamps.

Example:

let doc = Document::new();

---

Document::with_id

pub fn with_id(id: ObjectId) -> Self

Creates a new Document with the specified ObjectId.

---

doc! Macro

use pocketdb::doc;

let d = doc! {
    "name" => "Alice",
    "age" => 30,
    "active" => true
};

Values are automatically converted to PocketValue via the From trait.

Methods

Document::id

pub fn id(&self) -> &ObjectId

Returns a reference to the document's ObjectId.

---

Document::id_hex

pub fn id_hex(&self) -> String

Returns the ObjectId as a 24-character hex string.

---

Document::set_id

pub fn set_id(&mut self, id: ObjectId)

Sets the document's ObjectId (used during replace operations).

---

Document::created_at

pub fn created_at(&self) -> u64

Returns the creation timestamp in milliseconds since epoch.

---

Document::updated_at

pub fn updated_at(&self) -> u64

Returns the last modification timestamp in milliseconds since epoch.

---

Document::touch

pub fn touch(&mut self)

Sets the updated_at timestamp to the current time. Called automatically by set and remove.

---

Document::get

pub fn get(&self, field: &str) -> Option<&PocketValue>

Returns a reference to the field value, or None if the field doesn't exist.

Example:

if let Some(name) = doc.get("name").and_then(|v| v.as_str()) {
    println!("Name: {}", name);
}

---

Document::get_mut

pub fn get_mut(&mut self, field: &str) -> Option<&mut PocketValue>

Returns a mutable reference to the field value.

---

Document::set

pub fn set(&mut self, field: &str, value: PocketValue) -> Option<PocketValue>

Sets a field to the given value. Returns the previous value if the field existed. Updates updated_at.

---

Document::remove

pub fn remove(&mut self, field: &str) -> Option<PocketValue>

Removes a field from the document. Returns the removed value. Updates updated_at.

---

Document::contains

pub fn contains(&self, field: &str) -> bool

Returns true if the document contains the given field.

---

Document::iter

pub fn iter(&self) -> impl Iterator<Item = (&str, &PocketValue)>

Returns an iterator over all (field_name, value) pairs.

---

Document::field_count

pub fn field_count(&self) -> usize

Returns the number of fields (excluding _id).

---

Document::is_empty

pub fn is_empty(&self) -> bool

Returns true if the document has no fields (besides _id).

---

Document::fields

pub fn fields(&self) -> &HashMap<String, PocketValue>

Returns a reference to the underlying fields map.

---

Document::fields_mut

pub fn fields_mut(&mut self) -> &mut HashMap<String, PocketValue>

Returns a mutable reference to the underlying fields map. Updates updated_at.

---

Document::merge

pub fn merge(&mut self, other: &Document)

Merges all fields from other into this document. Existing fields are overwritten.

---

Document::to_json

pub fn to_json(&self) -> serde_json::Value

Converts the document to a serde_json::Value.

---

Document::from_json

pub fn from_json(val: serde_json::Value) -> Result<Self>

Creates a Document from a serde_json::Value. The _id is extracted if present.

PocketValue Methods

pub fn type_name(&self) -> &'static str  // "null", "bool", "int", etc.
pub fn is_null(&self) -> bool
pub fn is_number(&self) -> bool           // true for Int or Float
pub fn as_i64(&self) -> Option<i64>
pub fn as_f64(&self) -> Option<f64>
pub fn as_str(&self) -> Option<&str>
pub fn as_bool(&self) -> Option<bool>
pub fn as_object_id(&self) -> Option<&ObjectId>
pub fn as_array(&self) -> Option<&Vec<PocketValue>>
pub fn as_object(&self) -> Option<&HashMap<String, PocketValue>>
pub fn as_binary(&self) -> Option<&Vec<u8>>

ObjectId Methods

pub fn new() -> Self
pub fn from_bytes(bytes: [u8; 12]) -> Self
pub fn as_bytes(&self) -> &[u8; 12]
pub fn to_hex(&self) -> String           // 24-char hex string
pub fn from_hex(hex: &str) -> Result<Self, PocketError>
pub fn timestamp_ms(&self) -> u64        // Creation timestamp