effect 4.0.5 → 4.0.6

package/src/http-api/OpenApi.ts

@@ -229,9 +229,20 @@ export const annotations: (
   transform: Transform
 })
 
-const defaultOptions: SchemaRepresentation.ToRepresentationOptions = {}
+/**
+ * Options for {@link fromApi}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface FromApiOptions
+  extends SchemaRepresentation.ToRepresentationOptions, Pick<Schema.ToJsonSchemaOptions, "includeAnnotationKey">
+{}
+
+const defaultOptions: FromApiOptions = {}
 const apiCache = new WeakMap<
-  SchemaRepresentation.ToRepresentationOptions,
+  FromApiOptions,
   WeakMap<HttpApi.Constraint, OpenAPISpec>
 >()
 
@@ -285,7 +296,8 @@ function processAnnotation<Services, S, I>(
  * integrates annotations like descriptions, summaries, external documentation,
  * and overrides. The optional reference policy receives canonical JSON encoded
  * ASTs and controls which schemas are extracted into components. By default, only candidates with resolved identifiers
- * become references; anonymous non-recursive schemas remain inline.
+ * become references; anonymous non-recursive schemas remain inline. The optional `includeAnnotationKey` predicate selects
+ * custom schema annotation keys, such as `x-*` vendor extensions, to include in the generated schemas.
  *
  * **Gotchas**
  *
@@ -299,7 +311,7 @@ function processAnnotation<Services, S, I>(
  */
 export function fromApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>,
-  options?: SchemaRepresentation.ToRepresentationOptions
+  options?: FromApiOptions
 ): OpenAPISpec {
   const resolvedOptions = options ?? defaultOptions
   let cache = apiCache.get(resolvedOptions)
@@ -329,7 +341,7 @@ type SchemaOp =
 
 function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>,
-  options: SchemaRepresentation.ToRepresentationOptions
+  options: FromApiOptions
 ): OpenAPISpec {
   let spec: OpenAPISpec = {
     openapi: "3.1.0",
@@ -423,10 +435,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
       }
 
       const paramNames = HttpApiPath.getParamNames(endpoint.params)
-      const path = endpoint.path.replace(
-        /:(\w+)\??/g,
-        (match, key: string) => paramNames === undefined || paramNames.has(key) ? `{${key}}` : match
-      )
+      const path = HttpApiPath.replaceParams(endpoint.path, paramNames, (key) => `{${key}}`)
       const method = endpoint.method.toLowerCase() as Lowercase<HttpMethod.HttpMethod>
       const isQuery = method === "query"
       const operationKey = isQuery ? "QUERY" : method
@@ -467,32 +476,44 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
           if (streamContent !== undefined) {
             streamContent.forEach((stream, contentType) => {
               op.responses[status].content ??= {}
-              if (HttpApiSchema.isStreamSse(stream)) {
-                InternalRecord.assignProperty(op.responses[status].content, contentType, {
-                  schema: registerSchema(stream.events.ast),
-                  "x-effect-stream": {
-                    encoding: "sse",
-                    causeSchema: registerSchema(Schema.Cause(stream.error, Schema.Defect()).ast),
-                    errorSchema: registerSchema(stream.error.ast),
-                    failureEvent: reservedStreamFailureEvent
-                  }
-                })
-              } else {
-                InternalRecord.assignProperty(op.responses[status].content, contentType, {
-                  schema: {
-                    type: "string",
-                    format: "binary"
-                  },
-                  "x-effect-stream": {
-                    encoding: "uint8array"
-                  }
-                })
-              }
+              InternalRecord.assignProperty(op.responses[status].content, contentType, makeStreamMediaType(stream))
             })
           }
         }
       }
 
+      function makeStreamMediaType(stream: HttpApiSchema.StreamSchema): OpenApiSpecMediaType {
+        if (HttpApiSchema.isStreamSse(stream)) {
+          return {
+            schema: registerSchema(stream.events.ast),
+            "x-effect-stream": {
+              encoding: "sse",
+              causeSchema: registerSchema(Schema.Cause(stream.error, Schema.Defect()).ast),
+              errorSchema: registerSchema(stream.error.ast),
+              failureEvent: reservedStreamFailureEvent
+            }
+          }
+        }
+        if (HttpApiSchema.isStreamNdjson(stream)) {
+          // Each line is one element, so the media type documents the element schema.
+          return {
+            schema: registerSchema(stream.schema.ast),
+            "x-effect-stream": {
+              encoding: "ndjson"
+            }
+          }
+        }
+        return {
+          schema: {
+            type: "string",
+            format: "binary"
+          },
+          "x-effect-stream": {
+            encoding: "uint8array"
+          }
+        }
+      }
+
       function processParameters(schema: Schema.Constraint | undefined, i: OpenAPISpecParameter["in"]) {
         if (schema) {
           schemaOps.push({
@@ -554,27 +575,39 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
 
       const hasBody = HttpMethod.hasBody(endpoint.method)
       if (hasBody) {
-        const schemasByContentType = new Map<string, {
-          readonly encoding: HttpApiSchema.PayloadEncoding
-          readonly schemas: Array<Schema.Top>
-        }>()
+        const schemasByContentType = new Map<
+          string,
+          {
+            readonly encoding: HttpApiSchema.PayloadEncoding
+            readonly schemas: Array<Schema.Top>
+          } | HttpApiSchema.StreamSchema
+        >()
         for (const schema of HttpApiEndpoint.getPayloadSchemas(endpoint)) {
+          if (HttpApiSchema.isStreamSchema(schema)) {
+            // Endpoint construction rejects a buffered payload sharing a streaming payload's media type.
+            schemasByContentType.set(schema.contentType, schema)
+            continue
+          }
           if (HttpApiSchema.isNoContent(schema.ast)) continue
           const encoding = HttpApiSchema.getPayloadEncoding(schema.ast, endpoint.method)
           const existing = schemasByContentType.get(encoding.contentType)
           if (existing === undefined) {
             schemasByContentType.set(encoding.contentType, { encoding, schemas: [schema] })
-          } else {
+          } else if (!HttpApiSchema.isStreamSchema(existing)) {
             existing.schemas.push(schema)
           }
         }
         if (schemasByContentType.size > 0) {
           const content: OpenApiSpecContent = {}
-          for (const [contentType, { encoding, schemas }] of schemasByContentType) {
-            const asts = schemas.map(SchemaAST.getAST)
+          for (const [contentType, entry] of schemasByContentType) {
+            if (HttpApiSchema.isStreamSchema(entry)) {
+              InternalRecord.assignProperty(content, contentType, makeStreamMediaType(entry))
+              continue
+            }
+            const asts = entry.schemas.map(SchemaAST.getAST)
             const ast = asts.length === 1 ? asts[0] : new SchemaAST.Union(asts)
             InternalRecord.assignProperty(content, contentType, {
-              schema: registerSchema(ast, encoding._tag)
+              schema: registerSchema(ast, entry.encoding._tag)
             })
           }
           op.requestBody = { content, required: true }
@@ -678,7 +711,7 @@ function makeOpenApi<Id extends string, Groups extends HttpApiGroup.Constraint>(
 
 function compileSchemaOps(
   schemaOps: Array<SchemaOp>,
-  options: SchemaRepresentation.ToRepresentationOptions,
+  options: FromApiOptions,
   components: JsonSchema.Definitions
 ): void {
   if (!Arr.isArrayNonEmpty(schemaOps)) return
@@ -697,7 +730,7 @@ function compileSchemaOps(
   const jsonSchemaMultiDocument = JsonSchema.toMultiDocumentOpenApi3_1(
     InternalToJsonSchemaDocument.toJsonSchemaMultiDocument(
       { representations, references },
-      { onExcessProperty: "error" }
+      { onExcessProperty: "error", includeAnnotationKey: options.includeAnnotationKey }
     )
   )
 
@@ -861,7 +894,12 @@ function extractResponseBodies(
     const headers = HttpApiSchema.isWithHeaders(schema) ? schema.headers : annotation?.headersCodec
     const status = getStatus(schema)
     const ast = body.ast
-    if (HttpApiSchema.isStreamSchema(body)) {
+    if (HttpApiSchema.isUpgrade(body)) {
+      addNoContent(status, getDescription(ast) ?? "Switching Protocols")
+      map.get(status)!.headers.push(
+        Schema.Struct({ connection: Schema.Literal("Upgrade"), upgrade: Schema.Literal(body.protocol) })
+      )
+    } else if (HttpApiSchema.isStreamSchema(body)) {
       addStreamContent(body, status)
     } else if (HttpApiSchema.isNoContent(ast)) {
       addNoContent(status, getDescription(schema.ast) ?? getDescription(ast) ?? "<No Content>")
@@ -1259,7 +1297,8 @@ export interface OpenApiSpecMediaType {
 }
 
 /**
- * Effect-specific metadata for generated streaming response media types.
+ * Effect-specific metadata for generated streaming request and response media
+ * types.
  *
  * @stability unstable
  * @category models
@@ -1275,6 +1314,9 @@ export type OpenApiSpecEffectStream =
   | {
     encoding: "uint8array"
   }
+  | {
+    encoding: "ndjson"
+  }
 
 /**
  * Generated OpenAPI request body object for endpoint payloads.

package/src/http-api/internal/path.ts

@@ -1,3 +1,4 @@
+import { getClosingParenthensePosition } from "../../http/FindMyWay/internal/router.ts"
 import type * as Schema from "../../Schema.ts"
 import * as SchemaAST from "../../SchemaAST.ts"
 
@@ -24,17 +25,8 @@ export function toRouterPath(path: string, schema: Schema.Constraint | undefined
   if (paramNames === undefined) return path
 
   let out = ""
-  let depth = 0
-  let regexStart = -1
   for (let i = 0; i < path.length; i++) {
     const char = path[i]
-    if (depth > 0 || i === regexStart) {
-      out += char
-      if (char === "\\") out += path[++i] ?? ""
-      else if (char === "(") depth++
-      else if (char === ")") depth--
-      continue
-    }
     if (char !== ":") {
       out += char
       continue
@@ -50,12 +42,48 @@ export function toRouterPath(path: string, schema: Schema.Constraint | undefined
       out += param[0]
       i += param[0].length - 1
       const next = path[i + 1]
-      if (next === "(") regexStart = i + 1
-      // FindMyWay needs a regex to end the parameter name here.
-      else if (next !== undefined && !"/.-?".includes(next)) out += "(.*?)"
+      if (next === "(") {
+        const end = getClosingParenthensePosition(path, i + 1)
+        out += path.slice(i + 1, end + 1)
+        i = end
+      } else if (next !== undefined && !"/.-?".includes(next)) {
+        // FindMyWay needs a regex to end the parameter name here.
+        out += "(.*?)"
+      }
     } else {
       out += "::"
     }
   }
   return out
 }
+
+/**
+ * Replaces declared `:name` params, including any regex constraint and `?`.
+ * Returning `undefined` also removes a preceding `/`.
+ *
+ * @internal
+ */
+export function replaceParams(
+  path: string,
+  paramNames: ReadonlySet<string> | undefined,
+  replace: (name: string, optional: boolean) => string | undefined
+): string {
+  const params = /::|:(\w+)/g
+  let out = ""
+  let last = 0
+  for (let param = params.exec(path); param !== null; param = params.exec(path)) {
+    const name = param[1]
+    if (name === undefined || (paramNames !== undefined && !paramNames.has(name))) continue
+    let end = params.lastIndex
+    if (path[end] === "(") end = getClosingParenthensePosition(path, end) + 1
+    const optional = path[end] === "?"
+    if (optional) end++
+    const value = replace(name, optional)
+    let start = param.index
+    if (value === undefined && path[start - 1] === "/") start--
+    out += path.slice(last, start) + (value ?? "")
+    params.lastIndex = end
+    last = end
+  }
+  return out + path.slice(last)
+}

package/src/index.ts

@@ -80,6 +80,12 @@ export * as Boolean from "./Boolean.ts"
  */
 export * as Brand from "./Brand.ts"
 
+/**
+ * @stability unstable
+ * @since 4.0.6
+ */
+export * as Bytes from "./Bytes.ts"
+
 /**
  * @stability unstable
  * @since 4.0.0
@@ -698,6 +704,18 @@ export * as ScopedRef from "./ScopedRef.ts"
  */
 export * as Semaphore from "./Semaphore.ts"
 
+/**
+ * @stability unstable
+ * @since 4.0.6
+ */
+export * as SemVer from "./SemVer.ts"
+
+/**
+ * @stability unstable
+ * @since 4.0.6
+ */
+export * as SemVerRange from "./SemVerRange.ts"
+
 /**
  * @stability stable
  * @since 2.0.0
@@ -764,6 +782,12 @@ export * as Take from "./Take.ts"
  */
 export * as Terminal from "./Terminal.ts"
 
+/**
+ * @stability experimental
+ * @since 4.0.6
+ */
+export * as TextDiff from "./TextDiff.ts"
+
 /**
  * @stability stable
  * @since 2.0.0

package/src/internal/core.ts

@@ -154,7 +154,7 @@ export class CauseImpl<E> implements Cause.Cause<E> {
   toJSON(): unknown {
     return {
       _id: "Cause",
-      failures: this.reasons.map((f) => f.toJSON())
+      reasons: this.reasons.map((f) => f.toJSON())
     }
   }
   toString() {

package/src/internal/dateTime.ts

@@ -238,8 +238,12 @@ export const makeUnsafe = <A extends DateTime.DateTime.Input>(input: A): DateTim
  * so `makeUnsafe` appends "Z" to force UTC interpretation.
  * This check prevents appending "Z" to strings that already have a zone
  * (e.g. "2024-01-01T12:00:00Z", "...+05:30", "...GMT"), which would produce invalid dates.
+ * `Date.parse` also accepts a trailing `z` or `gmt` in any case. Only that trailing
+ * match is case-insensitive, so lowercase letters in a comment like "(xyz)" do not
+ * count as a zone.
  */
-const hasZone = (input: string): boolean => /Z|GMT|[+-]\d{2}$|[+-]\d{2}:?\d{2}$|\]$/.test(input)
+const hasZone = (input: string): boolean =>
+  /Z|GMT|[+-]\d{2}$|[+-]\d{2}:?\d{2}$|\]$/.test(input) || /z$|gmt$/i.test(input)
 
 const minEpochMillis = -8640000000000000 + (12 * 60 * 60 * 1000)
 const maxEpochMillis = 8640000000000000 - (14 * 60 * 60 * 1000)
@@ -364,6 +368,7 @@ const formatOptions: Intl.DateTimeFormatOptions = {
   day: "numeric",
   month: "numeric",
   year: "numeric",
+  era: "short",
   hour: "numeric",
   minute: "numeric",
   second: "numeric",
@@ -428,7 +433,7 @@ export const zoneMakeNamedEffect = (zoneId: string): Effect.Effect<DateTime.Time
 export const zoneMakeLocal = (): DateTime.TimeZone.Named =>
   zoneMakeIntl(new Intl.DateTimeFormat("en-US", formatOptions))
 
-const offsetZoneRegExp = /^(?:GMT|[+-])/
+const offsetZoneRegExp = /^(?:GMT)?[+-]/
 
 /** @internal */
 export const zoneFromString = (zone: string): Option.Option<DateTime.TimeZone> => {
@@ -564,10 +569,18 @@ export const toDate = (self: DateTime.DateTime): Date => {
   } else if (self.adjustedEpochMilliseconds !== undefined) {
     return new Date(self.adjustedEpochMilliseconds)
   }
-  const parts = self.zone.format.formatToParts(self.epochMilliseconds).filter((_) => _.type !== "literal")
+  let bc = false
+  const parts = self.zone.format.formatToParts(self.epochMilliseconds).filter((_) => {
+    if (_.type === "era") {
+      bc = _.value === "BC"
+      return false
+    }
+    return _.type !== "literal"
+  })
+  const year = Number(parts[2].value)
   const date = new Date(0)
   date.setUTCFullYear(
-    Number(parts[2].value),
+    bc ? 1 - year : year,
     Number(parts[0].value) - 1,
     Number(parts[1].value)
   )
@@ -814,7 +827,7 @@ const makeZonedFromAdjusted = (
   return makeZonedProto(adjustedMillis - afterOffset, zone)
 }
 
-const offsetRegExp = /([+-])(\d{2}):(\d{2})$/
+const offsetRegExp = /([+-])(\d{2}):?(\d{2})$/
 const parseOffset = (offset: string): number | null => {
   const match = offsetRegExp.exec(offset)
   if (match === null) {
@@ -1261,10 +1274,10 @@ export const formatIntl: {
 export const formatIso = (self: DateTime.DateTime): string => toDateUtc(self).toISOString()
 
 /** @internal */
-export const formatIsoDate = (self: DateTime.DateTime): string => toDate(self).toISOString().slice(0, 10)
+export const formatIsoDate = (self: DateTime.DateTime): string => toDate(self).toISOString().split("T")[0]
 
 /** @internal */
-export const formatIsoDateUtc = (self: DateTime.DateTime): string => toDateUtc(self).toISOString().slice(0, 10)
+export const formatIsoDateUtc = (self: DateTime.DateTime): string => toDateUtc(self).toISOString().split("T")[0]
 
 /** @internal */
 export const formatIsoOffset = (self: DateTime.DateTime): string => {