effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/unstable/ai/Chat.ts

@@ -1,48 +1,58 @@
 /**
- * The `Chat` module provides a stateful conversation interface for AI language
- * models.
+ * Stateful conversation sessions on top of a language model.
  *
- * This module enables persistent chat sessions that maintain conversation
- * history, support tool calling, and offer both streaming and non-streaming
- * text generation. It integrates seamlessly with the Effect AI ecosystem,
- * providing type-safe conversational AI capabilities.
+ * A `Chat` keeps `Prompt` history in a `Ref` and reuses it for text generation,
+ * streaming, and structured output. Each generation call combines the current
+ * history with the caller's new prompt, invokes the active language model, and
+ * appends the response parts back into history. Constructors create fresh
+ * sessions, seed sessions from prompts, restore exported history, or connect a
+ * chat to persistence.
  *
- * **Example** (Creating a chat session)
+ * **Mental model**
+ *
+ * A {@link Service} is a mutable conversation handle. It stores history, while
+ * the language model implementation is still supplied through the Effect
+ * environment when `generateText`, `streamText`, or `generateObject` runs.
+ * Local sessions created with {@link empty} and {@link fromPrompt} live only in
+ * memory; persisted sessions add a backing store and save after generation.
+ *
+ * **Common tasks**
+ *
+ * - Start an empty session with {@link empty}.
+ * - Seed system prompts or prior messages with {@link fromPrompt}.
+ * - Restore saved history with {@link fromExport} or {@link fromJson}.
+ * - Persist sessions by providing {@link Persistence} with {@link makePersisted}
+ *   or {@link layerPersisted}.
+ *
+ * **Example** (Starting a chat session)
  *
  * ```ts
  * import { Effect } from "effect"
  * import { Chat } from "effect/unstable/ai"
  *
- * // Create a new chat session
  * const program = Effect.gen(function*() {
- *   const chat = yield* Chat.empty
+ *   const chat = yield* Chat.fromPrompt([{
+ *     role: "system",
+ *     content: "Answer in one sentence."
+ *   }])
  *
- *   // Send a message and get response
  *   const response = yield* chat.generateText({
- *     prompt: "Hello! What can you help me with?"
+ *     prompt: "What does Effect provide for TypeScript applications?"
  *   })
  *
- *   console.log(response.content)
+ *   const saved = yield* chat.exportJson
  *
- *   return response
+ *   return { text: response.text, saved }
  * })
  * ```
  *
- * **Example** (Streaming chat responses)
+ * **Gotchas**
  *
- * ```ts
- * import { Effect, Stream } from "effect"
- * import { Chat } from "effect/unstable/ai"
- *
- * // Streaming chat with tool support
- * const streamingChat = Effect.gen(function*() {
- *   const chat = yield* Chat.empty
- *
- *   yield* chat.streamText({
- *     prompt: "Generate a creative story"
- *   }).pipe(Stream.runForEach((part) => Effect.sync(() => console.log(part))))
- * })
- * ```
+ * Generation requires a language model service in the environment. `streamText`
+ * records the parts emitted by the stream when the stream finalizes, so consume
+ * the stream to completion when the full assistant response should become part
+ * of history. Direct writes to `history` are possible, but bypass the helpers
+ * that encode, decode, export, and persist the conversation.
  *
  * @since 4.0.0
  */
@@ -102,6 +112,15 @@ export class Chat extends Context.Service<Chat, Service>()(
 /**
  * Represents the interface that the `Chat` service provides.
  *
+ * **When to use**
+ *
+ * Use as the service contract for code that receives or constructs a stateful
+ * chat session and needs history, export, text generation, streaming, and
+ * structured-output operations.
+ *
+ * @see {@link Chat} for the context tag that provides this service
+ * @see {@link Persisted} for the persistence-backed extension
+ *
  * @category models
  * @since 4.0.0
  */
@@ -481,7 +500,7 @@ const makeUnsafe = (history: Ref.Ref<Prompt.Prompt>) => {
  *
  * **When to use**
  *
- * This is the most common way to start a fresh chat session without
+ * Use when this is the most common way to start a fresh chat session without
  * any initial context or system prompts.
  *
  * **Example** (Creating an empty chat)
@@ -761,11 +780,19 @@ export interface Persisted extends Service {
 /**
  * Creates a new chat persistence service.
  *
+ * **When to use**
+ *
+ * Use to construct the `Chat.Persistence` service from the current
+ * `BackingPersistence` when you want to create and retrieve persisted chats
+ * programmatically by chat id.
+ *
  * **Details**
  *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
+ * @see {@link layerPersisted} for the `Layer`-based constructor
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -916,11 +943,18 @@ export const makePersisted = Effect.fnUntraced(function*(options: {
 /**
  * Creates a `Layer` for a new chat persistence service.
  *
+ * **When to use**
+ *
+ * Use to provide `Chat.Persistence` from a configured `BackingPersistence` when
+ * your application needs persisted chat sessions backed by a named store.
+ *
  * **Details**
  *
  * The provided store identifier will be used to indicate which "store" the
  * backing persistence should load chats from.
  *
+ * @see {@link makePersisted} for the effect constructor when building the service directly instead of providing it as a layer
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/ai/EmbeddingModel.ts

@@ -1,18 +1,50 @@
 /**
- * The `EmbeddingModel` module provides provider-agnostic text embedding capabilities.
+ * The `EmbeddingModel` module defines the provider-neutral service for turning
+ * text into embedding vectors. It exposes single-input `embed` and ordered
+ * batch `embedMany` operations, and keeps provider failures represented as
+ * `AiError` values.
  *
- * **Example** (Embedding text with a model)
+ * **Mental model**
+ *
+ * Providers supply one batch embedding function through `make`. The module
+ * derives single-input `embed` calls from a request resolver, so concurrent
+ * single-input requests can be batched into one provider call. Provider
+ * vectors are wrapped as `EmbedResponse` values, while `EmbedManyResponse`
+ * preserves input order and carries token usage when the provider reports it.
+ *
+ * **Common tasks**
+ *
+ * - Build an `EmbeddingModel` service from a provider implementation.
+ * - Use `embed` for one query or document, and `embedMany` when the caller
+ *   already has a batch.
+ * - Read `Dimensions` when downstream code needs the configured vector size.
+ *
+ * **Example** (Building a small embedding model)
  *
  * ```ts
  * import { Effect } from "effect"
  * import { EmbeddingModel } from "effect/unstable/ai"
  *
  * const program = Effect.gen(function*() {
- *   const model = yield* EmbeddingModel.EmbeddingModel
- *   return yield* model.embed("hello world")
+ *   const model = yield* EmbeddingModel.make({
+ *     embedMany: ({ inputs }) =>
+ *       Effect.succeed({
+ *         results: inputs.map((input) => [input.length]),
+ *         usage: { inputTokens: inputs.join(" ").length }
+ *       })
+ *   })
+ *
+ *   const response = yield* model.embed("hello")
+ *   return response.vector
  * })
  * ```
  *
+ * **Gotchas**
+ *
+ * - `embedMany([])` returns an empty response without invoking the provider.
+ * - Provider batch responses must contain exactly one vector for each input,
+ *   in the same order as the input array.
+ *
  * @since 4.0.0
  */
 import * as Context from "../../Context.ts"
@@ -26,6 +58,15 @@ import * as AiError from "./AiError.ts"
 /**
  * Service tag for embedding model operations.
  *
+ * **When to use**
+ *
+ * Use to retrieve or provide an `EmbeddingModel.Service` when an `Effect`
+ * program needs to embed text into vectors.
+ *
+ * @see {@link Service} for the service contract provided by this tag
+ * @see {@link make} for constructing an embedding model service from a provider
+ * @see {@link Dimensions} for the current embedding vector size service
+ *
  * @category services
  * @since 4.0.0
  */
@@ -36,6 +77,13 @@ export class EmbeddingModel extends Context.Service<EmbeddingModel, Service>()(
 /**
  * Service tag that provides the current embedding dimensions.
  *
+ * **When to use**
+ *
+ * Use to retrieve or provide the configured embedding vector size through
+ * context.
+ *
+ * @see {@link EmbeddingModel} for the embedding service that uses these dimensions
+ *
  * @category services
  * @since 4.0.0
  */
@@ -46,6 +94,12 @@ export class Dimensions extends Context.Service<Dimensions, number>()(
 /**
  * Token usage metadata for embedding operations.
  *
+ * **Details**
+ *
+ * Contains optional provider-reported `inputTokens`. The value may be
+ * `undefined` when the provider does not report usage or when `embedMany([])`
+ * bypasses the provider.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -68,7 +122,15 @@ export class EmbedResponse extends Schema.Class<EmbedResponse>(
 }) {}
 
 /**
- * Response for multiple embeddings.
+ * Batch embedding response containing per-input embeddings and usage metadata.
+ *
+ * **Details**
+ *
+ * `embeddings` preserves batch order, and `usage` carries token metadata for
+ * the operation.
+ *
+ * @see {@link EmbedResponse} for individual embedding responses
+ * @see {@link EmbeddingUsage} for token usage metadata
  *
  * @category models
  * @since 4.0.0
@@ -106,6 +168,15 @@ export interface ProviderResponse {
 /**
  * Tagged request used by request resolvers for embedding operations.
  *
+ * **When to use**
+ *
+ * Use when building or calling a low-level embedding request resolver and you
+ * need a typed request for one input that resolves to `EmbedResponse`.
+ *
+ * @see {@link Service} for the resolver-bearing service contract
+ * @see {@link make} for constructing the request resolver from a provider implementation
+ * @see {@link EmbedResponse} for the response produced by this request
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -137,6 +208,30 @@ const invalidProviderResponse = (description: string): AiError.AiError =>
 /**
  * Creates an EmbeddingModel service from a provider embedMany implementation.
  *
+ * **When to use**
+ *
+ * Use to adapt a provider's batch embedding implementation into an
+ * `EmbeddingModel.Service` that offers single-input and batch embedding
+ * operations.
+ *
+ * **Details**
+ *
+ * The returned service builds single-input `embed` calls through a request
+ * resolver, so concurrent `embed` requests can be batched into one provider
+ * `embedMany` call. Direct `embedMany` calls pass the input array to the
+ * provider, while `embedMany([])` returns an empty response without calling the
+ * provider.
+ *
+ * **Gotchas**
+ *
+ * Provider responses are interpreted positionally and must contain exactly one
+ * result for each requested input. If the provider returns a different number
+ * of results, `embed` and `embedMany` fail with `AiError.InvalidOutputError`.
+ *
+ * @see {@link Service} for the service shape returned by this constructor
+ * @see {@link ProviderOptions} for the input passed to the provider implementation
+ * @see {@link ProviderResponse} for the provider response contract consumed by this constructor
+ *
  * @category constructors
  * @since 4.0.0
  */

package/src/unstable/ai/IdGenerator.ts

@@ -301,7 +301,7 @@ export const make = Effect.fnUntraced(function*({
  *
  * **When to use**
  *
- * This is the recommended way to provide ID generation capabilities to your
+ * Use when this is the recommended way to provide ID generation capabilities to your
  * application. The layer will fail during construction if the configuration is
  * invalid.
  *

package/src/unstable/ai/LanguageModel.ts

@@ -234,6 +234,20 @@ export type CodecTransformer = <T, E, RD, RE>(schema: Schema.Codec<T, E, RD, RE>
  * The default codec transformer that passes schemas through without
  * provider-specific rewrites.
  *
+ * **When to use**
+ *
+ * Use as the codec transformer for provider implementations when the provider
+ * accepts the JSON Schema generated from an `Effect` Schema codec without
+ * provider-specific rewrites.
+ *
+ * **Details**
+ *
+ * The transformer returns the original codec, resolves a top-level `$ref`, and
+ * copies schema definitions into `$defs`.
+ *
+ * @see {@link CodecTransformer} for the structured-output transformer contract
+ * @see {@link make} for where this transformer is used as the default
+ *
  * @category services
  * @since 4.0.0
  */
@@ -286,7 +300,7 @@ export interface GenerateTextOptions<Tools extends Record<string, Tool.Any>> {
    *
    * **When to use**
    *
-   * Use this when you want to include tool call definitions from an `AiToolkit`
+   * Use when you want to include tool call definitions from an `AiToolkit`
    * in requests to the large language model, while controlling tool call
    * resolver execution yourself.
    */
@@ -734,7 +748,32 @@ export interface ProviderOptions {
 }
 
 /**
- * Creates a LanguageModel service from provider-specific text generation and streaming implementations.
+ * Creates a LanguageModel service from provider-specific text generation and
+ * streaming implementations.
+ *
+ * **When to use**
+ *
+ * Use to build a `LanguageModel.Service` from provider-specific final and
+ * streaming text generation functions.
+ *
+ * **Details**
+ *
+ * The returned service implements `generateText`, `generateObject`, and
+ * `streamText`. It prepares `ProviderOptions` for each request, including the
+ * normalized prompt, tools, tool choice, response format, tracing span, and
+ * incremental response fields, before calling the supplied provider hook.
+ * Structured object generation uses the `generateText` hook and the configured
+ * `codecTransformer`, or `defaultCodecTransformer` when none is supplied.
+ *
+ * **Gotchas**
+ *
+ * Provider hooks must return encoded response parts that match the toolkit and
+ * response format prepared in `ProviderOptions`; invalid parts fail decoding as
+ * `AiError.InvalidOutputError`.
+ *
+ * @see {@link Service} for the returned service contract
+ * @see {@link ProviderOptions} for the normalized options passed to provider hooks
+ * @see {@link defaultCodecTransformer} for the default structured-output schema transformer
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/ai/McpSchema.ts

@@ -293,7 +293,7 @@ export type Role = typeof Role.Type
 
 /**
  * Optional annotations for the client. The client can use annotations to
- * inform how objects are used or displayed
+ * inform how objects are used or displayed.
  *
  * @category common
  * @since 4.0.0
@@ -879,7 +879,7 @@ export class TextResourceContents extends Schema.Opaque<TextResourceContents>()(
 })) {}
 
 /**
- * The contents of a binary resource, which can be represented as an Uint8Array
+ * The contents of a binary resource, which can be represented as a Uint8Array.
  *
  * @category resources
  * @since 4.0.0
@@ -1457,6 +1457,14 @@ export class CallToolResult extends Schema.Class<CallToolResult>("@effect/ai/Mcp
 /**
  * Used by the client to invoke a tool provided by the server.
  *
+ * **When to use**
+ *
+ * Use when a client already knows the tool name and wants the server to execute
+ * it with argument values.
+ *
+ * @see {@link ListTools} for discovering available tools before calling one
+ * @see {@link CallToolResult} for the successful tool-call result shape
+ *
  * @category tools
  * @since 4.0.0
  */

package/src/unstable/ai/McpServer.ts

@@ -547,6 +547,27 @@ export const run: (options: {
  * `RpcServer.Protocol` and provides the `McpServer` and `McpServerClient`
  * services.
  *
+ * **When to use**
+ *
+ * Use when you already have a custom or externally provided
+ * `RpcServer.Protocol` and want to start an MCP server as part of a layer
+ * graph.
+ *
+ * **Details**
+ *
+ * The returned layer forks `run(options)` in the layer scope and merges
+ * `McpServer.layer`, so registration layers can use the `McpServer` service
+ * while the server is running.
+ *
+ * **Gotchas**
+ *
+ * Unlike `layerStdio` and `layerHttp`, this layer does not install a concrete
+ * transport. The surrounding layer graph must provide `RpcServer.Protocol`.
+ *
+ * @see {@link run} for the effect form used by this layer
+ * @see {@link layerStdio} for a stdio-backed layer that installs the MCP protocol and NDJSON-RPC serialization
+ * @see {@link layerHttp} for an HTTP-backed layer that registers with `HttpRouter` and installs JSON-RPC serialization
+ *
  * @category layers
  * @since 4.0.0
  */
@@ -628,7 +649,20 @@ export const layerStdio = (options: {
   )
 
 /**
- * Run the `McpServer`, registering a router with a `HttpRouter`
+ * Registers an HTTP POST JSON-RPC route at `options.path` on the current
+ * `HttpRouter`.
+ *
+ * **When to use**
+ *
+ * Use to expose an MCP server through an existing `HttpRouter`.
+ *
+ * **Details**
+ *
+ * This layer composes `layer(options)`, `RpcServer.layerProtocolHttp(options)`,
+ * and `RpcSerialization.layerJsonRpc()`.
+ *
+ * @see {@link layerStdio} for exposing the server over stdio
+ * @see {@link layer} for the base MCP server layer without a transport protocol
  *
  * @category layers
  * @since 4.0.0
@@ -1016,6 +1050,18 @@ export const resource: {
 /**
  * Register a prompt with the McpServer.
  *
+ * **When to use**
+ *
+ * Use to register an MCP prompt from an Effect program.
+ *
+ * **Details**
+ *
+ * Parameters are decoded with the supplied schema, completion handlers encode
+ * per-parameter suggestions, and string prompt content is converted into a user
+ * text message.
+ *
+ * @see {@link prompt} for the layer-based prompt registration wrapper
+ *
  * @category prompts
  * @since 4.0.0
  */
@@ -1111,6 +1157,18 @@ export const registerPrompt = <
 /**
  * Register a prompt with the McpServer.
  *
+ * **When to use**
+ *
+ * Use to compose prompt registration into an MCP server layer.
+ *
+ * **Details**
+ *
+ * Parameters are decoded with the supplied schema, completion handlers encode
+ * per-parameter suggestions, and string prompt content is converted into a user
+ * text message.
+ *
+ * @see {@link registerPrompt} for the Effect-level prompt registration API
+ *
  * @category prompts
  * @since 4.0.0
  */

package/src/unstable/ai/Model.ts

@@ -1,30 +1,52 @@
 /**
- * The `Model` module provides a unified interface for AI service providers.
+ * The `Model` module wraps a provider-specific language model layer with the
+ * metadata Effect AI needs at runtime. A `Model` is still a `Layer`, but it
+ * also provides the current provider name and model name to programs that need
+ * to inspect or report which model is in use.
  *
- * This module enables creation of provider-specific AI models that can be used
- * interchangeably within the Effect AI ecosystem. It combines Layer
- * functionality with provider identification, allowing for seamless switching
- * between different AI service providers while maintaining type safety.
+ * **Mental model**
  *
- * **Example** (Creating a provider-specific model)
+ * - `make` combines a provider identifier, a model identifier, and a layer that
+ *   provides AI services such as `LanguageModel`.
+ * - Providing the resulting model installs both the provider services and the
+ *   metadata services {@link ProviderName} and {@link ModelName}.
+ * - `captureRequirements` lets effectful setup capture the current environment
+ *   into a concrete model layer.
+ *
+ * **Common tasks**
+ *
+ * - Create a provider-backed model with {@link make}.
+ * - Provide the model to a program with `Effect.provide`.
+ * - Read {@link ProviderName} and {@link ModelName} inside shared workflows,
+ *   telemetry, or provider-agnostic services.
+ *
+ * **Gotchas**
+ *
+ * - The provider and model names are metadata; the actual implementation still
+ *   comes from the layer passed to {@link make}.
+ * - If the underlying layer has requirements, those requirements must be
+ *   satisfied before the model can be provided.
+ *
+ * **Example** (Providing model metadata)
  *
  * ```ts
  * import { Effect } from "effect"
  * import type { Layer } from "effect"
  * import { LanguageModel, Model } from "effect/unstable/ai"
  *
- * declare const myAnthropicLayer: Layer.Layer<LanguageModel.LanguageModel>
+ * declare const languageModelLayer: Layer.Layer<LanguageModel.LanguageModel>
  *
- * const anthropicModel = Model.make("anthropic", "claude-3-5-haiku", myAnthropicLayer)
+ * const model = Model.make("example-provider", "fast-text", languageModelLayer)
  *
  * const program = Effect.gen(function*() {
+ *   const provider = yield* Model.ProviderName
+ *   const modelName = yield* Model.ModelName
  *   const response = yield* LanguageModel.generateText({
- *     prompt: "Hello, world!"
+ *     prompt: `Generate with ${provider}/${modelName}`
  *   })
+ *
  *   return response.text
- * }).pipe(
- *   Effect.provide(anthropicModel)
- * )
+ * }).pipe(Effect.provide(model))
  * ```
  *
  * @since 4.0.0
@@ -42,7 +64,7 @@ const TypeId = "~effect/ai/Model" as const
  *
  * **When to use**
  *
- * Use a Model directly as a Layer to provide a particular model implementation
+ * Use when you use a Model directly as a Layer to provide a particular model implementation
  * to an Effect program, or use it as an Effect to "lift" dependencies of the
  * Model constructor into the parent Effect when you want to use a Model from
  * within an Effect service.

package/src/unstable/ai/OpenAiStructuredOutput.ts

@@ -1,5 +1,52 @@
 /**
- * Provides codec transformations for OpenAI structured output.
+ * Adapt Effect Schema codecs to the JSON Schema subset accepted by OpenAI
+ * structured output.
+ *
+ * The main entry point is {@link toCodecOpenAI}. It returns a JSON Schema value
+ * for the model request and a codec that preserves the original decoded Type
+ * while changing the encoded representation when OpenAI cannot express that
+ * shape directly.
+ *
+ * **Mental model**
+ *
+ * OpenAI structured output requires a narrower schema vocabulary than Effect
+ * Schema. This module walks the schema AST before JSON Schema generation,
+ * rewrites unsupported shapes into OpenAI-compatible encodings, and
+ * post-processes the generated JSON Schema to remove constructs such as
+ * `allOf`.
+ *
+ * **Common tasks**
+ *
+ * - Convert a `Schema.Codec` for an OpenAI response format with
+ *   {@link toCodecOpenAI}
+ * - Decode model output back into the original application shape with the
+ *   returned codec
+ * - Represent optional properties as `T | null`, tuples as objects with
+ *   numeric string keys, and records as arrays of `[key, value]` pairs
+ *
+ * **Gotchas**
+ *
+ * - The returned codec may encode to a different shape than the input schema,
+ *   so use it for decoding model output instead of the original schema.
+ * - Unsupported schema kinds throw during conversion rather than producing a
+ *   lossy schema.
+ * - Optional properties are required in the emitted JSON Schema and use `null`
+ *   to represent absence because OpenAI requires object keys to be present.
+ *
+ * **Example** (Prepare a response schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { OpenAiStructuredOutput } from "effect/unstable/ai"
+ *
+ * const Weather = Schema.Struct({
+ *   city: Schema.String,
+ *   forecast: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * const output = OpenAiStructuredOutput.toCodecOpenAI(Weather)
+ * console.log(output.jsonSchema)
+ * ```
  *
  * @since 4.0.0
  */

package/src/unstable/ai/Prompt.ts

@@ -522,7 +522,14 @@ export const FilePart: Schema.Struct<{
 }).annotate({ identifier: "FilePart" })
 
 /**
- * Constructs a new file part.
+ * Constructs a `FilePart` for prompt file attachments.
+ *
+ * **When to use**
+ *
+ * Use to create the file-attachment part of a prompt from typed file part
+ * parameters.
+ *
+ * @see {@link makePart} for the generic part constructor
  *
  * @category constructors
  * @since 4.0.0
@@ -768,7 +775,7 @@ export const toolResultPart = (params: PartConstructorParams<ToolResultPart>): T
  *
  * **When to use**
  *
- * Use this part in tool messages to approve or deny tool execution when tools
+ * Use when you use this part in tool messages to approve or deny tool execution when tools
  * have the `needsApproval` property set.
  *
  * **Example** (Creating tool approval responses)
@@ -1476,6 +1483,12 @@ export interface AssistantMessageOptions extends ProviderOptions {}
 /**
  * Schema for validation and encoding of assistant messages.
  *
+ * **Details**
+ *
+ * Assistant content can be a string decoded through `ContentFromString` or an
+ * array of text, file, reasoning, tool-call, tool-result, and
+ * tool-approval-request parts.
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1543,6 +1556,14 @@ export const AssistantMessage: Schema.Struct<{
 /**
  * Constructs a new assistant message.
  *
+ * **When to use**
+ *
+ * Use to add assistant-role prompt history or model responses.
+ *
+ * **Details**
+ *
+ * This is the role-specific wrapper around `makeMessage("assistant", params)`.
+ *
  * @category constructors
  * @since 4.0.0
  */