@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/src/firestore/FirestoreValue.ts

@@ -0,0 +1,207 @@
+/**
+ * Firestore Values: values as Firestore stores them, independent of either
+ * SDK.
+ *
+ * {@link toCodecFirestore} derives a codec from any Effect schema to Firestore
+ * Values, the way `Schema.toCodecJson` derives one to JSON. That keeps a model
+ * a plain Effect schema that needs no service to encode. Each SDK package then
+ * maps Firestore Values to and from its own SDK's values.
+ *
+ * You rarely call this module yourself: {@link Firestore} encodes and decodes
+ * documents through it.
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Result, Schema, SchemaAST } from "effect";
+import type * as DocumentPath from "./DocumentPath.ts";
+import type * as FieldValue from "./FieldValue.ts";
+import type { FirestoreError } from "./Firestore.ts";
+import type * as GeoPoint from "./GeoPoint.ts";
+import * as firestoreValue from "./internal/firestoreValue.ts";
+import * as firestoreValueWalk from "./internal/firestoreValueWalk.ts";
+import type * as Timestamp from "./Timestamp.ts";
+
+declare module "effect/Schema" {
+  namespace Annotations {
+    // The augmentation has to repeat Effect's type parameters, `T` included.
+    // oxlint-disable-next-line no-unused-vars
+    interface Declaration<T, TypeParameters extends ReadonlyArray<Constraint> = readonly []> {
+      /**
+       * Returns the link used to derive the declaration's Firestore
+       * representation, or `undefined` when it already holds a Firestore Value.
+       *
+       * {@link toCodecFirestore} prefers it to `toCodecJson` and `toCodec`.
+       */
+      readonly toCodecFirestore?:
+        | ((typeParameters: TypeParameters.Encoded<TypeParameters>) => SchemaAST.Link | undefined)
+        | undefined;
+    }
+  }
+}
+
+/**
+ * A value as Firestore stores it, independent of either SDK.
+ *
+ * **Details**
+ *
+ * One of: `null`, a boolean, a number, a string, a {@link Timestamp.Timestamp},
+ * a {@link GeoPoint.GeoPoint}, a {@link DocumentPath.DocumentPath}, bytes as a
+ * `Uint8Array`, a {@link FieldValue} sentinel, or an array or plain-object map
+ * of Firestore Values.
+ *
+ * A typed {@link Collection.DocumentReference} is not one: Firestore stores
+ * only its path, as a {@link DocumentPath.DocumentPath}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type FirestoreValue =
+  | null
+  | boolean
+  | number
+  | string
+  | Timestamp.Timestamp
+  | GeoPoint.GeoPoint
+  | DocumentPath.DocumentPath
+  | Uint8Array
+  | FieldValue.ServerTimestamp
+  | FieldValue.Increment
+  | FieldValue.DeleteField
+  | FieldValue.ArrayUnion<FirestoreValue>
+  | FieldValue.ArrayRemove<FirestoreValue>
+  | ReadonlyArray<FirestoreValue>
+  | { readonly [key: string]: FirestoreValue };
+
+/**
+ * Checks whether `u` is a {@link FirestoreValue}, all the way down.
+ *
+ * **Details**
+ *
+ * Maps must be plain objects. An instance of any other class is not a
+ * Firestore Value, since Firestore would store it as a map and read it back as
+ * a plain object.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isFirestoreValue: (u: unknown) => u is FirestoreValue =
+  firestoreValue.isFirestoreValue;
+
+// The walk the SDK packages map Firestore Values with. Not API: they reach it
+// here because a package can only import another's public modules.
+
+/** @internal */
+export type FieldPath = firestoreValueWalk.FieldPath;
+
+/** @internal */
+export type Kinds = firestoreValueWalk.Kinds;
+
+/** @internal */
+export type Writer = firestoreValueWalk.Writer;
+
+/** @internal */
+export type Reader = firestoreValueWalk.Reader;
+
+/** @internal */
+export const formatFieldPath: (path: FieldPath) => string = firestoreValueWalk.formatFieldPath;
+
+/** @internal */
+export const toSdk: (value: FirestoreValue, writer: Writer) => unknown = firestoreValueWalk.toSdk;
+
+/** @internal */
+export const fromSdk: (
+  value: unknown,
+  reader: Reader,
+) => Result.Result<FirestoreValue, FirestoreError> = firestoreValueWalk.fromSdk;
+
+/** @internal */
+export const readDocument: (
+  path: string,
+  data: unknown,
+  reader: Reader,
+) => Result.Result<FirestoreValue | undefined, FirestoreError> = firestoreValueWalk.readDocument;
+
+/**
+ * Type-level representation of the codec {@link toCodecFirestore} returns: the
+ * schema's `Type`, encoded as a {@link FirestoreValue}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface toCodecFirestore<S extends Schema.Constraint> extends Schema.BottomLazy<
+  S["ast"],
+  toCodecFirestore<S>,
+  S["~type.parameters"],
+  S["~type.mutability"],
+  S["~type.optionality"],
+  S["~type.constructor.default"],
+  S["~encoded.mutability"],
+  S["~encoded.optionality"]
+> {
+  readonly Type: S["Type"];
+  readonly Encoded: FirestoreValue;
+  readonly DecodingServices: S["DecodingServices"];
+  readonly EncodingServices: S["EncodingServices"];
+  readonly "~type.make.in": S["~type.make.in"];
+  readonly "~type.make": S["~type.make"];
+  readonly Iso: S["Iso"];
+  readonly schema: S;
+}
+
+/**
+ * Derives a codec from a schema to Firestore Values.
+ *
+ * **When to use**
+ *
+ * Use to encode or decode a value the way {@link Firestore} stores it outside
+ * a read or write, such as in a test or a custom backend. Reads and writes
+ * through {@link Firestore} already use it.
+ *
+ * **Details**
+ *
+ * It works like `Schema.toCodecJson`: the schema's own transformations run
+ * first, then structs, tuples, arrays, unions and `Schema.suspend` are walked.
+ * A declaration is resolved in this order:
+ *
+ * 1. `Schema.Date` and `Schema.DateTimeUtc` become a portable `Timestamp`, and
+ *    `Schema.Uint8Array` is stored as bytes. Reading a `Date` or `DateTime.Utc`
+ *    back keeps milliseconds only.
+ * 2. A `toCodecFirestore` annotation.
+ * 3. A `toCodecJson` annotation, since every JSON value is a Firestore Value.
+ * 4. A `toCodec` annotation.
+ * 5. Otherwise the value must already be a Firestore Value, and encoding
+ *    anything else fails with a schema issue at its path.
+ *
+ * Keywords follow `Schema.toCodecJson`: a `bigint` or `symbol` is written as a
+ * string, and `undefined` as `null`. Unlike there, `Schema.Any` is no escape
+ * hatch: like `Schema.Unknown` it takes Firestore Values only, since the SDK
+ * mappings take nothing else. Derivation never fails and is memoized per
+ * schema.
+ *
+ * @example Encoding a value to Firestore Values
+ * ```ts
+ * import { DateTime, Effect, Schema } from "effect";
+ * import { FirestoreValue } from "@visiolab/effect-firebase/firestore";
+ *
+ * const Event = Schema.Struct({ name: Schema.String, at: Schema.DateTimeUtc });
+ * const codec = FirestoreValue.toCodecFirestore(Event);
+ *
+ * // `at` is encoded as a portable `Timestamp`.
+ * const encoded = Schema.encodeEffect(codec)({
+ *   name: "launch",
+ *   at: DateTime.makeUnsafe("2024-01-01T00:00:00Z"),
+ * });
+ * ```
+ *
+ * @see {@link FirestoreSchema} for schemas of the values Effect has none for
+ *
+ * @stability unstable
+ * @category converting
+ * @since 0.2.0
+ */
+export const toCodecFirestore: <S extends Schema.Constraint>(schema: S) => toCodecFirestore<S> =
+  firestoreValue.toCodecFirestore;

package/src/firestore/GeoPoint.ts

@@ -0,0 +1,105 @@
+/**
+ * Firestore geopoints, independent of either SDK.
+ *
+ * Firestore stores a place on the globe as a latitude and a longitude, and
+ * each SDK reads it back as its own `GeoPoint` 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.
+ *
+ * @see {@link FirestoreSchema.GeoPoint} for storing a `GeoPoint` in a document
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Equal, Inspectable, Option } from "effect";
+import * as geoPoint from "./internal/geoPoint.ts";
+
+const TypeId = geoPoint.TypeId;
+
+/**
+ * A place on the globe, stored the way Firestore stores it.
+ *
+ * Two geopoints are equal when their latitudes and longitudes are.
+ *
+ * @see {@link FirestoreSchema.GeoPoint} for the schema of this value
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface GeoPoint extends Equal.Equal, Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /** Degrees north of the equator, between -90 and 90. */
+  readonly latitude: number;
+  /** Degrees east of the prime meridian, between -180 and 180. */
+  readonly longitude: number;
+}
+
+/**
+ * Checks whether `u` is a {@link GeoPoint} built by this module.
+ *
+ * An SDK's own `GeoPoint` is not one.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isGeoPoint: (u: unknown) => u is GeoPoint = geoPoint.isGeoPoint;
+
+/**
+ * Builds a geopoint from a latitude and a longitude, throwing when either is
+ * out of range.
+ *
+ * **When to use**
+ *
+ * Use for coordinates known to be valid, such as constants. Use {@link make}
+ * for coordinates you have not checked.
+ *
+ * **Details**
+ *
+ * Throws unless `latitude` is a number from -90 to 90 and `longitude` a number
+ * from -180 to 180.
+ *
+ * @example Building a geopoint
+ * ```ts
+ * import { GeoPoint } from "@visiolab/effect-firebase/firestore";
+ *
+ * const berlin = GeoPoint.makeUnsafe(52.52, 13.405);
+ * ```
+ *
+ * @see {@link make} for the same check returning an `Option`
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const makeUnsafe: (latitude: number, longitude: number) => GeoPoint = geoPoint.makeUnsafe;
+
+/**
+ * Builds a geopoint from a latitude and a longitude, or `None` when either is
+ * out of range.
+ *
+ * **When to use**
+ *
+ * Use when the coordinates come from outside the program and may be invalid.
+ *
+ * **Details**
+ *
+ * Returns `None` unless `latitude` is a number from -90 to 90 and `longitude`
+ * a number from -180 to 180.
+ *
+ * @example Building a geopoint from untrusted input
+ * ```ts
+ * import { GeoPoint } from "@visiolab/effect-firebase/firestore";
+ *
+ * GeoPoint.make(52.52, 13.405); // Option.some(...)
+ * GeoPoint.make(91, 0); // Option.none()
+ * ```
+ *
+ * @see {@link makeUnsafe} for the same check throwing instead
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: (latitude: number, longitude: number) => Option.Option<GeoPoint> = geoPoint.make;

package/src/firestore/Patch.ts

@@ -0,0 +1,117 @@
+/**
+ * Patches: what an update writes, and how.
+ *
+ * A patch has the shape of the document it changes. Each part of it says how
+ * that part is written:
+ *
+ * - A plain object handed to a {@link FirestoreModel.Struct} field is a nested
+ *   patch, written field by field: `{ address: { city } }` writes
+ *   `"address.city"` and leaves the rest of `address` as it is.
+ * - {@link replace} handed to a {@link FirestoreModel.Struct} field writes the
+ *   struct whole, dropping any field the value leaves out.
+ * - Any other value is written whole where it stands. A sentinel from
+ *   {@link FieldValue} may stand at any depth.
+ *
+ * Firestore itself tells a merge from a replace by the key: a dotted path
+ * merges, a map handed to a field replaces it. A patch tells them apart by the
+ * value instead, so the same patch means the same thing wherever it is
+ * written, and replacing a map is asked for by name.
+ *
+ * Which patches a document accepts is up to its model.
+ *
+ * @example Replacing one struct and deleting a field
+ * ```ts
+ * import { Schema } from "effect";
+ * import { FieldValue, FirestoreModel, Patch } from "@visiolab/effect-firebase/firestore";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({
+ *   address: FirestoreModel.Struct({ city: Schema.String, zip: Schema.String }),
+ *   nickname: FirestoreModel.Optional(Schema.String),
+ * }) {}
+ *
+ * const patch = User.update.make({
+ *   address: Patch.replace({ city: "Berlin", zip: "10115" }),
+ *   nickname: FieldValue.deleteField,
+ * });
+ * ```
+ *
+ * @see {@link Firestore.With.updateDoc} for writing a patch
+ * @see {@link FirestoreModel.Update} for which patches a model accepts
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Inspectable } from "effect";
+import * as patch from "./internal/patch.ts";
+
+const ReplaceTypeId = patch.ReplaceTypeId;
+
+/**
+ * A struct written whole, as the map `value`. Built by {@link replace}.
+ *
+ * **Details**
+ *
+ * Unlike the sentinels in {@link FieldValue}, it never reaches Firestore. It
+ * only tells the update how to write the struct, and is the plain map by the
+ * time the update is encoded.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Replace<A> extends Inspectable.Inspectable {
+  readonly [ReplaceTypeId]: typeof ReplaceTypeId;
+  /** What the struct holds once the update lands. */
+  readonly value: A;
+}
+
+/**
+ * Checks whether `u` is a {@link Replace}.
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isReplace: (u: unknown) => u is Replace<unknown> = patch.isReplace;
+
+/**
+ * Marks a {@link FirestoreModel.Struct} field in a patch to be written whole,
+ * rather than field by field.
+ *
+ * **When to use**
+ *
+ * Use to replace a struct field outright, dropping any keys the new value leaves
+ * out. It is also the safe choice when the struct may not be in the document
+ * yet: a nested patch writes only some of its fields there, while `replace`
+ * writes all of them.
+ *
+ * **Details**
+ *
+ * `value` is the whole struct, in the shape `setDoc` writes it in. A plain
+ * object in the same place is a nested patch that only touches the fields it
+ * names. A field declared with a plain `Schema.Struct` is a value, always
+ * written whole, and takes neither.
+ *
+ * @example Replacing a struct
+ * ```ts
+ * import { Schema } from "effect";
+ * import { FirestoreModel, Patch } from "@visiolab/effect-firebase/firestore";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({
+ *   address: FirestoreModel.Struct({ city: Schema.String, zip: Schema.String }),
+ * }) {}
+ *
+ * // Writes `address` as `{ city: "Berlin", zip: "10115" }`, whatever it held.
+ * User.update.make({ address: Patch.replace({ city: "Berlin", zip: "10115" }) });
+ *
+ * // Writes `address.city` only, and leaves `address.zip` as it is.
+ * User.update.make({ address: { city: "Berlin" } });
+ * ```
+ *
+ * @see {@link Firestore.With.updateDoc} for writing the patch
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const replace: <const A>(value: A) => Replace<A> = patch.replace;

package/src/firestore/QuerySnapshot.ts

@@ -0,0 +1,150 @@
+/**
+ * What a read of many documents returns.
+ *
+ * A read of a collection or a Collection Group finds any number of documents.
+ * A query snapshot holds them as one result rather than a bare array, which
+ * leaves room for what a backend knows about the read as a whole, such as the
+ * client's `metadata`.
+ *
+ * @example Reading every document in a collection
+ * ```ts
+ * import { Collection, Firestore, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+ * import { Effect, 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.getDocs(Users.collection());
+ *   return yield* Effect.forEach(snapshot.docs, (user) => user.data);
+ * });
+ * ```
+ *
+ * @see {@link DocumentSnapshot} for what a read of one document returns
+ *
+ * @stability unstable
+ * @since 0.2.0
+ */
+import type { Inspectable } from "effect";
+import type * as Collection from "./Collection.ts";
+import type * as DocumentSnapshot from "./DocumentSnapshot.ts";
+import * as querySnapshot from "./internal/querySnapshot.ts";
+
+const TypeId = querySnapshot.TypeId;
+
+/**
+ * A {@link DocumentSnapshot.Existing} snapshot in whichever of the collections
+ * `C` it is in.
+ *
+ * **Details**
+ *
+ * For a union `C` it is `Existing<A> | Existing<B>` rather than
+ * `Existing<A | B>`, so a document's id, ancestors, reference and data all
+ * belong to the same collection.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Existing<C extends Collection.Any> = C extends Collection.Any
+  ? DocumentSnapshot.Existing<C>
+  : never;
+
+/**
+ * The documents of `C` that a read of many documents found.
+ *
+ * **Details**
+ *
+ * {@link Firestore.With.getDocs} returns one, and
+ * {@link Firestore.With.streamDocs} emits one per change. `C` is a union when
+ * the read was of a Collection Group with several members, and each document
+ * is then in one of them.
+ *
+ * `DocumentExtra` is what a backend adds to each document beyond the portable
+ * snapshot, such as the client's `metadata`. What it adds to the read as a
+ * whole is not part of this type: it is intersected where the snapshot is
+ * used, as `QuerySnapshot<C, E> & E`.
+ *
+ * @see {@link DocumentSnapshot.DocumentSnapshot} for the result of a read of one document
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface QuerySnapshot<C extends Collection.Any, DocumentExtra extends object = {}>
+  extends Inspectable.Inspectable {
+  readonly [TypeId]: typeof TypeId;
+  /**
+   * Every document the read found, in the order Firestore returned them.
+   * Empty when there were none.
+   *
+   * **Details**
+   *
+   * Each was there when it was read, so each is a
+   * {@link DocumentSnapshot.Existing} in the collection of `C` it lives in,
+   * with the `DocumentExtra` of the read.
+   *
+   * @see {@link Collection.Collection.contains} for keeping the documents of one collection
+   */
+  readonly docs: ReadonlyArray<Existing<C> & DocumentExtra>;
+}
+
+/**
+ * The fields a document snapshot `D` has beyond the portable
+ * {@link DocumentSnapshot.Existing}, such as the client's `metadata`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type ExtraOf<D extends DocumentSnapshot.Existing<Collection.Any>> = {
+  [K in keyof D as K extends keyof DocumentSnapshot.Existing<Collection.Any> ? never : K]: D[K];
+};
+
+/**
+ * Checks whether a value is a {@link QuerySnapshot}.
+ *
+ * @see {@link DocumentSnapshot.isDocumentSnapshot} for a snapshot of one document
+ *
+ * @stability unstable
+ * @category guards
+ * @since 0.2.0
+ */
+export const isQuerySnapshot: (u: unknown) => u is QuerySnapshot<Collection.Any> =
+  querySnapshot.isQuerySnapshot;
+
+/**
+ * Builds a {@link QuerySnapshot} from the documents a read found.
+ *
+ * **When to use**
+ *
+ * Use when implementing a backend or a test double. Application code gets
+ * query snapshots from {@link Firestore.With.getDocs} instead.
+ *
+ * **Details**
+ *
+ * An SDK that knows more about the read as a whole, such as the client's
+ * `metadata`, passes it as `extra`: each of its fields is put on the snapshot
+ * and shown when it prints, as {@link DocumentSnapshot.make} does for one
+ * document. Its fields must not have the same names as the snapshot's own.
+ *
+ * The documents are kept as given, so any extra fields on them stay, and stay
+ * in the snapshot's type.
+ *
+ * @see {@link DocumentSnapshot.existing} for building each document
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export const make: {
+  <C extends Collection.Any, D extends DocumentSnapshot.Existing<C> = DocumentSnapshot.Existing<C>>(
+    docs: ReadonlyArray<D> & ReadonlyArray<DocumentSnapshot.Existing<C>>,
+  ): QuerySnapshot<C, ExtraOf<D>>;
+  <C extends Collection.Any, D extends DocumentSnapshot.Existing<C>, E extends object>(
+    docs: ReadonlyArray<D> & ReadonlyArray<DocumentSnapshot.Existing<C>>,
+    extra: E,
+  ): QuerySnapshot<C, ExtraOf<D>> & E;
+} = querySnapshot.make;