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

package/dist/firestore/ClientFirestore.d.mts

@@ -0,0 +1,331 @@
+import { App } from "../app/App.mjs";
+import { SnapshotMetadata } from "./ClientDocumentSnapshot.mjs";
+import { Context, Effect, Layer } from "effect";
+import { Firestore, With } from "@visiolab/effect-firebase/firestore/Firestore";
+import { Firestore as Firestore$1, FirestoreLocalCache } from "firebase/firestore";
+declare namespace ClientFirestore_d_exports {
+  export { ClientFirestore, Emulator, ListenOptions, Options, ReadOptions, ReadSource, layer, make };
+}
+declare const TypeId = "~@visiolab/effect-firebase-client/firestore/ClientFirestore";
+/**
+ * The portable {@link Firestore}, plus what only the client SDK can do.
+ *
+ * **When to use**
+ *
+ * Ask for it where code needs the client SDK: a read from the server or the
+ * cache alone, metadata changes on a listen, a snapshot's
+ * {@link ClientDocumentSnapshot.SnapshotMetadata}, or the SDK itself through
+ * {@link ClientFirestore.instance}. Everywhere else ask for {@link Firestore},
+ * so the code also runs on the Admin SDK.
+ *
+ * **Details**
+ *
+ * Its reads take {@link ReadOptions} and its listens {@link ListenOptions}.
+ * Every document snapshot, each document of a query snapshot, and each query
+ * snapshot as a whole carries the `metadata` of its read, as a
+ * {@link ClientDocumentSnapshot.ClientDocumentSnapshot} or
+ * {@link ClientQuerySnapshot.ClientQuerySnapshot} does.
+ *
+ * The service its key holds is also a {@link Firestore}, so it can be handed
+ * to code that expects one as it is. The type itself only extends
+ * {@link Firestore.With}, so providing a {@link Firestore} alone, such as an
+ * in-memory fake, does not satisfy code that asks for it. Its
+ * transactions are the portable {@link Firestore.Transaction}: the client SDK's
+ * transactions read one document at a time.
+ *
+ * The client SDK cannot abort a request in flight, so interrupting a call does
+ * not stop it: the request still runs to completion.
+ *
+ * @see {@link Firestore.With} for each read and write it offers
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface ClientFirestore extends With<ReadOptions, ListenOptions, {
+  readonly metadata: SnapshotMetadata;
+}> {
+  readonly [TypeId]: typeof TypeId;
+  /**
+   * The client SDK's own `Firestore`, for the database the service was opened
+   * on.
+   *
+   * **When to use**
+   *
+   * Use for what this service does not wrap, such as queries or
+   * `disableNetwork` and `enableNetwork`. Prefer the service's own methods
+   * where one exists.
+   *
+   * **Details**
+   *
+   * Calls through it skip the collection's model, take and return the SDK's
+   * own values, and throw the SDK's own errors. To write a model through it,
+   * encode with {@link FirestoreValue.toCodecFirestore} and map with
+   * {@link ClientFirestoreValue.toClient}.
+   *
+   * @see {@link ClientFirestoreValue} for mapping between the SDK's values and Firestore Values
+   */
+  readonly instance: Firestore$1;
+}
+/**
+ * How `streamDoc` and `streamDocs` on {@link ClientFirestore} listen, named as
+ * in the client SDK's own listen options.
+ *
+ * **When to use**
+ *
+ * Use to also hear metadata changes, such as a pending write being
+ * acknowledged, or to listen to the local cache alone. Left out, a listen
+ * behaves as the SDK's does by default: it emits only when the data changes.
+ *
+ * **Details**
+ *
+ * Every snapshot a listen emits carries the
+ * {@link ClientDocumentSnapshot.SnapshotMetadata} it arrived with. The portable
+ * {@link Firestore.With.streamDoc} takes no options, because the Admin SDK's
+ * listeners take none.
+ *
+ * @example Waiting for the server to acknowledge a write
+ * ```ts
+ * import { Effect, Schema, Stream } from "effect";
+ * import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+ * import { ClientFirestore } from "@visiolab/effect-firebase-client/firestore";
+ *
+ * class Post extends FirestoreModel.Class<Post>("Post")({
+ *   title: Schema.String,
+ * }) {}
+ *
+ * const Posts = Collection.make("posts", Post);
+ * const hello = Posts.doc(Posts.id.make("hello"));
+ *
+ * const acknowledged = Effect.gen(function* () {
+ *   const firestore = yield* ClientFirestore.ClientFirestore;
+ *   yield* firestore.streamDoc(hello, { includeMetadataChanges: true }).pipe(
+ *     Stream.filter((snapshot) => !snapshot.metadata.hasPendingWrites),
+ *     Stream.runHead,
+ *   );
+ * });
+ * ```
+ *
+ * @see {@link ReadOptions} for the options of a one-off read
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface ListenOptions {
+  /**
+   * Whether to also emit when only the
+   * {@link ClientDocumentSnapshot.SnapshotMetadata} changes, such as when the
+   * server acknowledges a pending write or the cache catches up with the
+   * server. Without it, a listen only emits when the data changes.
+   */
+  readonly includeMetadataChanges?: boolean | undefined;
+  /**
+   * Where to listen. `"default"` listens to the server and the local cache.
+   * `"cache"` listens to the local cache alone and never reaches the server, so
+   * it only sees what this client has written or already read.
+   */
+  readonly source?: "default" | "cache" | undefined;
+}
+/**
+ * Service key for {@link ClientFirestore}.
+ *
+ * @see {@link Firestore} for the portable key, which {@link layer} provides the same service under
+ *
+ * @stability unstable
+ * @category services
+ * @since 0.1.0
+ */
+export declare const ClientFirestore: Context.Service<ClientFirestore, ClientFirestore & Firestore>;
+/**
+ * Where a one-off read is served from.
+ *
+ * - `"default"`: the server when it can be reached, otherwise the local cache.
+ *   What a read does when no source is given.
+ * - `"server"`: the server alone. Fails with the SDK's code when the server
+ *   cannot be reached, instead of falling back to the cache.
+ * - `"cache"`: the local cache alone, without asking the server.
+ *
+ * The two reads report what the cache lacks differently, as the SDK does. A
+ * cached `getDoc` of a document the cache has never seen fails with a
+ * {@link Firestore.FirestoreError} whose code is `unavailable`, and one the
+ * cache knows was deleted reads as `Missing`. A cached `getDocs` never fails
+ * for what the cache lacks: it returns whatever the cache holds, which may be
+ * nothing, with `fromCache: true`.
+ *
+ * @see {@link ReadOptions} for passing it to a read
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type ReadSource = "default" | "server" | "cache";
+/**
+ * How `getDoc` and `getDocs` on {@link ClientFirestore} read a document, a
+ * collection, or a Collection Group.
+ *
+ * **When to use**
+ *
+ * Use to read from the server alone, such as to confirm a value before acting
+ * on it, or from the local cache alone, such as to render at once while
+ * offline. Left out, a read behaves as the SDK's does by default.
+ *
+ * **Details**
+ *
+ * With `source: "cache"`, a `getDoc` of a document the cache has never seen
+ * fails with a {@link Firestore.FirestoreError} whose code is `unavailable`:
+ * not being cached is not the same as not existing. One the cache knows was
+ * deleted reads as `Missing`. A `getDocs` never fails for what the cache lacks:
+ * it returns whatever the cache holds, which may be nothing, with `fromCache:
+ * true`. So, unlike `getDoc`, an empty result cannot tell "nothing cached" from
+ * "nothing there".
+ *
+ * The portable {@link Firestore.With.getDoc} takes no options, because the
+ * Admin SDK's reads take none.
+ *
+ * @example Reading from the server alone
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+ * import { ClientFirestore } from "@visiolab/effect-firebase-client/firestore";
+ *
+ * class Post extends FirestoreModel.Class<Post>("Post")({
+ *   title: Schema.String,
+ * }) {}
+ *
+ * const Posts = Collection.make("posts", Post);
+ *
+ * const fresh = Effect.gen(function* () {
+ *   const firestore = yield* ClientFirestore.ClientFirestore;
+ *   return yield* firestore.getDoc(Posts.doc(Posts.id.make("hello")), { source: "server" });
+ * });
+ * ```
+ *
+ * @see {@link ReadSource} for where a read can be served from
+ * @see {@link ListenOptions} for the options of a listen
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface ReadOptions {
+  /**
+   * Where the read is served from. Left out, it is `"default"`.
+   *
+   * @see {@link ReadSource} for each source, and what a cached read does with what the cache lacks
+   */
+  readonly source?: ReadSource | undefined;
+}
+/**
+ * Where the Firestore emulator listens, such as `{ host: "127.0.0.1", port:
+ * 8080 }`.
+ *
+ * @see {@link Options.emulator} for connecting to it
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface Emulator {
+  readonly host: string;
+  readonly port: number;
+}
+/**
+ * How {@link layer} opens a database. All of them are fixed once the database
+ * is open.
+ *
+ * @see {@link AdminFirestore.Options} for the Admin SDK's, which read the emulator from the environment
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options {
+  /**
+   * The database to open, where the project has more than its default one.
+   * Leave it out for the default database.
+   */
+  readonly databaseId?: string | undefined;
+  /**
+   * The emulator to talk to instead of the project's database.
+   *
+   * Unlike the Admin SDK, the client SDK takes the emulator per database, not
+   * from the environment, and only before the database is first used.
+   */
+  readonly emulator?: Emulator | undefined;
+  /**
+   * Where the SDK keeps the documents it has seen and the writes it has yet to
+   * send: `memoryLocalCache()`, the SDK's default, or `persistentLocalCache()`,
+   * which keeps them in IndexedDB across reloads.
+   */
+  readonly localCache?: FirestoreLocalCache | undefined;
+}
+/**
+ * Builds {@link ClientFirestore} on the {@link App.App} in context.
+ *
+ * **When to use**
+ *
+ * Use to build the service inside an effect of your own. Most programs provide
+ * it with {@link layer} instead, which also provides it as {@link Firestore}.
+ *
+ * **Details**
+ *
+ * Building the service cannot fail. Opening a database only throws for an app
+ * that was already deleted, or a database already opened or used with other
+ * settings. Both are wiring mistakes, so they are defects, and a
+ * {@link Firestore.FirestoreError} only ever means that a call failed.
+ *
+ * A write only succeeds once the server acknowledges it, so a write made
+ * offline waits for the connection. It is applied to the local cache at once
+ * and sent when it can be: interrupting the write, or timing it out, does not
+ * take it back.
+ *
+ * A server timestamp the server has not settled yet reads as the local clock's
+ * estimate, so the field decodes as a timestamp.
+ *
+ * @see {@link layer} for the same as a layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: (options?: Options) => Effect.Effect<ClientFirestore & Firestore, never, App>;
+/**
+ * A layer that provides {@link ClientFirestore} for the {@link App.App} in
+ * context, and the same service as the portable {@link Firestore}.
+ *
+ * **When to use**
+ *
+ * Use in a browser, or anywhere the client SDK runs. On a server, use
+ * {@link AdminFirestore.layer} instead.
+ *
+ * **Details**
+ *
+ * With no options it opens the project's default database with the SDK's
+ * defaults.
+ *
+ * @example Providing Firestore with a persistent cache
+ * ```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>" })),
+ * );
+ * ```
+ *
+ * @see {@link make} for why building the service cannot fail
+ * @see {@link AdminFirestore.layer} for the Admin SDK's layer, for servers
+ *
+ * @stability unstable
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: (options?: Options) => Layer.Layer<ClientFirestore | Firestore, never, App>;
+export { ClientFirestore_d_exports };
+//# sourceMappingURL=ClientFirestore.d.mts.map

package/dist/firestore/ClientFirestore.mjs

@@ -0,0 +1,146 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { fromDatabase, openDatabase } from "./internal/firestore.mjs";
+import { Context, Effect, Layer } from "effect";
+import { Firestore } from "@visiolab/effect-firebase/firestore/Firestore";
+// src/firestore/ClientFirestore.ts
+/**
+* Firestore on the Firebase client SDK, for browsers.
+*
+* {@link layer} provides one service under two keys: the portable
+* {@link Firestore}, which code that runs on either SDK asks for, and
+* {@link ClientFirestore}, which adds what only the client SDK can do: read
+* sources, listen options, and the
+* {@link ClientDocumentSnapshot.SnapshotMetadata} of every read. Both reach the
+* same database.
+*
+* Where it behaves differently from the Admin SDK:
+*
+* - The emulator is a layer option, not an environment variable.
+* - A write only succeeds once the server acknowledges it, so a write made
+*   offline waits for the connection. It is applied to the local cache at once
+*   and sent when it can be; interrupting the write does not take it back.
+* - A pending server timestamp reads as the local clock's estimate, not `null`,
+*   so it decodes as a timestamp before the server has settled it.
+* - Error codes are always named, such as `permission-denied`.
+*
+* @example Reading a document, and where the read came from
+* ```ts
+* import { Effect, Layer, Schema } from "effect";
+* import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { App } from "@visiolab/effect-firebase-client/app";
+* import { ClientFirestore } from "@visiolab/effect-firebase-client/firestore";
+*
+* class Post extends FirestoreModel.Class<Post>("Post")({
+*   title: Schema.String,
+* }) {}
+*
+* const Posts = Collection.make("posts", Post);
+*
+* const program = Effect.gen(function* () {
+*   const firestore = yield* ClientFirestore.ClientFirestore;
+*   const snapshot = yield* firestore.getDoc(Posts.doc(Posts.id.make("hello")));
+*   yield* Effect.log(snapshot.metadata.fromCache ? "from the cache" : "from the server");
+* });
+*
+* const FirestoreLive = ClientFirestore.layer().pipe(
+*   Layer.provide(App.layer({ apiKey: "<api key>", projectId: "my-project", appId: "<app id>" })),
+* );
+*
+* program.pipe(Effect.provide(FirestoreLive));
+* ```
+*
+* @see {@link AdminFirestore} for the same service on the Admin SDK, for servers
+*
+* @stability unstable
+* @since 0.1.0
+*/
+var ClientFirestore_exports = /* @__PURE__ */ __exportAll({
+	ClientFirestore: () => ClientFirestore,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* Service key for {@link ClientFirestore}.
+*
+* @see {@link Firestore} for the portable key, which {@link layer} provides the same service under
+*
+* @stability unstable
+* @category services
+* @since 0.1.0
+*/
+const ClientFirestore = Context.Service("@visiolab/effect-firebase-client/firestore/ClientFirestore");
+/**
+* Builds {@link ClientFirestore} on the {@link App.App} in context.
+*
+* **When to use**
+*
+* Use to build the service inside an effect of your own. Most programs provide
+* it with {@link layer} instead, which also provides it as {@link Firestore}.
+*
+* **Details**
+*
+* Building the service cannot fail. Opening a database only throws for an app
+* that was already deleted, or a database already opened or used with other
+* settings. Both are wiring mistakes, so they are defects, and a
+* {@link Firestore.FirestoreError} only ever means that a call failed.
+*
+* A write only succeeds once the server acknowledges it, so a write made
+* offline waits for the connection. It is applied to the local cache at once
+* and sent when it can be: interrupting the write, or timing it out, does not
+* take it back.
+*
+* A server timestamp the server has not settled yet reads as the local clock's
+* estimate, so the field decodes as a timestamp.
+*
+* @see {@link layer} for the same as a layer
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const make = Effect.fn("ClientFirestore.make")(function* (options) {
+	const firestore = yield* openDatabase(options);
+	return fromDatabase(firestore);
+});
+/** The one service, under both its own tag and the portable one. */
+const both = (service) => Context.make(ClientFirestore, service).pipe(Context.add(Firestore, service));
+/**
+* A layer that provides {@link ClientFirestore} for the {@link App.App} in
+* context, and the same service as the portable {@link Firestore}.
+*
+* **When to use**
+*
+* Use in a browser, or anywhere the client SDK runs. On a server, use
+* {@link AdminFirestore.layer} instead.
+*
+* **Details**
+*
+* With no options it opens the project's default database with the SDK's
+* defaults.
+*
+* @example Providing Firestore with a persistent cache
+* ```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>" })),
+* );
+* ```
+*
+* @see {@link make} for why building the service cannot fail
+* @see {@link AdminFirestore.layer} for the Admin SDK's layer, for servers
+*
+* @stability unstable
+* @category layers
+* @since 0.1.0
+*/
+const layer = (options) => Layer.effectContext(Effect.map(make(options), both));
+export { ClientFirestore, ClientFirestore_exports, layer, make };
+
+//# sourceMappingURL=ClientFirestore.mjs.map

package/dist/firestore/ClientFirestore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientFirestore.mjs","names":["internalFirestore.openDatabase","internalFirestore.fromDatabase"],"sources":["../../src/firestore/ClientFirestore.ts"],"sourcesContent":["/**\n * Firestore on the Firebase client SDK, for browsers.\n *\n * {@link layer} provides one service under two keys: the portable\n * {@link Firestore}, which code that runs on either SDK asks for, and\n * {@link ClientFirestore}, which adds what only the client SDK can do: read\n * sources, listen options, and the\n * {@link ClientDocumentSnapshot.SnapshotMetadata} of every read. Both reach the\n * same database.\n *\n * Where it behaves differently from the Admin SDK:\n *\n * - The emulator is a layer option, not an environment variable.\n * - A write only succeeds once the server acknowledges it, so a write made\n *   offline waits for the connection. It is applied to the local cache at once\n *   and sent when it can be; interrupting the write does not take it back.\n * - A pending server timestamp reads as the local clock's estimate, not `null`,\n *   so it decodes as a timestamp before the server has settled it.\n * - Error codes are always named, such as `permission-denied`.\n *\n * @example Reading a document, and where the read came from\n * ```ts\n * import { Effect, Layer, Schema } from \"effect\";\n * import { Collection, FirestoreModel } from \"@visiolab/effect-firebase/firestore\";\n * import { App } from \"@visiolab/effect-firebase-client/app\";\n * import { ClientFirestore } from \"@visiolab/effect-firebase-client/firestore\";\n *\n * class Post extends FirestoreModel.Class<Post>(\"Post\")({\n *   title: Schema.String,\n * }) {}\n *\n * const Posts = Collection.make(\"posts\", Post);\n *\n * const program = Effect.gen(function* () {\n *   const firestore = yield* ClientFirestore.ClientFirestore;\n *   const snapshot = yield* firestore.getDoc(Posts.doc(Posts.id.make(\"hello\")));\n *   yield* Effect.log(snapshot.metadata.fromCache ? \"from the cache\" : \"from the server\");\n * });\n *\n * const FirestoreLive = ClientFirestore.layer().pipe(\n *   Layer.provide(App.layer({ apiKey: \"<api key>\", projectId: \"my-project\", appId: \"<app id>\" })),\n * );\n *\n * program.pipe(Effect.provide(FirestoreLive));\n * ```\n *\n * @see {@link AdminFirestore} for the same service on the Admin SDK, for servers\n *\n * @stability unstable\n * @since 0.1.0\n */\nimport { Context, Effect, Layer } from \"effect\";\nimport { Firestore, type With } from \"@visiolab/effect-firebase/firestore/Firestore\";\nimport type { Firestore as SdkFirestore, FirestoreLocalCache } from \"firebase/firestore\";\nimport type * as App from \"../app/App.ts\";\nimport type * as ClientDocumentSnapshot from \"./ClientDocumentSnapshot.ts\";\n// Only {@link ClientFirestore}'s documentation links to it.\n// oxlint-disable-next-line no-unused-vars\nimport type * as ClientQuerySnapshot from \"./ClientQuerySnapshot.ts\";\nimport * as internalFirestore from \"./internal/firestore.ts\";\n\nconst TypeId = internalFirestore.TypeId;\n\n/**\n * The portable {@link Firestore}, plus what only the client SDK can do.\n *\n * **When to use**\n *\n * Ask for it where code needs the client SDK: a read from the server or the\n * cache alone, metadata changes on a listen, a snapshot's\n * {@link ClientDocumentSnapshot.SnapshotMetadata}, or the SDK itself through\n * {@link ClientFirestore.instance}. Everywhere else ask for {@link Firestore},\n * so the code also runs on the Admin SDK.\n *\n * **Details**\n *\n * Its reads take {@link ReadOptions} and its listens {@link ListenOptions}.\n * Every document snapshot, each document of a query snapshot, and each query\n * snapshot as a whole carries the `metadata` of its read, as a\n * {@link ClientDocumentSnapshot.ClientDocumentSnapshot} or\n * {@link ClientQuerySnapshot.ClientQuerySnapshot} does.\n *\n * The service its key holds is also a {@link Firestore}, so it can be handed\n * to code that expects one as it is. The type itself only extends\n * {@link Firestore.With}, so providing a {@link Firestore} alone, such as an\n * in-memory fake, does not satisfy code that asks for it. Its\n * transactions are the portable {@link Firestore.Transaction}: the client SDK's\n * transactions read one document at a time.\n *\n * The client SDK cannot abort a request in flight, so interrupting a call does\n * not stop it: the request still runs to completion.\n *\n * @see {@link Firestore.With} for each read and write it offers\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface ClientFirestore extends With<\n  ReadOptions,\n  ListenOptions,\n  { readonly metadata: ClientDocumentSnapshot.SnapshotMetadata }\n> {\n  readonly [TypeId]: typeof TypeId;\n\n  /**\n   * The client SDK's own `Firestore`, for the database the service was opened\n   * on.\n   *\n   * **When to use**\n   *\n   * Use for what this service does not wrap, such as queries or\n   * `disableNetwork` and `enableNetwork`. Prefer the service's own methods\n   * where one exists.\n   *\n   * **Details**\n   *\n   * Calls through it skip the collection's model, take and return the SDK's\n   * own values, and throw the SDK's own errors. To write a model through it,\n   * encode with {@link FirestoreValue.toCodecFirestore} and map with\n   * {@link ClientFirestoreValue.toClient}.\n   *\n   * @see {@link ClientFirestoreValue} for mapping between the SDK's values and Firestore Values\n   */\n  readonly instance: SdkFirestore;\n}\n\n/**\n * How `streamDoc` and `streamDocs` on {@link ClientFirestore} listen, named as\n * in the client SDK's own listen options.\n *\n * **When to use**\n *\n * Use to also hear metadata changes, such as a pending write being\n * acknowledged, or to listen to the local cache alone. Left out, a listen\n * behaves as the SDK's does by default: it emits only when the data changes.\n *\n * **Details**\n *\n * Every snapshot a listen emits carries the\n * {@link ClientDocumentSnapshot.SnapshotMetadata} it arrived with. The portable\n * {@link Firestore.With.streamDoc} takes no options, because the Admin SDK's\n * listeners take none.\n *\n * @example Waiting for the server to acknowledge a write\n * ```ts\n * import { Effect, Schema, Stream } from \"effect\";\n * import { Collection, FirestoreModel } from \"@visiolab/effect-firebase/firestore\";\n * import { ClientFirestore } from \"@visiolab/effect-firebase-client/firestore\";\n *\n * class Post extends FirestoreModel.Class<Post>(\"Post\")({\n *   title: Schema.String,\n * }) {}\n *\n * const Posts = Collection.make(\"posts\", Post);\n * const hello = Posts.doc(Posts.id.make(\"hello\"));\n *\n * const acknowledged = Effect.gen(function* () {\n *   const firestore = yield* ClientFirestore.ClientFirestore;\n *   yield* firestore.streamDoc(hello, { includeMetadataChanges: true }).pipe(\n *     Stream.filter((snapshot) => !snapshot.metadata.hasPendingWrites),\n *     Stream.runHead,\n *   );\n * });\n * ```\n *\n * @see {@link ReadOptions} for the options of a one-off read\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface ListenOptions {\n  /**\n   * Whether to also emit when only the\n   * {@link ClientDocumentSnapshot.SnapshotMetadata} changes, such as when the\n   * server acknowledges a pending write or the cache catches up with the\n   * server. Without it, a listen only emits when the data changes.\n   */\n  readonly includeMetadataChanges?: boolean | undefined;\n  /**\n   * Where to listen. `\"default\"` listens to the server and the local cache.\n   * `\"cache\"` listens to the local cache alone and never reaches the server, so\n   * it only sees what this client has written or already read.\n   */\n  readonly source?: \"default\" | \"cache\" | undefined;\n}\n\n/**\n * Service key for {@link ClientFirestore}.\n *\n * @see {@link Firestore} for the portable key, which {@link layer} provides the same service under\n *\n * @stability unstable\n * @category services\n * @since 0.1.0\n */\nexport const ClientFirestore = Context.Service<ClientFirestore, ClientFirestore & Firestore>(\n  \"@visiolab/effect-firebase-client/firestore/ClientFirestore\",\n);\n\n/**\n * Where a one-off read is served from.\n *\n * - `\"default\"`: the server when it can be reached, otherwise the local cache.\n *   What a read does when no source is given.\n * - `\"server\"`: the server alone. Fails with the SDK's code when the server\n *   cannot be reached, instead of falling back to the cache.\n * - `\"cache\"`: the local cache alone, without asking the server.\n *\n * The two reads report what the cache lacks differently, as the SDK does. A\n * cached `getDoc` of a document the cache has never seen fails with a\n * {@link Firestore.FirestoreError} whose code is `unavailable`, and one the\n * cache knows was deleted reads as `Missing`. A cached `getDocs` never fails\n * for what the cache lacks: it returns whatever the cache holds, which may be\n * nothing, with `fromCache: true`.\n *\n * @see {@link ReadOptions} for passing it to a read\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport type ReadSource = \"default\" | \"server\" | \"cache\";\n\n/**\n * How `getDoc` and `getDocs` on {@link ClientFirestore} read a document, a\n * collection, or a Collection Group.\n *\n * **When to use**\n *\n * Use to read from the server alone, such as to confirm a value before acting\n * on it, or from the local cache alone, such as to render at once while\n * offline. Left out, a read behaves as the SDK's does by default.\n *\n * **Details**\n *\n * With `source: \"cache\"`, a `getDoc` of a document the cache has never seen\n * fails with a {@link Firestore.FirestoreError} whose code is `unavailable`:\n * not being cached is not the same as not existing. One the cache knows was\n * deleted reads as `Missing`. A `getDocs` never fails for what the cache lacks:\n * it returns whatever the cache holds, which may be nothing, with `fromCache:\n * true`. So, unlike `getDoc`, an empty result cannot tell \"nothing cached\" from\n * \"nothing there\".\n *\n * The portable {@link Firestore.With.getDoc} takes no options, because the\n * Admin SDK's reads take none.\n *\n * @example Reading from the server alone\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 Post extends FirestoreModel.Class<Post>(\"Post\")({\n *   title: Schema.String,\n * }) {}\n *\n * const Posts = Collection.make(\"posts\", Post);\n *\n * const fresh = Effect.gen(function* () {\n *   const firestore = yield* ClientFirestore.ClientFirestore;\n *   return yield* firestore.getDoc(Posts.doc(Posts.id.make(\"hello\")), { source: \"server\" });\n * });\n * ```\n *\n * @see {@link ReadSource} for where a read can be served from\n * @see {@link ListenOptions} for the options of a listen\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface ReadOptions {\n  /**\n   * Where the read is served from. Left out, it is `\"default\"`.\n   *\n   * @see {@link ReadSource} for each source, and what a cached read does with what the cache lacks\n   */\n  readonly source?: ReadSource | undefined;\n}\n\n/**\n * Where the Firestore emulator listens, such as `{ host: \"127.0.0.1\", port:\n * 8080 }`.\n *\n * @see {@link Options.emulator} for connecting to it\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface Emulator {\n  readonly host: string;\n  readonly port: number;\n}\n\n/**\n * How {@link layer} opens a database. All of them are fixed once the database\n * is open.\n *\n * @see {@link AdminFirestore.Options} for the Admin SDK's, which read the emulator from the environment\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface Options {\n  /**\n   * The database to open, where the project has more than its default one.\n   * Leave it out for the default database.\n   */\n  readonly databaseId?: string | undefined;\n  /**\n   * The emulator to talk to instead of the project's database.\n   *\n   * Unlike the Admin SDK, the client SDK takes the emulator per database, not\n   * from the environment, and only before the database is first used.\n   */\n  readonly emulator?: Emulator | undefined;\n  /**\n   * Where the SDK keeps the documents it has seen and the writes it has yet to\n   * send: `memoryLocalCache()`, the SDK's default, or `persistentLocalCache()`,\n   * which keeps them in IndexedDB across reloads.\n   */\n  readonly localCache?: FirestoreLocalCache | undefined;\n}\n\n/**\n * Builds {@link ClientFirestore} on the {@link App.App} in context.\n *\n * **When to use**\n *\n * Use to build the service inside an effect of your own. Most programs provide\n * it with {@link layer} instead, which also provides it as {@link Firestore}.\n *\n * **Details**\n *\n * Building the service cannot fail. Opening a database only throws for an app\n * that was already deleted, or a database already opened or used with other\n * settings. Both are wiring mistakes, so they are defects, and a\n * {@link Firestore.FirestoreError} only ever means that a call failed.\n *\n * A write only succeeds once the server acknowledges it, so a write made\n * offline waits for the connection. It is applied to the local cache at once\n * and sent when it can be: interrupting the write, or timing it out, does not\n * take it back.\n *\n * A server timestamp the server has not settled yet reads as the local clock's\n * estimate, so the field decodes as a timestamp.\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: (\n  options?: Options,\n) => Effect.Effect<ClientFirestore & Firestore, never, App.App> = Effect.fn(\"ClientFirestore.make\")(\n  function* (options?: Options) {\n    const firestore = yield* internalFirestore.openDatabase(options);\n    return internalFirestore.fromDatabase(firestore);\n  },\n);\n\n/** The one service, under both its own tag and the portable one. */\nconst both = (service: ClientFirestore & Firestore) =>\n  Context.make(ClientFirestore, service).pipe(Context.add(Firestore, service));\n\n/**\n * A layer that provides {@link ClientFirestore} for the {@link App.App} in\n * context, and the same service as the portable {@link Firestore}.\n *\n * **When to use**\n *\n * Use in a browser, or anywhere the client SDK runs. On a server, use\n * {@link AdminFirestore.layer} instead.\n *\n * **Details**\n *\n * With no options it opens the project's default database with the SDK's\n * defaults.\n *\n * @example Providing Firestore with a persistent cache\n * ```ts\n * import { Layer } from \"effect\";\n * import { persistentLocalCache } from \"firebase/firestore\";\n * import { App } from \"@visiolab/effect-firebase-client/app\";\n * import { ClientFirestore } from \"@visiolab/effect-firebase-client/firestore\";\n *\n * const FirestoreLive = ClientFirestore.layer({\n *   localCache: persistentLocalCache(),\n *   emulator: import.meta.env.DEV ? { host: \"127.0.0.1\", port: 8080 } : undefined,\n * }).pipe(\n *   Layer.provide(App.layer({ apiKey: \"<api key>\", projectId: \"my-project\", appId: \"<app id>\" })),\n * );\n * ```\n *\n * @see {@link make} for why building the service cannot fail\n * @see {@link AdminFirestore.layer} for the Admin SDK's layer, for servers\n *\n * @stability unstable\n * @category layers\n * @since 0.1.0\n */\nexport const layer = (\n  options?: Options,\n): Layer.Layer<ClientFirestore | Firestore, never, App.App> =>\n  Layer.effectContext(Effect.map(make(options), both));\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqMA,MAAa,kBAAkB,QAAQ,QACrC,4DACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8JA,MAAa,OAEqD,OAAO,GAAG,sBAAsB,CAAC,CACjG,WAAW,SAAmB;CAC5B,MAAM,YAAY,OAAOA,aAA+B,OAAO;CAC/D,OAAOC,aAA+B,SAAS;AACjD,CACF;;AAGA,MAAM,QAAQ,YACZ,QAAQ,KAAK,iBAAiB,OAAO,CAAC,CAAC,KAAK,QAAQ,IAAI,WAAW,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsC7E,MAAa,SACX,YAEA,MAAM,cAAc,OAAO,IAAI,KAAK,OAAO,GAAG,IAAI,CAAC"}

package/dist/firestore/ClientFirestoreValue.d.mts

@@ -0,0 +1,61 @@
+import { Result } from "effect";
+import { FirestoreError } from "@visiolab/effect-firebase/firestore/Firestore";
+import { Firestore as Firestore$1 } from "firebase/firestore";
+import { FirestoreValue } from "@visiolab/effect-firebase/firestore/FirestoreValue";
+declare namespace ClientFirestoreValue_d_exports {
+  export { fromClient, toClient };
+}
+/**
+ * Turns a Firestore Value into the value the client SDK writes into
+ * `firestore`.
+ *
+ * **When to use**
+ *
+ * Use to write what a model encodes to through the client SDK itself.
+ *
+ * **Details**
+ *
+ * The portable `Timestamp`, `GeoPoint` and bytes become the SDK's `Timestamp`,
+ * `GeoPoint` and `Bytes`, and the sentinels its `FieldValue`s. A `DocumentPath`
+ * becomes `doc(firestore, path)`, so it points into that database. Map keys are
+ * kept as they are, so the dotted field paths of an update stay field paths.
+ *
+ * It throws for anything that is not a Firestore Value, such as one of the
+ * client SDK's own values or a class instance cast past the type. What
+ * {@link FirestoreValue.toCodecFirestore} encodes is always a Firestore Value.
+ *
+ * @see {@link fromClient} for the other direction
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.3.0
+ */
+export declare const toClient: (value: FirestoreValue, firestore: Firestore$1) => unknown;
+/**
+ * Turns a value the client SDK read into a Firestore Value.
+ *
+ * **When to use**
+ *
+ * Use to decode what the client SDK itself read through a model, with
+ * {@link FirestoreValue.toCodecFirestore}.
+ *
+ * **Details**
+ *
+ * The SDK's `Timestamp`, `GeoPoint` and `Bytes` become the portable
+ * `Timestamp`, `GeoPoint` and `Uint8Array`. A `DocumentReference` becomes the
+ * `DocumentPath` it points at, since Firestore stores nothing else of it;
+ * {@link FirestoreSchema.DocumentReference} reads that back into the
+ * collection it names.
+ *
+ * Fails with a {@link Firestore.FirestoreError} naming the field for a value
+ * that is not a Firestore Value, such as a vector.
+ *
+ * @see {@link toClient} for the other direction
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.3.0
+ */
+export declare const fromClient: (value: unknown) => Result.Result<FirestoreValue, FirestoreError>;
+export { ClientFirestoreValue_d_exports };
+//# sourceMappingURL=ClientFirestoreValue.d.mts.map

package/dist/firestore/ClientFirestoreValue.mjs

@@ -0,0 +1,62 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { fromClient as fromClient$1, toClient as toClient$1 } from "./internal/firestoreValue.mjs";
+// src/firestore/ClientFirestoreValue.ts
+var ClientFirestoreValue_exports = /* @__PURE__ */ __exportAll({
+	fromClient: () => fromClient,
+	toClient: () => toClient
+});
+/**
+* Turns a Firestore Value into the value the client SDK writes into
+* `firestore`.
+*
+* **When to use**
+*
+* Use to write what a model encodes to through the client SDK itself.
+*
+* **Details**
+*
+* The portable `Timestamp`, `GeoPoint` and bytes become the SDK's `Timestamp`,
+* `GeoPoint` and `Bytes`, and the sentinels its `FieldValue`s. A `DocumentPath`
+* becomes `doc(firestore, path)`, so it points into that database. Map keys are
+* kept as they are, so the dotted field paths of an update stay field paths.
+*
+* It throws for anything that is not a Firestore Value, such as one of the
+* client SDK's own values or a class instance cast past the type. What
+* {@link FirestoreValue.toCodecFirestore} encodes is always a Firestore Value.
+*
+* @see {@link fromClient} for the other direction
+*
+* @stability unstable
+* @category conversions
+* @since 0.3.0
+*/
+const toClient = toClient$1;
+/**
+* Turns a value the client SDK read into a Firestore Value.
+*
+* **When to use**
+*
+* Use to decode what the client SDK itself read through a model, with
+* {@link FirestoreValue.toCodecFirestore}.
+*
+* **Details**
+*
+* The SDK's `Timestamp`, `GeoPoint` and `Bytes` become the portable
+* `Timestamp`, `GeoPoint` and `Uint8Array`. A `DocumentReference` becomes the
+* `DocumentPath` it points at, since Firestore stores nothing else of it;
+* {@link FirestoreSchema.DocumentReference} reads that back into the
+* collection it names.
+*
+* Fails with a {@link Firestore.FirestoreError} naming the field for a value
+* that is not a Firestore Value, such as a vector.
+*
+* @see {@link toClient} for the other direction
+*
+* @stability unstable
+* @category conversions
+* @since 0.3.0
+*/
+const fromClient = fromClient$1;
+export { ClientFirestoreValue_exports, fromClient, toClient };
+
+//# sourceMappingURL=ClientFirestoreValue.mjs.map

package/dist/firestore/ClientFirestoreValue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientFirestoreValue.mjs","names":["internal.toClient","internal.fromClient"],"sources":["../../src/firestore/ClientFirestoreValue.ts"],"sourcesContent":["/**\n * Maps between Firestore Values, the portable values a model encodes to, and\n * the values the client SDK reads and writes.\n *\n * {@link ClientFirestore} applies it on every read and write. Use it directly\n * to read or write a model through the client SDK itself, such as through\n * {@link ClientFirestore.instance}.\n *\n * @example Writing a model through the client SDK\n * ```ts\n * import { Schema } from \"effect\";\n * import { FirestoreModel, FirestoreValue } from \"@visiolab/effect-firebase/firestore\";\n * import { ClientFirestoreValue } from \"@visiolab/effect-firebase-client/firestore\";\n * import { type DocumentData, doc, getFirestore, setDoc } from \"firebase/firestore\";\n *\n * class Post extends FirestoreModel.Class<Post>(\"Post\")({\n *   title: Schema.String,\n * }) {}\n *\n * const firestore = getFirestore();\n * const encoded = Schema.encodeSync(FirestoreValue.toCodecFirestore(Post.create))({\n *   title: \"Hello\",\n * });\n * await setDoc(\n *   doc(firestore, \"posts/hello\"),\n *   ClientFirestoreValue.toClient(encoded, firestore) as DocumentData,\n * );\n * ```\n *\n * @see {@link AdminFirestoreValue} for the Admin SDK's mapping\n *\n * @stability unstable\n * @since 0.3.0\n */\nimport type { Result } from \"effect\";\nimport type { FirestoreError } from \"@visiolab/effect-firebase/firestore/Firestore\";\nimport type { FirestoreValue } from \"@visiolab/effect-firebase/firestore/FirestoreValue\";\nimport type { Firestore } from \"firebase/firestore\";\nimport * as internal from \"./internal/firestoreValue.ts\";\n\n/**\n * Turns a Firestore Value into the value the client SDK writes into\n * `firestore`.\n *\n * **When to use**\n *\n * Use to write what a model encodes to through the client SDK itself.\n *\n * **Details**\n *\n * The portable `Timestamp`, `GeoPoint` and bytes become the SDK's `Timestamp`,\n * `GeoPoint` and `Bytes`, and the sentinels its `FieldValue`s. A `DocumentPath`\n * becomes `doc(firestore, path)`, so it points into that database. Map keys are\n * kept as they are, so the dotted field paths of an update stay field paths.\n *\n * It throws for anything that is not a Firestore Value, such as one of the\n * client SDK's own values or a class instance cast past the type. What\n * {@link FirestoreValue.toCodecFirestore} encodes is always a Firestore Value.\n *\n * @see {@link fromClient} for the other direction\n *\n * @stability unstable\n * @category conversions\n * @since 0.3.0\n */\nexport const toClient: (value: FirestoreValue, firestore: Firestore) => unknown = internal.toClient;\n\n/**\n * Turns a value the client SDK read into a Firestore Value.\n *\n * **When to use**\n *\n * Use to decode what the client SDK itself read through a model, with\n * {@link FirestoreValue.toCodecFirestore}.\n *\n * **Details**\n *\n * The SDK's `Timestamp`, `GeoPoint` and `Bytes` become the portable\n * `Timestamp`, `GeoPoint` and `Uint8Array`. A `DocumentReference` becomes the\n * `DocumentPath` it points at, since Firestore stores nothing else of it;\n * {@link FirestoreSchema.DocumentReference} reads that back into the\n * collection it names.\n *\n * Fails with a {@link Firestore.FirestoreError} naming the field for a value\n * that is not a Firestore Value, such as a vector.\n *\n * @see {@link toClient} for the other direction\n *\n * @stability unstable\n * @category conversions\n * @since 0.3.0\n */\nexport const fromClient: (value: unknown) => Result.Result<FirestoreValue, FirestoreError> =\n  internal.fromClient;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,MAAa,WAAqEA;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BlF,MAAa,aACXC"}