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
//! COALESCING WITH NO CLOCK OF ITS OWN: the size-or-time batch, and the quiet-window debounce.
//!
//! Two machines and one posture. Neither owns a thread, neither owns a timer, and neither reads the
//! clock — `now` arrives as an ARGUMENT on every call that needs one. What each holds is the state a
//! coalescer has (an open batch and when it opened; a set of pending keys and when each falls
//! quiet), and what each answers is the one question a driving loop must ask on its behalf:
//! `deadline` — WHEN to come back.
//!
//! * [`Batcher<T>`] flushes on whichever arrives first, a count or a wait. `max_items` is BOTH the
//!   trigger and the bound, so a driver that flushes only on the timer still cannot grow a batch
//!   without end: a push into a full batch is REFUSED and the item handed back.
//! * [`Debounce<K>`] coalesces a burst per KEY. A second touch RESETS that key's window, so
//!   `create` + `modify` + `modify` is one intake rather than three — and a key nobody re-touched is
//!   untouched by the one somebody did.
//!
//! # THE OWNING LOOP DRIVES ME — the contract, and the whole of it
//!
//! Nothing here happens on its own. A loop that owns one of these machines runs three lines
//! forever, and the machine supplies the middle one:
//!
//! 1. ask `deadline()` — `None` means *nothing is pending, park until something arrives*;
//! 2. wait for whichever comes first, an arrival or that instant;
//! 3. hand the machine the `now` it woke at, and take what came due.
//!
//! The waiting is the LOOP's, and that is what makes the pair engine-agnostic. On the async engine
//! the driver is a long-lived task on the runtime the app ignited, and step 2 is that runtime's own
//! timer against its own channel; on the pure-thread engine it is a `Sweeper`-shaped park. Neither
//! spelling reaches in here, which is the same posture `Recurrence` and the poll clock behind a
//! `Resident` already take: a schedule computes instants and something else does the sleeping.
//!
//! It is also why a test needs no clock control and no waiting. `now` is a value, so a fake clock is
//! an [`Instant`](std::time::Instant) and some arithmetic, and a 500 ms window is exercised in
//! microseconds.
//!
//! # Durations arrive already parsed
//!
//! `max_wait` and `quiet` are [`Duration`](core::time::Duration)s. Where they came from — a default,
//! a `[registry]` section in a startup file, a knob on a request — is the options layer's business,
//! and the text form a person wrote is `humantime`'s. Neither word reaches this module, which
//! therefore has nothing to say about precedence between them.
//!
//! # Why this is CORE and rides no tier
//!
//! Both machines are `std` and arithmetic. They name no engine, no runtime, no backend and no
//! dependency, and their customers do not sit in one tier: the registry intake is a `runtime`
//! concern, and the record seat's write batching is a store one. Gating them on `runtime` would make
//! a coalescer that costs a build nothing unavailable to a build that has the store and no driver,
//! for no reason but where the first caller happened to live.
//!
//! # The plug sites
//!
//! These land AHEAD of their customers, and the demand that admitted them is one finding: the
//! feasibility census behind the root-key registry read the framework's timing suite as complete —
//! `park_on`, `select`, the shutdown arm, `Recurrence`, the merged tick cell, the sweeper — and
//! complete EXCEPT for these two shapes and the deadline schedule under them. Every seat below
//! wanted one, and every one of them would otherwise have written its own.
//!
//! * **The registry intake.** [`Debounce`] over root keys: a burst of filesystem events on one asset
//!   becomes one analysis, and the driver feeds the head node once the key has fallen quiet.
//! * **The record seat's write batching.** [`Batcher`] over rows, where one batch is one
//!   transaction — a count bound the transaction cannot exceed, and a wait so a trickle still lands.
//! * **A subscriber's publish cadence.** The fulltext index became a node and its write lane became
//!   a seam; a cadence knob on that seam is a [`Batcher`] and nothing else.
//! * **The retirement sweep.** Retired keys collected into one `WHERE lineage IN (…)` rather than a
//!   statement apiece.
//!
//! # Examples
//!
//! One driving loop's worth of turns, with the clock supplied by hand — which is exactly what a test
//! does, and exactly what a runtime's timer does for real:
//!
//! ```
//! use core::{num::NonZeroUsize, time::Duration};
//! use std::time::Instant;
//!
//! use ingraph::batch::{Batcher, Debounce, Push};
//!
//! let quiet = Duration::from_millis(500);
//! let start = Instant::now();
//!
//! let mut debounce = Debounce::<u64>::new(quiet);
//! let mut batcher = Batcher::<u64>::new(
//!   NonZeroUsize::new(10).expect("ten is not zero"),
//!   Duration::from_millis(500),
//! );
//!
//! // A burst on ONE key: a create and two modifies, 10 ms apart.
//! debounce.touch(7, start);
//! debounce.touch(7, start + Duration::from_millis(10));
//! debounce.touch(7, start + Duration::from_millis(20));
//!
//! // What the loop parks until — the LAST touch plus the window, not the first.
//! assert_eq!(debounce.deadline(), Some(start + Duration::from_millis(520)));
//! assert!(debounce.ripe(start + Duration::from_millis(519)).is_empty());
//!
//! // One intake for the whole burst, and nothing left pending.
//! assert_eq!(debounce.ripe(start + Duration::from_millis(520)), vec![7]);
//! assert_eq!(debounce.deadline(), None);
//!
//! // The intake feeds the batch, which flushes on whichever of the two comes first.
//! assert_eq!(batcher.push(7, start), Push::Queued);
//! assert_eq!(batcher.deadline(), Some(start + Duration::from_millis(500)));
//! assert!(!batcher.ready(start));
//! assert!(batcher.ready(start + Duration::from_millis(500)));
//!
//! // END punctuation BEATS the timer, and `drain` is the door that says so: it asks nothing about
//! // size and nothing about time.
//! assert_eq!(batcher.drain(), vec![7]);
//! assert_eq!(batcher.deadline(), None);
//! ```

mod batcher;
mod debounce;

pub use batcher::{Batcher, Push};
pub use debounce::Debounce;