effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/SchemaUtils.ts

@@ -37,7 +37,7 @@
  */
 import { identity } from "./Function.ts"
 import * as Schema from "./Schema.ts"
-import * as Transformation from "./SchemaTransformation.ts"
+import * as SchemaTransformation from "./SchemaTransformation.ts"
 
 /**
  * Builds an experimental schema for instances of a native class using a struct
@@ -68,7 +68,7 @@ export function getNativeClassSchema<C extends new(...args: any) => any, S exten
     readonly annotations?: Schema.Annotations.Declaration<InstanceType<C>>
   }
 ): Schema.decodeTo<Schema.instanceOf<InstanceType<C>, S["Iso"]>, S> {
-  const transformation = Transformation.transform<InstanceType<C>, S["Type"]>({
+  const transformation = SchemaTransformation.transform<InstanceType<C>, S["Type"]>({
     decode: (props) => new constructor(props),
     encode: identity
   })

package/src/Scope.ts

@@ -290,6 +290,11 @@ export const make: (finalizerStrategy?: "sequential" | "parallel") => Effect<Clo
  * This is useful when you need a scope immediately but should be used with caution
  * as it doesn't provide the same safety guarantees as the `Effect`-wrapped version.
  *
+ * **When to use**
+ *
+ * Use when a scope must be allocated synchronously and the caller will close it
+ * manually.
+ *
  * **Example** (Creating a scope synchronously)
  *
  * ```ts
@@ -420,6 +425,11 @@ export const provide: {
 /**
  * Registers an exit-aware finalizer on a scope.
  *
+ * **When to use**
+ *
+ * Use when cleanup needs to know whether the scope closed with success,
+ * failure, or interruption.
+ *
  * **Details**
  *
  * If the scope is open, the finalizer runs when the scope closes and receives
@@ -537,6 +547,11 @@ export const fork: (
 /**
  * Creates a closeable child scope synchronously and registers it with a parent scope.
  *
+ * **When to use**
+ *
+ * Use when a child scope must be created synchronously and the caller controls
+ * both parent and child scope lifetimes.
+ *
  * **Details**
  *
  * Closing the parent closes the child with the same exit value, and closing the

package/src/ScopedCache.ts

@@ -128,7 +128,7 @@ export interface Entry<A, E> {
  *
  * **When to use**
  *
- * Use when cached scoped resources need different lifetimes based on the lookup
+ * Use when you need a scoped cache whose entry lifetime depends on each lookup
  * result or key.
  *
  * **Details**

package/src/ScopedRef.ts

@@ -73,8 +73,7 @@ const makeUnsafe = <A>(
 }
 
 /**
- * Creates a new `ScopedRef` from an effect that resourcefully produces a
- * value.
+ * Creates a new `ScopedRef` from an effect that acquires the initial value.
  *
  * **When to use**
  *
@@ -150,7 +149,7 @@ export const get = <A>(self: ScopedRef<A>): Effect.Effect<A> => Effect.sync(() =
  * `fromAcquire` so acquisition and finalization are tracked.
  *
  * @see {@link fromAcquire} for creating a `ScopedRef` from an effect that acquires the initial value
- * @see {@link set} for replacing the current value with a resourcefully acquired value
+ * @see {@link set} for replacing the current value with a newly acquired value
  *
  * @category constructors
  * @since 2.0.0
@@ -164,14 +163,13 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
   })
 
 /**
- * Sets the value of this reference to the specified resourcefully-created
- * value, releasing any resources associated with the old value.
+ * Sets the value of this reference to a newly acquired scoped value, releasing
+ * any resources associated with the old value.
  *
  * **When to use**
  *
- * Use to replace the current value of an existing `ScopedRef` with a
- * resourcefully acquired value while releasing resources for the previous
- * value.
+ * Use to replace the current value of an existing `ScopedRef` with a newly
+ * acquired scoped value while releasing resources for the previous value.
  *
  * **Details**
  *
@@ -184,14 +182,13 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
  */
 export const set: {
   /**
-   * Sets the value of this reference to the specified resourcefully-created
-   * value, releasing any resources associated with the old value.
+   * Sets the value of this reference to a newly acquired scoped value, releasing
+   * any resources associated with the old value.
    *
    * **When to use**
    *
-   * Use to replace the current value of an existing `ScopedRef` with a
-   * resourcefully acquired value while releasing resources for the previous
-   * value.
+   * Use to replace the current value of an existing `ScopedRef` with a newly
+   * acquired scoped value while releasing resources for the previous value.
    *
    * **Details**
    *
@@ -204,14 +201,13 @@ export const set: {
    */
   <A, R, E>(acquire: Effect.Effect<A, E, R>): (self: ScopedRef<A>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>>
   /**
-   * Sets the value of this reference to the specified resourcefully-created
-   * value, releasing any resources associated with the old value.
+   * Sets the value of this reference to a newly acquired scoped value, releasing
+   * any resources associated with the old value.
    *
    * **When to use**
    *
-   * Use to replace the current value of an existing `ScopedRef` with a
-   * resourcefully acquired value while releasing resources for the previous
-   * value.
+   * Use to replace the current value of an existing `ScopedRef` with a newly
+   * acquired scoped value while releasing resources for the previous value.
    *
    * **Details**
    *

package/src/Semaphore.ts

@@ -625,7 +625,7 @@ export const withPermitsIfAvailable: {
  *
  * **When to use**
  *
- * Use to manually acquire permits when a lower-level permit protocol needs
+ * Use when you need manual permit acquisition for a lower-level protocol with
  * explicit acquisition and release control.
  *
  * **Details**
@@ -646,7 +646,7 @@ export const take: {
    *
    * **When to use**
    *
-   * Use to manually acquire permits when a lower-level permit protocol needs
+   * Use when you need manual permit acquisition for a lower-level protocol with
    * explicit acquisition and release control.
    *
    * **Details**
@@ -667,7 +667,7 @@ export const take: {
    *
    * **When to use**
    *
-   * Use to manually acquire permits when a lower-level permit protocol needs
+   * Use when you need manual permit acquisition for a lower-level protocol with
    * explicit acquisition and release control.
    *
    * **Details**
@@ -690,8 +690,8 @@ export const take: {
  *
  * **When to use**
  *
- * Use to manually return permits acquired with `take` when a lower-level
- * permit protocol needs explicit release control.
+ * Use when you need to return permits acquired with `take` in a lower-level
+ * permit protocol with explicit release control.
  *
  * **Details**
  *
@@ -719,8 +719,8 @@ export const release: {
    *
    * **When to use**
    *
-   * Use to manually return permits acquired with `take` when a lower-level
-   * permit protocol needs explicit release control.
+   * Use when you need to return permits acquired with `take` in a lower-level
+   * permit protocol with explicit release control.
    *
    * **Details**
    *
@@ -748,8 +748,8 @@ export const release: {
    *
    * **When to use**
    *
-   * Use to manually return permits acquired with `take` when a lower-level
-   * permit protocol needs explicit release control.
+   * Use when you need to return permits acquired with `take` in a lower-level
+   * permit protocol with explicit release control.
    *
    * **Details**
    *

package/src/Sink.ts

@@ -448,8 +448,8 @@ export declare namespace make {
  *
  * **When to use**
  *
- * Use when the effect needs to provide both the result value and optional
- * leftovers.
+ * Use when you need to create a sink from an effect that returns both the sink
+ * result value and optional leftovers.
  *
  * @category constructors
  * @since 4.0.0
@@ -1224,8 +1224,8 @@ export const mapEffectEnd: {
  *
  * **When to use**
  *
- * Use when transforming a sink result itself is effectful, can fail, or needs
- * services.
+ * Use when you need a sink result transformation that is effectful, can fail,
+ * or requires services.
  *
  * **Details**
  *
@@ -1245,8 +1245,8 @@ export const mapEffect: {
    *
    * **When to use**
    *
-   * Use when transforming a sink result itself is effectful, can fail, or needs
-   * services.
+   * Use when you need a sink result transformation that is effectful, can fail,
+   * or requires services.
    *
    * **Details**
    *
@@ -1266,8 +1266,8 @@ export const mapEffect: {
    *
    * **When to use**
    *
-   * Use when transforming a sink result itself is effectful, can fail, or needs
-   * services.
+   * Use when you need a sink result transformation that is effectful, can fail,
+   * or requires services.
    *
    * **Details**
    *
@@ -1691,7 +1691,8 @@ const last_ = reduceArray(Option.none<unknown>, (_, arr) => Arr.last(arr))
  *
  * **When to use**
  *
- * Use when consuming all upstream input and only the final element is needed.
+ * Use when you need to consume all upstream input and keep only the final
+ * element.
  *
  * **Details**
  *
@@ -1785,8 +1786,8 @@ export const find: {
  *
  * **When to use**
  *
- * Use when deciding whether an input matches requires an effect, can fail, or
- * needs services.
+ * Use when you need to run effects, fail, or use services while searching for
+ * the first matching input.
  *
  * **Details**
  *
@@ -1838,8 +1839,7 @@ export const count: Sink<number, unknown> = reduceArray(() => 0, (s, arr) => s +
  *
  * **When to use**
  *
- * Use to collect all upstream input elements into a single array when you need
- * a sink result containing the complete input.
+ * Use when you need a sink result containing all upstream input elements.
  *
  * @see {@link take} for collecting only a fixed number of input elements
  *

package/src/Stdio.ts

@@ -95,8 +95,8 @@ export interface Stdio {
  *
  * **When to use**
  *
- * Use when an effect needs command-line arguments or standard I/O streams
- * supplied by its environment.
+ * Use when you need command-line arguments or standard I/O streams supplied by
+ * an effect's environment.
  *
  * @see {@link make} for constructing a `Stdio` service directly
  * @see {@link layerTest} for a test layer with defaults and overrides
@@ -112,9 +112,8 @@ export const Stdio: Context.Service<Stdio, Stdio> = Context.Service<Stdio>(TypeI
  *
  * **When to use**
  *
- * Use to assemble a concrete `Stdio` service when you already have
- * implementations for command-line arguments, standard output, standard error,
- * and standard input.
+ * Use when you need to assemble a concrete `Stdio` service from command-line
+ * arguments and standard I/O implementations.
  *
  * **Details**
  *