Better error (#118)

* Add NoPathError

* Rename to C (Compile error message utility)

* Return more explicit error from ValidateQuery

* Simplify and more comment

Author: mpppk

Diff for: src/compile-error-utils.ts

@@ -0,0 +1,10 @@
+// Type Utilities for Compile error message
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace C {
+  const e: unique symbol;
+  const ok: unique symbol;
+  export type E<MSG> = { [e]: MSG };
+  export type OK = { [ok]: true };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type AnyE = E<any>;
+}

Diff for: src/core/query-string.t-test.ts

@@ -2,10 +2,13 @@ import { Equal, Expect } from "./type-test";
 import {
   HasExcessiveQuery,
   HasMissingQuery,
-  IsValidQuery,
+  ValidateQuery,
   NonOptionalKeys,
   ToQueryUnion,
+  ExcessiveQueryError,
+  MissingQueryError,
 } from "./query-string";
+import { C } from "../compile-error-utils";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type ToQueryUnionCase = [
@@ -49,22 +52,22 @@ type NonOptionalKeysCase = [
 ];
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-type IsValidQueryCase = [
-  Expect<Equal<IsValidQuery<{ a: string }, "a">, true>>,
-  Expect<Equal<IsValidQuery<{ a: string }, "b">, "E: maybe missing query: a">>,
+type ValidateQueryCase = [
+  Expect<Equal<ValidateQuery<{ a: string }, "a">, C.OK>>,
+  Expect<Equal<ValidateQuery<{ a: string }, "b">, MissingQueryError<"a">>>,
   Expect<
     Equal<
-      IsValidQuery<{ a: string }, "a" | "b">,
-      "E: maybe excessive query: a" | "E: maybe excessive query: b"
+      ValidateQuery<{ a: string }, "a" | "b">,
+      ExcessiveQueryError<"a" | "b">
     >
   >,
-  Expect<Equal<IsValidQuery<{ a: string; b?: string }, "a">, true>>,
-  Expect<Equal<IsValidQuery<{ a: string; b?: string }, "a" | "b">, true>>,
+  Expect<Equal<ValidateQuery<{ a: string; b?: string }, "a">, C.OK>>,
+  Expect<Equal<ValidateQuery<{ a: string; b?: string }, "a" | "b">, C.OK>>,
   Expect<
     Equal<
-      IsValidQuery<{ a: string; b: string }, "a">,
-      "E: maybe missing query: a" | "E: maybe missing query: b"
+      ValidateQuery<{ a: string; b: string }, "a">,
+      MissingQueryError<"a" | "b">
     >
   >,
-  Expect<Equal<IsValidQuery<{ a: string; b: string }, "a" | "b">, true>>,
+  Expect<Equal<ValidateQuery<{ a: string; b: string }, "a" | "b">, C.OK>>,
 ];

Diff for: src/core/query-string.ts

@@ -1,4 +1,6 @@
 // https://github.com/type-challenges/type-challenges/issues/21419
+import { C } from "../compile-error-utils";
+
 export type ParseQueryString<S extends string> = S extends ""
   ? Record<string, never>
   : MergeParams<SplitParams<S>>;
@@ -66,12 +68,20 @@ export type NonOptionalKeys<T> = {
   [K in keyof T]-?: undefined extends T[K] ? never : K;
 }[keyof T];
 
-export type IsValidQuery<
+export type MissingQueryError<Keys extends string> = {
+  reason: `missing query`;
+  keys: Keys;
+};
+export type ExcessiveQueryError<Keys extends string> = {
+  reason: `excessive query`;
+  keys: Keys;
+};
+export type ValidateQuery<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   QueryDef extends Record<string, any>,
   QueryKeys extends string,
 > = [HasMissingQuery<QueryDef, QueryKeys>] extends [true]
-  ? `E: maybe missing query: ${keyof QueryDef & string}`
+  ? MissingQueryError<keyof QueryDef & string>
   : [HasExcessiveQuery<QueryDef, QueryKeys>] extends [true]
-    ? `E: maybe excessive query: ${QueryKeys}`
-    : true;
+    ? ExcessiveQueryError<QueryKeys>
+    : C.OK;

Diff for: src/core/spec.ts

@@ -1,5 +1,6 @@
 import { ParseUrlParams } from "./url";
 import { ClientResponse, StatusCode } from "./hono-types";
+import { C } from "../compile-error-utils";
 
 /**
  * { // ApiEndpoints
@@ -23,7 +24,7 @@ export const Method = [
   "head",
 ] as const;
 export type Method = (typeof Method)[number];
-export type CaseInsensitive<S extends string> = Uppercase<S> | Lowercase<S>;
+export type CaseInsensitive<S extends string> = S | Uppercase<S> | Lowercase<S>;
 export type CaseInsensitiveMethod = Method | Uppercase<Method>;
 export const isMethod = (x: unknown): x is Method =>
   Method.includes(x as Method);
@@ -83,14 +84,18 @@ type AsJsonApiSpec<AS extends ApiSpec> = Omit<AS, "headers" | "resHeaders"> & {
 
 export type ApiP<
   E extends ApiEndpoints,
-  Path extends keyof E & string,
+  Path extends (keyof E & string) | C.AnyE,
   M extends Method,
   P extends keyof ApiSpec,
-> = E[Path] extends ApiEndpoint
-  ? E[Path][M] extends ApiSpec<ParseUrlParams<Path>>
-    ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      E[Path][M][P] extends Record<string, any> | string
-      ? E[Path][M][P]
+> = Path extends keyof E & string
+  ? E[Path] extends ApiEndpoint
+    ? M extends Method
+      ? E[Path][M] extends ApiSpec<ParseUrlParams<Path>>
+        ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          E[Path][M][P] extends Record<string, any> | string
+          ? E[Path][M][P]
+          : undefined
+        : undefined
       : undefined
     : undefined
   : undefined;

Diff for: src/core/url.t-test.ts

@@ -1,6 +1,7 @@
 import { Equal, Expect } from "./type-test";
 import {
   MatchedPatterns,
+  NoPathError,
   ParseHostAndPort,
   ParseOriginAndPath,
   ParseURL,
@@ -55,6 +56,7 @@ type ToUrlPatternTestCases = [
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 type MatchedPatternsTestCases = [
+  Expect<Equal<MatchedPatterns<string, "">, NoPathError>>,
   Expect<Equal<MatchedPatterns<"", "">, "">>,
   Expect<Equal<MatchedPatterns<"/1", "/:userId">, "/:userId">>,
   Expect<

Diff for: src/core/url.ts

@@ -1,5 +1,6 @@
 import { ParseQueryString } from "./query-string";
 import { ExtractByPrefix, SameSlashNum, Split, UndefinedTo } from "./type";
+import { C } from "../compile-error-utils";
 
 type ExtractParams<T extends string> = ExtractByPrefix<T, ":">;
 
@@ -63,6 +64,8 @@ export type ToUrlPattern<T extends string> = T extends `${infer O}?${infer R}`
   ? `${ToUrlParamPattern<O>}?${ToUrlPattern<R>}`
   : ToUrlParamPattern<T>;
 
+export type NoPathError = C.E<"no matched path found">;
+
 /**
  * Extract matched URL pattern from URL
  * T: URL
@@ -74,13 +77,17 @@ export type ToUrlPattern<T extends string> = T extends `${infer O}?${infer R}`
  * // => "/users/:userId"
  * ```
  */
-export type MatchedPatterns<T extends string, Patterns extends string> = keyof {
-  [P in Patterns as T extends ToUrlPattern<P>
-    ? SameSlashNum<P, T> extends true
-      ? P
-      : never
-    : never]: true;
-};
+export type MatchedPatterns<
+  T extends string,
+  Patterns extends string,
+  Matched = {
+    [P in Patterns as T extends ToUrlPattern<P>
+      ? SameSlashNum<P, T> extends true
+        ? P
+        : never
+      : never]: true;
+  },
+> = Matched extends Record<string, never> ? NoPathError : keyof Matched;
 
 /**
  * Parse host and port

Diff for: src/fetch/index.ts

@@ -5,39 +5,41 @@ import {
   CaseInsensitiveMethod,
   MatchedPatterns,
   MergeApiResponseBodies,
-  Method,
   NormalizePath,
   ParseURL,
   PathToUrlParamPattern,
   Replace,
   StatusCode,
   IsAllOptional,
-  CaseInsensitive,
   ExtractQuery,
-  IsValidQuery,
+  ValidateQuery,
   ToQueryUnion,
+  Method,
+  CaseInsensitive,
 } from "../core";
 import { UrlPrefixPattern, ToUrlParamPattern } from "../core";
 import { TypedString } from "../json";
+import { C } from "../compile-error-utils";
 
-type IsValidUrl<
+type ValidateUrl<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   QueryDef extends Record<string, unknown> | undefined,
   Url extends string,
   Query extends string | undefined = ExtractQuery<Url>,
   QueryKeys extends string = Query extends string ? ToQueryUnion<Query> : never,
-> = IsValidQuery<
+> = ValidateQuery<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/ban-types
   QueryDef extends Record<string, any> ? QueryDef : {},
   QueryKeys
 >;
 
 export type RequestInitT<
-  InputMethod extends CaseInsensitiveMethod,
+  CanOmitMethod extends boolean,
   Body extends Record<string, unknown> | string | undefined,
   HeadersObj extends string | Record<string, string> | undefined,
+  InputMethod extends CaseInsensitiveMethod,
 > = Omit<RequestInit, "method" | "body" | "headers"> &
-  (InputMethod extends "get" | "GET"
+  (CanOmitMethod extends true
     ? { method?: InputMethod }
     : { method: InputMethod }) &
   (Body extends Record<string, unknown>
@@ -57,8 +59,37 @@ export type RequestInitT<
 
 /**
  * FetchT is a type for window.fetch like function but more strict type information
+ *
+ * @template UrlPrefix - url prefix of `Input`
+ * For example, if `UrlPrefix` is "https://example.com", then `Input` must be `https://example.com/${string}`
+ *
+ * @template E - ApiEndpoints
+ * E is used to infer the type of the acceptable path, response body, and more
  */
 type FetchT<UrlPrefix extends UrlPrefixPattern, E extends ApiEndpoints> = <
+  /**
+   * internal type for FetchT
+   *
+   * @template UrlPattern - Acceptable url pattern
+   * for example, if endpoints is defined as below:
+   * { "/users": ..., "/users/:userId": ... }
+   * then UrlPattern will be "/users" | "/users/:userId"
+   *
+   * @template InputPath - Extracted path from `Input`
+   *
+   * @template CandidatePaths - Matched paths from `InputPath` and `keyof E`
+   *
+   * @template AcceptableMethods - Acceptable methods for the matched path
+   *
+   * @template InputMethod - Method of the request
+   *
+   * @template LM - Lowercase of `InputMethod`
+   *
+   * @template Query - Query object
+   *
+   * @template ResBody - Response body
+   *
+   */
   UrlPattern extends ToUrlParamPattern<`${UrlPrefix}${keyof E & string}`>,
   Input extends Query extends undefined
     ? UrlPattern
@@ -70,40 +101,51 @@ type FetchT<UrlPrefix extends UrlPrefixPattern, E extends ApiEndpoints> = <
       ParseURL<Replace<Input, ToUrlParamPattern<UrlPrefix>, "">>["path"]
     >
   >,
-  CandidatePaths extends string = MatchedPatterns<InputPath, keyof E & string>,
-  InputMethod extends CaseInsensitive<keyof E[CandidatePaths] & string> &
-    CaseInsensitiveMethod = CaseInsensitive<keyof E[CandidatePaths] & string> &
-    CaseInsensitiveMethod,
-  M extends Method = CaseInsensitive<"get"> extends InputMethod
-    ? "get"
-    : Lowercase<InputMethod>,
-  Query extends ApiP<E, CandidatePaths, M, "query"> = ApiP<
+  CandidatePaths extends MatchedPatterns<
+    InputPath,
+    keyof E & string
+  > = MatchedPatterns<InputPath, keyof E & string>,
+  AcceptableMethods extends CandidatePaths extends string
+    ? Extract<Method, keyof E[CandidatePaths]>
+    : never = CandidatePaths extends string
+    ? Extract<Method, keyof E[CandidatePaths]>
+    : never,
+  InputMethod extends CaseInsensitive<AcceptableMethods> = Extract<
+    AcceptableMethods,
+    "get"
+  >,
+  LM extends Lowercase<InputMethod> = Lowercase<InputMethod>,
+  Query extends ApiP<E, CandidatePaths, LM, "query"> = ApiP<
     E,
     CandidatePaths,
-    M,
+    LM,
     "query"
   >,
   ResBody extends ApiP<
     E,
     CandidatePaths,
-    M,
+    LM,
     "responses"
   > extends AnyApiResponses
-    ? MergeApiResponseBodies<ApiP<E, CandidatePaths, M, "responses">>
+    ? MergeApiResponseBodies<ApiP<E, CandidatePaths, LM, "responses">>
     : Record<StatusCode, never> = ApiP<
     E,
     CandidatePaths,
-    M,
+    LM,
     "responses"
   > extends AnyApiResponses
-    ? MergeApiResponseBodies<ApiP<E, CandidatePaths, M, "responses">>
+    ? MergeApiResponseBodies<ApiP<E, CandidatePaths, LM, "responses">>
     : Record<StatusCode, never>,
 >(
-  input: IsValidUrl<Query, Input> extends true ? Input : never,
+  input: ValidateUrl<Query, Input> extends C.OK
+    ? Input
+    : ValidateUrl<Query, Input>,
   init: RequestInitT<
-    InputMethod,
-    ApiP<E, CandidatePaths, M, "body">,
-    ApiP<E, CandidatePaths, M, "headers">
+    // If `get` method is defined in the spec, method can be omitted
+    "get" extends AcceptableMethods ? true : false,
+    ApiP<E, CandidatePaths, LM, "body">,
+    ApiP<E, CandidatePaths, LM, "headers">,
+    InputMethod
   >,
 ) => Promise<ResBody>;