effect 4.0.0-beta.99 → 4.0.0-rc.109

package/ai-docs/src/40_sql/10_basics.ts

@@ -0,0 +1,175 @@
+/**
+ * @title Getting started with SQL
+ *
+ * Define a schema-backed domain model, run migrations against a SQLite
+ * database, and expose a derived repository through a service.
+ */
+import { NodeRuntime } from "@effect/platform-node"
+import { SqliteClient, SqliteMigrator } from "@effect/sql-sqlite-node"
+import { Context, Effect, Layer, Schema } from "effect"
+import { Model } from "effect/unstable/schema"
+import { SqlClient, SqlModel, SqlSchema } from "effect/unstable/sql"
+
+// Use a branded string for the group id, so it cannot be mixed up with other
+// string ids in the application.
+export const GroupId = Schema.String.pipe(Schema.brand("GroupId"))
+export type GroupId = typeof GroupId.Type
+
+// `Model.Class` defines a domain model with variants for the database and JSON
+// boundaries. The single field declaration is the source of truth, and each
+// variant only contains the fields that make sense for that operation:
+//
+// - `Group` / `Group.insert` / `Group.update` for the database
+// - `Group.json` / `Group.jsonCreate` / `Group.jsonUpdate` for JSON APIs
+export class Group extends Model.Class<Group>("Group")({
+  // A UUID v4 primary key that is generated by the application on insert
+  id: Model.UuidV4Insert(GroupId),
+  name: Schema.NonEmptyString,
+  // `Model.FieldExcept` removes a field from the given variants. The slug is
+  // chosen when the group is created and is immutable afterwards, so it is
+  // removed from the update variants.
+  slug: Schema.NonEmptyString.pipe(Model.FieldExcept(["update", "jsonUpdate"])),
+  // `Model.FieldOnly` keeps a field in only the given variants. Internal notes
+  // live in the database and are never exposed through the JSON variants.
+  notes: Schema.NullOr(Schema.String).pipe(Model.FieldOnly(["select", "insert"])),
+  // `Model.Field` gives full control over the individual variants. The member
+  // count is maintained by the database, so the application can read it but
+  // never writes it.
+  memberCount: Model.Field({
+    select: Schema.Int,
+    json: Schema.Int
+  }),
+  // `createdAt` is set to the current time on insert, and `updatedAt` is
+  // refreshed on every update. Both are stored as strings, which suits SQLite.
+  createdAt: Model.DateTimeInsert,
+  updatedAt: Model.DateTimeUpdate
+}) {}
+
+export class GroupNotFound extends Schema.TaggedError<GroupNotFound>()("GroupNotFound", {
+  id: GroupId
+}) {}
+
+// The SqlClient layer determines which database you are talking to. Swap this
+// layer for `@effect/sql-pg`, `@effect/sql-mysql2` etc. to target another
+// database without changing the rest of the code.
+const SqlLayer = SqliteClient.layer({ filename: ":memory:" })
+
+// Migrations are effects keyed by `<id>_<name>` that run once, in id order. A
+// real application would keep each migration in its own file and load them
+// with `SqliteMigrator.fromFileSystem` instead of an inline record.
+const MigratorLayer = SqliteMigrator.layer({
+  loader: SqliteMigrator.fromRecord({
+    "0001_create_groups": Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+      yield* sql`
+        CREATE TABLE groups (
+          id TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          slug TEXT NOT NULL,
+          notes TEXT,
+          memberCount INTEGER NOT NULL DEFAULT 0,
+          createdAt TEXT NOT NULL,
+          updatedAt TEXT NOT NULL
+        )
+      `
+    })
+  })
+})
+
+// Combine the database client with the migrations, so anything built on top of
+// `SqlLive` sees a fully migrated database.
+const SqlLive = MigratorLayer.pipe(Layer.provideMerge(SqlLayer))
+
+// Wrap data access in a service, so the rest of the application depends on
+// `Groups` instead of the database directly.
+export class Groups extends Context.Service<Groups, {
+  create(name: string, slug: string): Effect.Effect<Group>
+  rename(id: GroupId, name: string): Effect.Effect<Group, GroupNotFound>
+  findById(id: GroupId): Effect.Effect<Group, GroupNotFound>
+  readonly list: Effect.Effect<Array<Group>>
+}>()("app/Groups") {
+  static readonly layer = Layer.effect(
+    Groups,
+    Effect.gen(function*() {
+      const sql = yield* SqlClient.SqlClient
+
+      // `SqlModel.makeRepository` derives insert / update / findById / delete
+      // operations from the model, using the matching variant schema for each
+      // operation.
+      const repo = yield* SqlModel.makeRepository(Group, {
+        tableName: "groups",
+        spanPrefix: "Groups",
+        idColumn: "id"
+      })
+
+      // For queries the repository does not cover, combine the `sql` tag with
+      // `SqlSchema` to decode the rows using the model schema.
+      const listAll = SqlSchema.findAll({
+        Request: Schema.Void,
+        Result: Group,
+        execute: () => sql`SELECT * FROM groups ORDER BY createdAt`
+      })
+
+      // Use `Effect.fn` to give each method a named span for observability.
+      const create = Effect.fn("Groups.create")((name: string, slug: string) =>
+        // `Group.insert.makeEffect` fills in the generated id and timestamps
+        // using the Effect clock, so tests can control them with `TestClock`.
+        Group.insert.makeEffect({ name, slug, notes: null }).pipe(
+          Effect.flatMap(repo.insert),
+          // Database and encoding failures are unexpected here, so treat
+          // them as defects to keep the service interface focused on domain
+          // errors.
+          Effect.orDie
+        )
+      )
+
+      const rename = Effect.fn("Groups.rename")((id: GroupId, name: string) =>
+        Group.update.makeEffect({ id, name }).pipe(
+          Effect.flatMap(repo.update),
+          Effect.orDie
+        )
+      )
+
+      const findById = Effect.fn("Groups.findById")((id: GroupId) =>
+        repo.findById(id).pipe(
+          Effect.catchTags({
+            NoSuchElementError: () => new GroupNotFound({ id }),
+            SchemaError: Effect.die,
+            SqlError: Effect.die
+          })
+        )
+      )
+
+      const list = listAll().pipe(
+        Effect.orDie,
+        Effect.withSpan("Groups.list")
+      )
+
+      return Groups.of({ create, rename, findById, list })
+    })
+  ).pipe(
+    // Provide the layers locally, so lots of messy wiring doesn't need to
+    // happen in the "main" entrypoint of the application.
+    Layer.provide(SqlLive)
+  )
+}
+
+const program = Effect.gen(function*() {
+  const groups = yield* Groups
+
+  const engineering = yield* groups.create("Engineering", "engineering")
+  const design = yield* groups.create("Design", "design")
+
+  yield* groups.rename(design.id, "Product Design")
+
+  const found = yield* groups.findById(engineering.id)
+  yield* Effect.log("found group", found)
+
+  const all = yield* groups.list
+  yield* Effect.log(`total groups: ${all.length}`)
+})
+
+program.pipe(
+  Effect.provide(Groups.layer),
+  NodeRuntime.runMain
+)

package/ai-docs/src/40_sql/index.md

@@ -0,0 +1,6 @@
+## Working with SQL databases
+
+Use the `effect/unstable/sql` modules together with a driver package such as
+`@effect/sql-sqlite-node` to access SQL databases. Define domain models with
+`Model.Class` to derive schemas for the database and JSON boundaries, run
+migrations, and write type-safe queries.

package/ai-docs/src/50_http-client/10_basics.ts

@@ -0,0 +1,102 @@
+/**
+ * @title Getting started with HttpClient
+ *
+ * Define a service that uses the HttpClient module to fetch data from an external API
+ */
+import { Context, Effect, flow, Layer, Schedule, Schema } from "effect"
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
+
+class Todo extends Schema.Class<Todo>("Todo")({
+  userId: Schema.Int,
+  id: Schema.Int,
+  title: Schema.String,
+  completed: Schema.Boolean
+}) {}
+
+export class JsonPlaceholder extends Context.Service<JsonPlaceholder, {
+  readonly allTodos: Effect.Effect<ReadonlyArray<Todo>, JsonPlaceholderError>
+  getTodo(id: number): Effect.Effect<Todo, JsonPlaceholderError>
+  createTodo(todo: Omit<Todo, "id">): Effect.Effect<Todo, JsonPlaceholderError>
+}>()("app/JsonPlaceholder") {
+  static readonly layer = Layer.effect(
+    JsonPlaceholder,
+    Effect.gen(function*() {
+      // Access the HttpClient service, and apply some common middleware to all
+      // requests:
+      const client = (yield* HttpClient.HttpClient).pipe(
+        // Add a base URL to all requests made with this client, and set the
+        // Accept header to expect JSON responses
+        HttpClient.mapRequest(flow(
+          HttpClientRequest.prependUrl("https://jsonplaceholder.typicode.com"),
+          HttpClientRequest.acceptJson
+        )),
+        // Fail if the response status is not 2xx
+        HttpClient.filterStatusOk,
+        // Retry transient errors (network issues, 5xx responses) with an
+        // exponential backoff.
+        //
+        // See the schedule documentation for more complex retry strategies.
+        HttpClient.retryTransient({
+          schedule: Schedule.exponential(100),
+          times: 3
+        })
+      )
+
+      const allTodos = client.get("/todos").pipe(
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(Schema.Array(Todo))),
+        Effect.mapError((cause) => new JsonPlaceholderError({ cause })),
+        Effect.withSpan("JsonPlaceholder.allTodos")
+      )
+
+      // Use the HttpClient to fetch a todo item by id, and decode the response
+      // using the Todo schema.
+      const getTodo = Effect.fn("JsonPlaceholder.getTodo")(function*(id: number) {
+        // Annotate the current span with the id of the todo being fetched, so
+        // that it shows up in telemetry for this request.
+        yield* Effect.annotateCurrentSpan({ id })
+
+        const todo = yield* client.get(`/todos/${id}`, {
+          // You can pass additional options to individual requests.
+          // There are options for query parameters, request body, headers, and
+          // more.
+          urlParams: { format: "json" }
+        }).pipe(
+          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
+          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
+        )
+
+        return todo
+      })
+
+      // You can use the HttpClientRequest module to build up more complex
+      // requests:
+      const createTodo = Effect.fn("JsonPlaceholder.createTodo")(function*(todo: Omit<Todo, "id">) {
+        yield* Effect.annotateCurrentSpan({ title: todo.title })
+
+        const createdTodo = yield* HttpClientRequest.post("/todos").pipe(
+          // The HttpClientRequest module has many helper functions for building requests.
+          HttpClientRequest.setUrlParams({ format: "json" }),
+          HttpClientRequest.bodyJsonUnsafe(todo),
+          client.execute,
+          Effect.flatMap(HttpClientResponse.schemaBodyJson(Todo)),
+          Effect.mapError((cause) => new JsonPlaceholderError({ cause }))
+        )
+
+        return createdTodo
+      })
+
+      return JsonPlaceholder.of({
+        allTodos,
+        getTodo,
+        createTodo
+      })
+    })
+  ).pipe(
+    // Provide the fetch-based HttpClient implementation
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+export class JsonPlaceholderError extends Schema.TaggedError<JsonPlaceholderError>()("JsonPlaceholderError", {
+  cause: Schema.Defect()
+}) {}

package/ai-docs/src/50_http-client/index.md

@@ -0,0 +1,3 @@
+## Effect HttpClient
+
+Build http clients with the `HttpClient` module.

package/ai-docs/src/51_http-server/10_basics.ts

@@ -0,0 +1,118 @@
+/**
+ * @title Getting started with HttpApi
+ *
+ * Define a schema-first API, implement handlers, secure endpoints with
+ * middleware, serve it over HTTP, and call it using a generated typed client.
+ */
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
+import { Context, Effect, flow, Layer, Schedule } from "effect"
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpRouter, HttpServer } from "effect/unstable/http"
+import { HttpApiBuilder, HttpApiClient, HttpApiMiddleware, HttpApiScalar } from "effect/unstable/httpapi"
+import { createServer } from "node:http"
+// Api definitions should **always** be seperate from the server implementation,
+// so that they can be shared between the server and client without leaking
+// server code into clients.
+// Ideally, the would use a seperate package in a monorepo.
+import { Api } from "./fixtures/api/Api.ts"
+import { Authorization } from "./fixtures/api/Authorization.ts"
+import { UsersApiHandlers } from "./fixtures/server/Users/http.ts"
+
+// This walkthrough focuses on runtime wiring and typed client usage.
+// See the fixture files for the API schemas, endpoint definitions and handlers:
+
+const SystemApiHandlers = HttpApiBuilder.group(
+  Api,
+  "system",
+  Effect.fn(function*(handlers) {
+    return handlers.handleAll({
+      health: () => Effect.void
+    })
+  })
+)
+
+const ApiRoutes = HttpApiBuilder.layer(Api, {
+  openapiPath: "/openapi.json"
+}).pipe(
+  // Provide all the handler Layers for the API.
+  Layer.provide([UsersApiHandlers, SystemApiHandlers])
+)
+
+// Define a /docs route that serves scalar documentation
+const DocsRoute = HttpApiScalar.layer(Api, {
+  path: "/docs"
+})
+
+// Merge all the http routes together
+const AllRoutes = Layer.mergeAll(ApiRoutes, DocsRoute)
+
+// Create an HTTP server Layer that serves the API routes.
+//
+// Here we are using the NodeHttpServer, but you could also use the
+// BunHttpServer
+export const HttpServerLayer = HttpRouter.serve(AllRoutes).pipe(
+  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 }))
+)
+
+// Then run the server using Layer.launch
+Layer.launch(HttpServerLayer).pipe(
+  NodeRuntime.runMain
+)
+
+// Or create a web handler, which can be used in serverless environments
+export const { handler, dispose } = HttpRouter.toWebHandler(AllRoutes.pipe(
+  Layer.provide(HttpServer.layerServices)
+))
+
+// -----------------
+// Client side setup
+// -----------------
+
+export const AuthorizationClient = HttpApiMiddleware.layerClient(
+  Authorization,
+  Effect.fn(function*({ next, request }) {
+    // Here you can modify the request and pass it down the middleware chain.
+    // This is where you would add authentication tokens, custom headers, etc.
+    // For this example, we just add a hardcoded bearer token to all requests.
+    return yield* next(HttpClientRequest.bearerToken(request, "dev-token"))
+  })
+)
+
+// Define the HttpApiClient service, which will be used to make requests to the
+// API.
+export class ApiClient extends Context.Service<ApiClient, HttpApiClient.ForApi<typeof Api>>()("acme/ApiClient") {
+  static readonly layer = Layer.effect(
+    ApiClient,
+    HttpApiClient.make(Api, {
+      // Use transformClient to apply middleware to the generated client. This
+      // is useful for settings the base url and applying retry policies.
+      transformClient: (client) =>
+        client.pipe(
+          HttpClient.mapRequest(flow(
+            HttpClientRequest.prependUrl("http://localhost:3000")
+          )),
+          HttpClient.retryTransient({
+            schedule: Schedule.exponential(100),
+            times: 3
+          })
+        )
+    })
+  ).pipe(
+    // Provide the client implementation of the Authorization middleware, which
+    // is required.
+    Layer.provide(AuthorizationClient),
+    // Supply a HttpClient implementation to use for making requests. Here we
+    // use the FetchHttpClient, but you could also use the NodeHttpClient or
+    // BunHttpClient.
+    Layer.provide(FetchHttpClient.layer)
+  )
+}
+
+// The generated client mirrors your API definition, so renames and schema
+// changes are checked end-to-end at compile time.
+export const callApi = Effect.gen(function*() {
+  const client = yield* ApiClient
+
+  yield* client.health()
+}).pipe(
+  Effect.provide(ApiClient.layer)
+)

package/ai-docs/src/51_http-server/20_testing.ts

@@ -0,0 +1,100 @@
+/**
+ * @title Testing HttpApi implementations
+ *
+ * Test handlers through an in-memory typed client with `HttpApiTest`, without
+ * starting an HTTP server or touching a real database.
+ */
+import { assert, layer } from "@effect/vitest"
+import { Effect, Layer } from "effect"
+import { HttpClientRequest, HttpServer } from "effect/unstable/http"
+import { HttpApiMiddleware, HttpApiTest } from "effect/unstable/httpapi"
+import { Api } from "./fixtures/api/Api.ts"
+import { Authorization } from "./fixtures/api/Authorization.ts"
+import { UserId } from "./fixtures/domain/User.ts"
+import { AuthorizationLayer } from "./fixtures/server/Authorization.ts"
+import { Users } from "./fixtures/server/Users.ts"
+import { UsersApiHandlersNoDeps } from "./fixtures/server/Users/http.ts"
+
+// Provide the handlers with the in-memory `Users` implementation, so the full
+// HTTP pipeline is exercised without any SQL. The Authorization middleware is
+// provided with `Layer.provideMerge`, because the HTTP pipeline also resolves
+// it when the routes are built.
+const HandlersLayer = UsersApiHandlersNoDeps.pipe(
+  Layer.provide(Users.layerMemory),
+  Layer.provideMerge(AuthorizationLayer)
+)
+
+// The client-side Authorization middleware supplies the bearer token.
+// Providing different middleware implementations lets the tests cover both
+// authorized and unauthorized requests.
+const AuthorizationMiddlewareGood = HttpApiMiddleware.layerClient(
+  Authorization,
+  ({ next, request }) => next(HttpClientRequest.bearerToken(request, "dev-token"))
+)
+
+const AuthorizationMiddlewareBad = HttpApiMiddleware.layerClient(
+  Authorization,
+  // Forward the request without attaching a token
+  ({ next, request }) => next(request)
+)
+
+// `HttpApiTest.groups` builds a typed client wired directly to the handlers of
+// the selected groups, using the same request encoding, routing, and response
+// decoding as a real server.
+const makeClient = HttpApiTest.groups(Api, ["users"])
+
+// `HttpServer.layerServices` provides the platform services the HTTP pipeline
+// needs in tests.
+layer(Layer.mergeAll(HandlersLayer, HttpServer.layerServices))("UsersApi", (it) => {
+  it.effect("lists, fetches, and creates users", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const created = yield* client.users.create({
+        payload: { name: "Alice", email: "alice@acme.dev" }
+      })
+      assert.strictEqual(created.name, "Alice")
+
+      const fetched = yield* client.users.getById({
+        params: { id: created.id }
+      })
+      assert.deepStrictEqual(fetched, created)
+
+      const all = yield* client.users.list({ query: {} })
+      assert.isTrue(all.some((user) => user.id === created.id))
+    }).pipe(Effect.provide(AuthorizationMiddlewareGood)))
+
+  it.effect("returns a 404 for a missing user", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      // Use Effect.flip to assert on the error channel
+      const error = yield* client.users.getById({
+        params: { id: UserId.make("019845e1-682f-4b02-a706-3b2422d13aec") }
+      }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "UserNotFound")
+    }).pipe(Effect.provide(AuthorizationMiddlewareGood)))
+
+  it.effect("rejects requests without a valid bearer token", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const error = yield* client.users.list({ query: {} }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "Unauthorized")
+    }).pipe(Effect.provide(AuthorizationMiddlewareBad)))
+
+  it.effect("rejects requests with an invalid bearer token", () =>
+    Effect.gen(function*() {
+      const client = yield* makeClient
+
+      const error = yield* client.users.getById({
+        params: { id: UserId.make("019845e1-682f-4b02-a706-3b2422d13aec") }
+      }).pipe(Effect.flip)
+      assert.strictEqual(error._tag, "Unauthorized")
+    }).pipe(
+      Effect.provide(HttpApiMiddleware.layerClient(
+        Authorization,
+        ({ next, request }) => next(HttpClientRequest.bearerToken(request, "wrong-token"))
+      ))
+    ))
+})

package/ai-docs/src/51_http-server/fixtures/api/Api.ts

@@ -0,0 +1,14 @@
+import { HttpApi, OpenApi } from "effect/unstable/httpapi"
+import { SystemApi } from "./System.ts"
+import { UsersApiGroup } from "./Users.ts"
+
+// Defined the root API, which combines all of the groups together. This is the
+// API that you will serve and generate clients for. You can also annotate the
+// API with OpenAPI metadata.
+export class Api extends HttpApi.make("user-api")
+  .add(UsersApiGroup)
+  .add(SystemApi)
+  .annotateMerge(OpenApi.annotations({
+    title: "Acme User API"
+  }))
+{}

package/ai-docs/src/51_http-server/fixtures/api/Authorization.ts

@@ -0,0 +1,36 @@
+import { Context, Schema } from "effect"
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi"
+import type { User } from "../domain/User.ts"
+
+export class CurrentUser extends Context.Service<CurrentUser, User>()("acme/HttpApi/Authorization/CurrentUser") {}
+
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
+  "Unauthorized",
+  {
+    message: Schema.String
+  },
+  // You can define error status codes directly on the error class
+  { httpApiStatus: 401 }
+) {}
+
+export class Authorization extends HttpApiMiddleware.Service<Authorization, {
+  // Middleware can provide services to other middleware and endpoints, which is
+  // useful for things like authentication, where you want to inject the current
+  // user into the context for other endpoints to consume.
+  provides: CurrentUser
+  // If your middleware requires dependencies from other middleware, you can
+  // specify those as well.
+  requires: never
+}>()("acme/HttpApi/Authorization", {
+  // This middleware requires clients to also provide an implementation, to
+  // inject a api key
+  requiredForClient: true,
+  // Middleware can optionally define security schemes, which are used to
+  // generate OpenAPI docs and decode credientials from incoming requests for
+  // you.
+  security: {
+    bearer: HttpApiSecurity.bearer
+  },
+  // Middlware can specify errors that it may raise
+  error: Unauthorized
+}) {}

package/ai-docs/src/51_http-server/fixtures/api/System.ts

@@ -0,0 +1,10 @@
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi"
+
+// Top level groups are added to the root of the derived HttpApiClient.
+//
+// `client.health()`
+export class SystemApi extends HttpApiGroup.make("system", { topLevel: true }).add(
+  HttpApiEndpoint.get("health", "/health", {
+    success: HttpApiSchema.NoContent
+  })
+) {}

package/ai-docs/src/51_http-server/fixtures/api/Users.ts

@@ -0,0 +1,107 @@
+import { Schema } from "effect"
+import { HttpApiEndpoint, HttpApiError, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { User, UserId } from "../domain/User.ts"
+import { SearchQueryTooShort, UserNotFound } from "../domain/UserErrors.ts"
+import { Authorization } from "./Authorization.ts"
+
+export class UsersApiGroup extends HttpApiGroup.make("users")
+  .add(
+    HttpApiEndpoint.get("list", "/", {
+      query: {
+        search: Schema.optional(Schema.String)
+      },
+      // Use the `json` variant of the model for API responses. It shares the
+      // field declarations with the database variants, but can encode values
+      // differently where needed.
+      success: Schema.Array(User.json)
+    }),
+    HttpApiEndpoint.get("search", "/search", {
+      // For get requests, payload uses the query string
+      payload: {
+        search: Schema.String
+      },
+      success: [
+        Schema.Array(User.json),
+        Schema.String.pipe(HttpApiSchema.asText({
+          contentType: "text/csv"
+        }))
+      ],
+      error: [
+        SearchQueryTooShort.pipe(
+          // If you want an error to return no content, you can use
+          // `HttpApiSchema.asNoContent` and provide a decoder that transforms the
+          // error into the appropriate type.
+          HttpApiSchema.asNoContent({
+            decode: () => new SearchQueryTooShort()
+          })
+        ),
+        // You can also add some of the built in `HttpApiError`s to handle common
+        // error cases like bad requests, unauthorized, etc.
+        HttpApiError.RequestTimeoutNoContent
+      ]
+    }),
+    HttpApiEndpoint.get("getById", "/:id", {
+      params: {
+        // Path parameter values are automatically coerced from their string
+        // form using `Schema.toCodecStringTree`, so schemas that decode from
+        // other types (like numbers) work here as well.
+        id: UserId
+      },
+      success: User.json,
+      error: UserNotFound.pipe(
+        // If you want an error to return no content, you can use
+        // `HttpApiSchema.asNoContent` and provide a decoder that transforms the
+        // error into the appropriate type.
+        HttpApiSchema.asNoContent({
+          decode: () => new UserNotFound()
+        })
+      )
+    }),
+    HttpApiEndpoint.post("create", "/", {
+      // For post requests, payload uses the request body. It defaults to JSON,
+      // but you can specify other content types as well using
+      // `HttpApiSchema.asText`, `HttpApiSchema.asMultipart`, etc.
+      //
+      // The `jsonCreate` variant only exposes the fields clients are allowed
+      // to provide, so the generated id and timestamps cannot be set here.
+      payload: User.jsonCreate,
+      success: User.json
+    }),
+    HttpApiEndpoint.patch("update", "/:id", {
+      params: {
+        id: UserId
+      },
+      // The `jsonUpdate` variant similarly excludes the id and the managed
+      // timestamps from the update payload.
+      payload: User.jsonUpdate,
+      success: User.json,
+      error: UserNotFound.pipe(
+        HttpApiSchema.asNoContent({
+          decode: () => new UserNotFound()
+        })
+      )
+    }),
+    HttpApiEndpoint.get("me", "/me", {
+      success: User.json,
+      error: UserNotFound.pipe(HttpApiSchema.status(404))
+    })
+  )
+  // You can apply middleware to entire groups, which is useful for things like
+  // authentication and authorization.
+  //
+  // You can also apply middleware to individual endpoints if you need more
+  // fine-grained control.
+  .middleware(Authorization)
+  // To add a common prefix to all endpoints in a group, you can use the `prefix`
+  // method. This is useful for grouping related endpoints together under a common
+  // path segment. In this case, all endpoints in the `UsersApiGroup` will be
+  // prefixed with `/users`.
+  .prefix("/users")
+  // You can add OpenAPI annotations to groups, endpoints, and even parameters and
+  // request bodies. These will be merged together to generate the final OpenAPI
+  // docs for the API
+  .annotateMerge(OpenApi.annotations({
+    title: "Users",
+    description: "User management endpoints"
+  }))
+{}