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

package/dist/auth/Auth.mjs

@@ -0,0 +1,131 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { App } from "../app/App.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+import { FirebaseError } from "firebase-admin/app";
+import * as Admin from "firebase-admin/auth";
+// src/auth/Auth.ts
+/**
+* Firebase Authentication on the Admin SDK, as an Effect service.
+*
+* {@link Auth} wraps the calls server code uses most, such as verifying ID
+* tokens and managing users. Every call fails with an {@link AuthError}, and
+* {@link Auth.use} reaches the rest of the Admin SDK.
+*
+* @example Verifying an ID token
+* ```ts
+* import { Effect, Layer } from "effect";
+* import { App } from "@visiolab/effect-firebase-admin/app";
+* import { Auth } from "@visiolab/effect-firebase-admin/auth";
+*
+* const uidOf = (idToken: string) =>
+*   Effect.gen(function* () {
+*     const auth = yield* Auth.Auth;
+*     const token = yield* auth.verifyIdToken(idToken, true);
+*     return token.uid;
+*   });
+*
+* const AuthLive = Auth.layer.pipe(Layer.provide(App.layer()));
+*
+* uidOf("<id token>").pipe(Effect.provide(AuthLive));
+* ```
+*
+* @stability unstable
+* @since 0.1.0
+*/
+var Auth_exports = /* @__PURE__ */ __exportAll({
+	Auth: () => Auth,
+	AuthError: () => AuthError,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* Fails a call on {@link Auth} when the Admin SDK rejects it, with what it
+* threw as the `cause`.
+*
+* Match on `code` to tell failures apart, such as `auth/user-not-found` or
+* `auth/id-token-revoked`.
+*
+* @stability unstable
+* @category errors
+* @since 0.1.0
+*/
+var AuthError = class extends Schema.TaggedError()("AuthError", {
+	message: Schema.String,
+	/** The `service/string-code` the Admin SDK reported, such as `auth/user-not-found`. */
+	code: Schema.optional(Schema.String),
+	cause: Schema.optional(Schema.Defect())
+}) {};
+const authError = (message) => (cause) => new AuthError({
+	message,
+	code: cause instanceof FirebaseError ? cause.code : void 0,
+	cause
+});
+/**
+* Service key for Firebase Authentication.
+*
+* @stability unstable
+* @category services
+* @since 0.1.0
+*/
+const Auth = Context.Service("@visiolab/effect-firebase-admin/auth/Auth");
+/**
+* Builds {@link Auth} 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.
+*
+* **Details**
+*
+* Building the service cannot fail. `getAuth` only throws for an app that was
+* already deleted or is not an app at all. Both are wiring mistakes, so they
+* are defects, and {@link AuthError} only ever means that a call failed.
+*
+* @see {@link layer} for the same as a layer
+*
+* @stability unstable
+* @category constructors
+* @since 0.1.0
+*/
+const make = Effect.gen(function* () {
+	const app = yield* App;
+	const auth = Admin.getAuth(app);
+	const call = (span, message, f) => Effect.tryPromise({
+		try: () => Promise.resolve(f(auth)),
+		catch: authError(message)
+	}).pipe(Effect.withSpan(`Auth.${span}`));
+	return Auth.of({
+		use: (f) => call("use", "A Firebase Authentication call failed", f),
+		verifyIdToken: (idToken, checkRevoked) => call("verifyIdToken", "Failed to verify the ID token", (auth) => auth.verifyIdToken(idToken, checkRevoked)),
+		createCustomToken: (uid, developerClaims) => call("createCustomToken", `Failed to create a custom token for "${uid}"`, (auth) => auth.createCustomToken(uid, developerClaims)),
+		getUser: (uid) => call("getUser", `Failed to get the user "${uid}"`, (auth) => auth.getUser(uid)),
+		getUserByEmail: (email) => call("getUserByEmail", `Failed to get the user with the email "${email}"`, (auth) => auth.getUserByEmail(email)),
+		createUser: (properties) => call("createUser", "Failed to create the user", (auth) => auth.createUser(properties)),
+		updateUser: (uid, properties) => call("updateUser", `Failed to update the user "${uid}"`, (auth) => auth.updateUser(uid, properties)),
+		deleteUser: (uid) => call("deleteUser", `Failed to delete the user "${uid}"`, (auth) => auth.deleteUser(uid))
+	});
+});
+/**
+* A layer that provides {@link Auth} for the {@link App.App} in context.
+*
+* @example Providing Auth
+* ```ts
+* import { Layer } from "effect";
+* import { App } from "@visiolab/effect-firebase-admin/app";
+* import { Auth } from "@visiolab/effect-firebase-admin/auth";
+*
+* const AuthLive = Auth.layer.pipe(Layer.provide(App.layer()));
+* ```
+*
+* @see {@link make} for why building the service cannot fail
+* @see {@link App.layer} for the app it needs
+*
+* @stability unstable
+* @category layers
+* @since 0.1.0
+*/
+const layer = Layer.effect(Auth, make);
+export { Auth, AuthError, Auth_exports, layer, make };
+
+//# sourceMappingURL=Auth.mjs.map

package/dist/auth/Auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Auth.mjs","names":["App.App"],"sources":["../../src/auth/Auth.ts"],"sourcesContent":["/**\n * Firebase Authentication on the Admin SDK, as an Effect service.\n *\n * {@link Auth} wraps the calls server code uses most, such as verifying ID\n * tokens and managing users. Every call fails with an {@link AuthError}, and\n * {@link Auth.use} reaches the rest of the Admin SDK.\n *\n * @example Verifying an ID token\n * ```ts\n * import { Effect, Layer } from \"effect\";\n * import { App } from \"@visiolab/effect-firebase-admin/app\";\n * import { Auth } from \"@visiolab/effect-firebase-admin/auth\";\n *\n * const uidOf = (idToken: string) =>\n *   Effect.gen(function* () {\n *     const auth = yield* Auth.Auth;\n *     const token = yield* auth.verifyIdToken(idToken, true);\n *     return token.uid;\n *   });\n *\n * const AuthLive = Auth.layer.pipe(Layer.provide(App.layer()));\n *\n * uidOf(\"<id token>\").pipe(Effect.provide(AuthLive));\n * ```\n *\n * @stability unstable\n * @since 0.1.0\n */\nimport { Context, Effect, Layer, Schema } from \"effect\";\nimport { FirebaseError } from \"firebase-admin/app\";\nimport * as Admin from \"firebase-admin/auth\";\nimport * as App from \"../app/App.ts\";\n\n/**\n * Fails a call on {@link Auth} when the Admin SDK rejects it, with what it\n * threw as the `cause`.\n *\n * Match on `code` to tell failures apart, such as `auth/user-not-found` or\n * `auth/id-token-revoked`.\n *\n * @stability unstable\n * @category errors\n * @since 0.1.0\n */\nexport class AuthError extends Schema.TaggedError<AuthError, { readonly brand: unique symbol }>()(\n  \"AuthError\",\n  {\n    message: Schema.String,\n    /** The `service/string-code` the Admin SDK reported, such as `auth/user-not-found`. */\n    code: Schema.optional(Schema.String),\n    cause: Schema.optional(Schema.Defect()),\n  },\n) {}\n\nconst authError = (message: string) => (cause: unknown) =>\n  new AuthError({\n    message,\n    code: cause instanceof FirebaseError ? cause.code : undefined,\n    cause,\n  });\n\n/**\n * Firebase Authentication for a single app.\n *\n * Each call is the Admin SDK's method of the same name, with the same\n * arguments, failing with an {@link AuthError} and traced as a span named\n * `Auth.<method>`. Use {@link Auth.use} for anything else the Admin SDK offers.\n *\n * The Admin SDK cannot abort a request in flight, so interrupting a call does\n * not stop it: the request still runs to completion.\n *\n * @stability unstable\n * @category models\n * @since 0.1.0\n */\nexport interface Auth {\n  /**\n   * Runs `f` against the Admin SDK's own `Auth`, failing with an\n   * {@link AuthError} when it throws or rejects.\n   *\n   * **When to use**\n   *\n   * Use for the Admin SDK calls this service does not wrap, such as\n   * `setCustomUserClaims` or `listUsers`. Prefer the wrapped methods where one\n   * exists: they name the failure in the error's message.\n   *\n   * @example Setting custom claims\n   * ```ts\n   * import { Effect } from \"effect\";\n   * import { Auth } from \"@visiolab/effect-firebase-admin/auth\";\n   *\n   * const makeAdmin = (uid: string) =>\n   *   Effect.gen(function* () {\n   *     const auth = yield* Auth.Auth;\n   *     yield* auth.use((sdk) => sdk.setCustomUserClaims(uid, { admin: true }));\n   *   });\n   * ```\n   */\n  readonly use: <A>(f: (auth: Admin.Auth) => PromiseLike<A> | A) => Effect.Effect<A, AuthError>;\n  /**\n   * Verifies a Firebase ID token and decodes it.\n   *\n   * With `checkRevoked`, it also fails for a token whose session was revoked or\n   * whose user is disabled, at the cost of a request to the Auth backend.\n   *\n   * @see {@link Auth.createCustomToken} for minting a token a client signs in with\n   */\n  readonly verifyIdToken: (\n    idToken: string,\n    checkRevoked?: boolean,\n  ) => Effect.Effect<Admin.DecodedIdToken, AuthError>;\n  /**\n   * Mints a custom token for `uid`, which a client signs in with through\n   * `signInWithCustomToken`.\n   *\n   * `developerClaims` end up in the ID tokens of that session.\n   *\n   * @see {@link Auth.verifyIdToken} for checking the ID token a client sends back\n   */\n  readonly createCustomToken: (\n    uid: string,\n    developerClaims?: object,\n  ) => Effect.Effect<string, AuthError>;\n  /**\n   * Reads the user with `uid`.\n   *\n   * Fails with `auth/user-not-found` when there is none.\n   *\n   * @see {@link Auth.getUserByEmail} for looking a user up by email\n   */\n  readonly getUser: (uid: string) => Effect.Effect<Admin.UserRecord, AuthError>;\n  /**\n   * Reads the user with `email`.\n   *\n   * Fails with `auth/user-not-found` when there is none.\n   *\n   * @see {@link Auth.getUser} for looking a user up by uid\n   */\n  readonly getUserByEmail: (email: string) => Effect.Effect<Admin.UserRecord, AuthError>;\n  /**\n   * Creates a user, under the `uid` in `properties` or one the Auth backend\n   * picks.\n   *\n   * @see {@link Auth.updateUser} for changing a user that exists\n   */\n  readonly createUser: (\n    properties: Admin.CreateRequest,\n  ) => Effect.Effect<Admin.UserRecord, AuthError>;\n  /**\n   * Changes the properties of the user with `uid`.\n   *\n   * @see {@link Auth.createUser} for creating one\n   */\n  readonly updateUser: (\n    uid: string,\n    properties: Admin.UpdateRequest,\n  ) => Effect.Effect<Admin.UserRecord, AuthError>;\n  /**\n   * Deletes the user with `uid`.\n   */\n  readonly deleteUser: (uid: string) => Effect.Effect<void, AuthError>;\n}\n\n/**\n * Service key for Firebase Authentication.\n *\n * @stability unstable\n * @category services\n * @since 0.1.0\n */\nexport const Auth = Context.Service<Auth>(\"@visiolab/effect-firebase-admin/auth/Auth\");\n\n/**\n * Builds {@link Auth} 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.\n *\n * **Details**\n *\n * Building the service cannot fail. `getAuth` only throws for an app that was\n * already deleted or is not an app at all. Both are wiring mistakes, so they\n * are defects, and {@link AuthError} only ever means that a call failed.\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.gen(function* () {\n  const app = yield* App.App;\n\n  // `getAuth` memoizes the service on the app itself, so there is nothing to\n  // release here.\n  const auth = Admin.getAuth(app);\n\n  const call = <A>(\n    span: string,\n    message: string,\n    f: (auth: Admin.Auth) => PromiseLike<A> | A,\n  ): Effect.Effect<A, AuthError> =>\n    Effect.tryPromise({\n      // `Promise.resolve` covers the calls that hand back a plain value, and\n      // keeps a synchronous throw on the `catch` path rather than the die one.\n      try: () => Promise.resolve(f(auth)),\n      catch: authError(message),\n    }).pipe(Effect.withSpan(`Auth.${span}`));\n\n  return Auth.of({\n    use: (f) => call(\"use\", \"A Firebase Authentication call failed\", f),\n    verifyIdToken: (idToken, checkRevoked) =>\n      call(\"verifyIdToken\", \"Failed to verify the ID token\", (auth) =>\n        auth.verifyIdToken(idToken, checkRevoked),\n      ),\n    createCustomToken: (uid, developerClaims) =>\n      call(\"createCustomToken\", `Failed to create a custom token for \"${uid}\"`, (auth) =>\n        auth.createCustomToken(uid, developerClaims),\n      ),\n    getUser: (uid) =>\n      call(\"getUser\", `Failed to get the user \"${uid}\"`, (auth) => auth.getUser(uid)),\n    getUserByEmail: (email) =>\n      call(\"getUserByEmail\", `Failed to get the user with the email \"${email}\"`, (auth) =>\n        auth.getUserByEmail(email),\n      ),\n    createUser: (properties) =>\n      call(\"createUser\", \"Failed to create the user\", (auth) => auth.createUser(properties)),\n    updateUser: (uid, properties) =>\n      call(\"updateUser\", `Failed to update the user \"${uid}\"`, (auth) =>\n        auth.updateUser(uid, properties),\n      ),\n    deleteUser: (uid) =>\n      call(\"deleteUser\", `Failed to delete the user \"${uid}\"`, (auth) => auth.deleteUser(uid)),\n  });\n});\n\n/**\n * A layer that provides {@link Auth} for the {@link App.App} in context.\n *\n * @example Providing Auth\n * ```ts\n * import { Layer } from \"effect\";\n * import { App } from \"@visiolab/effect-firebase-admin/app\";\n * import { Auth } from \"@visiolab/effect-firebase-admin/auth\";\n *\n * const AuthLive = Auth.layer.pipe(Layer.provide(App.layer()));\n * ```\n *\n * @see {@link make} for why building the service cannot fail\n * @see {@link App.layer} for the app it needs\n *\n * @stability unstable\n * @category layers\n * @since 0.1.0\n */\nexport const layer: Layer.Layer<Auth, never, App.App> = Layer.effect(Auth, make);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,IAAa,YAAb,cAA+B,OAAO,YAA0D,CAAC,CAC/F,aACA;CACE,SAAS,OAAO;;CAEhB,MAAM,OAAO,SAAS,OAAO,MAAM;CACnC,OAAO,OAAO,SAAS,OAAO,OAAO,CAAC;AACxC,CACF,CAAC,CAAC,CAAC;AAEH,MAAM,aAAa,aAAqB,UACtC,IAAI,UAAU;CACZ;CACA,MAAM,iBAAiB,gBAAgB,MAAM,OAAO,KAAA;CACpD;AACF,CAAC;;;;;;;;AA+GH,MAAa,OAAO,QAAQ,QAAc,2CAA2C;;;;;;;;;;;;;;;;;;;;;AAsBrF,MAAa,OAAO,OAAO,IAAI,aAAa;CAC1C,MAAM,MAAM,OAAOA;CAInB,MAAM,OAAO,MAAM,QAAQ,GAAG;CAE9B,MAAM,QACJ,MACA,SACA,MAEA,OAAO,WAAW;EAGhB,WAAW,QAAQ,QAAQ,EAAE,IAAI,CAAC;EAClC,OAAO,UAAU,OAAO;CAC1B,CAAC,CAAC,CAAC,KAAK,OAAO,SAAS,QAAQ,MAAM,CAAC;CAEzC,OAAO,KAAK,GAAG;EACb,MAAM,MAAM,KAAK,OAAO,yCAAyC,CAAC;EAClE,gBAAgB,SAAS,iBACvB,KAAK,iBAAiB,kCAAkC,SACtD,KAAK,cAAc,SAAS,YAAY,CAC1C;EACF,oBAAoB,KAAK,oBACvB,KAAK,qBAAqB,wCAAwC,IAAI,KAAK,SACzE,KAAK,kBAAkB,KAAK,eAAe,CAC7C;EACF,UAAU,QACR,KAAK,WAAW,2BAA2B,IAAI,KAAK,SAAS,KAAK,QAAQ,GAAG,CAAC;EAChF,iBAAiB,UACf,KAAK,kBAAkB,0CAA0C,MAAM,KAAK,SAC1E,KAAK,eAAe,KAAK,CAC3B;EACF,aAAa,eACX,KAAK,cAAc,8BAA8B,SAAS,KAAK,WAAW,UAAU,CAAC;EACvF,aAAa,KAAK,eAChB,KAAK,cAAc,8BAA8B,IAAI,KAAK,SACxD,KAAK,WAAW,KAAK,UAAU,CACjC;EACF,aAAa,QACX,KAAK,cAAc,8BAA8B,IAAI,KAAK,SAAS,KAAK,WAAW,GAAG,CAAC;CAC3F,CAAC;AACH,CAAC;;;;;;;;;;;;;;;;;;;;AAqBD,MAAa,QAA2C,MAAM,OAAO,MAAM,IAAI"}

package/dist/auth/index.d.mts

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

package/dist/auth/index.mjs

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

package/dist/firestore/AdminFirestore.d.mts

@@ -0,0 +1,241 @@
+import { App } from "../app/App.mjs";
+import { Context, Effect, Layer } from "effect";
+import { Firestore, Transaction, TransactionBase, With } from "@visiolab/effect-firebase/firestore/Firestore";
+import * as Admin from "firebase-admin/firestore";
+declare namespace AdminFirestore_d_exports {
+  export { AdminFirestore, AdminTransaction, Options, layer, make };
+}
+declare const TypeId = "~@visiolab/effect-firebase-admin/firestore/AdminFirestore";
+declare const TransactionTypeId = "~@visiolab/effect-firebase-admin/firestore/AdminFirestore/AdminTransaction";
+/**
+ * The portable {@link Firestore}, plus what only the Admin SDK can do.
+ *
+ * **When to use**
+ *
+ * Ask for it where code needs the Admin SDK: {@link AdminTransaction} reads of
+ * many documents, or the SDK itself through {@link AdminFirestore.instance}.
+ * Everywhere else ask for {@link Firestore}, so the code also runs on the
+ * client SDK.
+ *
+ * **Details**
+ *
+ * The service its key holds is also a {@link Firestore}, so it can be handed to
+ * portable code 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. A {@link Firestore.With.runTransaction} body
+ * finds its transaction both
+ * as {@link AdminTransaction} and as the portable
+ * {@link Firestore.Transaction}. They are the same transaction, so portable
+ * helpers and Admin-only ones can run in the same body.
+ *
+ * The Admin 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.2.0
+ */
+export interface AdminFirestore extends With<never, never, {}, AdminTransaction> {
+  readonly [TypeId]: typeof TypeId;
+  /**
+   * The Admin 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, batched writes
+   * or `recursiveDelete`. 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 AdminFirestoreValue.toAdmin}.
+   *
+   * @see {@link AdminFirestoreValue} for mapping between the SDK's values and Firestore Values
+   */
+  readonly instance: Admin.Firestore;
+}
+/**
+ * A {@link Firestore.Transaction} that can also read every document in a
+ * collection or a Collection Group, which only the Admin SDK's transactions
+ * can.
+ *
+ * **When to use**
+ *
+ * Ask for it in a transaction body that reads many documents. A body that only
+ * reads single documents should ask for the portable
+ * {@link Firestore.Transaction}, so it also runs on the client SDK.
+ *
+ * **Details**
+ *
+ * A body run through {@link AdminFirestore} finds it next to
+ * {@link Firestore.Transaction}; they are the same transaction. The type
+ * extends {@link Firestore.TransactionBase}, not {@link Firestore.Transaction},
+ * and its key holds an `AdminTransaction & Transaction`. A body that asks for
+ * it and runs
+ * through the portable {@link Firestore} still needs it provided, so the
+ * compiler catches Admin-only code handed to portable code.
+ *
+ * The same rules hold as for {@link Firestore.Transaction}: a read of many is a
+ * read, so it comes before every write.
+ *
+ * @example Reading a collection in a transaction
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { Collection, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+ * import { AdminFirestore } from "@visiolab/effect-firebase-admin/firestore";
+ *
+ * class Seat extends FirestoreModel.Class<Seat>("Seat")({
+ *   taken: Schema.Boolean,
+ * }) {}
+ *
+ * const Seats = Collection.make("seats", Seat);
+ *
+ * const takeAnySeat = Effect.gen(function* () {
+ *   const firestore = yield* AdminFirestore.AdminFirestore;
+ *   return yield* firestore.runTransaction(
+ *     Effect.gen(function* () {
+ *       const tx = yield* AdminFirestore.AdminTransaction;
+ *       const { docs } = yield* tx.getDocs(Seats.collection());
+ *       for (const seat of docs) {
+ *         if (!(yield* seat.data).taken) {
+ *           yield* tx.updateDoc(seat.ref, { taken: true });
+ *           return seat.id;
+ *         }
+ *       }
+ *       return undefined;
+ *     }),
+ *   );
+ * });
+ * ```
+ *
+ * @see {@link Firestore.Transaction} for the portable transaction, which reads one document at a time
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface AdminTransaction extends TransactionBase {
+  readonly [TransactionTypeId]: typeof TransactionTypeId;
+  /**
+   * Reads every document in a collection or a Collection Group as part of the
+   * transaction, as {@link Firestore.With.getDocs} does outside one.
+   *
+   * Every document it returns is locked for the rest of the transaction, so
+   * another write to one of them makes the transaction run again. A group
+   * read that fails with an {@link Firestore.UndefinedCollectionError} fails
+   * the body, which rolls the transaction back without running it again.
+   */
+  readonly getDocs: Firestore["getDocs"];
+}
+/**
+ * Service key for {@link AdminTransaction}. The transaction it holds is a
+ * {@link Firestore.Transaction} too.
+ *
+ * @stability unstable
+ * @category services
+ * @since 0.2.0
+ */
+export declare const AdminTransaction: Context.Service<AdminTransaction, AdminTransaction & Transaction>;
+/**
+ * Service key for {@link AdminFirestore}.
+ *
+ * @see {@link Firestore} for the portable key, which {@link layer} provides the same service under
+ *
+ * @stability unstable
+ * @category services
+ * @since 0.2.0
+ */
+export declare const AdminFirestore: Context.Service<AdminFirestore, AdminFirestore & Firestore>;
+/**
+ * How {@link layer} opens a database. Both are fixed once the database is open.
+ *
+ * There is no emulator option. The Admin SDK reads the emulator from the
+ * `FIRESTORE_EMULATOR_HOST` environment variable, which must be set before the
+ * database is opened and applies to every app in the process.
+ *
+ * @see {@link ClientFirestore.Options} for the client SDK's, which take the emulator per database
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.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;
+  /**
+   * Talk HTTP/1.1 instead of gRPC until something needs gRPC.
+   *
+   * Use it where a process handles a request or two and exits, such as a
+   * function: it saves loading the gRPC libraries and opening a channel.
+   * Listening is the one thing that needs gRPC; the first listen loads it and
+   * the SDK stays on it.
+   */
+  readonly preferRest?: boolean | undefined;
+}
+/**
+ * Builds {@link AdminFirestore} 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, something that is not an app, or a database already
+ * opened with other settings. All three are wiring mistakes, so they are
+ * defects, and a {@link Firestore.FirestoreError} only ever means that a call
+ * failed.
+ *
+ * @see {@link layer} for the same as a layer
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const make: (options?: Options) => Effect.Effect<AdminFirestore & Firestore, never, App>;
+/**
+ * A layer that provides {@link AdminFirestore} for the {@link App.App} in
+ * context, and the same service as the portable {@link Firestore}.
+ *
+ * **When to use**
+ *
+ * Use on a server, or anywhere the Admin SDK runs. In a browser, use
+ * {@link ClientFirestore.layer} instead.
+ *
+ * **Details**
+ *
+ * With no options it opens the project's default database with the SDK's
+ * defaults.
+ *
+ * @example Providing Firestore against the emulator
+ * ```ts
+ * import { Layer } from "effect";
+ * import { App } from "@visiolab/effect-firebase-admin/app";
+ * import { AdminFirestore } from "@visiolab/effect-firebase-admin/firestore";
+ *
+ * // The Admin SDK reads FIRESTORE_EMULATOR_HOST, such as "127.0.0.1:8080".
+ * const FirestoreLive = AdminFirestore.layer({ preferRest: true }).pipe(
+ *   Layer.provide(App.layer({ projectId: "demo-project" })),
+ * );
+ * ```
+ *
+ * @see {@link make} for why building the service cannot fail
+ * @see {@link ClientFirestore.layer} for the client SDK's layer, for browsers
+ *
+ * @stability unstable
+ * @category layers
+ * @since 0.2.0
+ */
+export declare const layer: (options?: Options) => Layer.Layer<AdminFirestore | Firestore, never, App>;
+export { AdminFirestore_d_exports };
+//# sourceMappingURL=AdminFirestore.d.mts.map

package/dist/firestore/AdminFirestore.mjs

@@ -0,0 +1,133 @@
+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/AdminFirestore.ts
+/**
+* Firestore on the Firebase Admin SDK, for servers.
+*
+* {@link layer} provides one service under two keys: the portable
+* {@link Firestore}, which code that runs on either SDK asks for, and
+* {@link AdminFirestore}, which adds what only the Admin SDK can do. Both reach
+* the same database.
+*
+* @example Reading and writing a document
+* ```ts
+* import { Effect, Layer, Schema } from "effect";
+* import { Collection, Firestore, FirestoreModel } from "@visiolab/effect-firebase/firestore";
+* import { App } from "@visiolab/effect-firebase-admin/app";
+* import { AdminFirestore } from "@visiolab/effect-firebase-admin/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 program = Effect.gen(function* () {
+*   const firestore = yield* Firestore.Firestore;
+*   yield* firestore.setDoc(hello, { title: "Hello" });
+*   return yield* firestore.getDoc(hello);
+* });
+*
+* const FirestoreLive = AdminFirestore.layer().pipe(Layer.provide(App.layer()));
+*
+* program.pipe(Effect.provide(FirestoreLive));
+* ```
+*
+* @see {@link ClientFirestore} for the same service on the client SDK, for browsers
+*
+* @stability unstable
+* @since 0.2.0
+*/
+var AdminFirestore_exports = /* @__PURE__ */ __exportAll({
+	AdminFirestore: () => AdminFirestore,
+	AdminTransaction: () => AdminTransaction,
+	layer: () => layer,
+	make: () => make
+});
+/**
+* Service key for {@link AdminTransaction}. The transaction it holds is a
+* {@link Firestore.Transaction} too.
+*
+* @stability unstable
+* @category services
+* @since 0.2.0
+*/
+const AdminTransaction = Context.Service("@visiolab/effect-firebase-admin/firestore/AdminFirestore/AdminTransaction");
+/**
+* Service key for {@link AdminFirestore}.
+*
+* @see {@link Firestore} for the portable key, which {@link layer} provides the same service under
+*
+* @stability unstable
+* @category services
+* @since 0.2.0
+*/
+const AdminFirestore = Context.Service("@visiolab/effect-firebase-admin/firestore/AdminFirestore");
+/**
+* Builds {@link AdminFirestore} 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, something that is not an app, or a database already
+* opened with other settings. All three are wiring mistakes, so they are
+* defects, and a {@link Firestore.FirestoreError} only ever means that a call
+* failed.
+*
+* @see {@link layer} for the same as a layer
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const make = Effect.fn("AdminFirestore.make")(function* (options) {
+	const firestore = yield* openDatabase(options);
+	return fromDatabase(firestore, AdminTransaction);
+});
+/** The one service, under both its own tag and the portable one. */
+const both = (service) => Context.make(AdminFirestore, service).pipe(Context.add(Firestore, service));
+/**
+* A layer that provides {@link AdminFirestore} for the {@link App.App} in
+* context, and the same service as the portable {@link Firestore}.
+*
+* **When to use**
+*
+* Use on a server, or anywhere the Admin SDK runs. In a browser, use
+* {@link ClientFirestore.layer} instead.
+*
+* **Details**
+*
+* With no options it opens the project's default database with the SDK's
+* defaults.
+*
+* @example Providing Firestore against the emulator
+* ```ts
+* import { Layer } from "effect";
+* import { App } from "@visiolab/effect-firebase-admin/app";
+* import { AdminFirestore } from "@visiolab/effect-firebase-admin/firestore";
+*
+* // The Admin SDK reads FIRESTORE_EMULATOR_HOST, such as "127.0.0.1:8080".
+* const FirestoreLive = AdminFirestore.layer({ preferRest: true }).pipe(
+*   Layer.provide(App.layer({ projectId: "demo-project" })),
+* );
+* ```
+*
+* @see {@link make} for why building the service cannot fail
+* @see {@link ClientFirestore.layer} for the client SDK's layer, for browsers
+*
+* @stability unstable
+* @category layers
+* @since 0.2.0
+*/
+const layer = (options) => Layer.effectContext(Effect.map(make(options), both));
+export { AdminFirestore, AdminFirestore_exports, AdminTransaction, layer, make };
+
+//# sourceMappingURL=AdminFirestore.mjs.map

package/dist/firestore/AdminFirestore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdminFirestore.mjs","names":["internalFirestore.openDatabase","internalFirestore.fromDatabase"],"sources":["../../src/firestore/AdminFirestore.ts"],"sourcesContent":["/**\n * Firestore on the Firebase Admin SDK, for servers.\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 AdminFirestore}, which adds what only the Admin SDK can do. Both reach\n * the same database.\n *\n * @example Reading and writing a document\n * ```ts\n * import { Effect, Layer, Schema } from \"effect\";\n * import { Collection, Firestore, FirestoreModel } from \"@visiolab/effect-firebase/firestore\";\n * import { App } from \"@visiolab/effect-firebase-admin/app\";\n * import { AdminFirestore } from \"@visiolab/effect-firebase-admin/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 program = Effect.gen(function* () {\n *   const firestore = yield* Firestore.Firestore;\n *   yield* firestore.setDoc(hello, { title: \"Hello\" });\n *   return yield* firestore.getDoc(hello);\n * });\n *\n * const FirestoreLive = AdminFirestore.layer().pipe(Layer.provide(App.layer()));\n *\n * program.pipe(Effect.provide(FirestoreLive));\n * ```\n *\n * @see {@link ClientFirestore} for the same service on the client SDK, for browsers\n *\n * @stability unstable\n * @since 0.2.0\n */\nimport { Context, Effect, Layer } from \"effect\";\nimport { Firestore, type With } from \"@visiolab/effect-firebase/firestore/Firestore\";\nimport type { Transaction, TransactionBase } from \"@visiolab/effect-firebase/firestore/Firestore\";\nimport type * as Admin from \"firebase-admin/firestore\";\nimport type * as App from \"../app/App.ts\";\nimport * as internalFirestore from \"./internal/firestore.ts\";\n\nconst TypeId = internalFirestore.TypeId;\n\nconst TransactionTypeId = internalFirestore.TransactionTypeId;\n\n/**\n * The portable {@link Firestore}, plus what only the Admin SDK can do.\n *\n * **When to use**\n *\n * Ask for it where code needs the Admin SDK: {@link AdminTransaction} reads of\n * many documents, or the SDK itself through {@link AdminFirestore.instance}.\n * Everywhere else ask for {@link Firestore}, so the code also runs on the\n * client SDK.\n *\n * **Details**\n *\n * The service its key holds is also a {@link Firestore}, so it can be handed to\n * portable code as it is. The type itself only extends {@link Firestore.With},\n * so providing a {@link Firestore} alone, such as an in-memory fake, does not\n * satisfy code that asks for it. A {@link Firestore.With.runTransaction} body\n * finds its transaction both\n * as {@link AdminTransaction} and as the portable\n * {@link Firestore.Transaction}. They are the same transaction, so portable\n * helpers and Admin-only ones can run in the same body.\n *\n * The Admin 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.2.0\n */\nexport interface AdminFirestore extends With<never, never, {}, AdminTransaction> {\n  readonly [TypeId]: typeof TypeId;\n\n  /**\n   * The Admin 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, batched writes\n   * or `recursiveDelete`. Prefer the service's own methods 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 AdminFirestoreValue.toAdmin}.\n   *\n   * @see {@link AdminFirestoreValue} for mapping between the SDK's values and Firestore Values\n   */\n  readonly instance: Admin.Firestore;\n}\n\n/**\n * A {@link Firestore.Transaction} that can also read every document in a\n * collection or a Collection Group, which only the Admin SDK's transactions\n * can.\n *\n * **When to use**\n *\n * Ask for it in a transaction body that reads many documents. A body that only\n * reads single documents should ask for the portable\n * {@link Firestore.Transaction}, so it also runs on the client SDK.\n *\n * **Details**\n *\n * A body run through {@link AdminFirestore} finds it next to\n * {@link Firestore.Transaction}; they are the same transaction. The type\n * extends {@link Firestore.TransactionBase}, not {@link Firestore.Transaction},\n * and its key holds an `AdminTransaction & Transaction`. A body that asks for\n * it and runs\n * through the portable {@link Firestore} still needs it provided, so the\n * compiler catches Admin-only code handed to portable code.\n *\n * The same rules hold as for {@link Firestore.Transaction}: a read of many is a\n * read, so it comes before every write.\n *\n * @example Reading a collection in a transaction\n * ```ts\n * import { Effect, Schema } from \"effect\";\n * import { Collection, FirestoreModel } from \"@visiolab/effect-firebase/firestore\";\n * import { AdminFirestore } from \"@visiolab/effect-firebase-admin/firestore\";\n *\n * class Seat extends FirestoreModel.Class<Seat>(\"Seat\")({\n *   taken: Schema.Boolean,\n * }) {}\n *\n * const Seats = Collection.make(\"seats\", Seat);\n *\n * const takeAnySeat = Effect.gen(function* () {\n *   const firestore = yield* AdminFirestore.AdminFirestore;\n *   return yield* firestore.runTransaction(\n *     Effect.gen(function* () {\n *       const tx = yield* AdminFirestore.AdminTransaction;\n *       const { docs } = yield* tx.getDocs(Seats.collection());\n *       for (const seat of docs) {\n *         if (!(yield* seat.data).taken) {\n *           yield* tx.updateDoc(seat.ref, { taken: true });\n *           return seat.id;\n *         }\n *       }\n *       return undefined;\n *     }),\n *   );\n * });\n * ```\n *\n * @see {@link Firestore.Transaction} for the portable transaction, which reads one document at a time\n *\n * @stability unstable\n * @category models\n * @since 0.2.0\n */\nexport interface AdminTransaction extends TransactionBase {\n  readonly [TransactionTypeId]: typeof TransactionTypeId;\n\n  /**\n   * Reads every document in a collection or a Collection Group as part of the\n   * transaction, as {@link Firestore.With.getDocs} does outside one.\n   *\n   * Every document it returns is locked for the rest of the transaction, so\n   * another write to one of them makes the transaction run again. A group\n   * read that fails with an {@link Firestore.UndefinedCollectionError} fails\n   * the body, which rolls the transaction back without running it again.\n   */\n  readonly getDocs: Firestore[\"getDocs\"];\n}\n\n/**\n * Service key for {@link AdminTransaction}. The transaction it holds is a\n * {@link Firestore.Transaction} too.\n *\n * @stability unstable\n * @category services\n * @since 0.2.0\n */\nexport const AdminTransaction = Context.Service<AdminTransaction, AdminTransaction & Transaction>(\n  \"@visiolab/effect-firebase-admin/firestore/AdminFirestore/AdminTransaction\",\n);\n\n/**\n * Service key for {@link AdminFirestore}.\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.2.0\n */\nexport const AdminFirestore = Context.Service<AdminFirestore, AdminFirestore & Firestore>(\n  \"@visiolab/effect-firebase-admin/firestore/AdminFirestore\",\n);\n\n/**\n * How {@link layer} opens a database. Both are fixed once the database is open.\n *\n * There is no emulator option. The Admin SDK reads the emulator from the\n * `FIRESTORE_EMULATOR_HOST` environment variable, which must be set before the\n * database is opened and applies to every app in the process.\n *\n * @see {@link ClientFirestore.Options} for the client SDK's, which take the emulator per database\n *\n * @stability unstable\n * @category models\n * @since 0.2.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   * Talk HTTP/1.1 instead of gRPC until something needs gRPC.\n   *\n   * Use it where a process handles a request or two and exits, such as a\n   * function: it saves loading the gRPC libraries and opening a channel.\n   * Listening is the one thing that needs gRPC; the first listen loads it and\n   * the SDK stays on it.\n   */\n  readonly preferRest?: boolean | undefined;\n}\n\n/**\n * Builds {@link AdminFirestore} 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, something that is not an app, or a database already\n * opened with other settings. All three are wiring mistakes, so they are\n * defects, and a {@link Firestore.FirestoreError} only ever means that a call\n * failed.\n *\n * @see {@link layer} for the same as a layer\n *\n * @stability unstable\n * @category constructors\n * @since 0.2.0\n */\nexport const make: (\n  options?: Options,\n) => Effect.Effect<AdminFirestore & Firestore, never, App.App> = Effect.fn(\"AdminFirestore.make\")(\n  function* (options?: Options) {\n    const firestore = yield* internalFirestore.openDatabase(options);\n    return internalFirestore.fromDatabase(firestore, AdminTransaction);\n  },\n);\n\n/** The one service, under both its own tag and the portable one. */\nconst both = (service: AdminFirestore & Firestore) =>\n  Context.make(AdminFirestore, service).pipe(Context.add(Firestore, service));\n\n/**\n * A layer that provides {@link AdminFirestore} 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 on a server, or anywhere the Admin SDK runs. In a browser, use\n * {@link ClientFirestore.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 against the emulator\n * ```ts\n * import { Layer } from \"effect\";\n * import { App } from \"@visiolab/effect-firebase-admin/app\";\n * import { AdminFirestore } from \"@visiolab/effect-firebase-admin/firestore\";\n *\n * // The Admin SDK reads FIRESTORE_EMULATOR_HOST, such as \"127.0.0.1:8080\".\n * const FirestoreLive = AdminFirestore.layer({ preferRest: true }).pipe(\n *   Layer.provide(App.layer({ projectId: \"demo-project\" })),\n * );\n * ```\n *\n * @see {@link make} for why building the service cannot fail\n * @see {@link ClientFirestore.layer} for the client SDK's layer, for browsers\n *\n * @stability unstable\n * @category layers\n * @since 0.2.0\n */\nexport const layer = (options?: Options): Layer.Layer<AdminFirestore | Firestore, never, App.App> =>\n  Layer.effectContext(Effect.map(make(options), both));\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0LA,MAAa,mBAAmB,QAAQ,QACtC,2EACF;;;;;;;;;;AAWA,MAAa,iBAAiB,QAAQ,QACpC,0DACF;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAa,OAEoD,OAAO,GAAG,qBAAqB,CAAC,CAC/F,WAAW,SAAmB;CAC5B,MAAM,YAAY,OAAOA,aAA+B,OAAO;CAC/D,OAAOC,aAA+B,WAAW,gBAAgB;AACnE,CACF;;AAGA,MAAM,QAAQ,YACZ,QAAQ,KAAK,gBAAgB,OAAO,CAAC,CAAC,KAAK,QAAQ,IAAI,WAAW,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmC5E,MAAa,SAAS,YACpB,MAAM,cAAc,OAAO,IAAI,KAAK,OAAO,GAAG,IAAI,CAAC"}

package/dist/firestore/AdminFirestoreValue.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-admin/firestore";
+import { FirestoreValue } from "@visiolab/effect-firebase/firestore/FirestoreValue";
+declare namespace AdminFirestoreValue_d_exports {
+  export { fromAdmin, toAdmin };
+}
+/**
+ * Turns a Firestore Value into the value the Admin SDK writes into
+ * `firestore`.
+ *
+ * **When to use**
+ *
+ * Use to write what a model encodes to through the Admin SDK itself.
+ *
+ * **Details**
+ *
+ * The portable `Timestamp`, `GeoPoint`, bytes and sentinels become the Admin
+ * SDK's own. A `DocumentPath` becomes `firestore.doc(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
+ * Admin SDK's own values or a class instance cast past the type. What
+ * {@link FirestoreValue.toCodecFirestore} encodes is always a Firestore Value.
+ *
+ * @see {@link fromAdmin} for the other direction
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export declare const toAdmin: (value: FirestoreValue, firestore: Firestore$1) => unknown;
+/**
+ * Turns a value the Admin SDK read into a Firestore Value.
+ *
+ * **When to use**
+ *
+ * Use to decode what the Admin SDK itself read through a model, with
+ * {@link FirestoreValue.toCodecFirestore}.
+ *
+ * **Details**
+ *
+ * The Admin SDK's `Timestamp`, `GeoPoint`, bytes and sentinels become their
+ * portable forms. 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 toAdmin} for the other direction
+ *
+ * @stability unstable
+ * @category conversions
+ * @since 0.2.0
+ */
+export declare const fromAdmin: (value: unknown) => Result.Result<FirestoreValue, FirestoreError>;
+export { AdminFirestoreValue_d_exports };
+//# sourceMappingURL=AdminFirestoreValue.d.mts.map