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

package/src/SchemaRepresentation.ts

@@ -108,7 +108,7 @@ import * as Getter from "./SchemaGetter.ts"
  *
  * **When to use**
  *
- * Use this when inspecting or transforming non-primitive schema types.
+ * Use when inspecting or transforming non-primitive schema types.
  *
  * **Details**
  *
@@ -758,7 +758,7 @@ export interface References {
  *
  * **When to use**
  *
- * Use {@link fromAST} to create a `Document` from a Schema AST, {@link toSchema}
+ * Use when you use {@link fromAST} to create a `Document` from a Schema AST, {@link toSchema}
  * to reconstruct a runtime Schema, {@link toJsonSchemaDocument} to convert to
  * JSON Schema, and {@link toMultiDocument} to wrap it as a
  * {@link MultiDocument}.
@@ -779,7 +779,7 @@ export type Document = {
  *
  * **When to use**
  *
- * Use {@link fromASTs} to create this from multiple Schema ASTs,
+ * Use when you use {@link fromASTs} to create this from multiple Schema ASTs,
  * {@link toCodeDocument} to generate TypeScript code, and
  * {@link toJsonSchemaMultiDocument} to convert to JSON Schema.
  *
@@ -818,6 +818,14 @@ export type PrimitiveTree = Schema.Tree<null | number | boolean | bigint | symbo
 /**
  * Schema codec for {@link PrimitiveTree}.
  *
+ * **When to use**
+ *
+ * Use to validate recursive annotation metadata trees whose leaves are `null`,
+ * `number`, `boolean`, `bigint`, `symbol`, or `string`.
+ *
+ * @see {@link PrimitiveTree} for the recursive tree type accepted by this codec
+ * @see {@link $Annotations} for the annotation codec that filters values through this codec
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -838,6 +846,18 @@ const isPrimitiveTree = Schema.is($PrimitiveTree)
  * Schema codec for `Schema.Annotations.Annotations`. Filters out internal
  * annotation keys and non-primitive values during encoding.
  *
+ * **When to use**
+ *
+ * Use to serialize schema annotations in representation schemas while retaining
+ * only primitive-tree metadata.
+ *
+ * **Details**
+ *
+ * Decoding is passthrough. Encoding removes internal annotation keys and values
+ * that are not accepted by `$PrimitiveTree`.
+ *
+ * @see {@link $PrimitiveTree} for the codec used to filter annotation values
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1203,6 +1223,18 @@ const $BigIntMeta = Schema.Union([
 /**
  * Schema codec for the {@link BigInt} representation node.
  *
+ * **When to use**
+ *
+ * Use to encode, decode, or validate serialized `BigInt` representation nodes,
+ * not application `bigint` values.
+ *
+ * **Details**
+ *
+ * Accepts representation nodes with `_tag: "BigInt"`, optional annotations,
+ * and bigint-specific validation metadata in `checks`.
+ *
+ * @see {@link BigIntMeta} for the metadata accepted by the `checks` array
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1592,8 +1624,20 @@ export const $Representation: $Representation = Schema.Union([
 ]).annotate({ identifier: "Schema" })
 
 /**
- * Schema codec for {@link Document}. Use with `Schema.decodeUnknownSync` or
- * `Schema.encodeSync` to validate or serialize document data.
+ * Schema codec for {@link Document}.
+ *
+ * **When to use**
+ *
+ * Use to validate or serialize a single schema representation document with
+ * `Schema.decodeUnknownSync` or `Schema.encodeSync`.
+ *
+ * **Gotchas**
+ *
+ * This codec validates document structure but does not resolve `$ref` keys
+ * against `references`.
+ *
+ * @see {@link DocumentFromJson} for the JSON-string codec wrapper
+ * @see {@link $MultiDocument} for validating documents with multiple root representations
  *
  * @category schemas
  * @since 4.0.0
@@ -1623,7 +1667,7 @@ export const $MultiDocument = Schema.Struct({
  *
  * **When to use**
  *
- * Use this when you have a single schema and need its representation.
+ * Use when you have a single schema and need its representation.
  *
  * **Details**
  *
@@ -1658,7 +1702,7 @@ export const fromAST: (ast: AST.AST) => Document = InternalRepresentation.fromAS
  *
  * **When to use**
  *
- * Use this when you have multiple schemas that may share references.
+ * Use when you have multiple schemas that may share references.
  *
  * **Details**
  *
@@ -1678,7 +1722,7 @@ export const fromASTs: (asts: readonly [AST.AST, ...Array<AST.AST>]) => MultiDoc
  *
  * **When to use**
  *
- * Use this with `Schema.decodeUnknownSync` or `Schema.encodeSync` to serialize
+ * Use with `Schema.decodeUnknownSync` or `Schema.encodeSync` to serialize
  * and deserialize documents.
  *
  * **Example** (Round-tripping a Document through JSON)
@@ -1717,7 +1761,7 @@ export const MultiDocumentFromJson: Schema.Codec<MultiDocument, Schema.Json> = S
  *
  * **When to use**
  *
- * Use this when an API expects a `MultiDocument` but you only have a single
+ * Use when an API expects a `MultiDocument` but you only have a single
  * `Document`.
  *
  * **Details**
@@ -1764,8 +1808,8 @@ export type Reviver<T> = (declaration: Declaration, recur: (representation: Repr
  *
  * **When to use**
  *
- * Pass this as `options.reviver` to {@link toSchema} to reconstruct schemas
- * that use these types.
+ * Use when passing this as `options.reviver` to {@link toSchema} to reconstruct
+ * schemas that use these types.
  *
  * **Details**
  *
@@ -1852,7 +1896,7 @@ export const toSchemaDefaultReviver: Reviver<Schema.Top> = (s, recur) => {
  *
  * **When to use**
  *
- * Use this when you have a serialized or computed representation and need a
+ * Use when you have a serialized or computed representation and need a
  * working Schema for decoding/encoding.
  *
  * **Details**
@@ -2198,7 +2242,7 @@ export function toSchema<S extends Schema.Top = Schema.Top>(document: Document,
  *
  * **When to use**
  *
- * Use this to produce a standard JSON Schema from an Effect Schema
+ * Use to produce a standard JSON Schema from an Effect Schema
  * representation.
  *
  * **Details**
@@ -2234,7 +2278,7 @@ export const toJsonSchemaDocument: (
  *
  * **When to use**
  *
- * Use this when you have multiple schemas sharing references.
+ * Use when you have multiple schemas sharing references.
  *
  * **Details**
  *
@@ -2344,7 +2388,7 @@ export type CodeDocument = {
  *
  * **When to use**
  *
- * Use this to produce source code for Schema definitions, such as in codegen
+ * Use to produce source code for Schema definitions, such as in codegen
  * tools.
  *
  * **Details**
@@ -2980,7 +3024,7 @@ function toRuntimeRegExp(regExp: RegExp): string {
  *
  * **When to use**
  *
- * Use this to import external JSON Schemas into the Effect representation
+ * Use to import external JSON Schemas into the Effect representation
  * system.
  *
  * **Details**
@@ -3020,7 +3064,7 @@ export function fromJsonSchemaDocument(document: JsonSchema.Document<"draft-2020
  *
  * **When to use**
  *
- * Use this to import multiple JSON Schemas sharing definitions.
+ * Use to import multiple JSON Schemas sharing definitions.
  *
  * **Details**
  *

package/src/SchemaTransformation.ts

@@ -102,7 +102,7 @@ import * as Issue from "./SchemaIssue.ts"
  *
  * **When to use**
  *
- * - You need to catch or recover from parsing errors (e.g. `Schema.catchDecoding`).
+ * Use when you need to catch or recover from parsing errors (e.g. `Schema.catchDecoding`).
  * - You need to run side effects around the parsing pipeline.
  * - You need access to the full `Effect` rather than a single decoded value.
  *
@@ -176,7 +176,7 @@ const TypeId = "~effect/SchemaTransformation/Transformation"
  *
  * **When to use**
  *
- * - You need to define how a schema converts between two representations.
+ * Use when you need to define how a schema converts between two representations.
  * - You want to compose multiple transformations into a pipeline.
  * - You want to flip a transformation to swap decode/encode.
  *
@@ -240,7 +240,7 @@ export class Transformation<in out T, in out E, RD = never, RE = never> {
  *
  * **When to use**
  *
- * - Checking whether a value is already a Transformation before wrapping it.
+ * Use to check whether a value is already a Transformation before wrapping it.
  *
  * **Details**
  *
@@ -275,7 +275,7 @@ export function isTransformation(u: unknown): u is Transformation<any, any, unkn
  *
  * **When to use**
  *
- * - You already have `Getter` instances and want to pair them.
+ * Use when you already have `Getter` instances and want to pair them.
  * - You want idempotent wrapping (won't double-wrap).
  *
  * **Details**
@@ -317,7 +317,7 @@ export const make = <T, E, RD = never, RE = never>(options: {
  *
  * **When to use**
  *
- * - The transformation can fail (e.g. parsing, validation).
+ * Use when the transformation can fail (e.g. parsing, validation).
  * - The transformation requires Effect services.
  *
  * **Details**
@@ -370,7 +370,7 @@ export function transformOrFail<T, E, RD = never, RE = never>(options: {
  *
  * **When to use**
  *
- * - The conversion cannot fail.
+ * Use when the conversion cannot fail.
  * - No Effect services are needed.
  *
  * **Details**
@@ -418,7 +418,7 @@ export function transform<T, E>(options: {
  *
  * **When to use**
  *
- * - You need to produce or consume `Option.None` to represent absent keys.
+ * Use when you need to produce or consume `Option.None` to represent absent keys.
  * - You are working with optional struct fields.
  *
  * **Details**
@@ -469,7 +469,7 @@ export function transformOptional<T, E>(options: {
  *
  * **When to use**
  *
- * - Normalizing user input by stripping leading/trailing whitespace.
+ * Use to normalize user input by stripping leading/trailing whitespace.
  *
  * **Details**
  *
@@ -507,7 +507,7 @@ export function trim(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Converting API field names between snake_case and camelCase conventions.
+ * Use to convert API field names between snake_case and camelCase conventions.
  *
  * **Details**
  *
@@ -544,7 +544,7 @@ export function snakeToCamel(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Normalizing strings to lowercase (e.g. email addresses).
+ * Use to normalize strings to lowercase (e.g. email addresses).
  *
  * **Details**
  *
@@ -581,7 +581,7 @@ export function toLowerCase(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Normalizing strings to uppercase (e.g. country codes).
+ * Use to normalize strings to uppercase (e.g. country codes).
  *
  * **Details**
  *
@@ -618,7 +618,7 @@ export function toUpperCase(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Normalizing display names or titles.
+ * Use to normalize display names or titles.
  *
  * **Details**
  *
@@ -654,7 +654,7 @@ export function capitalize(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Normalizing identifiers or field names.
+ * Use to normalize identifiers or field names.
  *
  * **Details**
  *
@@ -690,7 +690,7 @@ export function uncapitalize(): Transformation<string, string> {
  *
  * **When to use**
  *
- * - Parsing query-string-like or config-file-like strings into records.
+ * Use to parse query-string-like or config-file-like strings into records.
  *
  * **Details**
  *
@@ -740,7 +740,7 @@ const passthrough_ = new Transformation(
  *
  * **When to use**
  *
- * - Connecting two schemas that share the same type with no conversion.
+ * Use when connecting two schemas that share the same type with no conversion.
  * - As a placeholder when `Schema.decodeTo` requires a transformation but
  *   no actual conversion is needed.
  *
@@ -780,7 +780,7 @@ export function passthrough<T>(): Transformation<T, T> {
  *
  * **When to use**
  *
- * Use this when the runtime value is unchanged but the decoded side should be
+ * Use when the runtime value is unchanged but the decoded side should be
  * narrower than the encoded side.
  *
  * **Details**
@@ -813,7 +813,7 @@ export function passthroughSupertype<T>(): Transformation<T, T> {
  *
  * **When to use**
  *
- * - Narrowing: the encoded side is more specific than the decoded side.
+ * Use when narrowing: the encoded side is more specific than the decoded side.
  *
  * **Details**
  *
@@ -845,7 +845,7 @@ export function passthroughSubtype<T>(): Transformation<T, T> {
  *
  * **When to use**
  *
- * - Parsing numeric strings from APIs, form data, or URL parameters.
+ * Use to parse numeric strings from APIs, form data, or URL parameters.
  *
  * **Details**
  *
@@ -881,7 +881,7 @@ export const numberFromString = new Transformation(
  *
  * **When to use**
  *
- * - Parsing large integer strings (e.g. database IDs, blockchain values).
+ * Use to parse large integer strings (e.g. database IDs, blockchain values).
  *
  * **Details**
  *
@@ -915,7 +915,7 @@ export const bigintFromString = new Transformation(
  *
  * **When to use**
  *
- * - Parsing ISO 8601 date strings from APIs or user input.
+ * Use to parse ISO 8601 date strings from APIs or user input.
  *
  * **Details**
  *
@@ -950,7 +950,7 @@ export const dateFromString: Transformation<globalThis.Date, string> = new Trans
  *
  * **When to use**
  *
- * - Parsing human-readable duration strings from APIs, config, or user input.
+ * Use to parse human-readable duration strings from APIs, config, or user input.
  *
  * **Details**
  *
@@ -993,7 +993,7 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
  *
  * **When to use**
  *
- * - Working with nanosecond-precision timestamps or intervals.
+ * Use when working with nanosecond-precision timestamps or intervals.
  *
  * **Details**
  *
@@ -1034,7 +1034,7 @@ export const durationFromNanos: Transformation<Duration.Duration, bigint> = tran
  *
  * **When to use**
  *
- * Use this for timeouts, delays, elapsed intervals, or other duration values
+ * Use when you use this for timeouts, delays, elapsed intervals, or other duration values
  * stored as millisecond counts.
  *
  * **Details**
@@ -1099,7 +1099,7 @@ export const errorFromErrorJsonEncoded = (options?: {
  *
  * **When to use**
  *
- * - Converting nullable API fields to `Option`.
+ * Use to convert nullable API fields to `Option`.
  *
  * **Details**
  *
@@ -1138,7 +1138,7 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
  *
  * **When to use**
  *
- * - Converting undefined-or API fields to `Option`.
+ * Use to convert undefined-or API fields to `Option`.
  *
  * **Details**
  *
@@ -1179,7 +1179,7 @@ export function optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T |
  *
  * **When to use**
  *
- * - Converting nullish API fields to `Option` when both `null` and
+ * Use to convert nullish API fields to `Option` when both `null` and
  *   `undefined` represent absence.
  *
  * **Details**
@@ -1225,7 +1225,7 @@ export function optionFromNullishOr<T>(
  *
  * **When to use**
  *
- * - Converting optional struct keys (declared with `Schema.optionalKey`) to
+ * Use to convert optional struct keys (declared with `Schema.optionalKey`) to
  *   `Option` values.
  *
  * **Details**
@@ -1269,7 +1269,7 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
  *
  * **When to use**
  *
- * - Converting optional (possibly `undefined`) values to `Option`.
+ * Use to convert optional (possibly `undefined`) values to `Option`.
  *
  * **Details**
  *
@@ -1312,7 +1312,7 @@ export function optionFromOptional<T>(): Transformation<Option.Option<T>, T | un
  *
  * **When to use**
  *
- * - Parsing URL strings from user input or API responses.
+ * Use to parse URL strings from user input or API responses.
  *
  * **Details**
  *
@@ -1351,7 +1351,7 @@ export const urlFromString: Transformation<URL, string> = transformOrFail<URL, s
  *
  * **When to use**
  *
- * - Parsing decimal number strings from APIs or user input.
+ * Use to parse decimal number strings from APIs or user input.
  *
  * **Details**
  *
@@ -1381,7 +1381,7 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
  *
  * **When to use**
  *
- * - Handling binary data transmitted as Base64 strings (e.g. file uploads,
+ * Use when handling binary data transmitted as Base64 strings (e.g. file uploads,
  *   API payloads).
  *
  * **Details**
@@ -1416,7 +1416,7 @@ export const uint8ArrayFromBase64String: Transformation<Uint8Array<ArrayBufferLi
  *
  * **When to use**
  *
- * - Handling text data transmitted as Base64 strings.
+ * Use when handling text data transmitted as Base64 strings.
  *
  * **Details**
  *
@@ -1449,7 +1449,7 @@ export const stringFromBase64String: Transformation<string, string> = new Transf
  *
  * **When to use**
  *
- * - Handling text data transmitted as Base64 URL-safe strings.
+ * Use when handling text data transmitted as Base64 URL-safe strings.
  *
  * **Details**
  *
@@ -1482,7 +1482,7 @@ export const stringFromBase64UrlString: Transformation<string, string> = new Tra
  *
  * **When to use**
  *
- * - Handling text data transmitted as hexadecimal strings.
+ * Use when handling text data transmitted as hexadecimal strings.
  *
  * **Details**
  *
@@ -1516,7 +1516,7 @@ export const stringFromHexString: Transformation<string, string> = new Transform
  *
  * **When to use**
  *
- * - Storing structured data in URL query parameters or fragments.
+ * Use when storing structured data in URL query parameters or fragments.
  * - Composing with `Schema.parseJson` to round-trip JSON through a URL.
  *
  * **Details**
@@ -1552,7 +1552,7 @@ export const stringFromUriComponent: Transformation<string, string> = new Transf
  *
  * **When to use**
  *
- * Use this for JSON stored or transmitted as a string, usually before composing
+ * Use when you use this for JSON stored or transmitted as a string, usually before composing
  * with another schema that validates the parsed structure.
  *
  * **Details**
@@ -1587,7 +1587,7 @@ export const fromJsonString = new Transformation<unknown, string>(
  *
  * **When to use**
  *
- * Use this for form or multipart payloads where keys such as `user[name]` or
+ * Use when you use this for form or multipart payloads where keys such as `user[name]` or
  * `items[0]` should become nested data.
  *
  * **Details**
@@ -1623,7 +1623,7 @@ export const fromFormData = new Transformation<unknown, FormData>(
  *
  * **When to use**
  *
- * Use this for query strings where keys such as `filter[name]` or `items[0]`
+ * Use when you use this for query strings where keys such as `filter[name]` or `items[0]`
  * should become nested data.
  *
  * **Details**
@@ -1657,11 +1657,19 @@ export const fromURLSearchParams = new Transformation<unknown, URLSearchParams>(
  * Decodes a numeric time-zone offset in milliseconds into a
  * `DateTime.TimeZone.Offset` and encodes it back to the offset number.
  *
+ * **When to use**
+ *
+ * Use to represent fixed-offset time zones with numeric millisecond offsets in
+ * schema transformations or JSON codecs.
+ *
  * **Details**
  *
  * Decode uses `DateTime.zoneMakeOffset`; encode returns the offset's `offset`
  * field.
  *
+ * @see {@link timeZoneFromString} for IANA or offset string encodings
+ * @see {@link timeZoneNamedFromString} for IANA named-zone strings
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1677,11 +1685,18 @@ export const timeZoneOffsetFromNumber: Transformation<DateTime.TimeZone.Offset,
  * Decodes an IANA time-zone identifier string into a
  * `DateTime.TimeZone.Named` and encodes a named time zone back to its `id`.
  *
+ * **When to use**
+ *
+ * Use when a schema transformation should accept only IANA time-zone identifier
+ * strings and produce `DateTime.TimeZone.Named` values.
+ *
  * **Details**
  *
  * Decode fails with `InvalidValue` when the string is not a valid IANA time-zone
  * identifier.
  *
+ * @see {@link timeZoneFromString} for time-zone strings that may be either IANA identifiers or offset strings
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1702,12 +1717,20 @@ export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, st
  * Decodes a string into a `DateTime.TimeZone` and encodes a time zone back to
  * its string representation.
  *
+ * **When to use**
+ *
+ * Use when schema decoding should accept either an IANA time-zone identifier or
+ * an offset string and produce a general `DateTime.TimeZone`.
+ *
  * **Details**
  *
  * Accepted decode inputs include valid IANA identifiers and offset strings such
  * as `"+03:00"`. Decode fails with `InvalidValue` when the string cannot be
  * parsed as a time zone.
  *
+ * @see {@link timeZoneNamedFromString} for IANA named-zone strings only
+ * @see {@link timeZoneOffsetFromNumber} for fixed-offset zones encoded as numbers
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1728,12 +1751,20 @@ export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = tra
  * Decodes a date-time string into a `DateTime.Utc` and encodes it back to an ISO
  * string.
  *
+ * **When to use**
+ *
+ * Use to decode date-time strings when the schema value should be a normalized
+ * `DateTime.Utc` and encode back as a UTC ISO string.
+ *
  * **Details**
  *
  * Decode accepts strings supported by `DateTime.make`, converts the result to
  * UTC, and fails with `InvalidValue` when parsing fails. Encode uses
  * `DateTime.formatIso`.
  *
+ * @see {@link dateTimeZonedFromString} for ISO strings that should preserve zoned date-time information
+ * @see {@link dateFromString} for decoding into JavaScript `Date`
+ *
  * @category transforming
  * @since 4.0.0
  */
@@ -1755,12 +1786,19 @@ export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = trans
  * Decodes a zoned date-time string into a `DateTime.Zoned` and encodes it back
  * to an ISO zoned string.
  *
+ * **When to use**
+ *
+ * Use to define a schema transformation for ISO zoned date-time strings that
+ * decode to `DateTime.Zoned` and encode with `DateTime.formatIsoZoned`.
+ *
  * **Details**
  *
  * Decode uses `DateTime.makeZonedFromString` and fails with `InvalidValue` when
  * the input is not a valid zoned date-time. Encode uses
  * `DateTime.formatIsoZoned`.
  *
+ * @see {@link dateTimeUtcFromString} for date-time strings that should decode to `DateTime.Utc` and encode as UTC ISO strings
+ *
  * @category transforming
  * @since 4.0.0
  */