GoatDB Documentation

GoatDB performance is measured across multiple runtimes and storage modes. Key metrics include Average, Median, Stddev, CV (Coefficient of Variation), Samples, and Throughput (ops/s).

Available Performance Suites:

1. Deno: Benchmarks running on Deno 2.7.5.
2. Node.js: Benchmarks running on Node v25.2.1.
3. Browser: Benchmarks running in Chrome 145.0 using OPFS (Origin Private File System).

GoatDB Storage Modes:

• Trusted: Standard mode.
• Durable: Mode optimized for durability.
• JSONL: Mode using JSON Lines format.

Comparison Target:

• SQLite: Benchmarked in standard and Fast-Unsafe modes for head-to-head comparison.

The nodejs-basic example demonstrates essential GoatDB operations, including:

• Database setup and schema definitions
• CRUD (Create, Read, Update, Delete) operations
• Reactive queries that respond to data changes

GoatDB provides specialized hooks and types for seamless integration into React applications. This allows for reactive UI updates based on database changes.

Key React-specific components include:

• Hooks: Specialized hooks (referenced via UseQueryOpts and UseItemOpts) for querying and managing items.
• State Management: DBReadyState tracks the loading and readiness state of the database connection.
• Component Props: PropsWithPath provides a standard way for components to accept a database path as an input.

The TrustPool manages all known sessions and their associated public keys. In GoatDB, every commit in the graph is signed with the private key of the session that generated it.

TrustPool performs two levels of validation:

1. Signature Verification: It checks each commit's signature against its session's public key.
2. Permission Verification: It ensures that the modifications within a commit are valid and stay within the creator's assigned scope of permissions.

The Server API provides abstractions for running GoatDB in a networked environment. It includes:

• Server: A simple abstraction around an HTTP server used to expose database functionality.
• Compilation & Deployment: Types like CompileOptions, TargetOS, and CPUArch support compiling GoatDB applications into standalone executables.
• Email Support: Types like EmailInfo and EmailBuilder facilitate email-related operations within the server context.

The GoatDB Core API provides the fundamental building blocks for interacting with the database. Key components include:

• GoatDB: The central class for managing repositories, data synchronization, and overall database operations.
• Repository: A collection of items within the database.
• ManagedItem: A high-level interface used for reading, writing, and synchronizing individual items.
• Query: Represents a live, reactive view over a repository or another query.
• DataRegistry: A registry that manages known schemas for a given GoatDB instance.
• TrustPool: Manages cryptographic signatures for commits in the data graph.
• LogStream: Implementations like ConsoleLogStream (for console output) and JSONLogStream (for file output) handle database logging.

GoatDB's security model is built on a distributed verification system that enables a tamper-proof commit graph.

• Peer Verification: Because every operation is signed, all peers in the network can independently verify the authenticity of any change.
• Client-as-Replica: Clients maintain their own copy of the commit graph and verify operations independently. This allows clients to act as replicas, providing resilience. If a peer fails, a client can restore the state by replaying the verified commit graph.
• Resilience: This architecture protects against network partitions, peer failures, and malicious actors by eliminating single points of failure in the verification process.

The SchemaRequiredFields<T> type is used to extract the names of all fields in a schema that are strictly required.

Key Behavior:

• It identifies fields where the required property is set to true.
• Exception for Default Functions: For practical purposes, if a field has a default property that is a Function, it is treated as not required from the type system perspective (it is excluded from the extracted list) because the database can satisfy the requirement using the default value.
• If a field is required but has no default function, its name (key K) is included in the resulting type.

In GoatDB, SchemaFieldsDef is a type used to define the mapping between field names and their respective definitions. It is structured as a record where each key is a string (the field name) and each value is a FieldDef containing a ValueType. This is typically used when defining the schema for a document or a collection.

// Conceptual structure of SchemaFieldsDef
const mySchema: SchemaFieldsDef = {
  fieldName: [FieldDef<ValueType>],
};