JavaScript SDK reference

Repository lifecycle handles and typed clients exported by @thegarage/sdk.

@thegarage/sdk provides authenticated and anonymous repository handles plus typed low-level clients. Install it with:

npm install @thegarage/sdk

The package targets Node.js 24 and later. Its authenticated porcelain APIs can also run in browser and Worker-style runtimes when token, baseUrl, and optionally fetch are passed explicitly.

Lazy authenticated handle

garage(name, options?): Promise<AuthenticatedRepo>

Creates a lazy repository handle. Construction performs zero network I/O.

const repo = await garage('my-repo', {
  token,
  defaultBranch: 'trunk',
})

console.log(repo.defaultBranch) // null until server metadata is observed

Reads never create a repository or call repos.ensure, so a read-only flow continues to work with only repos:read. The first commit() provisions a missing repository. ensure() provisions without committing and shares its memo with the first commit.

Strict create and import

garage.create(name, options?): Promise<AuthenticatedRepo>

Always performs I/O. Creation is strict: an existing name throws RepoExistsError rather than opening the existing repository.

const created = await garage.create('new-repo', {
  token,
  defaultBranch: 'trunk',
})

const imported = await garage.create('imported-repo', {
  token,
  from: 'https://github.com/acme/project.git',
})

from routes to the GitHub import procedure. Only https://github.com remotes are accepted. Rejections throw ImportRemoteRejectedError with that allowlist in the SDK message.

Created and imported handles retain their complete RepoView, including the clone remote, effective permissions, size, source, and timestamps.

List repositories

garage.list(options?): Promise<RepoPage<AuthenticatedRepo>>

Returns { items, nextCursor }. Each item is an authenticated handle seeded with its complete cached RepoView.

The server page maximum is 100. A total limit over 100 auto-paginates with requests of min(100, remaining) and stops exactly at the requested cap. The default does not enumerate an entire organization implicitly.

const first = await garage.list({ token })
if (first.nextCursor) {
  const second = await garage.list({ token, cursor: first.nextCursor })
}

Repository handles

The shared handle is Repo<TView extends RepoView>. Public handles are split into AuthenticatedRepo and AnonymousRepo so anonymous-only view fields and authenticated-only mutations remain correctly typed.

Metadata and lifecycle

info() does not expose mutable cache state. Use info({ refresh: true }) to force a server read. exists() never provisions a repository.

An exists() that finds the repository gone clears the cached view and the memoized ensure() result together. The next ensure() re-runs create-or-open against the server instead of replaying the earlier outcome; anonymous handles cannot provision, so theirs throws RepoNotFoundError.

After successful deletion, exists() returns false; cached metadata is cleared and all other operations throw DeletedRepoHandleError. Construct a new handle to recreate or reattach. Anonymous deletion does not clear the persisted anonymous identity.

Git operations

For a missing lazy authenticated repository, ls() and log() return []. read() throws PathNotFoundError, matching an empty create-or-open handle. An existing repository with a missing path throws the same typed error. Anonymous 404s are never normalized.

Anonymous repository

garage.ephemeral(options?): Promise<AnonymousRepo>

With no name, creates a new randomly named repository. With name, first reattaches if the persisted identity owns that repository and creates it when missing. Concurrent creators converge by retrying the read when another creator wins the race. Supplying a TTL makes the named creation strict: if the repo already exists, TtlReattachUnsupportedError is thrown instead of silently ignoring the requested lifetime.

Pass either ttl or ttlSeconds; supplying both throws TtlConflictError. The accepted range is 60 seconds through 72 hours. configDir treats a missing anon.json as a new identity, but a damaged file throws InvalidAnonIdFileError.

Authentication resolution

Authenticated entry points use this precedence:

1. options.token, then Node.js GARAGE_API_KEY
2. options.baseUrl, then Node.js GARAGE_SERVER_URL, then https://api.thegarage.sh

An explicitly empty token throws MissingTokenError instead of falling back. Environment lookup uses guarded globalThis.process?.env access, so runtimes without process can use explicit options without a ReferenceError.

Errors

Every validation or lifecycle failure defined by the SDK extends GarageError and has a stable code. Porcelain RPC failures extend GarageRpcError, preserving status, structured data, the server message, and the raw oRPC error as cause. Known subclasses include:

• RepoNotFoundError, RepoExistsError, ForbiddenError
• QuotaExceededError, PayloadTooLargeError
• ImportRemoteRejectedError, ImportTooLargeError, ImportFailedError
• MissingTokenError, InvalidRepoNameError, InvalidApiKeyError
• InvalidTtlError, TtlConflictError, TtlReattachUnsupportedError, DeletedRepoHandleError
• InvalidAnonIdFileError, ConfigDirPersistenceUnsupportedError

Native network/runtime failures remain native errors.

Low-level clients

createClient(options): GarageSdkClient
createAnonClient(options): GarageAnonSdkClient

These expose the typed raw oRPC contracts. They intentionally retain raw oRPC errors rather than the porcelain GarageRpcError mapping.

Examples

• Commit files without cloning
• Create an anonymous repository
• Inspect a repository without cloning