Refactor encoding interfaces and add TS utilities

Author: vweevers

README.md

@@ -16,7 +16,7 @@
 Create a transcoder, passing a desired format:
 
 ```js
-const Transcoder = require('level-transcoder')
+const { Transcoder } = require('level-transcoder')
 
 const transcoder1 = new Transcoder(['view'])
 const transcoder2 = new Transcoder(['buffer'])
@@ -163,7 +163,7 @@ Name of the (lower-level) encoding used by the return value of `encode()`. One o
 Custom encodings must follow the following interface:
 
 ```ts
-interface EncodingOptions<TIn, TFormat, TOut> {
+interface IEncoding<TIn, TFormat, TOut> {
   name: string
   format: 'buffer' | 'view' | 'utf8'
   encode: (data: TIn) => TFormat

index.d.ts

@@ -1,6 +1,6 @@
-import { Encoding, EncodingOptions } from './lib/encoding'
+import { Encoding, MixedEncoding, KnownEncoding, KnownEncodingName } from './lib/encoding'
 
-declare class Transcoder<T = any> {
+export class Transcoder<T = any> {
   /**
    * Create a Transcoder.
    * @param formats Formats supported by consumer.
@@ -17,16 +17,11 @@ declare class Transcoder<T = any> {
    * @param encoding Named encoding or encoding object.
    */
   encoding<TIn, TFormat, TOut> (
-    encoding: Encoding<TIn, TFormat, TOut>|EncodingOptions<TIn, TFormat, TOut>
+    encoding: MixedEncoding<TIn, TFormat, TOut>
   ): Encoding<TIn, T, TOut>
 
-  encoding (encoding: 'utf8'): Encoding<string | Buffer | Uint8Array, T, string>
-  encoding (encoding: 'buffer'): Encoding<Buffer | Uint8Array | string, T, Buffer>
-  encoding (encoding: 'view'): Encoding<Uint8Array | string, T, Uint8Array>
-  encoding (encoding: 'json'): Encoding<any, T, any>
-  encoding (encoding: 'hex'): Encoding<Buffer | string, T, string>
-  encoding (encoding: 'base64'): Encoding<Buffer | string, T, string>
+  encoding<N extends KnownEncodingName> (encoding: N): KnownEncoding<N, T>
   encoding (encoding: string): Encoding<any, T, any>
 }
 
-export = Transcoder
+export * from './lib/encoding'

index.js

@@ -22,7 +22,7 @@ class Transcoder {
       throw new TypeError("Format must be one of 'buffer', 'view', 'utf8'")
     }
 
-    /** @type {Map<string|Encoding<any, any, any>|EncodingOptions<any, any, any>, Encoding<any, any, any>>} */
+    /** @type {Map<string|MixedEncoding<any, any, any>, Encoding<any, any, any>>} */
     this[kEncodings] = new Map()
     this[kFormats] = new Set(formats)
 
@@ -45,7 +45,7 @@ class Transcoder {
   }
 
   /**
-   * @param {string|Encoding<any, any, any>|EncodingOptions<any, any, any>} encoding
+   * @param {string|MixedEncoding<any, any, any>} encoding
    * @returns {Encoding<any, T, any>}
    */
   encoding (encoding) {
@@ -62,8 +62,6 @@ class Transcoder {
         }
       } else if (typeof encoding !== 'object' || encoding === null) {
         throw new TypeError("First argument 'encoding' must be a string or object")
-      } else if (encoding instanceof Encoding) {
-        resolved = encoding
       } else {
         resolved = from(encoding)
       }
@@ -75,8 +73,10 @@ class Transcoder {
           resolved = resolved.createViewTranscoder()
         } else if (this[kFormats].has('buffer')) {
           resolved = resolved.createBufferTranscoder()
+        } else if (this[kFormats].has('utf8')) {
+          resolved = resolved.createUTF8Transcoder()
         } else {
-          throw new ModuleError(`Encoding '${name}' cannot be transcoded to 'utf8'`, {
+          throw new ModuleError(`Encoding '${name}' cannot be transcoded`, {
             code: 'LEVEL_ENCODING_NOT_SUPPORTED'
           })
         }
@@ -91,19 +91,25 @@ class Transcoder {
   }
 }
 
-module.exports = Transcoder
+exports.Transcoder = Transcoder
 
 /**
- * @param {EncodingOptions<any, any, any>} options
+ * @param {MixedEncoding<any, any, any>} options
  * @returns {Encoding<any, any, any>}
  */
 function from (options) {
-  const format = detectFormat(options)
+  if (options instanceof Encoding) {
+    return options
+  }
+
+  // Loosely typed for ecosystem compatibility
+  const maybeType = 'type' in options && typeof options.type === 'string' ? options.type : undefined
+  const name = options.name || maybeType || `anonymous-${anonymousCount++}`
 
-  switch (format) {
-    case 'view': return new ViewFormat(options)
-    case 'utf8': return new UTF8Format(options)
-    case 'buffer': return new BufferFormat(options)
+  switch (detectFormat(options)) {
+    case 'view': return new ViewFormat({ ...options, name })
+    case 'utf8': return new UTF8Format({ ...options, name })
+    case 'buffer': return new BufferFormat({ ...options, name })
     default: {
       throw new TypeError("Format must be one of 'buffer', 'view', 'utf8'")
     }
@@ -113,23 +119,23 @@ function from (options) {
 /**
  * If format is not provided, fallback to detecting `level-codec`
  * or `multiformats` encodings, else assume a format of buffer.
- * @param {EncodingOptions<any, any, any>} options
+ * @param {MixedEncoding<any, any, any>} options
  * @returns {string}
  */
-function detectFormat ({ format, buffer, code }) {
-  if (format !== undefined) {
-    return format
-  } else if (typeof buffer === 'boolean') {
-    return buffer ? 'buffer' : 'utf8' // level-codec
-  } else if (Number.isInteger(code)) {
+function detectFormat (options) {
+  if ('format' in options && options.format !== undefined) {
+    return options.format
+  } else if ('buffer' in options && typeof options.buffer === 'boolean') {
+    return options.buffer ? 'buffer' : 'utf8' // level-codec
+  } else if ('code' in options && Number.isInteger(options.code)) {
     return 'view' // multiformats
   } else {
     return 'buffer'
   }
 }
 
 /**
- * @typedef {import('./lib/encoding').EncodingOptions<TIn,TFormat,TOut>} EncodingOptions
+ * @typedef {import('./lib/encoding').MixedEncoding<TIn,TFormat,TOut>} MixedEncoding
  * @template TIn, TFormat, TOut
  */
 
@@ -148,3 +154,5 @@ const lookup = {
   ...encodings,
   ...aliases
 }
+
+let anonymousCount = 0

lib/encoding.d.ts

@@ -1,20 +1,19 @@
-import { BufferFormat, ViewFormat } from './formats'
+import { BufferFormat, ViewFormat, UTF8Format } from './formats'
 
 /**
  * Encodes {@link TIn} to {@link TFormat} and decodes
  * {@link TFormat} to {@link TOut}.
  */
-export abstract class Encoding<TIn, TFormat, TOut> {
-  constructor (options: EncodingOptions<TIn, TFormat, TOut>)
+export abstract class Encoding<TIn, TFormat, TOut> implements IEncoding<TIn, TFormat, TOut> {
+  constructor (options: IEncoding<TIn, TFormat, TOut>)
 
-  /** Encode data. */
   encode: (data: TIn) => TFormat
-
-  /** Decode data. */
   decode: (data: TFormat) => TOut
-
-  /** Unique name. */
   name: string
+  format: 'buffer' | 'view' | 'utf8'
+  createViewTranscoder (): ViewFormat<TIn, TOut>
+  createBufferTranscoder (): BufferFormat<TIn, TOut>
+  createUTF8Transcoder (): UTF8Format<TIn, TOut>
 
   /**
    * Common name, computed from {@link name}. If this encoding is a
@@ -23,53 +22,65 @@ export abstract class Encoding<TIn, TFormat, TOut> {
    * will equal {@link commonName}.
    */
   get commonName (): string
+}
+
+export interface IEncoding<TIn, TFormat, TOut> {
+  /**
+   * Encode data.
+   */
+  encode: (data: TIn) => TFormat
+
+  /**
+   * Decode data.
+   */
+  decode: (data: TFormat) => TOut
 
   /**
-   * Name of the (lower-level) encoding used by the return value of
+   * Unique name.
+   */
+  name: string
+
+  /**
+   * The name of the (lower-level) encoding used by the return value of
    * {@link encode}. One of 'buffer', 'view', 'utf8'.
    */
   format: 'buffer' | 'view' | 'utf8'
 
   /**
-   * Create a new encoding that transcodes {@link TFormat} to a view.
+   * Create a new encoding that transcodes {@link TFormat} from / to a view.
    */
-  createViewTranscoder (): ViewFormat<TIn, TOut>
+  createViewTranscoder?: (() => ViewFormat<TIn, TOut>) | undefined
 
   /**
-   * Create a new encoding that transcodes {@link TFormat} to a buffer.
+   * Create a new encoding that transcodes {@link TFormat} from / to a buffer.
    */
-  createBufferTranscoder (): BufferFormat<TIn, TOut>
+  createBufferTranscoder?: (() => BufferFormat<TIn, TOut>) | undefined
+
+  /**
+   * Create a new encoding that transcodes {@link TFormat} from / to a UTF-8 string.
+   */
+  createUTF8Transcoder?: (() => UTF8Format<TIn, TOut>) | undefined
 }
 
-// TODO: split into multiple interfaces (and then union those) in order to
-// separate the main level-transcoder interface from compatibility options.
-export interface EncodingOptions<TIn, TFormat, TOut> {
+export interface IExternalEncoding<TIn, TFormat, TOut> {
   /**
    * Encode data.
    */
-  encode?: ((data: TIn) => TFormat) | undefined
+  encode: (data: TIn) => TFormat
 
   /**
    * Decode data.
    */
-  decode?: ((data: TFormat) => TOut) | undefined
+  decode: (data: TFormat) => TOut
 
   /**
    * Unique name.
    */
   name?: string | undefined
 
-  /**
-   * The name of the (lower-level) encoding used by the return value of
-   * {@link encode}. One of 'buffer', 'view', 'utf8'. Defaults to 'buffer'
-   * if the {@link buffer} and {@link code} options are also undefined.
-   */
-  format?: 'buffer' | 'view' | 'utf8' | undefined
-
   /**
    * Legacy `level-codec` option that means the same as `format: 'buffer'`
-   * if true or `format: 'utf8'` if false. Used only when the {@link format} option
-   * is undefined.
+   * if true or `format: 'utf8'` if false.
    */
   buffer?: boolean | undefined
 
@@ -80,13 +91,68 @@ export interface EncodingOptions<TIn, TFormat, TOut> {
   type?: any
 
   /**
-   * For compatibility with `multiformats`. If a number, then the encoding is
-   * assumed to have a {@link format} of 'view'. Used only when the {@link format}
-   * and {@link buffer} options are undefined.
+   * To detect `multiformats`. If a number, then the encoding is
+   * assumed to have a {@link format} of 'view'.
    * @see https://github.com/multiformats/js-multiformats/blob/master/src/codecs/interface.ts
    */
   code?: any
-
-  createViewTranscoder?: (() => ViewFormat<TIn, TOut>) | undefined
-  createBufferTranscoder?: (() => BufferFormat<TIn, TOut>) | undefined
 }
+
+/**
+ * Names of built-in encodings.
+ */
+export type KnownEncodingName = 'utf8' | 'buffer' | 'view' | 'json' | 'hex' | 'base64'
+
+/**
+ * One of the supported encoding interfaces.
+ */
+export type MixedEncoding<TIn, TFormat, TOut> =
+  IEncoding<TIn, TFormat, TOut> |
+  IExternalEncoding<TIn, TFormat, TOut>
+
+/**
+ * Type utility to cast a built-in encoding identified by its name to an {@link Encoding}.
+ */
+export type KnownEncoding<N extends KnownEncodingName, TFormat>
+  = Encoding<KnownEncodingInput<N>, TFormat, KnownEncodingOutput<N>>
+
+/**
+ * Type utility to get the input type of a built-in encoding identified by its name.
+ */
+export type KnownEncodingInput<N extends KnownEncodingName>
+  = N extends 'utf8' ? string | Buffer | Uint8Array
+    : N extends 'buffer' ? Buffer | Uint8Array | string
+      : N extends 'view' ? Uint8Array | string
+        : N extends 'json' ? any
+          : N extends 'hex' ? Buffer | string
+            : N extends 'base64' ? Buffer | string
+              : never
+
+/**
+ * Type utility to get the output type of a built-in encoding identified by its name.
+ */
+export type KnownEncodingOutput<N extends KnownEncodingName>
+  = N extends 'utf8' ? string
+    : N extends 'buffer' ? Buffer
+      : N extends 'view' ? Uint8Array
+        : N extends 'json' ? any
+          : N extends 'hex' ? string
+            : N extends 'base64' ? string
+              : never
+
+/**
+ * Type utility to use a {@link MixedEncoding} with an untyped format.
+ */
+export type PartialEncoding<TIn, TOut = TIn> = MixedEncoding<TIn, any, TOut>
+
+/**
+ * Type utility to use a {@link MixedEncoding} with an untyped format and output.
+ * For when only the encoding side is needed.
+ */
+export type PartialEncoder<TIn> = MixedEncoding<TIn, any, any>
+
+/**
+ * Type utility to use a {@link MixedEncoding} with an untyped input and format.
+ * For when only the decoding side is needed.
+ */
+export type PartialDecoder<TOut> = MixedEncoding<any, any, TOut>