effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -56,9 +56,9 @@ import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Redacted from "../../Redacted.ts"
 import * as Result from "../../Result.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Issue from "../../SchemaIssue.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaIssue from "../../SchemaIssue.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import * as Scope from "../../Scope.ts"
 import * as Stream from "../../Stream.ts"
 import type { Covariant, NoInfer } from "../../Types.ts"
@@ -446,7 +446,8 @@ export const securityDecode = <Security extends HttpApiSecurity.HttpApiSecurity>
     case "Http": {
       return Effect.map(
         HttpServerRequest,
-        (request) => Redacted.make((request.headers.authorization ?? "").slice(self.schemeLength)) as any
+        // schemeLength + space
+        (request) => Redacted.make((request.headers.authorization ?? "").slice(self.schemeLength + 1)) as any
       )
     }
     case "ApiKey": {
@@ -596,7 +597,7 @@ function buildPayloadDecoders(
       result.set(contentType, {
         _tag: encoding._tag,
         decode,
-        nullOnEmpty: schemas.some((s) => AST.isNull(AST.toEncoded(s.ast)))
+        nullOnEmpty: schemas.some((s) => SchemaAST.isNull(SchemaAST.toEncoded(s.ast)))
       })
     }
   })
@@ -828,8 +829,8 @@ function makeErrorSchema(endpoint: HttpApiEndpoint.AnyWithProps): Schema.Encoder
   return schemas.length === 1 ? schemas[0] : Schema.Union(schemas)
 }
 
-function toResponseSchema(getStatus: (ast: AST.AST) => number) {
-  const cache = new WeakMap<AST.AST, Schema.Top>()
+function toResponseSchema(getStatus: (ast: SchemaAST.AST) => number) {
+  const cache = new WeakMap<SchemaAST.AST, Schema.Top>()
 
   return (schema: Schema.Top): Schema.Encoder<HttpServerResponse, unknown> => {
     const cached = cache.get(schema.ast)
@@ -845,9 +846,9 @@ function toResponseSchema(getStatus: (ast: AST.AST) => number) {
 }
 
 function getResponseTransformation(
-  getStatus: (ast: AST.AST) => number,
+  getStatus: (ast: SchemaAST.AST) => number,
   schema: Schema.Top
-): Transformation.Transformation<unknown, Response.HttpServerResponse> {
+): SchemaTransformation.Transformation<unknown, Response.HttpServerResponse> {
   const ast = schema.ast
   const encode = getResponseEncode(
     getStatus(ast),
@@ -855,8 +856,8 @@ function getResponseTransformation(
     HttpApiSchema.isNoContent(ast)
   )
 
-  return Transformation.transformOrFail({
-    decode: (res) => Effect.fail(new Issue.Forbidden(Option.some(res), { message: "Encode only schema" })),
+  return SchemaTransformation.transformOrFail({
+    decode: (res) => Effect.fail(new SchemaIssue.Forbidden(Option.some(res), { message: "Encode only schema" })),
     encode
   })
 }
@@ -865,7 +866,7 @@ function getResponseEncode<E>(
   status: number,
   encoding: HttpApiSchema.ResponseEncoding,
   isNoContent: boolean
-): (e: E) => Effect.Effect<Response.HttpServerResponse, Issue.InvalidValue, never> {
+): (e: E) => Effect.Effect<Response.HttpServerResponse, SchemaIssue.InvalidValue, never> {
   switch (encoding._tag) {
     case "Json": {
       return ((e) => {
@@ -876,7 +877,7 @@ function getResponseEncode<E>(
           const s = JSON.stringify(e)
           return Effect.succeed(Response.text(s, { status, contentType: encoding.contentType }))
         } catch (error) {
-          return Effect.fail(new Issue.InvalidValue(Option.some(e), { message: globalThis.String(error) }))
+          return Effect.fail(new SchemaIssue.InvalidValue(Option.some(e), { message: globalThis.String(error) }))
         }
       })
     }

package/src/unstable/httpapi/HttpApiClient.ts

@@ -42,9 +42,9 @@ import { identity } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Issue from "../../SchemaIssue.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaIssue from "../../SchemaIssue.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import type { Simplify } from "../../Types.ts"
 import * as UndefinedOr from "../../UndefinedOr.ts"
 import * as HttpBody from "../http/HttpBody.ts"
@@ -679,7 +679,7 @@ const ArrayBuffer = Schema.instanceOf(globalThis.ArrayBuffer, {
 const Uint8ArrayFromArrayBuffer = ArrayBuffer.pipe(
   Schema.decodeTo(
     Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayBuffer>>,
-    Transformation.transform({
+    SchemaTransformation.transform({
       decode(fromA) {
         return new Uint8Array(fromA)
       },
@@ -696,7 +696,7 @@ const Uint8ArrayFromArrayBuffer = ArrayBuffer.pipe(
 const StringFromArrayBuffer = ArrayBuffer.pipe(
   Schema.decodeTo(
     Schema.String,
-    Transformation.transform({
+    SchemaTransformation.transform({
       decode(fromA) {
         return new TextDecoder().decode(fromA)
       },
@@ -716,7 +716,7 @@ const UnknownFromArrayBuffer = StringFromArrayBuffer.pipe(Schema.decodeTo(
     // Handle No Content
     Schema.Literal("").pipe(Schema.decodeTo(
       Schema.Undefined,
-      Transformation.transform({
+      SchemaTransformation.transform({
         decode: () => undefined,
         encode: () => ""
       })
@@ -733,11 +733,11 @@ function toCodecArrayBuffer(schemas: readonly [Schema.Top, ...Array<Schema.Top>]
     switch (encoding._tag) {
       case "Json": {
         // handle json codecs that transform void schemas to null
-        const encodedIsNull = AST.isNull(AST.toEncoded(schema.ast))
+        const encodedIsNull = SchemaAST.isNull(SchemaAST.toEncoded(schema.ast))
         return UnknownFromArrayBuffer.pipe(Schema.decodeTo(
           schema,
           encodedIsNull ?
-            Transformation.transform({
+            SchemaTransformation.transform({
               decode: (a) => a === undefined ? null : a,
               encode: (a) => a === null ? undefined : a
             }) as any :
@@ -776,7 +776,7 @@ function getEncodePayloadSchema(
   return Schema.Union(schemas.map((s) => getEncodePayloadSchemaFromBody(s, method)))
 }
 
-const bodyFromPayloadCache = new WeakMap<AST.AST, Schema.Top>()
+const bodyFromPayloadCache = new WeakMap<SchemaAST.AST, Schema.Top>()
 
 function getEncodePayloadSchemaFromBody(
   schema: Schema.Top,
@@ -790,40 +790,40 @@ function getEncodePayloadSchemaFromBody(
   const encoding = HttpApiSchema.getPayloadEncoding(ast, method)
   const out = $HttpBody.pipe(Schema.decodeTo(
     schema,
-    Transformation.transformOrFail<unknown, HttpBody.HttpBody>({
+    SchemaTransformation.transformOrFail<unknown, HttpBody.HttpBody>({
       decode(httpBody) {
-        return Effect.fail(new Issue.Forbidden(Option.some(httpBody), { message: "Encode only schema" }))
+        return Effect.fail(new SchemaIssue.Forbidden(Option.some(httpBody), { message: "Encode only schema" }))
       },
       encode(t) {
         switch (encoding._tag) {
           case "Multipart":
-            return Effect.fail(new Issue.Forbidden(Option.some(t), { message: "Payload must be a FormData" }))
+            return Effect.fail(new SchemaIssue.Forbidden(Option.some(t), { message: "Payload must be a FormData" }))
           case "Json": {
             try {
               const body = JSON.stringify(t)
               return Effect.succeed(HttpBody.text(body, encoding.contentType))
             } catch (error) {
-              return Effect.fail(new Issue.InvalidValue(Option.some(t), { message: globalThis.String(error) }))
+              return Effect.fail(new SchemaIssue.InvalidValue(Option.some(t), { message: globalThis.String(error) }))
             }
           }
           case "Text": {
             if (typeof t !== "string") {
               return Effect.fail(
-                new Issue.InvalidValue(Option.some(t), { message: "Expected a string" })
+                new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a string" })
               )
             }
             return Effect.succeed(HttpBody.text(t, encoding.contentType))
           }
           case "FormUrlEncoded": {
             if (!Predicate.isObject(t)) {
-              return Effect.fail(new Issue.InvalidValue(Option.some(t), { message: "Expected a record" }))
+              return Effect.fail(new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a record" }))
             }
             return Effect.succeed(HttpBody.urlParams(UrlParams.fromInput(t as any)))
           }
           case "Uint8Array": {
             if (!(t instanceof Uint8Array)) {
               return Effect.fail(
-                new Issue.InvalidValue(Option.some(t), { message: "Expected a Uint8Array" })
+                new SchemaIssue.InvalidValue(Option.some(t), { message: "Expected a Uint8Array" })
               )
             }
             return Effect.succeed(HttpBody.uint8Array(t, encoding.contentType))

package/src/unstable/httpapi/HttpApiError.ts

@@ -66,7 +66,7 @@ const serviceUnavailableResponse = HttpServerResponse.empty({ status: 503 })
  * Built-in HTTP API error for a `400 Bad Request` response. When used directly as
  * a server response, it renders as an empty response with status 400.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class BadRequest extends Schema.ErrorClass<BadRequest>("effect/HttpApiError/BadRequest")({
@@ -97,7 +97,7 @@ export const BadRequestNoContent = BadRequest.pipe(HttpApiSchema.asNoContent({
  * Built-in HTTP API error for a `401 Unauthorized` response. When used directly as
  * a server response, it renders as an empty response with status 401.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class Unauthorized extends Schema.ErrorClass<Unauthorized>("effect/HttpApiError/Unauthorized")({
@@ -127,7 +127,7 @@ export const UnauthorizedNoContent = Unauthorized.pipe(HttpApiSchema.asNoContent
  * Built-in HTTP API error for a `403 Forbidden` response. When used directly as a
  * server response, it renders as an empty response with status 403.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class Forbidden extends Schema.ErrorClass<Forbidden>("effect/HttpApiError/Forbidden")({
@@ -157,7 +157,7 @@ export const ForbiddenNoContent = Forbidden.pipe(HttpApiSchema.asNoContent({
  * Built-in HTTP API error for a `404 Not Found` response. When used directly as a
  * server response, it renders as an empty response with status 404.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class NotFound extends Schema.ErrorClass<NotFound>("effect/HttpApiError/NotFound")({
@@ -187,7 +187,7 @@ export const NotFoundNoContent = NotFound.pipe(HttpApiSchema.asNoContent({
  * Built-in HTTP API error for a `405 Method Not Allowed` response. When used
  * directly as a server response, it renders as an empty response with status 405.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class MethodNotAllowed extends Schema.ErrorClass<MethodNotAllowed>("effect/HttpApiError/MethodNotAllowed")({
@@ -217,7 +217,7 @@ export const MethodNotAllowedNoContent = MethodNotAllowed.pipe(HttpApiSchema.asN
  * Built-in HTTP API error for a `406 Not Acceptable` response. When used directly
  * as a server response, it renders as an empty response with status 406.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class NotAcceptable extends Schema.ErrorClass<NotAcceptable>("effect/HttpApiError/NotAcceptable")({
@@ -247,7 +247,7 @@ export const NotAcceptableNoContent = NotAcceptable.pipe(HttpApiSchema.asNoConte
  * Built-in HTTP API error for a `408 Request Timeout` response. When used directly
  * as a server response, it renders as an empty response with status 408.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class RequestTimeout extends Schema.ErrorClass<RequestTimeout>("effect/HttpApiError/RequestTimeout")({
@@ -277,7 +277,7 @@ export const RequestTimeoutNoContent = RequestTimeout.pipe(HttpApiSchema.asNoCon
  * Built-in HTTP API error for a `409 Conflict` response. When used directly as a
  * server response, it renders as an empty response with status 409.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class Conflict extends Schema.ErrorClass<Conflict>("effect/HttpApiError/Conflict")({
@@ -307,7 +307,7 @@ export const ConflictNoContent = Conflict.pipe(HttpApiSchema.asNoContent({
  * Built-in HTTP API error for a `410 Gone` response. When used directly as a
  * server response, it renders as an empty response with status 410.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class Gone extends Schema.ErrorClass<Gone>("effect/HttpApiError/Gone")({
@@ -337,7 +337,7 @@ export const GoneNoContent = Gone.pipe(HttpApiSchema.asNoContent({
  * Built-in HTTP API error for a `500 Internal Server Error` response. When used
  * directly as a server response, it renders as an empty response with status 500.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class InternalServerError
@@ -368,7 +368,7 @@ export const InternalServerErrorNoContent = InternalServerError.pipe(HttpApiSche
  * Built-in HTTP API error for a `501 Not Implemented` response. When used directly
  * as a server response, it renders as an empty response with status 501.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class NotImplemented extends Schema.ErrorClass<NotImplemented>("effect/HttpApiError/NotImplemented")({
@@ -397,7 +397,7 @@ export const NotImplementedNoContent = NotImplemented.pipe(HttpApiSchema.asNoCon
  * Built-in HTTP API error for a `503 Service Unavailable` response. When used
  * directly as a server response, it renders as an empty response with status 503.
  *
- * @category Built-in errors
+ * @category errors
  * @since 4.0.0
  */
 export class ServiceUnavailable
@@ -445,7 +445,7 @@ export const HttpApiSchemaErrorTypeId: HttpApiSchemaErrorTypeId = "~effect/httpa
  * which component failed and responds as an empty `400 Bad Request` when rendered
  * as a server response.
  *
- * @category Parsing errors
+ * @category errors
  * @since 4.0.0
  */
 export class HttpApiSchemaError extends Data.TaggedClass("HttpApiSchemaError")<{

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -348,9 +348,9 @@ export type ServiceClass<
  *
  * **When to use**
  *
- * Use when you use the optional configuration to declare required services, provided services,
- * typed error schemas, security schemes, client errors, and whether generated
- * clients must provide a matching client middleware.
+ * Use when you need an HTTP API middleware service whose configuration declares
+ * required services, provided services, typed error schemas, security schemes,
+ * client errors, or a matching client middleware requirement.
  *
  * @category schemas
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -43,8 +43,8 @@
  */
 import { constVoid, type LazyArg } from "../../Function.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import { hasBody, type HttpMethod } from "../http/HttpMethod.ts"
 import type * as Multipart_ from "../http/Multipart.ts"
 
@@ -274,7 +274,7 @@ export function asNoContent<S extends Schema.Top>(options: {
     return Schema.Void.pipe(
       Schema.decodeTo(
         Schema.toType(self),
-        Transformation.transform({
+        SchemaTransformation.transform({
           decode: options.decode,
           encode: constVoid
         })
@@ -472,18 +472,18 @@ export function asUint8Array(options?: {
  * @category predicates
  * @since 4.0.0
  */
-export const isNoContent = (ast: AST.AST): boolean => {
-  if (AST.isVoid(ast)) return true
-  const encoded = AST.toEncoded(ast)
-  if (AST.isVoid(encoded)) return true
+export const isNoContent = (ast: SchemaAST.AST): boolean => {
+  if (SchemaAST.isVoid(ast)) return true
+  const encoded = SchemaAST.toEncoded(ast)
+  if (SchemaAST.isVoid(encoded)) return true
   const target = ast.encoding?.[0].to
   if (target === undefined) return false
-  return AST.isVoid(target)
+  return SchemaAST.isVoid(target)
 }
 
-const resolveHttpApiEncoding = AST.resolveAt<Encoding>("~httpApiEncoding")
+const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
 
-const resolveHttpApiStatus = AST.resolveAt<number>("httpApiStatus")
+const resolveHttpApiStatus = SchemaAST.resolveAt<number>("httpApiStatus")
 
 const defaultJsonEncoding: Encoding = {
   _tag: "Json",
@@ -494,19 +494,19 @@ const defaultUrlEncodedEncoding: Encoding = {
   contentType: "application/x-www-form-urlencoded"
 }
 
-function getEncoding(ast: AST.AST): Encoding {
+function getEncoding(ast: SchemaAST.AST): Encoding {
   return resolveHttpApiEncoding(ast) ?? defaultJsonEncoding
 }
 
 /** @internal */
-export function getPayloadEncoding(ast: AST.AST, method: HttpMethod): PayloadEncoding {
+export function getPayloadEncoding(ast: SchemaAST.AST, method: HttpMethod): PayloadEncoding {
   const encoding = resolveHttpApiEncoding(ast)
   if (encoding) return encoding
   return hasBody(method) ? defaultJsonEncoding : defaultUrlEncodedEncoding
 }
 
 /** @internal */
-export function getResponseEncoding(ast: AST.AST): ResponseEncoding {
+export function getResponseEncoding(ast: SchemaAST.AST): ResponseEncoding {
   const out = getEncoding(ast)
   if (out._tag === "Multipart") {
     throw new Error("Multipart is not supported in response")
@@ -515,11 +515,11 @@ export function getResponseEncoding(ast: AST.AST): ResponseEncoding {
 }
 
 /** @internal */
-export function getStatusSuccess(self: AST.AST): number {
+export function getStatusSuccess(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 200
 }
 
 /** @internal */
-export function getStatusError(self: AST.AST): number {
+export function getStatusError(self: SchemaAST.AST): number {
   return resolveHttpApiStatus(self) ?? 500
 }

package/src/unstable/httpapi/OpenApi.ts

@@ -51,7 +51,7 @@ import { escapeToken } from "../../JsonPointer.ts"
 import * as JsonSchema from "../../JsonSchema.ts"
 import * as Option from "../../Option.ts"
 import * as Schema from "../../Schema.ts"
-import * as AST from "../../SchemaAST.ts"
+import * as SchemaAST from "../../SchemaAST.ts"
 import * as SchemaRepresentation from "../../SchemaRepresentation.ts"
 import * as HttpMethod from "../http/HttpMethod.ts"
 import * as HttpApi from "./HttpApi.ts"
@@ -305,11 +305,11 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
   const pathOps: Array<
     {
       readonly _tag: "schema"
-      readonly ast: AST.AST
+      readonly ast: SchemaAST.AST
       readonly path: ReadonlyArray<string>
     } | {
       readonly _tag: "parameter"
-      readonly ast: AST.AST
+      readonly ast: SchemaAST.AST
       readonly path: ReadonlyArray<string>
     }
   > = []
@@ -383,8 +383,8 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
             const filtered = schemas.filter((s) => !HttpApiSchema.isNoContent(s.ast))
             if (filtered.length === 0) return
             hasContent = true
-            const asts = filtered.map(AST.getAST)
-            const ast = asts.length === 1 ? asts[0] : new AST.Union(asts, "anyOf")
+            const asts = filtered.map(SchemaAST.getAST)
+            const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts, "anyOf")
             pathOps.push({
               _tag: "schema",
               ast: toEncodingAST(ast, encoding._tag),
@@ -409,8 +409,8 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
           if (content !== undefined) {
             content.forEach((map, encoding) => {
               map.forEach((schemas, contentType) => {
-                const asts = Array.from(schemas, AST.getAST)
-                const ast = asts.length === 1 ? asts[0] : new AST.Union(asts, "anyOf")
+                const asts = Array.from(schemas, SchemaAST.getAST)
+                const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts, "anyOf")
 
                 pathOps.push({
                   _tag: "schema",
@@ -429,14 +429,14 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
 
       function processParameters(schema: Schema.Top | undefined, i: OpenAPISpecParameter["in"]) {
         if (schema) {
-          const ast = AST.getLastEncoding(schema.ast)
-          if (AST.isObjects(ast)) {
+          const ast = SchemaAST.getLastEncoding(schema.ast)
+          if (SchemaAST.isObjects(ast)) {
             for (const ps of ast.propertySignatures) {
               op.parameters.push({
                 name: String(ps.name),
                 in: i,
                 schema: {},
-                required: i === "path" || !AST.isOptional(ps.type)
+                required: i === "path" || !SchemaAST.isOptional(ps.type)
               })
               pathOps.push({
                 _tag: "parameter",
@@ -528,7 +528,7 @@ export function fromApi<Id extends string, Groups extends HttpApiGroup.Any>(
 
   processAnnotation(api.annotations, HttpApi.AdditionalSchemas, (componentSchemas) => {
     componentSchemas.forEach((componentSchema) => {
-      const identifier = AST.resolveIdentifier(componentSchema.ast)
+      const identifier = SchemaAST.resolveIdentifier(componentSchema.ast)
       if (identifier !== undefined) {
         if (identifier in spec.components.schemas) {
           throw new globalThis.Error(`Duplicate component schema identifier: ${identifier}`)
@@ -603,8 +603,8 @@ type ResponseBodies = Map<
 
 function extractResponseBodies(
   schemas: Array<Schema.Top>,
-  getStatus: (ast: AST.AST) => number,
-  getDescription: (ast: AST.AST) => string | undefined
+  getStatus: (ast: SchemaAST.AST) => number,
+  getDescription: (ast: SchemaAST.AST) => string | undefined
 ): ResponseBodies {
   const map = new Map<number, {
     descriptions: Set<string>
@@ -671,8 +671,8 @@ function extractResponseBodies(
   }
 }
 
-function resolveDescriptionOrIdentifier(ast: AST.AST): string | undefined {
-  return AST.resolveDescription(ast) ?? AST.resolveIdentifier(ast)
+function resolveDescriptionOrIdentifier(ast: SchemaAST.AST): string | undefined {
+  return SchemaAST.resolveDescription(ast) ?? SchemaAST.resolveIdentifier(ast)
 }
 
 type Content = Map<
@@ -687,7 +687,7 @@ const Uint8ArrayEncoding = Schema.String.annotate({
   format: "binary"
 })
 
-function toEncodingAST(ast: AST.AST, _tag: HttpApiSchema.Encoding["_tag"]): AST.AST {
+function toEncodingAST(ast: SchemaAST.AST, _tag: HttpApiSchema.Encoding["_tag"]): SchemaAST.AST {
   switch (_tag) {
     case "Uint8Array":
       return Uint8ArrayEncoding.ast
@@ -701,9 +701,9 @@ function toEncodingAST(ast: AST.AST, _tag: HttpApiSchema.Encoding["_tag"]): AST.
   }
 }
 
-function persistedFileToBinaryEncoding(ast: AST.AST): AST.AST {
+function persistedFileToBinaryEncoding(ast: SchemaAST.AST): SchemaAST.AST {
   if (
-    AST.isDeclaration(ast) &&
+    SchemaAST.isDeclaration(ast) &&
     ((ast.annotations as (Schema.Annotations.Declaration<unknown, readonly []> | undefined))?.typeConstructor?._tag ===
       "effect/http/PersistedFile")
   ) {

package/src/unstable/observability/OtlpResource.ts

@@ -143,6 +143,11 @@ export const fromConfig: (
 /**
  * Returns the `service.name` attribute from an OTLP resource.
  *
+ * **When to use**
+ *
+ * Use when an OTLP resource is known to contain a string `service.name` and
+ * throwing is acceptable if that invariant is broken.
+ *
  * **Gotchas**
  *
  * Throws if the resource does not contain a string `service.name` attribute.

package/src/unstable/observability/PrometheusMetrics.ts

@@ -72,7 +72,7 @@ export type MetricNameMapper = (name: string) => string
 /**
  * Options for formatting metrics.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface FormatOptions {
@@ -90,7 +90,7 @@ export interface FormatOptions {
 /**
  * Options for exporting Prometheus metrics over HTTP.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface HttpOptions extends FormatOptions {
@@ -128,7 +128,7 @@ export interface HttpOptions extends FormatOptions {
  * })
  * ```
  *
- * @category Formatting
+ * @category formatting
  * @since 4.0.0
  */
 export const format: (options?: FormatOptions | undefined) => Effect.Effect<string> = Effect.fnUntraced(
@@ -143,10 +143,12 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
  *
  * **When to use**
  *
- * Use when you use this low-level function when you already have access to the context. Most
- * users should use `format` instead.
+ * Use when you already have access to the context and need low-level
+ * synchronous formatting.
+ *
+ * @see {@link format} for effectful formatting from the current context
  *
- * @category Formatting
+ * @category formatting
  * @since 4.0.0
  */
 export const formatUnsafe = (

package/src/unstable/persistence/KeyValueStore.ts

@@ -114,7 +114,7 @@ export interface KeyValueStore {
  * Primitive operations are required, while helpers such as `has`, `isEmpty`,
  * and `modify` can be supplied to override the defaults.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type MakeOptions = Partial<KeyValueStore> & {
@@ -153,7 +153,7 @@ export type MakeOptions = Partial<KeyValueStore> & {
  * Implementation callbacks for adapting a string-only backing store into a
  * `KeyValueStore`.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export type MakeStringOptions = Partial<Omit<KeyValueStore, "set">> & {
@@ -214,7 +214,7 @@ export class KeyValueStoreError extends Data.TaggedError("KeyValueStoreError")<{
  * Use to access or provide the persistence store used for lightweight durable
  * state.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export const KeyValueStore: Context.Service<

package/src/unstable/persistence/Persistable.ts

@@ -235,7 +235,7 @@ const exitSchemaCache = new WeakMap<Persistable<any, any>, Schema.Exit<any, any,
  * Encodes an `Exit` for a persistable request using its success and error
  * schemas.
  *
- * @category Serialization
+ * @category serialization
  * @since 4.0.0
  */
 export const serializeExit = <A extends Schema.Top, E extends Schema.Top>(
@@ -250,7 +250,7 @@ export const serializeExit = <A extends Schema.Top, E extends Schema.Top>(
  * Decodes a persisted value into an `Exit` for a persistable request using its
  * success and error schemas.
  *
- * @category Serialization
+ * @category serialization
  * @since 4.0.0
  */
 export const deserializeExit = <A extends Schema.Top, E extends Schema.Top>(