[doc] Improve examples

Author: gvergnaud

README.md

@@ -239,8 +239,8 @@ Then we add a first `with` clause:
 
 ```ts
   .with([{ status: 'loading' }, { type: 'success' }], ([state, event]) => ({
-    // `state` is infered as { status: 'loading' }
-    // `event` is infered as { type: 'success', data: string }
+    // `state` is inferred as { status: 'loading' }
+    // `event` is inferred as { type: 'success', data: string }
     status: 'success',
     data: event.data,
   }))
@@ -964,7 +964,7 @@ const output = match({ score: 10 })
     {
       score: P.when((score): score is 5 => score === 5),
     },
-    (input) => '😐' // input is infered as { score: 5 }
+    (input) => '😐' // input is inferred as { score: 5 }
   )
   .with({ score: P.when((score) => score < 5) }, () => '😞')
   .with({ score: P.when((score) => score > 5) }, () => '🙂')

ROADMAP.md

@@ -1,13 +1,13 @@
 ### Roadmap
 
-- [ ] add a `rest` (maybe `rest(Pattern<a>)`) pattern for list. Example of using `rest`:
+- [ ] add a `P.rest` (maybe `P.rest(Pattern<a>)`) pattern for list. Example of using `P.rest`:
 
 ```ts
 const reverse = <T>(xs: T[]): T[] => {
   return (
     match<T[], T[]>(xs)
       // matches a list with at least one element
-      .with([__, ...rest(__)], ([x, ...xs]) => [...reverse(xs), x])
+      .with([__, ...P.rest(__)], ([x, ...xs]) => [...reverse(xs), x])
       .otherwise(() => [])
   );
 };

examples/one-file-demo.ts

@@ -1,75 +1,82 @@
 /**
- * Demo summary:
- * - Basic pattern with inference with a wildcard
- *      -> use case: better than switch because you can use it in a react component
- * - using select
- *      -> easy to extract a value from the input Data Structure
- * - using P.union
- *      -> matching several cases
- * - basic exhaustiveness checking
- *      -> checking if everything is handled
- * - complexe exhaustiveness checking: matching on several values with a tuple
- *      -> matching all combination of 2 enums
- * - P.array, P.optional, isMatching: validating input
- *      -> typing API responses from 3rd party backends which aren't versioned
+ * ### One file TS-Pattern demo.
+ *
+ * This demo will demonstrate:
+ * - How to use pattern matching and wildcards
+ * - How to extract a value from the input Data Structure using `P.select`
+ * - How to match several cases using `P.union`
+ * - How to leverage exhaustiveness checking to make sure every case is handled
+ * - How to pattern match on several values at once using tuples
+ * - How to validate an unknown API responses using `P.array`, `P.optional` and `isMatching`
  */
 
 import { isMatching, match, P, __ } from '../src';
 
-/**
- * Use case 1: handling discriminated union types
- */
+/**************************************************
+ * Use case 1: handling discriminated union types *
+ **************************************************/
 
 type Response =
-  | { type: 'video'; format: 'mp4' | 'webm'; src: string }
-  | { type: 'image'; extension: 'gif' | 'jpg' | 'png'; src: string }
-  | { type: 'text'; content: string; tags: { name: string; id: number }[] };
+  | { type: 'video'; data: { format: 'mp4' | 'webm'; src: string } }
+  | { type: 'image'; data: { extension: 'gif' | 'jpg' | 'png'; src: string } }
+  | { type: 'text'; data: string; tags: { name: string; id: number }[] };
 
-const exampleFunction1 = (input: Response) =>
+const exampleFunction1 = (input: Response): string =>
   match(input)
     // 1. Basic pattern with inference with a wildcard
-    .with({ type: 'video', format: 'mp4' }, (video) => video.src)
+    .with({ type: 'video', data: { format: 'mp4' } }, (video) => video.data.src)
     // 2. using select
     .with(
-      { type: 'image', extension: 'gif', src: P.select() },
+      { type: 'image', data: { extension: 'gif', src: P.select() } },
       (value) => value + '!!'
     )
     // 3. using P.union
     .with(
-      { type: 'image', extension: P.union('jpg', 'png'), src: P.select() },
+      {
+        type: 'image',
+        data: { extension: P.union('jpg', 'png'), src: P.select() },
+      },
       (value) => value + '!!'
     )
-    // 4. basic exhaustiveness checking
-    // @ts-expect-error
+    // 4. selecting all tag names with P.array and P.select
+    .with(
+      { type: 'text', tags: P.array({ name: P.select() }) },
+      (tagNames) => tagNames.join(', ') + '!!'
+    )
+    // 5. basic exhaustiveness checking
+    // @ts-expect-error: { type: 'video', data: { format: 'webm' } } isn't covered
     .exhaustive();
 
-/**
- * Use case 2: multi params conditional logic
- */
+/**********************************************
+ * Use case 2: multi params conditional logic *
+ **********************************************/
 
-type UserType = 'contributor' | 'spectator';
+type UserType = 'editor' | 'viewer';
+// Uncomment 'premium' to see exhaustive checking in action
 type OrgPlan = 'basic' | 'pro' /* | 'premium' */ | 'enterprise';
 
-const exampleFunction2 = (org: OrgPlan, user: UserType) =>
-  // Checking several enums with tuples
+const exampleFunction2 = (org: OrgPlan, user: UserType): string =>
+  // 1. Checking several enums with tuples
   match([org, user] as const)
     .with(['basic', __], () => `Please upgrade to unlock this feature!`)
+    // 2. `.with()` can take several patterns. It will match if one of them do.
     .with(
-      [P.union('pro', 'enterprise'), 'spectator'],
+      ['pro', 'viewer'],
+      ['enterprise', 'viewer'],
       () => `Your account doesn't have permissions to use this feature`
     )
-    .with(['pro', 'contributor'], () => `Hello!`)
-    .with(['enterprise', 'contributor'], () => `You are our favorite customer!`)
-    // 5. complex exhaustive checking
+    .with(['pro', 'editor'], () => `Hello!`)
+    .with(['enterprise', 'editor'], () => `You are our favorite customer!`)
+    // 3. complex exhaustive checking
     .exhaustive();
 
-/**
- * Use case 3: Validation an API response
- */
+/******************************************
+ * Use case 3: Validation an API response *
+ ******************************************/
 
 const userPattern = {
   name: P.string,
-  // 6. optional properties
+  // 1. optional properties
   age: P.optional(P.number),
   socialLinks: P.optional({
     twitter: P.string,
@@ -82,7 +89,7 @@ const postPattern = {
   content: P.string,
   likeCount: P.number,
   author: userPattern,
-  // 7. arrays
+  // 2. arrays
   comments: P.array({
     author: userPattern,
     content: P.string,
@@ -91,12 +98,17 @@ const postPattern = {
 
 type Post = P.infer<typeof postPattern>;
 
-const validate = (response: unknown): Post | null => {
-  // 8. validating unknown input with isMatching
+// elsewhere ine the code:
+// `fetch(...).then(validateResponse)`
+
+const validateResponse = (response: unknown): Post | null => {
+  // 3. validating unknown input with isMatching
   if (isMatching(postPattern, response)) {
-    //  response: Post
-    const cardTitle = `${response.title} by @${response.author.name}`;
-    const commenters = response.comments.map((c) => c.author.name).join(', ');
+    //  response is inferred as  `Post`.
+
+    // Uncomment these lines if you want to try using `response`:
+    // const cardTitle = `${response.title} by @${response.author.name}`;
+    // const commenters = response.comments.map((c) => c.author.name).join(', ');
     return response;
   }
 

src/types/helpers.ts

@@ -6,7 +6,7 @@ export type Values<a extends object> = UnionToTuple<ValueOf<a>>;
  * ### LeastUpperBound
  * An interesting one. A type taking two imbricated sets and returning the
  * smallest one.
- * We need that because sometimes the pattern's infered type holds more
+ * We need that because sometimes the pattern's inferred type holds more
  * information than the value on which we are matching (if the value is any
  * or unknown for instance).
  */

tests/type-error.test.ts

@@ -30,7 +30,7 @@ describe('type errors', () => {
       .exhaustive();
   });
 
-  it("If the pattern's wrong, the infered selection must be the input type", () => {
+  it("If the pattern's wrong, the inferred selection must be the input type", () => {
     match<Country>('Germany')
       .with('Germany', 'Spain', () => 'Europe')
       // @ts-expect-error: 'US' instead of 'USA'

tests/when.test.ts

@@ -292,7 +292,7 @@ describe('when', () => {
         // handler to be executed.
         .with(
           { kind: 'some' },
-          // `someNumber` is infered to be a { kind: "some"; value: number }
+          // `someNumber` is inferred to be a { kind: "some"; value: number }
           // based on the pattern provided as first argument.
           (someNumber) =>
             someNumber.value % 5 === 0 && someNumber.value % 3 === 0,