/**
 * Encodes and decodes a single JSON array as a stream of its elements.
 *
 * **Details**
 *
 * Use `JsonArray` when a large response or file is one JSON document, such as
 * `[...]` or `{"items":[...],"total":n}`, and its elements should be processed
 * without buffering the whole document. Use `Ndjson` when the producer writes
 * one JSON value per line. This module is unrelated to `Schema.JsonArray`, the
 * type of a JSON array value.
 *
 * Decoders stream the elements of one array, the root array by default or the
 * array selected by an RFC 6901 JSON Pointer. Each element is buffered only
 * until it is complete and then parsed with `JSON.parse`. The rest of the
 * document is validated and discarded. Encoders write a stream of values as
 * one JSON array.
 *
 * **Example** (Streaming the items of a large HTTP response)
 *
 * ```ts
 * import { Effect, Schema, Stream } from "effect"
 * import { JsonArray } from "effect/encoding"
 * import { HttpClient, HttpClientResponse } from "effect/http"
 *
 * const User = Schema.Struct({ id: Schema.Number, name: Schema.String })
 *
 * // The response body is {"data":[{"id":1,"name":"Alice"},...],"total":...}
 * const program = HttpClientResponse.stream(HttpClient.get("https://example.com/users")).pipe(
 *   Stream.pipeThroughChannel(JsonArray.decodeSchema(User)({ pointer: "/data" })),
 *   Stream.runForEach((user) => Effect.log(user.name))
 * )
 * ```
 *
 * @stability unstable
 * @since 4.0.6
 */
import * as Arr from "../Array.ts"
import * as Cause from "../Cause.ts"
import * as Channel from "../Channel.ts"
import * as ChannelSchema from "../ChannelSchema.ts"
import * as Data from "../Data.ts"
import * as Effect from "../Effect.ts"
import * as JsonPointer from "../JsonPointer.ts"
import * as Predicate from "../Predicate.ts"
import * as Pull from "../Pull.ts"
import type * as Schema from "../Schema.ts"

const JsonArrayErrorTypeId = "~effect/encoding/JsonArray/JsonArrayError"

const encoder = new TextEncoder()

/**
 * Error raised when JSON array encoding or decoding fails.
 *
 * **Details**
 *
 * - `Syntax`: the input is not valid JSON, including an empty input or
 *   content after the document.
 * - `Limit`: a value exceeds `maxDepth` or `maxElementSize`, whether it is an
 *   element, a key, or a value outside the selected array.
 * - `Pointer`: the pointer target is missing or not an array, a value along the
 *   pointer is not an object or array, or an object along the pointer repeats
 *   the key that the pointer follows.
 * - `Encode`: a value has no JSON representation.
 *
 * Decoding errors set `offset`, a zero-based offset in UTF-16 code units into
 * the decoded text after any leading BOM. When a value is invalid or exceeds a
 * limit, the offset is the start of that value. `Encode` errors have no
 * offset. When `JSON.parse` or `JSON.stringify` throws, `Syntax` and `Encode`
 * errors retain the original thrown value as `cause`.
 *
 * @stability unstable
 * @category errors
 * @since 4.0.6
 */
export class JsonArrayError extends Data.TaggedError("JsonArrayError")<{
  readonly kind: "Syntax" | "Limit" | "Pointer" | "Encode"
  readonly message: string
  readonly offset?: number | undefined
  readonly cause?: unknown
}> {
  /**
   * Marks this value as a JSON array encoding or decoding error for runtime
   * guards.
   *
   * @stability unstable
   * @since 4.0.6
   */
  readonly [JsonArrayErrorTypeId] = JsonArrayErrorTypeId
}

/**
 * Checks whether a value is a `JsonArrayError`.
 *
 * @stability unstable
 * @category guards
 * @since 4.0.6
 */
export const isJsonArrayError = (u: unknown): u is JsonArrayError => Predicate.hasProperty(u, JsonArrayErrorTypeId)

/**
 * JSON array decoding options.
 *
 * **Details**
 *
 * - `pointer`: an RFC 6901 JSON Pointer to the array to stream, such as
 *   `"/data"`. Defaults to `""`, the root. Tokens select object members by
 *   key and array elements by index.
 * - `maxDepth`: the maximum nesting of arrays and objects in one value, where
 *   an array or object element has depth 1. Defaults to 1000.
 * - `maxElementSize`: the maximum length of one value in UTF-16 code units.
 *   Defaults to 16 MiB; `Infinity` disables the limit.
 *
 * Both limits also apply to values outside the selected array, which are
 * buffered and validated before being discarded. Invalid options throw when
 * the channel is created.
 *
 * @stability unstable
 * @category configuration
 * @since 4.0.6
 */
export interface DecodeOptions {
  readonly pointer?: string | undefined
  readonly maxDepth?: number | undefined
  readonly maxElementSize?: number | undefined
}

interface Config {
  readonly tokens: ReadonlyArray<string>
  // The array index selected by each token, or -1 when it is not an index.
  readonly indices: ReadonlyArray<number>
  readonly maxDepth: number
  readonly maxElementSize: number
}

const makeConfig = (options: DecodeOptions | undefined): Config => {
  const pointer = options?.pointer ?? ""
  if (pointer !== "" && (!pointer.startsWith("/") || /~(?:[^01]|$)/.test(pointer))) {
    throw new Error(`JsonArray: pointer must be an RFC 6901 JSON Pointer, got ${JSON.stringify(pointer)}`)
  }
  const maxDepth = options?.maxDepth ?? 1000
  if (!(Number.isInteger(maxDepth) && maxDepth >= 0)) {
    throw new Error(`JsonArray: maxDepth must be a non-negative integer, got ${maxDepth}`)
  }
  const maxElementSize = options?.maxElementSize ?? 16 * 1024 * 1024
  if (!(maxElementSize >= 1)) {
    throw new Error(`JsonArray: maxElementSize must be at least 1, got ${maxElementSize}`)
  }
  const tokens = pointer === "" ? [] : pointer.slice(1).split("/").map(JsonPointer.unescapeToken)
  return {
    tokens,
    indices: tokens.map((token) => /^(?:0|[1-9]\d*)$/.test(token) ? Number(token) : -1),
    maxDepth,
    maxElementSize
  };
}

const TAB = 9
const LF = 10
const CR = 13
const SPACE = 32
const QUOTE = 34
const COMMA = 44
const COLON = 58
const LBRACKET = 91
const BACKSLASH = 92
const RBRACKET = 93
const LBRACE = 123
const RBRACE = 125

const isWhitespace = (c: number): boolean => c === SPACE || c === LF || c === CR || c === TAB

const indexOf = (text: string, search: string, i: number): number => {
  const index = text.indexOf(search, i)
  return index === -1 ? text.length : index
}

const isValueStart = (c: number): boolean =>
  c === QUOTE || c === LBRACKET || c === LBRACE || c === 45 || (c >= 48 && c <= 57) || c === 102 || c === 110 ||
  c === 116

// The scanner walks the containers along the pointer and the selected array.
// Every other value is captured whole and parsed with `JSON.parse`: elements
// are emitted, keys are matched against the pointer, and the rest is
// discarded.

// Structural states.
const VALUE = 0 // the value at the current pointer prefix
const OBJECT_START = 1 // after `{`: a key or `}`
const OBJECT_KEY = 2 // after `,`: a key
const OBJECT_COLON = 3 // after a key: `:`
const OBJECT_VALUE = 4 // after `:` for a key the pointer does not follow
const OBJECT_NEXT = 5 // after a member: `,` or `}`
const ARRAY_START = 6 // after `[`: a value or `]`
const ARRAY_VALUE = 7 // after `,`: a value
const ARRAY_NEXT = 8 // after an element: `,` or `]`
const END = 9 // after the document

// Capture modes.
const NONE = 0
const SKIP = 1
const ELEMENT = 2
const KEY = 3

interface Frame {
  readonly object: boolean
  // Whether this is the selected array.
  readonly target: boolean
  // Whether the pointer token for this container has been found.
  found: boolean
  index: number
}

class Scanner {
  readonly config: Config
  state = VALUE
  readonly frames: Array<Frame> = []
  key = ""
  started = false
  // The offset of the start of the current chunk.
  base = 0

  // The value being captured, which may span chunks.
  capture = NONE
  start = 0
  buffer = ""
  scalar = false
  depth = 0
  inString = false
  escape = false

  // Cached quote and backslash positions; the chunk length means not found.
  quote = -1
  backslash = -1
  // Absolute end of a batch that failed to parse. The precise scan handles
  // text before it, so the batch is not rescanned for every element.
  slow = 0

  constructor(config: Config) {
    this.config = config
  }

  fail(kind: "Syntax" | "Limit" | "Pointer", message: string, offset: number, cause?: unknown): JsonArrayError {
    return new JsonArrayError({ kind, message, offset, cause })
  }

  pointerPrefix(length: number, ...rest: Array<string>): string {
    return JSON.stringify(
      this.config.tokens.slice(0, length).concat(rest).map((token) => "/" + JsonPointer.escapeToken(token)).join("")
    )
  }

  // Names the value being captured, for limit errors.
  subject(): string {
    if (this.capture === ELEMENT) return "Element"
    const depth = this.frames.length - 1
    if (this.capture === KEY) return `Key in ${this.pointerPrefix(depth)}`
    const frame = this.frames[depth]
    const token = frame.object ? this.key : String(frame.index - 1)
    return `Value outside the selected array at ${this.pointerPrefix(depth, token)}`
  }

  feed(text: string, out: Array<unknown>): void {
    if (!this.started && text.length > 0) {
      this.started = true
      if (text.charCodeAt(0) === 0xFEFF) text = text.slice(1)
    }
    this.quote = -1
    this.backslash = -1
    let i = this.capture === NONE ? 0 : this.scan(text, 0, out)
    while (i < text.length) {
      const c = text.charCodeAt(i)
      i = isWhitespace(c) ? i + 1 : this.step(text, i, c, out)
    }
    if (this.capture !== NONE) {
      this.buffer += text.slice(Math.max(this.start - this.base, 0))
      this.checkSize(this.buffer.length)
    }
    this.base += text.length
  }

  end(): void {
    if (this.state !== END || this.capture !== NONE) {
      throw this.fail("Syntax", "Unexpected end of input", this.base)
    }
  }

  // Handles one structural character and returns the next index.
  step(text: string, i: number, c: number, out: Array<unknown>): number {
    const frame = this.frames[this.frames.length - 1]
    switch (this.state) {
      case VALUE: {
        const target = this.frames.length === this.config.tokens.length
        if (c === LBRACKET || (c === LBRACE && !target)) {
          this.frames.push({ object: c === LBRACE, target, found: false, index: 0 })
          this.state = c === LBRACE ? OBJECT_START : ARRAY_START
          return i + 1
        }
        if (isValueStart(c)) {
          const expected = target ? "an array" : "an object or array"
          throw this.fail(
            "Pointer",
            `Expected ${expected} at ${this.pointerPrefix(this.frames.length)}`,
            this.base + i
          )
        }
        break
      }
      case OBJECT_START:
      case OBJECT_KEY: {
        if (c === QUOTE) {
          this.state = OBJECT_COLON
          return this.begin(KEY, text, i, out)
        }
        if (c === RBRACE && this.state === OBJECT_START) return this.close(i)
        break
      }
      case OBJECT_COLON: {
        if (c !== COLON) break
        if (this.key === this.config.tokens[this.frames.length - 1]) {
          if (frame.found) {
            throw this.fail("Pointer", `Duplicate key ${JSON.stringify(this.key)} along the pointer`, this.base + i)
          }
          frame.found = true
          this.state = VALUE
        } else {
          this.state = OBJECT_VALUE
        }
        return i + 1
      }
      case OBJECT_VALUE: {
        if (!isValueStart(c)) break
        this.state = OBJECT_NEXT
        return this.begin(SKIP, text, i, out)
      }
      case OBJECT_NEXT:
      case ARRAY_NEXT: {
        if (c === COMMA) {
          this.state = this.state === OBJECT_NEXT ? OBJECT_KEY : ARRAY_VALUE
          return i + 1
        }
        if (c === (this.state === OBJECT_NEXT ? RBRACE : RBRACKET)) return this.close(i)
        break
      }
      case ARRAY_START:
      case ARRAY_VALUE: {
        if (c === RBRACKET && this.state === ARRAY_START) return this.close(i)
        if (!isValueStart(c)) break
        if (frame.target) {
          const next = this.scanElements(text, i, out)
          if (next > i) return next
          this.state = ARRAY_NEXT
          return this.begin(ELEMENT, text, i, out)
        }
        this.state = ARRAY_NEXT
        if (frame.index++ === this.config.indices[this.frames.length - 1]) {
          frame.found = true
          this.state = VALUE
          return i
        }
        return this.begin(SKIP, text, i, out)
      }
    }
    throw this.fail(
      "Syntax",
      this.state === END
        ? "Unexpected content after the document"
        : `Unexpected character ${JSON.stringify(String.fromCharCode(c))}`,
      this.base + i
    )
  }

  close(i: number): number {
    const frame = this.frames.pop()!
    if (!frame.target && !frame.found) {
      throw this.fail("Pointer", `No value at ${this.pointerPrefix(this.frames.length + 1)}`, this.base + i)
    }
    const parent = this.frames[this.frames.length - 1]
    this.state = parent === undefined ? END : parent.object ? OBJECT_NEXT : ARRAY_NEXT
    return i + 1
  }

  // Starts capturing the value that begins at `i`.
  begin(mode: number, text: string, i: number, out: Array<unknown>): number {
    const c = text.charCodeAt(i)
    this.capture = mode
    this.start = this.base + i
    this.inString = c === QUOTE
    this.escape = false
    this.depth = c === LBRACKET || c === LBRACE ? 1 : 0
    this.scalar = !this.inString && this.depth === 0
    if (this.depth > this.config.maxDepth) this.failDepth()
    return this.scan(text, i + 1, out)
  }

  // Continues the captured value from `i`, completing it if it ends in this
  // chunk. Returns the index after the value, or the chunk length.
  scan(text: string, i: number, out: Array<unknown>): number {
    const end = this.scalar ? this.scanScalar(text, i) : this.scanNested(text, i)
    if (end === -1) return text.length
    const source = this.buffer + text.slice(Math.max(this.start - this.base, 0), end)
    this.checkSize(source.length)
    const mode = this.capture
    this.capture = NONE
    this.buffer = ""
    let value: unknown
    try {
      value = JSON.parse(source)
    } catch (cause) {
      throw this.fail("Syntax", "Invalid JSON value", this.start, cause)
    }
    if (mode === ELEMENT) out.push(value)
    else if (mode === KEY) this.key = value as string
    return end
  }

  // A scalar ends at the first delimiter, which `JSON.parse` then validates.
  scanScalar(text: string, i: number): number {
    for (; i < text.length; i++) {
      const c = text.charCodeAt(i)
      if (isWhitespace(c) || c === COMMA || c === RBRACKET || c === RBRACE) return i
    }
    return -1
  }

  // Tracks only string, escape and nesting state; `JSON.parse` validates the
  // rest. Returns the index after the value, or -1.
  scanNested(text: string, i: number): number {
    if (this.inString) {
      i = this.scanString(text, i, this.escape)
      if (i === -1) return -1
      this.inString = false
      if (this.depth === 0) return i
    }
    let depth = this.depth
    while (i < text.length) {
      const c = text.charCodeAt(i++)
      if (c === QUOTE) {
        i = this.scanString(text, i, false)
        if (i === -1) {
          this.inString = true
          break
        }
      } else if (c === LBRACKET || c === LBRACE) {
        if (++depth > this.config.maxDepth) this.failDepth()
      } else if ((c === RBRACKET || c === RBRACE) && --depth === 0) {
        this.depth = 0
        return i
      }
    }
    this.depth = depth
    return -1
  }

  // Scans string contents from `i`; returns the index after the closing quote,
  // or -1 if the string continues into the next chunk, recording `escape` for
  // `scanNested` to resume with.
  scanString(text: string, i: number, escape: boolean): number {
    let plain = 0
    while (i < text.length) {
      const c = text.charCodeAt(i++)
      if (escape) {
        escape = false
      } else if (c === BACKSLASH) {
        escape = true
      } else if (c === QUOTE) {
        return i
      } else if (++plain === 16) {
        // A long string: jump to the next quote or backslash.
        if (this.quote < i) this.quote = indexOf(text, "\"", i)
        if (this.backslash < i) this.backslash = indexOf(text, "\\", i)
        i = Math.min(this.quote, this.backslash)
        plain = 0
      }
    }
    this.escape = escape
    return -1
  }

  // Parses the elements from `i` up to the last comma or closing bracket at
  // the array's level with one `JSON.parse`. Wrapped in brackets, that text
  // parses only when every element and separator in it is valid. Returns `i`
  // to leave anything else, including errors, to the precise scan.
  scanElements(text: string, i: number, out: Array<unknown>): number {
    if (this.base + i < this.slow) return i
    const { maxDepth, maxElementSize } = this.config
    let cut = -1
    let start = i
    let close = false
    let depth = 0
    let j = i
    while (j < text.length) {
      const c = text.charCodeAt(j++)
      if (c === QUOTE) {
        j = this.scanString(text, j, false)
        if (j === -1) break
      } else if (c === LBRACKET || c === LBRACE) {
        if (++depth > maxDepth) break
      } else if (c === RBRACKET || c === RBRACE) {
        if (depth-- > 0) continue
        // Including surrounding whitespace makes this a conservative size check.
        if (c === RBRACKET && j - 1 - start <= maxElementSize) {
          cut = j - 1
          close = true
        }
        break
      } else if (c === COMMA && depth === 0) {
        if (j - 1 - start > maxElementSize) break
        cut = j - 1
        start = j
      }
    }
    let values: Array<unknown> | undefined
    if (cut !== -1) {
      try {
        values = JSON.parse("[" + text.slice(i, cut) + "]")
      } catch {
        this.slow = this.base + cut
      }
    }
    // Rescanning may start before the cached matches, so discard them.
    this.quote = -1
    this.backslash = -1
    if (values === undefined) return i
    for (let k = 0; k < values.length; k++) out.push(values[k])
    if (close) return this.close(cut)
    this.state = ARRAY_VALUE
    return cut + 1
  }

  checkSize(size: number): void {
    if (size > this.config.maxElementSize) {
      throw this.fail("Limit", `${this.subject()} exceeds maxElementSize of ${this.config.maxElementSize}`, this.start)
    }
  }

  failDepth(): never {
    throw this.fail("Limit", `${this.subject()} exceeds maxDepth of ${this.config.maxDepth}`, this.start)
  }
}

/**
 * Creates a channel that parses the text of one JSON document and emits the
 * elements of one of its arrays.
 *
 * **When to use**
 *
 * Use when a large JSON array, or an object that contains one, arrives as
 * string chunks and its elements should be processed as they arrive.
 *
 * **Details**
 *
 * Each output chunk holds the elements completed by one input chunk. Elements
 * may span input chunks and are buffered only until they are complete. A
 * leading BOM is stripped.
 *
 * **Gotchas**
 *
 * - The document is validated as it streams, so elements from earlier
 *   successfully processed input chunks may already have been emitted when a
 *   later error fails the channel. Elements accumulated in the failing chunk
 *   are not emitted. A failure in content after the selected array signals
 *   that the document was invalid, but cannot guard against using earlier
 *   output.
 * - The pointer follows the first occurrence of a key, where `JSON.parse`
 *   keeps the last. A repeated followed key fails with a `Pointer` error, as
 *   does a first occurrence that is not an object or array where the pointer
 *   needs one. When the repeat comes after the selected array, elements from
 *   earlier successfully processed chunks may already have been emitted.
 * - A root that is not an array fails with a `Pointer` error unless the
 *   pointer selects an array inside it.
 *
 * **Example** (Streaming an array inside an envelope)
 *
 * ```ts import.meta.vitest
 * import { Effect, Stream } from "effect"
 * import { JsonArray } from "effect/encoding"
 *
 * const items = Stream.make("{\"total\":2,\"items\":[{\"id\":1},{\"i", "d\":2}]}").pipe(
 *   Stream.pipeThroughChannel(JsonArray.decodeString({ pointer: "/items" })),
 *   Stream.runCollect
 * )
 * await Effect.runPromise(items) // => [{ id: 1 }, { id: 2 }]
 * ```
 *
 * @see decode
 * @see decodeSchemaString
 * @stability unstable
 * @category decoding
 * @since 4.0.6
 */
export const decodeString = <IE = never, Done = unknown>(options?: DecodeOptions): Channel.Channel<
  Arr.NonEmptyReadonlyArray<unknown>,
  IE | JsonArrayError,
  Done,
  Arr.NonEmptyReadonlyArray<string>,
  IE,
  Done
> => {
  const config = makeConfig(options)
  return Channel.fromTransform((upstream, _scope) =>
    Effect.sync(() => {
      const scanner = new Scanner(config)
      let done: Pull.Pull<never, never, Done> | undefined
      type Out = Pull.Pull<Arr.NonEmptyReadonlyArray<unknown>, IE | JsonArrayError, Done>

      const emit = (run: (out: Array<unknown>) => void): Out => {
        const out: Array<unknown> = []
        try {
          run(out)
        } catch (error) {
          if (isJsonArrayError(error)) return Effect.fail(error)
          throw error
        }
        return Arr.isArrayNonEmpty(out) ? Effect.succeed(out) : pull
      }

      const pull: Out = Effect.suspend(() => {
        if (done !== undefined) return done
        return Pull.matchEffect(upstream, {
          onSuccess: (texts) =>
            emit((out) => {
              for (const text of texts) scanner.feed(text, out)
            }),
          onFailure: Effect.failCause,
          onDone: (value) => {
            done = Cause.done(value)
            return emit(() => scanner.end())
          }
        })
      })
      return pull
    })
  )
}

/**
 * Creates a channel that parses UTF-8 bytes of one JSON document and emits the
 * elements of one of its arrays.
 *
 * **Details**
 *
 * Multi-byte characters may span input chunks, and invalid UTF-8 is replaced
 * with U+FFFD.
 *
 * @see decodeString
 * @stability unstable
 * @category decoding
 * @since 4.0.6
 */
export const decode = <IE = never, Done = unknown>(options?: DecodeOptions): Channel.Channel<
  Arr.NonEmptyReadonlyArray<unknown>,
  IE | JsonArrayError,
  Done,
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  IE,
  Done
> => Channel.pipeTo(Channel.decodeText<IE, Done>("utf-8", { ignoreBOM: true }), decodeString(options))

/**
 * Creates a channel that parses the text of one JSON document and decodes the
 * elements of one of its arrays with a schema.
 *
 * @see decodeString
 * @stability unstable
 * @category decoding
 * @since 4.0.6
 */
export const decodeSchemaString = <S extends Schema.Constraint>(
  schema: S
) =>
<IE = never, Done = unknown>(options?: DecodeOptions): Channel.Channel<
  Arr.NonEmptyReadonlyArray<S["Type"]>,
  Schema.SchemaError | JsonArrayError | IE,
  Done,
  Arr.NonEmptyReadonlyArray<string>,
  IE,
  Done,
  S["DecodingServices"]
> => Channel.pipeTo(decodeString(options), ChannelSchema.decodeUnknown(schema)())

/**
 * Creates a channel that parses UTF-8 bytes of one JSON document and decodes
 * the elements of one of its arrays with a schema.
 *
 * @see decodeSchemaString
 * @stability unstable
 * @category decoding
 * @since 4.0.6
 */
export const decodeSchema = <S extends Schema.Constraint>(
  schema: S
) =>
<IE = never, Done = unknown>(options?: DecodeOptions): Channel.Channel<
  Arr.NonEmptyReadonlyArray<S["Type"]>,
  Schema.SchemaError | JsonArrayError | IE,
  Done,
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  IE,
  Done,
  S["DecodingServices"]
> => Channel.pipeTo(decode(options), ChannelSchema.decodeUnknown(schema)())

const stringify = (value: unknown): string => {
  let output: string | undefined
  try {
    output = JSON.stringify(value)
  } catch (cause) {
    throw new JsonArrayError({ kind: "Encode", message: cause instanceof Error ? cause.message : String(cause), cause })
  }
  if (output === undefined) {
    throw new JsonArrayError({ kind: "Encode", message: `Value of type ${typeof value} cannot be represented as JSON` })
  }
  return output
}

/**
 * Creates a channel that writes a stream of values as the text of one JSON
 * array.
 *
 * **Details**
 *
 * Each input chunk produces one string. An empty stream produces `"[]"`.
 * Values are written with `JSON.stringify`.
 *
 * **Gotchas**
 *
 * A value that `JSON.stringify` cannot write, such as `undefined`, a function
 * or a `bigint`, fails with an `Encode` error after the preceding text has
 * been emitted.
 *
 * **Example** (Writing values as a JSON array)
 *
 * ```ts import.meta.vitest
 * import { Effect, Stream } from "effect"
 * import { JsonArray } from "effect/encoding"
 *
 * const json = Stream.make({ id: 1 }, { id: 2 }).pipe(
 *   Stream.pipeThroughChannel(JsonArray.encodeString()),
 *   Stream.mkString
 * )
 * await Effect.runPromise(json) // => '[{"id":1},{"id":2}]'
 * ```
 *
 * @see encode
 * @see encodeSchemaString
 * @stability unstable
 * @category encoding
 * @since 4.0.6
 */
export const encodeString = <IE = never, Done = unknown>(): Channel.Channel<
  Arr.NonEmptyReadonlyArray<string>,
  IE | JsonArrayError,
  Done,
  Arr.NonEmptyReadonlyArray<unknown>,
  IE,
  Done
> =>
  Channel.fromTransform((upstream, _scope) =>
    Effect.sync(() => {
      let started = false
      let done: Pull.Pull<never, never, Done> | undefined
      type Out = Pull.Pull<Arr.NonEmptyReadonlyArray<string>, IE | JsonArrayError, Done>
      const pull: Out = Effect.suspend((): Out => {
        if (done !== undefined) return done
        return Pull.matchEffect(upstream, {
          onSuccess: (values): Out => {
            let text: string
            try {
              text = (started ? "," : "[") + values.map(stringify).join(",")
            } catch (error) {
              if (isJsonArrayError(error)) return Effect.fail(error)
              throw error
            }
            started = true
            return Effect.succeed(Arr.of(text))
          },
          onFailure: Effect.failCause,
          onDone: (value) => {
            done = Cause.done(value)
            return Effect.succeed(Arr.of(started ? "]" : "[]"))
          }
        })
      })
      return pull
    })
  )

/**
 * Creates a channel that writes a stream of values as UTF-8 bytes of one JSON
 * array.
 *
 * @see encodeString
 * @stability unstable
 * @category encoding
 * @since 4.0.6
 */
export const encode = <IE = never, Done = unknown>(): Channel.Channel<
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  IE | JsonArrayError,
  Done,
  Arr.NonEmptyReadonlyArray<unknown>,
  IE,
  Done
> => Channel.map(encodeString(), Arr.map((text) => encoder.encode(text)))

/**
 * Creates a channel that encodes values with a schema and writes them as the
 * text of one JSON array.
 *
 * @see encodeString
 * @stability unstable
 * @category encoding
 * @since 4.0.6
 */
export const encodeSchemaString = <S extends Schema.Constraint>(
  schema: S
) =>
<IE = never, Done = unknown>(): Channel.Channel<
  Arr.NonEmptyReadonlyArray<string>,
  JsonArrayError | Schema.SchemaError | IE,
  Done,
  Arr.NonEmptyReadonlyArray<S["Type"]>,
  IE,
  Done,
  S["EncodingServices"]
> => Channel.pipeTo(ChannelSchema.encode(schema)(), encodeString())

/**
 * Creates a channel that encodes values with a schema and writes them as UTF-8
 * bytes of one JSON array.
 *
 * @see encodeSchemaString
 * @stability unstable
 * @category encoding
 * @since 4.0.6
 */
export const encodeSchema = <S extends Schema.Constraint>(
  schema: S
) =>
<IE = never, Done = unknown>(): Channel.Channel<
  Arr.NonEmptyReadonlyArray<Uint8Array>,
  JsonArrayError | Schema.SchemaError | IE,
  Done,
  Arr.NonEmptyReadonlyArray<S["Type"]>,
  IE,
  Done,
  S["EncodingServices"]
> => Channel.pipeTo(ChannelSchema.encode(schema)(), encode())