decoders 2.0.0-beta1 → 2.0.0-beta5

package/{cjs/result.js → result.js}

@@ -8,13 +8,14 @@ exports.errValue = errValue;
 exports.expect = expect;
 exports.isErr = isErr;
 exports.isOk = isOk;
-exports.map = map;
 exports.mapError = mapError;
+exports.mapOk = mapOk;
 exports.ok = ok;
+exports.okOrErrValue = okOrErrValue;
+exports.okValue = okValue;
 exports.orElse = orElse;
 exports.toString = toString;
 exports.unwrap = unwrap;
-exports.value = value;
 exports.withDefault = withDefault;
 
 /**
@@ -29,7 +30,8 @@ exports.withDefault = withDefault;
 function ok(value) {
   return {
     type: 'ok',
-    value: value
+    value: value,
+    error: undefined
   };
 }
 /**
@@ -40,6 +42,7 @@ function ok(value) {
 function err(error) {
   return {
     type: 'err',
+    value: undefined,
     error: error
   };
 }
@@ -58,15 +61,23 @@ function isErr(result) {
 
 function withDefault(result, defaultValue) {
   return result.type === 'ok' ? result.value : defaultValue;
-}
+} // TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { value } = result;
+
 
-function value(result) {
+function okValue(result) {
   return result.type === 'ok' ? result.value : undefined;
-}
+} // TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { error } = result;
+
 
 function errValue(result) {
   return result.type === 'err' ? result.error : undefined;
 }
+
+function okOrErrValue(result) {
+  return result.type === 'ok' ? result.value : result.error;
+}
 /**
  * Unwrap the value from this Result instance if this is an "Ok" result.
  * Otherwise, will throw the "Err" error via a runtime exception.
@@ -159,7 +170,7 @@ function orElse(result1, lazyResult2) {
  */
 
 
-function map(result, mapper) {
+function mapOk(result, mapper) {
   return result.type === 'ok' ? ok(mapper(result.value)) : result;
 }
 /**

package/result.js.flow

@@ -0,0 +1,174 @@
+// @flow strict
+
+/**
+ * Result <value> <error>
+ *     = Ok <value>
+ *     | Err <error>
+ */
+
+type Ok<+T> = {| +type: 'ok', +value: T, +error: void |};
+type Err<+E> = {| +type: 'err', +value: void, +error: E |};
+
+export type Result<+T, +E> = Ok<T> | Err<E>;
+
+/**
+ * Create a new Result instance representing a successful computation.
+ */
+export function ok<T>(value: T): Ok<T> {
+    return { type: 'ok', value, error: undefined };
+}
+
+/**
+ * Create a new Result instance representing a failed computation.
+ */
+export function err<E>(error: E): Err<E> {
+    return { type: 'err', value: undefined, error };
+}
+
+export function toString(result: Result<mixed, mixed>): string {
+    return result.type === 'ok'
+        ? `Ok(${String(result.value)})`
+        : `Err(${String(result.error)})`;
+}
+
+export function isOk(result: Result<mixed, mixed>): boolean {
+    return result.type === 'ok';
+}
+
+export function isErr(result: Result<mixed, mixed>): boolean {
+    return result.type === 'err';
+}
+
+export function withDefault<T>(result: Result<T, mixed>, defaultValue: T): T {
+    return result.type === 'ok' ? result.value : defaultValue;
+}
+
+// TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { value } = result;
+export function okValue<T>(result: Result<T, mixed>): void | T {
+    return result.type === 'ok' ? result.value : undefined;
+}
+
+// TODO: Remove this from the public API? The same can be achieved now with
+// TODO: const { error } = result;
+export function errValue<E>(result: Result<mixed, E>): void | E {
+    return result.type === 'err' ? result.error : undefined;
+}
+
+export function okOrErrValue<T, E>(result: Result<T, E>): T | E {
+    return result.type === 'ok' ? result.value : result.error;
+}
+
+/**
+ * Unwrap the value from this Result instance if this is an "Ok" result.
+ * Otherwise, will throw the "Err" error via a runtime exception.
+ */
+export function unwrap<T>(result: Result<T, mixed>): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw result.error;
+    }
+}
+
+export function expect<T>(result: Result<T, mixed>, message: string | Error): T {
+    if (result.type === 'ok') {
+        return result.value;
+    } else {
+        throw message instanceof Error ? message : new Error(message);
+    }
+}
+
+export function dispatch<T, E, O>(
+    result: Result<T, E>,
+    okCallback: (value: T) => O,
+    errCallback: (error: E) => O,
+): O {
+    return result.type === 'ok' ? okCallback(result.value) : errCallback(result.error);
+}
+
+/**
+ * If the given result is OK, defers to the other result. Otherwise returns the
+ * error result.
+ *
+ * It's like saying A && B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)     && Result.ok('hi')    // => Ok('hi')
+ *     Result.err('boo') && Result.ok('hi')    // => Err('boo')
+ *     Result.ok(42)     && Result.err('boo')  // => Err('boo')
+ *     Result.err('boo') && Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function and<T, E, T2>(
+//     result1: Result<T, E>,
+//     result2: Result<T2, E>,
+// ): Result<T2, E> {
+//     return result1.type === 'ok' ? result2 : result1;
+// }
+
+/**
+ * If the given result is OK, return that result. Otherwise, defers to the
+ * other result.
+ *
+ * It's like saying A || B, but on Result.
+ *
+ * Examples:
+ *
+ *     Result.ok(42)      || Result.ok('hi')    // => Ok(42)
+ *     Result.err('boo')  || Result.ok('hi')    // => Ok('hi')
+ *     Result.ok(42)      || Result.err('boo')  // => Ok(42)
+ *     Result.err('bleh') || Result.err('boo')  // => Err('boo')
+ *
+ */
+// export function or<T, E, E2>(
+//     result1: Result<T, E>,
+//     result2: Result<T, E2>,
+// ): Result<T, E2> {
+//     return result1.type === 'ok' ? result1 : result2;
+// }
+
+/**
+ * Like .and(), aka &&, but the second argument gets evaluated lazily only if
+ * the first result is an Ok result. If so, it has access to the Ok value from
+ * the first argument.
+ */
+export function andThen<T, E, T2>(
+    result1: Result<T, E>,
+    lazyResult2: (value: T) => Result<T2, E>,
+): Result<T2, E> {
+    return result1.type === 'ok' ? lazyResult2(result1.value) : result1;
+}
+
+/**
+ * Like .or(), aka ||, but the second argument gets evaluated lazily only if
+ * the first result is an Err result. If so, it has access to the Err value
+ * from the first argument.
+ */
+export function orElse<T, E, E2>(
+    result1: Result<T, E>,
+    lazyResult2: (errValue: E) => Result<T, E2>,
+): Result<T, E2> {
+    return result1.type === 'ok' ? result1 : lazyResult2(result1.error);
+}
+
+/**
+ * Transform an Ok result. Will not touch Err results.
+ */
+export function mapOk<T, E, T2>(
+    result: Result<T, E>,
+    mapper: (value: T) => T2,
+): Result<T2, E> {
+    return result.type === 'ok' ? ok(mapper(result.value)) : result;
+}
+
+/**
+ * Transform an Err value. Will not touch Ok results.
+ */
+export function mapError<T, E, E2>(
+    result: Result<T, E>,
+    mapper: (error: E) => E2,
+): Result<T, E2> {
+    return result.type === 'ok' ? result : err(mapper(result.error));
+}

package/ts/_guard.d.ts

@@ -1,7 +0,0 @@
-import { Annotation } from './annotate';
-import { Decoder, Guard } from './_types';
-
-export function guard<T>(
-    decoder: Decoder<T>,
-    formatter?: (annotation: Annotation) => string,
-): Guard<T>;

package/ts/_helpers.d.ts

@@ -1,79 +0,0 @@
-/**
- * Given a type like:
- *
- *   {
- *     a: string;
- *     b: number | undefined;
- *     c: null | undefined;
- *     d: null;
- *     e: undefined;
- *   }
- *
- * Will drop all the "undefined" types. In this case, only "e":
- *
- *   {
- *     a: string;
- *     b: number | undefined;
- *     c: null | undefined;
- *     d: null;
- *   }
- *
- */
-type Compact<T> = { [K in IsDefined<T, keyof T>]: T[K] };
-
-type IsDefined<T, K extends keyof T> = K extends any
-    ? T[K] extends undefined
-        ? never
-        : K
-    : never;
-
-//
-// HACK:
-// These weird conditionals test whether TypeScript is configured with the
-// `strictNullChecks` compiler option. We use these definitions to influence
-// what's considered a "required" vs an "optional" key for the AllowImplicit
-// type.
-//
-// If strictNullChecks is false, then we should not be emitting any `?` fields
-// and consider all fields "required" because everything is optional by default
-// in that mode anyway.
-//
-type NoStrictNullChecks = undefined extends string ? 1 : undefined;
-//                        ^^^^^^^^^^^^^^^^^^^^^^^^
-type StrictNullChecks = undefined extends string ? undefined : 1;
-//                      ^^^^^^^^^^^^^^^^^^^^^^^^
-
-export type RequiredKeys<T> = keyof Compact<{
-    [K in keyof T]: undefined extends T[K] ? NoStrictNullChecks : 1;
-}>;
-
-export type OptionalKeys<T> = keyof Compact<{
-    [K in keyof T]: undefined extends T[K] ? 1 : StrictNullChecks;
-}>;
-
-/**
- * Transforms an object type, by marking all fields that contain "undefined"
- * with a question mark, i.e. allowing implicit-undefineds when
- * explicit-undefined are also allowed.
- *
- * For example, if:
- *
- *   type User = {
- *     name: string;
- *     age: number | null | undefined;
- *   }
- *
- * Then AllowImplicit<User> will become equivalent to:
- *
- *   {
- *     name: string;
- *     age?: number | null;
- *        ^
- *        Note the question mark
- *   }
- */
-type AllowImplicit<T> = { [K in RequiredKeys<T>]-?: T[K] } & {
-    [K in OptionalKeys<T>]+?: Exclude<T[K], undefined>;
-};
-
-export { AllowImplicit };

package/ts/_types.d.ts

@@ -1,16 +0,0 @@
-import { Annotation } from './annotate';
-import { Result } from './result';
-
-export type Scalar = string | number | boolean | symbol | undefined | null;
-
-export interface Guard<T> {
-    (blob: unknown): T;
-}
-export type Predicate<T> = (value: T) => boolean;
-export type DecodeResult<T> = Result<T, Annotation>;
-export interface Decoder<T, F = unknown> {
-    (blob: F): DecodeResult<T>;
-}
-
-export type DecoderType<T> = T extends Decoder<infer V> ? V : never;
-export type GuardType<T> = T extends Guard<infer V> ? V : never;

package/ts/_utils.d.ts

@@ -1,13 +0,0 @@
-import { Decoder } from './_types';
-
-export function isDate(value: unknown): boolean;
-export function map<T, V>(decoder: Decoder<T>, mapper: (value: T) => V): Decoder<V>;
-export function compose<T, V>(decoder: Decoder<T>, next: Decoder<V, T>): Decoder<V>;
-export function predicate<T extends F, F = unknown>(
-    predicate: (value: F) => value is T,
-    msg: string,
-): Decoder<T, F>;
-export function predicate<T>(
-    predicate: (value: T) => boolean,
-    msg: string,
-): Decoder<T, T>;

package/ts/annotate.d.ts

@@ -1,58 +0,0 @@
-export interface ObjectAnnotation {
-    type: 'object';
-    fields: { [key: string]: Annotation };
-    text?: string;
-}
-
-export interface ArrayAnnotation {
-    type: 'array';
-    items: readonly Annotation[];
-    text?: string;
-}
-
-export interface ScalarAnnotation {
-    type: 'scalar';
-    value: unknown;
-    text?: string;
-}
-
-export interface FunctionAnnotation {
-    type: 'function';
-    text?: string;
-}
-
-export interface CircularRefAnnotation {
-    type: 'circular-ref';
-    text?: string;
-}
-
-export type Annotation =
-    | ObjectAnnotation
-    | ArrayAnnotation
-    | ScalarAnnotation
-    | FunctionAnnotation
-    | CircularRefAnnotation;
-
-export function object(
-    fields: { [key: string]: Annotation },
-    text?: string,
-): ObjectAnnotation;
-export function array(items: readonly Annotation[], text?: string): ArrayAnnotation;
-export function func(text?: string): FunctionAnnotation;
-export function scalar(value: unknown, text?: string): ScalarAnnotation;
-export function circularRef(text?: string): CircularRefAnnotation;
-
-export function updateText<A extends Annotation>(annotation: A, text?: string): A;
-
-export function merge(
-    objAnnotation: ObjectAnnotation,
-    fields: { [key: string]: Annotation },
-): ObjectAnnotation;
-
-export function asAnnotation(thing: unknown): Annotation | void;
-
-export function annotate(value: unknown, text?: string): Annotation;
-export function annotateObject(
-    obj: { [key: string]: unknown },
-    text?: string,
-): ObjectAnnotation;

package/ts/array.d.ts

@@ -1,5 +0,0 @@
-import { Decoder } from '../_types';
-
-export const poja: Decoder<unknown[]>;
-export function array<T>(decoder: Decoder<T>): Decoder<T[]>;
-export function nonEmptyArray<T>(decoder: Decoder<T>): Decoder<[T, ...T[]]>;

package/ts/boolean.d.ts

@@ -1,5 +0,0 @@
-import { Decoder } from '../_types';
-
-export const boolean: Decoder<boolean>;
-export const truthy: Decoder<boolean>;
-export const numericBoolean: Decoder<boolean>;

package/ts/constants.d.ts

@@ -1,11 +0,0 @@
-import { Decoder, Scalar } from '../_types';
-
-// Constants
-
-export const null_: Decoder<null>;
-export const undefined_: Decoder<undefined>;
-export function constant<T extends Scalar>(value: T): Decoder<T>;
-export function hardcoded<T extends Scalar>(value: T): Decoder<T>;
-export function hardcoded<T>(value: T): Decoder<T>;
-export const mixed: Decoder<unknown>;
-export const unknown: Decoder<unknown>;

package/ts/date.d.ts

@@ -1,4 +0,0 @@
-import { Decoder } from '../_types';
-
-export const date: Decoder<Date>;
-export const iso8601: Decoder<Date>;

package/ts/describe.d.ts

@@ -1,3 +0,0 @@
-import { Decoder } from '../_types';
-
-export function describe<T>(decoder: Decoder<T>, msg: string): Decoder<T>;

package/ts/dispatch.d.ts

@@ -1,8 +0,0 @@
-import { Decoder, DecoderType } from '../_types';
-
-export type $Values<T extends object> = T[keyof T];
-
-export function dispatch<O extends { [key: string]: Decoder<any> }>(
-    field: string,
-    mapping: O,
-): Decoder<$Values<{ [key in keyof O]: DecoderType<O[key]> }>>;

package/ts/either.d.ts

@@ -1,61 +0,0 @@
-import { Decoder, Scalar } from '../_types';
-
-export function either<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-export function either2<T1, T2>(d1: Decoder<T1>, d2: Decoder<T2>): Decoder<T1 | T2>;
-export function either3<T1, T2, T3>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-): Decoder<T1 | T2 | T3>;
-export function either4<T1, T2, T3, T4>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-): Decoder<T1 | T2 | T3 | T4>;
-export function either5<T1, T2, T3, T4, T5>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-): Decoder<T1 | T2 | T3 | T4 | T5>;
-export function either6<T1, T2, T3, T4, T5, T6>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6>;
-export function either7<T1, T2, T3, T4, T5, T6, T7>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7>;
-export function either8<T1, T2, T3, T4, T5, T6, T7, T8>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8>;
-export function either9<T1, T2, T3, T4, T5, T6, T7, T8, T9>(
-    d1: Decoder<T1>,
-    d2: Decoder<T2>,
-    d3: Decoder<T3>,
-    d4: Decoder<T4>,
-    d5: Decoder<T5>,
-    d6: Decoder<T6>,
-    d7: Decoder<T7>,
-    d8: Decoder<T8>,
-    d9: Decoder<T9>,
-): Decoder<T1 | T2 | T3 | T4 | T5 | T6 | T7 | T8 | T9>;
-export function oneOf<T extends Scalar>(constants: readonly T[]): Decoder<T>;

package/ts/fail.d.ts

@@ -1,3 +0,0 @@
-import { Decoder } from '../_types';
-
-export function fail(msg: string): Decoder<never>;

package/ts/index.d.ts

@@ -1,42 +0,0 @@
-export { Decoder, Guard } from './_types';
-export { DecoderType, GuardType } from './_types';
-
-export { guard } from './_guard';
-export { compose, map, predicate } from './_utils';
-
-export { JSONArray, JSONObject, JSONValue } from './stdlib/json';
-
-export { array, nonEmptyArray, poja } from './stdlib/array';
-export { boolean, numericBoolean, truthy } from './stdlib/boolean';
-export {
-    constant,
-    hardcoded,
-    mixed,
-    null_,
-    undefined_,
-    unknown,
-} from './stdlib/constants';
-export { date, iso8601 } from './stdlib/date';
-export { describe } from './stdlib/describe';
-export { dispatch } from './stdlib/dispatch';
-export {
-    either,
-    either3,
-    either4,
-    either5,
-    either6,
-    either7,
-    either8,
-    either9,
-    oneOf,
-} from './stdlib/either';
-export { fail } from './stdlib/fail';
-export { instanceOf } from './stdlib/instanceOf';
-export { json, jsonArray, jsonObject } from './stdlib/json';
-export { lazy } from './stdlib/lazy';
-export { mapping, dict } from './stdlib/mapping';
-export { integer, number, positiveInteger, positiveNumber } from './stdlib/number';
-export { exact, inexact, object, pojo } from './stdlib/object';
-export { maybe, nullable, optional } from './stdlib/optional';
-export { email, nonEmptyString, regex, string, url } from './stdlib/string';
-export { tuple1, tuple2, tuple3, tuple4, tuple5, tuple6 } from './stdlib/tuple';

package/ts/inline.d.ts

@@ -1,3 +0,0 @@
-import { Annotation } from '../annotate';
-
-export function formatInline(ann: Annotation): string;

package/ts/instanceOf.d.ts

@@ -1,3 +0,0 @@
-import { Decoder } from '../_types';
-
-export function instanceOf<T>(klass: new (...args: any) => T): Decoder<T>;

package/ts/json.d.ts

@@ -1,11 +0,0 @@
-import { Decoder } from '../_types';
-
-export type JSONValue = null | string | number | boolean | JSONObject | JSONArray;
-export interface JSONObject {
-    [key: string]: JSONValue;
-}
-export type JSONArray = JSONValue[];
-
-export const json: Decoder<JSONValue>;
-export const jsonArray: Decoder<JSONArray>;
-export const jsonObject: Decoder<JSONObject>;

package/ts/lazy.d.ts

@@ -1,3 +0,0 @@
-import { Decoder } from '../_types';
-
-export function lazy<T>(decoderFn: () => Decoder<T>): Decoder<T>;

package/ts/mapping.d.ts

@@ -1,4 +0,0 @@
-import { Decoder } from '../_types';
-
-export function mapping<T>(decoder: Decoder<T>): Decoder<Map<string, T>>;
-export function dict<T>(decoder: Decoder<T>): Decoder<{ [key: string]: T }>;

package/ts/number.d.ts

@@ -1,6 +0,0 @@
-import { Decoder } from '../_types';
-
-export const integer: Decoder<number>;
-export const number: Decoder<number>;
-export const positiveInteger: Decoder<number>;
-export const positiveNumber: Decoder<number>;

package/ts/object.d.ts

@@ -1,33 +0,0 @@
-import { Decoder, DecoderType } from '../_types';
-import { AllowImplicit } from './_helpers';
-
-export type ObjectDecoderType<T> = AllowImplicit<{
-    [key in keyof T]: DecoderType<T[key]>;
-}>;
-
-export const pojo: Decoder<{ [key: string]: unknown }>;
-
-export function object<O extends { [key: string]: Decoder<any> }>(
-    mapping: O,
-): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
-//         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-//         This is basically just equivalent to:
-//             ObjectDecoderType<O>
-//
-//         But by "resolving" this with a mapped type, we remove the helper
-//         type names from the inferred type here, making this much easier to
-//         work with while developing.
-
-export function exact<O extends { [key: string]: Decoder<any> }>(
-    mapping: O,
-): Decoder<{ [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] }>;
-//         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-//         Ditto (see above)
-
-export function inexact<O extends { [key: string]: Decoder<any> }>(
-    mapping: O,
-): Decoder<
-    { [K in keyof ObjectDecoderType<O>]: ObjectDecoderType<O>[K] } & {
-        [extra: string]: unknown;
-    }
->;

package/ts/optional.d.ts

@@ -1,5 +0,0 @@
-import { Decoder } from '../_types';
-
-export function optional<T>(decoder: Decoder<T>): Decoder<T | undefined>;
-export function nullable<T>(decoder: Decoder<T>): Decoder<T | null>;
-export function maybe<T>(decoder: Decoder<T>): Decoder<T | null | undefined>;