@visiolab/effect-firebase 0.0.0-stage → 0.3.1

package/dist/firestore/FirestoreModel.mjs

@@ -0,0 +1,586 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { Array as Array$1, Class as Class$1, Field as Field$1, FieldExcept as FieldExcept$1, FieldOnly as FieldOnly$1, Immutable as Immutable$1, Number as Number$1, Optional as Optional$1, Record as Record$1, Struct as Struct$1, Timestamp as Timestamp$1, Union as Union$1, extract as extract$1, fieldEvolve as fieldEvolve$1, fields as fields$1 } from "./internal/firestoreModel.mjs";
+// src/firestore/FirestoreModel.ts
+var FirestoreModel_exports = /* @__PURE__ */ __exportAll({
+	Array: () => Array,
+	Class: () => Class,
+	Field: () => Field,
+	FieldExcept: () => FieldExcept,
+	FieldOnly: () => FieldOnly,
+	Immutable: () => Immutable,
+	Number: () => Number,
+	Optional: () => Optional,
+	Record: () => Record,
+	Struct: () => Struct,
+	Timestamp: () => Timestamp,
+	Union: () => Union,
+	extract: () => extract,
+	fieldEvolve: () => fieldEvolve,
+	fields: () => fields
+});
+/**
+* Declares a field with a different schema per variant.
+*
+* **When to use**
+*
+* Use when a field is read and written in shapes no ready-made field covers.
+* Leave a variant out to keep the field out of that shape.
+*
+* @example A field written as a sentinel and read as a timestamp
+* ```ts
+* import { FirestoreModel, FirestoreSchema } from "@visiolab/effect-firebase/firestore";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({
+*   publishedAt: FirestoreModel.Field({
+*     read: FirestoreSchema.Timestamp,
+*     create: FirestoreSchema.ServerTimestamp,
+*   }),
+* }) {}
+* ```
+*
+* @see {@link FieldOnly} for the same schema in some variants
+* @see {@link FieldExcept} for the same schema in all but some variants
+* @see {@link Timestamp} for a timestamp the client or the server may set
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const Field = Field$1;
+/**
+* Declares a field with one schema that appears only in the named variants.
+*
+* **When to use**
+*
+* Use for a field only some shapes carry, such as one only ever read, or one
+* only ever written.
+*
+* @example A field only read
+* ```ts
+* import { Schema } from "effect";
+* import { FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Account extends FirestoreModel.Class<Account>("Account")({
+*   plan: FirestoreModel.FieldOnly(["read"])(Schema.Literals(["free", "paid"])),
+* }) {}
+* ```
+*
+* @see {@link FieldExcept} for naming the variants to leave out instead
+* @see {@link Field} for a different schema per variant
+* @see {@link Immutable} for a field read and created, but never updated
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const FieldOnly = FieldOnly$1;
+/**
+* Declares a field with one schema that appears in every variant but the named
+* ones.
+*
+* **When to use**
+*
+* Use when a field belongs in most shapes and only a few leave it out.
+*
+* @see {@link FieldOnly} for naming the variants to keep instead
+* @see {@link Field} for a different schema per variant
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const FieldExcept = FieldExcept$1;
+/**
+* Declares a set of fields without building a class.
+*
+* **When to use**
+*
+* Use for a nested map inside a document, or for fields shared between several
+* documents. An update reaches into a struct field by field, unlike a plain
+* `Schema.Struct`, which is a value written whole.
+*
+* @example A nested address
+* ```ts
+* import { Schema } from "effect";
+* import { FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* const Address = FirestoreModel.Struct({ city: Schema.String, zip: Schema.String });
+*
+* class Customer extends FirestoreModel.Class<Customer>("Customer")({
+*   address: Address,
+* }) {}
+*
+* Customer.update.make({ address: { city: "Berlin" } }); // written at "address.city"
+* ```
+*
+* @see {@link Class} for a whole document
+* @see {@link Patch.replace} for writing a struct whole in an update
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const Struct = Struct$1;
+/**
+* Rewrites the schemas of a field, variant by variant.
+*
+* **When to use**
+*
+* Use to derive a field from another one, such as narrowing what one variant
+* takes while keeping the others.
+*
+* @see {@link Field} for declaring a field per variant directly
+*
+* @stability unstable
+* @category transforming
+* @since 0.2.0
+*/
+const fieldEvolve = fieldEvolve$1;
+/**
+* Pulls one variant out of a struct as a plain schema.
+*
+* **When to use**
+*
+* Use to get a struct's `read` or `create` shape as an ordinary schema, for
+* example to validate data outside Firestore.
+*
+* **Details**
+*
+* The `update` variant it returns is the one the fields declare: it is neither
+* made partial nor flattened into paths. Use {@link Class.update} for the
+* update a document is written through.
+*
+* @see {@link fields} for the field declarations themselves
+*
+* @stability unstable
+* @category converting
+* @since 0.2.0
+*/
+const extract = extract$1;
+/**
+* Returns the field declarations a {@link Class} or {@link Struct} was built
+* from.
+*
+* **When to use**
+*
+* Use to build a new struct or class from the fields of an existing one.
+*
+* @see {@link extract} for one variant of a struct as a plain schema
+*
+* @stability unstable
+* @category getters
+* @since 0.2.0
+*/
+const fields = fields$1;
+/**
+* Defines a document schema: one field declaration, with the shapes a document
+* is read, created and updated in derived from it.
+*
+* **When to use**
+*
+* Use to define what the documents of a collection hold. Hand the class to
+* {@link Collection.make}, and every read and write of that collection goes
+* through it.
+*
+* **Details**
+*
+* The class is the `read` variant: what a snapshot decodes into, and what
+* schema combinators take. The write shapes hang off it:
+*
+* - {@link Class.create} is what `setDoc` and `addDoc` write, a whole document,
+*   taking the sentinels and constructor defaults its fields declare.
+* - {@link Class.update} is what `updateDoc` writes, a nested partial encoded at
+*   field paths, taking only patches that leave any document readable.
+* - {@link Class.updateUnchecked} also takes patches that are only right where
+*   the caller knows what the document holds - see {@link UpdateMode}.
+*
+* The document's id is not a field: it lives in the path.
+*
+* @example Defining a document and its writes
+* ```ts
+* import { Schema } from "effect";
+* import {
+*   FieldValue,
+*   FirestoreModel,
+*   FirestoreSchema,
+* } from "@visiolab/effect-firebase/firestore";
+*
+* class User extends FirestoreModel.Class<User>("User")({
+*   displayName: Schema.String,
+*   signupSource: FirestoreModel.Immutable(Schema.String),
+*   createdAt: FirestoreModel.Timestamp(FirestoreSchema.Timestamp),
+*   visits: FirestoreModel.Number(Schema.Int),
+*   nickname: FirestoreModel.Optional(Schema.String),
+* }) {}
+*
+* User.create.make({
+*   displayName: "Ada",
+*   signupSource: "web",
+*   createdAt: FieldValue.serverTimestamp,
+*   visits: 0,
+* });
+*
+* User.update.make({ visits: FieldValue.increment(1), nickname: FieldValue.deleteField });
+* ```
+*
+* @see {@link Union} for a document that holds one of several shapes
+* @see {@link Struct} for a nested map, or fields shared between documents
+* @see {@link Collection.make} for the collection a document lives in
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const Class = Class$1;
+/**
+* Declares a document or field that holds one of several structs or classes.
+*
+* **When to use**
+*
+* Use when documents of one collection, or one field, come in several shapes,
+* such as the states of a job or the versions of a document, told apart by a
+* literal field.
+*
+* **Details**
+*
+* It is Effect's own union, with no tag of this library's. A snapshot decodes
+* into the first member that matches, so a literal field narrows it, and data
+* matching no member fails with a schema issue. A `create` takes any member
+* in the shape `setDoc` writes it. A value that fits several members, on
+* `create` or in a replacement, is taken as the first in declaration order, as
+* `Schema.Union` does.
+*
+* As a field, an update may:
+*
+* - Replace it with {@link Patch.replace} and any member, in its `create`
+*   shape. A member holding a field that `setDoc` or an update leaves out -
+*   {@link Immutable}, or a read-only field - is never replaced, as with a
+*   struct.
+* - Remove it with {@link FieldValue.deleteField}, where it is
+*   {@link Optional}.
+* - Patch its Shared Fields: keys every member holds, with a value every member
+*   takes and stores the same way, so the patch is right whichever member the
+*   document holds. A struct every member holds at a key is patched at its own
+*   Shared Fields. A union every member holds at a key is written by this same
+*   rule, across all of those unions. A Record is never shared.
+* - Under `unchecked`, also patch a key only some members hold, such as
+*   `completedAt` on a job the caller knows is done. The value is checked
+*   against just those members and written at its path. An {@link Optional}
+*   union is only patched under `unchecked`.
+*
+* As a whole document, `setDoc` writes any member and changing member takes a
+* whole `setDoc`. An update patches it by the same rule - see
+* {@link UnionUpdate}.
+*
+* @example A field holding one of several states
+* ```ts
+* import { Schema } from "effect";
+* import {
+*   FieldValue,
+*   FirestoreModel,
+*   FirestoreSchema,
+*   Patch,
+* } from "@visiolab/effect-firebase/firestore";
+*
+* const Pending = FirestoreModel.Struct({ status: Schema.Literal("pending") });
+* const Done = FirestoreModel.Struct({
+*   status: Schema.Literal("done"),
+*   completedAt: FirestoreModel.Timestamp(FirestoreSchema.Timestamp),
+* });
+*
+* class Job extends FirestoreModel.Class<Job>("Job")({
+*   state: FirestoreModel.Union([Pending, Done]),
+* }) {}
+*
+* Job.update.make({
+*   state: Patch.replace({ status: "done", completedAt: FieldValue.serverTimestamp }),
+* });
+* // Where the job is known to be done: written at "state.completedAt".
+* Job.updateUnchecked.make({ state: { completedAt: FieldValue.serverTimestamp } });
+* ```
+*
+* @see {@link Class} for a document with a single shape
+* @see {@link UpdateMode} for what `checked` and `unchecked` patch
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const Union = Union$1;
+/**
+* Declares a field written once, when the document is created.
+*
+* **When to use**
+*
+* Use for a field that must never change after creation, such as a sign-up
+* source or an owner id.
+*
+* **Details**
+*
+* It is read, and written by `setDoc`, but left out of `update`, so no update
+* can change it. A struct or union member holding it is never replaced by an
+* update, since that would rewrite it.
+*
+* @see {@link FieldOnly} for keeping a field to other variants
+* @see {@link Optional} for a field that may be missing
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Immutable = Immutable$1;
+/**
+* Declares a timestamp field that the client or the server may set.
+*
+* **When to use**
+*
+* Use for a timestamp a write may leave to the server, such as `createdAt` or
+* `updatedAt`. Where the server must never set it, use the schema itself as
+* the field.
+*
+* **Details**
+*
+* `setDoc` and `updateDoc` take either a value of `schema` or
+* {@link FieldValue.serverTimestamp}. A read takes `schema` alone, since the
+* sentinel is resolved by the time a document comes back.
+*
+* `schema` decides what the instant is held as:
+* {@link FirestoreSchema.Timestamp} where precision finer than a millisecond
+* must survive a round trip, or `Schema.DateTimeUtc` or `Schema.Date` where one
+* of those is easier to work with. Firestore stores each as a timestamp.
+*
+* @example Timestamps held two ways
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel, FirestoreSchema } from "@visiolab/effect-firebase/firestore";
+*
+* class Session extends FirestoreModel.Class<Session>("Session")({
+*   createdAt: FirestoreModel.Timestamp(FirestoreSchema.Timestamp),
+*   seenAt: FirestoreModel.Timestamp(Schema.DateTimeUtc),
+* }) {}
+*
+* Session.update.make({ seenAt: FieldValue.serverTimestamp });
+* ```
+*
+* @see {@link FirestoreSchema.Timestamp} for the schema that keeps full precision
+* @see {@link FirestoreSchema.ServerTimestampOr} for the write schema this
+* declares
+* @see {@link FieldValue.serverTimestamp} for the sentinel a write hands it
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Timestamp = Timestamp$1;
+/**
+* Declares a number field that a write may set or have the server increment.
+*
+* **When to use**
+*
+* Use for counters and totals more than one client may change at once: an
+* increment keeps the total right, where reading the number and writing the
+* sum back loses concurrent writes. Where it must never be incremented, use
+* the schema itself as the field.
+*
+* **Details**
+*
+* `setDoc` and `updateDoc` take either a value of `schema` or
+* {@link FieldValue.increment} / {@link FieldValue.decrement}. A read takes
+* `schema` alone, since the document holds the sum the server computed.
+*
+* `schema` decides what the number may be, on both reads and writes: hand it
+* `Schema.Int` for whole steps, or `Schema.Finite` for fractions. An increment
+* is not checked against it, since the server computes the sum and only the
+* next read sees it.
+*
+* @example A counter and a balance
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Account extends FirestoreModel.Class<Account>("Account")({
+*   visits: FirestoreModel.Number(Schema.Int),
+*   balance: FirestoreModel.Number(Schema.Finite),
+* }) {}
+*
+* Account.update.make({ visits: FieldValue.increment(1) });
+* ```
+*
+* @see {@link FieldValue.increment} for the sentinel a write hands it
+* @see {@link FirestoreSchema.IncrementOr} for the write schema this declares
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Number = Number$1;
+/**
+* Declares an array field that an update may write whole, or have the server
+* add elements to or remove elements from.
+*
+* **When to use**
+*
+* Use for an array more than one client may change at once, such as a list of
+* tags: {@link FieldValue.arrayUnion} and {@link FieldValue.arrayRemove} keep
+* an element another client added at the same time, where reading the array
+* and writing it back does not.
+*
+* **Details**
+*
+* An update takes the array, `arrayUnion` or `arrayRemove`. A read takes the
+* array alone. `setDoc` takes the array alone too: adding to a missing array
+* writes the elements as they are, and removing from one writes it empty,
+* which is not what was meant.
+*
+* Elements are matched by value, all the way down, so removing a map from the
+* array means handing over every key it holds - see
+* {@link FieldValue.ArrayRemove}. `item` is what each element is held as. It
+* cannot be an array, which Firestore does not nest, or a field, since an
+* element is always written whole.
+*
+* @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 FieldValue.arrayUnion} and {@link FieldValue.arrayRemove} for the
+* sentinels an update hands it
+* @see {@link FirestoreSchema.ArrayOr} for the update schema this declares
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Array = Array$1;
+/**
+* Declares a map field whose keys come from the data, which an update writes
+* key by key.
+*
+* **When to use**
+*
+* Use for a map keyed by data rather than by a fixed set of fields: a counter
+* per option, an entry per member, a lookup table. Writing key by key lets two
+* clients each change a key of the same map without reading it first.
+*
+* **Details**
+*
+* A read and `setDoc` hold it as `Schema.Record(key, value)`, with each value
+* in its read or create shape, so `setDoc` takes the sentinels `value` takes.
+* An update takes a patch, writing each key it carries at its own path, in the
+* update shape of `value`: a {@link Number} takes
+* {@link FieldValue.increment}, an {@link Array} {@link FieldValue.arrayUnion},
+* a {@link Timestamp} {@link FieldValue.serverTimestamp}.
+*
+* - Where `key` is a string, refined or not, any key may be missing, so each
+*   takes {@link FieldValue.deleteField}. A value that is itself a struct or
+*   Record is treated like an {@link Optional} struct: written whole with
+*   {@link Patch.replace} or removed, and only patched by
+*   {@link Class.updateUnchecked}.
+* - Where `key` is a union of literals, the Record holds every key, and an
+*   update treats it as a struct with a field per key: no key is removed
+*   unless `value` is {@link Optional}.
+*
+* Either way, it takes {@link Patch.replace} to be written whole, unless
+* `value` holds a field `setDoc` or an update leaves out.
+*
+* A key's path is the key as `key` encodes it, so the update requires any
+* service `key` needs to encode. A key no path can name - empty, or containing
+* a `.` - fails the update when it is encoded, or throws when the Record is
+* declared if it is a literal. A value no update writes, such as
+* {@link Immutable}, leaves the whole Record out of the update.
+*
+* @example Patching keys of a map
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+*
+* class Poll extends FirestoreModel.Class<Poll>("Poll")({
+*   votes: FirestoreModel.Record(Schema.String, FirestoreModel.Number(Schema.Int)),
+*   aliases: FirestoreModel.Record(Schema.String, Schema.String),
+* }) {}
+*
+* Poll.update.make({
+*   votes: { pizza: FieldValue.increment(1) }, // "votes.pizza"
+*   aliases: { old: FieldValue.deleteField }, // "aliases.old"
+* });
+* ```
+*
+* @see {@link Struct} for a map with a fixed set of fields
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Record = Record$1;
+/**
+* Declares a field a document may go without, and an update may remove.
+*
+* **When to use**
+*
+* Use for a field that may be missing from a document. Wrap any schema, field,
+* struct, union or {@link Record} in it.
+*
+* **Details**
+*
+* A read and `setDoc` hold it as an optional key: a missing field is left out
+* rather than stored as `null`. An update also takes
+* {@link FieldValue.deleteField}, since leaving a field out of an update leaves
+* it as it is. Inside a struct, an optional field is removed the same way, at
+* its path.
+*
+* A field with no `update` variant, such as {@link Immutable}, becomes optional
+* where it is read and created, and stays out of the update. Making a field
+* optional twice is the same as once.
+*
+* An optional struct is where the stored document decides what a patch does: a
+* patch written into a missing struct creates it holding only the patch, and
+* the document no longer reads. So {@link Class.update} writes it whole with
+* {@link Patch.replace} or removes it, and only {@link Class.updateUnchecked}
+* patches it, for a caller who knows it is there.
+*
+* @example Optional fields
+* ```ts
+* import { Schema } from "effect";
+* import { FirestoreModel, FirestoreSchema } from "@visiolab/effect-firebase/firestore";
+*
+* const Address = FirestoreModel.Struct({ city: Schema.String });
+*
+* class User extends FirestoreModel.Class<User>("User")({
+*   nickname: FirestoreModel.Optional(Schema.String),
+*   lastSeenAt: FirestoreModel.Optional(FirestoreModel.Timestamp(FirestoreSchema.Timestamp)),
+*   address: FirestoreModel.Optional(Address),
+* }) {}
+* ```
+*
+* @example Updating an optional struct
+* ```ts
+* import { Schema } from "effect";
+* import { FieldValue, FirestoreModel, Patch } from "@visiolab/effect-firebase/firestore";
+*
+* const Address = FirestoreModel.Struct({ city: Schema.String, zip: Schema.String });
+*
+* class Customer extends FirestoreModel.Class<Customer>("Customer")({
+*   address: FirestoreModel.Optional(Address),
+* }) {}
+*
+* Customer.update.make({ address: Patch.replace({ city: "Berlin", zip: "10115" }) }); // written whole
+* Customer.update.make({ address: FieldValue.deleteField }); // removed
+* Customer.updateUnchecked.make({ address: { city: "Berlin" } }); // the caller knows it is there
+* ```
+*
+* @see {@link FieldValue.deleteField} for removing it in an update
+* @see {@link UpdateMode} for when an optional struct may be patched
+*
+* @stability unstable
+* @category schemas
+* @since 0.2.0
+*/
+const Optional = Optional$1;
+export { Array, Class, Field, FieldExcept, FieldOnly, FirestoreModel_exports, Immutable, Number, Optional, Record, Struct, Timestamp, Union, extract, fieldEvolve, fields };