Skip to content
calternal docs

calternal_notes_core::reminders

Lossless calternal-reminders frontmatter projection.

A vault file owns a mapping from reminder UUID to reminder record. The mapping lives in one JSON flow value on the existing YAML frontmatter key; JSON is valid YAML, remains readable by ordinary YAML tools, and lets this module preserve unknown fields and trigger shapes without implementing a second YAML parser. The writer edits only that frontmatter line and leaves every other byte untouched.

Source: crates/calternal-notes-core/src/reminders.rs

Structs

Section titled “Structs”

BlockReminderInspection

Section titled “BlockReminderInspection”
pub struct BlockReminderInspection

Lossless-read status returned by inspect_block_reminders.

A malformed value intentionally has no raw rewrite authority: reminders is empty and callers must leave the source bytes alone or ask a newer tool to repair them. The raw value stays in the host file, never in this parsed projection.

Fields

  • pub status: BlockReminderStatus
  • pub reminders: BlockReminderMap

Implements: Debug, Clone, PartialEq

Source: crates/calternal-notes-core/src/reminders.rs:56

Enums

Section titled “Enums”

BlockReminderStatus

Section titled “BlockReminderStatus”
pub enum BlockReminderStatus

The parse outcome for the app-owned frontmatter key.

Malformed is deliberately distinct from Absent: an older client must never treat foreign YAML or damaged JSON as an empty map and erase it on a later save. The status is serialized in lowercase for the JS API.

Variants

  • Absent
  • Valid
  • Malformed

Implements: Debug, Clone, Copy, PartialEq, Eq

Source: crates/calternal-notes-core/src/reminders.rs:43

Type aliases

Section titled “Type aliases”

BlockReminderMap

Section titled “BlockReminderMap”
pub type BlockReminderMap = BTreeMap<String, Value>;

A UUID-keyed map of reminder records. Records intentionally remain JSON values at this boundary: fields added by a newer client, including nested trigger fields and non-string values, must survive an older round-trip.

Source: crates/calternal-notes-core/src/reminders.rs:35

Functions

Section titled “Functions”

extract_block_reminders

Section titled “extract_block_reminders”
pub fn extract_block_reminders(text: &str) -> BlockReminderMap

Read the calternal-reminders mapping from a host file.

The canonical writer emits one-line JSON. A malformed or non-object value remains an empty compatibility projection. New callers should use inspect_block_reminders first and refuse mutation on Malformed; this legacy helper remains for hosts that only need the valid-map projection.

Source: crates/calternal-notes-core/src/reminders.rs:87

inspect_block_reminders

Section titled “inspect_block_reminders”
pub fn inspect_block_reminders(text: &str) -> BlockReminderInspection

Inspect the owned frontmatter field without conflating absence and damage.

Source: crates/calternal-notes-core/src/reminders.rs:62

set_block_reminders

Section titled “set_block_reminders”
pub fn set_block_reminders(text: &str, reminders: &BlockReminderMap) -> String

Write the reminder map into the existing host file’s frontmatter.

An empty map removes the owned key. Non-empty maps are emitted in sorted UUID/key order by serde_json’s BTreeMap traversal, which makes equal logical maps converge to equal bytes across devices. Unknown record fields and trigger values are serialized unchanged in type and value.

Source: crates/calternal-notes-core/src/reminders.rs:97

set_block_reminders_checked

Section titled “set_block_reminders_checked”
pub fn set_block_reminders_checked(
    text: &str,
    reminders: &BlockReminderMap,
) -> Result<String, &'static str>

Safely write the mapping only when the current field is absent or valid.

Unlike set_block_reminders, this is the mutation seam for hosts that cannot afford to overwrite an externally-authored or damaged value. It returns an error and leaves the input untouched when inspection reports Malformed; callers can surface that state for manual repair or a newer client. The returned error is stable enough for a UI/log category, but is not a replacement for the structured inspection status.

Source: crates/calternal-notes-core/src/reminders.rs:115

valid_block_reminder_id

Section titled “valid_block_reminder_id”
pub fn valid_block_reminder_id(value: &str) -> bool

Validate a stable block anchor before it enters the reminder projection. Block IDs are Markdown identities, not paths, so accept only bounded ASCII letters, digits, _ and -.

Source: crates/calternal-notes-core/src/reminders.rs:24

Constants

Section titled “Constants”

REMINDERS_FRONTMATTER_KEY

Section titled “REMINDERS_FRONTMATTER_KEY”
pub const REMINDERS_FRONTMATTER_KEY: &str

The only frontmatter key owned by the reminder projection.

Source: crates/calternal-notes-core/src/reminders.rs:19