@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/src/firestore/CollectionGroup.ts

@@ -0,0 +1,245 @@
+/**
+ * Collection Groups: every collection with one collection id, wherever it
+ * sits, read together.
+ *
+ * A group is built from the {@link Collection.Collection} definitions it
+ * covers, not from a bare collection id. Each document a read of the group
+ * finds is matched to the collection it lives in, and comes back typed,
+ * addressed and decoded as that collection's.
+ *
+ * @example Reading every post of every user
+ * ```ts
+ * import {
+ *   Collection,
+ *   CollectionGroup,
+ *   Firestore,
+ *   FirestoreModel,
+ * } from "@visiolab/effect-firebase/firestore";
+ * import { Effect, Schema } from "effect";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({ name: Schema.String }) {}
+ * class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+ *
+ * const Users = Collection.make("users", User);
+ * const UserPosts = Users.subcollection("posts", Post);
+ * const AllPosts = CollectionGroup.make(UserPosts);
+ *
+ * const program = Effect.gen(function* () {
+ *   const firestore = yield* Firestore.Firestore;
+ *   const snapshot = yield* firestore.getDocs(AllPosts);
+ *   return snapshot.docs.map((post) => post.ref.path);
+ * });
+ * ```
+ *
+ * @see {@link Collection} for defining the collections a group is made of
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Inspectable, Result } from "effect";
+import type * as Collection from "./Collection.ts";
+import type { UndefinedCollectionError } from "./Firestore.ts";
+import * as collectionGroup from "./internal/collectionGroup.ts";
+
+const TypeId = collectionGroup.TypeId;
+
+/**
+ * The definition of a Collection Group: the collections in `Members`, which
+ * all share one collection id.
+ *
+ * **Details**
+ *
+ * Like a {@link Collection.Collection}, a group does not point at any data. It
+ * has no ids to fill in, so {@link Firestore.With.getDocs} and
+ * {@link Firestore.With.streamDocs} take it as it is. Build one with
+ * {@link make}.
+ *
+ * @see {@link Collection.CollectionReference} for reading one collection, under one parent
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface CollectionGroup<Members extends Collection.Any> extends Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /** The collections it was defined from, in the order they were given. */
+  readonly members: ReadonlyArray<Members>;
+  /** The collection id its members share, which Firestore reads the group by. */
+  readonly id: string;
+}
+
+/**
+ * Any Collection Group, whatever collections it is made of. Use it as a type
+ * bound.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Any = CollectionGroup<any>;
+
+/**
+ * The collections `G` was defined from, as a union.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Members<G extends Any> = G extends CollectionGroup<infer M> ? M : never;
+
+/**
+ * A reference to a document in one of the collections of `G`, typed by the one
+ * it lives in: `DocumentReference<A> | DocumentReference<B>` rather than a
+ * reference to `A | B`.
+ *
+ * @see {@link Collection.DocumentReference} for a reference into one known collection
+ * @see {@link Collection.Collection.contains} for narrowing it to one member
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type DocumentReference<G extends Any> =
+  Members<G> extends infer C extends Collection.Any
+    ? C extends Collection.Any
+      ? Collection.DocumentReference<C>
+      : never
+    : never;
+
+/** Whether `A` and `B` are the same type, rather than one fitting the other. */
+type Same<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+
+/**
+ * Whether `A` and `B` are the same path. A path with a segment only known as
+ * `string` could be any path, so it is never taken for another here.
+ */
+type SamePath<A extends ReadonlyArray<string>, B extends ReadonlyArray<string>> = string extends
+  | A[number]
+  | B[number]
+  ? false
+  : Same<A, B>;
+
+/** Whether a member of `Members` other than the one at `K` sits at `C`'s path. */
+type PathTakenElsewhere<
+  Members extends ReadonlyArray<Collection.Any>,
+  K,
+  C extends Collection.Any,
+> = true extends {
+  [J in keyof Members]: J extends K ? false : SamePath<Members[J]["path"], C["path"]>;
+}[number]
+  ? true
+  : false;
+
+/**
+ * The collections {@link make} accepts as `Members`: each one as it is, or, in
+ * place of one that breaks a rule, a message naming the rule. Every member must
+ * share the first one's collection id, and no two may sit at the same path.
+ *
+ * **Details**
+ *
+ * Members are told apart by their paths, so the same collection listed twice
+ * and two definitions built separately at the same path are both refused: a
+ * document at that path could belong to either. A path with a segment typed
+ * only as `string` is not checked here; {@link make} checks it at runtime.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Valid<Members extends ReadonlyArray<Collection.Any>> = {
+  readonly [K in keyof Members]: Members[K] extends Collection.Any
+    ? Members[K]["segment"] extends Members[0]["segment"]
+      ? PathTakenElsewhere<Members, K, Members[K]> extends true
+        ? `Collection Group member '${Members[K]["segment"]}' has the same path as another member`
+        : Members[K]
+      : `Collection Group member '${Members[K]["segment"]}' does not share the collection id '${Members[0]["segment"]}'`
+    : never;
+};
+
+/**
+ * Checks whether a value is a {@link CollectionGroup}.
+ *
+ * @see {@link Collection.isCollection} for a collection definition
+ * @see {@link Collection.isCollectionReference} for a reference to one collection
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isCollectionGroup: (u: unknown) => u is Any = collectionGroup.isCollectionGroup;
+
+/**
+ * Defines a Collection Group from the collections it covers.
+ *
+ * **When to use**
+ *
+ * Use to read or listen to documents across every parent at once, such as
+ * every user's posts. To read the collection under one parent, pass a
+ * {@link Collection.CollectionReference} to {@link Firestore.With.getDocs}
+ * instead.
+ *
+ * **Details**
+ *
+ * List every collection with the collection id you want to read. A read of
+ * the group fails with an `UndefinedCollectionError` when it finds a document
+ * under that collection id at a path none of the members define.
+ *
+ * The type checker refuses members that do not share the first one's
+ * collection id, and two members at the same path. The same checks run at
+ * runtime: it throws when given no collection, members with different
+ * collection ids, or two members at the same path, whether the same one twice
+ * or two built separately. An invalid definition is a programming error, as
+ * for {@link Collection.make}.
+ *
+ * @example Grouping collections under different parents
+ * ```ts
+ * import {
+ *   Collection,
+ *   CollectionGroup,
+ *   Firestore,
+ *   FirestoreModel,
+ * } from "@visiolab/effect-firebase/firestore";
+ * import { Effect, Schema } from "effect";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({ name: Schema.String }) {}
+ * class Org extends FirestoreModel.Class<Org>("Org")({ name: Schema.String }) {}
+ * class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+ *
+ * const UserPosts = Collection.make("users", User).subcollection("posts", Post);
+ * const OrgPosts = Collection.make("orgs", Org).subcollection("posts", Post);
+ * const AllPosts = CollectionGroup.make(UserPosts, OrgPosts);
+ *
+ * const program = Effect.gen(function* () {
+ *   const firestore = yield* Firestore.Firestore;
+ *   const snapshot = yield* firestore.getDocs(AllPosts);
+ *   // Only the posts under a user.
+ *   return snapshot.docs.filter(UserPosts.contains);
+ * });
+ * ```
+ *
+ * @see {@link Collection.make} for defining the member collections
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: <const Members extends readonly [Collection.Any, ...Array<Collection.Any>]>(
+  ...members: Valid<Members>
+) => CollectionGroup<Members[number]> = collectionGroup.make;
+
+// How the SDK packages match each document a group read finds to its
+// collection. Not API: they reach it here because a package can only import
+// another's public modules.
+
+/**
+ * References the document at `path` in whichever collection of `group` sits
+ * there, or fails with the {@link UndefinedCollectionError} a group read
+ * reports for a document none of them define.
+ *
+ * @internal
+ */
+export const documentAt: <G extends Any>(
+  group: G,
+  path: string,
+) => Result.Result<DocumentReference<G>, UndefinedCollectionError> = collectionGroup.documentAt;

package/src/firestore/DocumentPath.ts

@@ -0,0 +1,114 @@
+/**
+ * Untyped references to Firestore documents, independent of either SDK.
+ *
+ * Firestore stores a reference to a document as the document's path alone,
+ * and each SDK reads it back as its own `DocumentReference` class. This module
+ * owns a portable version of that value: the Firestore Value a reference is
+ * written and read as.
+ *
+ * A `DocumentPath` does not know which collection it points into, or what the
+ * document holds. A {@link Collection.DocumentReference} does.
+ *
+ * @see {@link FirestoreSchema.DocumentPath} for storing an untyped reference in a document
+ * @see {@link FirestoreSchema.DocumentReference} for storing a typed reference in a document
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Equal, Inspectable, Option } from "effect";
+import * as documentPath from "./internal/documentPath.ts";
+
+const TypeId = documentPath.TypeId;
+
+/**
+ * A reference to a document as Firestore stores it: the document's path, such
+ * as `users/alice/posts/hello`.
+ *
+ * **When to use**
+ *
+ * Use for a reference whose target collection the model does not know, or
+ * does not care about. Prefer {@link Collection.DocumentReference}, through
+ * {@link FirestoreSchema.DocumentReference}, when the field always points into
+ * a known collection: it keeps the target's ids and model typed.
+ *
+ * **Details**
+ *
+ * Two are equal when their paths are.
+ *
+ * @see {@link Collection.DocumentReference} for a reference that knows its collection and model
+ * @see {@link FirestoreSchema.DocumentPath} for the schema of this value
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface DocumentPath extends Equal.Equal, Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /** The path of the document, from the root of the database. */
+  readonly path: string;
+}
+
+/**
+ * Checks whether `u` is a {@link DocumentPath} built by this module.
+ *
+ * An SDK's own `DocumentReference` is not one.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isDocumentPath: (u: unknown) => u is DocumentPath = documentPath.isDocumentPath;
+
+/**
+ * Builds a reference to the document at `path`, or `None` when `path` does not
+ * address a document.
+ *
+ * **When to use**
+ *
+ * Use when the path comes from outside the program and may be invalid.
+ *
+ * **Details**
+ *
+ * Returns `None` when `path` is empty, has an empty segment, or has an odd
+ * number of segments and so ends in a collection.
+ *
+ * @example Building a reference from untrusted input
+ * ```ts
+ * import { DocumentPath } from "@visiolab/effect-firebase/firestore";
+ *
+ * DocumentPath.make("users/alice"); // Option.some(...)
+ * DocumentPath.make("users"); // Option.none()
+ * ```
+ *
+ * @see {@link makeUnsafe} for the same check throwing instead
+ * @see {@link Collection.Collection} for typed references built from ids
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: (path: string) => Option.Option<DocumentPath> = documentPath.make;
+
+/**
+ * Builds a reference to the document at `path`, throwing when `path` does not
+ * address a document.
+ *
+ * **When to use**
+ *
+ * Use for paths known to be valid, such as constants. Use {@link make} for
+ * paths you have not checked.
+ *
+ * @example Building a reference
+ * ```ts
+ * import { DocumentPath } from "@visiolab/effect-firebase/firestore";
+ *
+ * const post = DocumentPath.makeUnsafe("users/alice/posts/hello");
+ * ```
+ *
+ * @see {@link make} for the same check returning an `Option`
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const makeUnsafe: (path: string) => DocumentPath = documentPath.makeUnsafe;

package/src/firestore/DocumentSnapshot.ts

@@ -0,0 +1,308 @@
+/**
+ * What a read of one document returns.
+ *
+ * A document's id is in its path, not in its data, so the data alone cannot
+ * say which document it is. A snapshot pairs the two: the reference the
+ * document was read at, and what it held, or that it was not there.
+ *
+ * The data is kept as the SDK read it, and only decoded through the
+ * collection's model when you ask for it. Checking whether the document is
+ * there, or which one it is, never decodes, and a document that does not match
+ * the model only fails the code that reads its data.
+ *
+ * @example Reading a document that may be missing
+ * ```ts
+ * import {
+ *   Collection,
+ *   DocumentSnapshot,
+ *   Firestore,
+ *   FirestoreModel,
+ * } from "@visiolab/effect-firebase/firestore";
+ * import { Effect, Option, Schema } from "effect";
+ *
+ * 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 snapshot = yield* firestore.getDoc(Users.doc(Users.id.make("alice")));
+ *   if (DocumentSnapshot.isMissing(snapshot)) return Option.none();
+ *   const user = yield* snapshot.data;
+ *   return Option.some(user.name);
+ * });
+ * ```
+ *
+ * @see {@link QuerySnapshot} for what a read of many documents returns
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Effect, Inspectable, Schema } from "effect";
+import type * as Collection from "./Collection.ts";
+import * as documentSnapshot from "./internal/documentSnapshot.ts";
+
+const TypeId = documentSnapshot.TypeId;
+
+/**
+ * What a document in `C` decodes into: the `read` variant of its model.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Data<C extends Collection.Any> = Collection.DocumentSchema<C>["Type"];
+
+/**
+ * The services decoding a document in `C` requires, which
+ * {@link Existing.data} asks for.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type DecodingServices<C extends Collection.Any> =
+  Collection.DocumentSchema<C>["DecodingServices"];
+
+/**
+ * A snapshot of a document that was there when it was read.
+ *
+ * **Details**
+ *
+ * Its tag is `"Existing"`. {@link Existing.data} decodes what it held through
+ * the collection's model. Every document of a {@link QuerySnapshot.QuerySnapshot}
+ * is one of these.
+ *
+ * @see {@link Missing} for a document that was not there
+ * @see {@link isExisting} for narrowing a {@link DocumentSnapshot} to this
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Existing<C extends Collection.Any> extends Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  readonly _tag: "Existing";
+  /** The reference the document was read at. */
+  readonly ref: Collection.DocumentReference<C>;
+  /** The document's own id, the same as `ref.id`. */
+  readonly id: Collection.Id<C>;
+  /**
+   * The document's data as the SDK read it, before the collection's model has
+   * decoded it.
+   *
+   * **Details**
+   *
+   * It is what the document held at the time of the read. Do not change it: a
+   * snapshot is a record of that read, not a handle on the document.
+   *
+   * @see {@link Existing.data} for the decoded data
+   */
+  readonly raw: unknown;
+  /**
+   * Decodes {@link Existing.raw} through the collection's model.
+   *
+   * **Details**
+   *
+   * Nothing is decoded until this runs, and it decodes again on each run.
+   * Fails with a `Schema.SchemaError` when the data does not match the model.
+   */
+  readonly data: Effect.Effect<Data<C>, Schema.SchemaError, DecodingServices<C>>;
+}
+
+/**
+ * A snapshot of a document that was not there when it was read.
+ *
+ * **Details**
+ *
+ * Its tag is `"Missing"`. It holds no data, so a missing document is never
+ * confused with one that failed to decode.
+ *
+ * @see {@link Existing} for a document that was there
+ * @see {@link isMissing} for narrowing a {@link DocumentSnapshot} to this
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Missing<C extends Collection.Any> extends Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  readonly _tag: "Missing";
+  /** The reference the document was read at. */
+  readonly ref: Collection.DocumentReference<C>;
+  /** The document's own id, the same as `ref.id`. */
+  readonly id: Collection.Id<C>;
+}
+
+/**
+ * A document in `C` as a read found it: {@link Existing} or {@link Missing}.
+ *
+ * **Details**
+ *
+ * {@link Firestore.With.getDoc} and {@link Firestore.With.streamDoc} return
+ * one. A missing document is a result, not a failure. Tell the two apart with
+ * {@link isExisting} or {@link isMissing}, or by `_tag`.
+ *
+ * @see {@link QuerySnapshot.QuerySnapshot} for the result of a read of many documents
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type DocumentSnapshot<C extends Collection.Any> = Existing<C> | Missing<C>;
+
+/**
+ * Checks whether a value is a {@link DocumentSnapshot}, existing or missing.
+ *
+ * @see {@link isExisting} and {@link isMissing} for telling the two kinds apart
+ * @see {@link QuerySnapshot.isQuerySnapshot} for a snapshot of many documents
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isDocumentSnapshot: (u: unknown) => u is DocumentSnapshot<Collection.Any> =
+  documentSnapshot.isDocumentSnapshot;
+
+/**
+ * Narrows a {@link DocumentSnapshot} to an {@link Existing} one.
+ *
+ * **When to use**
+ *
+ * Use after {@link Firestore.With.getDoc} to get at the data of a document
+ * that was there.
+ *
+ * @see {@link isMissing} for the opposite check
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isExisting: <C extends Collection.Any>(
+  self: DocumentSnapshot<C>,
+) => self is Existing<C> = documentSnapshot.isExisting;
+
+/**
+ * Narrows a {@link DocumentSnapshot} to a {@link Missing} one.
+ *
+ * **When to use**
+ *
+ * Use after {@link Firestore.With.getDoc} to handle a document that was not
+ * there, such as returning early.
+ *
+ * @see {@link isExisting} for the opposite check
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isMissing: <C extends Collection.Any>(
+  self: DocumentSnapshot<C>,
+) => self is Missing<C> = documentSnapshot.isMissing;
+
+/**
+ * Builds a snapshot of the document at `ref` from what an SDK's
+ * `snapshot.data()` returned: {@link Missing} for `undefined`, and
+ * {@link Existing} otherwise.
+ *
+ * **When to use**
+ *
+ * Use when implementing a backend or a test double, to turn an SDK snapshot
+ * into a portable one. Application code gets snapshots from
+ * {@link Firestore.With.getDoc} instead.
+ *
+ * **Details**
+ *
+ * Both SDKs return `undefined` from `data()` for a document that is not there.
+ * An SDK that knows more about the read, such as the client's `metadata`,
+ * passes it as `extra`: each of its fields is put on the snapshot and shown
+ * when it prints. Its fields must not have the same names as the snapshot's
+ * own.
+ *
+ * @example Building a snapshot with extra fields
+ * ```ts
+ * import {
+ *   Collection,
+ *   DocumentSnapshot,
+ *   FirestoreModel,
+ * } from "@visiolab/effect-firebase/firestore";
+ * import { Schema } from "effect";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({ name: Schema.String }) {}
+ *
+ * const Users = Collection.make("users", User);
+ * const ref = Users.doc(Users.id.make("alice"));
+ *
+ * const snapshot = DocumentSnapshot.make(ref, { name: "Alice" }, {
+ *   metadata: { fromCache: false, hasPendingWrites: false },
+ * });
+ *
+ * snapshot.metadata.fromCache; // false
+ * ```
+ *
+ * @see {@link existing} for a document known to be there
+ * @see {@link missing} for a document known not to be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: {
+  <C extends Collection.Any>(
+    ref: Collection.DocumentReference<C>,
+    data: unknown,
+  ): DocumentSnapshot<C>;
+  <C extends Collection.Any, E extends object>(
+    ref: Collection.DocumentReference<C>,
+    data: unknown,
+    extra: E,
+  ): DocumentSnapshot<C> & E;
+} = documentSnapshot.make;
+
+/**
+ * Builds an {@link Existing} snapshot of the document at `ref`, with the
+ * fields of `extra` when given, as {@link make} adds them.
+ *
+ * **When to use**
+ *
+ * Use in a backend for a document known to be there, such as each document a
+ * query returned.
+ *
+ * @see {@link make} for a document that may or may not be there
+ * @see {@link missing} for a document known not to be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const existing: {
+  <C extends Collection.Any>(ref: Collection.DocumentReference<C>, data: unknown): Existing<C>;
+  <C extends Collection.Any, E extends object>(
+    ref: Collection.DocumentReference<C>,
+    data: unknown,
+    extra: E,
+  ): Existing<C> & E;
+} = documentSnapshot.existing;
+
+/**
+ * Builds a {@link Missing} snapshot of the document at `ref`, with the fields
+ * of `extra` when given, as {@link make} adds them.
+ *
+ * **When to use**
+ *
+ * Use in a backend or a test double for a document known not to be there.
+ *
+ * @see {@link make} for a document that may or may not be there
+ * @see {@link existing} for a document known to be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const missing: {
+  <C extends Collection.Any>(ref: Collection.DocumentReference<C>): Missing<C>;
+  <C extends Collection.Any, E extends object>(
+    ref: Collection.DocumentReference<C>,
+    extra: E,
+  ): Missing<C> & E;
+} = documentSnapshot.missing;