@effect/platform 0.62.4 → 0.63.0

package/src/HttpApiSchema.ts

@@ -0,0 +1,384 @@
+/**
+ * @since 1.0.0
+ */
+import * as AST from "@effect/schema/AST"
+import * as Schema from "@effect/schema/Schema"
+import type { Brand } from "effect/Brand"
+import type { LazyArg } from "effect/Function"
+import { constVoid, dual } from "effect/Function"
+import * as Struct from "effect/Struct"
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const AnnotationMultipart: unique symbol = Symbol.for(
+  "@effect/platform/HttpApiSchema/AnnotationMultipart"
+)
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const AnnotationStatus: unique symbol = Symbol.for("@effect/platform/HttpApiSchema/AnnotationStatus")
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const AnnotationEmptyDecodeable: unique symbol = Symbol.for(
+  "@effect/platform/HttpApiSchema/AnnotationEmptyDecodeable"
+)
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const AnnotationEncoding: unique symbol = Symbol.for("@effect/platform/HttpApiSchema/AnnotationEncoding")
+
+const mergedAnnotations = (ast: AST.AST): Record<symbol, unknown> =>
+  ast._tag === "Transformation" ?
+    {
+      ...ast.to.annotations,
+      ...ast.annotations
+    } :
+    ast.annotations
+
+const getAnnotation = <A>(ast: AST.AST, key: symbol): A | undefined => mergedAnnotations(ast)[key] as A
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const getStatus = (ast: AST.AST, defaultStatus: number): number =>
+  getAnnotation<number>(ast, AnnotationStatus) ?? defaultStatus
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const getEmptyDecodeable = (ast: AST.AST): boolean =>
+  getAnnotation<boolean>(ast, AnnotationEmptyDecodeable) ?? false
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const getMultipart = (ast: AST.AST): boolean => getAnnotation<boolean>(ast, AnnotationMultipart) ?? false
+
+const encodingJson: Encoding = {
+  kind: "Json",
+  contentType: "application/json"
+}
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const getEncoding = (ast: AST.AST): Encoding => getAnnotation<Encoding>(ast, AnnotationEncoding) ?? encodingJson
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const annotations = <A>(
+  annotations: Schema.Annotations.Schema<NoInfer<A>> & {
+    readonly status?: number | undefined
+  }
+): Schema.Annotations.Schema<A> => {
+  const result: Record<symbol, unknown> = Struct.omit(annotations, "status")
+  if (annotations.status !== undefined) {
+    result[AnnotationStatus] = annotations.status
+  }
+  return result
+}
+
+/**
+ * @since 1.0.0
+ * @category reflection
+ */
+export const isVoid = (ast: AST.AST): boolean => {
+  switch (ast._tag) {
+    case "VoidKeyword": {
+      return true
+    }
+    case "Transformation": {
+      return isVoid(ast.from)
+    }
+    case "Suspend": {
+      return isVoid(ast.f())
+    }
+    default: {
+      return false
+    }
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category reflection
+ */
+export const getStatusSuccessAST = (ast: AST.AST): number => getStatus(ast, isVoid(ast) ? 204 : 200)
+
+/**
+ * @since 1.0.0
+ * @category reflection
+ */
+export const getStatusSuccess = <A extends Schema.Schema.Any>(self: A): number => getStatusSuccessAST(self.ast)
+
+/**
+ * @since 1.0.0
+ * @category reflection
+ */
+export const getStatusErrorAST = (ast: AST.AST): number => getStatus(ast, 500)
+
+/**
+ * @since 1.0.0
+ * @category reflection
+ */
+export const getStatusError = <A extends Schema.Schema.All>(self: A): number => getStatusErrorAST(self.ast)
+
+/**
+ * @since 1.0.0
+ */
+export const UnionUnify = <A extends Schema.Schema.All, B extends Schema.Schema.All>(self: A, that: B): Schema.Schema<
+  A["Type"] | B["Type"],
+  A["Encoded"] | B["Encoded"],
+  A["Context"] | B["Context"]
+> => {
+  const selfTypes = self.ast._tag === "Union" ? self.ast.types : [self.ast]
+  const thatTypes = that.ast._tag === "Union" ? that.ast.types : [that.ast]
+  return Schema.make(AST.Union.make([
+    ...selfTypes,
+    ...thatTypes
+  ]))
+}
+
+/**
+ * @since 1.0.0
+ * @category params
+ */
+export interface PathParams extends Schema.Record$<typeof Schema.String, typeof Schema.String> {}
+
+type Void$ = typeof Schema.Void
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export const Empty = (status: number): typeof Schema.Void => Schema.Void.annotations(annotations({ status }))
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export interface asEmpty<
+  S extends Schema.Schema.Any
+> extends Schema.transform<typeof Schema.Void, S> {}
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export const asEmpty: {
+  <S extends Schema.Schema.Any>(options: {
+    readonly status: number
+    readonly decode: LazyArg<Schema.Schema.Type<S>>
+  }): (self: S) => asEmpty<S>
+  <S extends Schema.Schema.Any>(
+    self: S,
+    options: {
+      readonly status: number
+      readonly decode?: LazyArg<Schema.Schema.Type<S>>
+    }
+  ): asEmpty<S>
+} = dual(
+  2,
+  <S extends Schema.Schema.Any>(
+    self: S,
+    options: {
+      readonly status: number
+      readonly decode?: LazyArg<Schema.Schema.Type<S>>
+    }
+  ): asEmpty<S> =>
+    Schema.transform(
+      Schema.Void,
+      Schema.typeSchema(self),
+      {
+        decode: options.decode as any,
+        encode: constVoid
+      }
+    ).annotations(annotations({
+      status: options.status,
+      [AnnotationEmptyDecodeable]: true
+    })) as any
+)
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export interface Created extends Void$ {
+  readonly _: unique symbol
+}
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export const Created: Created = Empty(201) as any
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export interface Accepted extends Void$ {
+  readonly _: unique symbol
+}
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export const Accepted: Accepted = Empty(202) as any
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export interface NoContent extends Void$ {
+  readonly _: unique symbol
+}
+
+/**
+ * @since 1.0.0
+ * @category empty response
+ */
+export const NoContent: NoContent = Empty(204) as any
+
+/**
+ * @since 1.0.0
+ * @category multipart
+ */
+export const MultipartTypeId: unique symbol = Symbol.for("@effect/platform/HttpApiSchema/Multipart")
+
+/**
+ * @since 1.0.0
+ * @category multipart
+ */
+export type MultipartTypeId = typeof MultipartTypeId
+
+/**
+ * @since 1.0.0
+ * @category multipart
+ */
+export interface Multipart<S extends Schema.Schema.Any>
+  extends
+    Schema.Schema<Schema.Schema.Type<S> & Brand<MultipartTypeId>, Schema.Schema.Encoded<S>, Schema.Schema.Context<S>>
+{}
+
+/**
+ * @since 1.0.0
+ * @category multipart
+ */
+export const Multipart = <S extends Schema.Schema.Any>(self: S): Multipart<S> =>
+  self.annotations({
+    [AnnotationMultipart]: true
+  }) as any
+
+const defaultContentType = (encoding: Encoding["kind"]) => {
+  switch (encoding) {
+    case "Json": {
+      return "application/json"
+    }
+    case "UrlParams": {
+      return "application/x-www-form-urlencoded"
+    }
+    case "Uint8Array": {
+      return "application/octet-stream"
+    }
+    case "Text": {
+      return "text/plain"
+    }
+  }
+}
+
+/**
+ * @since 1.0.0
+ * @category encoding
+ */
+export interface Encoding {
+  readonly kind: "Json" | "UrlParams" | "Uint8Array" | "Text"
+  readonly contentType: string
+}
+
+/**
+ * @since 1.0.0
+ * @category encoding
+ */
+export declare namespace Encoding {
+  /**
+   * @since 1.0.0
+   * @category encoding
+   */
+  export type Validate<A extends Schema.Schema.Any, Kind extends Encoding["kind"]> = Kind extends "Json" ? {}
+    : Kind extends "UrlParams" ? [A["Encoded"]] extends [Readonly<Record<string, string | undefined>>] ? {}
+      : `'UrlParams' kind can only be encoded to 'Record<string, string | undefined>'`
+    : Kind extends "Uint8Array" ?
+      [A["Encoded"]] extends [Uint8Array] ? {} : `'Uint8Array' kind can only be encoded to 'Uint8Array'`
+    : Kind extends "Text" ? [A["Encoded"]] extends [string] ? {} : `'Text' kind can only be encoded to 'string'`
+    : never
+}
+
+/**
+ * @since 1.0.0
+ * @category encoding
+ */
+export const withEncoding: {
+  <A extends Schema.Schema.Any, Kind extends Encoding["kind"]>(
+    options: {
+      readonly kind: Kind
+      readonly contentType?: string | undefined
+    } & Encoding.Validate<A, Kind>
+  ): (self: A) => A
+  <A extends Schema.Schema.Any, Kind extends Encoding["kind"]>(
+    self: A,
+    options: {
+      readonly kind: Kind
+      readonly contentType?: string | undefined
+    } & Encoding.Validate<A, Kind>
+  ): A
+} = dual(2, <A extends Schema.Schema.Any>(self: A, options: {
+  readonly kind: Encoding["kind"]
+  readonly contentType?: string | undefined
+}): A =>
+  self.annotations({
+    [AnnotationEncoding]: {
+      kind: options.kind,
+      contentType: options.contentType ?? defaultContentType(options.kind)
+    },
+    ...(options.kind === "Uint8Array" ?
+      {
+        jsonSchema: {
+          type: "string",
+          format: "binary"
+        }
+      } :
+      undefined)
+  }) as any)
+
+/**
+ * @since 1.0.0
+ * @category encoding
+ */
+export const Text = (options?: {
+  readonly contentType?: string
+}): typeof Schema.String => withEncoding(Schema.String, { kind: "Text", ...options })
+
+/**
+ * @since 1.0.0
+ * @category encoding
+ */
+export const Uint8Array = (options?: {
+  readonly contentType?: string
+}): typeof Schema.Uint8ArrayFromSelf => withEncoding(Schema.Uint8ArrayFromSelf, { kind: "Uint8Array", ...options })

package/src/HttpApiSecurity.ts

@@ -0,0 +1,169 @@
+/**
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context"
+import { dual } from "effect/Function"
+import { type Pipeable, pipeArguments } from "effect/Pipeable"
+import type { Redacted } from "effect/Redacted"
+import type { Covariant } from "effect/Types"
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export const TypeId: unique symbol = Symbol.for("@effect/platform/HttpApiSecurity")
+
+/**
+ * @since 1.0.0
+ * @category type ids
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export type HttpApiSecurity = Bearer | ApiKey | Basic
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export declare namespace HttpApiSecurity {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Proto<out A> extends Pipeable {
+    readonly [TypeId]: {
+      readonly _A: Covariant<A>
+    }
+    readonly annotations: Context.Context<never>
+  }
+
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export type Type<A extends HttpApiSecurity> = A extends Proto<infer Out> ? Out : never
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface Bearer extends HttpApiSecurity.Proto<Redacted> {
+  readonly _tag: "Bearer"
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface ApiKey extends HttpApiSecurity.Proto<Redacted> {
+  readonly _tag: "ApiKey"
+  readonly in: "header" | "query" | "cookie"
+  readonly key: string
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface Basic extends HttpApiSecurity.Proto<Credentials> {
+  readonly _tag: "Basic"
+}
+
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export interface Credentials {
+  readonly username: string
+  readonly password: Redacted
+}
+
+const Proto = {
+  [TypeId]: TypeId,
+  pipe() {
+    return pipeArguments(this, arguments)
+  }
+}
+
+/**
+ * Create an Bearer token security scheme.
+ *
+ * You can implement some api middleware for this security scheme using
+ * `HttpApiBuilder.middlewareSecurity`.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const bearer: Bearer = Object.assign(Object.create(Proto), {
+  _tag: "Bearer",
+  annotations: Context.empty()
+})
+
+/**
+ * Create an API key security scheme.
+ *
+ * You can implement some api middleware for this security scheme using
+ * `HttpApiBuilder.middlewareSecurity`.
+ *
+ * To set the correct cookie in a handler, you can use
+ * `HttpApiBuilder.securitySetCookie`.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const apiKey = (options: {
+  readonly key: string
+  readonly in?: "header" | "query" | "cookie" | undefined
+}): ApiKey =>
+  Object.assign(Object.create(Proto), {
+    _tag: "ApiKey",
+    key: options.key,
+    in: options.in ?? "header",
+    annotations: Context.empty()
+  })
+
+/**
+ * @since 1.0.0
+ * @category constructors
+ */
+export const basic: Basic = Object.assign(Object.create(Proto), {
+  _tag: "Basic",
+  annotations: Context.empty()
+})
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const annotateMerge: {
+  <I>(context: Context.Context<I>): <A extends HttpApiSecurity>(self: A) => A
+  <A extends HttpApiSecurity, I>(self: A, context: Context.Context<I>): A
+} = dual(
+  2,
+  <A extends HttpApiSecurity, I>(self: A, context: Context.Context<I>): A =>
+    Object.assign(Object.create(Proto), {
+      ...self,
+      annotations: Context.merge(self.annotations, context)
+    })
+)
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export const annotate: {
+  <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiSecurity>(self: A) => A
+  <A extends HttpApiSecurity, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
+} = dual(
+  3,
+  <A extends HttpApiSecurity, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A =>
+    Object.assign(Object.create(Proto), {
+      ...self,
+      annotations: Context.add(self.annotations, tag, value)
+    })
+)

package/src/HttpApiSwagger.ts

@@ -0,0 +1,46 @@
+/**
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect"
+import type { Layer } from "effect/Layer"
+import { HttpApi } from "./HttpApi.js"
+import { Router } from "./HttpApiBuilder.js"
+import * as HttpServerResponse from "./HttpServerResponse.js"
+import * as internal from "./internal/apiSwagger.js"
+import * as OpenApi from "./OpenApi.js"
+
+/**
+ * @since 1.0.0
+ * @category layers
+ */
+export const layer = (options?: {
+  readonly path?: `/${string}` | undefined
+}): Layer<never, never, HttpApi.Service> =>
+  Router.use((router) =>
+    Effect.gen(function*() {
+      const api = yield* HttpApi
+      const spec = OpenApi.fromApi(api)
+      const response = HttpServerResponse.html(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${spec.info.title} Documentation</title>
+  <style>${internal.css}</style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script>
+    ${internal.javascript}
+    window.onload = () => {
+      window.ui = SwaggerUIBundle({
+        spec: ${JSON.stringify(spec)},
+        dom_id: '#swagger-ui',
+      });
+    };
+  </script>
+</body>
+</html>`)
+      yield* router.get(options?.path ?? "/docs", Effect.succeed(response))
+    })
+  )

package/src/HttpMethod.ts

@@ -11,7 +11,25 @@ export type HttpMethod =
   | "HEAD"
   | "OPTIONS"
 
+/**
+ * @since 1.0.0
+ * @category models
+ */
+export declare namespace HttpMethod {
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export type NoBody = "GET" | "HEAD" | "OPTIONS"
+
+  /**
+   * @since 1.0.0
+   * @category models
+   */
+  export type WithBody = Exclude<HttpMethod, NoBody>
+}
+
 /**
  * @since 1.0.0
  */
-export const hasBody = (method: HttpMethod): boolean => method !== "GET" && method !== "HEAD"
+export const hasBody = (method: HttpMethod): boolean => method !== "GET" && method !== "HEAD" && method !== "OPTIONS"

package/src/HttpRouter.ts

@@ -357,6 +357,15 @@ export const makeRoute: <E, R>(
   options?: { readonly prefix?: string | undefined; readonly uninterruptible?: boolean | undefined } | undefined
 ) => Route<E, HttpRouter.ExcludeProvided<R>> = internal.makeRoute
 
+/**
+ * @since 1.0.0
+ * @category utils
+ */
+export const prefixPath: {
+  (prefix: string): (self: string) => string
+  (self: string, prefix: string): string
+} = internal.prefixPath
+
 /**
  * @since 1.0.0
  * @category combinators

package/src/HttpServerResponse.ts

@@ -124,7 +124,7 @@ export const htmlStream: <A extends ReadonlyArray<Template.InterpolatedWithStrea
  */
 export const json: (
   body: unknown,
-  options?: Options.WithContent | undefined
+  options?: Options.WithContentType | undefined
 ) => Effect.Effect<HttpServerResponse, Body.HttpBodyError> = internal.json
 
 /**
@@ -141,14 +141,14 @@ export const schemaJson: <A, I, R>(
  * @since 1.0.0
  * @category constructors
  */
-export const unsafeJson: (body: unknown, options?: Options.WithContent | undefined) => HttpServerResponse =
+export const unsafeJson: (body: unknown, options?: Options.WithContentType | undefined) => HttpServerResponse =
   internal.unsafeJson
 
 /**
  * @since 1.0.0
  * @category constructors
  */
-export const urlParams: (body: UrlParams.Input, options?: Options.WithContent | undefined) => HttpServerResponse =
+export const urlParams: (body: UrlParams.Input, options?: Options.WithContentType | undefined) => HttpServerResponse =
   internal.urlParams
 
 /**