Remove NativeFormat

Was just a brief idea. Might have panned out but I don't want to
commit to it yet.

Author: vweevers

UPGRADING.md

@@ -2,6 +2,15 @@
 
 This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md).
 
+## Upcoming
+
+WIP notes, describing the differences from `level-codec`.
+
+- Throws error if encoding is not found, rather than falling back to `id` encoding
+- The `binary` encoding has been renamed to `buffer`, with `binary` as an alias
+- The `utf8` encoding will always return a string. It previously did not touch Buffers. Now it will call `buffer.toString('utf8')` for consistency. Consumers can (selectively) use the `buffer` or `view` encoding to avoid this conversion.
+- The `ascii`, `ucs2` and `utf16le` encodings are not supported.
+
 ## 10.0.0
 
 Legacy range options have been removed ([Level/community#86](https://github.com/Level/community/issues/86)). If you previously did:

index.js

@@ -3,7 +3,7 @@
 const ModuleError = require('module-error')
 const encodings = require('./lib/encodings')
 const { Encoding } = require('./lib/encoding')
-const { BufferFormat, ViewFormat, UTF8Format, NativeFormat } = require('./lib/formats')
+const { BufferFormat, ViewFormat, UTF8Format } = require('./lib/formats')
 
 const kFormats = Symbol('formats')
 const kEncodings = Symbol('encodings')
@@ -57,7 +57,6 @@ class Transcoder {
     return Array.from(types)
   }
 
-  // TODO: document that we don't fallback to 'id' anymore if encoding is not found
   /**
    * @param {string|Encoding<any, any, any>|EncodingOptions<any, any, any>} encoding
    * @returns {Encoding<any, T, any>}
@@ -87,22 +86,18 @@ class Transcoder {
         resolved = new BufferFormat(encoding)
       }
 
-      const { type, idempotent, format } = resolved
+      const { type, format } = resolved
 
-      if (this[kFormats].has(type)) {
-        // If idempotent, run data through it to normalize
-        if (!idempotent) resolved = new NativeFormat(type)
-      } else if (!this[kFormats].has(format)) {
+      if (!this[kFormats].has(format)) {
         if (this[kFormats].has('view')) {
           resolved = resolved.transcode('view')
         } else if (this[kFormats].has('buffer')) {
           resolved = resolved.transcode('buffer')
         } else {
           // TODO: improve error message (see tests, it's inconsistent)
-          throw new ModuleError(
-            `Encoding '${type}' is not supported`,
-            { code: 'LEVEL_ENCODING_NOT_SUPPORTED' }
-          )
+          throw new ModuleError(`Encoding '${type}' is not supported`, {
+            code: 'LEVEL_ENCODING_NOT_SUPPORTED'
+          })
         }
       }
 

lib/encoding.d.ts

@@ -57,12 +57,6 @@ export interface EncodingOptions<TIn, TFormat, TOut> {
    */
   format?: string | undefined
 
-  /**
-   * Whether {@link encode} and {@link decode} are idempotent
-   * functions, such that `f(x) == f(f(x))`.
-   */
-  idempotent?: boolean | undefined
-
   /**
    * Legacy property that means the same as `format: 'buffer'`.
    * Used only when `format` is not provided.

lib/encoding.js

@@ -15,7 +15,6 @@ class Encoding {
     decode,
     type,
     format,
-    idempotent,
     buffer,
     createViewTranscoder,
     createBufferTranscoder
@@ -36,10 +35,6 @@ class Encoding {
       throw new TypeError("The 'format' option must be a string or undefined")
     }
 
-    if (typeof idempotent !== 'boolean' && idempotent !== undefined) {
-      throw new TypeError("The 'idempotent' option must be a boolean or undefined")
-    }
-
     /** @type {(data: TIn) => TFormat} */
     this.encode = (encode || this.encode || identity).bind(this)
 
@@ -53,9 +48,7 @@ class Encoding {
     this.format = format || (buffer === false ? 'utf8' : 'buffer')
 
     /** @type {boolean} */
-    this.idempotent = idempotent !== undefined
-      ? idempotent
-      : this.type === this.format
+    this.idempotent = this.type === this.format
 
     if (createViewTranscoder) {
       this.createViewTranscoder = createViewTranscoder

lib/encodings.js

@@ -9,7 +9,6 @@ const { BufferFormat, ViewFormat, UTF8Format, IdentityFormat } = require('./form
  */
 exports.utf8 = new UTF8Format({
   encode: function (data) {
-    // TODO: document that this now always returns a string
     // On node 16.9.1 buffer.toString() is 5x faster than TextDecoder
     return Buffer.isBuffer(data)
       ? data.toString('utf8')
@@ -106,9 +105,6 @@ exports.id = new IdentityFormat({
   type: 'id'
 })
 
-// TODO: document removed encodings (ascii, ucs2/ucs-2, utf16le/utf-16le)
-// TODO: perhaps even remove all of them
-
 /**
  * @type {BufferFormat<Buffer|string, string>}
  */

lib/formats.d.ts

@@ -4,11 +4,3 @@ export class BufferFormat<TIn, TOut> extends Encoding<TIn, Buffer, TOut> {}
 export class ViewFormat<TIn, TOut> extends Encoding<TIn, Uint8Array, TOut> {}
 export class UTF8Format<TIn, TOut> extends Encoding<TIn, string, TOut> {}
 export class IdentityFormat extends Encoding<any, any, any> {}
-
-/**
- * Special pass-through encoding for externally implemented encodings.
- * @experimental May get removed without warning.
- */
-export class NativeFormat extends Encoding<any, any, any> {
-  constructor (nativeType: string)
-}

lib/formats.js

@@ -108,23 +108,10 @@ class IdentityFormat extends Encoding {
   }
 }
 
-/**
- * @extends {Encoding<any,any,any>}
- */
-class NativeFormat extends Encoding {
-  /**
-   * @param {string} nativeType
-   */
-  constructor (nativeType) {
-    super({ type: `${nativeType}+native`, idempotent: true, format: nativeType })
-  }
-}
-
 exports.BufferFormat = BufferFormat
 exports.ViewFormat = ViewFormat
 exports.UTF8Format = UTF8Format
 exports.IdentityFormat = IdentityFormat
-exports.NativeFormat = NativeFormat
 
 /**
  * @typedef {import('./encoding').EncodingOptions<TIn,TFormat,TOut>} EncodingOptions

test/encoding.js

@@ -35,20 +35,6 @@ test('Encoding() throws on invalid type or format option', function (t) {
   }
 })
 
-test('Encoding() throws on invalid idempotent option', function (t) {
-  t.plan(6 * 2)
-
-  for (const invalid of ['', 'true', null, {}, () => {}, []]) {
-    try {
-      // eslint-disable-next-line no-new
-      new Encoding({ idempotent: invalid })
-    } catch (err) {
-      t.is(err.name, 'TypeError', 'is a TypeError')
-      t.is(err.message, "The 'idempotent' option must be a boolean or undefined", 'correct message')
-    }
-  }
-})
-
 test('Encoding() sets format based on format option or legacy buffer option', function (t) {
   t.is(new Encoding({ buffer: true }).format, 'buffer')
   t.is(new Encoding({ buffer: false }).format, 'utf8')

test/transcoder.js

@@ -34,10 +34,6 @@ test('transcoder.types()', function (t) {
   t.same(transcoder.types(), ['utf8', 'json', 'buffer', 'view', 'hex', 'base64'])
   t.same(transcoder.types(true), ['utf8+view', 'json+view', 'buffer+view', 'view', 'hex+view', 'base64+view'])
 
-  transcoder = new Transcoder(['json'])
-  t.same(transcoder.types(), ['json'])
-  t.same(transcoder.types(true), ['json+native'])
-
   transcoder = new Transcoder(['id'])
   t.same(transcoder.types(), ['id'])
   t.same(transcoder.types(true), ['id'])
@@ -218,9 +214,6 @@ test('transcoder.encoding() wraps custom anonymous encoding', function (t) {
     t.is(e.format, 'buffer', 'ignores invalid legacy buffer option')
   }
 
-  verify(transcoder.encoding({ ...opts, idempotent: true }), true)
-  verify(transcoder.encoding({ ...opts, idempotent: false }), false)
-
   t.end()
 })