1import type * as firestore from "@distilled.cloud/gcp/firestore_v1";
2import * as Data from "effect/Data";
3import type * as Effect from "effect/Effect";
4import * as Binding from "../../Binding.ts";
5import type { RuntimeContext } from "../../RuntimeContext.ts";
6import type { Database } from "./Database.ts";
7import type { DocumentSnapshot } from "./ReadDatabase.ts";
8
9/** `create` found a document already at `path`. */
10export class DocumentAlreadyExists extends Data.TaggedError(
11 "GCP.Firestore.DocumentAlreadyExists",
12)<{
13 path: string;
14 message: string;
15}> {}
16
17/** Write-only client for one Firestore database. */
18export interface WriteDatabaseClient {
19 /**
20 * Create or overwrite the document at `path` (`"users/alice"`) with
21 * exactly `fields` (plain JavaScript, encoded to Firestore `Value`s).
22 */
23 set(
24 path: string,
25 fields: Record<string, unknown>,
26 ): Effect.Effect<
27 DocumentSnapshot,
28 firestore.PatchProjectsDatabasesDocumentsError,
29 RuntimeContext
30 >;
31 /**
32 * Update only the top-level keys of `fields` on an existing document
33 * (the update mask is `Object.keys(fields)`). Fails with `NotFound` when
34 * the document does not exist.
35 */
36 update(
37 path: string,
38 fields: Record<string, unknown>,
39 ): Effect.Effect<
40 DocumentSnapshot,
41 firestore.PatchProjectsDatabasesDocumentsError,
42 RuntimeContext
43 >;
44 /** Delete the document at `path`. Deleting a missing document succeeds. */
45 delete(
46 path: string,
47 ): Effect.Effect<
48 void,
49 firestore.DeleteProjectsDatabasesDocumentsError,
50 RuntimeContext
51 >;
52 /**
53 * Create the document at `path`; fails with
54 * {@link DocumentAlreadyExists} when it already exists.
55 */
56 create(
57 path: string,
58 fields: Record<string, unknown>,
59 ): Effect.Effect<
60 DocumentSnapshot,
61 | DocumentAlreadyExists
62 | Exclude<
63 firestore.CreateDocumentProjectsDatabasesDocumentsError,
64 { _tag: "Conflict" }
65 >,
66 RuntimeContext
67 >;
68}
69
70/**
71 * Write access to a Firestore {@link Database}: `set`, `update`, `delete`,
72 * `create`. Grants `roles/datastore.user` on the project under an IAM
73 * Condition naming this database (Firestore databases have no
74 * resource-level IAM policy).
75 *
76 * ### Writing documents
77 * **Example:** Create, update, and delete
78 * ```typescript
79 * const db = yield* GCP.Firestore.WriteDatabase(database);
80 * yield* db.create("users/alice", { name: "Alice", visits: 0 }).pipe(
81 * Effect.catchTag("GCP.Firestore.DocumentAlreadyExists", () => Effect.void),
82 * );
83 * yield* db.update("users/alice", { visits: 1, lastSeen: new Date() });
84 * yield* db.delete("users/bob");
85 * // …provided with Effect.provide(GCP.Firestore.WriteDatabaseHttp)
86 * ```
87 *
88 * @binding
89 * @category Firestore
90 */
91export interface WriteDatabase extends Binding.Service<
92 WriteDatabase,
93 "GCP.Firestore.WriteDatabase",
94 (database: Database) => Effect.Effect<WriteDatabaseClient>
95> {}
96
97export const WriteDatabase = Binding.Service<WriteDatabase>(
98 "GCP.Firestore.WriteDatabase",
99);