From 909801647466c40bd35a231d8c2b8198cbb087cf Mon Sep 17 00:00:00 2001
From: Jamie King <jamie.king@aexp.com>
Date: Fri, 12 Apr 2024 14:56:06 -0700
Subject: [PATCH] feat: updated types to include expectPinoConfig

---
 README.md                  | 27 +++++++++++++++++++++++++--
 index.d.ts                 | 30 ++++++++++++++++++++++++++++++
 test/types/index.test-d.ts | 10 ++++++++++
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6b2aa49..acb91f3 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Write Pino transports easily.
 
 ## Install
 
-```
+```sh
 npm i pino-abstract-transport
 ```
 
@@ -43,9 +43,12 @@ module.exports = function (opts) {
 ```
 
 ## Typescript usage
+
 Install the type definitions for node. Make sure the major version of the type definitions matches the node version you are using.
+
 #### Node 16
-```
+
+```sh
 npm i -D @types/node@16
 ```
 
@@ -144,6 +147,26 @@ pipeline(process.stdin, buildTransform(), buildDestination(), function (err) {
 })
 ```
 
+### Using pino config
+
+Setting `expectPinoConfig` to `true` will make the transport wait for pino to send its configuration before starting to process logs. It will add `levels`, `messageKey` and `errorKey` to the stream.
+
+When used with an incompatible version of pino, the stream will immediately error.
+
+```js
+import build from 'pino-abstract-transport'
+
+export default function (opts) {
+  return build(async function (source) {
+    for await (const obj of source) {
+      console.log(`[${source.levels.labels[obj.level]}]: ${obj[source.messageKey]}`)
+    }
+  }, {
+    expectPinoConfig: true
+  })
+}
+```
+
 ## License
 
 MIT
diff --git a/index.d.ts b/index.d.ts
index 74b58a8..1ac49a5 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -40,6 +40,12 @@ type BuildOptions = {
    * `metadata` If set to false, do not add metadata properties to the returned stream
    */
   metadata?: false;
+
+  /**
+   * `expectPinoConfig` If set to true, the transport will wait for pino to send its
+   * configuration before starting to process logs.
+   */
+  expectPinoConfig?: boolean;
 };
 
 /**
@@ -50,6 +56,17 @@ type EnablePipelining = BuildOptions & {
   enablePipelining: true;
 };
 
+/**
+ * Create a split2 instance and returns it. This same instance is also passed
+ * to the given function, which is called after pino has sent its configuration.
+ *
+ * @returns {Promise<Transform>} the split2 instance
+ */
+declare function build(
+  fn: (transform: Transform & build.OnUnknown) => void | Promise<void>,
+  opts: BuildOptions & { expectPinoConfig: true }
+): Promise<Transform & build.OnUnknown>;
+
 /**
  * Create a split2 instance and returns it. This same instance is also passed
  * to the given function, which is called synchronously.
@@ -61,6 +78,19 @@ declare function build(
   opts?: BuildOptions
 ): Transform & build.OnUnknown;
 
+/**
+ * Creates a split2 instance and passes it to the given function, which is called
+ * after pino has sent its configuration. Then wraps the split2 instance and
+ * the returned stream into a Duplex, so they can be concatenated into multiple
+ * transports.
+ *
+ * @returns {Promise<Transform>} the wrapped split2 instance
+ */
+declare function build(
+  fn: (transform: Transform & build.OnUnknown) => Transform & build.OnUnknown,
+  opts: EnablePipelining & { expectPinoConfig: true }
+): Promise<Transform>;
+
 /**
  * Creates a split2 instance and passes it to the given function, which is called
  * synchronously. Then wraps the split2 instance and the returned stream into a
diff --git a/test/types/index.test-d.ts b/test/types/index.test-d.ts
index 3fa9169..b5f6a85 100644
--- a/test/types/index.test-d.ts
+++ b/test/types/index.test-d.ts
@@ -9,12 +9,22 @@ import { Transform } from "stream";
  */
 expectType<Transform>(build((source) => source, { enablePipelining: true }));
 
+/**
+ * If expectPinoConfig is set with enablePipelining, build returns a promise
+ */
+expectType<(Promise<Transform>)>(build((source) => source, { enablePipelining: true, expectPinoConfig: true }));
+
 /**
  * If enablePipelining is not set the unknown event can be listened to on
  * the returned stream.
  */
 expectType<Transform & OnUnknown>(build((source) => {}));
 
+/**
+ * If expectPinoConfig is set, build returns a promise
+ */
+expectType<(Promise<Transform & OnUnknown>)>(build((source) => {}, { expectPinoConfig: true }));
+
 /**
  * build also accepts an async function
  */