@visiolab/effect-firebase 0.0.0-stage → 0.3.1

package/src/firestore/Timestamp.ts

@@ -0,0 +1,302 @@
+/**
+ * Firestore timestamps, independent of either SDK.
+ *
+ * Firestore stores an instant as whole seconds since the Unix epoch plus a
+ * non-negative count of nanoseconds, and each SDK reads it back as its own
+ * `Timestamp` class. This module owns a portable version of that value, so a
+ * document schema works the same under the Admin SDK and the client SDK.
+ *
+ * Its schema is {@link FirestoreSchema.Timestamp}.
+ *
+ * @see {@link FirestoreSchema.Timestamp} for storing a `Timestamp` in a document
+ * @see {@link FirestoreModel.Timestamp} for a timestamp field the server may fill in
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { DateTime, Effect, Equal, Inspectable, Option, Order as order } from "effect";
+import * as timestamp from "./internal/timestamp.ts";
+
+const TypeId = timestamp.TypeId;
+
+/**
+ * An instant, stored the way Firestore stores it.
+ *
+ * **When to use**
+ *
+ * Use when a document is read, written back, and has to come out unchanged.
+ * Firestore keeps timestamps to the microsecond, which `DateTime.Utc` and
+ * `Date` cannot hold, so this is the only representation that round-trips
+ * exactly.
+ *
+ * **Details**
+ *
+ * Two timestamps are equal when their `seconds` and `nanoseconds` are.
+ * Firestore addresses instants from the start of year 1 to the end of year
+ * 9999, and every constructor here checks for that range.
+ *
+ * @see {@link FirestoreSchema.Timestamp} for the schema of this value
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Timestamp extends Equal.Equal, Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /** Seconds since the Unix epoch, negative before it. */
+  readonly seconds: number;
+  /** The fraction of that second, from 0 to 999,999,999. */
+  readonly nanoseconds: number;
+}
+
+/**
+ * Checks whether `u` is a {@link Timestamp} built by this module.
+ *
+ * An SDK's own `Timestamp` is not one.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isTimestamp: (u: unknown) => u is Timestamp = timestamp.isTimestamp;
+
+/**
+ * Builds a timestamp from seconds and nanoseconds, throwing on values
+ * Firestore cannot store.
+ *
+ * **When to use**
+ *
+ * Use for values known to be valid, such as constants. Use {@link make} for
+ * values you have not checked.
+ *
+ * **Details**
+ *
+ * Throws unless `seconds` is an integer from year 1 to year 9999, and
+ * `nanoseconds` is an integer from 0 to 999,999,999.
+ *
+ * @example Building a timestamp
+ * ```ts
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const epoch = Timestamp.makeUnsafe(0, 0);
+ * ```
+ *
+ * @see {@link make} for the same check returning an `Option`
+ * @see {@link fromMillisUnsafe} for building one from milliseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const makeUnsafe: (seconds: number, nanoseconds: number) => Timestamp = timestamp.makeUnsafe;
+
+/**
+ * Builds a timestamp from seconds and nanoseconds, or `None` for values
+ * Firestore cannot store.
+ *
+ * **When to use**
+ *
+ * Use when the fields come from outside the program, such as a request body,
+ * and may be invalid.
+ *
+ * **Details**
+ *
+ * Returns `None` unless `seconds` is an integer from year 1 to year 9999, and
+ * `nanoseconds` is an integer from 0 to 999,999,999.
+ *
+ * @example Building a timestamp from untrusted input
+ * ```ts
+ * import { Option } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const valid = Timestamp.make(1_700_000_000, 500); // Option.some(...)
+ * const invalid = Timestamp.make(0, -1); // Option.none()
+ *
+ * Option.isSome(valid); // true
+ * Option.isNone(invalid); // true
+ * ```
+ *
+ * @see {@link makeUnsafe} for the same check throwing instead
+ * @see {@link fromMillis} for building one from milliseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: (seconds: number, nanoseconds: number) => Option.Option<Timestamp> =
+  timestamp.make;
+
+/**
+ * Builds a timestamp from milliseconds since the Unix epoch, throwing outside
+ * the range Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with millisecond values known to be in range, such as `Date.now()`.
+ *
+ * @example Building a timestamp from milliseconds
+ * ```ts
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const timestamp = Timestamp.fromMillisUnsafe(Date.now());
+ * ```
+ *
+ * @see {@link fromMillis} for the same check returning an `Option`
+ * @see {@link makeUnsafe} for building one from seconds and nanoseconds
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const fromMillisUnsafe: (millis: number) => Timestamp = timestamp.fromMillisUnsafe;
+
+/**
+ * Builds a timestamp from milliseconds since the Unix epoch, or `None` outside
+ * the range Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with millisecond values that may be out of range or not finite.
+ *
+ * @see {@link fromMillisUnsafe} for the same check throwing instead
+ * @see {@link toMillis} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const fromMillis: (millis: number) => Option.Option<Timestamp> = timestamp.fromMillis;
+
+/**
+ * Builds a timestamp from a `DateTime.Utc`, throwing outside the range
+ * Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with a `DateTime` known to fall between year 1 and year 9999, which
+ * covers almost every real date.
+ *
+ * **Details**
+ *
+ * A `DateTime.Utc` only carries milliseconds, so the result has no finer
+ * digits.
+ *
+ * @example Converting a DateTime
+ * ```ts
+ * import { DateTime } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const timestamp = Timestamp.fromDateTimeUnsafe(DateTime.makeUnsafe("2024-01-01T00:00:00Z"));
+ * ```
+ *
+ * @see {@link fromDateTime} for the same check returning an `Option`
+ * @see {@link toDateTime} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const fromDateTimeUnsafe: (dateTime: DateTime.Utc) => Timestamp =
+  timestamp.fromDateTimeUnsafe;
+
+/**
+ * Builds a timestamp from a `DateTime.Utc`, or `None` outside the range
+ * Firestore stores.
+ *
+ * **When to use**
+ *
+ * Use with a `DateTime` that may fall outside year 1 to year 9999, such as one
+ * parsed from user input.
+ *
+ * **Details**
+ *
+ * A `DateTime.Utc` only carries milliseconds, so the result has no finer
+ * digits.
+ *
+ * @see {@link fromDateTimeUnsafe} for the same check throwing instead
+ * @see {@link toDateTime} for the reverse conversion
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const fromDateTime: (dateTime: DateTime.Utc) => Option.Option<Timestamp> =
+  timestamp.fromDateTime;
+
+/**
+ * The current instant, read from Effect's `Clock`, to the millisecond.
+ *
+ * **When to use**
+ *
+ * Use when the time this program sees is the one to store, and when a test
+ * should control it through `TestClock`.
+ *
+ * **Details**
+ *
+ * This is the local clock, not the database's. Clients with skewed clocks
+ * write different times for the same moment.
+ *
+ * @example Reading the current time
+ * ```ts
+ * import { Effect } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const program = Effect.gen(function* () {
+ *   const now = yield* Timestamp.now;
+ *   return Timestamp.toMillis(now);
+ * });
+ * ```
+ *
+ * @see {@link FieldValue.serverTimestamp} for the time the server applies the write
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const now: Effect.Effect<Timestamp> = timestamp.now;
+
+/**
+ * Converts a timestamp to milliseconds since the Unix epoch, dropping the
+ * finer digits.
+ *
+ * @see {@link fromMillis} for the reverse conversion
+ * @see {@link toDateTime} for converting to a `DateTime.Utc`
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export const toMillis: (self: Timestamp) => number = timestamp.toMillis;
+
+/**
+ * Converts a timestamp to a `DateTime.Utc`, dropping the digits finer than a
+ * millisecond.
+ *
+ * @see {@link fromDateTime} for the reverse conversion
+ * @see {@link toMillis} for converting to milliseconds
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export const toDateTime: (self: Timestamp) => DateTime.Utc = timestamp.toDateTime;
+
+/**
+ * Orders timestamps from earliest to latest, at full precision.
+ *
+ * @example Sorting timestamps
+ * ```ts
+ * import { Array } from "effect";
+ * import { Timestamp } from "@visiolab/effect-firebase/firestore";
+ *
+ * const sorted = Array.sort(
+ *   [Timestamp.makeUnsafe(2, 0), Timestamp.makeUnsafe(1, 500)],
+ *   Timestamp.Order,
+ * );
+ * ```
+ *
+ * @stability unstable
+ * @category ordering
+ * @since 0.2.0
+ */
+export const Order: order.Order<Timestamp> = timestamp.Order;

package/src/firestore/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Firestore.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as Collection from "./Collection.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as CollectionGroup from "./CollectionGroup.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as DocumentPath from "./DocumentPath.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as DocumentSnapshot from "./DocumentSnapshot.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as FieldValue from "./FieldValue.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as Firestore from "./Firestore.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as FirestoreModel from "./FirestoreModel.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as FirestoreSchema from "./FirestoreSchema.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as FirestoreValue from "./FirestoreValue.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as GeoPoint from "./GeoPoint.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as Patch from "./Patch.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as QuerySnapshot from "./QuerySnapshot.ts";
+/**
+ * @stability unstable
+ * @since 0.2.0
+ */
+export * as Timestamp from "./Timestamp.ts";

package/src/firestore/internal/collection.ts

@@ -0,0 +1,246 @@
+import { Equal, Hash, Inspectable, Option, Predicate, Schema } from "effect";
+import type * as Collection from "../Collection.ts";
+import type * as FirestoreModel from "../FirestoreModel.ts";
+import * as documentSnapshot from "./documentSnapshot.ts";
+
+/** @internal */
+export const CollectionTypeId = "~@visiolab/effect-firebase/firestore/Collection";
+
+/** @internal */
+export const CollectionReferenceTypeId = "~@visiolab/effect-firebase/firestore/CollectionReference";
+
+/** @internal */
+export const DocumentReferenceTypeId = "~@visiolab/effect-firebase/firestore/DocumentReference";
+
+/** @internal */
+export const isCollection = (u: unknown): u is Collection.Any =>
+  Predicate.hasProperty(u, CollectionTypeId);
+
+/** @internal */
+export const isCollectionReference = (
+  u: unknown,
+): u is Collection.CollectionReference<Collection.Any> =>
+  Predicate.hasProperty(u, CollectionReferenceTypeId);
+
+/** @internal */
+export const isDocumentReference = (
+  u: unknown,
+): u is Collection.DocumentReference<Collection.Any> =>
+  Predicate.hasProperty(u, DocumentReferenceTypeId);
+
+const encoder = new TextEncoder();
+
+/** Rejects the segments Firestore cannot address, before they reach a path. */
+const validateSegment = (segment: string): void => {
+  const reject = (reason: string): never => {
+    throw new Error(`Invalid Firestore collection id "${segment}": ${reason}`);
+  };
+  if (segment.length === 0) reject("it must not be empty");
+  if (segment.includes("/")) reject('it must not contain "/"');
+  if (segment === "." || segment === "..") reject('it must not be "." or ".."');
+  if (/^__.*__$/.test(segment)) reject('it must not match "__.*__"');
+  if (encoder.encode(segment).length > 1500) reject("it must be at most 1500 bytes");
+};
+
+/**
+ * Brands an id schema with the path addressing it.
+ *
+ * The path is only known at runtime, and `Schema.brand` rejects an open `string`
+ * key. Narrowing the key to a placeholder literal keeps the real path on the
+ * annotation: the static brand is erased where `makeCollection` takes the schema
+ * as `Schema.Top`, and the public id types are built above it.
+ */
+const brandId = (path: ReadonlyArray<string>) =>
+  Schema.String.pipe(Schema.brand(path.join("/") as "~firestore/collection-path"));
+
+/** Interleaves the segments with the ids addressing them: `a/1/b/2/c`. */
+const joinPath = (segments: ReadonlyArray<string>, ancestors: ReadonlyArray<string>): string => {
+  let path = segments[0];
+  for (let i = 0; i < ancestors.length; i++) path += `/${ancestors[i]}/${segments[i + 1]}`;
+  return path;
+};
+
+/**
+ * The untyped shapes behind the exported ones.
+ *
+ * Everything below works on plain segments and ids. The public types are what
+ * make a path only buildable out of the ids that address it, so the runtime has
+ * no work left to do beyond joining strings.
+ */
+interface CollectionImpl {
+  readonly path: ReadonlyArray<string>;
+  readonly segment: string;
+  readonly schema: FirestoreModel.Any;
+  readonly id: Schema.Top;
+  contains(value: unknown): boolean;
+  subcollection(segment: string, schema: FirestoreModel.Any): CollectionImpl;
+  collection(...ancestors: ReadonlyArray<string>): CollectionReferenceImpl;
+  doc(...ids: ReadonlyArray<string>): DocumentReferenceImpl;
+}
+
+interface CollectionReferenceImpl {
+  readonly collection: CollectionImpl;
+  readonly ancestors: ReadonlyArray<string>;
+  readonly id: string;
+  readonly path: string;
+  doc(id: string): DocumentReferenceImpl;
+}
+
+interface DocumentReferenceImpl {
+  readonly collection: CollectionImpl;
+  readonly ancestors: ReadonlyArray<string>;
+  readonly id: string;
+  readonly path: string;
+  readonly parent: CollectionReferenceImpl;
+}
+
+const CollectionProto = {
+  ...Inspectable.BaseProto,
+  [CollectionTypeId]: CollectionTypeId,
+  toJSON(this: CollectionImpl) {
+    return { _id: "Collection", path: this.path.join("/") };
+  },
+  subcollection(this: CollectionImpl, segment: string, schema: FirestoreModel.Any): CollectionImpl {
+    validateSegment(segment);
+    const path = [...this.path, segment];
+    return makeCollection(path, schema, brandId(path));
+  },
+  collection(this: CollectionImpl, ...ancestors: ReadonlyArray<string>): CollectionReferenceImpl {
+    return makeCollectionReference(this, ancestors);
+  },
+  doc(this: CollectionImpl, ...ids: ReadonlyArray<string>): DocumentReferenceImpl {
+    const parent = makeCollectionReference(this, ids.slice(0, -1));
+    return makeDocumentReference(parent, ids[ids.length - 1]);
+  },
+};
+
+/**
+ * The target is asserted as the prototype rather than as the finished shape, so
+ * that the result type is inferred from the fields below. The return annotation
+ * then catches a field that is missing, misspelled or of the wrong type -
+ * asserting the finished shape up front would check none of the three.
+ */
+const makeCollection = (
+  path: ReadonlyArray<string>,
+  schema: FirestoreModel.Any,
+  id: Schema.Top,
+): CollectionImpl => {
+  const self: CollectionImpl = Object.assign(
+    Object.create(CollectionProto) as typeof CollectionProto,
+    {
+      path,
+      segment: path[path.length - 1],
+      schema,
+      id,
+      // An own closure rather than a method on the prototype, so that it can be
+      // passed on unbound, as in `docs.filter(Posts.contains)`. The definition
+      // is compared by reference, as references compare theirs in `Equal`.
+      contains: (value: unknown): boolean =>
+        isDocumentReference(value)
+          ? value.collection === self
+          : documentSnapshot.isDocumentSnapshot(value) && value.ref.collection === self,
+    },
+  );
+  return self;
+};
+
+const CollectionReferenceProto = {
+  ...Inspectable.BaseProto,
+  [CollectionReferenceTypeId]: CollectionReferenceTypeId,
+  toJSON(this: CollectionReferenceImpl) {
+    return { _id: "CollectionReference", path: this.path };
+  },
+  // The definition is compared by reference: it is written once and named, and
+  // `Equal.equals` would otherwise walk the whole schema behind it.
+  [Equal.symbol](this: CollectionReferenceImpl, that: unknown): boolean {
+    return (
+      isCollectionReference(that) && this.path === that.path && this.collection === that.collection
+    );
+  },
+  [Hash.symbol](this: CollectionReferenceImpl): number {
+    return Hash.combine(Hash.string(this.path), Hash.random(this.collection));
+  },
+  doc(this: CollectionReferenceImpl, id: string): DocumentReferenceImpl {
+    return makeDocumentReference(this, id);
+  },
+};
+
+const makeCollectionReference = (
+  collection: CollectionImpl,
+  ancestors: ReadonlyArray<string>,
+): CollectionReferenceImpl =>
+  Object.assign(Object.create(CollectionReferenceProto) as typeof CollectionReferenceProto, {
+    collection,
+    ancestors,
+    id: collection.segment,
+    path: joinPath(collection.path, ancestors),
+  });
+
+const DocumentReferenceProto = {
+  ...Inspectable.BaseProto,
+  [DocumentReferenceTypeId]: DocumentReferenceTypeId,
+  toJSON(this: DocumentReferenceImpl) {
+    return { _id: "DocumentReference", path: this.path };
+  },
+  // The definition is compared by reference: it is written once and named, and
+  // `Equal.equals` would otherwise walk the whole schema behind it.
+  [Equal.symbol](this: DocumentReferenceImpl, that: unknown): boolean {
+    return (
+      isDocumentReference(that) && this.path === that.path && this.collection === that.collection
+    );
+  },
+  [Hash.symbol](this: DocumentReferenceImpl): number {
+    return Hash.combine(Hash.string(this.path), Hash.random(this.collection));
+  },
+};
+
+/** A document is always built from the collection holding it, which it keeps. */
+const makeDocumentReference = (
+  parent: CollectionReferenceImpl,
+  id: string,
+): DocumentReferenceImpl =>
+  Object.assign(Object.create(DocumentReferenceProto) as typeof DocumentReferenceProto, {
+    collection: parent.collection,
+    ancestors: parent.ancestors,
+    id,
+    path: `${parent.path}/${id}`,
+    parent,
+  });
+
+/** @internal */
+export const make = <const Segment extends string, S extends FirestoreModel.Any>(
+  segment: Segment,
+  schema: S,
+): Collection.Collection<readonly [readonly [Segment, S]]> => {
+  validateSegment(segment);
+  const path = [segment];
+  return makeCollection(path, schema, brandId(path)) as unknown as Collection.Collection<
+    readonly [readonly [Segment, S]]
+  >;
+};
+
+/** @internal */
+export const fromPath = <C extends Collection.Any>(
+  collection: C,
+  path: string,
+): Option.Option<Collection.DocumentReference<C>> => {
+  const self = collection as unknown as CollectionImpl;
+  const parts = path.split("/");
+  if (parts.length !== self.path.length * 2) return Option.none();
+  const ids: Array<string> = [];
+  for (let i = 0; i < self.path.length; i++) {
+    const id = parts[2 * i + 1];
+    if (parts[2 * i] !== self.path[i] || id.length === 0) return Option.none();
+    ids.push(id);
+  }
+  return Option.some(self.doc(...ids) as unknown as Collection.DocumentReference<C>);
+};
+
+/**
+ * The path a document in `collection` is found at, with `{id}` standing in for
+ * each id: `users/{id}/posts/{id}`.
+ *
+ * @internal
+ */
+export const pattern = (collection: Collection.Any): string =>
+  (collection as unknown as CollectionImpl).path.map((segment) => `${segment}/{id}`).join("/");

package/src/firestore/internal/collectionGroup.ts

@@ -0,0 +1,81 @@
+import { Inspectable, Option, Predicate, Result } from "effect";
+import type * as Collection from "../Collection.ts";
+import type * as CollectionGroup from "../CollectionGroup.ts";
+import { UndefinedCollectionError } from "./firestoreError.ts";
+import * as collection from "./collection.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase/firestore/CollectionGroup";
+
+/** @internal */
+export const isCollectionGroup = (u: unknown): u is CollectionGroup.Any =>
+  Predicate.hasProperty(u, TypeId);
+
+/**
+ * Where `member`'s collections sit, with `{id}` standing in for each ancestor
+ * id: `users/{id}/posts`.
+ */
+const memberPattern = (member: Collection.Any): string =>
+  collection.pattern(member).slice(0, -"/{id}".length);
+
+const CollectionGroupProto = {
+  ...Inspectable.BaseProto,
+  [TypeId]: TypeId,
+  toJSON(this: CollectionGroup.Any) {
+    return { _id: "CollectionGroup", members: this.members.map(memberPattern) };
+  },
+};
+
+/**
+ * Rejects the groups that would not mean one thing: one with nothing in it,
+ * one whose collections Firestore could not read under one collection id, and
+ * one with two collections at the same path, which no document could be told
+ * apart between.
+ */
+const validate = (members: ReadonlyArray<Collection.Any>): void => {
+  const reject = (reason: string): never => {
+    throw new Error(`Invalid collection group: ${reason}`);
+  };
+  if (members.length === 0) reject("it must hold at least one collection");
+  const [first] = members;
+  const seen = new Set<string>();
+  for (const member of members) {
+    if (member.segment !== first.segment) {
+      reject(
+        `"${memberPattern(first)}" and "${memberPattern(member)}" do not share their collection id`,
+      );
+    }
+    const pattern = memberPattern(member);
+    if (seen.has(pattern)) reject(`it has more than one member at "${pattern}"`);
+    seen.add(pattern);
+  }
+};
+
+/** @internal */
+export const make = <const Members extends readonly [Collection.Any, ...Array<Collection.Any>]>(
+  ...valid: CollectionGroup.Valid<Members>
+): CollectionGroup.CollectionGroup<Members[number]> => {
+  // The type checker has refused anything that is not one of `Members`, but
+  // a caller that got past it is checked again here.
+  const members = valid as ReadonlyArray<unknown> as Members;
+  validate(members);
+  return Object.assign(Object.create(CollectionGroupProto) as typeof CollectionGroupProto, {
+    members,
+    id: members[0].segment as string,
+  }) as CollectionGroup.CollectionGroup<Members[number]>;
+};
+
+/** @internal */
+export const documentAt = <G extends CollectionGroup.Any>(
+  group: G,
+  path: string,
+): Result.Result<CollectionGroup.DocumentReference<G>, UndefinedCollectionError> => {
+  // The members are read as `Collection.Any`, so the reference found in one is
+  // typed back by the member it was found in.
+  for (const member of group.members) {
+    const ref = collection.fromPath(member, path);
+    if (Option.isSome(ref))
+      return Result.succeed(ref.value as CollectionGroup.DocumentReference<G>);
+  }
+  return Result.fail(new UndefinedCollectionError({ path, collectionId: group.id }));
+};