Struct Collection 

pub struct Collection<'a> { /* private fields */ }

A typed handle to one collection.

Validates, stores, and maintains secondary indexes for documents, composing the schema validator, the document codec seam, and the index engine over a single Database. The Rust core is the sole validation authority (PRD §3); the TS surface applies id/defaults before a document reaches insert.

Implementations

impl<'a> Collection<'a>

pub fn new( db: &'a Database, schema: &'a SchemaIr, name: &str, ) -> Result<Self, NookError>

Binds a collection name to its compiled schema IR.

Errors

Returns NookError::Schema if name is not a collection in schema.

pub fn find(&self, filter: &Value) -> Result<Vec<Value>, NookError>

Returns every document in the collection that matches filter, in storage order. Equivalent to find_with(filter, &QueryOptions::default()).

Operator support (M2): bare equality, $ne, $in, $nin, $gt, $gte, $lt, $lte, $exists. An empty filter ({}) returns all documents.

Errors

Storage/corruption errors.

pub fn find_with( &self, filter: &Value, opts: &QueryOptions, ) -> Result<Vec<Value>, NookError>

Returns documents matching filter, then applies opts (schema-typed sort → offset → limit). null/missing sort last; ties break by id.

Operator support for filter matches find.

Errors

Storage/corruption errors; NookError::Schema if a sort field is unknown or non-orderable.

pub fn find_one(&self, filter: &Value) -> Result<Option<Value>, NookError>

Returns the first document matching filter, or None.

Errors

Storage/corruption errors.

pub fn find_one_with( &self, filter: &Value, opts: &QueryOptions, ) -> Result<Option<Value>, NookError>

find_one honoring opts: sorts, then returns the first row. limit is forced to 1 internally.

Errors

Storage/corruption errors; sort-field errors as find_with.

pub fn count(&self, filter: &Value) -> Result<usize, NookError>

Returns the number of documents matching filter.

Errors

Storage/corruption errors.

pub fn count_with( &self, filter: &Value, opts: &QueryOptions, ) -> Result<usize, NookError>

count honoring opts: sort does not change a count so it is not applied, but an INVALID sort field is still rejected so count and find accept/reject identical options identically; offset/limit cap the returned count (“are there at most N?”).

Errors

Storage/corruption errors; NookError::Schema if a sort field is unknown or non-orderable.

pub fn delete(&self, filter: &Value) -> Result<usize, NookError>

Deletes every document matching filter, removing each document and all of its index entries atomically.

Errors

Storage/corruption errors.

pub fn delete_in_tx( &self, tx: &mut WriteTx<'_>, filter: &Value, ) -> Result<usize, NookError>

Variant of Self::delete that runs the write phase inside the caller-supplied WriteTx, so multiple delete ops can share one transaction (see M5c db.transaction(cb) and the NAPI tx_delete_many primitive).

Victims are still resolved against the latest committed snapshot via Self::find BEFORE entering the caller’s write txn, then removed atomically. This mirrors the M2 split-txn shape: read + write are separate observations even when delete is composed with other ops in one outer txn (read-after-write inside the same transaction is M6 retrofit work).

Returns the number of documents removed.

Errors

Storage/corruption errors, or NookError::Schema if any victim document lacks the id field.

pub fn insert(&self, doc: &Value) -> Result<(), NookError>

Validates doc, stores it, and maintains every secondary index atomically. Unique indexes are pre-checked against the in-flight write transaction so two colliding inserts (even within one txn) conflict and roll back.

Errors

• NookError::Schema — doc fails schema validation, or the id field is missing/not a string.
• NookError::InvalidArg — the id contains a \0 byte (the \0-delimited index key requires a NUL-free doc_id; see crate::index::engine).
• NookError::Conflict — a unique-index value already exists; the whole transaction is rolled back.
• storage errors propagated from the write transaction.

pub fn insert_in_tx( &self, tx: &mut WriteTx<'_>, doc: &Value, ) -> Result<(), NookError>

Variant of Self::insert that runs the validation + index maintenance + storage write inside the caller-supplied WriteTx, so multiple insert ops can share one transaction (see M5c db.transaction(cb) and the NAPI tx_insert primitive). Same semantics as insert, including the in-transaction unique pre-check that catches two colliding inserts buffered into one outer txn.

Errors

Same as Self::insert.