effect 4.0.0-beta.103 → 4.0.0-beta.105

package/src/SchemaParser.ts

@@ -18,41 +18,11 @@ import { effectIsExit } from "./internal/effect.ts"
 import * as InternalSchemaCause from "./internal/schema/cause.ts"
 import * as InternalParser from "./internal/schema/parser.ts"
 import * as Option from "./Option.ts"
-import * as Predicate from "./Predicate.ts"
 import * as Result from "./Result.ts"
 import type * as Schema from "./Schema.ts"
 import * as SchemaAST from "./SchemaAST.ts"
 import * as SchemaIssue from "./SchemaIssue.ts"
 
-// Converts a type-side AST into its constructor form by recursively restoring
-// constructor encodings for nested classes and fields with constructor defaults.
-const toConstructorAST = memoize((ast: SchemaAST.AST): SchemaAST.AST => {
-  switch (ast._tag) {
-    case "Declaration": {
-      const getLink = ast.annotations?.[SchemaAST.ClassTypeId]
-      if (Predicate.isFunction(getLink)) {
-        const link = getLink(ast.typeParameters)
-        return SchemaAST.replaceEncoding(ast, [SchemaAST.mapLink(link, toConstructorAST)])
-      }
-      return ast
-    }
-    case "Objects":
-    case "Arrays":
-      return ast.recur((ast) => {
-        const defaultValue = ast.context?.defaultValue
-        if (defaultValue) {
-          const out = toConstructorAST(ast)
-          return SchemaAST.replaceEncoding(out, out.encoding ? [...out.encoding, ...defaultValue] : defaultValue)
-        }
-        return toConstructorAST(ast)
-      })
-    case "Suspend":
-      return ast.recur(toConstructorAST)
-    default:
-      return ast
-  }
-})
-
 /**
  * Creates an effectful maker for the schema's decoded type side.
  *
@@ -71,8 +41,7 @@ const toConstructorAST = memoize((ast: SchemaAST.AST): SchemaAST.AST => {
  * @since 4.0.0
  */
 export function makeEffect<S extends Schema.Constraint>(schema: S) {
-  const ast = toConstructorAST(SchemaAST.toType(schema.ast))
-  const parser = run<S["Type"], never>(ast)
+  const parser = runWithCompiler<S["Type"], never>(constructorCompiler, SchemaAST.toType(schema.ast))
   return (input: S["~type.make.in"], options?: Schema.MakeOptions): Effect.Effect<S["Type"], SchemaIssue.Issue> => {
     return parser(
       input,
@@ -125,6 +94,9 @@ export function makeOption<S extends Schema.Constraint>(schema: S) {
  *
  * The returned function constructs a value from constructor input and throws an
  * `Error` with the `SchemaIssue.Issue` in its `cause` when construction fails.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -146,7 +118,7 @@ export function make<S extends Schema.Constraint>(schema: S) {
       exit.cause,
       "Constructor adapter can only throw schema issues"
     )
-    throw new Error(issue.toString(), { cause: issue })
+    throw new Error("Schema validation failed", { cause: issue })
   }
 }
 
@@ -215,6 +187,9 @@ export function _issue<T>(ast: SchemaAST.AST) {
  * The assertion returns normally when validation succeeds. When the input does
  * not satisfy the schema with a schema-only failure, it throws an `Error` with
  * the `SchemaIssue.Issue` in its `cause`.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -233,7 +208,7 @@ export function asserts<S extends Schema.Constraint, I>(schema: S, input: I): as
       exit.cause,
       "Assertion adapter can only throw schema issues"
     )
-    throw new Error(issue.toString(), { cause: issue })
+    throw new Error("Schema validation failed", { cause: issue })
   }
 }
 
@@ -313,6 +288,9 @@ export const decodeEffect: <S extends Schema.Constraint>(
  *
  * The returned function resolves with the decoded `Type` on success and rejects
  * with an `Error` whose cause is a `SchemaIssue.Issue` on decoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -345,6 +323,9 @@ export function decodeUnknownPromise<S extends Schema.ConstraintDecoder<unknown>
  *
  * The returned function resolves with the decoded `Type` on success and rejects
  * with an `Error` whose cause is a `SchemaIssue.Issue` on decoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -523,6 +504,9 @@ export const decodeResult: <S extends Schema.ConstraintDecoder<unknown>>(
  *
  * The returned function returns the decoded `Type` on success and throws an
  * `Error` with the `SchemaIssue.Issue` in its `cause` on decoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -557,6 +541,9 @@ export function decodeUnknownSync<S extends Schema.ConstraintDecoder<unknown>>(
  *
  * The returned function returns the decoded `Type` on success and throws an
  * `Error` with the `SchemaIssue.Issue` in its `cause` on decoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -651,6 +638,9 @@ export const encodeEffect: <S extends Schema.Constraint>(
  *
  * The returned function resolves with the schema's `Encoded` value on success and
  * rejects with an `Error` whose cause is a `SchemaIssue.Issue` on encoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -682,6 +672,9 @@ export const encodeUnknownPromise = <S extends Schema.ConstraintEncoder<unknown>
  *
  * The returned function resolves with the schema's `Encoded` value on success and
  * rejects with an `Error` whose cause is a `SchemaIssue.Issue` on encoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -857,6 +850,9 @@ export const encodeResult: <S extends Schema.ConstraintEncoder<unknown>>(
  *
  * The returned function returns the schema's `Encoded` value on success and throws
  * an `Error` with the `SchemaIssue.Issue` in its `cause` on encoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -890,6 +886,9 @@ export function encodeUnknownSync<S extends Schema.ConstraintEncoder<unknown>>(
  *
  * The returned function returns the schema's `Encoded` value on success and throws
  * an `Error` with the `SchemaIssue.Issue` in its `cause` on encoding failure.
+ * Schema validation failures use the generic message `"Schema validation failed"`.
+ * Format the `cause` explicitly with `SchemaIssue.makeFormatterDefault()` when
+ * human-readable details are needed.
  *
  * **Gotchas**
  *
@@ -923,9 +922,13 @@ const getValue = (value: unknown): Effect.Effect<any, SchemaIssue.Issue> => {
 
 /** @internal */
 export function run<T, R>(ast: SchemaAST.AST) {
+  return runWithCompiler<T, R>(normalCompiler, ast)
+}
+
+function runWithCompiler<T, R>(compiler: Compiler, ast: SchemaAST.AST) {
   let parser: Parser
   return (input: unknown, options?: SchemaAST.ParseOptions): Effect.Effect<T, SchemaIssue.Issue, R> => {
-    const result = (parser ??= compile(ast))(
+    const result = (parser ??= compiler(ast))(
       input,
       options ?? SchemaAST.defaultParseOptions
     )
@@ -954,7 +957,7 @@ function asPromise<T, E>(
         exit.cause,
         "Promise adapter can only reject schema issues"
       )
-      throw new Error(issue.toString(), { cause: issue })
+      throw new Error("Schema validation failed", { cause: issue })
     })
 }
 
@@ -1004,7 +1007,7 @@ function asSync<T, E>(
       return exit.value
     }
     const issue = InternalSchemaCause.getSchemaIssueOrThrow(exit.cause, "Sync adapter can only throw schema issues")
-    throw new Error(issue.toString(), { cause: issue })
+    throw new Error("Schema validation failed", { cause: issue })
   }
 }
 
@@ -1016,20 +1019,79 @@ export interface Parser {
   ): Effect.Effect<unknown, SchemaIssue.Issue, any>
 }
 
-const parserCache = new WeakMap<SchemaAST.AST, Parser>()
+/** @internal */
+export interface Compiler {
+  (ast: SchemaAST.AST): Parser
+}
+
+const normalCompiler: Compiler = memoize((ast) => makeParser(ast, normalCompiler))
+const constructorCompiler: Compiler = memoize((ast) => makeParser(ast, constructorCompiler, compileConstructorDefault))
+const compileDefaulted = memoize((ast: SchemaAST.AST) =>
+  makeParser(ast, constructorCompiler, compileConstructorDefault, ast.context?.constructorDefault)
+)
+
+function compileConstructorDefault(ast: SchemaAST.AST): Parser {
+  return ast.context?.constructorDefault ? compileDefaulted(ast) : constructorCompiler(ast)
+}
+
+function applyTransformation(
+  result: Effect.Effect<unknown, SchemaIssue.Issue, unknown>,
+  current: unknown,
+  transformation: SchemaAST.Link["transformation"],
+  options: SchemaAST.ParseOptions
+): Effect.Effect<unknown, SchemaIssue.Issue, unknown> {
+  let transformed: Effect.Effect<Option.Option<unknown>, SchemaIssue.Issue, unknown>
+  if (effectIsExit(result) && result._tag === "Success") {
+    const optional = InternalParser.toOption(
+      result === InternalParser.sameExit
+        ? current
+        : (result as InternalParser.Success<unknown, SchemaIssue.Issue>)[InternalParser.args]
+    )
+    transformed = transformation._tag === "Transformation"
+      ? transformation.decode.run(optional, options)
+      : transformation.decode(InternalParser.succeed(optional), options)
+  } else if (transformation._tag === "Transformation") {
+    transformed = Effect.flatMapEager(
+      result,
+      (value) => transformation.decode.run(InternalParser.toOption(value), options)
+    )
+  } else {
+    transformed = transformation.decode(
+      Effect.mapEager(result, InternalParser.toOption),
+      options
+    )
+  }
+  return effectIsExit(transformed) && transformed._tag === "Success"
+    ? InternalParser.fromOptionExit(
+      (transformed as InternalParser.Success<Option.Option<unknown>, SchemaIssue.Issue>)[InternalParser.args]
+    )
+    : Effect.flatMapEager(transformed, InternalParser.fromOptionExit)
+}
 
-function compile(ast: SchemaAST.AST): Parser {
-  let parser = parserCache.get(ast)
-  if (!parser) {
-    parserCache.set(ast, parser = makeParser(ast))
+function makeConstructorParser(descriptor: SchemaAST.ConstructorDescriptor, compile: Compiler): Parser {
+  let sourceParser: Parser
+  return (input, options) => {
+    if (input === InternalParser.missing) return InternalParser.missingExit
+    if (descriptor.isConstructed(input)) return InternalParser.sameExit
+    const result = (sourceParser ??= compile(descriptor.link.to))(input, options)
+    return applyTransformation(result, input, descriptor.link.transformation, options)
   }
-  return parser
 }
 
-function makeParser(ast: SchemaAST.AST): Parser {
-  const parser = ast.getParser(compile)
+function makeParser(
+  ast: SchemaAST.AST,
+  compile: Compiler,
+  compileConstructorDefault?: Compiler,
+  constructorDefault?: SchemaAST.Link
+): Parser {
+  const descriptor = compileConstructorDefault ? SchemaAST.getConstructorDescriptor(ast) : undefined
+  const parser = descriptor
+    ? makeConstructorParser(descriptor, compile)
+    : ast.getParser(compile, compileConstructorDefault)
   const checks = ast.checks
-  const links = ast.encoding
+  const links = constructorDefault
+    ? ast.encoding ? [...ast.encoding, constructorDefault] : [constructorDefault]
+    : ast.encoding
   const encodingChecks = (ast as any).encodingChecks
   const astOptions = (checks ? checks[checks.length - 1].annotations : ast.annotations)
     ?.["parseOptions"]
@@ -1054,9 +1116,7 @@ function makeParser(ast: SchemaAST.AST): Parser {
           if (input !== InternalParser.missing && output !== InternalParser.missing) {
             const issues = SchemaAST.collectIssues(encodingChecks, input, undefined, ast, options)
             if (issues) {
-              result = Effect.fail(
-                new SchemaIssue.Composite(ast, issues)
-              )
+              result = Effect.fail(new SchemaIssue.Composite(ast, issues, input, options))
             }
           }
         }
@@ -1065,9 +1125,7 @@ function makeParser(ast: SchemaAST.AST): Parser {
           if (input !== InternalParser.missing && value !== InternalParser.missing) {
             const issues = SchemaAST.collectIssues(encodingChecks, input, undefined, ast, options)
             if (issues) {
-              return Effect.fail(
-                new SchemaIssue.Composite(ast, issues)
-              )
+              return Effect.fail(new SchemaIssue.Composite(ast, issues, input, options))
             }
           }
           return Effect.succeed(value)
@@ -1084,9 +1142,7 @@ function makeParser(ast: SchemaAST.AST): Parser {
           if (value === InternalParser.missing) return result
           const issues = SchemaAST.collectIssues(checks, value, undefined, ast, options)
           if (issues) {
-            result = Effect.fail(
-              new SchemaIssue.Composite(ast, issues)
-            )
+            result = Effect.fail(new SchemaIssue.Composite(ast, issues, value, options))
           }
         }
       } else {
@@ -1094,9 +1150,7 @@ function makeParser(ast: SchemaAST.AST): Parser {
           if (value !== InternalParser.missing) {
             const issues = SchemaAST.collectIssues(checks, value, undefined, ast, options)
             if (issues) {
-              return Effect.fail(
-                new SchemaIssue.Composite(ast, issues)
-              )
+              return Effect.fail(new SchemaIssue.Composite(ast, issues, value, options))
             }
           }
           return Effect.succeed(value)
@@ -1122,33 +1176,7 @@ function makeParser(ast: SchemaAST.AST): Parser {
     let current = input
     let result = parsers[parsers.length - 1](input, options)
     for (let i = links.length - 1; i >= 0; i--) {
-      const transformation = links[i].transformation
-      let transformed: Effect.Effect<Option.Option<unknown>, SchemaIssue.Issue, unknown>
-      if (effectIsExit(result) && result._tag === "Success") {
-        const optional = InternalParser.toOption(
-          result === InternalParser.sameExit
-            ? current
-            : (result as InternalParser.Success<unknown, SchemaIssue.Issue>)[InternalParser.args]
-        )
-        transformed = transformation._tag === "Transformation"
-          ? transformation.decode.run(optional, options)
-          : transformation.decode(InternalParser.succeed(optional), options)
-      } else if (transformation._tag === "Transformation") {
-        transformed = Effect.flatMapEager(
-          result,
-          (value) => transformation.decode.run(InternalParser.toOption(value), options)
-        )
-      } else {
-        transformed = transformation.decode(
-          Effect.mapEager(result, InternalParser.toOption),
-          options
-        )
-      }
-      result = effectIsExit(transformed) && transformed._tag === "Success"
-        ? InternalParser.fromOptionExit(
-          (transformed as InternalParser.Success<Option.Option<unknown>, SchemaIssue.Issue>)[InternalParser.args]
-        )
-        : Effect.flatMapEager(transformed, InternalParser.fromOptionExit)
+      result = applyTransformation(result, current, links[i].transformation, options)
       if (i !== 0) {
         const next = parsers[i - 1]
         if ((result as Exit.Exit<unknown, unknown>)._tag === "Success") {
@@ -1169,7 +1197,19 @@ function makeParser(ast: SchemaAST.AST): Parser {
     }
     result = Effect.catchCause(
       result,
-      (cause) => Effect.failCauseSync(() => Cause.map(cause, (issue) => new SchemaIssue.Encoding(ast, issue)))
+      (cause) =>
+        Effect.failCauseSync(() =>
+          Cause.map(
+            cause,
+            (issue) =>
+              new SchemaIssue.Encoding(
+                ast,
+                issue,
+                input,
+                options
+              )
+          )
+        )
     )
     return Effect.flatMapEager(result, (value) => {
       const local = parseLocal(value, options)

package/src/SchemaTransformation.ts

@@ -263,10 +263,10 @@ export const make = <T, E, RD = never, RE = never>(options: {
  *   Schema.decodeTo(
  *     Schema.Date,
  *     SchemaTransformation.transformOrFail({
- *       decode: (s) => {
+ *       decode: (s, options) => {
  *         const d = new Date(s)
  *         return isNaN(d.getTime())
- *           ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid date" }))
+ *           ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid date" }, s, options))
  *           : Effect.succeed(d)
  *       },
  *       encode: (d) => Effect.succeed(d.toISOString())
@@ -974,9 +974,16 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
   Duration.Duration,
   string
 >({
-  decode: (s) =>
+  decode: (s, options) =>
     Option.match(Duration.fromInput(s as Duration.Input), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid Duration string" })),
+      onNone: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Duration string" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     }),
   encode: (duration) => Effect.succeed(globalThis.String(duration))
@@ -1015,11 +1022,15 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
  */
 export const durationFromNanos: Transformation<Duration.Duration, bigint> = transformOrFail({
   decode: (i) => Effect.succeed(Duration.nanos(i)),
-  encode: (a) =>
+  encode: (a, options) =>
     Option.match(Duration.toNanos(a), {
       onNone: () =>
         Effect.fail(
-          new SchemaIssue.InvalidValue({ message: "Expected a Duration representable as a bigint" })
+          new SchemaIssue.InvalidValue(
+            { expected: "a Duration representable as a bigint" },
+            a,
+            options
+          )
         ),
       onSome: (nanos) => Effect.succeed(nanos)
     })
@@ -1395,10 +1406,16 @@ export function optionFromOptional<T>(): Transformation<Option.Option<T>, T | un
  * @since 4.0.0
  */
 export const urlFromString: Transformation<URL, string> = transformOrFail<URL, string>({
-  decode: (s) =>
+  decode: (s, options) =>
     URL.canParse(s)
       ? Effect.succeed(new URL(s))
-      : Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid URL string" })),
+      : Effect.fail(
+        new SchemaIssue.InvalidValue(
+          { expected: "a valid URL string" },
+          s,
+          options
+        )
+      ),
   encode: (url) => Effect.succeed(url.href)
 })
 
@@ -1424,10 +1441,16 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
   BigDecimal.BigDecimal,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     const result = BigDecimal.fromString(s)
     return Option.isNone(result)
-      ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid BigDecimal string" }))
+      ? Effect.fail(
+        new SchemaIssue.InvalidValue(
+          { expected: "a valid BigDecimal string" },
+          s,
+          options
+        )
+      )
       : Effect.succeed(result.value)
   },
   encode: (bd) => Effect.succeed(BigDecimal.format(bd))
@@ -1784,9 +1807,16 @@ export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, st
   DateTime.TimeZone.Named,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.zoneMakeNamed(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid IANA time zone" })),
+      onNone: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid IANA time zone" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     })
   },
@@ -1818,9 +1848,16 @@ export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = tra
   DateTime.TimeZone,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.zoneFromString(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid time zone" })),
+      onNone: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid time zone" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     })
   },
@@ -1852,9 +1889,16 @@ export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = trans
   DateTime.Utc,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.make(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "Expected a valid UTC DateTime string" })),
+      onNone: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid UTC DateTime string" },
+            s,
+            options
+          )
+        ),
       onSome: (result) => Effect.succeed(DateTime.toUtc(result))
     })
   },
@@ -1885,11 +1929,15 @@ export const dateTimeZonedFromString: Transformation<DateTime.Zoned, string> = t
   DateTime.Zoned,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.makeZonedFromString(s), {
       onNone: () =>
         Effect.fail(
-          new SchemaIssue.InvalidValue({ message: "Expected a valid Zoned DateTime string" })
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Zoned DateTime string" },
+            s,
+            options
+          )
         ),
       onSome: Effect.succeed
     })

package/src/ScopedCache.ts

@@ -211,7 +211,7 @@ export const make = <
 > =>
   makeWith<Key, A, E, R, ServiceMode>({
     ...options,
-    timeToLive: options.timeToLive ? () => options.timeToLive! : defaultTimeToLive
+    timeToLive: options.timeToLive !== undefined ? () => options.timeToLive! : defaultTimeToLive
   })
 
 const Proto = {

package/src/Sink.ts

@@ -2529,7 +2529,7 @@ export const catchCause: {
 const catch_: {
   <E, A2, E2, R2>(
     f: (error: Types.NoInfer<E>) => Effect.Effect<A2, E2, R2>
-  ): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In, L, E, R2 | R>
+  ): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In, L, E2, R2 | R>
   <A, In, L, E, R, A2, E2, R2>(
     self: Sink<A, In, L, E, R>,
     f: (error: E) => Effect.Effect<A2, E2, R2>

package/src/Stdio.ts

@@ -63,6 +63,18 @@ export const TypeId: TypeId = "~effect/Stdio"
 export interface Stdio {
   readonly [TypeId]: TypeId
   readonly args: Effect.Effect<ReadonlyArray<string>>
+  /**
+   * Whether standard input is attached to a terminal.
+   *
+   * @since 4.0.0
+   */
+  readonly stdinIsTerminal: Effect.Effect<boolean>
+  /**
+   * Whether standard output is attached to a terminal.
+   *
+   * @since 4.0.0
+   */
+  readonly stdoutIsTerminal: Effect.Effect<boolean>
   stdout(options?: {
     readonly endOnDone?: boolean | undefined
   }): Sink.Sink<void, string | Uint8Array, never, PlatformError>
@@ -98,16 +110,23 @@ export const Stdio: Context.Service<Stdio, Stdio> = Context.Service<Stdio>(TypeI
  *
  * **Details**
  *
- * The returned service reuses the supplied fields unchanged and only adds the
- * `Stdio` type identifier; it does not create a `Layer` or provide defaults.
+ * The returned service reuses the supplied fields unchanged and adds the
+ * `Stdio` type identifier. Omitted terminal-detection fields default to
+ * effects that succeed with `false`.
  *
  * @see {@link layerTest} for a test layer with default fields that can be overridden
  *
  * @category constructors
  * @since 4.0.0
  */
-export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
+export const make = (
+  options:
+    & Omit<Stdio, TypeId | "stdinIsTerminal" | "stdoutIsTerminal">
+    & Partial<Pick<Stdio, "stdinIsTerminal" | "stdoutIsTerminal">>
+): Stdio => ({
   [TypeId]: TypeId,
+  stdinIsTerminal: Effect.succeed(false),
+  stdoutIsTerminal: Effect.succeed(false),
   ...options
 })
 
@@ -123,7 +142,7 @@ export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
  *
  * Any provided fields override defaults. By default, arguments are empty,
  * standard output and error are draining sinks, and standard input is an empty
- * stream.
+ * stream, and terminal-detection effects succeed with `false`.
  *
  * @see {@link make} for constructing a `Stdio` service directly without a `Layer` or defaults
  *