v2.4.0

New features

• A new .pipe() method on Decoder allows you to pass the output of one decoder into another:

  string
    .transform((s) => s.split(',')) // transform first...
    .pipe(array(nonEmptyString)); //   ...then validate that result

  This was previously possible already with .then, but it wasn't as elegant to express.
• The new .pipe() can also dynamically select another decoder, based on the input:

  string
    .transform((s) => s.split(',').map(Number)) // transform first...
    .pipe((tup) =>
      tup.length === 2
        ? point2d
        : tup.length === 3
          ? point3d
          : never('Invalid coordinate'),
    );

• Decoder error messages will now quote identifiers using single quotes, which makes them more human-readable in JSON responses. Compare:

  "Value at key \"foo\": Must be \"bar\", \"qux\""  // ❌ Previously
  "Value at key 'foo': Must be 'bar', 'qux'"        // ✅ Now
  

• Some runtime perf optimizations

New decoders

• identifier (docs)
• nanoid() (docs)

Removed decoders

• Remove numericBoolean decoder, which was deprecated since 2.3.0.

v2.3.0

New features:

• All enum types are now supported (docs)
• Record decoder now supports both record(values) and record(keys, values) forms (docs)
• Add datelike decoder (docs)
• Add support for bigint (docs)
• Add built-in support for common string validations
• Better support for symbols in constant() and oneOf()

New decoders:

• enum_ (see docs)
• record() (see docs)
• select() (see docs)
• bigint (see docs)
• datelike (see docs)
• decimal (see docs)
• hexadecimal (see docs)
• numeric (see docs)

Renamed decoders:

Some decoders have been renamed because their names were based on Flowisms. Names have been updated to better reflect TypeScript terminology:

• dict() → record()
• maybe() → nullish()
• set() → setFromArray() (to make room for a better set() decoder in a future
  version)

Deprecated decoders:

The following decoders are deprecated because they were not commonly used, and a bit too specific to be in the standard library. They are also scheduled for removal in a future decoders version.

• dict() (prefer record())
• hardcoded() (prefer always())
• maybe() (prefer nullish())
• mixed (prefer unknown)
• numericBoolean()

Other changes:

• Fix: positiveNumber and positiveInteger no longer accept -0 as valid inputs
• Fix: either return type would sometimes get inferred incorrectly if members partially overlapped (see #941)
• Reorganized internal module structure
• Simplified some of the more complicated internal types

v2.2.0

Breaking change: Dropped Flow support¹.

Breaking change: Projects that are not yet using strict: true in their tsconfig.json files files are no longer supported. Previously, decoders went to great lenghts to support both configurations, but the internal typing magic was getting too complex to maintain without much benefit.

Breaking change: A small breaking change is introduced that removes the need for some packaging workarounds to support projects using old TypeScript/Node versions. It’s now simpler to use, and simpler to maintain:

-import { formatInline, formatShort } from 'decoders/format'; // ❌
+import { formatInline, formatShort } from 'decoders'; // ✅

-import { Result, ok, err } from 'decoders/result'; // ❌
+import { Result, ok, err } from 'decoders'; // ✅

Other, smaller changes, mostly internal:

• Rewritten source code in TypeScript (previously Flow)
• Rewritten test suite in Vitest (previously Jest)
• Modern ESM and CJS dual exports (fully tree-shakable when using ESM)
• Further reduced bundle size
• Related, greatly simplified complex internal typing magic to make it work in projects with and without strict mode.

1. I'm still open to bundling Flow types within this package, but only if that can be supported in a maintenance-free way, for example by using a script that will generate *.flow files from TypeScript source files. If someone can add support for that, I'm open to pull requests! 🙏 ) ↩

v2.1.0

• Officially drop Node 12 and 14 support (they may still work)
• Fix unintentional inclusion of lib.dom.d.ts in TypeScript

v2.0.5

• The returned value for positiveInteger(-0) is now 0, not -0
• The returned value for positiveNumber(-0) is now 0, not -0

Thanks, @gcampax!

v2.0.4

Fix a bug in the url decoder, which could incorrectly reject URLs with a / in the query path. Thanks, @gcampax!

v2.0.3

• Fix bundling issue where TypeScript types would not get picked up correctly in old TypeScript versions. Thanks, @robinchow!

• Fix TypeScript types for Result type to allow implicit-undefineds.

v2.0.2

• Fix TypeScript types for formatShort and formatInline helper functions

v2.0.1

• TypeScript-only: Fix definition of JSONObject to reflect that its values might always be undefined as well.

• TypeScript-only: Changed return types of { [key: string]: T } to Record<string, T>.

• TypeScript-only: Fine-tune the type of instanceOf().

v2.0.0

This is a breaking change, which brings numerous benefits:

• A simpler API 😇
• Smaller bundle size (67% reduction 😱)
• Tree-shaking support 🍃
• Runtime speed 🏎️
• Better documentation 📚
• Better support for writing your own decoders 🛠️

Please see the migration guide for precise instructions on how to
adjust your v1 code.

The main change is the brand new Decoder<T> API! The tl;dr is:

Replace this v1 pattern...		...with this v2 API	Notes
mydecoder(input)	→	mydecoder.decode(input)	migration instructions
guard(mydecoder)(input)	→	mydecoder.verify(input)	migration instructions
map(mydecoder, ...)	→	mydecoder.transform(...)	migration instructions
compose(mydecoder, predicate(...))	→	mydecoder.refine(...)	migration instructions
describe(mydecoder, ...)	→	mydecoder.describe(...)
mydecoder(input).value()	→	mydecoder.value(input)
either, either3, ..., either9	→	either	migration instructions
tuple1, tuple2, ... tuple6	→	tuple	migration instructions
dispatch	→	taggedUnion	migration instructions
url(...)	→	httpsUrl / url (signature has changed)	migration instructions

The full documentation is available on decoders.cc.

Other features:

• Include ES modules in published NPM builds (yay tree-shaking! 🍃)
• Much smaller total bundle size (67% smaller compared to v1 😱)

Other potentially breaking changes:

• Drop support for all Node versions below 12.x
• Drop support for TypeScript versions below 4.1.0
• Drop support for Flow versions below 0.142.0
• Drop all package dependencies
• Direct reliance on lemons has been removed

New decoders:

• always
• anyNumber
• never
• prep()
• set()
• uuid
• uuidv1
• uuidv4

Other improvements:

• optional(),
  nullable(), and
  maybe() now each take an optional 2nd param to
  specify a default value
• Better error messages for nested eithers

Implementation changes:

• Major reorganization of internal module structure
• Various simplification of internals