From 4cad01c441e0ca0ea1e525158f4335eb77cf15be Mon Sep 17 00:00:00 2001
From: Eugene Lazutkin <eugene.lazutkin@gmail.com>
Date: Tue, 17 Sep 2024 13:06:50 -0500
Subject: [PATCH] Added embedded docs.

---
 src/jsonl/parser.d.ts         | 15 +++++++++++++++
 src/jsonl/parserStream.d.ts   | 12 ++++++++++++
 src/jsonl/stringerStream.d.ts | 23 +++++++++++++++++++++++
 3 files changed, 50 insertions(+)

diff --git a/src/jsonl/parser.d.ts b/src/jsonl/parser.d.ts
index b478195..388ecd4 100644
--- a/src/jsonl/parser.d.ts
+++ b/src/jsonl/parser.d.ts
@@ -4,13 +4,28 @@ import {Buffer} from 'node:buffer';
 
 export = parser;
 
+/**
+ * The JSONL parser output.
+ */
 interface OutputItem {
+  /** The key: a sequential number starting from 0. */
   key: number;
+  /** The parsed value. */
   value: any;
 }
 
+/**
+ * The reviver function prototype required by `JSON.parse()`.
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
+ */
 type Reviver = (this: unknown, key: string, value: unknown) => unknown;
 
+/**
+ * The JSONL parser as a streamable generator.
+ * @param reviver an optional reviver function (see {@link Reviver})
+ * @returns an asynchronous generator
+ * @remark parsers JSON lines items returning them as {@link OutputItem}.
+ */
 declare function parser(
   reviver?: Reviver
 ): (x: string | Buffer) => AsyncGenerator<OutputItem, void, unknown>;
diff --git a/src/jsonl/parserStream.d.ts b/src/jsonl/parserStream.d.ts
index 84328fb..ce5eadd 100644
--- a/src/jsonl/parserStream.d.ts
+++ b/src/jsonl/parserStream.d.ts
@@ -5,10 +5,22 @@ import {TypedDuplex} from '../typed-streams';
 
 export = parserStream;
 
+/**
+ * Options for the parser stream based on `DuplexOptions` with some additional properties.
+ */
 interface ParserOptions extends DuplexOptions {
+  /**
+   * An optional reviver function suitable for `JSON.parse()`.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse
+   */
   reviver?: (this: unknown, key: string, value: unknown) => unknown;
 }
 
+/**
+ * Returns a JSONL parser as a duplex stream.
+ * @param options options for the parser stream (see {@link ParserOptions})
+ * @returns a duplex stream
+ */
 declare function parserStream<T = any>(
   options?: ParserOptions
 ): TypedDuplex<string | Uint8Array, T>;
diff --git a/src/jsonl/stringerStream.d.ts b/src/jsonl/stringerStream.d.ts
index 95469ea..98e617b 100644
--- a/src/jsonl/stringerStream.d.ts
+++ b/src/jsonl/stringerStream.d.ts
@@ -5,13 +5,36 @@ import {TypedTransform} from '../typed-streams';
 
 export = stringer;
 
+/**
+ * Options for the stringer stream used to control the output.
+ */
 interface StringerOptions {
+  /** The prefix string. It is prepended to the output. Defaults to `""`. */
   prefix?: string;
+  /** The suffix string. It is appended to the output. Defaults to `""`. */
   suffix?: string;
+  /** The separator string used between items. Defaults to `"\n"`. */
   separator?: string;
+  /**
+   * The empty value string. It is used when no values were streamed. Defaults to `prefix + suffix`.
+   * See {@link StringerOptions.prefix} and {@link StringerOptions.suffix}.
+   */
   emptyValue?: string;
+  /**
+   * The optional replacer function used by `JSON.stringify()`.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+   */
   replacer?: (this: unknown, key: string, value: unknown) => unknown;
+  /**
+   * The optional space string or number used by `JSON.stringify()`.
+   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+   */
   space?: string | number;
 }
 
+/**
+ * Returns a JSONL stringer as a duplex stream.
+ * @param options options for the stringer stream (see {@link StringerOptions})
+ * @returns a duplex stream
+ */
 declare function stringer<T>(options?: any): TypedTransform<T, string>;