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

package/src/firestore/internal/firestore.ts

@@ -0,0 +1,264 @@
+import { Effect, Result } from "effect";
+import * as Firestore from "@visiolab/effect-firebase/firestore/Firestore";
+import { FirebaseError } from "firebase/app";
+import * as Client from "firebase/firestore";
+import * as App from "../../app/App.ts";
+import type * as ClientFirestore from "../ClientFirestore.ts";
+import * as firestoreValue from "./firestoreValue.ts";
+import * as snapshotMetadata from "./snapshotMetadata.ts";
+
+/** @internal */
+export const TypeId = "~@visiolab/effect-firebase-client/firestore/ClientFirestore";
+
+/**
+ * Opens the database the options name.
+ *
+ * Settings can only be handed over through `initializeFirestore`, which refuses
+ * a database already opened, so they are only passed along when there are
+ * some: asking for the default database twice keeps working, and asking for it
+ * twice with settings is the mistake it reports.
+ *
+ * The emulator is connected after, which the SDK takes as often as it is asked
+ * for the same one, but only before the database is first used.
+ */
+const open = (app: App.App, options: ClientFirestore.Options | undefined): Client.Firestore => {
+  const databaseId = options?.databaseId;
+  const firestore =
+    options?.localCache === undefined
+      ? databaseId === undefined
+        ? Client.getFirestore(app)
+        : Client.getFirestore(app, databaseId)
+      : Client.initializeFirestore(app, { localCache: options.localCache }, databaseId);
+  if (options?.emulator !== undefined) {
+    Client.connectFirestoreEmulator(firestore, options.emulator.host, options.emulator.port);
+  }
+  return firestore;
+};
+
+/**
+ * Opens the database the options name on the {@link App.App} in context.
+ *
+ * The SDK memoizes a database on the app itself, and deleting the app
+ * terminates it, so there is nothing to release here.
+ *
+ * @internal
+ */
+export const openDatabase = Effect.fnUntraced(function* (options?: ClientFirestore.Options) {
+  const app = yield* App.App;
+  return open(app, options);
+});
+
+const firestoreError = (message: string) => (cause: unknown) =>
+  new Firestore.FirestoreError({
+    message,
+    // The client SDK names every failure it reports, such as
+    // `permission-denied`, whether it raised it itself or the database did.
+    code: cause instanceof FirebaseError ? cause.code : undefined,
+    cause,
+  });
+
+/** Runs one call to the SDK, turning what it throws or rejects with into a `FirestoreError`. */
+const call = <A>(
+  message: string,
+  f: () => PromiseLike<A> | A,
+): Effect.Effect<A, Firestore.FirestoreError> =>
+  Effect.tryPromise({
+    try: () => Promise.resolve(f()),
+    catch: firestoreError(message),
+  });
+
+/**
+ * Reads a document's data as Firestore Values, with the server timestamps it
+ * is still waiting on estimated, rather than left `null` where a timestamp is
+ * expected.
+ *
+ * A document holding a value outside the Firestore Value union, such as a
+ * vector, fails to read: it could only ever be decoded as an untyped object.
+ * `data()` hands back `undefined` for a document that is not there, which is
+ * kept as it is.
+ */
+const dataOf = (
+  path: string,
+  snapshot: Client.DocumentSnapshot,
+): Result.Result<Firestore.DocumentData | undefined, Firestore.FirestoreError> =>
+  firestoreValue.readDocument(
+    path,
+    snapshot.data({ serverTimestamps: "estimate" }),
+  ) as Result.Result<Firestore.DocumentData | undefined, Firestore.FirestoreError>;
+
+/** What the client knows about a read beyond the portable snapshot. */
+type Extra = ReturnType<typeof snapshotMetadata.extraOf>;
+
+/** A read of one document, with the metadata the SDK reported for it. */
+const documentReadOf = (
+  snapshot: Client.DocumentSnapshot,
+): Result.Result<Firestore.DocumentRead<Extra>, Firestore.FirestoreError> =>
+  Result.map(dataOf(snapshot.ref.path, snapshot), (data) => ({
+    data,
+    extra: snapshotMetadata.extraOf(snapshot.metadata),
+  }));
+
+/** A read of many documents, each and as a whole with the metadata the SDK reported. */
+const queryReadOf = (
+  query: Client.QuerySnapshot,
+): Result.Result<Firestore.QueryRead<Extra>, Firestore.FirestoreError> =>
+  Result.map(
+    Result.all(
+      query.docs.map((snapshot) =>
+        Result.map(dataOf(snapshot.ref.path, snapshot), (data) => ({
+          path: snapshot.ref.path,
+          // A query only hands back documents that are there.
+          data: data as Firestore.DocumentData,
+          extra: snapshotMetadata.extraOf(snapshot.metadata),
+        })),
+      ),
+    ),
+    (docs) => ({ docs, extra: snapshotMetadata.extraOf(query.metadata) }),
+  );
+
+/** The client SDK query `selector` names, and what it is called in a failure. */
+const queryOf = (
+  firestore: Client.Firestore,
+  selector: Firestore.CollectionSelector,
+): { readonly query: Client.Query; readonly name: string } =>
+  selector._tag === "CollectionGroup"
+    ? {
+        query: Client.collectionGroup(firestore, selector.id),
+        name: `the collection group "${selector.id}"`,
+      }
+    : {
+        query: Client.collection(firestore, selector.path),
+        name: `the collection "${selector.path}"`,
+      };
+
+/** The SDK's own reads, for one {@link ClientFirestore.ReadSource}. */
+interface Reads {
+  readonly getDoc: (ref: Client.DocumentReference) => Promise<Client.DocumentSnapshot>;
+  readonly getDocs: (query: Client.Query) => Promise<Client.QuerySnapshot>;
+}
+
+const reads: Record<ClientFirestore.ReadSource, Reads> = {
+  default: { getDoc: Client.getDoc, getDocs: Client.getDocs },
+  server: { getDoc: Client.getDocFromServer, getDocs: Client.getDocsFromServer },
+  cache: { getDoc: Client.getDocFromCache, getDocs: Client.getDocsFromCache },
+};
+
+/** The SDK's reads from where `options` names, `"default"` where it names none. */
+const readsFrom = (options: ClientFirestore.ReadOptions | undefined): Reads =>
+  reads[options?.source ?? "default"];
+
+/**
+ * The SDK's listen options for `options`, leaving out what is not given rather
+ * than handing the SDK an `undefined` in its place.
+ */
+const snapshotListenOptions = (
+  options: ClientFirestore.ListenOptions | undefined,
+): Client.SnapshotListenOptions => ({
+  ...(options?.includeMetadataChanges === undefined
+    ? {}
+    : { includeMetadataChanges: options.includeMetadataChanges }),
+  ...(options?.source === undefined ? {} : { source: options.source }),
+});
+
+/**
+ * The service over a database already opened.
+ *
+ * @internal
+ */
+export const fromDatabase = (
+  firestore: Client.Firestore,
+): ClientFirestore.ClientFirestore & Firestore.Firestore => {
+  const docOf = (path: string) => Client.doc(firestore, path);
+  const toClient = (data: Firestore.DocumentData) =>
+    firestoreValue.toClient(data, firestore) as Client.DocumentData;
+
+  const made = Firestore.make({
+    getDoc: (path, options: ClientFirestore.ReadOptions | undefined) =>
+      Effect.flatMap(
+        call(`Failed to read the document "${path}"`, () => readsFrom(options).getDoc(docOf(path))),
+        (snapshot) => Effect.fromResult(documentReadOf(snapshot)),
+      ),
+
+    getDocs: (selector, options: ClientFirestore.ReadOptions | undefined) => {
+      const { query, name } = queryOf(firestore, selector);
+      return Effect.flatMap(
+        call(`Failed to read ${name}`, () => readsFrom(options).getDocs(query)),
+        (snapshot) => Effect.fromResult(queryReadOf(snapshot)),
+      );
+    },
+
+    setDoc: (path, data) =>
+      call(`Failed to write the document "${path}"`, () =>
+        Client.setDoc(docOf(path), toClient(data)),
+      ),
+
+    updateDoc: (path, data) =>
+      call(`Failed to update the document "${path}"`, () =>
+        Client.updateDoc(docOf(path), toClient(data)),
+      ),
+
+    addDoc: (path, data) =>
+      Effect.map(
+        call(`Failed to add a document to "${path}"`, () =>
+          Client.addDoc(Client.collection(firestore, path), toClient(data)),
+        ),
+        (added) => added.id,
+      ),
+
+    // The client SDK hands a listener the documents as this client last wrote
+    // them, before the database has taken the writes, so each write is seen
+    // straight away rather than once it is acknowledged.
+    streamDoc: (path, options: ClientFirestore.ListenOptions | undefined) =>
+      Firestore.streamFromListener({
+        subscribe: (onNext, onError) =>
+          Client.onSnapshot(docOf(path), snapshotListenOptions(options), onNext, onError),
+        onError: firestoreError(`Failed to listen to the document "${path}"`),
+        map: documentReadOf,
+      }),
+
+    streamDocs: (selector, options: ClientFirestore.ListenOptions | undefined) => {
+      const { query, name } = queryOf(firestore, selector);
+      return Firestore.streamFromListener({
+        subscribe: (onNext, onError) =>
+          Client.onSnapshot(query, snapshotListenOptions(options), onNext, onError),
+        onError: firestoreError(`Failed to listen to ${name}`),
+        map: queryReadOf,
+      });
+    },
+
+    runTransaction: Firestore.transactionFromCallback({
+      run: (callback, options) => Client.runTransaction(firestore, callback, options),
+      operations: (tx: Client.Transaction) => ({
+        // A transaction reads from the server alone and never holds writes of
+        // its own that are pending, so its metadata says nothing and is left
+        // out: what it hands back is the portable snapshot.
+        getDoc: (path) =>
+          Effect.flatMap(
+            call(`Failed to read the document "${path}"`, () => tx.get(docOf(path))),
+            (snapshot) =>
+              Effect.fromResult(Result.map(dataOf(path, snapshot), (data) => ({ data }))),
+          ),
+        // Writes into a transaction are queued rather than sent, so these return
+        // straight away - or throw, where the transaction refuses them.
+        setDoc: (path, data) =>
+          call(`Failed to write the document "${path}"`, () => {
+            tx.set(docOf(path), toClient(data));
+          }),
+        updateDoc: (path, data) =>
+          call(`Failed to update the document "${path}"`, () => {
+            tx.update(docOf(path), toClient(data));
+          }),
+      }),
+      onError: firestoreError("Failed to run a transaction"),
+    }),
+  });
+
+  // `make` infers the read source and listen options its hooks are handed and
+  // the metadata they read with each snapshot, so the client's interface is
+  // checked against what it built here.
+  const service: ClientFirestore.ClientFirestore & Firestore.Firestore = Object.assign(made, {
+    [TypeId]: TypeId as typeof TypeId,
+    instance: firestore,
+  });
+  return service;
+};

package/src/firestore/internal/firestoreValue.ts

@@ -0,0 +1,58 @@
+import type { Result } from "effect";
+import * as DocumentPath from "@visiolab/effect-firebase/firestore/DocumentPath";
+import type { FirestoreError } from "@visiolab/effect-firebase/firestore/Firestore";
+import * as FirestoreValue from "@visiolab/effect-firebase/firestore/FirestoreValue";
+import * as GeoPoint from "@visiolab/effect-firebase/firestore/GeoPoint";
+import * as Timestamp from "@visiolab/effect-firebase/firestore/Timestamp";
+import * as Client from "firebase/firestore";
+
+/** How the client SDK writes each kind of Firestore Value into `firestore`. */
+const writer = (firestore: Client.Firestore): FirestoreValue.Writer => ({
+  // The client SDK refuses a raw `Uint8Array`, as a custom object.
+  bytes: (bytes) => Client.Bytes.fromUint8Array(bytes),
+  timestamp: (ts) => new Client.Timestamp(ts.seconds, ts.nanoseconds),
+  geoPoint: (point) => new Client.GeoPoint(point.latitude, point.longitude),
+  documentPath: (ref) => Client.doc(firestore, ref.path),
+  serverTimestamp: () => Client.serverTimestamp(),
+  increment: (increment) => Client.increment(increment.by),
+  deleteField: () => Client.deleteField(),
+  arrayUnion: (union, walk) => Client.arrayUnion(...union.elements.map(walk)),
+  arrayRemove: (remove, walk) => Client.arrayRemove(...remove.elements.map(walk)),
+});
+
+/** @internal */
+export const toClient = (
+  value: FirestoreValue.FirestoreValue,
+  firestore: Client.Firestore,
+): unknown => FirestoreValue.toSdk(value, writer(firestore));
+
+/**
+ * How the client SDK's own values read back as Firestore Values. Its
+ * sentinels are not read back: a read never hands one back, and the names it
+ * keeps them by are internal to it.
+ */
+const reader: FirestoreValue.Reader = (u) => {
+  if (u instanceof Client.Timestamp) return Timestamp.makeUnsafe(u.seconds, u.nanoseconds);
+  if (u instanceof Client.GeoPoint) return GeoPoint.makeUnsafe(u.latitude, u.longitude);
+  if (u instanceof Client.DocumentReference) return DocumentPath.makeUnsafe(u.path);
+  if (u instanceof Client.Bytes) return u.toUint8Array();
+  return undefined;
+};
+
+/** @internal */
+export const fromClient = (
+  value: unknown,
+): Result.Result<FirestoreValue.FirestoreValue, FirestoreError> =>
+  FirestoreValue.fromSdk(value, reader);
+
+/**
+ * What the client SDK read for the document at `path`, as Firestore Values,
+ * or `undefined` for a document that is not there.
+ *
+ * @internal
+ */
+export const readDocument = (
+  path: string,
+  data: Client.DocumentData | undefined,
+): Result.Result<FirestoreValue.FirestoreValue | undefined, FirestoreError> =>
+  FirestoreValue.readDocument(path, data, reader);

package/src/firestore/internal/snapshotMetadata.ts

@@ -0,0 +1,14 @@
+import type * as ClientDocumentSnapshot from "../ClientDocumentSnapshot.ts";
+
+/**
+ * The extra a client snapshot is built with: its metadata, copied out of the
+ * SDK's own object so that the snapshot holds, and prints, only these two
+ * fields.
+ *
+ * @internal
+ */
+export const extraOf = (
+  metadata: ClientDocumentSnapshot.SnapshotMetadata,
+): { readonly metadata: ClientDocumentSnapshot.SnapshotMetadata } => ({
+  metadata: { fromCache: metadata.fromCache, hasPendingWrites: metadata.hasPendingWrites },
+});

package/src/functions/CallableClient.ts

@@ -0,0 +1,296 @@
+/**
+ * Callable Clients: call the Callables a server serves, with the Payload, the
+ * success value and the errors typed by their contract.
+ *
+ * A client calls through the {@link ClientFunctions.ClientFunctions} in
+ * context, so the region and the emulator are set once, where that is
+ * provided.
+ *
+ * @example Calling a Callable
+ * ```ts
+ * import { Effect, Layer, Schema } from "effect";
+ * import { Callable } from "@visiolab/effect-firebase/functions";
+ * import { App } from "@visiolab/effect-firebase-client/app";
+ * import { CallableClient, ClientFunctions } from "@visiolab/effect-firebase-client/functions";
+ *
+ * const Greet = Callable.make("greet", {
+ *   payload: { name: Schema.String },
+ *   success: Schema.String,
+ * });
+ *
+ * const program = Effect.gen(function* () {
+ *   const { greet } = yield* CallableClient.make(Greet);
+ *   const message = yield* greet({ name: "Ada" });
+ *   yield* Effect.log(message);
+ * });
+ *
+ * const FunctionsLive = ClientFunctions.layer().pipe(
+ *   Layer.provide(App.layer({ apiKey: "<api key>", projectId: "my-project", appId: "<app id>" })),
+ * );
+ *
+ * program.pipe(Effect.provide(FunctionsLive));
+ * ```
+ *
+ * @stability unstable
+ * @since 0.3.0
+ */
+import { Effect, Schema } from "effect";
+import * as Callable from "@visiolab/effect-firebase/functions/Callable";
+import * as CallableError from "@visiolab/effect-firebase/functions/CallableError";
+import * as FunctionGroup from "@visiolab/effect-firebase/functions/FunctionGroup";
+import * as Sdk from "firebase/functions";
+import * as ClientFunctions from "./ClientFunctions.ts";
+
+/**
+ * A client of one Callable: a function from its Payload to an Effect of its
+ * success value, failing with its declared errors or a `CallableError`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type Method<C extends Callable.Any> = (
+  payload: Callable.Payload<C>,
+) => Effect.Effect<Callable.Success<C>, Callable.Error<C> | CallableError.CallableError>;
+
+/**
+ * What {@link make} returns: one {@link Method} per Callable, keyed by the
+ * Callable's name. For a Function Group, one per Callable member.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.3.0
+ */
+export type Client<T extends Callable.Any | FunctionGroup.Any> = {
+  readonly [C in Members<T> as C["name"]]: Method<C>;
+};
+
+/**
+ * The Callables a client of `T` calls: the Callable members of a Function
+ * Group, or the Callable itself. Members of other kinds are left out.
+ *
+ * @stability unstable
+ * @category type-level
+ * @since 0.3.0
+ */
+export type Members<T extends Callable.Any | FunctionGroup.Any> = T extends FunctionGroup.Any
+  ? FunctionGroup.Members<T, Callable.Any>
+  : T;
+
+/** The ` [<status>]` the SDK appends to the message of an error built from an answer. */
+const statusSuffix = / \[(\d+)\]$/;
+
+/**
+ * The messages of the SDK's errors for an answer it can't read: not a JSON
+ * object, or one without `data` or `error`.
+ */
+const malformedAnswer = /Response is (?:not valid JSON object|missing data field)\.$/;
+
+/**
+ * The client function of `callable`, served as `deployment`. `errors` are the
+ * schemas of every error it can be answered with, its middleware's included.
+ */
+const method = (
+  functions: Sdk.Functions,
+  callable: Callable.Any,
+  deployment: Callable.Deployment,
+  errors: ReadonlyArray<Schema.Top>,
+) => {
+  const deployedName = deployment.name;
+  const span = { kind: "client", attributes: deployment.attributes } as const;
+  const call = Sdk.httpsCallable(functions, deployedName);
+  const encode = Schema.encodeUnknownEffect(
+    Schema.toCodecJson(callable.payload as Schema.Codec<unknown>),
+  );
+  const decode = Schema.decodeUnknownEffect(
+    Schema.toCodecJson(callable.success as Schema.Codec<unknown>),
+  );
+  const fail = (reason: CallableError.Reason) =>
+    new CallableError.CallableError({ callable: deployedName, reason });
+  const run = Effect.fn(
+    `CallableClient.${deployedName}`,
+    span,
+  )(function* (payload: unknown) {
+    const data = yield* encode(payload).pipe(
+      Effect.mapError((cause) => fail(new CallableError.EncodeError({ cause }))),
+    );
+    const result = yield* Effect.tryPromise({
+      try: () => call(data),
+      catch: (error) => error,
+    }).pipe(Effect.catch(decodeFailure));
+    return yield* decode(result.data).pipe(
+      Effect.mapError((cause) => fail(new CallableError.DecodeError({ cause }))),
+    );
+  });
+
+  /**
+   * Turns what the SDK threw into the declared error it carries, or into a
+   * `CallableError`.
+   */
+  const decodeFailure = (error: unknown): Effect.Effect<never, unknown> => {
+    if (!(error instanceof Sdk.FunctionsError)) {
+      return Effect.fail(fail(new CallableError.TransportError({ cause: error })));
+    }
+    // The SDK appends the HTTP status to the message of an error built from
+    // an answer, and status 0 to a network failure. The errors it makes
+    // itself, such as its timeout or a cancellation, carry no status.
+    const status = statusSuffix.exec(error.message)?.[1];
+    if (status === undefined || status === "0") {
+      // An answer arrived, but not one the SDK could read.
+      if (malformedAnswer.test(error.message)) {
+        return Effect.fail(fail(new CallableError.DecodeError({ cause: error })));
+      }
+      return Effect.fail(fail(new CallableError.TransportError({ cause: error })));
+    }
+    const code = error.code.replace(/^functions\//, "") as CallableError.ErrorCode;
+    const candidates = errors.filter((schema) => Callable.getErrorCode(schema) === code);
+    if (candidates.length === 0 || error.details === undefined) {
+      return Effect.fail(
+        fail(
+          new CallableError.ResponseError({
+            code,
+            message: error.message.replace(statusSuffix, ""),
+            details: error.details,
+          }),
+        ),
+      );
+    }
+    return Schema.decodeUnknownEffect(
+      Schema.toCodecJson(Schema.Union(candidates) as unknown as Schema.Codec<unknown>),
+    )(error.details).pipe(
+      Effect.mapError((cause) => fail(new CallableError.DecodeError({ cause }))),
+      Effect.flatMap(Effect.fail),
+    );
+  };
+  return run;
+};
+
+/**
+ * Builds the client of a Callable in no group, or of every Callable member of
+ * a Function Group.
+ *
+ * **When to use**
+ *
+ * Use to call Callables from the browser or any other client SDK program.
+ *
+ * **Details**
+ *
+ * Returns a record keyed by Callable name: `const { greet } = yield*
+ * CallableClient.make(Greet)` for a Callable in no group, and
+ * `const users = yield* CallableClient.make(Users)` for a group, where
+ * `users.create` calls `users-create`. A group's members of other kinds, which
+ * no client calls, are left out. The region of the
+ * {@link ClientFunctions.ClientFunctions} in context is bound once, here.
+ *
+ * Build a member's client from its group. A client built from the member on
+ * its own calls the name without the group's prefix, which the server doesn't
+ * export, and fails with `not-found`. Nothing checks this at runtime.
+ *
+ * Each call encodes the Payload with `Schema.toCodecJson`, sends it as is
+ * through the SDK's `httpsCallable`, and decodes the answer the same way.
+ *
+ * When the server answers with an error, the client strips the `functions/`
+ * prefix from its code and decodes its `details` against the declared errors
+ * that carry that code. It fails with the decoded error, so `Effect.catchTag`
+ * recovers from it. Every other failure is a
+ * {@link CallableError.CallableError}:
+ *
+ * - `EncodeError` when the Payload doesn't encode. Nothing is sent.
+ * - `DecodeError` when the success value doesn't decode, the `details` of
+ *   an error don't decode against the declared errors with its code, as after
+ *   the server and the client drift apart, or the answer isn't one the SDK
+ *   can read: not a JSON object, or one without `data`.
+ * - `ResponseError` when the server answers with a code no declared error
+ *   carries, or without details, as on a defect. `not-found` usually means a
+ *   wrong region, or a name the server doesn't export, such as a group's
+ *   member called without its group. A `deadline-exceeded` the server sends
+ *   is a `ResponseError` too.
+ * - `TransportError` when no answer arrived: a network failure, the SDK's
+ *   own timeout (`deadline-exceeded`), a cancelled call, or a deleted
+ *   Functions instance. The SDK appends the HTTP status of an answer to its
+ *   error's message as ` [<status>]`, and status 0 to a network failure. The
+ *   client treats an error without that suffix, or with status 0, as no
+ *   answer.
+ *
+ * Each call runs in a `kind: "client"` span named `CallableClient.<deployed
+ * name>`, such as `CallableClient.users-create`, with the attributes
+ * `rpc.system: "firebase_callable"`, `rpc.method` (the Callable's name),
+ * `rpc.service` (the group, for a member) and `faas.name` (the deployed name).
+ * The span isn't linked to the server's span of the same call: the two land in
+ * separate traces. It carries no uid; add one with `Effect.annotateCurrentSpan`
+ * around the call when you want it.
+ *
+ * @example Injecting a client as a service
+ * ```ts
+ * import { Context, Layer, Schema } from "effect";
+ * import { Callable } from "@visiolab/effect-firebase/functions";
+ * import { CallableClient } from "@visiolab/effect-firebase-client/functions";
+ *
+ * const Greet = Callable.make("greet", {
+ *   payload: { name: Schema.String },
+ *   success: Schema.String,
+ * });
+ *
+ * class GreetClient extends Context.Service<GreetClient, CallableClient.Client<typeof Greet>>()(
+ *   "app/GreetClient",
+ * ) {
+ *   static readonly layer = Layer.effect(GreetClient, CallableClient.make(Greet));
+ * }
+ * ```
+ *
+ * @example Calling the members of a group
+ * ```ts
+ * import { Effect, Schema } from "effect";
+ * import { Callable, FunctionGroup } from "@visiolab/effect-firebase/functions";
+ * import { CallableClient } from "@visiolab/effect-firebase-client/functions";
+ *
+ * const CreateUser = Callable.make("create", {
+ *   payload: { name: Schema.String },
+ *   success: Schema.String,
+ * });
+ *
+ * class Users extends FunctionGroup.make("users").add(CreateUser) {}
+ *
+ * const program = Effect.gen(function* () {
+ *   const users = yield* CallableClient.make(Users);
+ *   // Calls `users-create`.
+ *   return yield* users.create({ name: "Ada" });
+ * });
+ * ```
+ *
+ * @see {@link ClientFunctions.ClientFunctions} for the region and emulator it calls
+ * @see {@link Functions.make} for serving a Callable in no group
+ * @see {@link Functions.group} for serving the members of a group
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.3.0
+ */
+export const make = <T extends Callable.Any | FunctionGroup.Any>(
+  target: T,
+): Effect.Effect<Client<T>, never, ClientFunctions.ClientFunctions> =>
+  Effect.map(Effect.service(ClientFunctions.ClientFunctions), ({ instance }) => {
+    if (!FunctionGroup.isFunctionGroup(target)) {
+      const callable = target as Callable.Any;
+      return {
+        [callable.name]: method(
+          instance,
+          callable,
+          Callable.deployment(callable),
+          Callable.errorSchemas(callable),
+        ),
+      } as Client<T>;
+    }
+    const client: Record<string, ReturnType<typeof method>> = {};
+    for (const [name, member] of Object.entries(target.functions)) {
+      // Only Callables are called by a client.
+      if (member.kind !== "Callable") continue;
+      client[name] = method(
+        instance,
+        member as Callable.Any,
+        Callable.deployment(target, name),
+        Callable.errorSchemas(target, name),
+      );
+    }
+    return client as Client<T>;
+  });