effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/unstable/encoding/Msgpack.ts

@@ -1,4 +1,20 @@
 /**
+ * Utilities for encoding Effect channel payloads and schema values as
+ * MessagePack bytes.
+ *
+ * This module is useful when a protocol or storage layer expects compact binary
+ * frames instead of JSON text, such as RPC transports, socket streams, caches,
+ * or database columns that carry typed Effect data. Use the raw channel helpers
+ * when both sides already agree on the MessagePack value shape, and use the
+ * schema-aware helpers when values should be validated, transformed, or decoded
+ * into domain types at the boundary.
+ *
+ * MessagePack preserves binary data and common JavaScript collection shapes, but
+ * it is still a data format rather than an Effect schema. Schema encoders run
+ * before packing and schema decoders run after unpacking, so unsupported runtime
+ * values, lossy schema encodings, or mismatched schemas surface as either
+ * `MsgPackError` or `SchemaError` depending on where the failure occurs.
+ *
  * @since 4.0.0
  */
 import { Packr, Unpackr } from "msgpackr"
@@ -19,19 +35,28 @@ import * as Transformation from "../../SchemaTransformation.ts"
 const MsgPackErrorTypeId = "~effect/encoding/MsgPack/MsgPackError"
 
 /**
- * @since 4.0.0
+ * Error raised when MessagePack encoding or decoding fails.
+ *
+ * The `kind` field identifies whether the failure happened while packing or
+ * unpacking, and `cause` preserves the original error.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class MsgPackError extends Data.TaggedError("MsgPackError")<{
   readonly kind: "Pack" | "Unpack"
   readonly cause: unknown
 }> {
   /**
+   * Marks this value as a MessagePack encoding or decoding error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [MsgPackErrorTypeId] = MsgPackErrorTypeId
 
   /**
+   * Uses the failed MessagePack operation as the public message.
+   *
    * @since 4.0.0
    */
   override get message() {
@@ -40,8 +65,13 @@ export class MsgPackError extends Data.TaggedError("MsgPackError")<{
 }
 
 /**
- * @since 4.0.0
+ * Creates a channel that encodes non-empty chunks of values as MessagePack byte
+ * arrays.
+ *
+ * The channel fails with `MsgPackError` when any value cannot be packed.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encode = <IE = never, Done = unknown>(): Channel.Channel<
   Arr.NonEmptyReadonlyArray<Uint8Array<ArrayBuffer>>,
@@ -65,8 +95,13 @@ export const encode = <IE = never, Done = unknown>(): Channel.Channel<
   )
 
 /**
- * @since 4.0.0
+ * Creates a MessagePack encoder channel for values of a schema.
+ *
+ * Values are first encoded with the schema and then packed as MessagePack bytes,
+ * so the channel can fail with either schema errors or `MsgPackError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encodeSchema = <S extends Schema.Top>(
   schema: S
@@ -82,8 +117,13 @@ export const encodeSchema = <S extends Schema.Top>(
 > => Channel.pipeTo(ChannelSchema.encode(schema)(), encode())
 
 /**
- * @since 4.0.0
+ * Creates a channel that decodes MessagePack byte chunks into values.
+ *
+ * Incomplete frames are buffered across chunks, and invalid MessagePack data
+ * fails with `MsgPackError`.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decode = <IE = never, Done = unknown>(): Channel.Channel<
   Arr.NonEmptyReadonlyArray<unknown>,
@@ -131,8 +171,13 @@ export const decode = <IE = never, Done = unknown>(): Channel.Channel<
   )
 
 /**
- * @since 4.0.0
+ * Creates a MessagePack decoder channel for values of a schema.
+ *
+ * The channel unpacks bytes into unknown values and then decodes each value with
+ * the schema.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decodeSchema = <S extends Schema.Top>(
   schema: S
@@ -148,8 +193,13 @@ export const decodeSchema = <S extends Schema.Top>(
 > => Channel.pipeTo(decode<IE, Done>(), ChannelSchema.decodeUnknown(schema)())
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional byte channel with MessagePack encoding and decoding.
+ *
+ * Outgoing values are packed as MessagePack bytes before reaching the wrapped
+ * channel, and incoming bytes are unpacked into values.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplex = <R, IE, OE, OutDone, InDone>(
   self: Channel.Channel<
@@ -176,13 +226,27 @@ export const duplex = <R, IE, OE, OutDone, InDone>(
   )
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
+ * decoding.
+ *
+ * Values sent to the wrapped channel are encoded with `inputSchema` and packed
+ * as MessagePack bytes; bytes received from it are unpacked and decoded with
+ * `outputSchema`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplexSchema: {
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema` and packed
+   * as MessagePack bytes; bytes received from it are unpacked and decoded with
+   * `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <In extends Schema.Top, Out extends Schema.Top>(
     options: {
@@ -209,8 +273,15 @@ export const duplexSchema: {
     R | In["EncodingServices"] | Out["DecodingServices"]
   >
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with schema-aware MessagePack encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema` and packed
+   * as MessagePack bytes; bytes received from it are unpacked and decoded with
+   * `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Out extends Schema.Top, In extends Schema.Top, OutErr, OutDone, InErr, InDone, R>(
     self: Channel.Channel<
@@ -260,14 +331,23 @@ export const duplexSchema: {
 > => ChannelSchema.duplexUnknown(duplex(self), options))
 
 /**
- * @since 4.0.0
+ * Schema type for values encoded as MessagePack bytes.
+ *
+ * It decodes a `Uint8Array` MessagePack payload to the target schema type and
+ * encodes the target type back to bytes.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export interface schema<S extends Schema.Top> extends Schema.decodeTo<S, Schema.instanceOf<Uint8Array<ArrayBuffer>>> {}
 
 /**
- * @since 4.0.0
+ * Schema transformation between MessagePack bytes and decoded values.
+ *
+ * MessagePack codec failures are converted to `InvalidValue` schema issues.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const transformation: Transformation.Transformation<
   unknown,
@@ -298,8 +378,13 @@ export const transformation: Transformation.Transformation<
 })
 
 /**
- * @since 4.0.0
+ * Builds a schema that stores values as MessagePack bytes.
+ *
+ * The resulting schema decodes `Uint8Array` payloads with MessagePack and the
+ * provided schema, and encodes values back to MessagePack bytes.
+ *
  * @category schemas
+ * @since 4.0.0
  */
 export const schema = <S extends Schema.Top>(schema: S): schema<S> =>
   (Schema.Uint8Array as Schema.instanceOf<Uint8Array<ArrayBuffer>>).pipe(

package/src/unstable/encoding/Ndjson.ts

@@ -1,4 +1,20 @@
 /**
+ * Utilities for encoding Effect channel payloads and schema values as
+ * newline-delimited JSON.
+ *
+ * NDJSON represents a stream as one complete JSON value per line, making this
+ * module useful for log pipelines, long-lived HTTP responses, socket protocols,
+ * and file formats where records should be processed incrementally instead of
+ * buffering a whole JSON array. Use the byte helpers at transport boundaries
+ * that speak UTF-8, the string helpers when text framing is already handled,
+ * and the schema-aware helpers when each record should be validated or
+ * transformed at the boundary.
+ *
+ * Encoders append a trailing newline after each emitted chunk, and decoders
+ * tolerate records split across input chunks. Empty lines are only skipped when
+ * `ignoreEmptyLines` is enabled; otherwise they are passed to `JSON.parse` and
+ * fail like any other invalid JSON record.
+ *
  * @since 4.0.0
  */
 import * as Arr from "../../Array.ts"
@@ -14,19 +30,28 @@ const NdjsonErrorTypeId = "~effect/encoding/Ndjson/NdjsonError"
 const encoder = new TextEncoder()
 
 /**
- * @since 4.0.0
+ * Error raised when NDJSON encoding or decoding fails.
+ *
+ * The `kind` field identifies whether the failure happened while packing or
+ * unpacking, and `cause` preserves the original error.
+ *
  * @category errors
+ * @since 4.0.0
  */
 export class NdjsonError extends Data.TaggedError("NdjsonError")<{
   readonly kind: "Pack" | "Unpack"
   readonly cause: unknown
 }> {
   /**
+   * Marks this value as an NDJSON encoding or decoding error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [NdjsonErrorTypeId] = NdjsonErrorTypeId
 
   /**
+   * Uses the failed NDJSON operation as the public message.
+   *
    * @since 4.0.0
    */
   override get message() {
@@ -35,8 +60,13 @@ export class NdjsonError extends Data.TaggedError("NdjsonError")<{
 }
 
 /**
- * @since 4.0.0
+ * Creates a channel that encodes chunks of values as NDJSON strings.
+ *
+ * Each input item is `JSON.stringify`-encoded, separated by newlines, and the
+ * output chunk ends with a trailing newline.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encodeString = <IE = never, Done = unknown>(): Channel.Channel<
   Arr.NonEmptyReadonlyArray<string>,
@@ -57,8 +87,10 @@ export const encodeString = <IE = never, Done = unknown>(): Channel.Channel<
   )
 
 /**
- * @since 4.0.0
+ * Creates a channel that encodes chunks of values as UTF-8 NDJSON bytes.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encode = <IE = never, Done = unknown>(): Channel.Channel<
   Arr.NonEmptyReadonlyArray<Uint8Array>,
@@ -70,8 +102,13 @@ export const encode = <IE = never, Done = unknown>(): Channel.Channel<
 > => Channel.map(encodeString(), Arr.map((_) => encoder.encode(_)))
 
 /**
- * @since 4.0.0
+ * Creates an NDJSON byte encoder channel for values of a schema.
+ *
+ * Values are first encoded with the schema and then written as UTF-8
+ * newline-delimited JSON.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encodeSchema = <S extends Schema.Top>(
   schema: S
@@ -87,8 +124,13 @@ export const encodeSchema = <S extends Schema.Top>(
 > => Channel.pipeTo(ChannelSchema.encode(schema)(), encode())
 
 /**
- * @since 4.0.0
+ * Creates an NDJSON string encoder channel for values of a schema.
+ *
+ * Values are first encoded with the schema and then written as newline-delimited
+ * JSON strings.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const encodeSchemaString = <S extends Schema.Top>(
   schema: S
@@ -104,8 +146,13 @@ export const encodeSchemaString = <S extends Schema.Top>(
 > => Channel.pipeTo(ChannelSchema.encode(schema)(), encodeString())
 
 /**
- * @since 4.0.0
+ * Creates a channel that parses NDJSON string chunks into values.
+ *
+ * Lines may span input chunks. Set `ignoreEmptyLines` to skip blank lines before
+ * calling `JSON.parse`; otherwise blank lines are parsed and fail as invalid JSON.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decodeString = <IE = never, Done = unknown>(options?: {
   readonly ignoreEmptyLines?: boolean | undefined
@@ -132,8 +179,13 @@ export const decodeString = <IE = never, Done = unknown>(options?: {
 }
 
 /**
- * @since 4.0.0
+ * Creates a channel that decodes UTF-8 byte chunks and parses them as NDJSON.
+ *
+ * Lines may span input chunks, and `ignoreEmptyLines` controls whether blank
+ * lines are skipped before JSON parsing.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decode = <IE = never, Done = unknown>(options?: {
   readonly ignoreEmptyLines?: boolean | undefined
@@ -149,8 +201,13 @@ export const decode = <IE = never, Done = unknown>(options?: {
 }
 
 /**
- * @since 4.0.0
+ * Creates an NDJSON byte decoder channel for values of a schema.
+ *
+ * The channel decodes UTF-8 bytes, parses each NDJSON line, and then decodes
+ * each parsed value with the schema.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decodeSchema = <S extends Schema.Top>(
   schema: S
@@ -168,8 +225,13 @@ export const decodeSchema = <S extends Schema.Top>(
 > => Channel.pipeTo(decode(options), ChannelSchema.decodeUnknown(schema)())
 
 /**
- * @since 4.0.0
+ * Creates an NDJSON string decoder channel for values of a schema.
+ *
+ * The channel parses each line as JSON and then decodes each parsed value with
+ * the schema.
+ *
  * @category constructors
+ * @since 4.0.0
  */
 export const decodeSchemaString = <S extends Schema.Top>(
   schema: S
@@ -187,13 +249,23 @@ export const decodeSchemaString = <S extends Schema.Top>(
 > => Channel.pipeTo(decodeString(options), ChannelSchema.decodeUnknown(schema)())
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional byte channel with NDJSON encoding and decoding.
+ *
+ * Outgoing values are written as UTF-8 NDJSON bytes, and incoming bytes are
+ * parsed as NDJSON values.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplex: {
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with NDJSON encoding and decoding.
+   *
+   * Outgoing values are written as UTF-8 NDJSON bytes, and incoming bytes are
+   * parsed as NDJSON values.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     options?: {
@@ -219,8 +291,13 @@ export const duplex: {
     R
   >
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with NDJSON encoding and decoding.
+   *
+   * Outgoing values are written as UTF-8 NDJSON bytes, and incoming bytes are
+   * parsed as NDJSON values.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <R, IE, OE, OutDone, InDone>(
     self: Channel.Channel<
@@ -272,13 +349,23 @@ export const duplex: {
   ))
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional string channel with NDJSON encoding and decoding.
+ *
+ * Outgoing values are written as NDJSON strings, and incoming strings are parsed
+ * as NDJSON values.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplexString: {
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional string channel with NDJSON encoding and decoding.
+   *
+   * Outgoing values are written as NDJSON strings, and incoming strings are parsed
+   * as NDJSON values.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   (
     options?: {
@@ -304,8 +391,13 @@ export const duplexString: {
     R
   >
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional string channel with NDJSON encoding and decoding.
+   *
+   * Outgoing values are written as NDJSON strings, and incoming strings are parsed
+   * as NDJSON values.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <R, IE, OE, OutDone, InDone>(
     self: Channel.Channel<
@@ -357,13 +449,25 @@ export const duplexString: {
   ))
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional byte channel with schema-aware NDJSON encoding and
+ * decoding.
+ *
+ * Values sent to the wrapped channel are encoded with `inputSchema`; bytes
+ * received from it are parsed as NDJSON and decoded with `outputSchema`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplexSchema: {
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with schema-aware NDJSON encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema`; bytes
+   * received from it are parsed as NDJSON and decoded with `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <In extends Schema.Top, Out extends Schema.Top>(
     options: {
@@ -391,8 +495,14 @@ export const duplexSchema: {
     R | In["EncodingServices"] | Out["DecodingServices"]
   >
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional byte channel with schema-aware NDJSON encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema`; bytes
+   * received from it are parsed as NDJSON and decoded with `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Out extends Schema.Top, In extends Schema.Top, OutErr, OutDone, InErr, InDone, R>(
     self: Channel.Channel<
@@ -444,13 +554,25 @@ export const duplexSchema: {
 > => ChannelSchema.duplexUnknown(duplex(self, options), options))
 
 /**
- * @since 4.0.0
+ * Wraps a bidirectional string channel with schema-aware NDJSON encoding and
+ * decoding.
+ *
+ * Values sent to the wrapped channel are encoded with `inputSchema`; strings
+ * received from it are parsed as NDJSON and decoded with `outputSchema`.
+ *
  * @category combinators
+ * @since 4.0.0
  */
 export const duplexSchemaString: {
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional string channel with schema-aware NDJSON encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema`; strings
+   * received from it are parsed as NDJSON and decoded with `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <In extends Schema.Top, Out extends Schema.Top>(
     options: {
@@ -478,8 +600,14 @@ export const duplexSchemaString: {
     R | In["EncodingServices"] | Out["DecodingServices"]
   >
   /**
-   * @since 4.0.0
+   * Wraps a bidirectional string channel with schema-aware NDJSON encoding and
+   * decoding.
+   *
+   * Values sent to the wrapped channel are encoded with `inputSchema`; strings
+   * received from it are parsed as NDJSON and decoded with `outputSchema`.
+   *
    * @category combinators
+   * @since 4.0.0
    */
   <Out extends Schema.Top, In extends Schema.Top, OutErr, OutDone, InErr, InDone, R>(
     self: Channel.Channel<