sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Firestore/ ReadDatabase.ts

import type * as firestore from "@distilled.cloud/gcp/firestore_v1";
import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import type { Database } from "./Database.ts";

/**
 * A Firestore document read through a {@link ReadDatabase} client. `fields`
 * are decoded from Firestore `Value`s to plain JavaScript: integers →
 * `number` (`bigint` beyond the safe range), doubles → `number`,
 * timestamps → `Date`, bytes → `Uint8Array`, arrays and maps recursively,
 * geo points → `{ latitude, longitude }`, references → resource name.
 */
export interface DocumentSnapshot {
  /** Full resource name `projects/{p}/databases/{d}/documents/{path}`. */
  name: string;
  /** Decoded document fields. */
  fields: Record<string, unknown>;
  /** RFC 3339 creation time. */
  createTime: string | undefined;
  /** RFC 3339 last-update time. */
  updateTime: string | undefined;
}

export interface ListDocumentsOptions {
  /** Maximum documents per page. */
  pageSize?: number;
  /** Page token from a previous `list`. */
  pageToken?: string;
}

export interface ListDocumentsResult {
  documents: DocumentSnapshot[];
  /** Pass to the next `list` call; `undefined` on the last page. */
  nextPageToken: string | undefined;
}

/** Read-only client for one Firestore database. */
export interface ReadDatabaseClient {
  /**
   * Get a document by path relative to the database (`"users/alice"`), or
   * `undefined` when it does not exist.
   */
  get(
    path: string,
  ): Effect.Effect<
    DocumentSnapshot | undefined,
    firestore.GetProjectsDatabasesDocumentsError,
    RuntimeContext
  >;
  /**
   * One page of documents in a collection (`"users"`, or a subcollection
   * such as `"users/alice/posts"`).
   */
  list(
    collection: string,
    options?: ListDocumentsOptions,
  ): Effect.Effect<
    ListDocumentsResult,
    firestore.ListProjectsDatabasesDocumentsError,
    RuntimeContext
  >;
  /**
   * Run a Firestore `StructuredQuery` against the database root. Filter
   * values use the Firestore REST `Value` shape
   * (`{ integerValue: "2" }`, `{ stringValue: "a" }`, …).
   */
  query(
    structuredQuery: firestore.StructuredQuery,
  ): Effect.Effect<
    DocumentSnapshot[],
    firestore.RunQueryProjectsDatabasesDocumentsError,
    RuntimeContext
  >;
}

/**
 * Read access to a Firestore {@link Database}: `get`, `list`, `query`.
 * Grants `roles/datastore.viewer` on the project under an IAM Condition
 * naming this database (Firestore databases have no resource-level IAM
 * policy).
 *
 * ### Reading documents
 * **Example:** Get a document and list a collection
 * ```typescript
 * const db = yield* GCP.Firestore.ReadDatabase(database);
 * const alice = yield* db.get("users/alice");
 * const { documents } = yield* db.list("users", { pageSize: 20 });
 * // …provided with Effect.provide(GCP.Firestore.ReadDatabaseHttp)
 * ```
 *
 * ### Querying
 * **Example:** Filter a collection
 * ```typescript
 * const db = yield* GCP.Firestore.ReadDatabase(database);
 * const admins = yield* db.query({
 *   from: [{ collectionId: "users" }],
 *   where: {
 *     fieldFilter: {
 *       field: { fieldPath: "role" },
 *       op: "EQUAL",
 *       value: { stringValue: "admin" },
 *     },
 *   },
 * });
 * ```
 *
 * @binding
 * @category Firestore
 */
export interface ReadDatabase extends Binding.Service<
  ReadDatabase,
  "GCP.Firestore.ReadDatabase",
  (database: Database) => Effect.Effect<ReadDatabaseClient>
> {}

export const ReadDatabase = Binding.Service<ReadDatabase>("GCP.Firestore.ReadDatabase");