chainable: add a few string chainable methods

Author: gvergnaud

docs/roadmap.md

@@ -1,30 +1,28 @@
 ### Roadmap
 
 - [ ] chainable methods
-
-  - string
-  - `P.string.includes('str')`
-  - `P.string.startsWith('str')`
-  - `P.string.endsWith('str')`
-  - `P.string.regex('[a-z]+')`
-  - numbers
-  - `P.number.between(1, 10)`
-  - `P.number.lt(12)`
-  - `P.number.gt(12)`
-  - `P.number.gte(12)`
-  - `P.number.lte(12)`
-  - `P.number.int(12)`
-  - `P.number.finite`
-  - `P.number.positive`
-  - `P.number.negative`
-  - all
-  - `P.number.optional`
-  - `P.string.optional`
-  - `P.number.select()`
-  - `P.string.select()`
-  - `P.number.optional.select()`
-  - `P.string.optional.select()`
-
+  - [ ] string
+    - [x] `P.string.includes('str')`
+    - [x] `P.string.startsWith('str')`
+    - [x] `P.string.endsWith('str')`
+    - [ ] `P.string.regex('[a-z]+')`
+  - [ ] numbers
+    - [ ] `P.number.between(1, 10)`
+    - [ ] `P.number.lt(12)`
+    - [ ] `P.number.gt(12)`
+    - [ ] `P.number.gte(12)`
+    - [ ] `P.number.lte(12)`
+    - [ ] `P.number.int(12)`
+    - [ ] `P.number.finite`
+    - [ ] `P.number.positive`
+    - [ ] `P.number.negative`
+  - [ ] all
+    - [ ] `P.number.optional`
+    - [ ] `P.string.optional`
+    - [ ] `P.number.select()`
+    - [ ] `P.string.select()`
+    - [ ] `P.number.optional.select()`
+    - [ ] `P.string.optional.select()`
 - [x] Add a custom matcher protocol data structures could implement to make them matchable.
 - [x] (Maybe) add an iterator protocol to `P.array` to be usable as a variadic tuple pattern. Example of using `P.array`:
 

src/patterns.ts

@@ -593,19 +593,68 @@ export const any = when(isUnknown);
 export const _ = any;
 
 /**
- * `P.string` is a wildcard pattern matching any **string**.
+ * `P.string.startsWith(start)` is a pattern, matching **strings** starting with `start`.
+ *
+ * [Read documentation for `P.string.startsWith` on GitHub](https://github.com/gvergnaud/ts-pattern#PstringstartsWith)
+ *
+ * @example
+ *  match(value)
+ *   .with(P.string.startsWith('A'), () => 'value starts with an A')
+ */
+
+const startsWith = <input, const start extends string>(
+  start: start
+): GuardP<input, `${start}${string}`> =>
+  when((value) => isString(value) && value.startsWith(start));
+
+/**
+ * `P.string.endsWith(end)` is a pattern, matching **strings** ending with `end`.
+ *
+ * [Read documentation for `P.string.endsWith` on GitHub](https://github.com/gvergnaud/ts-pattern#PstringendsWith)
+ *
+ * @example
+ *  match(value)
+ *   .with(P.string.endsWith('!'), () => 'value ends with an !')
+ */
+const endsWith = <input, const end extends string>(
+  end: end
+): GuardP<input, `${string}${end}`> =>
+  when((value) => isString(value) && value.endsWith(end));
+
+/**
+ * `P.string.includes(substr)` is a pattern, matching **strings** containing `substr`.
+ *
+ * [Read documentation for `P.string.includes` on GitHub](https://github.com/gvergnaud/ts-pattern#Pstringincludes)
+ *
+ * @example
+ *  match(value)
+ *   .with(P.string.includes('http'), () => 'value contains http')
+ */
+const includes = <input, const substr extends string>(
+  substr: substr
+): GuardExcludeP<input, string, never> =>
+  when((value) => isString(value) && value.includes(substr));
+
+const assignStringMethods = <p extends GuardP<any, any>>(pattern: p) =>
+  Object.assign(pattern, {
+    startsWith,
+    endsWith,
+    includes,
+  });
+
+/**
+ * `P.string` is a wildcard pattern, matching any **string**.
  *
  * [Read documentation for `P.string` on GitHub](https://github.com/gvergnaud/ts-pattern#Pstring-wildcard)
  *
  * @example
  *  match(value)
  *   .with(P.string, () => 'will match on strings')
  */
-
-export const string = when(isString);
+export const string = assignStringMethods(when(isString));
 
 /**
- * `P.number` is a wildcard pattern matching any **number**.
+ * `P.number` is a wildcard pattern, matching any **number**.
  *
  * [Read documentation for `P.number` on GitHub](https://github.com/gvergnaud/ts-pattern#Pnumber-wildcard)
  *
@@ -616,7 +665,7 @@ export const string = when(isString);
 export const number = when(isNumber);
 
 /**
- * `P.boolean` is a wildcard pattern matching any **boolean**.
+ * `P.boolean` is a wildcard pattern, matching any **boolean**.
  *
  * [Read documentation for `P.boolean` on GitHub](https://github.com/gvergnaud/ts-pattern#boolean-wildcard)
  *
@@ -626,7 +675,7 @@ export const number = when(isNumber);
 export const boolean = when(isBoolean);
 
 /**
- * `P.bigint` is a wildcard pattern matching any **bigint**.
+ * `P.bigint` is a wildcard pattern, matching any **bigint**.
  *
  * [Read documentation for `P.bigint` on GitHub](https://github.com/gvergnaud/ts-pattern#bigint-wildcard)
  *
@@ -636,7 +685,7 @@ export const boolean = when(isBoolean);
 export const bigint = when(isBigInt);
 
 /**
- * `P.symbol` is a wildcard pattern matching any **symbol**.
+ * `P.symbol` is a wildcard pattern, matching any **symbol**.
  *
  * [Read documentation for `P.symbol` on GitHub](https://github.com/gvergnaud/ts-pattern#symbol-wildcard)
  *
@@ -646,7 +695,7 @@ export const bigint = when(isBigInt);
 export const symbol = when(isSymbol);
 
 /**
- * `P.nullish` is a wildcard pattern matching **null** or **undefined**.
+ * `P.nullish` is a wildcard pattern, matching **null** or **undefined**.
  *
  * [Read documentation for `P.nullish` on GitHub](https://github.com/gvergnaud/ts-pattern#nullish-wildcard)
  *

tests/chainable.test.ts

@@ -1,10 +1,58 @@
+import { P, match } from '../src';
+import { Equal, Expect } from '../src/types/helpers';
+
 describe('chainable methods', () => {
   describe('string', () => {
-    it(`P.string.includes('str')`, () => {});
-    it(`P.string.startsWith('str')`, () => {});
-    it(`P.string.endsWith('str')`, () => {});
+    it(`P.string.includes('str')`, () => {
+      const f = (input: string | number) =>
+        match(input)
+          .with(P.string.includes('!!'), (value) => {
+            type t = Expect<Equal<typeof value, string>>;
+            return 'includes !!';
+          })
+          .otherwise((value) => {
+            type t = Expect<Equal<typeof value, string | number>>;
+            return 'something else';
+          });
+
+      expect(f('hello!!')).toBe('includes !!');
+      expect(f('nope')).toBe('something else');
+    });
+
+    it(`P.string.startsWith('str')`, () => {
+      const f = (input: string | number) =>
+        match(input)
+          .with(P.string.startsWith('hello '), (value) => {
+            type t = Expect<Equal<typeof value, `hello ${string}`>>;
+            return 'starts with hello';
+          })
+          .otherwise((value) => {
+            type t = Expect<Equal<typeof value, string | number>>;
+            return 'something else';
+          });
+
+      expect(f('hello gabriel')).toBe('starts with hello');
+      expect(f('gabriel')).toBe('something else');
+    });
+
+    it(`P.string.endsWith('str')`, () => {
+      const f = (input: string | number) =>
+        match(input)
+          .with(P.string.endsWith('!!'), (value) => {
+            type t = Expect<Equal<typeof value, `${string}!!`>>;
+            return 'ends with !!';
+          })
+          .otherwise((value) => {
+            type t = Expect<Equal<typeof value, string | number>>;
+            return 'something else';
+          });
+
+      expect(f('hello!!')).toBe('ends with !!');
+      expect(f('nope')).toBe('something else');
+    });
     it(`P.string.regex('[a-z]+')`, () => {});
   });
+
   describe('number', () => {
     it(`P.number.between(1, 10)`, () => {});
     it(`P.number.lt(12)`, () => {});