@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/firestore/Firestore.mjs

@@ -0,0 +1,274 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { FirestoreError, UndefinedCollectionError } from "./internal/firestoreError.mjs";
+import { make as make$1 } from "./internal/firestore.mjs";
+import { streamFromListener as streamFromListener$1 } from "./internal/streamFromListener.mjs";
+import { transactionFromCallback as transactionFromCallback$1 } from "./internal/transactionFromCallback.mjs";
+import { Context } from "effect";
+// src/firestore/Firestore.ts
+/**
+* Reading and writing Firestore documents as an Effect service.
+*
+* {@link Firestore} is the portable service: it reads, listens to, writes and
+* updates documents, and runs transactions, the same way on every backend.
+* Every call is addressed by a reference built from a
+* {@link Collection.Collection}, whose {@link FirestoreModel} encodes what is
+* written and decodes what is read.
+*
+* - Define documents with {@link FirestoreModel.Class} and where they live with
+*   {@link Collection.make}.
+* - Provide the service with {@link AdminFirestore.layer} on a server, or
+*   {@link ClientFirestore.layer} in a browser or app. Each layer also provides
+*   its richer service, {@link AdminFirestore.AdminFirestore} or
+*   {@link ClientFirestore.ClientFirestore}, as the same object.
+* - Implement a backend of your own with {@link make}.
+*
+* @example Reading and writing a document
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, DocumentSnapshot, Firestore, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class User extends FirestoreModel.Class<User>("User")({ name: Schema.String }) {}
+*
+* const Users = Collection.make("users", User);
+*
+* const program = Effect.gen(function* () {
+*   const firestore = yield* Firestore.Firestore;
+*   const alice = Users.doc(Users.id.make("alice"));
+*
+*   yield* firestore.setDoc(alice, { name: "Alice" });
+*
+*   const snapshot = yield* firestore.getDoc(alice);
+*   if (DocumentSnapshot.isExisting(snapshot)) {
+*     const user = yield* snapshot.data;
+*     yield* Effect.log(user.name);
+*   }
+* });
+* ```
+*
+* @stability unstable
+* @since 0.2.0
+*/
+var Firestore_exports = /* @__PURE__ */ __exportAll({
+	Firestore: () => Firestore,
+	FirestoreError: () => FirestoreError,
+	Transaction: () => Transaction,
+	UndefinedCollectionError: () => UndefinedCollectionError,
+	make: () => make,
+	streamFromListener: () => streamFromListener,
+	transactionFromCallback: () => transactionFromCallback
+});
+/**
+* Service key for the {@link Transaction} a {@link With.runTransaction} body
+* runs in.
+*
+* @stability unstable
+* @category services
+* @since 0.2.0
+*/
+const Transaction = Context.Service("@visiolab/effect-firebase/firestore/Firestore/Transaction");
+/**
+* Service key for the portable {@link Firestore}.
+*
+* Provide it with {@link AdminFirestore.layer} or
+* {@link ClientFirestore.layer}.
+*
+* @stability unstable
+* @category services
+* @since 0.2.0
+*/
+const Firestore = Context.Service("@visiolab/effect-firebase/firestore/Firestore");
+/**
+* Builds a Firestore service from one backend's hooks.
+*
+* **When to use**
+*
+* Use to implement a backend, such as a new SDK or an in-memory fake for
+* tests. Applications use a backend's layer instead, such as
+* {@link AdminFirestore.layer} or {@link ClientFirestore.layer}.
+*
+* **Details**
+*
+* The hooks only move Firestore Values to and from the backend. `make`
+* handles everything above them, the same way for every backend:
+*
+* - encoding writes through the collection's model, in its `create` shape or
+*   the update shape for the requested mode
+* - decoding reads into snapshots, with any extra the hooks return
+* - matching each document of a Collection Group to its collection
+* - tracing spans
+* - providing the {@link Transaction} a transaction body runs in
+*
+* The return type is inferred from the hooks: a {@link With} whose reads and
+* listens take the options the hooks take, whose snapshots carry the extra
+* they return, and whose transaction bodies get the services the transaction
+* hook's `context` offers. It is always the portable {@link Firestore} as
+* well, so a backend can provide it under {@link Firestore}.
+*
+* A backend's richer service extends {@link With}, not {@link Firestore}, has a
+* type id of its own, and its key's service type adds {@link Firestore} back,
+* as {@link AdminFirestore.AdminFirestore} does. Its type then stays apart from
+* {@link Firestore}, so providing a {@link Firestore} alone does not satisfy
+* code that asks for the richer one.
+*
+* @see {@link transactionFromCallback} to build the `runTransaction` hook from an SDK callback
+* @see {@link streamFromListener} to build the `streamDoc` and `streamDocs` hooks from an SDK listener
+*
+* @example An in-memory backend
+* ```ts
+* import { Effect, Layer, Stream } from "effect";
+* import { Firestore } from "@visiolab/effect-firebase/firestore";
+*
+* const documents = new Map<string, Firestore.DocumentData>();
+*
+* const getDoc = (path: string) => Effect.sync(() => ({ data: documents.get(path) }));
+* const setDoc = (path: string, data: Firestore.DocumentData) =>
+*   Effect.sync(() => void documents.set(path, data));
+* const updateDoc = (path: string, data: Firestore.DocumentData) =>
+*   Effect.sync(() => void documents.set(path, { ...documents.get(path), ...data }));
+* const getDocs = (selector: Firestore.CollectionSelector) =>
+*   Effect.sync(() => ({
+*     docs: [...documents]
+*       .filter(([path]) => selector._tag === "Collection" && path.startsWith(`${selector.path}/`))
+*       .map(([path, data]) => ({ path, data })),
+*   }));
+*
+* const firestore = Firestore.make({
+*   getDoc,
+*   getDocs,
+*   setDoc,
+*   updateDoc,
+*   addDoc: (path, data) => {
+*     const id = crypto.randomUUID();
+*     return Effect.as(setDoc(`${path}/${id}`, data), id);
+*   },
+*   streamDoc: (path) => Stream.fromEffect(getDoc(path)),
+*   streamDocs: (selector) => Stream.fromEffect(getDocs(selector)),
+*   runTransaction: { run: (body) => body({ getDoc, setDoc, updateDoc }) },
+* });
+*
+* const FirestoreInMemory = Layer.succeed(Firestore.Firestore, firestore);
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const make = (options) => make$1(options, Transaction);
+/**
+* Builds the {@link MakeOptions.runTransaction} hook for an SDK that runs a
+* transaction as a callback and retries it. It is the counterpart of Effect's
+* `SqlClient.makeWithTransaction`.
+*
+* **When to use**
+*
+* Use when implementing a backend over an SDK with a
+* `runTransaction(callback)` API, such as the Admin or client SDK.
+*
+* **Details**
+*
+* Each attempt runs the body over that attempt's operations. What the
+* callback throws for a failed body decides whether the SDK retries it:
+*
+* - A {@link FirestoreError} with a `cause` throws that cause, so the SDK
+*   retries by its own rules, as for a read answered with `ABORTED`.
+* - Any other failure throws a marker without a `code`, which the SDK never
+*   retries, even when the body's own error carries a `code`.
+*
+* A failure the SDK returns without retrying comes back as the body's own
+* error, unwrapped. Anything else the SDK rejects with goes through
+* `onError`. Interrupting the transaction interrupts the body and waits for
+* the SDK to roll back.
+*
+* `Operations` is inferred from `operations`, so `context` receives a
+* transaction with `getDocs` exactly when `operations` has one.
+*
+* @see {@link make} for the service this hook is part of
+* @see {@link streamFromListener} for the matching helper for listeners
+*
+* @example Wrapping an SDK's runTransaction
+* ```ts
+* import { Effect } from "effect";
+* import { Firestore } from "@visiolab/effect-firebase/firestore";
+*
+* interface SdkTransaction {
+*   get(path: string): Promise<Firestore.DocumentData | undefined>;
+*   set(path: string, data: Firestore.DocumentData): void;
+*   update(path: string, data: Firestore.DocumentData): void;
+* }
+*
+* declare const db: {
+*   runTransaction<A>(callback: (tx: SdkTransaction) => Promise<A>, options?: object): Promise<A>;
+* };
+*
+* const fail = (cause: unknown) => new Firestore.FirestoreError({ message: "Transaction failed", cause });
+*
+* const runTransaction = Firestore.transactionFromCallback({
+*   run: (callback, options) => db.runTransaction(callback, options),
+*   operations: (tx: SdkTransaction) => ({
+*     getDoc: (path: string) =>
+*       Effect.tryPromise({ try: () => tx.get(path), catch: fail }).pipe(
+*         Effect.map((data) => ({ data })),
+*       ),
+*     setDoc: (path: string, data: Firestore.DocumentData) => Effect.sync(() => tx.set(path, data)),
+*     updateDoc: (path: string, data: Firestore.DocumentData) =>
+*       Effect.sync(() => tx.update(path, data)),
+*   }),
+*   onError: fail,
+* });
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const transactionFromCallback = transactionFromCallback$1;
+/**
+* Builds a listen hook's stream, such as {@link MakeOptions.streamDoc}, from
+* an SDK listener that returns a function to stop listening.
+*
+* **When to use**
+*
+* Use when implementing a backend over an SDK with an `onSnapshot`-style
+* listener.
+*
+* **Details**
+*
+* Each run of the stream attaches its own listener through `subscribe`, and
+* detaches it when the run stops. A reader that falls behind only sees the
+* latest snapshot.
+*
+* `map` turns each snapshot into what the stream emits. A snapshot it fails on
+* fails the stream instead of throwing into the SDK. An error the listener
+* receives fails the stream with what `onError` builds from it.
+*
+* @see {@link make} for the service this hook is part of
+* @see {@link transactionFromCallback} for the matching helper for transactions
+*
+* @example Wrapping an SDK listener
+* ```ts
+* import { Result } from "effect";
+* import { Firestore } from "@visiolab/effect-firebase/firestore";
+*
+* declare const sdk: {
+*   onSnapshot(
+*     path: string,
+*     onNext: (data: Firestore.DocumentData | undefined) => void,
+*     onError: (error: unknown) => void,
+*   ): () => void;
+* };
+*
+* const streamDoc = (path: string) =>
+*   Firestore.streamFromListener({
+*     subscribe: (onNext, onError) => sdk.onSnapshot(path, onNext, onError),
+*     onError: (cause) =>
+*       new Firestore.FirestoreError({ message: `Failed to listen to "${path}"`, cause }),
+*     map: (data) => Result.succeed({ data }),
+*   });
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const streamFromListener = streamFromListener$1;
+export { Firestore, FirestoreError, Firestore_exports, Transaction, UndefinedCollectionError, make, streamFromListener, transactionFromCallback };