@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/src/firestore/internal/documentPath.ts

@@ -0,0 +1,53 @@
+import { Equal, Hash, Inspectable, Option, Predicate } from "effect";
+import type * as DocumentPath from "../DocumentPath.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/DocumentPath";
+
+/** A collection id, then a document id, and so on: an even number of non-empty segments. */
+const addressesDocument = (path: string): boolean => {
+  const segments = path.split("/");
+  return segments.length % 2 === 0 && segments.every((segment) => segment.length > 0);
+};
+
+/** @internal */
+export const isDocumentPath = (u: unknown): u is DocumentPath.DocumentPath =>
+  Predicate.hasProperty(u, TypeId) &&
+  u[TypeId] === TypeId &&
+  Predicate.hasProperty(u, "path") &&
+  Predicate.isString(u.path);
+
+const Proto: Omit<DocumentPath.DocumentPath, "path"> = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  toJSON(this: DocumentPath.DocumentPath) {
+    return { _id: "DocumentPath", path: this.path };
+  },
+  [Equal.symbol](this: DocumentPath.DocumentPath, that: unknown): boolean {
+    return isDocumentPath(that) && this.path === that.path;
+  },
+  [Hash.symbol](this: DocumentPath.DocumentPath): number {
+    return Hash.string(this.path);
+  },
+};
+
+/**
+ * Builds the value without checking `path`, for one that already addresses a
+ * document, such as a reference's own.
+ *
+ * @internal
+ */
+export const makeUnchecked = (path: string): DocumentPath.DocumentPath =>
+  Object.assign(Object.create(Proto) as typeof Proto, { path });
+
+/** @internal */
+export const make = (path: string): Option.Option<DocumentPath.DocumentPath> =>
+  addressesDocument(path) ? Option.some(makeUnchecked(path)) : Option.none();
+
+/** @internal */
+export const makeUnsafe = (path: string): DocumentPath.DocumentPath => {
+  if (!addressesDocument(path)) {
+    throw new Error(`Invalid Firestore document path "${path}": it must address a document`);
+  }
+  return makeUnchecked(path);
+};

package/src/firestore/internal/documentSnapshot.ts

@@ -0,0 +1,117 @@
+import { Effect, Inspectable, Predicate, Schema } from "effect";
+import type * as Collection from "../Collection.ts";
+import type * as DocumentSnapshot from "../DocumentSnapshot.ts";
+import * as firestoreValue from "./firestoreValue.ts";
+import { attach, extraToJson, type WithExtra } from "./snapshotExtra.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/DocumentSnapshot";
+
+/** @internal */
+export const isDocumentSnapshot = (
+  u: unknown,
+): u is DocumentSnapshot.DocumentSnapshot<Collection.Any> => Predicate.hasProperty(u, TypeId);
+
+/** @internal */
+export const isExisting = <C extends Collection.Any>(
+  self: DocumentSnapshot.DocumentSnapshot<C>,
+): self is DocumentSnapshot.Existing<C> => self._tag === "Existing";
+
+/** @internal */
+export const isMissing = <C extends Collection.Any>(
+  self: DocumentSnapshot.DocumentSnapshot<C>,
+): self is DocumentSnapshot.Missing<C> => self._tag === "Missing";
+
+/**
+ * The untyped shapes behind the exported ones.
+ *
+ * The schema is held as one that decodes with no services, which is what is
+ * left of the collection's own once its type is erased: `Existing<C>` is what
+ * puts the real ones back.
+ */
+interface ExistingImpl extends WithExtra {
+  readonly ref: {
+    readonly path: string;
+    readonly collection: { readonly schema: Schema.Decoder<unknown> };
+  };
+  readonly id: string;
+  readonly raw: unknown;
+}
+
+interface MissingImpl extends WithExtra {
+  readonly ref: Collection.DocumentReference<Collection.Any>;
+  readonly id: string;
+}
+
+const ExistingProto = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  _tag: "Existing" as const,
+  toJSON(this: ExistingImpl) {
+    return {
+      _id: "DocumentSnapshot",
+      _tag: "Existing",
+      ref: this.ref.path,
+      raw: Inspectable.toJson(this.raw),
+      ...extraToJson(this),
+    };
+  },
+  // A getter rather than a field, so that nothing is built until it is asked
+  // for. It suspends as well, because a schema that decodes synchronously
+  // decodes when it is called rather than when it is run, which would decode
+  // on reading `data` and replay that one result on every run.
+  // `raw` holds Firestore Values, which the SDK mapped its own values to, so it
+  // is decoded through the codec derived from the model rather than the model
+  // itself. Derivation is memoized, so this costs nothing after the first read.
+  get data(): Effect.Effect<unknown, Schema.SchemaError> {
+    const self = this as unknown as ExistingImpl;
+    return Effect.suspend(() =>
+      Schema.decodeUnknownEffect(firestoreValue.toCodecFirestore(self.ref.collection.schema))(
+        self.raw,
+      ),
+    );
+  },
+};
+
+const MissingProto = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  _tag: "Missing" as const,
+  toJSON(this: MissingImpl) {
+    return { _id: "DocumentSnapshot", _tag: "Missing", ref: this.ref.path, ...extraToJson(this) };
+  },
+};
+
+/** @internal */
+export const existing = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  data: unknown,
+  extra?: object,
+): DocumentSnapshot.Existing<C> => {
+  const self = Object.assign(Object.create(ExistingProto) as typeof ExistingProto, {
+    ref,
+    id: ref.id,
+    raw: data,
+  });
+  return attach(self, extra) as unknown as DocumentSnapshot.Existing<C>;
+};
+
+/** @internal */
+export const missing = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  extra?: object,
+): DocumentSnapshot.Missing<C> => {
+  const self: MissingImpl = Object.assign(Object.create(MissingProto) as typeof MissingProto, {
+    ref,
+    id: ref.id,
+  });
+  return attach(self, extra) as unknown as DocumentSnapshot.Missing<C>;
+};
+
+/** @internal */
+export const make = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  data: unknown,
+  extra?: object,
+): DocumentSnapshot.DocumentSnapshot<C> =>
+  data === undefined ? missing(ref, extra) : existing(ref, data, extra);

package/src/firestore/internal/fieldValue.ts

@@ -0,0 +1,119 @@
+import { Equal, Hash, Inspectable, Predicate } from "effect";
+import type * as FieldValue from "../FieldValue.ts";
+
+/** @internal */
+export const ServerTimestampTypeId =
+  "~@visiolab/effect-firebase/firestore/FieldValue/ServerTimestamp";
+
+const ServerTimestampProto: FieldValue.ServerTimestamp = {
+  ...Inspectable.BaseProto,
+  [ServerTimestampTypeId]: ServerTimestampTypeId,
+  toJSON() {
+    return { _id: "ServerTimestamp" };
+  },
+};
+
+/** @internal */
+export const serverTimestamp: FieldValue.ServerTimestamp = Object.create(
+  ServerTimestampProto,
+) as FieldValue.ServerTimestamp;
+
+/** @internal */
+export const isServerTimestamp = (u: unknown): u is FieldValue.ServerTimestamp =>
+  Predicate.hasProperty(u, ServerTimestampTypeId);
+
+/** @internal */
+export const IncrementTypeId = "~@visiolab/effect-firebase/firestore/FieldValue/Increment";
+
+/** @internal */
+export const isIncrement = (u: unknown): u is FieldValue.Increment =>
+  Predicate.hasProperty(u, IncrementTypeId);
+
+const IncrementProto: Omit<FieldValue.Increment, "by"> = {
+  ...Inspectable.BaseProto,
+  [IncrementTypeId]: IncrementTypeId,
+  toJSON(this: FieldValue.Increment) {
+    return { _id: "Increment", by: this.by };
+  },
+  [Equal.symbol](this: FieldValue.Increment, that: unknown): boolean {
+    return isIncrement(that) && this.by === that.by;
+  },
+  [Hash.symbol](this: FieldValue.Increment): number {
+    return Hash.combine(Hash.string(IncrementTypeId), Hash.number(this.by));
+  },
+};
+
+/** @internal */
+export const increment = (by: number): FieldValue.Increment => {
+  if (!Number.isFinite(by)) {
+    throw new Error(`Invalid Firestore increment: by must be a finite number, got ${by}`);
+  }
+  return Object.assign(Object.create(IncrementProto) as typeof IncrementProto, { by });
+};
+
+/** @internal */
+export const decrement = (by: number): FieldValue.Increment => increment(-by);
+
+/** @internal */
+export const DeleteFieldTypeId = "~@visiolab/effect-firebase/firestore/FieldValue/DeleteField";
+
+const DeleteFieldProto: FieldValue.DeleteField = {
+  ...Inspectable.BaseProto,
+  [DeleteFieldTypeId]: DeleteFieldTypeId,
+  toJSON() {
+    return { _id: "DeleteField" };
+  },
+};
+
+/** @internal */
+export const deleteField: FieldValue.DeleteField = Object.create(
+  DeleteFieldProto,
+) as FieldValue.DeleteField;
+
+/** @internal */
+export const isDeleteField = (u: unknown): u is FieldValue.DeleteField =>
+  Predicate.hasProperty(u, DeleteFieldTypeId);
+
+/** @internal */
+export const ArrayUnionTypeId = "~@visiolab/effect-firebase/firestore/FieldValue/ArrayUnion";
+
+const ArrayUnionProto: Omit<FieldValue.ArrayUnion<unknown>, "elements"> = {
+  ...Inspectable.BaseProto,
+  [ArrayUnionTypeId]: ArrayUnionTypeId,
+  toJSON(this: FieldValue.ArrayUnion<unknown>) {
+    return {
+      _id: "ArrayUnion",
+      elements: this.elements.map((element) => Inspectable.toJson(element)),
+    };
+  },
+};
+
+/** @internal */
+export const isArrayUnion = (u: unknown): u is FieldValue.ArrayUnion<unknown> =>
+  Predicate.hasProperty(u, ArrayUnionTypeId);
+
+/** @internal */
+export const arrayUnion = <A>(...elements: ReadonlyArray<A>): FieldValue.ArrayUnion<A> =>
+  Object.assign(Object.create(ArrayUnionProto) as typeof ArrayUnionProto, { elements });
+
+/** @internal */
+export const ArrayRemoveTypeId = "~@visiolab/effect-firebase/firestore/FieldValue/ArrayRemove";
+
+const ArrayRemoveProto: Omit<FieldValue.ArrayRemove<unknown>, "elements"> = {
+  ...Inspectable.BaseProto,
+  [ArrayRemoveTypeId]: ArrayRemoveTypeId,
+  toJSON(this: FieldValue.ArrayRemove<unknown>) {
+    return {
+      _id: "ArrayRemove",
+      elements: this.elements.map((element) => Inspectable.toJson(element)),
+    };
+  },
+};
+
+/** @internal */
+export const isArrayRemove = (u: unknown): u is FieldValue.ArrayRemove<unknown> =>
+  Predicate.hasProperty(u, ArrayRemoveTypeId);
+
+/** @internal */
+export const arrayRemove = <A>(...elements: ReadonlyArray<A>): FieldValue.ArrayRemove<A> =>
+  Object.assign(Object.create(ArrayRemoveProto) as typeof ArrayRemoveProto, { elements });

package/src/firestore/internal/firestore.ts

@@ -0,0 +1,322 @@
+import { Context, Effect, Result, Schema, Stream } from "effect";
+import type * as Collection from "../Collection.ts";
+import type * as CollectionGroup from "../CollectionGroup.ts";
+import type * as DocumentSnapshot from "../DocumentSnapshot.ts";
+import type * as Firestore from "../Firestore.ts";
+import type * as FirestoreModel from "../FirestoreModel.ts";
+import type * as QuerySnapshot from "../QuerySnapshot.ts";
+import * as collectionGroup from "./collectionGroup.ts";
+import * as documentSnapshot from "./documentSnapshot.ts";
+import * as firestoreValue from "./firestoreValue.ts";
+import * as firestoreValueWalk from "./firestoreValueWalk.ts";
+import * as querySnapshot from "./querySnapshot.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/Firestore";
+
+/** @internal */
+export const TransactionTypeId = "~@visiolab/effect-firebase/firestore/Firestore/Transaction";
+
+/** What `getDocs` and `streamDocs` read from: a collection, or a group. */
+type Source = Collection.CollectionReference<Collection.Any> | CollectionGroup.Any;
+
+/** The last segment of a document's path: its id. */
+const idOf = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
+
+/**
+ * What a hook is handed for `source`, and how each document it read is
+ * addressed: in the collection read, by its id, or, for a group, matched by
+ * its path to the collection of the group it lives in.
+ */
+const resolve = (
+  source: Source,
+): {
+  readonly selector: Firestore.CollectionSelector;
+  readonly refOf: (
+    path: string,
+  ) => Result.Result<
+    Collection.DocumentReference<Collection.Any>,
+    Firestore.UndefinedCollectionError
+  >;
+} =>
+  collectionGroup.isCollectionGroup(source)
+    ? {
+        selector: { _tag: "CollectionGroup", id: source.id },
+        refOf: (path) => collectionGroup.documentAt(source, path),
+      }
+    : {
+        selector: { _tag: "Collection", path: source.path },
+        refOf: (path) => Result.succeed(source.doc(source.collection.id.make(idOf(path)))),
+      };
+
+// The snapshot constructors put each field of the `extra` they are handed on
+// the snapshot, but are typed without it, so the two below say it is there.
+
+/** A snapshot of the document at `ref`, as a hook read it, with its extra. */
+const documentSnapshotOf = <C extends Collection.Any, Extra extends object>(
+  ref: Collection.DocumentReference<C>,
+  read: Firestore.DocumentRead<Extra>,
+): Result.Result<DocumentSnapshot.DocumentSnapshot<C> & Extra, Firestore.FirestoreError> =>
+  Result.map(
+    firestoreValueWalk.checkDocument(ref.path, read.data),
+    (data) =>
+      documentSnapshot.make(ref, data, read.extra) as DocumentSnapshot.DocumentSnapshot<C> & Extra,
+  );
+
+/**
+ * A snapshot of the documents a hook read, each addressed by `refOf`, with the
+ * extra of each and of the read as a whole.
+ */
+const querySnapshotOf = <Extra extends object>(
+  refOf: ReturnType<typeof resolve>["refOf"],
+  read: Firestore.QueryRead<Extra>,
+): Result.Result<
+  QuerySnapshot.QuerySnapshot<Collection.Any, Extra> & Extra,
+  Firestore.FirestoreError | Firestore.UndefinedCollectionError
+> =>
+  Result.map(
+    Result.all(
+      read.docs.map((doc) =>
+        Result.flatMap(refOf(doc.path), (ref) =>
+          Result.map(firestoreValueWalk.checkDocument(ref.path, doc.data), (data) =>
+            documentSnapshot.existing(ref, data, doc.extra),
+          ),
+        ),
+      ),
+    ),
+    (docs) =>
+      querySnapshot.make(docs, read.extra) as QuerySnapshot.QuerySnapshot<Collection.Any, Extra> &
+        Extra,
+  );
+
+/**
+ * Turns what is written, in the shape `schema` takes, into Firestore Values,
+ * through the codec derived from `schema`. Whatever services the schema
+ * encodes through are left for the caller to provide.
+ */
+const encode = <S extends Schema.Top>(schema: S, data: S["Type"]) =>
+  Schema.encodeEffect(firestoreValue.toCodecFirestore(schema))(data);
+
+/** A document, in its model's `create` shape. */
+const encodeCreate = <C extends Collection.Any>(collection: C, data: Firestore.Create<C>) => {
+  // Named so that the codec is derived from the schema `C` was defined with
+  // rather than from `Schema.Top`, which keeps the services it encodes through
+  // in the type instead of erasing them to `unknown`.
+  const schema: Collection.DocumentSchema<C>["create"] = collection.schema.create;
+  // A model is a struct, so it encodes to a map.
+  return encode(schema, data) as Effect.Effect<
+    Firestore.DocumentData,
+    Schema.SchemaError,
+    Collection.DocumentSchema<C>["create"]["EncodingServices"]
+  >;
+};
+
+/**
+ * A patch, in its model's update shape for `mode`, which encodes to a map from
+ * the field paths it writes at to what it writes there.
+ */
+const encodeUpdate = <C extends Collection.Any, Mode extends FirestoreModel.UpdateMode>(
+  collection: C,
+  data: Firestore.Update<C, Mode>,
+  mode: Mode | undefined,
+) => {
+  const schema = (
+    mode === "unchecked" ? collection.schema.updateUnchecked : collection.schema.update
+  ) as Firestore.UpdateSchema<C, Mode>;
+  // Both modes encode the same fields at the same paths, so they ask for the
+  // same services.
+  return encode(schema, data) as Effect.Effect<
+    Firestore.DocumentData,
+    Schema.SchemaError,
+    Collection.DocumentSchema<C>["update"]["EncodingServices"]
+  >;
+};
+
+/**
+ * Where reads and writes go: straight to the database, or into one attempt at
+ * a transaction, through the hooks of {@link Firestore.MakeOptions}, with
+ * `getDocs` only where the backend can read many documents there. `name`
+ * prefixes the span of each.
+ */
+interface Target<ReadOptions, Extra extends object>
+  extends
+    Pick<Firestore.MakeOptions<ReadOptions, never, Extra>, "getDoc" | "setDoc" | "updateDoc">,
+    Partial<Pick<Firestore.MakeOptions<ReadOptions, never, Extra>, "getDocs">> {
+  readonly name: string;
+}
+
+/**
+ * The reads and writes a {@link Firestore.Firestore} and a transaction share,
+ * made against `target`. Each runs in a span named after it, so traces read
+ * the same whichever backend answered.
+ */
+const operations = <ReadOptions, Extra extends object>(target: Target<ReadOptions, Extra>) => {
+  const span = (name: string) => Effect.withSpan(`${target.name}.${name}`);
+
+  const getDocs = target.getDocs;
+
+  return {
+    getDoc: <C extends Collection.Any>(
+      ref: Collection.DocumentReference<C>,
+      options?: ReadOptions,
+    ) =>
+      Effect.flatMap(target.getDoc(ref.path, options), (read) =>
+        Effect.fromResult(documentSnapshotOf(ref, read)),
+      ).pipe(span("getDoc")),
+
+    getDocs:
+      getDocs === undefined
+        ? undefined
+        : (source: Source, options?: ReadOptions) => {
+            const { selector, refOf } = resolve(source);
+            return Effect.flatMap(getDocs(selector, options), (read) =>
+              Effect.fromResult(querySnapshotOf(refOf, read)),
+            ).pipe(span("getDocs"));
+          },
+
+    setDoc: <C extends Collection.Any>(
+      ref: Collection.DocumentReference<C>,
+      data: Firestore.Create<C>,
+    ) =>
+      Effect.flatMap(encodeCreate(ref.collection, data), (encoded) =>
+        target.setDoc(ref.path, encoded),
+      ).pipe(span("setDoc")),
+
+    updateDoc: <C extends Collection.Any, Mode extends FirestoreModel.UpdateMode = "checked">(
+      ref: Collection.DocumentReference<C>,
+      data: Firestore.Update<C, Mode>,
+      options?: Firestore.UpdateOptions<Mode>,
+    ) =>
+      Effect.flatMap(encodeUpdate(ref.collection, data, options?.mode), (encoded) =>
+        target.updateDoc(ref.path, encoded),
+      ).pipe(span("updateDoc")),
+  };
+};
+
+/**
+ * The transaction a body reads and writes through, over the operations of one
+ * attempt.
+ */
+const transactionOf = <Operations extends Firestore.TransactionOperations>(
+  transaction: Operations,
+): Firestore.BuiltTransaction<Operations> => {
+  const readMany = transaction.getDocs;
+  const { getDoc, getDocs, setDoc, updateDoc } = operations<never, {}>({
+    name: "Firestore.Transaction",
+    getDoc: (path) => transaction.getDoc(path),
+    getDocs: readMany === undefined ? undefined : (selector) => readMany(selector),
+    setDoc: transaction.setDoc,
+    updateDoc: transaction.updateDoc,
+  });
+  // `getDocs` is there exactly where `Operations` has one, which is what
+  // `BuiltTransaction` says, though the compiler cannot follow it into the
+  // conditional type.
+  const portable = { [TransactionTypeId]: TransactionTypeId, getDoc, setDoc, updateDoc } as const;
+  return (
+    getDocs === undefined ? portable : { ...portable, getDocs }
+  ) as Firestore.BuiltTransaction<Operations>;
+};
+
+/**
+ * The key a transaction body finds its {@link Firestore.Transaction} under is
+ * handed in by the public module that defines it, so that this one only
+ * imports it as a type and the two do not import each other.
+ *
+ * @internal
+ */
+export const make = <
+  ReadOptions,
+  ListenOptions,
+  Extra extends object,
+  Operations extends Firestore.TransactionOperations,
+  TransactionServices,
+>(
+  options: Firestore.MakeOptions<
+    ReadOptions,
+    ListenOptions,
+    Extra,
+    Operations,
+    TransactionServices
+  >,
+  Transaction: typeof Firestore.Transaction,
+): Firestore.With<ReadOptions, ListenOptions, Extra, TransactionServices> & Firestore.Firestore => {
+  const { getDoc, getDocs, setDoc, updateDoc } = operations<ReadOptions, Extra>({
+    name: "Firestore",
+    getDoc: options.getDoc,
+    getDocs: options.getDocs,
+    setDoc: options.setDoc,
+    updateDoc: options.updateDoc,
+  });
+
+  const addDoc = <C extends Collection.Any>(
+    ref: Collection.CollectionReference<C>,
+    data: Firestore.Create<C>,
+  ) =>
+    Effect.flatMap(encodeCreate(ref.collection, data), (encoded) =>
+      Effect.map(options.addDoc(ref.path, encoded), (id) => ref.doc(ref.collection.id.make(id))),
+    ).pipe(Effect.withSpan("Firestore.addDoc"));
+
+  // Each read is decoded as it is pulled, so a reader that falls behind only
+  // decodes the latest one the hook kept.
+  const streamDoc = <C extends Collection.Any>(
+    ref: Collection.DocumentReference<C>,
+    listenOptions?: ListenOptions,
+  ) =>
+    Stream.mapEffect(options.streamDoc(ref.path, listenOptions), (read) =>
+      Effect.fromResult(documentSnapshotOf(ref, read)),
+    ).pipe(Stream.withSpan("Firestore.streamDoc"));
+
+  const streamDocs = (source: Source, listenOptions?: ListenOptions) => {
+    const { selector, refOf } = resolve(source);
+    return Stream.mapEffect(options.streamDocs(selector, listenOptions), (read) =>
+      Effect.fromResult(querySnapshotOf(refOf, read)),
+    ).pipe(Stream.withSpan("Firestore.streamDocs"));
+  };
+
+  const runTransaction = Effect.fn("Firestore.runTransaction")(function* <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    transactionOptions?: Firestore.TransactionOptions,
+  ) {
+    // Captured inside the span, so the body's own spans hang off it, and
+    // handed to the body whole, so it needs nothing from wherever the hook
+    // runs it.
+    const context =
+      yield* Effect.context<Exclude<R, Firestore.Transaction | TransactionServices>>();
+    const offer = options.runTransaction.context;
+    const maxAttempts = transactionOptions?.maxAttempts;
+
+    return yield* options.runTransaction.run(
+      (operations) => {
+        // One transaction, under every tag, so that helpers asking for any of
+        // them read and write through it alike.
+        const transaction = transactionOf(operations);
+        const withTransaction = Context.add(context, Transaction, transaction);
+        return Effect.provideContext(
+          effect,
+          (offer === undefined
+            ? withTransaction
+            : Context.merge(withTransaction, offer(transaction))) as Context.Context<R>,
+        );
+      },
+      // Left out rather than `undefined` where it is not set, since some
+      // backends read `undefined` as no retries at all.
+      maxAttempts === undefined ? {} : { maxAttempts },
+    );
+  });
+
+  const service: Firestore.With<ReadOptions, ListenOptions, Extra, TransactionServices> = {
+    getDoc,
+    getDocs: getDocs as Firestore.With<ReadOptions, never, Extra>["getDocs"],
+    setDoc,
+    updateDoc,
+    addDoc,
+    streamDoc,
+    streamDocs: streamDocs as Firestore.With<never, ListenOptions, Extra>["streamDocs"],
+    runTransaction,
+  };
+  // Every backend's service is a portable Firestore too: its reads and listens
+  // only add optional options, its snapshots only add fields, and its
+  // transaction bodies need no more than a portable one's. The compiler cannot
+  // check that for unknown type parameters.
+  return { [TypeId]: TypeId, ...service } as typeof service & Firestore.Firestore;
+};

package/src/firestore/internal/firestoreError.ts

@@ -0,0 +1,36 @@
+/**
+ * The errors of the Firestore module, defined apart from it so that the
+ * modules it builds on can raise them without importing it back: the public
+ * module imports its implementation, and an import cycle through it would
+ * leave these unset while a bundle evaluates.
+ */
+import { Schema } from "effect";
+
+/** @internal */
+export class FirestoreError extends Schema.TaggedError<
+  FirestoreError,
+  { readonly brand: unique symbol }
+>()("FirestoreError", {
+  message: Schema.String,
+  /**
+   * The code the SDK reported, where it reported one it can be named by.
+   *
+   * The client SDK names every failure, such as `permission-denied`. The Admin
+   * SDK answers for Firestore over gRPC, which numbers its statuses rather than
+   * naming them, so there this is often absent even where something went wrong
+   * at the database.
+   */
+  code: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.Defect()),
+}) {}
+
+/** @internal */
+export class UndefinedCollectionError extends Schema.TaggedError<
+  UndefinedCollectionError,
+  { readonly brand: unique symbol }
+>()("UndefinedCollectionError", {
+  /** The full path of the document no collection of the group defines. */
+  path: Schema.String,
+  /** The collection id of the group that was read. */
+  collectionId: Schema.String,
+}) {}