ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! An index's NAME, as a type neither a value nor a column can be passed as: [`SlotName`].

use crate::name::borrowed_name;

/// Is `name` a bare identifier — non-empty, ASCII `[A-Za-z0-9_]`, and not digit-leading?
///
/// `pub(crate)` rather than private, because the rule is the crate's ONE slot rule and a backend
/// that makes a directory or a table out of a slot has to ask it WITHOUT panicking — [`SlotName`]'s
/// own door refuses at a `const`, which is right for a declaration and wrong for a caller-supplied
/// name reaching a store at runtime.
///
/// Over BYTES and written as a `while` loop, because a `const fn` has neither iterators nor
/// closures — and it has to be `const` for [`SlotName::new`] to refuse at the declaration. It gives
/// the same answer a `chars()` form would on every input: a multi-byte UTF-8 character's bytes are
/// all `>= 0x80`, so none is `is_ascii_alphanumeric`, and a non-ASCII name is refused byte-wise
/// exactly as it would be char-wise.
pub(crate) const fn is_identifier(name: &[u8]) -> bool {
  if name.is_empty() {
    return false;
  }
  let first = name[0];
  if !(first.is_ascii_alphabetic() || first == b'_') {
    return false;
  }
  let mut i = 1;
  while i < name.len() {
    let byte = name[i];
    if !(byte.is_ascii_alphanumeric() || byte == b'_') {
      return false;
    }
    i += 1;
  }
  true
}

borrowed_name! {
  /// A validated SLOT name — WHICH index of a kind a record's documents land in, and that
  /// resource's durable name.
  ///
  /// # Why not [`FieldName`](crate::FieldName), which is already this construction
  ///
  /// Two reasons, and the second is the one that makes them unmergeable.
  ///
  /// A slot names an INDEX and a field names a COLUMN inside one, so a signature taking both as
  /// one type cannot refuse the swap. That is the argument keeping a field name from being a
  /// `&str`, one level up.
  ///
  /// And they disagree about what a legal name is. A field name is deliberately UNCHECKED because
  /// a backend quotes it, so `""` and `a"b` are names that type. A slot name reaches positions
  /// where no quoting exists — an index is a directory, a virtual table, a table — so there the
  /// same strings are not names that acquire a second meaning; they are not names at all. One type
  /// cannot hold both policies, and holding the looser one would put the refusal at whichever
  /// engine arrives first, on a declaration written long before it.
  ///
  /// # The content is the validation, and it is spent at the DECLARATION
  ///
  /// A `&SlotName` in hand PROVES the name passed the charset. [`new`](Self::new) is the only way
  /// to get one and it is `const`, so `SlotName::new("captions v2")` in a `const SLOT` position is
  /// `E0080` at const-evaluation: the record does not compile, rather than failing a boot check in
  /// a store nobody has written yet.
  ///
  /// # Why validated now, with nothing rendering it
  ///
  /// Because the alternative is a breaking change. A view accepting anything, acquiring a charset
  /// when the first engine lands, stops compiling declarations that already compiled — and this
  /// crate has already ruled that trade once, on `flatten`: a permissive shape that later becomes a
  /// refusal costs strictly more taken late than taken now.
  ///
  /// It is a CHARSET rather than a path rule, which is what makes it portable: the empty name,
  /// `.`, `..`, an embedded `/` or `\`, a NUL and a drive prefix all fall outside the set on EVERY
  /// target, where a `Path`-based rule would ask the host and admit `a\b` on unix while refusing
  /// it on Windows.
  ///
  /// # Examples
  ///
  /// ```
  /// use ingraph::SlotName;
  ///
  /// const CAPTIONS: &SlotName = SlotName::new("captions");
  ///
  /// assert_eq!(CAPTIONS.as_ref(), "captions");
  /// ```
  ///
  /// A malformed name in a `const` position never links:
  ///
  /// ```compile_fail,E0080
  /// use ingraph::SlotName;
  ///
  /// const BAD: &SlotName = SlotName::new("captions v2");
  /// ```
  pub struct SlotName;
}

impl SlotName {
  /// View `name` as a slot name, refusing anything that is not a bare identifier.
  ///
  /// `const`, so the refusal lands at the declaration that names the slot. There is no fallible
  /// twin, because there is no runtime name to take one: every slot in this crate is a `const` a
  /// declaration writes.
  ///
  /// # Panics
  ///
  /// If `name` is not a bare identifier — non-empty, ASCII `[A-Za-z0-9_]`, not digit-leading. In
  /// the position this type exists for, a `const SLOT` on a table trait, that panic is `E0080` at
  /// const-evaluation, so a malformed name is a compile error AT THE IMPL SITE. The pattern is
  /// std's own `CStr::from_bytes_with_nul`: validate, then view a `#[repr(transparent)]` DST.
  #[inline]
  pub const fn new(name: &str) -> &Self {
    assert!(
      is_identifier(name.as_bytes()),
      "a slot name must be non-empty ASCII [A-Za-z0-9_] and must not start with a digit"
    );
    Self::view(name)
  }
}

#[cfg(test)]
mod tests;