prague - npm Package Compare versions

Comparing version 0.20.3 to 0.21.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 ? undefined : 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<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>>)>;
 }
 export {};

lib/src/core.d.ts

@@ -19,6 +19,6 @@ import { Observable } from 'rxjs';
 }
-declare type NormalizedResult<R> = R extends undefined | null ? undefined : R extends Result ? R : R extends () => any ? Action : Match<R>;
+declare type NormalizedResult<R> = R extends undefined | null ? never : R extends Result ? R : R extends () => any ? Action : Match<R>;
 export declare type Norm<R> = NormalizedResult<BaseType<R>>;
-export declare type Transform<ARGS extends any[], RESULT extends Result | undefined> = (...args: ARGS) => Observable<RESULT>;
-export declare function from<ARGS extends any[] = [], R = undefined>(transform?: null | ((...args: ARGS) => R)): Transform<ARGS, Norm<R>>;
+export declare type Transform<ARGS extends any[], RESULT extends Result> = (...args: ARGS) => Observable<RESULT>;
+export declare function from<ARGS extends any[], R>(transform?: null | ((...args: ARGS) => R)): Transform<ARGS, Norm<R>>;
 export {};

lib/src/core.js

@@ -41,3 +41,3 @@ "use strict";
 exports.Match = Match;
-const none = () => rxjs_1.of(undefined);
+const none = () => rxjs_1.empty();
 function from(transform) {
@@ -48,13 +48,7 @@ if (!transform)
         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.map(result => {
-        if (result instanceof Result)
-            return result;
-        if (result == null)
-            return undefined;
-        if (typeof result === 'function')
-            return new Action(result);
-        return new Match(result);
-    }));
+    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 Match(result))));
 }
 exports.from = from;
 //# sourceMappingURL=core.js.map

lib/src/first.d.ts

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

lib/src/first.js

@@ -10,6 +10,4 @@ "use strict";
     // we put concatMap here because it forces everything to after it to execute serially
-    operators_1.concatMap((transform, i) => transform(...args).pipe(
-    // ignore every undefined but the last one
-    operators_1.filter(result => i === transforms.length - 1 || result !== undefined))), 
-    // Stop when we find one that matches
+    operators_1.concatMap(transform => transform(...args)), 
+    // Stop when one emits a result
     operators_1.take(1));
@@ -16,0 +14,0 @@ }

lib/src/matching.d.ts

 import { Observableable, Match } from './prague';
-export declare function match<ARGS extends any[], VALUE, ONMATCH, ONNOMATCH>(getMatch: (...args: ARGS) => Observableable<null | undefined | VALUE | Match<VALUE>>, onMatch: (match: Match<VALUE>) => ONMATCH, onNoMatch?: () => ONNOMATCH): import("./core").Transform<ARGS, import("./core").Result | Exclude<(import("./core").BaseType<ONNOMATCH> extends null | undefined ? undefined : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH>>) extends null | undefined ? undefined : (import("./core").BaseType<ONNOMATCH> extends null | undefined ? undefined : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH>>) extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> extends null | undefined ? undefined : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH>> : (import("./core").BaseType<ONNOMATCH> extends null | undefined ? undefined : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH>>) extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH> extends null | undefined ? undefined : import("./core").BaseType<ONNOMATCH> extends import("./core").Result ? import("./core").BaseType<ONNOMATCH> : import("./core").BaseType<ONNOMATCH> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONNOMATCH>>>, undefined>>;
-declare function _if<ARGS extends any[], ONTRUE, ONFALSE>(predicate: (...args: ARGS) => any, onTrue: () => ONTRUE, onFalse?: () => ONFALSE): import("./core").Transform<ARGS, import("./core").Result | Exclude<(import("./core").BaseType<ONFALSE> extends null | undefined ? undefined : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE>>) extends null | undefined ? undefined : (import("./core").BaseType<ONFALSE> extends null | undefined ? undefined : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE>>) extends import("./core").Result ? import("./core").BaseType<ONFALSE> extends null | undefined ? undefined : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE>> : (import("./core").BaseType<ONFALSE> extends null | undefined ? undefined : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE>>) extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE> extends null | undefined ? undefined : import("./core").BaseType<ONFALSE> extends import("./core").Result ? import("./core").BaseType<ONFALSE> : import("./core").BaseType<ONFALSE> extends () => any ? import("./core").Action : Match<import("./core").BaseType<ONFALSE>>>, undefined>>;
+export declare function match<ARGS extends any[], VALUE, ONMATCH, ONNOMATCH>(getMatch: (...args: ARGS) => Observableable<null | undefined | VALUE | Match<VALUE>>, onMatch: (match: Match<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 : Match<import("./core").BaseType<ONNOMATCH>>) extends null | undefined ? never : (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 : Match<import("./core").BaseType<ONNOMATCH>>) extends 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 : Match<import("./core").BaseType<ONNOMATCH>> : (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 : Match<import("./core").BaseType<ONNOMATCH>>) extends () => any ? import("./core").Action : Match<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 : Match<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 : Match<import("./core").BaseType<ONFALSE>>) extends null | undefined ? never : (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 : Match<import("./core").BaseType<ONFALSE>>) extends 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 : Match<import("./core").BaseType<ONFALSE>> : (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 : Match<import("./core").BaseType<ONFALSE>>) extends () => any ? import("./core").Action : Match<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 : Match<import("./core").BaseType<ONFALSE>>>)>;
 export { _if as if };

lib/src/pipe.d.ts

@@ -7,5 +7,6 @@ import { Result, Transform, Norm } from "./prague";
 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, ...functions: ((...args: any[]) => any)[]): Transform<ARGS, Result | undefined>;
-export declare const _tap: <RESULT extends Result | undefined>(fn: (route: RESULT) => any) => Transform<[RESULT], RESULT>;
+export declare function pipe<ARGS extends any[]>(transform: (...args: ARGS) => any, ...functions: ((...args: any[]) => any)[]): Transform<ARGS, Result>;
+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 run: Transform<[Result | undefined], Result | undefined>;
+export declare const run: Transform<[Result], Result>;

lib/src/pipe.js

@@ -8,7 +8,8 @@ "use strict";
     const _transforms = rxjs_1.from(transforms.map(transform => prague_1.from(transform)));
-    return (...args) => _transforms.pipe(operators_1.reduce((args$, transform) => args$.pipe(operators_1.flatMap(args => args ? transform(...args) : rxjs_1.of(args)), operators_1.map(result => result && [result])), rxjs_1.of(args)), operators_1.mergeAll(), operators_1.map(results => results && results[0]));
+    return (...args) => _transforms.pipe(operators_1.reduce((args$, transform) => args$.pipe(operators_1.flatMap(args => args instanceof prague_1.Result ? transform(args) : transform(...args))), rxjs_1.of(args)), operators_1.mergeAll());
 }
 exports.pipe = pipe;
-exports._tap = (fn) => (route) => rxjs_1.of(route).pipe(operators_1.map(route => fn(route)), operators_1.flatMap(prague_1.toObservable), operators_1.mapTo(route));
+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 => {
@@ -15,0 +16,0 @@ if (result instanceof prague_1.Action)

lib/src/scoring.js

@@ -15,7 +15,3 @@ "use strict";
     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 === undefined ? rxjs_1.empty() :
-        result instanceof Multiple ? rxjs_1.from(result.results) :
-            rxjs_1.of(result)), operators_1.toArray(), operators_1.flatMap(results => rxjs_1.from(results.sort((a, b) => b.score - a.score)).pipe(operators_1.toArray(), operators_1.map(results => results.length === 0 ? undefined :
-        results.length === 1 ? results[0] :
-            new Multiple(results)))));
+    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)))));
 }
@@ -22,0 +18,0 @@ exports.sorted = sorted;

package.json

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

README.md

@@ -1,2 +0,2 @@
-# Prague
+# *Prague*
 
@@ -10,3 +10,3 @@ 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.**
 
-Some types of applications you could build with Prague:
+Some types of applications you could build with *Prague*:
 * OS shell
@@ -16,3 +16,3 @@ * Chat bot
 
-## Building Prague
+## Building *Prague*
 
@@ -26,26 +26,24 @@ * clone or fork this repo
 
-## Prague Essentials
+## *Prague* Essentials
 
 ### `Transform`
-The fundamental unit of Prague is a *Transform*:
+The fundamental unit of *Prague* is a `Transform`:
 
 ```ts
-type Transform<ARGS extends any[], RESULT | undefined> = (...args: ARGS) => Observable<RESULT | undefined>;
+type Transform<ARGS extends any[], RESULT extends Result> = (...args: ARGS) => Observable<RESULT>;
 ```
 
-A Transform returns an `Observable` of either: 
-* `undefined`, meaning no transformation occurred (i.e. the rule was not satisfied), or
-* a subclass of the abstract base class `Result`
+If a transformation occurred, the `Transform` emits a `Result` object. If no transformation occurred, nothing is emitted.
 
 ### `Result`
 
-The following `Result` subclasses are built in, but you can provide your own:
+`Result` is an abstract base class. The following subclasses of `Result` are built in, but you can provide your own:
 * `Match<VALUE>` - a value
 * `Action` - a function to execute at a future time
 * `ActionReference` - a serializable reference to a function to execute at a future time
-* `Multiple` - an array of `Result`s (typically the result of a tie) to be disambiguated
+* `Multiple` - an array of `Result`s
 
 ### `from`
 
-The `from` function allows you to write Tranforms more simply, by returning a value instead a `Match`, a function instead of an `Action`, 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 `Match`, 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`:
 
@@ -67,11 +65,10 @@ ```ts
 const getName = (a: string) => Rx.from(fetch(`url/${a}`).then(r => r.json()).then(r => new Match(r.someString)));
-
 ```
 
-For your convenience, `from` is automatically called every place you supply a Transform:
+For your convenience, `from` is automatically called every place you supply a `Transform`:
 ```ts
 first(
-    (t: string) => t === "Bill" ? "Bill Barnes" : undefined,
-    t => t === "Hao" ? "Hao Luo" : undefined,
-    t => t === "Kevin" ? "Kevin Leung" : undefined,
+    (t: string) => t === "Bill" ? "Bill Barnes" : null,
+    t => t === "Hao" ? "Hao Luo" : null,
+    t => t === "Kevin" ? "Kevin Leung" : null,
 )
@@ -82,5 +79,5 @@ ```
 first(
-    from((t: string) => t === "Bill" ? "Bill Barnes" : undefined),
-    from(t => t === "Hao" ? "Hao Luo" : undefined),
-    from(t => t === "Kevin" ? "Kevin Leung" : undefined),
+    from((t: string) => t === "Bill" ? "Bill Barnes" : null),
+    from(t => t === "Hao" ? "Hao Luo" : null),
+    from(t => t === "Kevin" ? "Kevin Leung" : null),
 )
@@ -92,3 +89,3 @@ ```
 
-Observables are a powerful and flexible approach to writing asynchronous code, but you don't have to go all the way down that rabbit hole to use Prague. To run a Transform you just `subscribe`:
+`Observable`s are a powerful and flexible approach to writing asynchronous code, but you don't have to go all the way down that rabbit hole to use *Prague*. To run a `Transform` you just `subscribe`:
 
@@ -106,6 +103,9 @@ ```ts
         },
+        done = {
+            // this is called when there are no more results
+        }
     )
 ```
 
-If you think this looks a like like writing resolve/reject handlers for a `Promise`s, you're right. In fact, you can easily convert an `Observable` to a `Promise`:
+If you think this looks like writing resolve/reject handlers for a `Promise`, you're right. In fact, you can easily convert an `Observable` to a `Promise` as follows:
 
@@ -128,7 +128,7 @@ ```ts
 
-You can compose Transforms together into a new transform using one of the following high-order functions, or create your own. In all the below helpers, your Transforms are automatically normalized via `from`.
+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`.
 
 #### `first`
 
-`first` returns a new Transform which calls each of the supplied transforms in turn until one returns a non-`undefined` result, then stops and returns that. If they all return `undefined`, it returns `undefined`. 
+`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. 
 
@@ -139,5 +139,5 @@ ```ts
 const fullName = first(
-    (t: string) => t === "Bill" ? "Bill Barnes" : undefined,
-    t => t === "Hao" ? "Hao Luo" : undefined,
-    t => t === "Kevin" ? "Kevin Leung" : undefined,
+    (t: string) => t === "Bill" ? "Bill Barnes" : null,
+    t => t === "Hao" ? "Hao Luo" : null,
+    t => t === "Kevin" ? "Kevin Leung" : null,
 );
@@ -147,10 +147,10 @@
 fullName("Hao").subscribe(console.log);     // Match{ value: "Hao Luo" }
-fullName("Yomi").subscribe(console.log);    // undefined
+fullName("Yomi").subscribe(console.log);    //
 ```
 
-Note that all the Transforms 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 new 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.
 
 #### `pipe`
 
-`pipe` returns a new Transform which calls each of the supplied Transforms in turn. You supply the arguments for the first, its result is the argument for the second, and so on. If any of the Tranforms return `undefined`, the new Transform returns `undefined`, otherwise the return value is the result of the last Transform.
+`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.
 
@@ -160,31 +160,37 @@ ```ts
 
-const greet = pipe(
+const someAssemblyRequired = pipe(
     (a: string, b: string) => a + b,
     fullName,
-    m => {
-        if (m instanceof Match)
-            return `Nice to meet you, ${m.value}.`;
-        else
-            return `I don't know you.`;
-    },
 );
 
-greet("Kev", "in").subscribe(console.log);      // Match{ value: "Nice to meet you, Kevin Leung." }
-greet("Yo", "mi").subscribe(console.log);       // Match( value: "I don't know you." }
+someAssemblyRequired("Kev", "in").subscribe(console.log);      // Match{ value: "Kevin Leung." }
+someAssemblyRequired("Yo", "mi").subscribe(console.log);       //
 ```
 
-Note that you only need to declare the argument types for the first transform. TypeScript will infer the argument types for the rest (and for the new Transform) automatically.
+Note that you only need to declare the argument types for the first transform. TypeScript will infer the argument types for the rest (and for the resultant `Transform`) automatically.
 
 #### `match`
 
-`match` is a special case of `pipe` optimized for the common case of having one outcome if a value is successfully extracted, and another if not. The above can be rewritten as:
+Consider this `Transform`:
 
 ```ts
+const greet = first(
+    pipe(
+        fullName,
+        m => `Nice to meet you, ${m.value}.`,
+    ),
+    () => `I don't know you.`,
+)
+
+greet("Kevin").subscribe(console.log);      // Match{ value: "Nice to meet you, Kevin Leung." }
+greet("Yomi").subscribe(console.log);      // Match{ 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';
 
 const greet = match(
-    pipe(
-        (a: string, b: string) => a + b,
-        fullName,
-    ),
+    fullName,
     m => `Nice to meet you, ${m.value}.`,
@@ -197,8 +203,11 @@ () => `I don't know you.`,
 
-`if` is a special case of `match` for the common case of testing a predicate. Beacause `if` is a JavaScript reserved word, if you `import` Prague functions individually you'll need to rename it:
+`if` 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';
 
-const greet = _if((t: string) => t === "Bill",
+const greet = _if(
+    (t: string) => t === "Bill",
     () => `I greet you, my creator!`,
@@ -214,7 +223,7 @@ () => `Meh.`,
 
-`tap` creates 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 its original input. This is a great way to debug:
 
 ```ts
 pipe(
-    (t: string) => t === "Bill" ? "Bill Barnes" : undefined,
+    (t: string) => t === "Bill" ? "Bill Barnes" : null,
     tap(console.log),
@@ -245,16 +254,13 @@ t => t.repeat(2),
 
-This works, but it isn't the Prague way. Rather than executing code immediately, we prefer to return `Action`s:
+This works, but it isn't the *Prague* way. Rather than executing code immediately, we prefer to return `Action`s:
 
 ```ts
-const bot = first(
-    _if((t: string) => t === "current time",
-        () => () => console.log(`The time is ${new Date().toLocaleTimeString()}`),
-    ),
-    _if(t => t === "I'm hungry",
-        () => () => console.log(`You shoud eat some protein.`),
-    ),
-    _if(t => t === "Wassup",
-        () => () => console.log(`WAAAASSSUUUUUUP!`),
-    ),
-)
+const bot = from((t: string) => {
+    if (t === "current time")
+        return () => console.log(`The time is ${new Date().toLocaleTimeString()}`);
+    else if (t === "I'm hungry")
+        return () => console.log(`You shoud eat some protein.`);
+    else if (t === "Wassup")
+        return () => console.log(`WAAAASSSUUUUUUP!`);
+})
 ```
@@ -274,3 +280,3 @@
 
-This is common enough that Prague provides a helper called `run`:
+This is common enough that *Prague* provides a helper called `run`:
 
@@ -302,3 +308,3 @@ ```ts
 
-const bot = best
+const bot = best(
     match(
@@ -308,4 +314,4 @@ best(
                 (t: string) => /My name is (.*)/i.exec(t),
-                matches => matches.value[1]; // gets converted to a Match of score 1
-            },
+                matches => matches.value[1], // gets converted to a Match of score 1
+            ),
             t => new Match(t, .5),
@@ -324,3 +330,3 @@ ),
     run
-).subscribe();
+)(a).subscribe();
 
@@ -351,3 +357,3 @@ test("Bill"); // Nice to meet you, Bill
 
-It turns out that `best` is a special case of a helper called `sorted`, which returns a Transform which calls each supplied Transform with the supplied arguments. If all return `undefined`, it returns `undefined`. If one returns a `Result`, it returns that. If two or more return a `Result`, it returns a `Multiple`, which is a `Result` containing an array of all the `Result`s.
+It turns out that `best` is a special case of a helper called `sorted`, which returns a `Transform` which calls each supplied `Transform` with the supplied arguments. If none emit, neither does it. If one returns a `Result`, it returns that. If two or more return a `Result`, it returns a `Multiple`, which is a `Result` containing an array of all the `Result`s.
 
@@ -357,3 +363,3 @@ ```ts
     ...transforms
-)();
+);
 
@@ -360,0 +366,0 @@ sortme()

No alert changes

Improved metrics

Number of lines in readme file

419

increased by1.45%

Worsened metrics

Total package byte prevSize

57622

decreased by-2.83%

Lines of code

323

decreased by-3.58%

No dependency changes