add HttpApi modules to /platform (#3495)

Co-authored-by: Tim Smart <[email protected]>
Effect-TS · Aug 30, 2024 · 327cd82 · 327cd82
1 parent f114c96
commit 327cd82
Show file tree

Hide file tree

Showing 27 changed files with 6,398 additions and 307 deletions.
diff --git a/.changeset/curvy-clouds-battle.md b/.changeset/curvy-clouds-battle.md
@@ -0,0 1,10 @@
 ---
 "@effect/platform": patch
 ---
 
 add HttpApi modules
 
 The `HttpApi` family of modules provide a declarative way to define HTTP APIs.
 
 For more infomation see the README.md for the /platform package:<br />
 https://github.com/Effect-TS/effect/blob/main/packages/platform/README.md
diff --git a/.changeset/young-pugs-grow.md b/.changeset/young-pugs-grow.md
@@ -0,0 1,5 @@
 ---
 "effect": minor
 ---
 
 add Context.getOrElse api, for gettings a Tag's value with a fallback
diff --git a/.prettierrc.json b/.prettierrc.json
@@ -0,0 1,4 @@
 {
  "semi": false,
  "trailingComma": "none"
 }
diff --git a/packages/effect/src/Context.ts b/packages/effect/src/Context.ts
@@ -8,6 8,7 @@
  * @since 2.0.0
  */
 import type { Equal } from "./Equal.js"
 import type { LazyArg } from "./Function.js"
 import type { Inspectable } from "./Inspectable.js"
 import * as internal from "./internal/context.js"
 import type { Option } from "./Option.js"
@@ -263,6 264,18 @@ export const get: {
  <Services, T extends ValidTagsById<Services>>(self: Context<Services>, tag: T): Tag.Service<T>
 } = internal.get
 
 /**
  * Get a service from the context that corresponds to the given tag, or
  * use the fallback value.
  *
  * @since 3.7.0
  * @category getters
  */
 export const getOrElse: {
  <S, I, B>(tag: Tag<I, S>, orElse: LazyArg<B>): <Services>(self: Context<Services>) => S | B
  <Services, S, I, B>(self: Context<Services>, tag: Tag<I, S>, orElse: LazyArg<B>): S | B
 } = internal.getOrElse
 
 /**
  * Get a service from the context that corresponds to the given tag.
  * This function is unsafe because if the tag is not present in the context, a runtime error will be thrown.

diff --git a/packages/effect/src/internal/context.ts b/packages/effect/src/internal/context.ts
@@ -1,5 1,6 @@
 import type * as C from "../Context.js"
 import * as Equal from "../Equal.js"
 import type { LazyArg } from "../Function.js"
 import { dual } from "../Function.js"
 import * as Hash from "../Hash.js"
 import { format, NodeInspectSymbol, toJSON } from "../Inspectable.js"
@@ -209,6 210,17 @@ export const get: {
  <Services, T extends C.ValidTagsById<Services>>(self: C.Context<Services>, tag: T): C.Tag.Service<T>
 } = unsafeGet
 
 /** @internal */
 export const getOrElse = dual<
  <S, I, B>(tag: C.Tag<I, S>, orElse: LazyArg<B>) => <Services>(self: C.Context<Services>) => S | B,
  <Services, S, I, B>(self: C.Context<Services>, tag: C.Tag<I, S>, orElse: LazyArg<B>) => S | B
 >(3, (self, tag, orElse) => {
  if (!self.unsafeMap.has(tag.key)) {
  return orElse()
  }
  return self.unsafeMap.get(tag.key)! as any
 })
 
 /** @internal */
 export const getOption = dual<
  <S, I>(tag: C.Tag<I, S>) => <Services>(self: C.Context<Services>) => O.Option<S>,

diff --git a/packages/platform-node/examples/api.ts b/packages/platform-node/examples/api.ts
@@ -0,0 1,178 @@
 import {
  HttpApi,
  HttpApiBuilder,
  HttpApiClient,
  HttpApiEndpoint,
  HttpApiGroup,
  HttpApiSchema,
  HttpApiSecurity,
  HttpApiSwagger,
  HttpClient,
  HttpMiddleware,
  HttpServer,
  OpenApi
 } from "@effect/platform"
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
 import { Schema } from "@effect/schema"
 import { Context, Effect, Layer, Redacted } from "effect"
 import { createServer } from "node:http"
 
 class User extends Schema.Class<User>("User")({
  id: Schema.Number,
  name: Schema.String
 }) {}
 
 class CurrentUser extends Context.Tag("CurrentUser")<CurrentUser, User>() {}
 
 class Unauthorized extends Schema.TaggedError<Unauthorized>()("Unauthorized", {
  message: Schema.String
 }, HttpApiSchema.annotations({ status: 401 })) {}
 
 const security = HttpApiSecurity.bearer
 
 const securityMiddleware = HttpApiBuilder.middlewareSecurity(
  security,
  CurrentUser,
  (token) => Effect.succeed(new User({ id: 1000, name: `Authenticated with ${Redacted.value(token)}` }))
 )
 
 class UsersApi extends HttpApiGroup.make("users").pipe(
  HttpApiGroup.add(
  HttpApiEndpoint.get("findById", "/:id").pipe(
  HttpApiEndpoint.setPath(Schema.Struct({
  id: Schema.NumberFromString
  })),
  HttpApiEndpoint.setSuccess(User),
  HttpApiEndpoint.setHeaders(Schema.Struct({
  page: Schema.NumberFromString.pipe(
  Schema.optionalWith({ default: () => 1 })
  )
  })),
  HttpApiEndpoint.addError(Schema.String.pipe(
  HttpApiSchema.asEmpty({ status: 413, decode: () => "boom" })
  ))
  )
  ),
  HttpApiGroup.add(
  HttpApiEndpoint.post("create", "/").pipe(
  HttpApiEndpoint.setPayload(HttpApiSchema.Multipart(Schema.Struct({
  name: Schema.String
  }))),
  HttpApiEndpoint.setSuccess(User)
  )
  ),
  HttpApiGroup.add(
  HttpApiEndpoint.get("me", "/me").pipe(
  HttpApiEndpoint.setSuccess(User)
  )
  ),
  HttpApiGroup.add(
  HttpApiEndpoint.get("csv", "/csv").pipe(
  HttpApiEndpoint.setSuccess(HttpApiSchema.Text({
  contentType: "text/csv"
  }))
  )
  ),
  HttpApiGroup.add(
  HttpApiEndpoint.get("binary", "/binary").pipe(
  HttpApiEndpoint.setSuccess(HttpApiSchema.Uint8Array())
  )
  ),
  HttpApiGroup.add(
  HttpApiEndpoint.get("urlParams", "/url-params").pipe(
  HttpApiEndpoint.setSuccess(
  Schema.Struct({
  id: Schema.NumberFromString,
  name: Schema.String
  }).pipe(
  HttpApiSchema.withEncoding({
  kind: "UrlParams"
  })
  )
  )
  )
  ),
  HttpApiGroup.addError(Unauthorized),
  HttpApiGroup.prefix("/users"),
  OpenApi.annotate({ security })
 ) {}
 
 class MyApi extends HttpApi.empty.pipe(
  HttpApi.addGroup(UsersApi),
  OpenApi.annotate({
  title: "Users API",
  description: "API for managing users"
  })
 ) {}
 
 const UsersLive = HttpApiBuilder.group(MyApi, "users", (handlers) =>
  handlers.pipe(
  HttpApiBuilder.handle("create", (_) => Effect.succeed(new User({ ..._.payload, id: 123 }))),
  HttpApiBuilder.handle("findById", (_) =>
  Effect.as(
  HttpApiBuilder.securitySetCookie(
  HttpApiSecurity.apiKey({
  in: "cookie",
  key: "token"
  }),
  "secret123"
  ),
  new User({
  id: _.path.id,
  name: `John Doe (${_.headers.page})`
  })
  )),
  HttpApiBuilder.handle("me", (_) => CurrentUser),
  HttpApiBuilder.handle("csv", (_) => Effect.succeed("id,name\n1,John")),
  HttpApiBuilder.handle("urlParams", (_) =>
  Effect.succeed({
  id: 123,
  name: "John"
  })),
  HttpApiBuilder.handle("binary", (_) => Effect.succeed(new Uint8Array([1, 2, 3, 4, 5]))),
  securityMiddleware
  ))
 
 const ApiLive = HttpApiBuilder.api(MyApi).pipe(
  Layer.provide(UsersLive)
 )
 
 HttpApiBuilder.serve(HttpMiddleware.logger).pipe(
  Layer.provide(HttpApiSwagger.layer()),
  Layer.provide(HttpApiBuilder.middlewareOpenApi()),
  Layer.provide(ApiLive),
  Layer.provide(HttpApiBuilder.middlewareCors()),
  HttpServer.withLogAddress,
  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
  Layer.launch,
  NodeRuntime.runMain
 )
 
 Effect.gen(function*() {
  yield* Effect.sleep(2000)
  const client = yield* HttpApiClient.make(MyApi, {
  baseUrl: "http://localhost:3000"
  })
 
  const data = new FormData()
  data.append("name", "John")
  console.log("Multipart", yield* client.users.create({ payload: data }))
 
  const user = yield* client.users.findById({
  path: { id: 123 },
  headers: { page: 10 }
  })
  console.log("json", user)
 
  const csv = yield* client.users.csv()
  console.log("csv", csv)
 
  const urlParams = yield* client.users.urlParams()
  console.log("urlParams", urlParams)
 
  const binary = yield* client.users.binary()
  console.log("binary", binary)
 }).pipe(
  Effect.provide(HttpClient.layer),
  NodeRuntime.runMain
 )