@visiolab/effect-firebase 0.0.0-stage → 0.3.1

package/dist/firestore/FieldValue.mjs

@@ -0,0 +1,256 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { arrayRemove as arrayRemove$1, arrayUnion as arrayUnion$1, decrement as decrement$1, deleteField as deleteField$1, increment as increment$1, isArrayRemove as isArrayRemove$1, isArrayUnion as isArrayUnion$1, isDeleteField as isDeleteField$1, isIncrement as isIncrement$1, isServerTimestamp as isServerTimestamp$1, serverTimestamp as serverTimestamp$1 } from "./internal/fieldValue.mjs";
+// src/firestore/FieldValue.ts
+var FieldValue_exports = /* @__PURE__ */ __exportAll({
+	arrayRemove: () => arrayRemove,
+	arrayUnion: () => arrayUnion,
+	decrement: () => decrement,
+	deleteField: () => deleteField,
+	increment: () => increment,
+	isArrayRemove: () => isArrayRemove,
+	isArrayUnion: () => isArrayUnion,
+	isDeleteField: () => isDeleteField,
+	isIncrement: () => isIncrement,
+	isServerTimestamp: () => isServerTimestamp,
+	serverTimestamp: () => serverTimestamp
+});
+/**
+* Asks the server to write the time it applies the write.
+*
+* **When to use**
+*
+* Use for fields such as `createdAt` and `updatedAt` that every client should
+* agree on. The local clock differs between clients, the server's does not.
+*
+* **Details**
+*
+* It carries nothing, so there is only this one value. The field reads back as
+* the timestamp the server wrote.
+*
+* @example Stamping a document with the server's time
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({
+*   updatedAt: FirestoreModel.Timestamp(Schema.DateTimeUtc),
+* }) {}
+*
+* Post.update.make({ updatedAt: FieldValue.serverTimestamp });
+* ```
+*
+* @see {@link Timestamp.now} for the local time instead
+* @see {@link FirestoreModel.Timestamp} for a model field that accepts it
+* @see {@link FirestoreSchema.ServerTimestampOr} for a schema that accepts it
+* @see {@link FirestoreSchema.ServerTimestamp} for a schema that always writes it
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const serverTimestamp = serverTimestamp$1;
+/**
+* Checks whether `u` is the {@link ServerTimestamp} sentinel.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isServerTimestamp = isServerTimestamp$1;
+/**
+* Checks whether `u` is an {@link Increment} sentinel.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isIncrement = isIncrement$1;
+/**
+* Asks the server to raise a number field by `by`.
+*
+* **When to use**
+*
+* Use for counters and totals that several clients may change at once. Two
+* clients that each read a number and write back the sum lose one of the
+* changes; two increments do not.
+*
+* **Details**
+*
+* Throws unless `by` is a finite number. Integers and doubles both work; an
+* integer added to a double gives a double. A field that holds no number, or
+* is missing, counts as zero.
+*
+* @example Counting a visit
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Page extends FirestoreModel.Class<Page>("Page")({
+*   visits: FirestoreModel.Number(Schema.Int),
+* }) {}
+*
+* Page.update.make({ visits: FieldValue.increment(1) });
+* ```
+*
+* @see {@link decrement} for lowering a field
+* @see {@link FirestoreModel.Number} for a model field that accepts it
+* @see {@link FirestoreSchema.IncrementOr} for a schema that accepts it
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const increment = increment$1;
+/**
+* Asks the server to lower a number field by `by`.
+*
+* **When to use**
+*
+* Use where the code counts down, so it reads that way rather than as an
+* increment by a negative number.
+*
+* **Details**
+*
+* It is {@link increment} of `-by`: `decrement(2).by` is `-2`.
+*
+* @see {@link increment} for raising a field
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const decrement = decrement$1;
+/**
+* Asks the server to remove a field.
+*
+* **When to use**
+*
+* Use in an update to remove an optional field. Leaving a field out of an
+* update keeps it as it is, so removing one has to be asked for.
+*
+* **Details**
+*
+* After the write, the document has no key at all for the field, not one
+* holding `null`. Only an update accepts it: a document written whole with
+* `setDoc` drops a field by leaving it out, and Firestore refuses the sentinel
+* there.
+*
+* It carries nothing, so there is only this one value. It is not called
+* `delete` because that is a reserved word in JavaScript, which is also why the
+* client SDK calls its own `deleteField`.
+*
+* @example Removing an optional field
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class User extends FirestoreModel.Class<User>("User")({
+*   nickname: FirestoreModel.Optional(Schema.String),
+* }) {}
+*
+* User.update.make({ nickname: FieldValue.deleteField });
+* ```
+*
+* @see {@link FirestoreModel.Optional} for a model field that accepts it
+* @see {@link FirestoreSchema.DeleteFieldOr} for a schema that accepts it
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const deleteField = deleteField$1;
+/**
+* Checks whether `u` is the {@link DeleteField} sentinel.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isDeleteField = isDeleteField$1;
+/**
+* Checks whether `u` is an {@link ArrayUnion} sentinel.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isArrayUnion = isArrayUnion$1;
+/**
+* Asks the server to add `elements` to an array, skipping any it holds already.
+*
+* **When to use**
+*
+* Use to add to an array that several clients may change at once. A client
+* that reads the array, adds an element and writes it back loses whatever
+* another client added in between; `arrayUnion` does not.
+*
+* **Details**
+*
+* Elements are compared by value, as {@link ArrayUnion} describes. With no
+* elements it changes nothing, except that a field that held no array ends up
+* holding an empty one.
+*
+* @example Adding a tag
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Article extends FirestoreModel.Class<Article>("Article")({
+*   tags: FirestoreModel.Array(Schema.String),
+* }) {}
+*
+* Article.update.make({ tags: FieldValue.arrayUnion("news") });
+* ```
+*
+* @see {@link arrayRemove} for removing elements
+* @see {@link FirestoreModel.Array} for a model field that accepts it
+* @see {@link FirestoreSchema.ArrayOr} for a schema that accepts it
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const arrayUnion = arrayUnion$1;
+/**
+* Checks whether `u` is an {@link ArrayRemove} sentinel.
+*
+* @stability unstable
+* @category guards
+* @since 0.2.0
+*/
+const isArrayRemove = isArrayRemove$1;
+/**
+* Asks the server to remove every element equal to one of `elements` from an
+* array.
+*
+* **When to use**
+*
+* Use to remove from an array that several clients may change at once, keeping
+* whatever they add in the meantime.
+*
+* **Details**
+*
+* The match is exact, as {@link ArrayRemove} describes.
+*
+* @example Removing a tag
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Article extends FirestoreModel.Class<Article>("Article")({
+*   tags: FirestoreModel.Array(Schema.String),
+* }) {}
+*
+* Article.update.make({ tags: FieldValue.arrayRemove("draft") });
+* ```
+*
+* @see {@link arrayUnion} for adding elements
+* @see {@link FirestoreModel.Array} for a model field that accepts it
+* @see {@link FirestoreSchema.ArrayOr} for a schema that accepts it
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const arrayRemove = arrayRemove$1;
+export { FieldValue_exports, arrayRemove, arrayUnion, decrement, deleteField, increment, isArrayRemove, isArrayUnion, isDeleteField, isIncrement, isServerTimestamp, serverTimestamp };