From 8c2a2d46b4a2947374f0b3d88a655c18ad943f21 Mon Sep 17 00:00:00 2001
From: Matthias Geisler <matthias.geisler@data4life.care>
Date: Mon, 19 Oct 2020 05:35:40 +0200
Subject: [PATCH] Add AbstractConvert & ConverterConstructor

Please note: this changes opts of the convert method as well. It's now
'unknown', so consumer are able to redeclare the type for their need.
---
 packages/core/types/index.d.ts | 25 ++++++++++++++++++++++---
 packages/core/types/tests.ts   | 13 +++++++++++--
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/packages/core/types/index.d.ts b/packages/core/types/index.d.ts
index a57907caf..4b5ad86a4 100644
--- a/packages/core/types/index.d.ts
+++ b/packages/core/types/index.d.ts
@@ -2980,7 +2980,26 @@ export namespace Asciidoctor {
     function create(): Html5Converter;
   }
 
-  class Converter {
+  interface AbstractConverter {
+    /**
+     * Converts an {AbstractNode} using the given transform.
+     * This method must be implemented by a concrete converter class.
+     *
+     * @param node - The concrete instance of AbstractNode to convert.
+     * @param [transform] - An optional String transform that hints at which transformation should be applied to this node.
+     * If a transform is not given, the transform is often derived from the value of the {AbstractNode#getNodeName} property. (optional, default: undefined)
+     * @param [opts]- An optional JSON of options hints about how to convert the node. (optional, default: undefined)
+     *
+     * @returns the {String} result.
+     */
+    convert(node: AbstractNode, transform?: string, opts?: unknown): string;
+  }
+
+  interface ConverterConstructor {
+    new(backend?: string, opts?: unknown): AbstractConverter;
+  }
+
+  class Converter implements AbstractConverter {
     /**
      * Converts an {AbstractNode} using the given transform.
      * This method must be implemented by a concrete converter class.
@@ -3009,7 +3028,7 @@ export namespace Asciidoctor {
      * @param opts - a JSON of options to pass to the converter (default: {})
      * @returns a {Converter} instance for converting nodes in an Asciidoctor AST.
      */
-    function create(backend: string, opts?: any): Converter;
+    function create(backend: string, opts?: unknown): Converter;
   }
 
   /**
@@ -3027,7 +3046,7 @@ export namespace Asciidoctor {
      * @param converter - The {Converter} instance to register
      * @param backends- A {string} {Array} of backend names that this converter should be registered to handle (optional, default: ['*'])
      */
-    register(converter: any, backends?: string[]): void;
+    register(converter: AbstractConverter | ConverterConstructor, backends?: string[]): void;
 
     /**
      * Retrieves the singleton instance of the converter factory.
diff --git a/packages/core/types/tests.ts b/packages/core/types/tests.ts
index faa81a794..22dbd1344 100644
--- a/packages/core/types/tests.ts
+++ b/packages/core/types/tests.ts
@@ -510,7 +510,7 @@ interface Transforms {
   [key: string]: (node: Asciidoctor.AbstractNode) => string;
 }
 
-class BlogConverter {
+class BlogConverter implements Asciidoctor.AbstractConverter {
   private readonly baseConverter: Asciidoctor.Html5Converter;
   private readonly transforms: Transforms;
 
@@ -1076,12 +1076,21 @@ assert(blockSubs5[0] === 'specialcharacters');
 let converterRegistry = processor.ConverterFactory.getRegistry();
 assert(typeof converterRegistry.html5 === 'function');
 
-class BlankConverter {
+class BlankConverter implements Asciidoctor.AbstractConverter {
   convert() {
     return '';
   }
 }
 
+const BlankConstructor = BlankConverter as Asciidoctor.ConverterConstructor;
+processor.ConverterFactory.register(BlankConstructor, ['blank']);
+converterRegistry = processor.ConverterFactory.getRegistry();
+assert(typeof converterRegistry.html5 === 'function');
+assert(typeof converterRegistry.blank === 'function');
+assert(typeof processor.ConverterFactory.for('html5') === 'function');
+assert(typeof processor.ConverterFactory.for('blank') === 'function');
+assert(typeof processor.ConverterFactory.for('foo') === 'undefined');
+
 processor.ConverterFactory.register(new BlankConverter(), ['blank']);
 converterRegistry = processor.ConverterFactory.getRegistry();
 assert(typeof converterRegistry.html5 === 'function');