Error Handling

ctrodb throws typed errors for common failure scenarios. All custom errors extend CtrodbError.

Error hierarchy

CtrodbError{:ts}
├── ConnectionError{:ts}
├── SchemaError{:ts}
├── ValidationError{:ts}

Additional error classes (CollectionNotFoundError, RecordNotFoundError, QueryError) exist in the library but are not currently thrown by ctrodb's built-in operations — they're available for your own use or plugin development.

Catching errors

import {
  CtrodbError,
  ConnectionError,
  ValidationError,
} from "ctrodb"

try {
  await db.collection("todos").create({ title: "My todo" })
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Field "${error.field}" failed validation`)
  } else if (error instanceof ConnectionError) {
    console.error("Database not connected — call db.connect()")
  } else if (error instanceof CtrodbError) {
    console.error("ctrodb error:", error.message)
  } else {
    throw error
  }
}

ConnectionError

Thrown when performing operations without an active connection.

try {
  db.collection("todos").getAll()
} catch (e) {
  // "Database 'ctrodb' is not connected. Call db.connect()..."
}

Can also include a custom reason passed to the constructor.

SchemaError

Thrown when the schema configuration is invalid.

// Missing version number
// No collections defined
// Index referencing a non-existent field

ValidationError

Thrown when a record violates schema validation rules. Contains field, collection, and value properties for detailed error handling.

const schema = {
  version: 1,
  collections: {
    users: {
      fields: {
        email: { type: "string", validate: "email" },
        age: { type: "number", min: 0, max: 150 },
      },
    },
  },
}

try {
  await db.collection("users").create({ email: "not-an-email", age: 200 })
} catch (e) {
  if (e instanceof ValidationError) {
    console.error(e.field)     // "email"
    console.error(e.collection) // "users"
    console.error(e.value)     // "not-an-email"
    console.error(e.message)   // "Field 'email' in collection 'users': ..."
  }
}

Additional error classes

These classes are exported and constructable but not thrown by ctrodb itself:

• CollectionNotFoundError(name, availableCollections?) — for schema-constrained lookups
• RecordNotFoundError(collection, id) — for record-level lookups
• QueryError(message) — for malformed queries

You can use them in your own code or plugins for consistent error types.

Log levels

logLevel is accepted in DatabaseConfig and reserved for future use:

const db = new Database({
  logLevel: "warn",
})

Level	Intended behavior (not yet implemented)
"debug"	All internal operations logged
"info"	Major lifecycle events (connect, disconnect)
"warn"	Recoverable issues (blocked IDB)
"error"	Failures and exceptions
"silent"	No logging