$doc

A composable toolkit for interacting with individual Firestore documents inside your application. Designed for DX, clarity, and observability using Result and Option types. Built to integrate smoothly with your agency's Firebase + Nuxt ecosystem.

API: $doc(path)

Creates a Firestore document handler for the provided string path.

const userDoc = $doc("users/abc123")

Generic Parameters

• Path extends string: A Firestore-style document path (e.g. users/abc123).
• Type inference is automatically applied via GetTypeAtStringPath<FirestoreSchema, Path>.

Returned Methods

Each method returns a Result<T, string> type, allowing for easy chaining, branching, and error handling.

.get()

Fetches the document at the given path.

const result = await $doc("users/abc").get()

Returns:

• ok(data) if document exists
• ok(null) if document does not exist
• err(message) on fetch failure

.exists()

Checks if the document exists.

const exists = await $doc("users/abc").exists()

Returns:

• ok(true | false)
• err(message) if query fails

.set(newData)

Writes (merges) data to the document. Supports strict or partial typing.

await $doc("users/abc").set({ name: "Jane" })

Supports optional type safety via TFull extends true:

set<true>({ id: string, name: string }) // full
set<false>({ name: string }) // partial

Returns:

• ok(null) on success
• err(message) on failure

.delete()

Deletes the document at the given path.

await $doc("users/abc").delete()

Returns:

• ok(null) on success
• err(message) on failure

Server-Safe Behavior

When used in a non-client environment (e.g., SSR or server middleware), all methods become inert and return mock ok() results. This makes $doc() SSR-safe by default.

if (!import.meta.client) return ok(null)

Benefits

• ✅ Returns are fully typed and observable
• ✅ Plays well with $result() and option() utilities
• ✅ SSR-safe by default
• ✅ Composable and chainable
• ✅ Clear and explicit control over document interaction

Example Usage

const doc = $doc("users/john123")

const result = await doc.get()
$result(result).match({
    ok: ({ data }) => renderUser(data),
    err: (e) => showError(e.message),
})

Use $doc() wherever you want safer, more ergonomic Firestore document access. Fully observable, fully typed, and integrated with your platform-wide utilities.