prague - npm Package Compare versions

Comparing version 0.21.2 to 0.22.0

lib/src/actionReference.d.ts

@@ -31,4 +31,4 @@ import { Result } from './prague';
     constructor(actions: (...contextargs: CONTEXTARGS) => ACTIONS);
-    toAction<RESULT extends Result | undefined>(...contextargs: CONTEXTARGS): import("./core").Transform<[RESULT], import("./core").Action | (import("./core").BaseType<RESULT> extends null | undefined ? never : import("./core").BaseType<RESULT> extends Result ? import("./core").BaseType<RESULT> : import("./core").BaseType<RESULT> extends () => any ? import("./core").Action : import("./core").Match<import("./core").BaseType<RESULT>>)>;
+    toAction(...contextargs: CONTEXTARGS): import("./core").Transform<[Result], Result | import("./core").Action | null>;
 }
 export {};

lib/src/actionReference.js

@@ -35,9 +35,6 @@ "use strict";
     toAction(...contextargs) {
-        return prague_1.from((result) => {
-            if (result instanceof ActionReference) {
-                const action = this.actions(...contextargs)[result.name];
-                if (action)
-                    return () => action(...result.args);
-            }
-            return result;
+        return prague_1.transformResult(ActionReference, result => {
+            const action = this.actions(...contextargs)[result.name];
+            if (action)
+                return () => action(...result.args);
         });
@@ -44,0 +41,0 @@ }

lib/src/core.d.ts

@@ -11,2 +11,10 @@ import { Observable } from 'rxjs';
 }
+export declare const transformToNull: () => Observable<null>;
+export declare const filterOutNull: import("rxjs/internal/types").MonoTypeOperatorFunction<Result>;
+export declare const nullIfEmpty: import("rxjs/internal/types").MonoTypeOperatorFunction<null>;
+export declare type Output = Result | null;
+export declare type Nullable<T> = T extends null ? null : never;
+export interface ResultClass<T extends Result> {
+    new (...args: any[]): T;
+}
 export declare class Action extends Result {
@@ -20,6 +28,6 @@ action: () => Observable<any>;
 }
-declare type NormalizedResult<R> = R extends never | undefined | null ? never : R extends Result ? R : R extends () => any ? Action : Value<R>;
-export declare type Norm<R> = NormalizedResult<BaseType<R>>;
-export declare type Transform<ARGS extends any[], RESULT extends Result> = (...args: ARGS) => Observable<RESULT>;
-export declare function from<ARGS extends any[] = [], R = never>(transform?: null | ((...args: ARGS) => R)): Transform<ARGS, Norm<R>>;
+declare type NormalizedOutput<O> = O extends undefined | null ? null : O extends Result ? O : O extends () => any ? Action : Value<O>;
+export declare type Norm<O> = NormalizedOutput<BaseType<O>>;
+export declare type Transform<ARGS extends any[], OUTPUT extends Output> = (...args: ARGS) => Observable<OUTPUT>;
+export declare function from<ARGS extends any[] = [], O = null>(transform?: null | ((...args: ARGS) => O)): Transform<ARGS, Norm<O>>;
 export {};

lib/src/core.js

@@ -25,2 +25,6 @@ "use strict";
 exports.Result = Result;
+// null is the "No Result"
+exports.transformToNull = () => rxjs_1.of(null);
+exports.filterOutNull = operators_1.filter((o) => o !== null);
+exports.nullIfEmpty = operators_1.defaultIfEmpty(null);
 class Action extends Result {
@@ -42,13 +46,13 @@ constructor(action, score) {
 exports.Value = Value;
-const returnsEmpty = () => rxjs_1.empty();
 function from(transform) {
     if (!transform)
-        return returnsEmpty;
+        return exports.transformToNull;
     if (typeof transform !== 'function')
         throw new Error("I can't transform that.");
-    return (...args) => rxjs_1.of(transform).pipe(operators_1.map(transform => transform(...args)), operators_1.flatMap(exports.toObservable), operators_1.flatMap(result => result == null ? rxjs_1.empty() : rxjs_1.of(result instanceof Result ? result :
-        typeof result === 'function' ? new Action(result) :
-            new Value(result))));
+    return (...args) => rxjs_1.of(transform).pipe(operators_1.map(transform => transform(...args)), operators_1.flatMap(exports.toObservable), operators_1.map(o => o == null ? null :
+        o instanceof Result ? o :
+            typeof o === 'function' ? new Action(o) :
+                new Value(o)));
 }
 exports.from = from;
 //# sourceMappingURL=core.js.map

lib/src/first.d.ts

 import { Result, Transform, Norm } from "./prague";
-export declare function first(): Transform<[], never>;
+export declare function first(): Transform<[], null>;
 export declare function first<ARGS extends any[] = [], R0 = never>(...args: [null | undefined | ((...args: ARGS) => R0)]): Transform<ARGS, Norm<R0>>;
-export declare function first<ARGS extends any[] = [], R0 = never, R1 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1)]): Transform<ARGS, Norm<R0 | R1>>;
-export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2)]): Transform<ARGS, Norm<R0 | R1 | R2>>;
-export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never, R3 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2), null | undefined | ((...args: ARGS) => R3)]): Transform<ARGS, Norm<R0 | R1 | R2 | R3>>;
-export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never, R3 = never, R4 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2), null | undefined | ((...args: ARGS) => R3), null | undefined | ((...args: ARGS) => R4)]): Transform<ARGS, Norm<R0 | R1 | R2 | R3 | R4>>;
+export declare function first<ARGS extends any[] = [], R0 = never, R1 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1)]): Transform<ARGS, Norm<NonNullable<R0> | R1>>;
+export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2)]): Transform<ARGS, Norm<NonNullable<R0 | R1> | R2>>;
+export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never, R3 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2), null | undefined | ((...args: ARGS) => R3)]): Transform<ARGS, Norm<NonNullable<R0 | R1 | R2> | R3>>;
+export declare function first<ARGS extends any[] = [], R0 = never, R1 = never, R2 = never, R3 = never, R4 = never>(...args: [null | undefined | ((...args: ARGS) => R0), null | undefined | ((...args: ARGS) => R1), null | undefined | ((...args: ARGS) => R2), null | undefined | ((...args: ARGS) => R3), null | undefined | ((...args: ARGS) => R4)]): Transform<ARGS, Norm<NonNullable<R0 | R1 | R2 | R3> | R4>>;
 export declare function first<ARGS extends any[] = []>(...args: (null | undefined | ((...args: ARGS) => any))[]): Transform<ARGS, Result>;

lib/src/first.js

@@ -6,11 +6,13 @@ "use strict";
 const operators_1 = require("rxjs/operators");
+const core_1 = require("./core");
 function first(...transforms) {
-    const _transforms = rxjs_1.from(transforms.map(transform => prague_1.from(transform)));
-    return (...args) => _transforms.pipe(
-    // we put concatMap here because it forces everything to after it to execute serially
-    operators_1.concatMap(transform => transform(...args)), 
-    // Stop when one emits a result
-    operators_1.take(1));
+    return transforms.length === 0
+        ? core_1.transformToNull
+        : prague_1.from((...args) => rxjs_1.from(transforms.map(transform => prague_1.from(transform))).pipe(
+        // we put concatMap here because it forces everything to after it to execute serially
+        operators_1.concatMap(transform => transform(...args)), prague_1.filterOutNull, 
+        // Stop when one emits a result
+        operators_1.take(1), prague_1.filterOutNull));
 }
 exports.first = first;
 //# sourceMappingURL=first.js.map

lib/src/matching.d.ts

 import { Observableable, Value } from './prague';
-export declare function match<ARGS extends any[], VALUE, ONMATCH, ONNOMATCH>(getMatch: (...args: ARGS) => Observableable<null | undefined | VALUE | Value<VALUE>>, onMatch: (value: Value<VALUE>) => ONMATCH, onNoMatch?: () => ONNOMATCH): import("./core").Transform<ARGS, import("./core").Result | (import("./core").BaseType<ONNOMATCH> extends null | undefined ? never : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Value<import("./core").BaseType<ONNOMATCH>>)>;
-declare function _if<ARGS extends any[], ONTRUE, ONFALSE>(predicate: (...args: ARGS) => any, onTrue: () => ONTRUE, onFalse?: () => ONFALSE): import("./core").Transform<ARGS, import("./core").Result | (import("./core").BaseType<ONFALSE> extends null | undefined ? never : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<ONFALSE>>)>;
-export { _if as if };
+export declare function match<ARGS extends any[], VALUE, ONVALUE, ONNULL = null>(getValue: (...args: ARGS) => Observableable<null | undefined | VALUE | Value<VALUE>>, onValue: (value: Value<VALUE>) => ONVALUE, onNull?: () => ONNULL): import("./core").Transform<ARGS, (ONVALUE extends null | undefined ? null : ONVALUE extends import("./core").Result ? ONVALUE : ONVALUE extends () => any ? import("./core").Action : Value<ONVALUE>) | (ONNULL extends null | undefined ? null : ONNULL extends import("./core").Result ? ONNULL : ONNULL extends () => any ? import("./core").Action : Value<ONNULL>) | ((VALUE extends null | undefined ? null : VALUE extends import("./core").Result ? VALUE : VALUE extends () => any ? import("./core").Action : Value<VALUE>) extends null | undefined ? null : (VALUE extends null | undefined ? null : VALUE extends import("./core").Result ? VALUE : VALUE extends () => any ? import("./core").Action : Value<VALUE>) extends import("./core").Result ? VALUE extends null | undefined ? null : VALUE extends import("./core").Result ? VALUE : VALUE extends () => any ? import("./core").Action : Value<VALUE> : (VALUE extends null | undefined ? null : VALUE extends import("./core").Result ? VALUE : VALUE extends () => any ? import("./core").Action : Value<VALUE>) extends () => any ? import("./core").Action : Value<VALUE extends null | undefined ? null : VALUE extends import("./core").Result ? VALUE : VALUE extends () => any ? import("./core").Action : Value<VALUE>>) | ((import("./core").BaseType<VALUE> extends null | undefined ? null : import("./core").BaseType<VALUE> extends import("./core").Result ? import("./core").BaseType<VALUE> : import("./core").BaseType<VALUE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE>>) extends null | undefined ? null : (import("./core").BaseType<VALUE> extends null | undefined ? null : import("./core").BaseType<VALUE> extends import("./core").Result ? import("./core").BaseType<VALUE> : import("./core").BaseType<VALUE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE>>) extends import("./core").Result ? import("./core").BaseType<VALUE> extends null | undefined ? null : import("./core").BaseType<VALUE> extends import("./core").Result ? import("./core").BaseType<VALUE> : import("./core").BaseType<VALUE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE>> : (import("./core").BaseType<VALUE> extends null | undefined ? null : import("./core").BaseType<VALUE> extends import("./core").Result ? import("./core").BaseType<VALUE> : import("./core").BaseType<VALUE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE>>) extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE> extends null | undefined ? null : import("./core").BaseType<VALUE> extends import("./core").Result ? import("./core").BaseType<VALUE> : import("./core").BaseType<VALUE> extends () => any ? import("./core").Action : Value<import("./core").BaseType<VALUE>>>) | null>;
+export declare function matchIf<ARGS extends any[], ONTRUTHY, ONFALSEY>(predicate: (...args: ARGS) => any, onTruthy: () => ONTRUTHY, onFalsey?: () => ONFALSEY): import("./core").Transform<ARGS, (ONTRUTHY extends null | undefined ? null : ONTRUTHY extends import("./core").Result ? ONTRUTHY : ONTRUTHY extends () => any ? import("./core").Action : Value<ONTRUTHY>) | (ONFALSEY extends null | undefined ? null : ONFALSEY extends import("./core").Result ? ONFALSEY : ONFALSEY extends () => any ? import("./core").Action : Value<ONFALSEY>) | Value<false> | Value<true> | null>;

lib/src/matching.js

@@ -6,23 +6,18 @@ "use strict";
 const prague_1 = require("./prague");
-const getMatchError = new Error("matching function should only return Value");
-function match(getMatch, onMatch, onNoMatch) {
-    return prague_1.first(prague_1.pipe(getMatch, prague_1.tap(result => {
-        if (!(result instanceof prague_1.Value))
-            throw getMatchError;
-    }), onMatch), onNoMatch);
+const getMatchError = new Error("getValue transform should only return Value or null");
+function match(getValue, onValue, onNull) {
+    return prague_1.from((...args) => prague_1.from(getValue)(...args).pipe(operators_1.map(o => {
+        if (o instanceof prague_1.Value)
+            return onValue(o);
+        if (o === null)
+            return onNull ? onNull() : o;
+        throw getMatchError;
+    })));
 }
 exports.match = match;
-const ifPredicateError = new Error("predicate must return true or false");
-function _if(predicate, onTrue, onFalse) {
-    return match(prague_1.pipe((...args) => rxjs_1.of(args).pipe(operators_1.map(args => predicate(...args)), operators_1.flatMap(prague_1.toObservable), operators_1.map(result => result instanceof prague_1.Value ? !!result.value : !!result)), result => {
-        if (result instanceof prague_1.Value) {
-            if (result.value === true)
-                return true;
-            if (result.value === false)
-                return undefined;
-        }
-        throw ifPredicateError;
-    }), onTrue, onFalse);
+const trueValue = new prague_1.Value(true);
+function matchIf(predicate, onTruthy, onFalsey) {
+    return match((...args) => rxjs_1.of(args).pipe(operators_1.map(args => predicate(...args)), operators_1.flatMap(prague_1.toObservable), operators_1.map(o => o instanceof prague_1.Value && !o.value || !o ? null : trueValue)), onTruthy, onFalsey);
 }
-exports.if = _if;
+exports.matchIf = matchIf;
 //# sourceMappingURL=matching.js.map

lib/src/pipe.d.ts

@@ -1,11 +0,12 @@
-import { Result, Transform, Norm } from "./prague";
+import { Result, Transform, Norm, Action, ResultClass, Output, Nullable } from "./prague";
 export declare function pipe<ARGS extends any[], R0>(...args: [(...args: ARGS) => R0]): Transform<ARGS, Norm<R0>>;
-export declare function pipe<ARGS extends any[], R0, R1>(...args: [(...args: ARGS) => R0, (arg: Norm<R0>) => R1]): Transform<ARGS, Norm<R1>>;
-export declare function pipe<ARGS extends any[], R0, R1, R2>(...args: [(...args: ARGS) => R0, (arg: Norm<R0>) => R1, (arg: Norm<R1>) => R2]): Transform<ARGS, Norm<R2>>;
-export declare function pipe<ARGS extends any[], R0, R1, R2, R3>(...args: [(...args: ARGS) => R0, (arg: Norm<R0>) => R1, (arg: Norm<R1>) => R2, (arg: Norm<R2>) => R3]): Transform<ARGS, Norm<R3>>;
-export declare function pipe<ARGS extends any[], R0, R1, R2, R3, R4>(...args: [(...args: ARGS) => R0, (arg: Norm<R0>) => R1, (arg: Norm<R1>) => R2, (arg: Norm<R2>) => R3, (arg: Norm<R2>) => R4]): Transform<ARGS, Norm<R4>>;
-export declare function pipe<ARGS extends any[]>(transform: (...args: ARGS) => any, ...transforms: ((result: any) => any)[]): Transform<ARGS, Result>;
-export declare const _tap: <RESULT extends Result>(fn: (result: RESULT) => any) => Transform<[RESULT], RESULT>;
+export declare function pipe<ARGS extends any[], R0, R1>(...args: [(...args: ARGS) => R0, (arg: NonNullable<Norm<R0>>) => R1]): Transform<ARGS, Nullable<Norm<R0>> | Norm<R1>>;
+export declare function pipe<ARGS extends any[], R0, R1, R2>(...args: [(...args: ARGS) => R0, (arg: NonNullable<Norm<R0>>) => R1, (arg: NonNullable<Norm<R1>>) => R2]): Transform<ARGS, Nullable<Norm<R0 | R1>> | Norm<R2>>;
+export declare function pipe<ARGS extends any[], R0, R1, R2, R3>(...args: [(...args: ARGS) => R0, (arg: NonNullable<Norm<R0>>) => R1, (arg: NonNullable<Norm<R1>>) => R2, (arg: NonNullable<Norm<R2>>) => R3]): Transform<ARGS, Nullable<Norm<R0 | R1 | R2>> | Norm<R3>>;
+export declare function pipe<ARGS extends any[], R0, R1, R2, R3, R4>(...args: [(...args: ARGS) => R0, (arg: NonNullable<Norm<R0>>) => R1, (arg: NonNullable<Norm<R1>>) => R2, (arg: NonNullable<Norm<R2>>) => R3, (arg: NonNullable<Norm<R2>>) => R4]): Transform<ARGS, Nullable<Norm<R0 | R1 | R2 | R3>> | Norm<R4>>;
+export declare function pipe<ARGS extends any[]>(transform: (...args: ARGS) => any, ...transforms: ((result: Result) => any)[]): Transform<ARGS, Output>;
+export declare const tap: <RESULT extends Result>(fn: (result: RESULT) => any) => Transform<[RESULT], RESULT>;
 export declare const log: Transform<[any], any>;
-export { _tap as tap };
+export declare const transformResult: <T extends Result, R>(TargetResult: ResultClass<T>, transform: (r: T) => R) => Transform<[Result], Result | (import("./core").BaseType<R> extends null | undefined ? null : import("./core").BaseType<R> extends Result ? import("./core").BaseType<R> : import("./core").BaseType<R> extends () => any ? Action : import("./core").Value<import("./core").BaseType<R>>)>;
+export declare const transformNull: <R>(transform: () => R) => Transform<[Output], Result | (import("./core").BaseType<R> extends null | undefined ? null : import("./core").BaseType<R> extends Result ? import("./core").BaseType<R> : import("./core").BaseType<R> extends () => any ? Action : import("./core").Value<import("./core").BaseType<R>>)>;
 export declare const run: Transform<[Result], Result>;

lib/src/pipe.js

@@ -7,13 +7,10 @@ "use strict";
 function pipe(transform, ...transforms) {
-    const _transforms = rxjs_1.from(transforms.map(_transform => prague_1.from(_transform)));
-    return (...args) => _transforms.pipe(operators_1.reduce((result$, _transform) => result$.pipe(operators_1.flatMap(result => _transform(result))), prague_1.from(transform)(...args)), operators_1.mergeAll());
+    return prague_1.from((...args) => rxjs_1.from(transforms.map(_transform => prague_1.from(_transform))).pipe(operators_1.reduce((result$, _transform) => result$.pipe(operators_1.flatMap(result => _transform(result)), prague_1.filterOutNull), prague_1.from(transform)(...args).pipe(prague_1.filterOutNull)), operators_1.mergeAll(), prague_1.nullIfEmpty));
 }
 exports.pipe = pipe;
-exports._tap = (fn) => (result) => rxjs_1.of(result).pipe(operators_1.map(result => fn(result)), operators_1.flatMap(prague_1.toObservable), operators_1.mapTo(result));
-exports.tap = exports._tap;
-exports.log = exports._tap(console.log);
-exports.run = exports._tap(result => {
-    if (result instanceof prague_1.Action)
-        return result.action();
-});
+exports.tap = (fn) => (result) => rxjs_1.of(result).pipe(operators_1.map(result => fn(result)), operators_1.flatMap(prague_1.toObservable), prague_1.nullIfEmpty, operators_1.mapTo(result));
+exports.log = exports.tap(console.log);
+exports.transformResult = (TargetResult, transform) => prague_1.from((r) => r instanceof TargetResult ? transform(r) : r);
+exports.transformNull = (transform) => prague_1.from((o) => o === null ? transform() : o);
+exports.run = exports.tap(exports.transformResult(prague_1.Action, action => action.action()));
 //# sourceMappingURL=pipe.js.map

lib/src/prague.d.ts

@@ -7,3 +7,2 @@ export * from './core';
 export * from './actionReference';
-export * from './noResult';
 export * from './util';

lib/src/prague.js

@@ -12,4 +12,3 @@ "use strict";
 __export(require("./actionReference"));
-__export(require("./noResult"));
 __export(require("./util"));
 //# sourceMappingURL=prague.js.map

lib/src/scoring.d.ts

@@ -1,2 +0,2 @@
-import { Result, Transform, Norm } from "./prague";
+import { Output, Transform, Norm, Result } from "./prague";
 export declare class Multiple extends Result {
@@ -11,3 +11,3 @@ results: Result[];
 export declare function sorted<ARGS extends any[], R0, R1, R2, R3, R4>(...transforms: [(...args: ARGS) => R0, (...args: ARGS) => R1, (...args: ARGS) => R2, (...args: ARGS) => R3, (...args: ARGS) => R4]): Transform<ARGS, Norm<R0 | R1 | R2 | R3 | R4> | Multiple>;
-export declare function sorted<ARGS extends any[]>(...args: ((...args: ARGS) => any)[]): Transform<ARGS, Result>;
+export declare function sorted<ARGS extends any[]>(...args: ((...args: ARGS) => any)[]): Transform<ARGS, Output>;
 export interface TopOptions {
@@ -18,2 +18,2 @@ maxResults?: number;
 export declare function top<RESULT extends Result>(options?: TopOptions): Transform<[RESULT], Result>;
-export declare function best<ARGS extends any[]>(...transforms: ((...args: ARGS) => any)[]): Transform<ARGS, Result>;
+export declare function best<ARGS extends any[]>(...transforms: ((...args: ARGS) => any)[]): Transform<ARGS, Output>;

lib/src/scoring.js

@@ -14,4 +14,5 @@ "use strict";
 function sorted(...transforms) {
-    const _transforms = rxjs_1.from(transforms.map(transform => prague_1.from(transform)));
-    return (...args) => _transforms.pipe(operators_1.flatMap(transform => transform(...args)), operators_1.flatMap(result => result instanceof Multiple ? rxjs_1.from(result.results) : rxjs_1.of(result)), operators_1.toArray(), operators_1.flatMap(results => results.length === 0 ? rxjs_1.empty() : rxjs_1.of(results.length === 1 ? results[0] : new Multiple(results.sort((a, b) => b.score - a.score)))));
+    return prague_1.from((...args) => rxjs_1.from(transforms.map(transform => prague_1.from(transform))).pipe(operators_1.flatMap(transform => transform(...args)), prague_1.filterOutNull, operators_1.flatMap(result => result instanceof Multiple ? rxjs_1.from(result.results) : rxjs_1.of(result)), operators_1.toArray(), operators_1.map(results => results.length === 0 ? null :
+        results.length === 1 ? results[0] :
+            new Multiple(results.sort((a, b) => b.score - a.score)))));
 }
@@ -23,10 +24,17 @@ exports.sorted = sorted;
     if (options) {
-        if (typeof options.maxResults === 'number')
+        if (options.maxResults) {
+            if (typeof options.maxResults !== 'number' || options.maxResults < 1)
+                throw new Error("maxResults must be a number >= 1");
             maxResults = options.maxResults;
-        if (typeof options.tolerance === 'number')
+        }
+        if (options.tolerance) {
+            if (typeof options.tolerance !== 'number' || options.tolerance < 0 || options.tolerance > 1)
+                throw new Error("tolerance must be a number >= 0 and <= 1");
             tolerance = options.tolerance;
+        }
     }
-    return prague_1.from((result) => result instanceof Multiple
-        ? rxjs_1.from(result.results).pipe(operators_1.takeWhile((m, i) => i < maxResults && m.score + tolerance >= result.results[0].score), operators_1.toArray(), operators_1.map(results => results.length === 1 ? results[0] : new Multiple(results)))
-        : result);
+    return prague_1.transformResult(Multiple, multiple => {
+        const highScore = multiple.results[0].score;
+        return rxjs_1.from(multiple.results).pipe(operators_1.takeWhile((m, i) => i < maxResults && m.score + tolerance >= highScore), operators_1.toArray(), operators_1.map(results => results.length === 1 ? results[0] : new Multiple(results)));
+    });
 }
@@ -33,0 +41,0 @@ exports.top = top;

package.json

 {
   "name": "prague",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "description": "EDSL for rules",
@@ -5,0 +5,0 @@ "main": "lib/src/prague.js",

README.md

@@ -0,4 +1,13 @@
+# Ideas
+
+## Spell out "magic" functions:
+
+arg => first(...)(arg)
+
+## Do "simple" Prague:
+
+
 # *Prague*
 
-An experimental rule system handy for games and conversational user interfaces. I thought of it as I walked around Prague on a sunny Spring day. **This is not an official Microsoft project.**
+A rule system handy for games and conversational user interfaces. I thought of it as I walked around the city of Prague on a sunny Spring day. **This is not an official Microsoft project.**
 
@@ -17,3 +26,3 @@ Major features of Prague:
 
-* clone or fork this repo
+* clone this repo
 * `npm install`
@@ -31,12 +40,12 @@ * `npm run build` (or `npm run watch` to build on file changes)
 ```ts
-type Transform<ARGS extends any[], RESULT extends Result> = (...args: ARGS) => Observable<RESULT>;
+type Transform<ARGS extends any[], OUTPUT extends Result | null> = (...args: ARGS) => Observable<OUTPUT>;
 ```
 
-A `Transform` is called with arguments as normal. If a transformation occurred, the resultant `Observable` emits a `Result` object and completes, oherwise it ompletes without emitting.
+A `Transform` function is called with arguments as normal. But instead of returning a result directly, it returns an object called an `Observable`. You subscribe to that object to get the result. If you're new to `Observable`s, you may want to read [Observables and Promises](#observables-and-promises), which has both a quick introduction to `Observable`s and also shows how to ignore them and just work with `Promise`s. 
 
-If you're new to `Observable`s and none of this makes sense to you, you may want to read [Obervables and Promises](#observables-and-promises), which has both a quick introduction to `Observable`s and also shows how to ignore them and just work with `Promise`s. 
+A `Transform` emits either `null` or a subclass of `Result`.
 
 ### `Result`
 
-`Result` is an abstract base class. The following two subclasses of `Result` are "core" to *Prague*:
+`Result` is an abstract base class. The following three subclasses of `Result` are "core" to *Prague*:
 * `Value<VALUE>` - contains a value of type VALUE
@@ -48,7 +57,6 @@ * `Action` - contains an action (function) to potentially execute at a future time
 * `Multiple` - contains an array of `Result`s
-* `NoResult` - a way to get a positive "no result" signal from a `Transform` using [emitNoResults](#noresult)
 
 ### `from`
 
-The `from` function allows you to write `Tranform`s more simply, by returning a value instead a `Value`, a function instead of an `Action`, `undefined`/`null` when nothing is to be emitted, or a `Promise` or a synchronous result instead of an `Observable`:
+The `from` function allows you to write `Tranform`s more simply, by returning a value instead a `Value`, a function instead of an `Action`, `undefined` instead of `null`, or a `Promise` or a synchronous result instead of an `Observable`:
 
@@ -58,4 +66,3 @@ ```ts
 
-const confirm = from((a: number) => () => 
-console.log(`You picked ${a.toString()}`));
+const confirm = from((a: number) => () => console.log(`You picked ${a.toString()}`));
 
@@ -66,10 +73,10 @@ const getName = from((a: string) => fetch(`url/${a}`).then(r => r.json()).then(r => r.name));
 ```ts
-const repeat = (a: string) => Rx.of.(new Value(a.repeat(5)));
+const repeat = (a: string) => Rx.of(new Value(a.repeat(5)));
 
 const confirm = (a: number) => Rx.of(new Action(() => console.log(`You picked ${a.toString()}`)));
 
-const getName = (a: string) => Rx.from(fetch(`url/${a}`).then(r => r.json()).then(r => new Value(r.someString)));
+const getName = (a: string) => Rx.from(fetch(`url/${a}`).then(r => r.json()).then(r => new Value(r.name)));
 ```
 
-For your convenience, `from` is automatically called every place you supply a `Transform`:
+For your convenience, `from` is automatically called every place a `Transform` is expected. For example:
 ```ts
@@ -94,7 +101,7 @@ first(
 
-You can compose `Transform`s together into a new transform using one of the following high-order functions, or create your own. In all the below helpers, your `Transform`s are automatically normalized via `from`.
+You can compose `Transform`s together into a new `Transform` using a variety of high-order functions included in *Prague*, or you can create your own.
 
 #### `first`
 
-`first` returns a new `Transform` which calls each of the supplied `Transform`s in turn. If one emits a `Result`, it stops and returns that. If none emit a `Result`, it doesn't either. 
+`first` returns a new `Transform` which calls each of the supplied `Transform`s in turn. If one emits a `Result`, it stops and emits that. If all emit `null`, it emits `null`.
 
@@ -112,10 +119,10 @@ ```ts
 fullName("Hao").subscribe(console.log);     // Value{ value: "Hao Luo" }
-fullName("Yomi").subscribe(console.log);    //
+fullName("Yomi").subscribe(console.log);    // null
 ```
 
-Note that all the `Transform`s have the same argument types. However you only need to declare the argument types for the first `Transform`. TypeScript will use those for the rest, and for the resultant `Transform`, automatically.
+Note that all the `Transform`s have the same argument types. However you only need to declare the argument types for the first `Transform`. TypeScript will use those for the rest, and for the resultant `Transform`, automatically. It will also complain if your `Transforms` have incompatibile argument types.
 
 #### `pipe`
 
-`pipe` returns a new `Transform` which calls each of the supplied `Transform`s in turn. You supply the arguments for the first, its `Result` is the argument for the second, and so on. If all of the `Transform`s emit a `Result`, the last one is the `Result` of the new `Transform`, otherwise it doesn't emit.
+`pipe` returns a new `Transform` which calls each of the supplied `Transform`s in turn. You supply the arguments for the first. If it emits a `Result`, that becomes the argument for the second, and so on. If any of the `Transform`s emit `null`, the new `Transform` stops and emits `null`. Otherwise the new `Transform` emits the `Result` emitted by the last `Transform`.
 
@@ -131,3 +138,3 @@ ```ts
 someAssemblyRequired("Kev", "in").subscribe(console.log);      // Value{ value: "Kevin Leung." }
-someAssemblyRequired("Yo", "mi").subscribe(console.log);       //
+someAssemblyRequired("Yo", "mi").subscribe(console.log);       // null
 ```
@@ -139,20 +146,5 @@
 
-Consider this `Transform`:
+`match(getValue, onValue, onNull)` returns a new `Transform` that calls `getValue`. If that emits a `Value`, it calls `onValue` with that value, and emits its output. If `getValue` emits `null`, `onNull` is called with no arguments, and the new `Transform` emits its output. If `onNull` is omitted, the new `Transform` emits `null` when `getValue` emits `null`.
 
 ```ts
-const greet = first(
-    pipe(
-        fullName,
-        m => `Nice to meet you, ${m.value}.`,
-    ),
-    () => `I don't know you.`,
-)
-
-greet("Kevin").subscribe(console.log);      // Value{ value: "Nice to meet you, Kevin Leung." }
-greet("Yomi").subscribe(console.log);      // Value{ value: "I don't know you." }
-```
-
-if `fullName` emits, we do one thing, otherwise we do another. This is a very common case, and the `match` helper is a little shorter and a lot more expressive. Here's the same `Transform`, rewritten with `match`:
-
-```ts
 import { match } from 'prague';
@@ -165,14 +157,15 @@
 );
+
+greet("Kevin").subscribe(console.log);     // Value{ value: "Nice to meet you, Kevin Leung." }
+greet("Yomi").subscribe(console.log);      // Value{ value: "I don't know you." }
 ```
 
-#### `if`
+#### `matchIf`
 
-`if` is a special case of `match` for the common case of testing a "truthy" predicate.
+`matchIf` is a special case of `match` for the common case of testing a "truthy" predicate.
 
-Pro Tip: Because `if` is a JavaScript reserved word, if you `import` *Prague* functions individually you'll need to rename it:
-
 ```ts
-import { if as _if } from 'prague';
+import { matchIf } from 'prague';
 
-const greet = _if(
+const greet = matchIf(
     (t: string) => t === "Bill",
@@ -183,4 +176,4 @@ () => `I greet you, my creator!`,
 
-greet("Bill")
-.subscribe(console.log); // Value{ value: "I greet you, my creator!" }
+greet("Bill").subscribe(console.log); // Value{ value: "I greet you, my creator!" }
+greet("Yomi").subscribe(console.log); // Value{ value: "Meh." }
 ```
@@ -190,3 +183,3 @@
 
-`tap` returns a `Transform` that executes a function but ignores its output, returning its original input. This is a great way to debug:
+`tap` returns a `Transform` that executes a function but ignores its output, returning the original input. This is a great way to debug:
 
@@ -203,2 +196,4 @@ ```ts
 
+This is common enough that *Prague* provides a helper called `log` which is equivalent to `tap(console.log)`.
+
 #### `Action` and `run`
@@ -218,4 +213,3 @@
 
-bot("Wassup")
-.subscribe(); // WAAAASSSUUUUUUP
+bot("Wassup").subscribe(); // WAAAASSSUUUUUUP
 ```
@@ -244,4 +238,3 @@
     }),
-)("Wassup")
-.subscribe(); // WAAAASSSUUUUUUP
+)("Wassup").subscribe(); // WAAAASSSUUUUUUP
 ```
@@ -255,4 +248,3 @@
     run,
-)("Wassup")
-.subscribe(); // WAAAASSSUUUUUUP
+)("Wassup").subscribe(); // WAAAASSSUUUUUUP
 ```
@@ -288,3 +280,3 @@
     ),
-    _if(
+    matchIf(
         t => t === "current time",
@@ -318,4 +310,3 @@ () => new Action(() => console.log(`The time is ${new Date().toLocaleTimeString()}`), .9),
     ...transforms
-)()
-.subscribe(console.log) // Value{ value: "hi", score: .75 }
+)().subscribe(console.log) // Value{ value: "hi", score: .75 }
 ```
@@ -332,4 +323,3 @@
 
-sortme()
-.subscribe(console.log); // Multiple{ results:[ /* all the results */ ] }
+sortme().subscribe(console.log); // Multiple{ results:[ /* all the results */ ] }
 ```
@@ -345,7 +335,6 @@
     top(),
-)()
-.subscribe(console.log); // Multiple{ results:[ Value{ value: "hi", score: .75 }, Value{ value: "hello", score: .75 }, ] }
+)().subscribe(console.log); // Multiple{ results:[ Value{ value: "hi", score: .75 }, Value{ value: "hello", score: .75 }, ] }
 ```
 
-To include "aloha" we can add a tolerance of 5%:
+To include "aloha" we can add a `tolerance` of 5%:
 
@@ -358,7 +347,6 @@ ```ts
     }),
-)()
-.subscribe(console.log); // Multiple{ results:[ Value{ value: "hi", score: .75 }, Value{ value: "hello", score: .75 }, Value{ value: "aloha", score: .70 }, ] }
+)().subscribe(console.log); // Multiple{ results:[ Value{ value: "hi", score: .75 }, Value{ value: "hello", score: .75 }, Value{ value: "aloha", score: .70 }, ] }
 ```
 
-We can set a tolerance of 1 (include all the results) but set the maximum results to 3. This will have the same effect as the above:
+We can set a `tolerance` of 1 (include all the results) but set the maximum results to 3. This will have the same effect as the above:
 
@@ -376,5 +364,5 @@ ```ts
 
-Increasing `tolerance` includes more items in the "high score". It defaults to `0`.
+Increasing `tolerance` includes more items in the "high score". It defaults to `0` and has a maximum value of `1`.
 
-Decreasing `maxResults` limits of the number of "high score" results retrieved. it defaults to `Number.POSITIVE_INFINITY`.
+Decreasing `maxResults` limits of the number of "high score" results retrieved. It defaults to `Number.POSITIVE_INFINITY` and has a minimum value of `1`.
 
@@ -409,3 +397,3 @@ In fact, `best` is just a special case of piping the results of `sorted` into `top`:
         result => {
-            // handle result (if there is one) here
+            // handle result here
         },
@@ -415,5 +403,2 @@ err => {
         },
-        () => {
-            // this is called when there are no more results, whether one was emitted or not
-        }
     )
@@ -428,10 +413,6 @@ ```
 fullName("Bill")
-    .toPromise() // returns a Promise<Result | undefined>
+    .toPromise() // returns a Promise<Value<string> | null>
     .then(
         result  => {
-            if (result === undefined) {
-                // No result was emitted
-            } else {
-                // handle result
-            }
+            // handle result here
         },
@@ -444,26 +425,2 @@ err => {
 
-### NoResult
-
-A quirk of `Observables` is that you don't automatically know if one emitted a value before completing:
-
-```ts
-fullName("Bill").subscribe(console.log); // Value{ value: "Bill Barnes" }
-fullName("Yomi").subscribe(console.log); // <crickets>
-```
-
-You can force a transform to always emit *something* by wrapping it in `emitNoResult` as follows:
-
-```ts
-import { NoResult, emitNoResult } from 'prague';
-
-const fullNameAlwaysEmits = emitNoResult(fullName);
-
-fullNameAlwaysEmits("Bill").subscribe(console.log); // Value{ value: "Bill Barnes" }
-fullNameAlwaysEmits("Yomi").subscribe(console.log); // NoResult{}
-```
-
-This is especially useful for writing unit tests for `Transform`s.
-
-(Another solution is to convert it to a `Promise` and check for an `undefined` result, as shown [above](#using-promises-instead).)
-
 ## Reference
@@ -475,6 +432,3 @@
 
-Some miscelaneous [samples](samples/test.ts) exist, but mostly tk.
+tk
 
-## Tests
-
-These are in the process of being ported from 0.19.1

No alert changes

Improved metrics

Total package byte prevSize

64541

increased by8.68%

Lines of code

400

increased by20.12%

Worsened metrics

Number of package files

27

decreased by-6.9%

Number of lines in readme file

408

decreased by-10.13%

No dependency changes