DEPRECATION NOTICE!

This is just a README update release.

The functionality of ts-string-visitor has been merged into ts-enum-util (npm, github), and improved to support visiting/mapping numeric literal/enum values!

There will be no further development on ts-string-visitor. Consider switching to ts-enum-util,
unless you are stuck with TypeScript version prior to 2.9 (2.9 is minimum version supported by ts-enum-util v4+ with Value Visitor/Mapper functionality). There is a migration guide link in the ts-enum-util README to
help you with the transition.

New Feature: Explicitly Unhandled Values

It is now possible to indicate that some values in your string visitor/mapper interface implementation are "unhandled", such that an error will be thrown if that value is encountered. See the README for details.

This is a major version bump due to:

• Minimum supported TypeScript version increasing from 2.4 to 2.7 (due to use of unique symbol type).
• Added requirement for ES6 Symbol (use a polyfill if you target environments without native support).

Otherwise, there are no breaking changes to the behavior or API of ts-enum-util itself.

Also confirmed compatibility with TypeScript 3.0.1!

Declaration Source Maps

Source maps are now generated and distributed for the TypeScript declaration files.

Minor README Update

Added links to my new ts-enum-util project in the README.

Bug Fix

This release fixes a bug where an unexpected value at run time that matches the name of a property on Object.prototype would not be properly detected as an "unexpected" value. See this pull request for more details: #9

Confirmed Compatibility with TypeScript 2.7.1

Mostly a minor documentation update. The project is now compiled/tested with TypeScript 2.7.1, confirming that #3 is no longer a problem.

Handle Unexpected Values at Runtime!

New Feature

visitString() and mapString() now detect unexpected values at run time and throw a descriptive error. You may optionally override this behavior by providing a handleUnexpected handler in your visitor/mapper implementation. This is useful for handling values from an external source (e.g., response data from an API) where there's no 100% guarantee that values will always match your string enum or string literal union type.

New Simplified Value Mapping!

New Feature

Sometimes a visitor pattern is overkill when you just want to map your input value to an output value without any additional logic. The new mapString() function provides the same compile-time checks as visitString(), but allows you to skip the overhead of creating a function for each value:

import { mapString } from "ts-string-visitor";

type RGB = "r" | "g" | "b";

// Example function that uses mapString() to convert a RGB value
// to a display label
function getRgbLabel(rgb: RGB): string {
    return mapString(rgb).with({
        "r": "Red",
        "g": "Green",
        "b": "Blue"
    });
}

const result = getRgbLabel("g"); // result === "Green"

Breaking Change (reason for major version bump)

Now that ts-string-visitor exports more than one function, I have removed the default export.

If you previously imported visitString like this:

import visitString from "ts-string-visitor";

You must change it to this style:

import { visitString } from "ts-string-visitor";

NOTE: There are no changes to how visitString() works; only how it is exported.

README Typo Fix

A rather important typo fix in the README: I made reference to TypeScript version < 4.1.0 as being unsupported. It should have been 2.4.1.

Other behind-the-scenes changes in this release include a major rework to the unit tests so that many example usages of visitString are confirmed to either pass or fail compilation as expected.

NPM Dependency Fix

I mistakenly had "tslint-strict-null-checks" listed as a dependency. I now fixed it to be a devDependency.