NyaruDB

public actor NyaruDB

The root entry point for the NyaruDB embedded document database.

NyaruDB is an actor that serialises all file I/O through Swift’s concurrency model. It manages the lifecycle of collections, handles manifest I/O, and coordinates durability across all open collections.

Opening a database. Provide a directory URL or filesystem path:

let db = try await NyaruDB(path: "path/to/database")

Opening collections. Use collection(_:of:options:) to open or create a typed collection:

let users = try await db.collection("users", of: User.self)

Lifecycle. Call sync() to flush pending index and shard I/O, and close() to shut down cleanly. After close(), the instance cannot be used again.

Note

A single NyaruDB instance corresponds to one directory on disk. Opening multiple instances pointing at the same directory is not supported.

  • Opens or creates a database at the given directory URL.

    If the directory does not exist, it is created (with intermediate directories). All collection data is stored as subdirectories within this directory.

    Throws

    NyaruError.ioError if the directory cannot be created.

    Declaration

    Swift

    public init(path: URL, options: DatabaseOptions = DatabaseOptions()) throws

    Parameters

    path

    The directory URL for the database.
    options

    Database-wide configuration applied to all collections.

  • Opens or creates a database at the given filesystem path string.

    Convenience initialiser that converts the string to a directory URL and delegates to init(path:options:).

    Throws

    NyaruError.ioError if the directory cannot be created.

    Declaration

    Swift

    public convenience init(path: String, options: DatabaseOptions = DatabaseOptions()) throws

    Parameters

    path

    The filesystem path to the database directory.
    options

    Database-wide configuration.

Collections

  • Opens an existing collection or creates a new one with the given name and document type.

    When opening an existing collection, the provided options are validated against the persisted manifest. If the base configuration (id field, partition key, compression, encryption, format) does not match, collectionTypeMismatch is thrown.

    Indexed fields can be added across opens — new fields are populated by scanning all shards on first open. The id field is always indexed automatically.

    Throws

    NyaruError.collectionTypeMismatch if options conflict with the persisted manifest, NyaruError.databaseClosed if closed.

    Declaration

    Swift

    public func collection<T: Codable & Sendable>(
  _ name: String,
  of type: T.Type,
  options collectionOptions: CollectionOptions = CollectionOptions()
) async throws -> NyaruCollection<T>

    Parameters

    name

    The collection name.
    type

    The document type, which must conform to Codable & Sendable.
    collectionOptions

    Per-collection options (id field, partition key, indexed fields).

    Return Value

    A typed NyaruCollection<T> handle.

  • Returns the names of all collections present on disk.

    Scans the database directory for subdirectories containing a manifest.json file and reads each manifest to extract the collection name. Handles encrypted manifests transparently.

    Throws

    NyaruError.databaseClosed if closed, or NyaruError.decryptionFailed if a manifest cannot be decrypted.

    Declaration

    Swift

    public func listCollections() throws -> [String]

    Return Value

    A sorted list of collection names.

  • drop(_:) Asynchronous

    Permanently deletes a collection and all of its files from disk.

    If the collection is currently open, it is destroyed through the core (which shuts down shards cleanly). Otherwise the directory is removed directly.

    Throws

    NyaruError.collectionNotFound if the collection directory does not exist, NyaruError.databaseClosed if closed.

    Declaration

    Swift

    public func drop(_ name: String) async throws

    Parameters

    name

    The name of the collection to drop.

Durability / lifecycle

  • sync() Asynchronous

    Flushes all index snapshots and shard headers to disk.

    After sync() returns successfully, a crash on any clean shard requires no recovery work — the index snapshots are current and the dirty flag is cleared. This is a no-op if no mutations have occurred since the last sync.

    Throws

    NyaruError.databaseClosed if closed, or the first I/O error encountered across all collections.

    Declaration

    Swift

    public func sync() async throws
  • close() Asynchronous

    Syncs and then closes every open collection.

    After close() returns, the instance is permanently closed. Calling any method other than close() (which is idempotent) will throw NyaruError.databaseClosed.

    Throws

    The first I/O error encountered from any collection’s sync or close operations.

    Declaration

    Swift

    public func close() async throws