@visiolab/effect-firebase-client 0.0.0-stage → 0.3.1

package/src/app/App.ts

@@ -0,0 +1,163 @@
+/**
+ * The Firebase client SDK app as an Effect service.
+ *
+ * Every other service in this package, such as
+ * {@link ClientFirestore.ClientFirestore}, is built on the {@link App} in
+ * context. Provide it with {@link layer}, or hand it an app initialized
+ * elsewhere.
+ *
+ * @example Initializing the app for a program
+ * ```ts
+ * import { Effect } from "effect";
+ * import { App } from "@visiolab/effect-firebase-client/app";
+ *
+ * const program = Effect.gen(function* () {
+ *   const app = yield* App.App;
+ *   yield* Effect.log(`Running against ${app.name}`);
+ * });
+ *
+ * program.pipe(
+ *   Effect.provide(App.layer({ apiKey: "<api key>", projectId: "my-project", appId: "<app id>" })),
+ * );
+ * ```
+ *
+ * @see [Add Firebase to your JavaScript project](https://firebase.google.com/docs/web/setup)
+ *
+ * @stability unstable
+ * @since 0.1.0
+ */
+import { Context, Effect, Layer, Schema } from "effect";
+import type * as Client from "firebase/app";
+// Only the module's documentation links to it.
+// oxlint-disable-next-line no-unused-vars
+import type * as ClientFirestore from "../firestore/ClientFirestore.ts";
+import * as internalApp from "./internal/app.ts";
+
+/**
+ * A Firebase client SDK app: the SDK's own `FirebaseApp`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface App extends Client.FirebaseApp {}
+
+/**
+ * Service key for the Firebase client SDK app.
+ *
+ * **When to use**
+ *
+ * Use to provide an app initialized elsewhere, such as one from `getApp()`,
+ * with `Layer.succeed`. Nothing deletes an app provided this way.
+ *
+ * @example Providing an app initialized elsewhere
+ * ```ts
+ * import { Layer } from "effect";
+ * import { getApp } from "firebase/app";
+ * import { App } from "@visiolab/effect-firebase-client/app";
+ *
+ * const AppLive = Layer.succeed(App.App, getApp());
+ * ```
+ *
+ * @see {@link layer} for initializing the app for the lifetime of a layer
+ *
+ * @stability unstable
+ * @category services
+ * @since 0.1.0
+ */
+export const App = Context.Service<App>("@visiolab/effect-firebase-client/app/App");
+
+/**
+ * Fails {@link make} and {@link layer} when the client SDK refuses to
+ * initialize the app, with what it threw as the `cause`.
+ *
+ * @stability unstable
+ * @category errors
+ * @since 0.1.0
+ */
+export class AppError extends Schema.TaggedError<AppError, { readonly brand: unique symbol }>()(
+  "AppError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {}
+
+/**
+ * Initializes a Firebase client SDK app, and deletes it again when the
+ * surrounding scope closes.
+ *
+ * **When to use**
+ *
+ * Use to build the app inside an effect of your own. Most programs provide it
+ * with {@link layer} instead.
+ *
+ * **Details**
+ *
+ * Takes the arguments of `initializeApp(options, name)`. Unlike the Admin SDK's,
+ * the options are required: they are the config the Firebase console gives a
+ * web app, which the client SDK only finds on its own when served from
+ * Firebase Hosting.
+ *
+ * An app already registered under the same name is not deleted when the scope
+ * closes. The client SDK only hands back that app when it was initialized with
+ * the same options, and throws otherwise.
+ *
+ * Fails with an {@link AppError} when the client SDK refuses to initialize the
+ * app. A failure to delete the app is logged as a warning, not raised.
+ *
+ * @see {@link layer} for the same as a layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = Effect.fn("App.make")(function* (
+  options: Client.FirebaseOptions,
+  name?: string,
+) {
+  const { app } = yield* Effect.acquireRelease(
+    Effect.try({
+      try: () => internalApp.initialize(options, name),
+      catch: (cause) =>
+        new AppError({ message: "Failed to initialize the Firebase client SDK app", cause }),
+    }),
+    internalApp.release,
+  );
+  return app;
+});
+
+/**
+ * A layer that initializes a Firebase client SDK app for the lifetime of the
+ * layer.
+ *
+ * **When to use**
+ *
+ * Use when this program owns the app. Where something else already initialized
+ * it, provide that app as {@link App} instead.
+ *
+ * **Details**
+ *
+ * Takes the arguments of `initializeApp(options, name)`.
+ *
+ * @example Initializing the app from the console's config
+ * ```ts
+ * import { App } from "@visiolab/effect-firebase-client/app";
+ *
+ * const AppLive = App.layer({
+ *   apiKey: "<api key>",
+ *   authDomain: "my-project.firebaseapp.com",
+ *   projectId: "my-project",
+ *   appId: "<app id>",
+ * });
+ * ```
+ *
+ * @see {@link make} for how the app is initialized and torn down
+ * @see {@link App} for providing an app initialized elsewhere
+ *
+ * @stability unstable
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = (options: Client.FirebaseOptions, name?: string): Layer.Layer<App, AppError> =>
+  Layer.effect(App, make(options, name));

package/src/app/index.ts

@@ -0,0 +1,7 @@
+/**
+ * The Firebase client SDK app as an Effect service.
+ *
+ * @stability unstable
+ * @since 0.1.0
+ */
+export * as App from "./App.ts";

package/src/app/internal/app.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import { defaultAppName } from "@visiolab/effect-firebase/app/App";
+import * as Client from "firebase/app";
+import type * as App from "../App.ts";
+
+/**
+ * The app together with whether we are the ones who initialized it.
+ *
+ * @internal
+ */
+export interface Initialized {
+  readonly app: App.App;
+  readonly owned: boolean;
+}
+
+/** @internal */
+export const initialize = (options: Client.FirebaseOptions, name?: string): Initialized => {
+  // An app that is already registered under this name was initialized by
+  // somebody else, so ending its lifecycle is not ours to do. `initializeApp`
+  // still throws when that app was configured differently, so conflicting
+  // configuration is not swallowed here.
+  const owned = !Client.getApps().some((app) => app.name === (name ?? defaultAppName));
+  return { app: Client.initializeApp(options, name), owned };
+};
+
+/** @internal */
+export const release = ({ app, owned }: Initialized): Effect.Effect<void> =>
+  owned
+    ? Effect.tryPromise(() => Client.deleteApp(app)).pipe(
+        Effect.ignore({
+          log: "Warn",
+          message: `Failed to delete the Firebase client SDK app "${app.name}"`,
+        }),
+      )
+    : Effect.void;

package/src/firestore/ClientDocumentSnapshot.ts

@@ -0,0 +1,156 @@
+/**
+ * What a read of one document through {@link ClientFirestore.ClientFirestore}
+ * returns: a portable {@link DocumentSnapshot.DocumentSnapshot} that also
+ * carries the {@link SnapshotMetadata} the client SDK reported for the read.
+ *
+ * Each variant extends its portable one, so a client snapshot can be handed to
+ * portable code as it is, and the portable guards, such as
+ * {@link DocumentSnapshot.isExisting}, tell its variants apart.
+ *
+ * @example Checking whether a read came from the cache
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+ * import { ClientFirestore } from "@visiolab/effect-firebase-client/firestore";
+ *
+ * class User extends FirestoreModel.Class<User>("User")({
+ *   name: Schema.String,
+ * }) {}
+ *
+ * const Users = Collection.make("users", User);
+ *
+ * const program = Effect.gen(function* () {
+ *   const firestore = yield* ClientFirestore.ClientFirestore;
+ *   const snapshot = yield* firestore.getDoc(Users.doc(Users.id.make("alice")));
+ *   if (snapshot.metadata.fromCache) {
+ *     // Served from the local cache, so possibly out of date.
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link ClientQuerySnapshot} for what a read of many documents returns
+ *
+ * @stability unstable
+ * @since 0.1.0
+ */
+import * as DocumentSnapshot from "@visiolab/effect-firebase/firestore/DocumentSnapshot";
+import type * as Collection from "@visiolab/effect-firebase/firestore/Collection";
+import * as snapshotMetadata from "./internal/snapshotMetadata.ts";
+
+/**
+ * What the client SDK reports about where a snapshot came from: the SDK's
+ * `SnapshotMetadata`.
+ *
+ * @see {@link ClientFirestore.ListenOptions} for hearing a change to it on a listen
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface SnapshotMetadata {
+  /**
+   * Whether it was served from the local cache instead of confirmed by the
+   * server, such as while offline, and so may be out of date.
+   */
+  readonly fromCache: boolean;
+  /**
+   * Whether it reflects writes made by this client that the server has not
+   * acknowledged yet.
+   */
+  readonly hasPendingWrites: boolean;
+}
+
+/**
+ * A document that was there when it was read, with the
+ * {@link SnapshotMetadata} of that read.
+ *
+ * @see {@link DocumentSnapshot.Existing} for the portable snapshot it extends
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface Existing<C extends Collection.Any> extends DocumentSnapshot.Existing<C> {
+  readonly metadata: SnapshotMetadata;
+}
+
+/**
+ * A document that was not there when it was read, with the
+ * {@link SnapshotMetadata} of that read. Its `fromCache` tells "the cache says
+ * it is gone" from "the server says it is gone".
+ *
+ * @see {@link DocumentSnapshot.Missing} for the portable snapshot it extends
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface Missing<C extends Collection.Any> extends DocumentSnapshot.Missing<C> {
+  readonly metadata: SnapshotMetadata;
+}
+
+/**
+ * A document in `C`, as a read through {@link ClientFirestore.ClientFirestore}
+ * found it: {@link Existing} or {@link Missing}.
+ *
+ * @see {@link DocumentSnapshot.DocumentSnapshot} for the portable snapshot
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type ClientDocumentSnapshot<C extends Collection.Any> = Existing<C> | Missing<C>;
+
+/**
+ * Builds a snapshot of the document at `ref` from what the client SDK's
+ * `snapshot.data()` returned and the `snapshot.metadata` it reported.
+ *
+ * **When to use**
+ *
+ * Use to turn a snapshot read through the client SDK itself into this
+ * library's. An `undefined` `data` builds {@link Missing}, anything else
+ * {@link Existing}.
+ *
+ * @see {@link existing} for a document known to be there
+ * @see {@link missing} for a document known not to be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  data: unknown,
+  metadata: SnapshotMetadata,
+): ClientDocumentSnapshot<C> =>
+  DocumentSnapshot.make(ref, data, snapshotMetadata.extraOf(metadata));
+
+/**
+ * Builds a snapshot of a document known to be there, such as one a query
+ * returned.
+ *
+ * @see {@link make} for a document that may or may not be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export const existing = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  data: unknown,
+  metadata: SnapshotMetadata,
+): Existing<C> => DocumentSnapshot.existing(ref, data, snapshotMetadata.extraOf(metadata));
+
+/**
+ * Builds a snapshot of a document known not to be there.
+ *
+ * @see {@link make} for a document that may or may not be there
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export const missing = <C extends Collection.Any>(
+  ref: Collection.DocumentReference<C>,
+  metadata: SnapshotMetadata,
+): Missing<C> => DocumentSnapshot.missing(ref, snapshotMetadata.extraOf(metadata));