effect 4.0.0-beta.60 → 4.0.0-beta.63

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "effect",
   "type": "module",
-  "version": "4.0.0-beta.60",
+  "version": "4.0.0-beta.63",
   "license": "MIT",
   "description": "The missing standard library for TypeScript, for writing production-grade software.",
   "homepage": "https://effect.website",

package/src/Effect.ts

@@ -7762,6 +7762,53 @@ export const orElseSucceed: {
   <A, E, R, A2>(self: Effect<A, E, R>, evaluate: LazyArg<A2>): Effect<A | A2, never, R>
 } = internal.orElseSucceed
 
+/**
+ * Runs a sequence of effects and returns the result of the first successful
+ * one.
+ *
+ * **Details**
+ *
+ * This function executes the provided effects in sequence, stopping at the
+ * first success. If an effect succeeds, its result is returned immediately and
+ * no further effects in the sequence are executed.
+ *
+ * If all effects fail, the returned effect fails with the error from the last
+ * effect. If the collection is empty, the returned effect defects with an
+ * `Error` whose message is `"Received an empty collection of effects"`.
+ *
+ * **When to Use**
+ *
+ * Use `firstSuccessOf` when you have prioritized fallback strategies, such as
+ * attempting multiple APIs, reading configuration from several sources, or
+ * trying alternative resource locations in order.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ *
+ * const primary = Effect.fail("primary unavailable")
+ * const secondary = Effect.succeed("secondary result")
+ * const tertiary = Effect.sync(() => {
+ *   throw new Error("not evaluated")
+ * })
+ *
+ * const program = Effect.firstSuccessOf([
+ *   primary,
+ *   secondary,
+ *   tertiary
+ * ])
+ *
+ * console.log(Effect.runSync(program))
+ * // Output: "secondary result"
+ * ```
+ *
+ * @since 2.0.0
+ * @category Fallback
+ */
+export const firstSuccessOf: <Eff extends Effect<any, any, any>>(
+  effects: Iterable<Eff>
+) => Effect<Success<Eff>, Error<Eff>, Services<Eff>> = internal.firstSuccessOf
+
 // -----------------------------------------------------------------------------
 // Delays & timeouts
 // -----------------------------------------------------------------------------
@@ -11992,6 +12039,47 @@ export const acquireRelease: <A, E, R, R2>(
   options?: { readonly interruptible?: boolean }
 ) => Effect<A, E, R | R2 | Scope> = internal.acquireRelease
 
+/**
+ * This function constructs a scoped resource from an Effect that acquires a
+ * disposable value.
+ *
+ * The resource is automatically disposed when the surrounding
+ * {@link Scope} is closed, using {@link Symbol.dispose} for
+ * synchronous disposables or {@link Symbol.asyncDispose} for asynchronous
+ * disposables.
+ *
+ * This is similar to {@link acquireRelease}, but uses the standard
+ * JavaScript disposal protocal instead of requiring an explicit release
+ * function.
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using}
+ *
+ * @example
+ * ```ts
+ * import sqlite from "node:sqlite";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function* () {
+ *     // acquire database connection
+ *     // database will be closed when the scope is closed
+ *     const db = yield* Effect.acquireDisposable(
+ *       Effect.sync(() => new sqlite.DatabaseSync(":memory:"))
+ *     )
+ *
+ *     const row = db.prepare("SELECT 1 AS value").get()
+ *     yield* Effect.log(row) // { value: 1 }
+ *   })
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ * @category Resource Management & Finalization
+ */
+export const acquireDisposable: <A extends AsyncDisposable | Disposable, E, R>(
+  acquire: Effect<A, E, R>
+) => Effect<A, E, R | Scope> = internal.acquireDisposable
+
 /**
  * This function is used to ensure that an `Effect` value that represents the
  * acquisition of a resource (for example, opening a file, launching a thread,

package/src/index.ts

@@ -3796,7 +3796,7 @@ export * as SchemaRepresentation from "./SchemaRepresentation.ts"
  * - Trim/case strings → {@link trim}, {@link toLowerCase}, {@link toUpperCase}, {@link capitalize}, {@link uncapitalize}, {@link snakeToCamel}
  * - Parse key-value strings → {@link splitKeyValue}
  * - Coerce string ↔ number/bigint → {@link numberFromString}, {@link bigintFromString}
- * - Coerce string ↔ Date → {@link dateFromString}
+ * - Coerce string ↔ Date/Duration → {@link dateFromString}, {@link durationFromString}
  * - Decode durations → {@link durationFromNanos}, {@link durationFromMillis}
  * - Wrap nullable/optional as Option → {@link optionFromNullOr}, {@link optionFromOptionalKey}, {@link optionFromOptional}
  * - Parse URLs → {@link urlFromString}

package/src/internal/effect.ts

@@ -511,6 +511,7 @@ export class FiberImpl<A = any, E = any> implements Fiber.Fiber<A, E> {
     this._children = undefined
     this._interruptedCause = undefined
     this._yielded = undefined
+    this.runtimeMetrics?.recordFiberStart(this.context)
   }
 
   readonly [FiberTypeId]: Fiber.Fiber.Variance<A, E>
@@ -582,7 +583,6 @@ export class FiberImpl<A = any, E = any> implements Fiber.Fiber<A, E> {
     return this._exit
   }
   evaluate(effect: Primitive): void {
-    this.runtimeMetrics?.recordFiberStart(this.context)
     if (this._exit) {
       return
     } else if (this._yielded !== undefined) {
@@ -3183,6 +3183,24 @@ export const orElseSucceed: {
   ): Effect.Effect<A | B, never, R> => catch_(self, (_) => sync(f))
 )
 
+/** @internal */
+export const firstSuccessOf = <Eff extends Effect.Effect<any, any, any>>(
+  effects: Iterable<Eff>
+): Effect.Effect<Effect.Success<Eff>, Effect.Error<Eff>, Effect.Services<Eff>> =>
+  suspend(() => {
+    const iterator = effects[Symbol.iterator]()
+    let state = iterator.next()
+    if (state.done) {
+      return die(new Error("Received an empty collection of effects"))
+    }
+    function loop(current: IteratorYieldResult<Eff>): Eff {
+      const next = iterator.next()
+      if (next.done) return current.value
+      return catch_(current.value, (_) => loop(next)) as any
+    }
+    return loop(state)
+  })
+
 /** @internal */
 export const eventually = <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, never, R> =>
   catch_(self, (_) => flatMap(yieldNow, () => eventually(self)))
@@ -4035,6 +4053,15 @@ export const acquireUseRelease = <Resource, E, R, A, E2, R2, E3, R3>(
       ))
   )
 
+/** @internal */
+export const acquireDisposable = <A extends AsyncDisposable | Disposable, E, R>(
+  acquire: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, R | Scope.Scope> =>
+  acquireRelease(acquire, (resource) =>
+    hasProperty(resource, Symbol.asyncDispose)
+      ? promise(() => resource[Symbol.asyncDispose]())
+      : sync(() => resource[Symbol.dispose]()))
+
 // ----------------------------------------------------------------------------
 // Caching
 // ----------------------------------------------------------------------------

package/src/unstable/cluster/K8sHttpClient.ts

@@ -203,7 +203,7 @@ export class PodStatus extends Schema.Class<PodStatus>("@effect/cluster/K8sHttpC
   conditions: Schema.Array(Schema.Struct({
     type: Schema.String,
     status: Schema.String,
-    lastTransitionTime: Schema.String
+    lastTransitionTime: Schema.NullOr(Schema.String)
   })),
   podIP: Schema.String,
   hostIP: Schema.String
@@ -227,8 +227,8 @@ export class Pod extends Schema.Class<Pod>("@effect/cluster/K8sHttpClient/Pod")(
   }
 
   get isReadyOrInitializing(): boolean {
-    let initializedAt: string | undefined
-    let readyAt: string | undefined
+    let initializedAt: string | null | undefined
+    let readyAt: string | null | undefined
     for (let i = 0; i < this.status.conditions.length; i++) {
       const condition = this.status.conditions[i]
       switch (condition.type) {

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -15,7 +15,7 @@ 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 type * as AST from "../../SchemaAST.ts"
+import * as AST from "../../SchemaAST.ts"
 import * as Issue from "../../SchemaIssue.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
 import * as Scope from "../../Scope.ts"
@@ -77,7 +77,7 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
       key.startsWith("effect/httpapi/HttpApiGroup/")
     )
     for (const group of Object.values(api.groups)) {
-      const groupRoutes = services.mapUnsafe.get(group.key) as Array<HttpRouter.Route<any, any>>
+      const groupRoutes = services.mapUnsafe.get(group.key)?.routes as Array<HttpRouter.Route<any, any>>
       if (groupRoutes === undefined) {
         const available = availableGroups.length === 0 ? "none" : availableGroups.join(", ")
         return yield* Effect.die(
@@ -130,10 +130,15 @@ export const group = <
       ? (yield* result as Effect.Effect<any, any, any>)
       : result
     const routes: Array<HttpRouter.Route<any, any>> = []
-    for (const item of handlers.handlers) {
+    for (const item of handlers.handlers.values()) {
       routes.push(handlerToRoute(group as any, item, services))
     }
-    return Context.makeUnsafe(new Map([[group.key, routes]]))
+    return Context.makeUnsafe(
+      new Map([[group.key, {
+        routes,
+        handlers: handlers.handlers
+      }]])
+    )
   })) as any
 
 /**
@@ -162,7 +167,7 @@ export interface Handlers<
     _Endpoints: Covariant<Endpoints>
   }
   readonly group: HttpApiGroup.AnyWithProps
-  readonly handlers: Set<Handlers.Item<R>>
+  readonly handlers: Map<string, Handlers.Item<R>>
 
   /**
    * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
@@ -449,7 +454,7 @@ const HandlersProto = {
     options?: { readonly uninterruptible?: boolean | undefined } | undefined
   ) {
     const endpoint = this.group.endpoints[name]
-    this.handlers.add({
+    this.handlers.set(name, {
       endpoint,
       handler,
       isRaw: false,
@@ -464,7 +469,7 @@ const HandlersProto = {
     options?: { readonly uninterruptible?: boolean | undefined } | undefined
   ) {
     const endpoint = this.group.endpoints[name]
-    this.handlers.add({
+    this.handlers.set(name, {
       endpoint,
       handler,
       isRaw: true,
@@ -479,7 +484,7 @@ const makeHandlers = <R, Endpoints extends HttpApiEndpoint.Any>(
 ): Handlers<R, Endpoints> => {
   const self = Object.create(HandlersProto)
   self.group = group
-  self.handlers = new Set<Handlers.Item<R>>()
+  self.handlers = new Map<string, Handlers.Item<R>>()
   return self
 }
 
@@ -492,6 +497,7 @@ type PayloadDecoder =
   }
   | {
     readonly _tag: "Json" | "FormUrlEncoded" | "Uint8Array" | "Text"
+    readonly nullOnEmpty: boolean
     readonly decode: (input: unknown) => Effect.Effect<unknown, Schema.SchemaError, unknown>
   }
 
@@ -504,7 +510,11 @@ function buildPayloadDecoders(
     if (encoding._tag === "Multipart") {
       result.set(contentType, { _tag: "Multipart", mode: encoding.mode, limits: encoding.limits, decode })
     } else {
-      result.set(contentType, { _tag: encoding._tag, decode })
+      result.set(contentType, {
+        _tag: encoding._tag,
+        decode,
+        nullOnEmpty: schemas.some((s) => AST.isNull(AST.toEncoded(s.ast)))
+      })
     }
   })
   return result
@@ -527,21 +537,26 @@ function decodePayload(
   switch (_tag) {
     case "Multipart": {
       if (existing.mode === "buffered") {
-        return Effect.flatMap(
-          Effect.orDie(UndefinedOr.match(existing.limits, {
-            onUndefined: () => httpRequest.multipart,
-            onDefined: (limits) => Effect.provideContext(httpRequest.multipart, Multipart.limitsServices(limits))
-          })),
-          decode
-        )
+        let eff = Effect.orDie(httpRequest.multipart)
+        if (existing.limits) {
+          eff = Effect.provideContext(eff, Multipart.limitsServices(existing.limits))
+        }
+        return Effect.flatMap(eff, decode)
       }
-      return Effect.succeed(UndefinedOr.match(existing.limits, {
-        onUndefined: () => httpRequest.multipartStream,
-        onDefined: (limits) => Stream.provideContext(httpRequest.multipartStream, Multipart.limitsServices(limits))
-      }))
+      return Effect.succeed(
+        existing.limits
+          ? Stream.provideContext(httpRequest.multipartStream, Multipart.limitsServices(existing.limits))
+          : httpRequest.multipartStream
+      )
     }
     case "Json":
-      return Effect.flatMap(Effect.orDie(httpRequest.json), decode)
+      const json = Effect.orDie(Effect.flatMap(httpRequest.text, (text) => {
+        if (text === "") {
+          return existing.nullOnEmpty ? Effect.succeed(null) : Effect.undefined
+        }
+        return Effect.succeed(JSON.parse(text))
+      }))
+      return Effect.flatMap(json, decode)
     case "Text":
       return Effect.flatMap(Effect.orDie(httpRequest.text), decode)
     case "FormUrlEncoded": {
@@ -622,7 +637,8 @@ function handlerToHttpEffect(
   )
 }
 
-function handlerToRoute(
+/** @internal */
+export function handlerToRoute(
   group: HttpApiGroup.AnyWithProps,
   handler: Handlers.Item<any>,
   context: Context.Context<any>

package/src/unstable/httpapi/HttpApiClient.ts

@@ -175,7 +175,8 @@ type UrlBuilderTopLevelMethods<Groups extends HttpApiGroup.Any> = Extract<Groups
   : never :
   never
 
-const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>(
+/** @internal */
+export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>(
   api: HttpApi.HttpApi<ApiId, Groups>,
   options: {
     readonly httpClient: HttpClient.HttpClient.With<E, R>
@@ -201,9 +202,9 @@ const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>
       | undefined
     readonly baseUrl?: URL | string | undefined
   }
-): Effect.Effect<void, unknown, unknown> =>
+): Effect.Effect<void> =>
   Effect.gen(function*() {
-    const services = yield* Effect.context<any>()
+    const services = yield* Effect.context()
 
     const httpClient = options.httpClient.pipe(
       options?.baseUrl === undefined

package/src/unstable/httpapi/HttpApiTest.ts

@@ -0,0 +1,95 @@
+/**
+ * @since 4.0.0
+ */
+import * as Context from "../../Context.ts"
+import * as Effect from "../../Effect.ts"
+import type { FileSystem } from "../../FileSystem.ts"
+import * as Layer from "../../Layer.ts"
+import type { Path } from "../../Path.ts"
+import type { Scope } from "../../Scope.ts"
+import type { Generator } from "../http/Etag.ts"
+import * as HttpClient from "../http/HttpClient.ts"
+import type { HttpPlatform } from "../http/HttpPlatform.ts"
+import * as HttpRouter from "../http/HttpRouter.ts"
+import * as HttpServerRequest from "../http/HttpServerRequest.ts"
+import * as HttpServerResponse from "../http/HttpServerResponse.ts"
+import type * as HttpApi from "./HttpApi.ts"
+import type { Handlers } from "./HttpApiBuilder.ts"
+import * as HttpApiBuilder from "./HttpApiBuilder.ts"
+import * as HttpApiClient from "./HttpApiClient.ts"
+import type * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
+import type * as HttpApiGroup from "./HttpApiGroup.ts"
+
+/**
+ * @since 4.0.0
+ * @category Testing
+ */
+export const groups = Effect.fnUntraced(function*<
+  ApiId extends string,
+  Groups extends HttpApiGroup.Any,
+  const Names extends ReadonlyArray<HttpApiGroup.Name<Groups>>,
+  SelectedGroups = HttpApiGroup.WithName<Groups, Names[number]>
+>(
+  api: HttpApi.HttpApi<ApiId, Groups>,
+  groupNames: Names
+): Effect.fn.Return<
+  HttpApiClient.Client<Groups>,
+  never,
+  | HttpApiGroup.ToService<ApiId, SelectedGroups>
+  | HttpApiGroup.MiddlewareClient<Groups>
+  | HttpApiEndpoint.Middleware<HttpApiGroup.Endpoints<Groups>>
+  | FileSystem
+  | Generator
+  | HttpPlatform
+  | Path
+  | Scope
+> {
+  let context = yield* Effect.context<HttpApiGroup.ToService<ApiId, SelectedGroups>>()
+
+  for (const name in api.groups) {
+    const group = api.groups[name]
+    if (groupNames.includes(name as any)) {
+      continue
+    }
+    const handlers = new Map<string, Handlers.Item<never>>()
+    const routes: Array<HttpRouter.Route<any, any>> = []
+    for (const endpointName in group.endpoints) {
+      const endpoint = group.endpoints[endpointName]
+      const handler: Handlers.Item<never> = {
+        endpoint: endpoint as any,
+        handler: () => Effect.die(new Error(`Unhandled endpoint: ${endpointName}`)),
+        isRaw: false,
+        uninterruptible: false
+      }
+      handlers.set(endpointName, handler)
+      routes.push(HttpApiBuilder.handlerToRoute(group as any, handler, context))
+    }
+    context = Context.add(context, group as any, { handlers, routes })
+  }
+
+  const layer: Layer.Layer<
+    never,
+    never,
+    | FileSystem
+    | Generator
+    | HttpPlatform
+    | HttpRouter.HttpRouter
+    | Path
+  > = HttpApiBuilder.layer(api).pipe(
+    Layer.provide(Layer.succeedContext(context))
+  ) as any
+  const handler = yield* HttpRouter.toHttpEffect(layer)
+  const httpClient = HttpClient.make(Effect.fnUntraced(function*(request) {
+    const serverRequest = HttpServerRequest.fromClientRequest(request)
+    const response = yield* handler.pipe(
+      Effect.provideService(HttpServerRequest.HttpServerRequest, serverRequest),
+      Effect.orDie
+    )
+    return HttpServerResponse.toClientResponse(response)
+  }, Effect.scoped))
+
+  return yield* HttpApiClient.makeWith(api, {
+    httpClient,
+    baseUrl: "http://localhost:3000"
+  })
+})

package/src/unstable/httpapi/index.ts

@@ -85,6 +85,11 @@ export * as HttpApiSecurity from "./HttpApiSecurity.ts"
  */
 export * as HttpApiSwagger from "./HttpApiSwagger.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as HttpApiTest from "./HttpApiTest.ts"
+
 /**
  * @since 4.0.0
  */