@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/functions/DocumentTrigger.mjs

@@ -0,0 +1,566 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { isFunctionGroup } from "./internal/functionGroup.mjs";
+import { changeEvent, createdEvent as createdEvent$1, deletedEvent as deletedEvent$1, deployment as deployment$1, kind, make, serve as serve$1, toLayer as toLayer$1 } from "./internal/documentTrigger.mjs";
+// src/functions/DocumentTrigger.ts
+var DocumentTrigger_exports = /* @__PURE__ */ __exportAll({
+	created: () => created,
+	createdEvent: () => createdEvent,
+	deleted: () => deleted,
+	deletedEvent: () => deletedEvent,
+	deployment: () => deployment,
+	serve: () => serve,
+	toLayer: () => toLayer,
+	updated: () => updated,
+	updatedEvent: () => updatedEvent,
+	written: () => written,
+	writtenEvent: () => writtenEvent
+});
+/**
+* The group and the trigger that the arguments of an overload taking
+* `(trigger, ...)` or `(group, name, ...)` name.
+*/
+const target = (args) => isFunctionGroup(args[0]) ? [args[0], args[0].functions[args[1]]] : [void 0, args[0]];
+/**
+* Declares a trigger that runs when a document of `collection` is created.
+*
+* **When to use**
+*
+* Use to react to new documents of a collection on the server. Use a
+* `Callable` instead when the client asks for the work by name.
+*
+* **Details**
+*
+* Its handler gets a {@link Created} event. It takes one collection,
+* whatever its depth: the path pattern it is deployed with is derived from
+* the collection's path, with a wildcard for each parent document's id and
+* for the document's id. A collection group can't be watched; declare a
+* trigger for each of its collections.
+*
+* Firebase delivers each event at least once. Make the handler idempotent,
+* keyed on the event's `id`.
+*
+* @example Declaring a trigger on a subcollection
+* ```ts
+* import { Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class User extends FirestoreModel.Class<User>("User")({ name: Schema.String }) {}
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("users", User).subcollection("posts", Post);
+*
+* // Runs for each post created under any user.
+* const OnPostCreated = DocumentTrigger.created("onPostCreated", Posts);
+* ```
+*
+* @see {@link updated} for running when an existing document changes
+* @see {@link deleted} for running when a document is deleted
+* @see {@link written} for running on a create, an update and a delete alike
+* @see {@link toLayer} for implementing the trigger
+* @see {@link createdEvent} for building its event in a test
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+* @see {@link Callable.make} for declaring a Function the client calls
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const created = (name, collection) => make({
+	kind,
+	name,
+	event: "created",
+	collection
+});
+/**
+* Builds the event of a {@link created} trigger from the created document's
+* snapshot.
+*
+* **When to use**
+*
+* Use in a test, to run a handler through {@link serve} with an event of
+* your own. The functions package builds its events with it too.
+*
+* **Details**
+*
+* The event's `ref` is the snapshot's. Build the snapshot with
+* `DocumentSnapshot.existing` and the stored data as Firestore Values.
+*
+* @example Building an event for a test
+* ```ts
+* import { Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("posts", Post);
+*
+* const event = DocumentTrigger.createdEvent({
+*   id: "event-1",
+*   time: "2026-01-01T00:00:00.000Z",
+*   snapshot: DocumentSnapshot.existing(Posts.doc(Posts.id.make("hello")), { title: "Hello" }),
+* });
+* ```
+*
+* @see {@link created} for declaring the trigger
+* @see {@link serve} for running the event through the handler
+* @see {@link Created} for the event it builds
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const createdEvent = createdEvent$1;
+/**
+* Declares a trigger that runs when a document of `collection` is deleted.
+*
+* **When to use**
+*
+* Use to clean up after a document of a collection is deleted, such as
+* removing what refers to it.
+*
+* **Details**
+*
+* Its handler gets a {@link Deleted} event, with the document as it was just
+* before it was deleted. It is deployed at the same path pattern as a
+* {@link created} trigger on the same collection.
+*
+* Firebase delivers each event at least once. Make the handler idempotent,
+* keyed on the event's `id`.
+*
+* @example Reading the deleted document
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const OnPostDeleted = DocumentTrigger.deleted("onPostDeleted", Collection.make("posts", Post));
+*
+* const OnPostDeletedLive = DocumentTrigger.toLayer(OnPostDeleted, (event) =>
+*   Effect.flatMap(event.snapshot.data, (post) => Effect.log(`Deleted ${post.title}`)),
+* );
+* ```
+*
+* @see {@link created} for running when a document is created
+* @see {@link updated} for running when an existing document changes
+* @see {@link written} for running on a create, an update and a delete alike
+* @see {@link toLayer} for implementing the trigger
+* @see {@link deletedEvent} for building its event in a test
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const deleted = (name, collection) => make({
+	kind,
+	name,
+	event: "deleted",
+	collection
+});
+/**
+* Builds the event of a {@link deleted} trigger from the snapshot of the
+* document as it was just before it was deleted.
+*
+* **When to use**
+*
+* Use in a test, to run a handler through {@link serve} with an event of
+* your own. The functions package builds its events with it too.
+*
+* **Details**
+*
+* The event's `ref` is the snapshot's. Build the snapshot with
+* `DocumentSnapshot.existing` and the document's last data as Firestore
+* Values.
+*
+* @example Building an event for a test
+* ```ts
+* import { Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("posts", Post);
+*
+* const event = DocumentTrigger.deletedEvent({
+*   id: "event-1",
+*   time: "2026-01-01T00:00:00.000Z",
+*   snapshot: DocumentSnapshot.existing(Posts.doc(Posts.id.make("hello")), { title: "Hello" }),
+* });
+* ```
+*
+* @see {@link deleted} for declaring the trigger
+* @see {@link serve} for running the event through the handler
+* @see {@link Deleted} for the event it builds
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const deletedEvent = deletedEvent$1;
+/**
+* Declares a trigger that runs when a document of `collection` that already
+* exists is changed.
+*
+* **When to use**
+*
+* Use to react to changes to existing documents, with the data before and
+* after the change at hand.
+*
+* **Details**
+*
+* Its handler gets an {@link Updated} event, with the document before and
+* after the update. Creating or deleting a document doesn't run it.
+*
+* Firebase delivers each event at least once. Make the handler idempotent,
+* keyed on the event's `id`.
+*
+* @example Reacting to a changed title
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const OnPostUpdated = DocumentTrigger.updated("onPostUpdated", Collection.make("posts", Post));
+*
+* const OnPostUpdatedLive = DocumentTrigger.toLayer(OnPostUpdated, (event) =>
+*   Effect.gen(function* () {
+*     const before = yield* event.before.data;
+*     const after = yield* event.after.data;
+*     if (before.title !== after.title) {
+*       yield* Effect.log(`Renamed ${before.title} to ${after.title}`);
+*     }
+*   }),
+* );
+* ```
+*
+* @see {@link created} for running when a document is created
+* @see {@link deleted} for running when a document is deleted
+* @see {@link written} for running on a create and a delete too
+* @see {@link toLayer} for implementing the trigger
+* @see {@link updatedEvent} for building its event in a test
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const updated = (name, collection) => make({
+	kind,
+	name,
+	event: "updated",
+	collection
+});
+/**
+* Builds the event of an {@link updated} trigger from the snapshots of the
+* document before and after the update.
+*
+* **When to use**
+*
+* Use in a test, to run a handler through {@link serve} with an event of
+* your own. The functions package builds its events with it too.
+*
+* **Details**
+*
+* Both snapshots are of the same document. The event's `ref` is the one of
+* `after`. Build each with `DocumentSnapshot.existing`.
+*
+* @example Building an event for a test
+* ```ts
+* import { Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("posts", Post);
+* const ref = Posts.doc(Posts.id.make("hello"));
+*
+* const event = DocumentTrigger.updatedEvent({
+*   id: "event-1",
+*   time: "2026-01-01T00:00:00.000Z",
+*   before: DocumentSnapshot.existing(ref, { title: "Draft" }),
+*   after: DocumentSnapshot.existing(ref, { title: "Final" }),
+* });
+* ```
+*
+* @see {@link updated} for declaring the trigger
+* @see {@link serve} for running the event through the handler
+* @see {@link Updated} for the event it builds
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const updatedEvent = changeEvent;
+/**
+* Declares a trigger that runs when a document of `collection` is created,
+* updated or deleted.
+*
+* **When to use**
+*
+* Use to handle every change to a collection's documents in one handler, such
+* as keeping a copy or a count in sync. Prefer {@link created},
+* {@link updated} or {@link deleted} when the handler acts on one change only.
+*
+* **Details**
+*
+* Its handler gets a {@link Written} event, whose `before` and `after` are
+* `DocumentSnapshot`s: `before` is `Missing` on a create, and `after` is
+* `Missing` on a delete. Narrow each with `DocumentSnapshot.isExisting` or
+* `DocumentSnapshot.isMissing`.
+*
+* Firebase delivers each event at least once. Make the handler idempotent,
+* keyed on the event's `id`.
+*
+* @example Telling a create, an update and a delete apart
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const OnPostWritten = DocumentTrigger.written("onPostWritten", Collection.make("posts", Post));
+*
+* const OnPostWrittenLive = DocumentTrigger.toLayer(OnPostWritten, (event) => {
+*   if (DocumentSnapshot.isMissing(event.after)) {
+*     return Effect.log(`Deleted ${event.ref.id}`);
+*   }
+*   const verb = DocumentSnapshot.isExisting(event.before) ? "Updated" : "Created";
+*   return Effect.flatMap(event.after.data, (post) => Effect.log(`${verb} ${post.title}`));
+* });
+* ```
+*
+* @see {@link created} for running on a create only, with the document always there
+* @see {@link updated} for running on an update only, with both sides always there
+* @see {@link deleted} for running on a delete only, with the last data always there
+* @see {@link toLayer} for implementing the trigger
+* @see {@link writtenEvent} for building its event in a test
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const written = (name, collection) => make({
+	kind,
+	name,
+	event: "written",
+	collection
+});
+/**
+* Builds the event of a {@link written} trigger from the snapshots of the
+* document before and after the write.
+*
+* **When to use**
+*
+* Use in a test, to run a handler through {@link serve} with an event of
+* your own. The functions package builds its events with it too.
+*
+* **Details**
+*
+* Both snapshots are of the same document. The event's `ref` is the one of
+* `after`, which a `Missing` snapshot carries too. Build a side that exists
+* with `DocumentSnapshot.existing` and one that doesn't with
+* `DocumentSnapshot.missing`.
+*
+* @example Building the event of a create for a test
+* ```ts
+* import { Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("posts", Post);
+* const ref = Posts.doc(Posts.id.make("hello"));
+*
+* const event = DocumentTrigger.writtenEvent({
+*   id: "event-1",
+*   time: "2026-01-01T00:00:00.000Z",
+*   before: DocumentSnapshot.missing(ref),
+*   after: DocumentSnapshot.existing(ref, { title: "Hello" }),
+* });
+* ```
+*
+* @see {@link written} for declaring the trigger
+* @see {@link serve} for running the event through the handler
+* @see {@link Written} for the event it builds
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const writtenEvent = changeEvent;
+/**
+* Implements a Document Trigger as a Layer.
+*
+* **When to use**
+*
+* Use to write the server side of a trigger. The Layer is what
+* `Functions.make` and `Functions.group` from
+* `@visiolab/effect-firebase-functions` serve, and what {@link serve} runs
+* in a test.
+*
+* **Details**
+*
+* Takes the handler itself, or an Effect that builds it. The Effect runs
+* once, when the Layer is built, so do per-instance setup there.
+*
+* For a trigger in a Function Group, pass the group and the member's name.
+* Each group implements its members separately, so the Layer of the trigger
+* on its own doesn't serve it in a group, and the Layer of one group's
+* member doesn't serve it in another.
+*
+* The Layer requires what the handler needs on each event and what building
+* it needs. Both are provided where the Layer is built, and shared by every
+* event. Reading `snapshot.data` needs what the collection's model needs to
+* decode.
+*
+* Firebase delivers each event at least once. Make the handler idempotent,
+* keyed on the event's `id`.
+*
+* @example Building the handler once per instance
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const OnPostCreated = DocumentTrigger.created("onPostCreated", Collection.make("posts", Post));
+*
+* const OnPostCreatedLive = DocumentTrigger.toLayer(
+*   OnPostCreated,
+*   Effect.gen(function* () {
+*     const prefix = yield* Effect.succeed("New post");
+*     return (event) => Effect.log(`${prefix}: ${event.ref.id}`);
+*   }),
+* );
+* ```
+*
+* @example Implementing a trigger in a Function Group
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { Callable, DocumentTrigger, FunctionGroup } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Publish = Callable.make("publish", { payload: { id: Schema.String } });
+* const OnCreated = DocumentTrigger.created("onCreated", Collection.make("posts", Post));
+*
+* class Posts extends FunctionGroup.make("posts").add(Publish, OnCreated) {}
+*
+* // Serves `posts-onCreated`.
+* const OnCreatedLive = DocumentTrigger.toLayer(Posts, "onCreated", (event) =>
+*   Effect.log(`New post: ${event.ref.id}`),
+* );
+* ```
+*
+* @see {@link created}, {@link updated}, {@link deleted} and {@link written} for declaring the trigger
+* @see {@link serve} for running an event through the handler
+* @see {@link Callable.toLayer} for implementing a Callable
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const toLayer = ((...args) => {
+	const [group, trigger] = target(args);
+	return toLayer$1(group?.identifier, trigger.name, args[group === void 0 ? 1 : 2]);
+});
+/**
+* Runs events of a Document Trigger through its handler.
+*
+* **When to use**
+*
+* Use to test a trigger's handler in process, without the emulator and
+* without `firebase-functions`: build an event with {@link createdEvent},
+* {@link updatedEvent}, {@link deletedEvent} or {@link writtenEvent} and
+* provide the Layer from {@link toLayer}. `Functions.make` from
+* `@visiolab/effect-firebase-functions` runs every real event through it too.
+*
+* **Details**
+*
+* Requires the trigger's handler, which it reads once. Returns a function of
+* the event, which fails with whatever the handler fails with.
+*
+* For a trigger in a Function Group, pass the group and the member's name:
+* it then requires the handler from `toLayer(group, name, handler)`.
+*
+* @example Running an event in a test
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Collection, DocumentSnapshot, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { DocumentTrigger } from "@visiolab/effect-firebase/functions";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({ title: Schema.String }) {}
+*
+* const Posts = Collection.make("posts", Post);
+* const OnPostCreated = DocumentTrigger.created("onPostCreated", Posts);
+*
+* const OnPostCreatedLive = DocumentTrigger.toLayer(OnPostCreated, (event) =>
+*   Effect.flatMap(event.snapshot.data, (post) => Effect.log(post.title)),
+* );
+*
+* const program = DocumentTrigger.serve(OnPostCreated).pipe(
+*   Effect.flatMap((run) =>
+*     run(
+*       DocumentTrigger.createdEvent({
+*         id: "event-1",
+*         time: "2026-01-01T00:00:00.000Z",
+*         snapshot: DocumentSnapshot.existing(Posts.doc(Posts.id.make("hello")), {
+*           title: "Hello",
+*         }),
+*       }),
+*     ),
+*   ),
+*   Effect.provide(OnPostCreatedLive),
+* );
+* ```
+*
+* @see {@link toLayer} for providing the handler
+* @see {@link createdEvent} for building the event of a `created` trigger
+* @see {@link deletedEvent} for building the event of a `deleted` trigger
+* @see {@link updatedEvent} for building the event of an `updated` trigger
+* @see {@link writtenEvent} for building the event of a `written` trigger
+* @see {@link Functions.make} for deploying the trigger through `firebase-functions`
+* @see {@link Callable.serve} for running a call to a Callable
+*
+* @stability unstable
+* @category serving
+* @since 0.3.0
+*/
+const serve = ((...args) => serve$1(...target(args)));
+/**
+* Returns the {@link Deployment} of a Document Trigger: its deployed name and
+* its document path pattern. A building block of the functions package. Most
+* apps don't need it.
+*
+* **When to use**
+*
+* Use when deploying triggers with a transport of your own. `Functions`
+* already uses it.
+*
+* **Details**
+*
+* Pass the trigger for one in no group, or a Function Group and a trigger
+* member's name for one in a group, which is deployed as `<group>-<name>`.
+*
+* @see {@link Callable.deployment} for where a Callable is served
+*
+* @stability unstable
+* @category serving
+* @since 0.3.0
+*/
+const deployment = ((...args) => deployment$1(...target(args)));
+export { DocumentTrigger_exports, created, createdEvent, deleted, deletedEvent, deployment, serve, toLayer, updated, updatedEvent, written, writtenEvent };

package/dist/functions/FirebaseFunction.d.mts

@@ -0,0 +1,79 @@
+import { HandlerTypeId, NoGroupTypeId } from "./internal/firebaseFunction.mjs";
+declare namespace FirebaseFunction_d_exports {
+  export { Any, FirebaseFunction, Handler, HandlerFor, NoGroup };
+}
+/**
+ * A Function: a server function's kind and its name.
+ *
+ * **Details**
+ *
+ * The name is the Function's identity. A Function in no group is deployed
+ * under its name, and a member of a group under `<group>-<name>`. It is a
+ * literal type that exports and group members are keyed on.
+ *
+ * The kind says what runs the Function, such as `"Callable"`, and decides how
+ * it is served and deployed.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface FirebaseFunction<out Kind extends string, out Name extends string> {
+  /** What runs the Function, such as `"Callable"`. */
+  readonly kind: Kind;
+  /** The Function's name, which a Function in no group is deployed under. */
+  readonly name: Name;
+}
+/**
+ * Any {@link FirebaseFunction}, whatever its kind and name.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Any extends FirebaseFunction<string, string> {}
+/**
+ * Marks the {@link Handler} of a Function in no group.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface NoGroup {
+  readonly [NoGroupTypeId]: typeof NoGroupTypeId;
+}
+/**
+ * The service that holds the handler of the Function `Name`, as served in
+ * `Group`, whatever its kind.
+ *
+ * **Details**
+ *
+ * A handler is keyed by its group and its name, so the handler of `greet` in
+ * no group is `Handler<NoGroup, "greet">`, and that of `create` in the group
+ * `users` is `Handler<"users", "create">`. A Layer that serves a Function must
+ * provide its handler under exactly that key. Each kind's `toLayer`, such as
+ * {@link Callable.toLayer}, builds such a Layer.
+ *
+ * @see {@link HandlerFor} for the handler of a Function in no group
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export interface Handler<Group, Name extends string> {
+  readonly [HandlerTypeId]: {
+    readonly group: Group;
+    readonly name: Name;
+  };
+}
+/**
+ * The {@link Handler} of a Function in no group.
+ *
+ * @see {@link Handler} for the handler of a member of a group
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type HandlerFor<F extends Any> = Handler<NoGroup, F["name"]>;
+export { FirebaseFunction_d_exports };

package/dist/functions/FirebaseFunction.mjs

@@ -0,0 +1,4 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+// src/functions/FirebaseFunction.ts
+var FirebaseFunction_exports = /* @__PURE__ */ __exportAll({});
+export { FirebaseFunction_exports };