Fix parse url params and add comments (#22)

* Refine types

* Organize type test

* Add comments to type

* Add more comments

Author: mpppk

src/common/spec.ts

@@ -12,7 +12,7 @@ export const Method = [
 ] as const;
 export type Method = (typeof Method)[number];
 
-export type ApiEndpoint<Path> = Partial<
+export type ApiEndpoint<Path extends string> = Partial<
   Record<Method, ApiSpec<ParseUrlParams<Path>>>
 >;
 export type ApiEndpoints = {

src/common/type.t-test.ts

@@ -0,0 +1,43 @@
+import { Equal, Expect } from "./type-test";
+import { ExtractByPrefix, FilterNever, Replace, Split } from "./type";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type FilterNeverCases = [
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  Expect<Equal<FilterNever<{ a: never }>, {}>>,
+  Expect<Equal<FilterNever<{ a: never; b: string }>, { b: string }>>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type SplitTestCases = [
+  Expect<Equal<Split<"", "">, []>>,
+  Expect<Equal<Split<"a", "">, ["a"]>>,
+  Expect<Equal<Split<"ab", "">, ["a", "b"]>>,
+  Expect<Equal<Split<"a/b", "/">, ["a", "b"]>>,
+  Expect<Equal<Split<"/a/b", "/">, ["", "a", "b"]>>,
+  Expect<Equal<Split<"a/b/c", "/">, ["a", "b", "c"]>>,
+  Expect<Equal<Split<"a/b/", "/">, ["a", "b", ""]>>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ReplaceTestCases = [
+  Expect<Equal<Replace<"a", "a", "-">, "-">>,
+  Expect<Equal<Replace<"a", "noexist", "-">, "a">>,
+  Expect<Equal<Replace<"a", "a", "a">, "a">>,
+  Expect<Equal<Replace<"abcd", "ab", "-">, "-cd">>,
+  Expect<Equal<Replace<"abcd", "cd", "-">, "ab-">>,
+  Expect<Equal<Replace<"abcd", "bc", "-">, "a-d">>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ExtractByPrefixTestCases = [
+  Expect<Equal<ExtractByPrefix<"", "">, "">>,
+  Expect<Equal<ExtractByPrefix<"a", "">, "a">>,
+  Expect<Equal<ExtractByPrefix<"a" | "b", "">, "a" | "b">>,
+  Expect<Equal<ExtractByPrefix<"a", ":">, never>>,
+  Expect<Equal<ExtractByPrefix<":a", ":">, "a">>,
+  Expect<Equal<ExtractByPrefix<":a" | "b", ":">, "a">>,
+  Expect<Equal<ExtractByPrefix<"a" | ":b", ":">, "b">>,
+  Expect<Equal<ExtractByPrefix<":a" | ":b", ":">, "a" | "b">>,
+  Expect<Equal<ExtractByPrefix<":a" | ":b" | ":c", ":">, "a" | "b" | "c">>,
+];

src/common/type.ts

@@ -1,9 +1,66 @@
+/**
+ * Filter key & value, which has "never" value
+ *
+ * @example
+ * ```
+ * type T0 = FilterNever<{ a: never; b: string }>, { b: string }>
+ * // => {b: string}
+ * ```
+ */
 export type FilterNever<T extends Record<string, unknown>> = {
   [K in keyof T as T[K] extends never ? never : K]: T[K];
 };
 
+/**
+ * Replace substring
+ * S: source string
+ * From: substring to be replaced
+ * To: substring to replace
+ *
+ * @example
+ * ```
+ * type T0 = Replace<"abcd", "bc", "-">;
+ * // => "a-d"
+ * ```
+ */
 export type Replace<
   S extends string,
   From extends string,
   To extends string,
 > = S extends `${infer P}${From}${infer R}` ? `${P}${To}${R}` : S;
+
+/**
+ * Split string by delimiter
+ * S: source string
+ * Delimiter: delimiter to split
+ *
+ * @example
+ * ```
+ * type T0 = Split<"a/b/c", "/">;
+ * // => ["a", "b", "c"]
+ * ```
+ */
+export type Split<
+  S extends string,
+  Delimiter extends string,
+> = S extends `${infer Head}${Delimiter}${infer Tail}`
+  ? [Head, ...Split<Tail, Delimiter>]
+  : S extends Delimiter
+    ? []
+    : [S];
+
+/**
+ * Extract string by prefix
+ * T: source string
+ * Prefix: prefix to extract
+ *
+ * @example
+ * ```
+ * type T0 = ExtractByPrefix<"p-a" | "p-b" | "c", "p-">;
+ * // => "a" | "b"
+ * ```
+ */
+export type ExtractByPrefix<
+  T extends string,
+  Prefix extends string,
+> = T extends `${Prefix}${infer R}` ? R : never;

src/common/url.t-test.ts

@@ -1,49 +1,145 @@
 import { Equal, Expect } from "./type-test";
-import { ParseOrigin, ParseURL } from "./url";
+import {
+  MatchedPatterns,
+  ParseHostAndPort,
+  ParseOriginAndPath,
+  ParseURL,
+  ParseUrlParams,
+  ToUrlParamPattern,
+  ToUrlPattern,
+} from "./url";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-type cases = [
-  Expect<Equal<ParseOrigin<undefined>, never>>,
+type ParseUrlParamsTestCases = [
+  // @ts-expect-error undefined is not a string
+  Expect<Equal<ParseUrlParams<undefined>, never>>,
+  Expect<Equal<ParseUrlParams<"">, never>>,
+  Expect<Equal<ParseUrlParams<"">, never>>,
+  Expect<Equal<ParseUrlParams<":a">, "a">>,
+  Expect<Equal<ParseUrlParams<"/:a">, "a">>,
+  Expect<Equal<ParseUrlParams<"/:a/:b">, "a" | "b">>,
+  Expect<Equal<ParseUrlParams<"/a/:b">, "b">>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ToUrlParamPatternTestCases = [
+  Expect<Equal<ToUrlParamPattern<"">, "">>,
+  Expect<Equal<ToUrlParamPattern<"/">, "/">>,
+  Expect<Equal<ToUrlParamPattern<":a">, string>>,
+  Expect<Equal<ToUrlParamPattern<"/:a/b">, `/${string}/b`>>,
+  Expect<Equal<ToUrlParamPattern<"/:a/:b">, `/${string}/${string}`>>,
+  Expect<
+    // @ts-expect-error URL is not supported
+    Equal<ToUrlParamPattern<"https://example.com">, `"https://example.com}`>
+  >,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ToUrlPatternTestCases = [
+  Expect<Equal<ToUrlPattern<"">, "">>,
+  Expect<Equal<ToUrlPattern<"/">, "/">>,
+  Expect<Equal<ToUrlPattern<"/users/:userId">, `/users/${string}`>>,
   Expect<
     Equal<
-      ParseOrigin<"">,
-      { schema: undefined; host: undefined; port: undefined; path: "" }
+      ToUrlPattern<"/users/:userId?key=value">,
+      `/users/${string}?key=value`
     >
   >,
+  // @ts-expect-error URL is not supported
+  Expect<Equal<ToUrlPattern<"https://example.com">, "https://example.com">>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type MatchedPatternsTestCases = [
+  Expect<Equal<MatchedPatterns<"", "">, "">>,
+  Expect<Equal<MatchedPatterns<"/1", "/:userId">, "/:userId">>,
+  Expect<
+    Equal<MatchedPatterns<"/1", "/:userId" | "/:orgId">, "/:userId" | "/:orgId">
+  >,
+  Expect<
+    Equal<
+      MatchedPatterns<"/users/1", "/users/:userId" | "/:userId">,
+      "/users/:userId" | "/:userId"
+    >
+  >,
+  Expect<
+    Equal<
+      MatchedPatterns<"/users/1", "/users/:userId" | "/org/:orgId">,
+      "/users/:userId"
+    >
+  >,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ParseHostAndPortTestCases = [
   Expect<
     Equal<
-      ParseOrigin<"https://example.com">,
-      { host: "example.com"; port: undefined } & { schema: "https"; path: "" }
+      ParseHostAndPort<"example.com">,
+      { host: "example.com"; port: undefined }
     >
   >,
   Expect<
     Equal<
-      ParseOrigin<"https://example.com/">,
+      ParseHostAndPort<"example.com:8080">,
+      { host: "example.com"; port: "8080" }
+    >
+  >,
+  // If invalid port is specified, it should return never
+  Expect<Equal<ParseHostAndPort<"example.com:xxx">, never>>,
+];
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ParseOriginAndPathCases = [
+  Expect<Equal<ParseOriginAndPath<undefined>, never>>,
+  Expect<
+    Equal<
+      ParseOriginAndPath<"">,
+      { schema: undefined; host: undefined; port: undefined; path: "" }
+    >
+  >,
+  Expect<
+    Equal<
+      ParseOriginAndPath<"https://example.com/">,
       { host: "example.com"; port: undefined } & { schema: "https"; path: "/" }
     >
   >,
   Expect<
     Equal<
-      ParseOrigin<"https://example.com/user">,
+      ParseOriginAndPath<"https://example.com/user">,
       { host: "example.com"; port: undefined } & {
         schema: "https";
         path: "/user";
       }
     >
   >,
+
+  Expect<
+    Equal<
+      ParseOriginAndPath<"https://example.com/users/:userId">,
+      { host: "example.com"; port: undefined } & {
+        schema: "https";
+        path: "/users/:userId";
+      }
+    >
+  >,
+
   Expect<
     Equal<
-      ParseOrigin<"https://example.com:8080/user">,
+      ParseOriginAndPath<"https://example.com:8080/user">,
       { host: "example.com"; port: "8080" } & { schema: "https"; path: "/user" }
     >
   >,
+
   Expect<
     Equal<
-      ParseOrigin<"/user">,
+      ParseOriginAndPath<"/user">,
       { schema: undefined; host: undefined; port: undefined; path: "/user" }
     >
   >,
+];
 
-  Expect<Equal<ParseURL<"/user">["path"], "/user">>,
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type ParseURLTestCases = [
+  Expect<Equal<ParseURL<"/user?a=b">["path"], "/user">>,
   Expect<Equal<ParseURL<"https://example.com/user">["path"], "/user">>,
 ];