# Gitapp API reference

> Exports of @dev-bench/gitapp.

Source: https://gitapp.n.yatsyk.com/docs/gitapp/jsdoc

## Classes

### SerialQueue

Serial command queue — guarantees no two `run()` calls overlap.

Framework-agnostic: no MobX. Observers subscribe via callback on construction.

```ts
class SerialQueue
```

- `constructor(observers?: QueueObserver[]): SerialQueue`
- `<T>(id: string, label: string, run: () => Promise<T>): Promise<T>` — Add work to the end of the queue. Returns a promise that resolves (or
rejects) with the result once it's this item's turn to execute.
- `whenIdle(): Promise<void>` — Returns a promise that resolves when the queue is idle (no pending or
in-flight commands). Safe to call when already idle.
- `pause(): void`
- `resume(): void`

### WatchRegistry

```ts
class WatchRegistry
```

- `subscribe(prefix: string, cb: (event: WatchEvent) => void): () => void` — Subscribe to events for paths matching `prefix`.
Returns an unsubscribe function.
- `emit(event: WatchEvent): void` — Emit a watch event to all subscribers whose prefix matches at least one
of the changed paths.

## Functions

### runTransaction

Execute one transaction: resolve mutations → commit → push → handle conflicts.
Called from within the serial queue; guaranteed exclusive access to gitFs.

```ts
runTransaction(tx: Transaction, config: RunnerConfig): Promise<TransactionResult>
```

### runSyncIn

Pull from remote, fire watch events for changed paths, return SyncInResult.
Called from within the serial queue.

```ts
runSyncIn(config: RunnerConfig): Promise<SyncInResult>
```

### createGitAppDocStore

```ts
createGitAppDocStore(_config: GitAppDocStoreConfig): DocStore
```

## Interfaces

### GitAppDocStoreConfig

```ts
interface GitAppDocStoreConfig
```

- `gitFs: GitFs`
- `mgmt: RepoManagement`
- `repoRef: { provider: "github" | "gitea" | "gitlab"; owner: string; name: string; branch: string; proxyBase: string; }`
- `getToken: () => TokenLookup` — Token lookup is a function (not a value) so the docstore picks up
fresh tokens when the user re-auths without needing reconstruction.
- `author: Omit<{ name: string; email: string; timestampISO: string; }, "timestampISO"> & { readonly timestampISO: () => string; }` — Author identity for commits. `timestampISO` is a function so each
commit gets the current time — pass `() => new Date().toISOString()`
in prod, fix it in tests.

### RunnerConfig

```ts
interface RunnerConfig
```

- `gitFs: GitFs`
- `repoRef: { provider: "github" | "gitea" | "gitlab"; owner: string; name: string; branch: string; proxyBase: string; }`
- `getToken: () => TokenLookup`
- `author: Omit<{ name: string; email: string; timestampISO: string; }, "timestampISO"> & { readonly timestampISO: () => string; }`
- `watchRegistry: WatchRegistry`