@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/firestore/GeoPoint.d.mts

@@ -0,0 +1,90 @@
+import { Equal, Inspectable, Option } from "effect";
+declare namespace GeoPoint_d_exports {
+  export { GeoPoint, isGeoPoint, make, makeUnsafe };
+}
+declare const TypeId = "~@visiolab/effect-firebase/firestore/GeoPoint";
+/**
+ * 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 declare const isGeoPoint: (u: unknown) => u is GeoPoint;
+/**
+ * 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 declare const makeUnsafe: (latitude: number, longitude: number) => GeoPoint;
+/**
+ * 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 declare const make: (latitude: number, longitude: number) => Option.Option<GeoPoint>;
+export { GeoPoint_d_exports };

package/dist/firestore/GeoPoint.mjs

@@ -0,0 +1,75 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { isGeoPoint as isGeoPoint$1, make as make$1, makeUnsafe as makeUnsafe$1 } from "./internal/geoPoint.mjs";
+// src/firestore/GeoPoint.ts
+var GeoPoint_exports = /* @__PURE__ */ __exportAll({
+	isGeoPoint: () => isGeoPoint,
+	make: () => make,
+	makeUnsafe: () => makeUnsafe
+});
+/**
+* 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
+*/
+const isGeoPoint = isGeoPoint$1;
+/**
+* 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
+*/
+const makeUnsafe = makeUnsafe$1;
+/**
+* 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
+*/
+const make = make$1;
+export { GeoPoint_exports, isGeoPoint, make, makeUnsafe };

package/dist/firestore/Patch.d.mts

@@ -0,0 +1,73 @@
+import { Inspectable } from "effect";
+declare namespace Patch_d_exports {
+  export { Replace, isReplace, replace };
+}
+declare const ReplaceTypeId = "~@visiolab/effect-firebase/firestore/Patch/Replace";
+/**
+ * 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 declare const isReplace: (u: unknown) => u is Replace<unknown>;
+/**
+ * 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 declare const replace: <const A>(value: A) => Replace<A>;
+export { Patch_d_exports };

package/dist/firestore/Patch.mjs

@@ -0,0 +1,57 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { isReplace as isReplace$1, replace as replace$1 } from "./internal/patch.mjs";
+// src/firestore/Patch.ts
+var Patch_exports = /* @__PURE__ */ __exportAll({
+	isReplace: () => isReplace,
+	replace: () => replace
+});
+/**
+* Checks whether `u` is a {@link Replace}.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isReplace = isReplace$1;
+/**
+* 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
+*/
+const replace = replace$1;
+export { Patch_exports, isReplace, replace };

package/dist/firestore/QuerySnapshot.d.mts

@@ -0,0 +1,107 @@
+import { Existing as Existing$1 } from "./DocumentSnapshot.mjs";
+import { Any } from "./Collection.mjs";
+import { Inspectable } from "effect";
+declare namespace QuerySnapshot_d_exports {
+  export { Existing, ExtraOf, QuerySnapshot, isQuerySnapshot, make };
+}
+declare const TypeId = "~@visiolab/effect-firebase/firestore/QuerySnapshot";
+/**
+ * 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 Any> = C extends Any ? Existing$1<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 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 Existing$1<Any>> = { [K in keyof D as K extends keyof Existing$1<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 declare const isQuerySnapshot: (u: unknown) => u is QuerySnapshot<Any>;
+/**
+ * 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 declare const make: {
+  <C extends Any, D extends Existing$1<C> = Existing$1<C>>(docs: ReadonlyArray<D> & ReadonlyArray<Existing$1<C>>): QuerySnapshot<C, ExtraOf<D>>;
+  <C extends Any, D extends Existing$1<C>, E extends object>(docs: ReadonlyArray<D> & ReadonlyArray<Existing$1<C>>, extra: E): QuerySnapshot<C, ExtraOf<D>> & E;
+};
+export { QuerySnapshot_d_exports };

package/dist/firestore/QuerySnapshot.mjs

@@ -0,0 +1,43 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { isQuerySnapshot as isQuerySnapshot$1, make as make$1 } from "./internal/querySnapshot.mjs";
+// src/firestore/QuerySnapshot.ts
+var QuerySnapshot_exports = /* @__PURE__ */ __exportAll({
+	isQuerySnapshot: () => isQuerySnapshot,
+	make: () => make
+});
+/**
+* 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
+*/
+const isQuerySnapshot = isQuerySnapshot$1;
+/**
+* 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
+*/
+const make = make$1;
+export { QuerySnapshot_exports, isQuerySnapshot, make };