refactor!: set up initial public API

mod.ts only publicly exports JsonSequenceDecoderStream. The two
individual Transformer-creating functions could be exported publicly
later, but I'm keeping it minimal for now.

The utility functions in mod_test.ts are now in a separate
_test_utils.ts module.

Author: h4l

_test_utils.ts

@@ -0,0 +1,34 @@
+import { assert, assertEquals } from "./dev_deps.ts";
+import { JSON_SEQ_END, JSON_SEQ_START } from "./mod.ts";
+
+export function chunkify(str: string, size: number): string[] {
+  assert(size > 0);
+  const chunks: string[] = [];
+  for (let i = 0; i < str.length; i += size) {
+    chunks.push(str.substring(i, Math.min(str.length, i + size)));
+  }
+  return chunks;
+}
+
+export function enlargen(chunk: string, length: number): string {
+  return chunk.repeat(Math.ceil(length / chunk.length)).substring(0, length);
+}
+
+export function jsonSeqChunk<Content extends string = string>(
+  content: Content,
+): `${typeof JSON_SEQ_START}${Content}${typeof JSON_SEQ_END}` {
+  return `${JSON_SEQ_START}${content}${JSON_SEQ_END}`;
+}
+
+export async function assertStreamContainsChunks<T>(
+  stream: ReadableStream<T>,
+  chunks: ReadonlyArray<T>,
+): Promise<void> {
+  const reader = stream.getReader();
+  for (const chunk of chunks) {
+    const result = await reader.read();
+    assertEquals(result, { done: false, value: chunk });
+  }
+  const result = await reader.read();
+  assertEquals(result, { done: true, value: undefined });
+}

_test_utils_test.ts

@@ -0,0 +1,18 @@
+import { assertEquals } from "./dev_deps.ts";
+import { chunkify, enlargen } from "./_test_utils.ts";
+
+Deno.test("chunkify", () => {
+  assertEquals(chunkify("", 1), []);
+  assertEquals(chunkify("", 10), []);
+  assertEquals(chunkify("foo", 10), ["foo"]);
+  assertEquals(chunkify("foo", 1), ["f", "o", "o"]);
+  assertEquals(chunkify("foo", 2), ["fo", "o"]);
+});
+
+Deno.test("enlargen", () => {
+  assertEquals(enlargen("a", 3), "aaa");
+  assertEquals(enlargen("abc", 5), "abcab");
+  assertEquals(enlargen("abc", 1), "a");
+  assertEquals(enlargen("abc", 2), "ab");
+  assertEquals(enlargen("abc", 3), "abc");
+});

mod.ts

@@ -13,10 +13,14 @@ enum State {
   BEFORE_CHUNK_END,
 }
 
-export function jsonSeqDelimiterTransformer(options?: {
+export interface _JsonSeqDelimiterTransformerOptions {
   strict?: boolean;
-}): Transformer<string, string> {
-  const strict = options?.strict === undefined ? true : options?.strict;
+}
+
+export function _jsonSeqDelimiterTransformer(
+  options?: _JsonSeqDelimiterTransformerOptions,
+): Transformer<string, string> {
+  const strict = options?.strict === undefined ? false : options?.strict;
   let state: State = State.BEFORE_CHUNK_START;
   let unDelimitedChunks: string[] = [];
 
@@ -29,7 +33,7 @@ export function jsonSeqDelimiterTransformer(options?: {
             throw new Error(
               `leading content before chunk start: ${
                 start < 0 ? chunk : chunk.substring(0, start)
-              }`
+              }`,
             );
           }
           if (start < 0) {
@@ -63,25 +67,52 @@ export function jsonSeqDelimiterTransformer(options?: {
   };
 }
 
-export function stringToJSONTransformer(): Transformer<string, unknown> {
+export function _stringToJSONTransformer(): Transformer<string, unknown> {
   return {
     transform(chunk, controller) {
       controller.enqueue(JSON.parse(chunk));
     },
   };
 }
 
+export interface JsonSequenceDecoderStreamOptions {
+  /** If `true`, raise errors instead of recovering when parsing malformed
+   * streams.
+   *
+   * The default is `false`, as the json-seq spec (RFC 7464) encourages decoders
+   * to automatically handle stream errors, such as truncated JSON texts.
+   *
+   * * When `true`, the decoder behaves as if the stream format **MUST** exactly
+   * match the [JSON Text Sequence Encoding] format.
+   * * When `false` the decoder follows the more permissive
+   *   [JSON Text Sequence Parsing] format and other permissive behaviour
+   *   described in the spec.
+   *
+   * [JSON Text Sequence Encoding]: https://datatracker.ietf.org/doc/html/rfc7464#section-2.2
+   * [JSON Text Sequence Parsing]: https://datatracker.ietf.org/doc/html/rfc7464#section-2.1
+   */
+  strict?: boolean;
+}
+
+/** A streaming decoder that decodes RFC 7464 JSON Sequences to JSON values.
+ *
+ * The stream consumes UTF-8-encoded bytes. The byte stream consists of zero or
+ * more JSON-encoded values, each of which is preceded by a `'\x1E'` character,
+ * and followed by a `'\n'` character.
+ *
+ * The stream produces the values resulting from parsing each individual JSON
+ * text in the stream.
+ */
 export class JsonSequenceDecoderStream
-  implements TransformStream<Uint8Array, unknown>
-{
+  implements TransformStream<Uint8Array, unknown> {
   readonly readable: ReadableStream<unknown>;
   readonly writable: WritableStream<Uint8Array>;
 
-  constructor() {
+  constructor(options?: JsonSequenceDecoderStreamOptions) {
     const decoder = new TextDecoderStream();
     this.readable = decoder.readable
-      .pipeThrough(new TransformStream(jsonSeqDelimiterTransformer()))
-      .pipeThrough(new TransformStream(stringToJSONTransformer()));
+      .pipeThrough(new TransformStream(_jsonSeqDelimiterTransformer(options)))
+      .pipeThrough(new TransformStream(_stringToJSONTransformer()));
     this.writable = decoder.writable;
   }
 }