effect 4.0.0-beta.68 → 4.0.0-beta.69

package/src/index.ts

@@ -894,7 +894,8 @@ export * as Cron from "./Cron.ts"
  * and message digests. The base `Random` service is not cryptographically
  * secure unless you replace it with a cryptographically secure implementation.
  *
- * @example
+ * **Example** (Providing a test Crypto service)
+ *
  * ```ts
  * import { Console, Crypto, Effect, Layer } from "effect"
  *
@@ -915,7 +916,8 @@ export * as Cron from "./Cron.ts"
  * Effect.runPromise(Effect.provide(program, TestCrypto))
  * ```
  *
- * @example
+ * **Example** (Generating random bytes)
+ *
  * ```ts
  * import { Crypto, Effect, Layer } from "effect"
  *
@@ -1219,7 +1221,7 @@ export * as Duration from "./Duration.ts"
  * - **Testable**: Built-in support for testing with controlled environments
  * - **Interruptible**: Effects can be safely interrupted and cancelled
  *
- * **Example** (Usage)
+ * **Example** (Creating and running effects)
  *
  * ```ts
  * import { Console, Effect } from "effect"
@@ -1238,7 +1240,7 @@ export * as Duration from "./Duration.ts"
  * Effect.runPromise(program).then(console.log) // 13
  * ```
  *
- * **Example** (Usage)
+ * **Example** (Handling typed failures)
  *
  * ```ts
  * import { Data, Effect } from "effect"
@@ -2290,8 +2292,7 @@ export * as HKT from "./HKT.ts"
  * **Example** (Creating inspectable values)
  *
  * ```ts
- * import { Inspectable } from "effect"
- * import { format } from "effect/Formatter"
+ * import { Formatter, Inspectable } from "effect"
  *
  * class User extends Inspectable.Class {
  *   constructor(
@@ -2312,7 +2313,7 @@ export * as HKT from "./HKT.ts"
  *
  * const user = new User("Alice", "alice@example.com")
  * console.log(user.toString()) // Pretty printed JSON
- * console.log(format(user)) // Same as toString()
+ * console.log(Formatter.format(user)) // Same as toString()
  * ```
  *
  * @since 2.0.0
@@ -2388,7 +2389,7 @@ export * as Iterable from "./Iterable.ts"
  * **Example** (Computing and applying a patch)
  *
  * ```ts
- * import * as JsonPatch from "effect/JsonPatch"
+ * import { JsonPatch } from "effect"
  *
  * const oldValue = { name: "Alice", age: 30 }
  * const newValue = { name: "Alice", age: 31, city: "NYC" }
@@ -2443,15 +2444,15 @@ export * as JsonPatch from "./JsonPatch.ts"
  * **Example** (Building and parsing a JSON Pointer)
  *
  * ```ts
- * import { escapeToken, unescapeToken } from "effect/JsonPointer"
+ * import { JsonPointer } from "effect"
  *
  * // Build a JSON Pointer from path segments
  * const segments = ["users", "name/alias", "value"]
- * const pointer = "/" + segments.map(escapeToken).join("/")
+ * const pointer = "/" + segments.map(JsonPointer.escapeToken).join("/")
  * // "/users/name~1alias/value"
  *
  * // Parse a JSON Pointer back to segments
- * const tokens = pointer.split("/").slice(1).map(unescapeToken)
+ * const tokens = pointer.split("/").slice(1).map(JsonPointer.unescapeToken)
  * // ["users", "name/alias", "value"]
  * ```
  *
@@ -2585,7 +2586,7 @@ export * as JsonSchema from "./JsonSchema.ts"
  * - Prefer the effectful APIs unless synchronous allocation or mutation is
  *   required
  *
- * @since 3.8.0
+ * @since 4.0.0
  */
 export * as Latch from "./Latch.ts"
 
@@ -2959,7 +2960,6 @@ export * as Metric from "./Metric.ts"
  * - Size: O(1)
  * - Iteration: O(n)
  *
- * @category data-structures
  * @since 2.0.0
  */
 export * as MutableHashMap from "./MutableHashMap.ts"
@@ -3034,8 +3034,6 @@ export * as MutableHashMap from "./MutableHashMap.ts"
  * // Output: ["apple", "cherry"]
  * ```
  *
- * @fileoverview
- * @category data-structures
  * @since 2.0.0
  */
 export * as MutableHashSet from "./MutableHashSet.ts"
@@ -3088,8 +3086,6 @@ export * as MutableHashSet from "./MutableHashSet.ts"
  * - {@link remove} uses JavaScript strict equality semantics, not structural
  *   equality
  *
- * @fileoverview
- * @category data-structures
  * @since 4.0.0
  */
 export * as MutableList from "./MutableList.ts"
@@ -3126,7 +3122,6 @@ export * as MutableList from "./MutableList.ts"
  * - `compareAndSet` compares with Effect equality semantics, not only JavaScript reference equality
  * - For state that must participate in `Effect` workflows, interruption, or fiber coordination, prefer higher-level Effect data types
  *
- * @category data-structures
  * @since 2.0.0
  */
 export * as MutableRef from "./MutableRef.ts"
@@ -3231,7 +3226,7 @@ export * as Newtype from "./Newtype.ts"
  * **Example** (Requiring a non-empty iterable)
  *
  * ```ts
- * import * as NonEmptyIterable from "effect/NonEmptyIterable"
+ * import { NonEmptyIterable } from "effect"
  *
  * // NonEmptyIterable is a type that represents any iterable with at least one element
  * function processNonEmpty<A>(data: NonEmptyIterable.NonEmptyIterable<A>): A {
@@ -3317,7 +3312,7 @@ export * as Newtype from "./Newtype.ts"
  *
  * ```ts
  * import { Array, pipe } from "effect"
- * import type * as NonEmptyIterable from "effect/NonEmptyIterable"
+ * import type { NonEmptyIterable } from "effect"
  *
  * // Many Array functions work with NonEmptyIterable
  * declare const nonEmptyData: NonEmptyIterable.NonEmptyIterable<number>
@@ -3609,8 +3604,6 @@ export * as Order from "./Order.ts"
  *   right value, while `1` means it should come after
  * - Reversing an `Ordering` swaps `-1` and `1`, but leaves `0` unchanged
  *
- * @fileoverview
- * @category utilities
  * @since 2.0.0
  */
 export * as Ordering from "./Ordering.ts"
@@ -3811,7 +3804,7 @@ export * as Pool from "./Pool.ts"
  * **Example** (Filter by a predicate)
  *
  * ```ts
- * import * as Predicate from "effect/Predicate"
+ * import { Predicate } from "effect"
  *
  * const isPositive = (n: number) => n > 0
  * const data = [2, -1, 3]
@@ -5159,7 +5152,7 @@ export * as ScopedRef from "./ScopedRef.ts"
  *   the requested permits cannot be acquired immediately.
  * - Manual `take` / `release` usage must keep permit counts balanced.
  *
- * @since 2.0.0
+ * @since 4.0.0
  */
 export * as Semaphore from "./Semaphore.ts"
 
@@ -5181,12 +5174,11 @@ export * as Semaphore from "./Semaphore.ts"
  * **Common tasks**
  *
  * - Create simple sinks: {@link succeed}, {@link fail}, {@link fromEffect}
- * - Fold input: {@link fold}, {@link foldEffect}, {@link foldLeft}
- * - Collect values: {@link collectAll}, {@link collectAllN}, {@link collectAllWhile}
+ * - Fold input: {@link fold}
+ * - Collect values: {@link collect}
  * - Count or drain input: {@link count}, {@link drain}
  * - Transform results: {@link map}, {@link mapEffect}, {@link as}
- * - Combine sinks: {@link zip}, {@link zipWith}, {@link race}
- * - Filter and refine input: {@link filterInput}, {@link filterInputEffect}
+ * - Adapt input before consumption: {@link mapInput}, {@link mapInputEffect}
  *
  * **Gotchas**
  *
@@ -5649,7 +5641,7 @@ export * as TxHashMap from "./TxHashMap.ts"
  * - Mutate an existing set with {@link add}, {@link remove}, and {@link clear}
  * - Query membership and size with {@link has}, {@link size}, and {@link isEmpty}
  * - Derive new sets with {@link map}, {@link filter}, {@link union}, {@link intersection}, and {@link difference}
- * - Fold or collect values with {@link reduce}, {@link toArray}, and {@link toHashSet}
+ * - Fold or collect values with {@link reduce} and {@link toHashSet}
  *
  * **Gotchas**
  *

package/src/unstable/ai/index.ts

@@ -353,8 +353,8 @@ export * as McpServer from "./McpServer.ts"
  * **Example** (Creating a provider-specific model)
  *
  * ```ts
- * import type { Layer } from "effect"
  * import { Effect } from "effect"
+ * import type { Layer } from "effect"
  * import { LanguageModel, Model } from "effect/unstable/ai"
  *
  * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>

package/src/unstable/cli/Flag.ts

@@ -641,6 +641,30 @@ export const withMetavar: {
   <A>(self: Flag<A>, metavar: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, metavar: string) => Param.withMetavar(self, metavar))
 
+/**
+ * Hides a flag from generated help output and shell completions while keeping
+ * it fully parseable on the command line.
+ *
+ * Useful for experimental or internal flags that should be accepted but not
+ * advertised — for example, `--experimental-foo`, debug toggles, or escape
+ * hatches that are not yet committed to the public CLI surface.
+ *
+ * **Example** (Hiding a flag from help)
+ *
+ * ```ts
+ * import { Flag } from "effect/unstable/cli"
+ *
+ * // Flag still parses --experimental-foo, but it does not appear in --help.
+ * const experimental = Flag.boolean("experimental-foo").pipe(
+ *   Flag.withHidden
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export const withHidden = <A>(self: Flag<A>): Flag<A> => Param.withHidden(self)
+
 /**
  * Makes a flag optional, returning an Option type that can be None if not provided.
  *

package/src/unstable/cli/Param.ts

@@ -205,6 +205,7 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly aliases: ReadonlyArray<string>
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
+  readonly hidden: boolean
 }
 
 /**
@@ -346,6 +347,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly typeName?: string | undefined
   readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
+  readonly hidden?: boolean | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -356,6 +358,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
     ...params,
     description: params.description ?? Option.none(),
     aliases: params.aliases ?? [],
+    hidden: params.hidden ?? false,
     parse
   })
 }
@@ -1107,6 +1110,35 @@ export const withDescription: {
     }))
 })
 
+/**
+ * Hides a parameter from generated help output and completions while keeping
+ * it parseable on the command line.
+ *
+ * Useful for experimental, internal, or deprecated flags that should be
+ * accepted but not advertised.
+ *
+ * **Example** (Hiding a flag from help)
+ *
+ * ```ts
+ * import { Param } from "effect/unstable/cli"
+ *
+ * // @internal - this module is not exported publicly
+ *
+ * const experimental = Param.boolean(Param.flagKind, "experimental-foo").pipe(
+ *   Param.withHidden
+ * )
+ * ```
+ *
+ * @category metadata
+ * @since 4.0.0
+ */
+export const withHidden = <Kind extends ParamKind, A>(self: Param<Kind, A>): Param<Kind, A> =>
+  transformSingle(self, <X>(single: Single<Kind, X>) =>
+    makeSingle({
+      ...single,
+      hidden: true
+    }))
+
 /**
  * Transforms the parsed value of an option using a mapping function.
  *

package/src/unstable/cli/index.ts

@@ -230,7 +230,7 @@ export * as HelpDoc from "./HelpDoc.ts"
  *   value; this is important for argument ordering and variadic parameters.
  * - Some parsers require CLI services such as filesystem, path, terminal, or
  *   child-process support through the parsing environment.
- * @internal
+ *
  * @since 4.0.0
  */
 export * as Param from "./Param.ts"

package/src/unstable/cli/internal/command.ts

@@ -157,6 +157,9 @@ export const makeCommand = <const Name extends string, Input, E, R, ContextInput
     for (const option of config.flags) {
       const singles = Param.extractSingleParams(option)
       for (const single of singles) {
+        // Hidden flags still parse on the command line but are omitted from
+        // generated --help output.
+        if (single.hidden) continue
         flags.push(toFlagDoc(single))
       }
     }

package/src/unstable/cli/internal/completions/descriptor.ts

@@ -85,6 +85,9 @@ export const fromCommand = (cmd: Command.Any): Completions.CommandDescriptor =>
     const singles = Param.extractSingleParams(flag)
     for (const single of singles) {
       if (single.kind !== "flag") continue
+      // Omit hidden flags from completion scripts so tab-completion in the
+      // shell does not advertise flags that are absent from --help.
+      if (single.hidden) continue
       flags.push({
         name: single.name,
         aliases: single.aliases,

package/src/unstable/cli/internal/help.ts

@@ -115,6 +115,12 @@ const getSharedFlagsForCommandPath = (
         if (seen.has(single.name)) {
           continue
         }
+        // Hidden ancestor flags are excluded from the shared-flags section
+        // of subcommand help, the same way they're excluded from the owning
+        // command's own help output.
+        if (single.hidden) {
+          continue
+        }
         seen.add(single.name)
         sharedFlags.push(toFlagDoc(single))
       }
@@ -160,6 +166,10 @@ export const getHelpForCommandPath = <Name extends string, Input, E, R, ContextI
     for (const flag of flags) {
       const singles = Param.extractSingleParams(flag.flag)
       for (const single of singles) {
+        // Same rule as command-local flags: hidden globals are still parsed
+        // and still trigger their handlers, they just don't appear under
+        // "GLOBAL FLAGS" in --help.
+        if (single.hidden) continue
         globalFlagDocs.push({
           ...toFlagDoc(single),
           required: false

package/src/unstable/cli/internal/parser.ts

@@ -517,6 +517,9 @@ const createUnrecognizedFlagError = (
   const validNames: Array<string> = []
 
   for (const p of params) {
+    // Exclude hidden flags so a near-miss typo cannot reveal a flag name
+    // that was intentionally kept out of --help.
+    if (p.hidden) continue
     validNames.push(p.name)
     if (Primitive.isBoolean(p.primitiveType)) {
       validNames.push(`no-${p.name}`)

package/src/unstable/cluster/index.ts

@@ -740,7 +740,7 @@ export * as ShardId from "./ShardId.ts"
  * transparency for stateful entities, singleton workloads that should run once
  * per shard group, or durable message processing backed by cluster storage.
  * Registered entity handlers are started on demand for shards owned by the
- * current runner, while clients produced by {@link Sharding.makeClient} route
+ * current runner, while clients produced by the {@link Sharding} service route
  * requests through the sharding service instead of calling handlers directly.
  *
  * **Gotchas**

package/src/unstable/observability/index.ts

@@ -205,7 +205,7 @@ export * as OtlpTracer from "./OtlpTracer.ts"
  *
  * ```ts
  * import { Effect, Metric } from "effect"
- * import * as PrometheusMetrics from "effect/unstable/observability/PrometheusMetrics"
+ * import { PrometheusMetrics } from "effect/unstable/observability"
  *
  * const program = Effect.gen(function*() {
  *   // Create and update metrics

package/src/unstable/process/index.ts

@@ -13,8 +13,8 @@
  * **Example** (Spawning and piping commands)
  *
  * ```ts
- * import { NodeServices } from "@effect/platform-node"
  * import { Effect, Stream } from "effect"
+ * import { NodeServices } from "@effect/platform-node"
  * import { ChildProcess } from "effect/unstable/process"
  *
  * // Build a command

package/src/unstable/reactivity/index.ts

@@ -203,9 +203,8 @@ export * as Hydration from "./Hydration.ts"
  * store them. Registrations are tied to the surrounding scope, failures from a
  * query fail the queue or stream, and invalidations that arrive while a query is
  * already running schedule a single follow-up run. Use stable key values, be
- * aware that the default layer is process-local, and wrap related work in
- * {@link Reactivity.withBatch} when many invalidations should be coalesced until
- * the batch exits.
+ * aware that the default layer is process-local, and use the {@link Reactivity}
+ * service when many invalidations should be coalesced until the batch exits.
  *
  * @since 4.0.0
  */

package/src/unstable/rpc/RpcWorker.ts

@@ -62,7 +62,9 @@ export declare namespace InitialMessage {
   }
 }
 
-const ProtocolTag: typeof Protocol = Context.Service("@effect/rpc/RpcServer/Protocol") as any
+const ProtocolTag = Context.Service<Protocol, Protocol["Service"]>(
+  "effect/rpc/RpcServer/Protocol" satisfies Protocol["key"]
+)
 
 /**
  * Runs an effect, encodes its result with the schema's JSON codec, and returns

package/src/unstable/sql/Migrator.ts

@@ -341,8 +341,8 @@ const isConstraintConflict = (error: SqlError): boolean =>
 
 /**
  * Creates a migration loader from a glob record of dynamic import functions,
- * parsing files named `<id>_<name>.js` or `<id>_<name>.ts` and sorting
- * migrations by id.
+ * parsing files named `<id>_<name>.js`, `<id>_<name>.ts`,
+ * `<id>_<name>.mjs`, or `<id>_<name>.mts` and sorting migrations by id.
  *
  * @category loaders
  * @since 4.0.0
@@ -352,7 +352,7 @@ export const fromGlob = (
 ): Loader =>
   pipe(
     Object.keys(migrations),
-    Arr.flatMapNullishOr((_) => _.match(/^(?:.*\/)?(\d+)_([^.]+)\.(js|ts)$/)),
+    Arr.flatMapNullishOr((_) => _.match(/^(?:.*\/)?(\d+)_([^.]+)\.(js|ts|mjs|mts)$/)),
     Arr.map(
       ([key, id, name]): ResolvedMigration => [
         Number(id),
@@ -366,7 +366,8 @@ export const fromGlob = (
 
 /**
  * Creates a migration loader from a Babel-style glob record, parsing keys such
- * as `_<id>_<name>Js` or `_<id>_<name>Ts` and sorting migrations by id.
+ * as `_<id>_<name>Js`, `_<id>_<name>Ts`, `_<id>_<name>Mjs`, or
+ * `_<id>_<name>Mts` and sorting migrations by id.
  *
  * @category loaders
  * @since 4.0.0
@@ -374,7 +375,7 @@ export const fromGlob = (
 export const fromBabelGlob = (migrations: Record<string, any>): Loader =>
   pipe(
     Object.keys(migrations),
-    Arr.flatMapNullishOr((_) => _.match(/^_(\d+)_([^.]+?)(Js|Ts)?$/)),
+    Arr.flatMapNullishOr((_) => _.match(/^_(\d+)_([^.]+?)(Js|Ts|Mjs|Mts)?$/)),
     Arr.map(
       ([key, id, name]): ResolvedMigration => [
         Number(id),
@@ -410,7 +411,8 @@ export const fromRecord = (migrations: Record<string, Effect.Effect<void, unknow
 
 /**
  * Creates a migration loader that reads a directory with `FileSystem`, imports
- * files named `<id>_<name>.js` or `<id>_<name>.ts`, and sorts migrations by id.
+ * files named `<id>_<name>.js`, `<id>_<name>.ts`,
+ * `<id>_<name>.mjs`, or `<id>_<name>.mts`, and sorts migrations by id.
  *
  * @category loaders
  * @since 4.0.0
@@ -427,7 +429,7 @@ export const fromFileSystem: (directory: string) => Loader<FileSystem> = Effect.
       })
   )
   return files
-    .map((file) => Option.fromNullishOr(file.match(/^(?:.*\/)?(\d+)_([^.]+)\.(js|ts)$/)))
+    .map((file) => Option.fromNullishOr(file.match(/^(?:.*\/)?(\d+)_([^.]+)\.(js|ts|mjs|mts)$/)))
     .flatMap(
       Option.match({
         onNone: () => [],

package/src/unstable/sql/index.ts

@@ -122,7 +122,6 @@ export * as SqlError from "./SqlError.ts"
  * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
  * and trigger-updated values must be observable from that query.
  *
- * @category models
  * @since 4.0.0
  */
 export * as SqlModel from "./SqlModel.ts"

package/src/unstable/workflow/WorkflowEngine.ts

@@ -415,22 +415,18 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
           return options.interrupt(self, executionId)
         })
       }
+      const run = options.execute(self, {
+        executionId,
+        payload: payload as object,
+        discard: opts.discard ?? false,
+        parent: Option.getOrUndefined(parentInstance)
+      }) as Effect.Effect<Workflow.Result<Success["Type"], Error["Type"]>>
 
       if (opts.discard) {
-        yield* options.execute(self, {
-          executionId,
-          payload: payload as object,
-          discard: true
-        })
+        yield* run
         return executionId
       }
 
-      const run = options.execute(self, {
-        executionId,
-        payload: payload as object,
-        discard: false,
-        parent: Option.getOrUndefined(parentInstance)
-      })
       if (Option.isSome(parentInstance)) {
         const wrapped = yield* Workflow.wrapActivityResult(
           run,