Structures

Configuration options for opening or creating a collection.

CollectionOptions lets you specify the document id field, an optional partition key for shard routing, and additional fields to index for query performance.

A typed, Sendable handle to one collection within a NyaruDB database.

NyaruCollection is a thin facade that encodes and decodes the generic document type T and delegates all storage operations to a shared CollectionCore actor. Handles are cheap value types — copy them freely.

Writing documents. Use insert, update, upsert, patch, and delete:

try await collection.insert(user)
try await collection.patch(id: userId, changes: ["name": "New Name"])

Reading documents. Use get(id:) for point lookups, all() for everything, stream() for bounded-memory iteration, and find() for fluent queries with predicates, sorting, and pagination.

Maintenance. Call compact() opportunistically (e.g. on app backgrounding) to reclaim space from tombstoned records.

A pull-based AsyncSequence that yields documents one by one without materialising the entire collection in memory.

The iterator fetches documents in bounded batches from the storage engine. Each batch is decoded lazily as the consumer calls next(). When the batch is exhausted, the next batch is fetched from the collection actor.

Memory usage is bounded by one batch (batchSize documents).

A snapshot of collection statistics returned by NyaruCollection.stats().

Configuration shared by every collection opened from a single NyaruDB instance.

DatabaseOptions controls compression, encryption, serialization format, file protection, and the fragmentation threshold that drives compaction hints. These options are applied to all collections within the database and are persisted in each collection’s manifest at creation time.

Changing options after collections exist has no effect on existing collections — the manifest is frozen at creation. Only encryptionKey is omitted from the manifest (it is provided at open time) so the key can be rotated or supplied from the Keychain without touching on-disk data.

The query execution plan produced by QueryBuilder.explain().

A query plan describes the chosen access path and how many predicates can be pushed down to the index versus evaluated in memory.

A thread-safe wrapper around NSRegularExpression that makes regex instances compatible with Sendable requirements.

An immutable, fluent query builder for executing typed queries against a NyaruDB collection.

QueryBuilder is created by NyaruCollection.find() and provides a chainable API for adding predicates, sorting, pagination, and executing the query:

let results = try await collection.find()
    .where("age", isGreaterThan: 18)
    .where("status", isEqualTo: "active")
    .sort(by: "name", ascending: true)
    .limit(20)
    .offset(0)
    .execute()

Query planning. The builder includes a simple cost-based planner that selects the most efficient access path:

1. Index equality lookup (highest priority).
2. Index IN set lookup.
3. Index range/comparison lookup.
4. Partition scan (if a partition key equality predicate exists).
5. Full collection scan (fallback).

Call explain() to inspect the plan without executing.

A stable, hashable reference to a physical record stored in a shard file.

Every index entry in NyaruDB is a RecordPointer. Storing bare offsets caused cross-shard lookup and delete corruption in the earlier engine because the same raw offset value is valid in every shard file — without the shard identifier, a pointer is ambiguous. By always coupling the shard ID with the offset, every index entry unambiguously identifies one record on disk, regardless of how many shards exist.

Conforms to Hashable (so it can be stored in posting-list arrays and sets), Codable (so index snapshots are serialisable), and Sendable (for safe use across actor boundaries).