NyaruError

public enum NyaruError : Error, Sendable, CustomStringConvertible

Represents all errors that can be thrown by NyaruDB operations.

NyaruError covers storage corruption, document validation failures, collection lifecycle issues, compression errors, and cryptographic failures. Each case carries contextual information to aid debugging.

Conforms to CustomStringConvertible to provide a human-readable description of each error case.

  • The on-disk file header or layout is invalid or unrecognised.

    This can occur when a file is not a NyaruDB shard, the magic bytes are wrong, the version is unsupported, or the header is truncated.

    Declaration

    Swift

    case invalidFileFormat(String)

    Parameters

    String

    A description of what was invalid.

  • A record at a specific offset failed integrity checks.

    This is raised when a record’s header is malformed, its CRC-32 checksum does not match, or the payload is truncated. Corruption may be caused by hardware faults, torn writes, or bugs.

    Declaration

    Swift

    case corruptedRecord(offset: UInt64, reason: String)

    Parameters

    offset

    The byte offset of the corrupt record within the shard.
    reason

    A human-readable description of the integrity failure.

  • An underlying filesystem read, write, or open operation failed.

    This wraps Foundation I/O errors such as permission denied, disk full, or file-not-found during shard operations.

    Declaration

    Swift

    case ioError(String)

    Parameters

    String

    The underlying I/O error description.

  • A document does not contain the configured id field.

    Every document inserted into a collection must have the field specified by CollectionOptions.idField. The default is "id".

    Declaration

    Swift

    case idFieldMissing(field: String)

    Parameters

    field

    The name of the missing id field.

  • A document does not contain the configured partition key field.

    If a partition key is configured, every document must include that field so the engine can determine which shard to route it to.

    Declaration

    Swift

    case partitionKeyMissing(field: String)

    Parameters

    field

    The name of the missing partition key field.

  • A document with the same id already exists in the collection.

    Raised by insert and insert(contentsOf:) when the id field value collides with an existing document. Batch inserts validate all ids before writing anything.

    Declaration

    Swift

    case duplicateID(String)

    Parameters

    String

    The duplicate id value.

  • No document exists with the given id.

    Raised by get, update, delete, and patch when the id is not found in the primary index.

    Declaration

    Swift

    case documentNotFound(id: String)

    Parameters

    id

    The requested document id.

  • Encoding a document to the storage format failed.

    Wraps errors from JSONEncoder or MsgPackEncoder (e.g. when a value is not encodable).

    Declaration

    Swift

    case encodingFailed(String)

    Parameters

    String

    The underlying encoding error description.

  • Decoding a stored payload back into a document failed.

    Wraps errors from JSONDecoder or MsgPackDecoder (e.g. when stored data is structurally invalid for the expected type).

    Declaration

    Swift

    case decodingFailed(String)

    Parameters

    String

    The underlying decoding error description.

  • The requested collection directory does not exist on disk.

    Raised by drop when the collection has not been opened and the directory is missing.

    Declaration

    Swift

    case collectionNotFound(String)

    Parameters

    String

    The collection name.

  • The collection was previously created with incompatible options.

    Raised when collection(_:of:options:) is called with options that conflict with the persisted manifest. The base configuration (id field, partition key, compression, encryption, format) is frozen at creation.

    Declaration

    Swift

    case collectionTypeMismatch(String)

    Parameters

    String

    The collection name.

  • Compressing a payload failed.

    Raised by the internal compression utilities when the underlying library returns an error status.

    Declaration

    Swift

    case compressionFailed

  • Decompressing a stored payload failed.

    Raised when a compressed record cannot be decompressed, possibly because the data is corrupt or was compressed with a different method.

    Declaration

    Swift

    case decompressionFailed

  • The requested compression method is not available on this platform.

    For example, LZFSE and LZ4 are only available on Apple platforms. gzip is always available.

    Declaration

    Swift

    case unsupportedCompression(String)

    Parameters

    String

    The name of the unsupported method.

  • Decrypting an encrypted payload or manifest failed.

    Raised when AES-GCM decryption fails, typically because the key is wrong or the data has been tampered with.

    Declaration

    Swift

    case decryptionFailed

  • Encrypting a payload or manifest failed.

    Raised when AES-GCM encryption produces an unexpected result.

    Declaration

    Swift

    case encryptionFailed

  • The requested operation is not supported in the current configuration.

    For example, pagination without a sort field, or patching the document id field.

    Declaration

    Swift

    case unsupportedOperation(String)

    Parameters

    String

    A description of the unsupported operation.

  • The database or collection has been closed and cannot accept operations.

    Declaration

    Swift

    case databaseClosed

  • Returns a human-readable description of this error.

    Declaration

    Swift

    public var description: String { get }