Skip to main content

GoatDB

The main database class that manages repositories, synchronization, and data access.

GoatDB is the primary entry point for working with the database. It handles:

  • Repository management (opening, closing, accessing)
  • Data synchronization with peers
  • User authentication and authorization
  • Schema validation

Extends: Emitter

Constructor​

new GoatDB(config: DBInstanceConfig)

Methods​

clientsForRepo()​

clientsForRepo(pathComps: string[]): Iterable<RepoClient<>>

Returns the associated RepoClient instances for the given repository. Each client instance handles synchronization with a different server endpoint, enabling client-side load-balancing.

close()​

close(path: string): Promise<void>

Closes a repository, flushing any pending writes to disk before releasing all memory associated with this repository.

This method does nothing if the repository isn't currently loaded.

count()​

count(path: string): number

Returns the number of items at the specified path, or -1 if the path doesn't exist.

NOTE: Currently only paths to repositories are supported.

create()​

create(path: string, schema: S, data: Partial<SchemaDataType<S>>): ManagedItem<S>

Creates a new item at the target repository, opening it if needed. Unlike GoatDB.item() there's no need to explicitly open a repository before creating items in it. Newly created items become immediately available for use and will get committed to the underlying repo after open completes.

Note: This method only initializes the item if it doesn't already exist. If the item already exists with a valid schema, this method will return the existing item without modifying it.

flush()​

flush(path: string): Promise<void>

Flushes all pending writes for the given repository to disk. Use this method when you must ensure all previously known commits are written to the local disk.

flushAll()​

flushAll(): Promise<void>

Flushes all pending writes for all repositories to disk.

getTrustPool()​

getTrustPool(): Promise<TrustPool<>>

Returns the trust pool of this DB instance. The trust pool is a low level object that manages all known sessions and their public keys. It is used to verify the authenticity of the underlying commit graph before persisting it to the local storage.

Note: You almost never need to use the trust pool directly.

item()​

item(pathComps: string[]): ManagedItem<S>

Access an item at the given path. An item's path is typically at the following format: /<data type>/<repo id>/<item key>

NOTE: If the item's repository haven't been opened yet, it'll be opened in the background. While open is progressing, the returned item will initially have a NULL scheme, and once open completes it'll be converted to the correct scheme if available. Typically it's easier to first explicitly open the repository before accessing any of its items.

itemLoaded()​

itemLoaded(path: string): boolean

Checks if an item at the given path is currently loaded in memory. This is a passive check that does not trigger loading the item.

keys()​

keys(path: string): Iterable<string>

Returns the keys at the specified path.

NOTE: Currently only paths to repositories are supported.

load()​

load(path: string, schema: S, data: SchemaDataType<S>): Promise<void>

Explicitly create an item, loading its repository if needed. Use this method for bulk load operations where you want to be notified after the write completes.

NOTE: This method uses a different internal path than the Item based API, and is much more efficient for bulk creations.

loginWithMagicLinkEmail()​

loginWithMagicLinkEmail(email: string): Promise<boolean>

When connecting to a new DB instance on the client, it'll start with an anonymous session that's not attached to any user in the system. Call this method with a user's email, to initiate an email-based login sequence that will end with the current session being attached to the user owning this email.

This login sequence sends a temporary magic link to the provided email address. Once clicked, the user item will be automatically created in /sys/users and attached to the current session.

logout()​

logout(): Promise<void>

Logs out the current user, closing all open repositories and clearing local data. On browsers, this method will also reload the page to ensure a clean state.

open()​

open(path: string, opts: OpenOptions): Promise<Repository<MemRepoStorage<>>>

Opens the given repository, loading all its items to memory. This method does nothing if the repository is already open.

query()​

query(config: Omit<QueryConfig<IS, OS, CTX>, 'db'>): Query<IS, OS, CTX>

Open a new query or access an already open one. Once opened, the query remains open until explicitly closed, and tracks updates to items as they happen.

readyPromise()​

readyPromise(): Promise<void>

A convenience promise form of the ready flag. When the promise returns, this DB instance is ready to receive commands.

repository()​

repository(pathComps: string[]): Repository<MemRepoStorage<>>

Returns the requested repository or undefined if it wasn't opened yet.

Note: Prefer to use the higher level APIs of this class rather than the repository instance directly.

sync()​

sync(path: string): Promise<SyncResult>

Syncs the given repository with all configured peers and waits for completion.

syncAll()​

syncAll(): Promise<Record<string, SyncResult>>

Syncs all open repositories with all configured peers and waits for completion.

Inherited Methods​

From Emitter​

attach(), detach(), detachAll(), emit(), mute(), once(), resume(), suspend(), unmute()

See Emitter for detailed documentation