Remove id encoding

Author: vweevers

README.md

@@ -57,17 +57,16 @@ For example, on `leveldown` a call like `db.put(key, { x: 3 }, { valueEncoding:
 
 Various modules in the ecosystem, in and outside of level, can be used with `level-transcoder`.
 
-| Module                                     | Format       | Interface                    | Named |
-|:-------------------------------------------|:-------------|:-----------------------------|:------|
-| [`protocol-buffers`][protocol-buffers]     | buffer       | `level-codec`                | ❌    |
-| [`charwise`][charwise]                     | utf8         | `level-codec`                | ✅    |
-| [`bytewise`][bytewise]                     | buffer       | `level-codec`                | ✅    |
-| [`lexicographic-integer-encoding`][lexint] | buffer, utf8 | `level-codec`                | ✅    |
-| [`codecs`][mafintosh-codecs]               | buffer       | `codecs`                     | ✅    |
-| [`abstract-encoding`][abstract-encoding]   | buffer       | `abstract-encoding`          | ❌    |
-| [`multiformats`][js-multiformats]          | view         | [`multiformats`][blockcodec] | ✅    |
-| [`base32-codecs`][base32-codecs]           | buffer       | `codecs`                     | ✅    |
-| [`level-codec`][level-codec]               | buffer, utf8 | `level-codec`                | ✅    |
+| Module                                     | Format       | Interface                           | Named |
+|:-------------------------------------------|:-------------|:------------------------------------|:------|
+| [`protocol-buffers`][protocol-buffers]     | buffer       | [`level-codec`][level-codec]        | ❌    |
+| [`charwise`][charwise]                     | utf8         | [`level-codec`][level-codec]        | ✅    |
+| [`bytewise`][bytewise]                     | buffer       | [`level-codec`][level-codec]        | ✅    |
+| [`lexicographic-integer-encoding`][lexint] | buffer, utf8 | [`level-codec`][level-codec]        | ✅    |
+| [`codecs`][mafintosh-codecs]               | buffer       | [`codecs`][mafintosh-codecs]        | ✅    |
+| [`abstract-encoding`][abstract-enc]        | buffer       | [`abstract-encoding`][abstract-enc] | ❌    |
+| [`multiformats`][js-multiformats]          | view         | [`multiformats`][blockcodec]        | ✅    |
+| [`base32-codecs`][base32-codecs]           | buffer       | [`codecs`][mafintosh-codecs]        | ✅    |
 
 Common between the interfaces is that they have `encode()` and `decode()` methods. The terms "codec" and "encoding" are used interchangeably. Passing these encodings through `Transcoder#encoding()` (which is done implicitly when used in an `abstract-level` database) results in normalized encoding objects that follow [the interface](./lib/encoding.d.ts) of `level-transcoder`.
 
@@ -206,7 +205,7 @@ Support us with a monthly donation on [Open Collective](https://opencollective.c
 
 [mafintosh-codecs]: https://github.com/mafintosh/codecs
 
-[abstract-encoding]: https://github.com/mafintosh/abstract-encoding
+[abstract-enc]: https://github.com/mafintosh/abstract-encoding
 
 [js-multiformats]: https://github.com/multiformats/js-multiformats
 

UPGRADING.md

@@ -8,7 +8,8 @@ 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 `utf8` encoding previously did not touch Buffers. Now it will call `buffer.toString('utf8')` for consistency. Consumers can use the `buffer` encoding to avoid this conversion.
+- The `id` encoding (aliased as `none`) which wasn't supported by any active `abstract-leveldown` implementation, has been removed.
 - The `ascii`, `ucs2` and `utf16le` encodings are not supported.
 
 ## 10.0.0

index.d.ts

@@ -5,7 +5,7 @@ declare class Transcoder<T = any> {
    * Create a Transcoder.
    * @param formats Formats supported by consumer.
    */
-  constructor (formats: Iterable<string>)
+  constructor (formats: Array<'buffer'|'view'|'utf8'>)
 
   /**
    * Get supported encoding objects.
@@ -26,7 +26,6 @@ declare class Transcoder<T = any> {
   encoding (encoding: 'json'): Encoding<any, T, any>
   encoding (encoding: 'hex'): Encoding<Buffer | string, T, string>
   encoding (encoding: 'base64'): Encoding<Buffer | string, T, string>
-  encoding (encoding: 'id'): Encoding<any, any, any>
   encoding (encoding: string): Encoding<any, T, any>
 }
 

index.js

@@ -7,32 +7,25 @@ const { BufferFormat, ViewFormat, UTF8Format } = require('./lib/formats')
 
 const kFormats = Symbol('formats')
 const kEncodings = Symbol('encodings')
+const validFormats = new Set(['buffer', 'view', 'utf8'])
 
 /** @template T */
 class Transcoder {
   /**
-   * @param {Iterable<string>} formats
+   * @param {Array<'buffer'|'view'|'utf8'>} formats
    */
   constructor (formats) {
-    if (formats == null ||
-      typeof formats[Symbol.iterator] !== 'function' ||
-      typeof formats === 'string') {
-      throw new TypeError("The first argument 'formats' must be an Iterable")
+    if (!Array.isArray(formats)) {
+      throw new TypeError("The first argument 'formats' must be an array")
+    } else if (!formats.every(f => validFormats.has(f))) {
+      // Note: we only only support aliases in key- and valueEncoding options (where we already did)
+      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>>} */
     this[kEncodings] = new Map()
     this[kFormats] = new Set(formats)
 
-    // Only support aliases in key- and valueEncoding options (where we already did)
-    for (const [alias, { name }] of Object.entries(aliases)) {
-      if (this[kFormats].has(alias)) {
-        throw new ModuleError(`The '${alias}' alias is not supported here; use '${name}' instead`, {
-          code: 'LEVEL_ENCODING_NOT_SUPPORTED'
-        })
-      }
-    }
-
     // Register encodings (done early in order to populate encodings())
     for (const k in encodings) {
       try {
@@ -83,7 +76,7 @@ class Transcoder {
         } else if (this[kFormats].has('buffer')) {
           resolved = resolved.createBufferTranscoder()
         } else {
-          throw new ModuleError(`Encoding '${name}' is not supported`, {
+          throw new ModuleError(`Encoding '${name}' cannot be transcoded to 'utf8'`, {
             code: 'LEVEL_ENCODING_NOT_SUPPORTED'
           })
         }
@@ -112,9 +105,7 @@ function from (options) {
     case 'utf8': return new UTF8Format(options)
     case 'buffer': return new BufferFormat(options)
     default: {
-      throw new ModuleError(`Encoding '${format}' is not supported`, {
-        code: 'LEVEL_ENCODING_NOT_SUPPORTED'
-      })
+      throw new TypeError("Format must be one of 'buffer', 'view', 'utf8'")
     }
   }
 }
@@ -147,8 +138,7 @@ function detectFormat ({ format, buffer, code }) {
  */
 const aliases = {
   binary: encodings.buffer,
-  'utf-8': encodings.utf8,
-  none: encodings.id
+  'utf-8': encodings.utf8
 }
 
 /**

lib/encoding.d.ts

@@ -25,9 +25,9 @@ export abstract class Encoding<TIn, TFormat, TOut> {
 
   /**
    * The name of the (lower-level) encoding used by the return value of
-   * {@link encode}. Typically one of 'buffer', 'view', 'utf8'.
+   * {@link encode}. One of 'buffer', 'view', 'utf8'.
    */
-  format: string
+  format: 'buffer' | 'view' | 'utf8'
 
   /**
    * Create a new encoding that transcodes {@link TFormat} to a view.
@@ -58,10 +58,10 @@ export interface EncodingOptions<TIn, TFormat, TOut> {
 
   /**
    * The name of the (lower-level) encoding used by the return value of
-   * {@link encode}. Typically one of 'buffer', 'view', 'utf8'. Defaults to
-   * 'buffer' if the {@link buffer} and {@link code} options are also undefined.
+   * {@link encode}. One of 'buffer', 'view', 'utf8'. Defaults to 'buffer'
+   * if the {@link buffer} and {@link code} options are also undefined.
    */
-  format?: string | undefined
+  format?: 'buffer' | 'view' | 'utf8' | undefined
 
   /**
    * Legacy `level-codec` option that means the same as `format: 'buffer'`

lib/encoding.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const ModuleError = require('module-error')
+const formats = new Set(['buffer', 'view', 'utf8'])
 
 /**
  * @template TIn, TFormat, TOut
@@ -23,8 +24,8 @@ class Encoding {
       throw new TypeError("The 'name' option must be a string or undefined")
     }
 
-    if (typeof options.format !== 'string' || options.format === '') {
-      throw new TypeError("The 'format' option must be a non-empty string")
+    if (typeof options.format !== 'string' || !formats.has(options.format)) {
+      throw new TypeError("The 'format' option must be one of 'buffer', 'view', 'utf8'")
     }
 
     // Loosely typed for ecosystem compatibility

lib/encodings.d.ts

@@ -1,9 +1,8 @@
-import { BufferFormat, ViewFormat, UTF8Format, IdentityFormat } from './formats'
+import { BufferFormat, ViewFormat, UTF8Format } from './formats'
 
 export const utf8: UTF8Format<string | Uint8Array | Buffer, string>
 export const json: UTF8Format<any, any>
 export const buffer: BufferFormat<string | Uint8Array | Buffer, Buffer>
 export const view: ViewFormat<Uint8Array | string, Uint8Array>
-export const id: IdentityFormat
 export const hex: BufferFormat<string | Buffer, string>
 export const base64: BufferFormat<string | Buffer, string>

lib/encodings.js

@@ -2,7 +2,7 @@
 
 const { Buffer } = require('buffer') || {}
 const { textEncoder, textDecoder } = require('./text-endec')()
-const { BufferFormat, ViewFormat, UTF8Format, IdentityFormat } = require('./formats')
+const { BufferFormat, ViewFormat, UTF8Format } = require('./formats')
 
 /**
  * @type {UTF8Format<string|Buffer|Uint8Array, string>}
@@ -101,10 +101,6 @@ exports.view = new ViewFormat({
   }
 })
 
-exports.id = new IdentityFormat({
-  name: 'id'
-})
-
 /**
  * @type {BufferFormat<Buffer|string, string>}
  */

lib/formats.d.ts

@@ -3,4 +3,3 @@ import { Encoding } from './encoding'
 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> {}

lib/formats.js

@@ -96,22 +96,9 @@ class UTF8Format extends Encoding {
   }
 }
 
-/**
- * @extends {Encoding<any,any,any>}
- */
-class IdentityFormat extends Encoding {
-  /**
-   * @param {EncodingOptions<any, any, any>} options
-   */
-  constructor (options) {
-    super({ ...options, format: 'id' })
-  }
-}
-
 exports.BufferFormat = BufferFormat
 exports.ViewFormat = ViewFormat
 exports.UTF8Format = UTF8Format
-exports.IdentityFormat = IdentityFormat
 
 /**
  * @typedef {import('./encoding').EncodingOptions<TIn,TFormat,TOut>} EncodingOptions