@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/firestore/Collection.mjs

@@ -0,0 +1,133 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { fromPath as fromPath$1, isCollection as isCollection$1, isCollectionReference as isCollectionReference$1, isDocumentReference as isDocumentReference$1, make as make$1 } from "./internal/collection.mjs";
+// src/firestore/Collection.ts
+var Collection_exports = /* @__PURE__ */ __exportAll({
+	fromPath: () => fromPath,
+	isCollection: () => isCollection,
+	isCollectionReference: () => isCollectionReference,
+	isDocumentReference: () => isDocumentReference,
+	make: () => make
+});
+/**
+* Checks whether a value is a collection definition.
+*
+* @see {@link isCollectionReference} for a reference to a collection
+* @see {@link CollectionGroup.isCollectionGroup} for a Collection Group
+*
+* @stability unstable
+* @category guards
+* @since 0.1.0
+*/
+const isCollection = isCollection$1;
+/**
+* Checks whether a value is a {@link CollectionReference}.
+*
+* @see {@link isCollection} for a collection definition
+* @see {@link isDocumentReference} for a reference to a document
+*
+* @stability unstable
+* @category guards
+* @since 0.1.0
+*/
+const isCollectionReference = isCollectionReference$1;
+/**
+* Checks whether a value is a {@link DocumentReference} into any collection.
+*
+* @see {@link Collection.contains} for checking that a reference belongs to one collection, with narrowing
+* @see {@link isCollectionReference} for a reference to a collection
+* @see {@link DocumentPath.isDocumentPath} for the untyped path stored in a field
+*
+* @stability unstable
+* @category guards
+* @since 0.1.0
+*/
+const isDocumentReference = isDocumentReference$1;
+/**
+* Defines a root collection and the model of its documents.
+*
+* **When to use**
+*
+* Use once per root collection, at module level, and build every reference to
+* it from the result. Use {@link Collection.subcollection} on the result for a
+* collection nested under its documents.
+*
+* **Details**
+*
+* The documents are described by a {@link FirestoreModel.Class} rather than a
+* plain schema, since a document is written in other shapes than it is read
+* in, and the model carries each of them. Pass a {@link FirestoreModel.Union}
+* of classes for a collection that holds several document shapes.
+*
+* Throws when `segment` is not a collection id Firestore accepts: empty,
+* containing `/`, `.` or `..`, matching `__.*__`, or longer than 1500 bytes. An
+* invalid definition is a programming error, not a failure to recover from.
+*
+* @example Defining a collection with a subcollection
+* ```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 }) {}
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Users = Collection.make("users", User);
+* const UserPosts = Users.subcollection("posts", Post);
+*
+* const program = Effect.gen(function* () {
+*   const firestore = yield* Firestore.Firestore;
+*   const alice = Users.id.make("alice");
+*
+*   yield* firestore.setDoc(Users.doc(alice), { name: "Alice" });
+*   const post = yield* firestore.addDoc(UserPosts.collection(alice), { title: "Hello" });
+*   return post.path; // "users/alice/posts/<generated id>"
+* });
+* ```
+*
+* @see {@link fromPath} for a reference to a document of an existing collection from a path string
+* @see {@link CollectionGroup.make} for reading several collections with one collection id together
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const make = make$1;
+/**
+* References the document of `collection` at a path string, such as
+* `users/alice/posts/hello`, or returns `None` when the path is not in that
+* collection.
+*
+* **When to use**
+*
+* Use when a path arrives as a string, such as from a URL, a message or a
+* stored {@link DocumentPath.DocumentPath}, and you know which collection it
+* should be in.
+*
+* **Details**
+*
+* The path is checked against every segment the collection was defined with,
+* so a path into another collection returns `None`, even one with the same
+* last segment. Every id in the path must be non-empty.
+*
+* @example Parsing a path
+* ```ts
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { Option, 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);
+*
+* Option.isSome(Collection.fromPath(UserPosts, "users/alice/posts/hello")); // true
+* Option.isSome(Collection.fromPath(UserPosts, "orgs/acme/posts/hello")); // false
+* ```
+*
+* @see {@link Collection.doc} for a reference built from typed ids
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const fromPath = fromPath$1;
+export { Collection_exports, fromPath, isCollection, isCollectionReference, isDocumentReference, make };

package/dist/firestore/CollectionGroup.d.mts

@@ -0,0 +1,164 @@
+import { Any as Any$1, DocumentReference as DocumentReference$1 } from "./Collection.mjs";
+import { UndefinedCollectionError } from "./internal/firestoreError.mjs";
+import "./Firestore.mjs";
+import { Inspectable, Result } from "effect";
+declare namespace CollectionGroup_d_exports {
+  export { Any, CollectionGroup, DocumentReference, Members, Valid, documentAt, isCollectionGroup, make };
+}
+declare const TypeId = "~@visiolab/effect-firebase/firestore/CollectionGroup";
+/**
+ * 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 Any$1> 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 Any$1) ? C extends Any$1 ? DocumentReference$1<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<Any$1>, K, C extends Any$1> = 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<Any$1>> = { readonly [K in keyof Members]: Members[K] extends Any$1 ? 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 declare const isCollectionGroup: (u: unknown) => u is Any;
+/**
+ * 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 declare const make: <const Members extends readonly [Any$1, ...Array<Any$1>]>(...members: Valid<Members>) => CollectionGroup<Members[number]>;
+/**
+ * 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 declare const documentAt: <G extends Any>(group: G, path: string) => Result.Result<DocumentReference<G>, UndefinedCollectionError>;
+export { CollectionGroup_d_exports };

package/dist/firestore/CollectionGroup.mjs

@@ -0,0 +1,84 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { documentAt as documentAt$1, isCollectionGroup as isCollectionGroup$1, make as make$1 } from "./internal/collectionGroup.mjs";
+// src/firestore/CollectionGroup.ts
+var CollectionGroup_exports = /* @__PURE__ */ __exportAll({
+	documentAt: () => documentAt,
+	isCollectionGroup: () => isCollectionGroup,
+	make: () => make
+});
+/**
+* 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
+*/
+const isCollectionGroup = isCollectionGroup$1;
+/**
+* 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
+*/
+const make = make$1;
+/**
+* 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
+*/
+const documentAt = documentAt$1;
+export { CollectionGroup_exports, documentAt, isCollectionGroup, make };

package/dist/firestore/DocumentPath.d.mts

@@ -0,0 +1,95 @@
+import { Equal, Inspectable, Option } from "effect";
+declare namespace DocumentPath_d_exports {
+  export { DocumentPath, isDocumentPath, make, makeUnsafe };
+}
+declare const TypeId = "~@visiolab/effect-firebase/firestore/DocumentPath";
+/**
+ * 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 declare const isDocumentPath: (u: unknown) => u is DocumentPath;
+/**
+ * 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 declare const make: (path: string) => Option.Option<DocumentPath>;
+/**
+ * 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 declare const makeUnsafe: (path: string) => DocumentPath;
+export { DocumentPath_d_exports };

package/dist/firestore/DocumentPath.mjs

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