matcher: simplify matcher protocol and mark unstable

src/patterns.ts

@@ -21,10 +21,51 @@ import {
   CustomP,
 } from './types/Pattern';
 
-export { Pattern };
+export { Pattern, Fn as unstable_Fn };
 
 export { matcher };
 
+/**
+ * @experimental
+ * A `Matchable` is an object implementing
+ * the Matcher Protocol. It must have a `[P.matcher]: P.Matcher<NarrowFn>`
+ * key, which defines how this object should be matched by TS-Pattern.
+ *
+ * Note that this api is unstable.
+ *
+ * @example
+ * ```ts
+ * class Some<T> implements P.unstable_Matchable {
+ *  [P.matcher](): P.unstable_Matcher<Some<T>>
+ * }
+ * ```
+ */
+export type unstable_Matchable<
+  narrowedOrFn,
+  input = unknown,
+  pattern = never
+> = CustomP<input, pattern, narrowedOrFn>;
+
+/**
+ * @experimental
+ * A `Matcher` is an object with `match` function, which
+ * defines how this object should be matched by TS-Pattern.
+ *
+ * Note that this api is unstable.
+ *
+ * @example
+ * ```ts
+ * class Some<T> implements P.unstable_Matchable {
+ *  [P.matcher](): P.unstable_Matcher<Some<T>>
+ * }
+ * ```
+ */
+export type unstable_Matcher<
+  narrowedOrFn,
+  input = unknown,
+  pattern = never
+> = ReturnType<CustomP<input, pattern, narrowedOrFn>[matcher]>;
+
 /**
  * `P.infer<typeof somePattern>` will return the type of the value
  * matched by this pattern.
@@ -682,15 +723,3 @@ export function typed<input>(): {
     when: when as any,
   };
 }
-
-export type Matchable<
-  narrowFn extends Fn,
-  input = unknown,
-  pattern = never
-> = CustomP<input, pattern, narrowFn>;
-
-export type Matcher<
-  narrowFn extends Fn,
-  input = unknown,
-  pattern = never
-> = ReturnType<CustomP<input, pattern, narrowFn>[matcher]>;

src/types/InvertPattern.ts

@@ -112,7 +112,7 @@ type InvertPatternInternal<p, input> = 0 extends 1 & p
       infer subpattern,
       infer matcherType,
       any,
-      infer narrowFn
+      infer narrowedOrFn
     >
   ? {
       not: DeepExclude<input, InvertPatternInternal<subpattern, input>>;
@@ -133,7 +133,9 @@ type InvertPatternInternal<p, input> = 0 extends 1 & p
       and: ReduceIntersection<Extract<subpattern, readonly any[]>, input>;
       or: ReduceUnion<Extract<subpattern, readonly any[]>, input>;
       default: [subpattern] extends [never] ? input : subpattern;
-      custom: Override<narrowFn extends Fn ? Apply<narrowFn, input> : never>;
+      custom: Override<
+        narrowedOrFn extends Fn ? Apply<narrowedOrFn, input> : narrowedOrFn
+      >;
     }[matcherType]
   : p extends Primitives
   ? p
@@ -341,9 +343,9 @@ type InvertPatternForExcludeInternal<p, i, empty = never> =
           InvertPatternForExcludeInternal<subpattern, i>
         >;
         default: excluded;
-        custom: excluded extends infer narrowFn extends Fn
-          ? Apply<narrowFn, i>
-          : never;
+        custom: excluded extends infer narrowedOrFn extends Fn
+          ? Apply<narrowedOrFn, i>
+          : excluded;
       }[matcherType]
     : p extends readonly any[]
     ? Extract<i, readonly any[]> extends infer arrayInput

src/types/Pattern.ts

@@ -78,15 +78,15 @@ export type AnyMatcher = Matcher<any, any, any, any, any>;
 
 type UnknownMatcher = Matcher<unknown, unknown, any, any>;
 
-export type CustomP<input, pattern, narrowFn extends Fn> = Matcher<
+export type CustomP<input, pattern, narrowedOrFn> = Matcher<
   input,
   pattern,
   //  👆
   // for the input type to be instantiated correctly
   // on subpatterns, it has to be passed through.
   'custom',
   None,
-  narrowFn
+  narrowedOrFn
 >;
 
 export type ArrayP<input, p> = Matcher<input, p, 'array'>;

tests/matcher-protocol.test.ts

@@ -1,20 +1,17 @@
 import { isMatching, match, P } from '../src';
-import { Equal, Expect, Fn } from '../src/types/helpers';
-import { UnknownPattern } from '../src/types/Pattern';
+import { Equal, Expect } from '../src/types/helpers';
 
 describe('matcher protocol', () => {
   type SomeValue<T> = T extends Some<infer V> ? V : never;
 
-  interface SomeNarrowFn<p extends P.Pattern<unknown> = never> extends Fn {
-    output: [p] extends [never]
-      ? Some<SomeValue<this['input']>>
-      : Some<P.narrow<SomeValue<this['input']>, p>>;
+  interface SomeNarrowFn extends P.unstable_Fn {
+    output: Some<SomeValue<this['input']>>;
   }
 
   class Some<const T> {
     constructor(public value: T) {}
 
-    static [P.matcher](): P.Matcher<SomeNarrowFn> {
+    static [P.matcher](): P.unstable_Matcher<SomeNarrowFn> {
       return {
         match: (input) => {
           return {
@@ -24,7 +21,9 @@ describe('matcher protocol', () => {
       };
     }
 
-    [P.matcher](): P.Matcher<SomeNarrowFn<Extract<T, UnknownPattern>>> {
+    [P.matcher](): P.unstable_Matcher<
+      Some<T extends P.Pattern<unknown> ? P.infer<T> : T>
+    > {
       return {
         match: (input) => {
           return {
@@ -35,15 +34,13 @@ describe('matcher protocol', () => {
       };
     }
   }
-  interface NoneNarrowFn extends Fn {
-    output: None;
-  }
+
   class None {
     coucou: number;
     constructor() {
       this.coucou = 1;
     }
-    static [P.matcher](): P.Matcher<NoneNarrowFn> {
+    static [P.matcher](): P.unstable_Matcher<None> {
       return {
         match: (input) => {
           return { matched: input instanceof None };