effect 4.0.0 → 4.0.2

package/src/Types.ts

@@ -6,6 +6,7 @@
  * object shapes, tagged unions, reason-tagged errors, mutability, exactness,
  * required keys, concurrency settings, and variance markers.
  *
+ * @stability stable
  * @since 4.0.0
  */
 
@@ -50,6 +51,7 @@ type TupleOf_<T, N extends number, R extends Array<unknown>> = `${N}` extends `-
  *
  * @see {@link TupleOfAtLeast}
  *
+ * @stability stable
  * @category utility types
  * @since 3.3.0
  */
@@ -83,6 +85,7 @@ export type TupleOf<N extends number, T> = N extends N ? number extends N ? Arra
  *
  * @see {@link TupleOf}
  *
+ * @stability stable
  * @category utility types
  * @since 3.3.0
  */
@@ -118,6 +121,7 @@ export type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>
  * @see {@link ExtractTag}
  * @see {@link ExcludeTag}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -154,6 +158,7 @@ export type Tags<E> = E extends { readonly _tag: string } ? E["_tag"] : never
  * @see {@link ExtractTag}
  * @see {@link Tags}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -189,6 +194,7 @@ export type ExcludeTag<E, K extends string> = Exclude<E, { readonly _tag: K }>
  * @see {@link ExcludeTag}
  * @see {@link Tags}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -223,6 +229,7 @@ export type ExtractTag<E, K extends string> = E extends { readonly _tag: infer T
  *
  * @see {@link IsUnion}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -256,6 +263,7 @@ export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) ext
  * @see {@link MergeLeft}
  * @see {@link MergeRight}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -288,6 +296,7 @@ export type Simplify<A> = {
  *
  * @see {@link EqualsWith}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -318,6 +327,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
  *
  * @see {@link Equals}
  *
+ * @stability stable
  * @category utility types
  * @since 3.15.0
  */
@@ -345,6 +355,7 @@ export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>
  * type No = Types.Has<{ a: number }, "b" | "c"> // false
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -381,6 +392,7 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
  * @see {@link MergeRight}
  * @see {@link Simplify}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -415,6 +427,7 @@ export type MergeLeft<Source, Target> = MergeRight<Target, Source>
  * @see {@link MergeLeft}
  * @see {@link Simplify}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -448,6 +461,7 @@ export type MergeRight<Target, Source> = Simplify<
  * const unbounded: Types.Concurrency = "unbounded"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -489,6 +503,7 @@ export type Concurrency = number | "unbounded"
  *
  * @see {@link DeepMutable}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -537,6 +552,7 @@ type DeepMutableIsOpaque<T> = Extract<keyof T, symbol> extends never
  *
  * @see {@link Mutable}
  *
+ * @stability stable
  * @category utility types
  * @since 3.1.0
  */
@@ -573,6 +589,7 @@ export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepM
  * const result = withDefault<"a" | "b">("a", "b")
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -609,6 +626,7 @@ export type NoInfer<A> = [A][A extends any ? 0 : never]
  * @see {@link Covariant}
  * @see {@link Contravariant}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -621,6 +639,7 @@ export type Invariant<A> = (_: A) => A
  *
  * Use when referring to type-level helpers nested under `Invariant`.
  *
+ * @stability stable
  * @since 3.9.0
  */
 export declare namespace Invariant {
@@ -681,6 +700,7 @@ export declare namespace Invariant {
  * @see {@link Contravariant}
  * @see {@link Invariant}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -693,6 +713,7 @@ export type Covariant<A> = (_: never) => A
  *
  * Use when referring to type-level helpers nested under `Covariant`.
  *
+ * @stability stable
  * @since 3.9.0
  */
 export declare namespace Covariant {
@@ -756,6 +777,7 @@ export declare namespace Covariant {
  * @see {@link Covariant}
  * @see {@link Invariant}
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -768,6 +790,7 @@ export type Contravariant<A> = (_: A) => void
  *
  * Use when referring to type-level helpers nested under `Contravariant`.
  *
+ * @stability stable
  * @since 3.9.0
  */
 export declare namespace Contravariant {
@@ -805,6 +828,7 @@ export declare namespace Contravariant {
  *
  * Use to erase an empty object type from an API result or parameter position.
  *
+ * @stability stable
  * @category utility types
  * @since 3.19.20
  */
@@ -832,6 +856,7 @@ export type VoidIfEmpty<S> = keyof S extends never ? void : S
  * const witness: Result = "value"
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -862,6 +887,7 @@ export type NotFunction<T> = T extends Function ? never : T
  * const accepted: Types.NoExcessProperties<Expected, Expected> = { a: 1, b: "value" }
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 3.9.0
  */
@@ -882,6 +908,7 @@ export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyo
  *
  * @see {@link unhandled}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -904,6 +931,7 @@ export interface unassigned {
  *
  * @see {@link unassigned}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -936,6 +964,7 @@ export interface unhandled {
  *
  * @see {@link UnionToIntersection}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -972,6 +1001,7 @@ export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true
  * @see {@link ExtractReason}
  * @see {@link ExcludeReason}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1008,6 +1038,7 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
  * @see {@link ReasonOf}
  * @see {@link ExtractReason}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1046,6 +1077,7 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1089,6 +1121,7 @@ export type ExtractReason<E, K extends string> = E extends { readonly reason: in
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1133,6 +1166,7 @@ export type NarrowReason<E, K extends string> = E extends { readonly reason: inf
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1173,6 +1207,7 @@ export type OmitReason<E, K extends string> = E extends { readonly reason: infer
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -1191,6 +1226,7 @@ type WithoutIndexSignature_<T> = {
 /**
  * Extracts the keys of required properties from a type.
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */

package/src/UndefinedOr.ts

@@ -8,6 +8,7 @@
  * cases, throwing when a value is missing, adapting throwing functions, and
  * building reducers or combiners.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Combiner from "./Combiner.ts"
@@ -25,6 +26,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * @see {@link match} when you need to handle the `undefined` case explicitly
  *
+ * @stability stable
  * @category mapping
  * @since 4.0.0
  */
@@ -39,6 +41,7 @@ export const map: {
    *
    * @see {@link match} when you need to handle the `undefined` case explicitly
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -53,6 +56,7 @@ export const map: {
    *
    * @see {@link match} when you need to handle the `undefined` case explicitly
    *
+   * @stability stable
    * @category mapping
    * @since 4.0.0
    */
@@ -71,6 +75,7 @@ export const map: {
  * @see {@link map} for transforming defined values while preserving `undefined`
  * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
  *
+ * @stability stable
  * @category pattern matching
  * @since 4.0.0
  */
@@ -87,6 +92,7 @@ export const match: {
    * @see {@link map} for transforming defined values while preserving `undefined`
    * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */
@@ -108,6 +114,7 @@ export const match: {
    * @see {@link map} for transforming defined values while preserving `undefined`
    * @see {@link getOrThrowWith} for throwing when the value is `undefined` instead of returning a fallback branch
    *
+   * @stability stable
    * @category pattern matching
    * @since 4.0.0
    */
@@ -143,6 +150,7 @@ export const match: {
  * @see {@link getOrThrow} for the default-error sibling
  * @see {@link match} for handling defined and undefined cases without throwing
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -164,6 +172,7 @@ export const getOrThrowWith: {
    * @see {@link getOrThrow} for the default-error sibling
    * @see {@link match} for handling defined and undefined cases without throwing
    *
+   * @stability stable
    * @category getters
    * @since 4.0.0
    */
@@ -185,6 +194,7 @@ export const getOrThrowWith: {
    * @see {@link getOrThrow} for the default-error sibling
    * @see {@link match} for handling defined and undefined cases without throwing
    *
+   * @stability stable
    * @category getters
    * @since 4.0.0
    */
@@ -213,6 +223,7 @@ export const getOrThrowWith: {
  * @see {@link getOrThrowWith} for the sibling that lets callers choose the thrown value
  * @see {@link match} for handling defined and undefined cases without throwing
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -234,6 +245,7 @@ export const getOrThrow: <A>(self: A | undefined) => A = getOrThrowWith(() =>
  * Thrown values are discarded. If the wrapped function can successfully return
  * `undefined`, that success is indistinguishable from a thrown failure.
  *
+ * @stability stable
  * @category converting
  * @since 4.0.0
  */
@@ -266,6 +278,7 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  * are combined with `combiner.combine`. The reducer's initial value is
  * `undefined`.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -295,6 +308,7 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
  * @see {@link makeReducerFailFast} if you have a `Reducer` and want to lift it
  * to `UndefinedOr` values.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -323,6 +337,7 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
  * @see {@link makeCombinerFailFast} if you only have a `Combiner` and want to
  * lift it to `UndefinedOr` values.
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */

package/src/Unify.ts

@@ -8,6 +8,7 @@
  * exports the protocol symbols, the `Unify` type that performs normalization,
  * and `unify`, an identity function that changes only the inferred type.
  *
+ * @stability stable
  * @since 2.0.0
  */
 
@@ -29,6 +30,7 @@ import { identity } from "./Function.ts"
  * @see {@link typeSymbol} for storing the source type information used during unification
  * @see {@link ignoreSymbol} for excluding protocol entries from unification
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -48,6 +50,7 @@ export declare const unifySymbol: unique symbol
  * behavior in Effect types. It's typically used in type-level operations
  * to enable automatic type unification.
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -68,6 +71,7 @@ export type unifySymbol = typeof unifySymbol
  *
  * @see {@link unifySymbol} for defining how protocol entries widen
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -87,6 +91,7 @@ export declare const typeSymbol: unique symbol
  * in types that support unification. It's used in type-level operations
  * to access and manipulate type information.
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -107,6 +112,7 @@ export type typeSymbol = typeof typeSymbol
  *
  * @see {@link unifySymbol} for defining the protocol entries being filtered
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -126,6 +132,7 @@ export declare const ignoreSymbol: unique symbol
  * be ignored during unification operations. It's used in type-level operations
  * to exclude specific types from the unification process.
  *
+ * @stability stable
  * @category symbols
  * @since 2.0.0
  */
@@ -202,6 +209,7 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
  *
  * @see {@link unify} for applying this normalization to a value or function
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -266,6 +274,7 @@ export type Unify<A> = Values<
  *
  * @see {@link Unify} for the type-level normalization applied by this helper
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -308,6 +317,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */
@@ -359,6 +369,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */
@@ -409,6 +420,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */
@@ -456,6 +468,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */
@@ -502,6 +515,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */
@@ -547,6 +561,7 @@ export const unify: {
    *
    * @see {@link Unify} for the type-level normalization applied by this helper
    *
+   * @stability stable
    * @category utility types
    * @since 2.0.0
    */

package/src/Utils.ts

@@ -8,6 +8,7 @@
  * used by modules such as `Effect`, `Option`, and `Result` to type their
  * `gen` APIs.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type { Kind, TypeLambda } from "./HKT.ts"
@@ -45,6 +46,7 @@ import type * as Types from "./Types.ts"
  * ```
  *
  * @see {@link Gen} for the type-level signature that relies on `SingleShotGen`
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -113,6 +115,7 @@ export class SingleShotGen<T, A> implements Iterator<T, A> {
  * ```
  *
  * @see {@link Gen} for the type-level signature that uses `Variance`
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -153,6 +156,7 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  *
  * @see {@link Variance} for encoding the variance used for inference
  * @see {@link SingleShotGen} for the iterator protocol that makes yielding work
+ * @stability stable
  * @category models
  * @since 2.0.0
  */

package/src/Version.ts

@@ -0,0 +1,38 @@
+/**
+ * The `effect` package version used in telemetry headers, resources, and scopes.
+ *
+ * @stability unstable
+ * @since 4.0.2
+ */
+import { version } from "./internal/version.ts"
+
+let currentVersion: string = version
+
+/**
+ * Returns the current version of the `effect` package.
+ *
+ * **Details**
+ *
+ * Defaults to the release version unless overridden by `setCurrentVersion`.
+ *
+ * @stability unstable
+ * @category getters
+ * @since 4.0.2
+ */
+export const getCurrentVersion = (): string => currentVersion
+
+/**
+ * Overrides the version returned by `getCurrentVersion`.
+ *
+ * **Gotchas**
+ *
+ * Applies to this copy of the module. Existing telemetry layers retain the
+ * version they read when built.
+ *
+ * @stability unstable
+ * @category setters
+ * @since 4.0.2
+ */
+export const setCurrentVersion = (version: string): void => {
+  currentVersion = version
+}

package/src/ai/Chat.ts

@@ -509,7 +509,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
       (effect, options) =>
         Effect.withSpan(effect, "Chat.generateObject", {
           attributes: {
-            objectName: LanguageModel.getObjectName(options.objectName, options.schema)
+            "effect.ai.object_name": LanguageModel.getObjectName(options.objectName, options.schema)
           },
           captureStackTrace: false
         })

package/src/ai/DecisionModel.ts

@@ -67,6 +67,23 @@ export class DecisionUsage extends Schema.Class<DecisionUsage>(
  */
 export interface DecideOptions<Input extends Schema.Constraint> {
   readonly input: Input["Type"]
+  /**
+   * Images to include with the input.
+   */
+  readonly images?: ReadonlyArray<Image> | undefined
+}
+
+/**
+ * An image sent to the provider with the encoded input.
+ * `data` is a base64 string, a byte array, or a URL.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.1
+ */
+export interface Image {
+  readonly mediaType: string
+  readonly data: string | Uint8Array | URL
 }
 
 /**
@@ -87,6 +104,7 @@ export interface DecideResponse<Decisions extends Record<string, Decision.Any>>
  * Provider input options for a decision request.
  * `state` is encoded with `Schema.toCodecJson`, not stringified.
  * All `decisions` must be answered in one call.
+ * `images` is omitted when no images are supplied.
  *
  * @stability unstable
  * @category options
@@ -95,6 +113,7 @@ export interface DecideResponse<Decisions extends Record<string, Decision.Any>>
 export interface ProviderOptions {
   readonly state: Schema.Json
   readonly decisions: Record<string, Decision.Any>
+  readonly images?: ReadonlyArray<Image> | undefined
 }
 
 /**
@@ -325,6 +344,9 @@ const validateAnswers = <Decisions extends Record<string, Decision.Any>>(
  *
  * **Details**
  *
+ * Set `supportsImages: true` to accept images. Otherwise, nonempty image input
+ * fails with `AiError.InvalidUserInputError`.
+ *
  * Providers that round each probability to `probabilityPrecision` decimal
  * places may return distributions whose sum drifts from 1 by up to half a unit
  * of the last place per label. Setting `probabilityPrecision` accepts that
@@ -341,6 +363,7 @@ const validateAnswers = <Decisions extends Record<string, Decision.Any>>(
 export const make = (params: {
   readonly decide: (options: ProviderOptions) => Effect.Effect<ProviderResponse, AiError.AiError>
   readonly probabilityPrecision?: number | undefined
+  readonly supportsImages?: boolean | undefined
 }): Effect.Effect<DecisionModel> =>
   Effect.sync(() => {
     const roundingError = params.probabilityPrecision === undefined ? 0 : 0.5 * 10 ** -params.probabilityPrecision
@@ -358,7 +381,25 @@ export const make = (params: {
               reason: new AiError.InvalidUserInputError({ description: error.message })
             })
           ),
-          Effect.flatMap((state) => params.decide({ state, decisions: definition.decisions })),
+          Effect.flatMap((state) => {
+            const images = options.images?.length ? options.images : undefined
+            if (images !== undefined && params.supportsImages !== true) {
+              return Effect.fail(
+                AiError.make({
+                  module: "DecisionModel",
+                  method: "decide",
+                  reason: new AiError.InvalidUserInputError({
+                    description: "This decision model does not accept images"
+                  })
+                })
+              )
+            }
+            return params.decide({
+              state,
+              decisions: definition.decisions,
+              ...(images === undefined ? undefined : { images })
+            })
+          }),
           Effect.flatMap((response) =>
             Effect.map(
               validateAnswers(definition.decisions, response.answers, roundingError),