@visiolab/effect-firebase 0.0.0-stage → 0.3.0

package/dist/functions/Callable.mjs

@@ -0,0 +1,450 @@
+import { __exportAll } from "../_virtual/_rolldown/runtime.mjs";
+import { deployedName, errorSchemas as errorSchemas$1, getErrorCode as getErrorCode$1, handler as handler$1, kind, make as make$1, serve as serve$1, spanAttributes, toLayer as toLayer$1 } from "./internal/callable.mjs";
+import { isFunctionGroup } from "./internal/functionGroup.mjs";
+import { Schema } from "effect";
+// src/functions/Callable.ts
+/**
+* Callables: server functions the client calls by name, declared once and
+* shared by the server and the client.
+*
+* A {@link Callable} is a contract: its name, its Payload and what it succeeds
+* with. The server implements it with {@link toLayer} and serves it with
+* `Functions.make` from `@visiolab/effect-firebase-functions`. The client
+* calls it with `CallableClient` from `@visiolab/effect-firebase-client`. This
+* module imports neither SDK, so the contract can live in code shared with the
+* browser.
+*
+* Values cross the wire as `Schema.toCodecJson` output, on both sides, so a
+* `Date` or a `bigint` arrives as itself.
+*
+* @example Declaring a Callable and implementing it
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Callable } from "@visiolab/effect-firebase/functions";
+*
+* const Greet = Callable.make("greet", {
+*   payload: { name: Schema.String },
+*   success: Schema.String,
+* });
+*
+* const GreetLive = Callable.toLayer(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+* ```
+*
+* @stability unstable
+* @since 0.3.0
+*/
+var Callable_exports = /* @__PURE__ */ __exportAll({
+	deployment: () => deployment,
+	errorCode: () => errorCode,
+	errorSchemas: () => errorSchemas,
+	getErrorCode: () => getErrorCode,
+	handler: () => handler,
+	make: () => make,
+	serve: () => serve,
+	toLayer: () => toLayer
+});
+/**
+* The group and the Callable that the arguments of an overload taking
+* `(callable, ...)` or `(group, name, ...)` name.
+*/
+const target = (args) => isFunctionGroup(args[0]) ? [args[0], args[0].functions[args[1]]] : [void 0, args[0]];
+/**
+* Declares a Callable.
+*
+* **When to use**
+*
+* Use to declare a server function once, in code that the server and the
+* client share.
+*
+* **Details**
+*
+* `payload` takes a schema or the fields of a struct, and defaults to
+* `Schema.Void`. `success` defaults to `Schema.Void`. `error` takes one
+* schema or an array; without it the Callable never fails with an error of
+* its own, and its client fails only with `CallableError`.
+*
+* All of them are sent through `Schema.toCodecJson`, so they must round-trip
+* through JSON. `Schema.Unknown` is the safe choice for "any JSON".
+* `Schema.Any` skips every check and is an escape hatch. A schema that can't
+* round-trip fails at runtime, not at compile time.
+*
+* An error is sent with the Firebase error code of its schema, `internal`
+* unless {@link errorCode} or its `callableErrorCode` annotation sets one.
+*
+* @example Declaring a Callable with a Payload and a success value
+* ```ts
+* import { Schema } from "effect";
+* import { Callable } from "@visiolab/effect-firebase/functions";
+*
+* const Greet = Callable.make("greet", {
+*   payload: { name: Schema.String, at: Schema.Date },
+*   success: Schema.Struct({ message: Schema.String }),
+* });
+* ```
+*
+* @example Declaring the errors a Callable can fail with
+* ```ts
+* import { Schema } from "effect";
+* import { Callable, CallableError } from "@visiolab/effect-firebase/functions";
+*
+* class NameTaken extends Schema.TaggedError<NameTaken>()(
+*   "NameTaken",
+*   { name: Schema.String },
+*   { callableErrorCode: "already-exists" },
+* ) {}
+*
+* const Register = Callable.make("register", {
+*   payload: { name: Schema.String },
+*   error: [NameTaken, CallableError.PermissionDenied],
+* });
+* ```
+*
+* @see {@link toLayer} for implementing the Callable on the server
+* @see {@link errorCode} for giving an error schema its code
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+* @see {@link DocumentTrigger.created} for declaring a Function a change to a document runs
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const make = (name, options) => {
+	const payload = options?.payload;
+	const error = options?.error;
+	return make$1({
+		kind,
+		error: new Set(error === void 0 ? [] : Schema.isSchema(error) ? [error] : error),
+		middlewares: /* @__PURE__ */ new Set(),
+		name,
+		payload: payload === void 0 ? Schema.Void : Schema.isSchema(payload) ? payload : Schema.Struct(payload),
+		success: options?.success ?? Schema.Void
+	});
+};
+/**
+* Implements a Callable as a Layer.
+*
+* **When to use**
+*
+* Use to write the server side of a Callable. The Layer is what
+* `Functions.make` or `Functions.group` from
+* `@visiolab/effect-firebase-functions` serves.
+*
+* **Details**
+*
+* Pass the Callable for a Callable in no group. Pass its group and its name
+* for a Callable member of a {@link FunctionGroup.FunctionGroup}: the Layer then
+* provides `Handler<"users", "create">`, which serves the member in that group
+* only. A Layer from the Callable on its own doesn't serve it in a group, and
+* a Callable in two groups needs a Layer for each.
+*
+* Takes the handler itself, or an Effect that builds it. The Effect runs once,
+* when the Layer is built, so do per-instance setup there.
+*
+* The Layer requires what the handler needs on each call and what building it
+* needs. Both are provided where the Layer is built: services built with the
+* Layer are shared by every call. What the Callable's middleware provides,
+* such as the `Caller`, and the {@link CallableRequest.CallableRequest} are
+* provided per call instead, so the Layer doesn't require them. Nor does it
+* require the middleware's implementations: those are required where the
+* chain runs.
+*
+* @example Implementing a Callable
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Callable } from "@visiolab/effect-firebase/functions";
+*
+* const Greet = Callable.make("greet", {
+*   payload: { name: Schema.String },
+*   success: Schema.String,
+* });
+*
+* const GreetLive = Callable.toLayer(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+* ```
+*
+* @example Building the handler once per instance
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Callable } from "@visiolab/effect-firebase/functions";
+*
+* const Greet = Callable.make("greet", {
+*   payload: { name: Schema.String },
+*   success: Schema.String,
+* });
+*
+* const GreetLive = Callable.toLayer(
+*   Greet,
+*   Effect.gen(function* () {
+*     const greeting = yield* Effect.succeed("Hello");
+*     return ({ name }) => Effect.succeed(`${greeting}, ${name}!`);
+*   }),
+* );
+* ```
+*
+* @example Implementing a member of a group
+* ```ts
+* import { Effect, Schema } from "effect";
+* import { Callable, FunctionGroup } from "@visiolab/effect-firebase/functions";
+*
+* const CreateUser = Callable.make("create", {
+*   payload: { name: Schema.String },
+*   success: Schema.String,
+* });
+*
+* class Users extends FunctionGroup.make("users").add(CreateUser) {}
+*
+* const CreateUserLive = Callable.toLayer(Users, "create", ({ name }) => Effect.succeed(name));
+* ```
+*
+* @see {@link make} for declaring the Callable
+* @see {@link serve} for running a call against the handler
+* @see {@link DocumentTrigger.toLayer} for implementing a Document Trigger
+* @see {@link FunctionGroup.make} for collecting Functions under one prefix
+*
+* @stability unstable
+* @category constructors
+* @since 0.3.0
+*/
+const toLayer = ((...args) => {
+	const [group, callable] = target(args);
+	return toLayer$1(group?.identifier, callable.name, args[group === void 0 ? 1 : 2]);
+});
+/**
+* Runs one call to a Callable, as it arrives on the wire. A building block for
+* the functions package. Most apps don't need it.
+*
+* **When to use**
+*
+* Use to serve Callables from a transport of your own. `Functions`
+* from `@visiolab/effect-firebase-functions` serves them through
+* `firebase-functions`.
+*
+* **Details**
+*
+* Pass the Callable for a Callable in no group, or its group and its name for
+* a Callable member of a {@link FunctionGroup.FunctionGroup}.
+*
+* Returns a function of the call's {@link CallableRequest.CallableRequest}. It
+* runs the middleware chain, the same one {@link handler} runs. Inside it, it
+* decodes the raw `data` with the Payload's `Schema.toCodecJson` and runs the
+* handler. It then encodes the success value with the success schema's
+* `Schema.toCodecJson`, so its result is plain JSON. The request is provided
+* to the chain. Give it a `rawRequest` built from your transport's HTTP
+* request, with `HttpServerRequest.fromWeb` from `effect/http/HttpServerRequest`.
+*
+* Requires the handler, every middleware implementation, and what the chain
+* still requires. They are read once, so a call needs nothing else.
+*
+* Every failure is a `CallableError` whose `ResponseError` reason is what to
+* answer with:
+*
+* - A declared error, or an error of a middleware, is sent with its schema's
+*   code, the error's `message` if it is a non-empty string, else its `_tag`,
+*   and the error encoded with its schema's `Schema.toCodecJson` as
+*   `details`.
+* - A raw Payload that doesn't decode is sent as `invalid-argument` with a
+*   generic message and no details. The `Schema.SchemaError` is logged at
+*   Debug.
+*
+* A defect, or a success or error value that doesn't encode, is a defect.
+* Answer it with a bare `internal`, so nothing of it reaches the caller.
+*
+* The `CallableError`'s `callable` is the deployed name: the Callable's name,
+* or `<group>-<name>` for a member of a group.
+*
+* @see {@link toLayer} for providing the handler
+* @see {@link handler} for running the handler in process, with typed values
+* @see {@link Functions.make} for serving through `firebase-functions`
+* @see {@link deployment} for the name and span attributes a transport uses
+* @see {@link DocumentTrigger.serve} for running an event of a Document Trigger
+*
+* @stability unstable
+* @category serving
+* @since 0.3.0
+*/
+const serve = ((...args) => serve$1(...target(args)));
+/**
+* Runs a Callable's handler in process, behind its middleware chain.
+*
+* **When to use**
+*
+* Use to test a handler and its middleware without the emulator and without
+* `firebase-functions`. Provide the same Layers you serve it with, or stub a
+* middleware with a Layer of your own.
+*
+* **Details**
+*
+* Pass the Callable for a Callable in no group, or its group and its name for
+* a Callable member of a {@link FunctionGroup.FunctionGroup}.
+*
+* Requires the handler, every middleware implementation, and what the chain
+* still requires. A middleware whose
+* `requires` no middleware outside it provides leaves that requirement here,
+* so a chain in the wrong order is a type error where the Layers are
+* provided.
+*
+* Yields a function of the Payload and a {@link CallableRequest.Input}: `{}`
+* for a signed-out call, `{ auth: { uid, token } }` for a signed-in one. It
+* encodes the Payload with `Schema.toCodecJson` as the request's raw `data`,
+* so middleware sees what it would see on the wire. The request's
+* `rawRequest` is the input's, or else a JSON `POST` of the encoded Payload to
+* `http://localhost/<deployed name>` (see
+* {@link CallableRequest.Input.rawRequest}). It runs the chain that
+* `Functions` runs, and fails with the Callable's declared errors and
+* those of its middleware. The success value is the handler's, not encoded.
+*
+* @example Running a handler behind Authenticated
+* ```ts
+* import { Effect, Layer, Schema } from "effect";
+* import { Callable, Caller } from "@visiolab/effect-firebase/functions";
+*
+* const WhoAmI = Callable.make("whoAmI", { success: Schema.String }).middleware(
+*   Caller.Authenticated,
+* );
+*
+* const WhoAmILive = Callable.toLayer(WhoAmI, () =>
+*   Effect.map(Effect.service(Caller.Caller), ({ uid }) => uid),
+* );
+*
+* const program = Effect.gen(function* () {
+*   const whoAmI = yield* Callable.handler(WhoAmI);
+*   // "ada"
+*   return yield* whoAmI(undefined, { auth: { uid: "ada", token: {} } });
+* }).pipe(Effect.provide(Layer.merge(WhoAmILive, Caller.Authenticated.layer)));
+* ```
+*
+* @see {@link serve} for running a call as it arrives on the wire
+* @see {@link toLayer} for providing the handler
+* @see {@link Functions.make} for serving the same chain through `firebase-functions`
+*
+* @stability unstable
+* @category serving
+* @since 0.3.0
+*/
+const handler = ((...args) => handler$1(...target(args)));
+/**
+* Sets the Firebase error code a Callable answers with when it fails with
+* errors of this schema.
+*
+* **When to use**
+*
+* Use to give a code to an error schema you don't own. For an error class of
+* your own, set `callableErrorCode` in its annotations instead, so every
+* Callable that lists it uses the same code.
+*
+* **Details**
+*
+* An error schema without a code is sent as `internal`. The client reads the
+* code to find the declared errors to decode the answer against, so the code
+* is part of the contract.
+*
+* @example Giving codes to error schemas
+* ```ts
+* import { Schema } from "effect";
+* import { Callable } from "@visiolab/effect-firebase/functions";
+*
+* class NameTaken extends Schema.TaggedError<NameTaken>()(
+*   "NameTaken",
+*   { name: Schema.String },
+*   { callableErrorCode: "already-exists" },
+* ) {}
+*
+* class Banned extends Schema.TaggedError<Banned>()("Banned", {}) {}
+*
+* const Register = Callable.make("register", {
+*   payload: { name: Schema.String },
+*   error: [NameTaken, Banned.pipe(Callable.errorCode("permission-denied"))],
+* });
+* ```
+*
+* @see {@link getErrorCode} for reading the code back
+* @see {@link make} for declaring the errors a Callable fails with
+*
+* @stability unstable
+* @category errors
+* @since 0.3.0
+*/
+const errorCode = (code) => (self) => self.annotate({ callableErrorCode: code });
+/**
+* Reads the Firebase error code of an error schema: what {@link errorCode} or
+* its `callableErrorCode` annotation set, else `internal`. A building block
+* for the functions and client packages. Most apps don't need it.
+*
+* **When to use**
+*
+* Use when serving or calling Callables from a transport of your own.
+*
+* @see {@link errorCode} for setting the code
+* @see {@link errorSchemas} for the schemas a call can be answered with
+*
+* @stability unstable
+* @category errors
+* @since 0.3.0
+*/
+const getErrorCode = getErrorCode$1;
+/**
+* The schemas of every error a call can be answered with: the Callable's
+* declared errors, then those of its middleware. A building block for the
+* client package. Most apps don't need it.
+*
+* **When to use**
+*
+* Use when calling Callables from a transport of your own, to decode an
+* error's `details` against the schemas that carry its code.
+*
+* **Details**
+*
+* Pass the Callable for a Callable in no group, or its group and its name for
+* a Callable member of a {@link FunctionGroup.FunctionGroup}.
+*
+* @see {@link getErrorCode} for the code of each schema
+* @see {@link deployment} for the name a transport calls
+*
+* @stability unstable
+* @category errors
+* @since 0.3.0
+*/
+const errorSchemas = ((...args) => errorSchemas$1(target(args)[1]));
+/**
+* Returns the {@link Deployment} of a Callable: its deployed name and its span
+* attributes. A building block of the functions and client packages, which
+* agree on both through it. Most apps don't need it.
+*
+* **When to use**
+*
+* Use when serving or calling Callables from a transport of your own.
+* `Functions` and `CallableClient` already use it.
+*
+* **Details**
+*
+* Pass the Callable for a Callable in no group, or its group and its name for
+* a Callable member of a {@link FunctionGroup.FunctionGroup}.
+*
+* @example Reading the deployed name of a member
+* ```ts
+* import { Schema } from "effect";
+* import { Callable, FunctionGroup } from "@visiolab/effect-firebase/functions";
+*
+* const CreateUser = Callable.make("create", { payload: { name: Schema.String } });
+*
+* class Users extends FunctionGroup.make("users").add(CreateUser) {}
+*
+* // "users-create"
+* const { name } = Callable.deployment(Users, "create");
+* ```
+*
+* @see {@link serve} for running a call on the server
+* @see {@link errorSchemas} for the errors a call can be answered with
+* @see {@link DocumentTrigger.deployment} for where a Document Trigger is deployed
+*
+* @stability unstable
+* @category serving
+* @since 0.3.0
+*/
+const deployment = ((...args) => {
+	const [group, callable] = target(args);
+	return {
+		name: deployedName(group, callable),
+		attributes: spanAttributes(group, callable)
+	};
+});
+export { Callable_exports, deployment, errorCode, errorSchemas, getErrorCode, handler, make, serve, toLayer };