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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisioLab GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @visiolab/effect-firebase-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [`@visiolab/effect-firebase`](https://github.com/VisioLab/effect-firebase/tree/main/packages/effect-firebase) services on the Firebase client SDK (`firebase`), for browsers. On a server, use [`@visiolab/effect-firebase-admin`](https://github.com/VisioLab/effect-firebase/tree/main/packages/admin) instead.
+
+```sh
+pnpm add effect @visiolab/effect-firebase @visiolab/effect-firebase-client firebase
+```
+
+## App
+
+`App` is the client SDK app as an Effect service. Every other service in this package is built on it.
+
+`App.layer` initializes the app when the layer is built and deletes it when the layer's scope closes. It takes the arguments of `initializeApp(options, name)`. The options are required: they are the config the Firebase console gives a web app.
+
+```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>" })),
+);
+```
+
+An app already registered under the same name is not deleted when the scope closes. The client SDK only hands that app back when it was initialized with the same options. To use an app initialized elsewhere, provide it directly:
+
+```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());
+```
+
+## Firestore
+
+`ClientFirestore.layer` provides one service under two keys: the portable `Firestore`, which code that runs on either SDK asks for, and `ClientFirestore`, which adds what only the client SDK can do. Both reach the same database:
+
+```ts
+import { Layer } from "effect";
+import { persistentLocalCache } from "firebase/firestore";
+import { App } from "@visiolab/effect-firebase-client/app";
+import { ClientFirestore } from "@visiolab/effect-firebase-client/firestore";
+
+const FirestoreLive = ClientFirestore.layer({
+  localCache: persistentLocalCache(),
+  emulator: import.meta.env.DEV ? { host: "127.0.0.1", port: 8080 } : undefined,
+}).pipe(
+  Layer.provide(App.layer({ apiKey: "<api key>", projectId: "my-project", appId: "<app id>" })),
+);
+```
+
+What `ClientFirestore` adds:
+
+- **Read sources.** `getDoc` and `getDocs` take `{ source: "server" }` or `{ source: "cache" }` to read from one side alone.
+- **Listen options.** `streamDoc` and `streamDocs` take `includeMetadataChanges` and a `source`.
+- **Snapshot metadata.** Every snapshot carries `metadata`, with `fromCache` and `hasPendingWrites`, as `ClientDocumentSnapshot` and `ClientQuerySnapshot` describe.
+
+Where it behaves differently from the Admin SDK's:
+
+- **The emulator is a layer option**, connected before the database is first used, not an environment variable.
+- **Writes wait for the server.** A write made offline is applied to the local cache at once, but only succeeds once the server acknowledges it. Interrupting it, or timing it out, does not take it back: the SDK still sends it when it can.
+- **Pending server timestamps are estimated.** A field written with a server timestamp the server has not settled yet reads as the local clock's estimate, not `null`, so it decodes as a timestamp.
+- **Error codes are always named**, such as `permission-denied`.
+- **Transactions read one document at a time.** The client SDK's transactions cannot read a collection.
+
+`ClientFirestore.instance` is the client SDK's own `Firestore`, for what the service does not wrap, such as `disableNetwork` and `enableNetwork`. `ClientFirestoreValue` maps between Firestore Values and the client SDK's values, to read or write a model through it.

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,12 @@
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+export { __exportAll };

package/dist/app/App.d.mts

@@ -0,0 +1,117 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import * as Client from "firebase/app";
+declare namespace App_d_exports {
+  export { App, AppError, layer, make };
+}
+/**
+ * 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 declare const App: Context.Service<App, App>;
+declare const AppError_base: Schema.Class<AppError, Schema.TaggedStruct<"AppError", {
+  readonly message: Schema.String;
+  readonly cause: Schema.optional<Schema.Defect>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * 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 declare class AppError extends AppError_base {}
+/**
+ * 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 declare const make: (options: Client.FirebaseOptions, name?: string | undefined) => Effect.Effect<App, AppError, import("effect/Scope").Scope>;
+/**
+ * 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 declare const layer: (options: Client.FirebaseOptions, name?: string) => Layer.Layer<App, AppError>;
+export { App_d_exports };
+//# sourceMappingURL=App.d.mts.map

package/dist/app/App.mjs

@@ -0,0 +1,149 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { initialize, release } from "./internal/app.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+// src/app/App.ts
+/**
+* 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
+*/
+var App_exports = /* @__PURE__ */ __exportAll({
+	App: () => App,
+	AppError: () => AppError,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* 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
+*/
+const App = Context.Service("@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
+*/
+var AppError = class extends Schema.TaggedError()("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
+*/
+const make = Effect.fn("App.make")(function* (options, name) {
+	const { app } = yield* Effect.acquireRelease(Effect.try({
+		try: () => initialize(options, name),
+		catch: (cause) => new AppError({
+			message: "Failed to initialize the Firebase client SDK app",
+			cause
+		})
+	}), 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
+*/
+const layer = (options, name) => Layer.effect(App, make(options, name));
+export { App, AppError, App_exports, layer, make };
+
+//# sourceMappingURL=App.mjs.map

package/dist/app/App.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.mjs","names":["internalApp.initialize","internalApp.release"],"sources":["../../src/app/App.ts"],"sourcesContent":["/**\n * The Firebase client SDK app as an Effect service.\n *\n * Every other service in this package, such as\n * {@link ClientFirestore.ClientFirestore}, is built on the {@link App} in\n * context. Provide it with {@link layer}, or hand it an app initialized\n * elsewhere.\n *\n * @example Initializing the app for a program\n * ```ts\n * import { Effect } from \"effect\";\n * import { App } from \"@visiolab/effect-firebase-client/app\";\n *\n * const program = Effect.gen(function* () {\n *   const app = yield* App.App;\n *   yield* Effect.log(`Running against ${app.name}`);\n * });\n *\n * program.pipe(\n *   Effect.provide(App.layer({ apiKey: \"<api key>\", projectId: \"my-project\", appId: \"<app id>\" })),\n * );\n * ```\n *\n * @see [Add Firebase to your JavaScript project](https://firebase.google.com/docs/web/setup)\n *\n * @stability unstable\n * @since 0.1.0\n */\nimport { Context, Effect, Layer, Schema } from \"effect\";\nimport type * as Client from \"firebase/app\";\n// Only the module's documentation links to it.\n// oxlint-disable-next-line no-unused-vars\nimport type * as ClientFirestore from \"../firestore/ClientFirestore.ts\";\nimport * as internalApp from \"./internal/app.ts\";\n\n/**\n * A Firebase client SDK app: the SDK's own `FirebaseApp`.\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface App extends Client.FirebaseApp {}\n\n/**\n * Service key for the Firebase client SDK app.\n *\n * **When to use**\n *\n * Use to provide an app initialized elsewhere, such as one from `getApp()`,\n * with `Layer.succeed`. Nothing deletes an app provided this way.\n *\n * @example Providing an app initialized elsewhere\n * ```ts\n * import { Layer } from \"effect\";\n * import { getApp } from \"firebase/app\";\n * import { App } from \"@visiolab/effect-firebase-client/app\";\n *\n * const AppLive = Layer.succeed(App.App, getApp());\n * ```\n *\n * @see {@link layer} for initializing the app for the lifetime of a layer\n *\n * @stability unstable\n * @category services\n * @since 0.1.0\n */\nexport const App = Context.Service<App>(\"@visiolab/effect-firebase-client/app/App\");\n\n/**\n * Fails {@link make} and {@link layer} when the client SDK refuses to\n * initialize the app, with what it threw as the `cause`.\n *\n * @stability unstable\n * @category errors\n * @since 0.1.0\n */\nexport class AppError extends Schema.TaggedError<AppError, { readonly brand: unique symbol }>()(\n  \"AppError\",\n  {\n    message: Schema.String,\n    cause: Schema.optional(Schema.Defect()),\n  },\n) {}\n\n/**\n * Initializes a Firebase client SDK app, and deletes it again when the\n * surrounding scope closes.\n *\n * **When to use**\n *\n * Use to build the app inside an effect of your own. Most programs provide it\n * with {@link layer} instead.\n *\n * **Details**\n *\n * Takes the arguments of `initializeApp(options, name)`. Unlike the Admin SDK's,\n * the options are required: they are the config the Firebase console gives a\n * web app, which the client SDK only finds on its own when served from\n * Firebase Hosting.\n *\n * An app already registered under the same name is not deleted when the scope\n * closes. The client SDK only hands back that app when it was initialized with\n * the same options, and throws otherwise.\n *\n * Fails with an {@link AppError} when the client SDK refuses to initialize the\n * app. A failure to delete the app is logged as a warning, not raised.\n *\n * @see {@link layer} for the same as a layer\n *\n * @stability unstable\n * @category constructors\n * @since 0.1.0\n */\nexport const make = Effect.fn(\"App.make\")(function* (\n  options: Client.FirebaseOptions,\n  name?: string,\n) {\n  const { app } = yield* Effect.acquireRelease(\n    Effect.try({\n      try: () => internalApp.initialize(options, name),\n      catch: (cause) =>\n        new AppError({ message: \"Failed to initialize the Firebase client SDK app\", cause }),\n    }),\n    internalApp.release,\n  );\n  return app;\n});\n\n/**\n * A layer that initializes a Firebase client SDK app for the lifetime of the\n * layer.\n *\n * **When to use**\n *\n * Use when this program owns the app. Where something else already initialized\n * it, provide that app as {@link App} instead.\n *\n * **Details**\n *\n * Takes the arguments of `initializeApp(options, name)`.\n *\n * @example Initializing the app from the console's config\n * ```ts\n * import { App } from \"@visiolab/effect-firebase-client/app\";\n *\n * const AppLive = App.layer({\n *   apiKey: \"<api key>\",\n *   authDomain: \"my-project.firebaseapp.com\",\n *   projectId: \"my-project\",\n *   appId: \"<app id>\",\n * });\n * ```\n *\n * @see {@link make} for how the app is initialized and torn down\n * @see {@link App} for providing an app initialized elsewhere\n *\n * @stability unstable\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (options: Client.FirebaseOptions, name?: string): Layer.Layer<App, AppError> =>\n  Layer.effect(App, make(options, name));\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,MAAM,QAAQ,QAAa,0CAA0C;;;;;;;;;AAUlF,IAAa,WAAb,cAA8B,OAAO,YAAyD,CAAC,CAC7F,YACA;CACE,SAAS,OAAO;CAChB,OAAO,OAAO,SAAS,OAAO,OAAO,CAAC;AACxC,CACF,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,MAAa,OAAO,OAAO,GAAG,UAAU,CAAC,CAAC,WACxC,SACA,MACA;CACA,MAAM,EAAE,QAAQ,OAAO,OAAO,eAC5B,OAAO,IAAI;EACT,WAAWA,WAAuB,SAAS,IAAI;EAC/C,QAAQ,UACN,IAAI,SAAS;GAAE,SAAS;GAAoD;EAAM,CAAC;CACvF,CAAC,GACDC,OACF;CACA,OAAO;AACT,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCD,MAAa,SAAS,SAAiC,SACrD,MAAM,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC"}

package/dist/app/index.d.mts

@@ -0,0 +1,2 @@
+import { App_d_exports } from "./App.mjs";
+export { App_d_exports as App };

package/dist/app/index.mjs

@@ -0,0 +1 @@
+export { App_exports as App } from "./App.mjs";

package/dist/app/internal/app.mjs

@@ -0,0 +1,20 @@
+import { Effect } from "effect";
+import { defaultAppName } from "@visiolab/effect-firebase/app/App";
+import * as Client from "firebase/app";
+// src/app/internal/app.ts
+/** @internal */
+const initialize = (options, name) => {
+	const owned = !Client.getApps().some((app) => app.name === (name ?? defaultAppName));
+	return {
+		app: Client.initializeApp(options, name),
+		owned
+	};
+};
+/** @internal */
+const release = ({ app, owned }) => owned ? Effect.tryPromise(() => Client.deleteApp(app)).pipe(Effect.ignore({
+	log: "Warn",
+	message: `Failed to delete the Firebase client SDK app "${app.name}"`
+})) : Effect.void;
+export { initialize, release };
+
+//# sourceMappingURL=app.mjs.map

package/dist/app/internal/app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.mjs","names":[],"sources":["../../../src/app/internal/app.ts"],"sourcesContent":["import { Effect } from \"effect\";\nimport { defaultAppName } from \"@visiolab/effect-firebase/app/App\";\nimport * as Client from \"firebase/app\";\nimport type * as App from \"../App.ts\";\n\n/**\n * The app together with whether we are the ones who initialized it.\n *\n * @internal\n */\nexport interface Initialized {\n  readonly app: App.App;\n  readonly owned: boolean;\n}\n\n/** @internal */\nexport const initialize = (options: Client.FirebaseOptions, name?: string): Initialized => {\n  // An app that is already registered under this name was initialized by\n  // somebody else, so ending its lifecycle is not ours to do. `initializeApp`\n  // still throws when that app was configured differently, so conflicting\n  // configuration is not swallowed here.\n  const owned = !Client.getApps().some((app) => app.name === (name ?? defaultAppName));\n  return { app: Client.initializeApp(options, name), owned };\n};\n\n/** @internal */\nexport const release = ({ app, owned }: Initialized): Effect.Effect<void> =>\n  owned\n    ? Effect.tryPromise(() => Client.deleteApp(app)).pipe(\n        Effect.ignore({\n          log: \"Warn\",\n          message: `Failed to delete the Firebase client SDK app \"${app.name}\"`,\n        }),\n      )\n    : Effect.void;\n"],"mappings":";;;;;AAgBA,MAAa,cAAc,SAAiC,SAA+B;CAKzF,MAAM,QAAQ,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,QAAQ,IAAI,UAAU,QAAQ,eAAe;CACnF,OAAO;EAAE,KAAK,OAAO,cAAc,SAAS,IAAI;EAAG;CAAM;AAC3D;;AAGA,MAAa,WAAW,EAAE,KAAK,YAC7B,QACI,OAAO,iBAAiB,OAAO,UAAU,GAAG,CAAC,CAAC,CAAC,KAC7C,OAAO,OAAO;CACZ,KAAK;CACL,SAAS,iDAAiD,IAAI,KAAK;AACrE,CAAC,CACH,IACA,OAAO"}

package/dist/firestore/ClientDocumentSnapshot.d.mts

@@ -0,0 +1,106 @@
+import * as DocumentSnapshot from "@visiolab/effect-firebase/firestore/DocumentSnapshot";
+import * as Collection from "@visiolab/effect-firebase/firestore/Collection";
+declare namespace ClientDocumentSnapshot_d_exports {
+  export { ClientDocumentSnapshot, Existing, Missing, SnapshotMetadata, existing, make, missing };
+}
+/**
+ * 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 declare const make: <C extends Collection.Any>(ref: Collection.DocumentReference<C>, data: unknown, metadata: SnapshotMetadata) => ClientDocumentSnapshot<C>;
+/**
+ * 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 declare const existing: <C extends Collection.Any>(ref: Collection.DocumentReference<C>, data: unknown, metadata: SnapshotMetadata) => Existing<C>;
+/**
+ * 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 declare const missing: <C extends Collection.Any>(ref: Collection.DocumentReference<C>, metadata: SnapshotMetadata) => Missing<C>;
+export { ClientDocumentSnapshot_d_exports };
+//# sourceMappingURL=ClientDocumentSnapshot.d.mts.map

package/dist/firestore/ClientDocumentSnapshot.mjs

@@ -0,0 +1,86 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { extraOf } from "./internal/snapshotMetadata.mjs";
+import * as DocumentSnapshot from "@visiolab/effect-firebase/firestore/DocumentSnapshot";
+// src/firestore/ClientDocumentSnapshot.ts
+/**
+* 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
+*/
+var ClientDocumentSnapshot_exports = /* @__PURE__ */ __exportAll({
+	existing: () => existing,
+	make: () => make,
+	missing: () => missing
+});
+/**
+* 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
+*/
+const make = (ref, data, metadata) => DocumentSnapshot.make(ref, data, 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
+*/
+const existing = (ref, data, metadata) => DocumentSnapshot.existing(ref, data, 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
+*/
+const missing = (ref, metadata) => DocumentSnapshot.missing(ref, extraOf(metadata));
+export { ClientDocumentSnapshot_exports, existing, make, missing };
+
+//# sourceMappingURL=ClientDocumentSnapshot.mjs.map

package/dist/firestore/ClientDocumentSnapshot.mjs.map

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