Shared API types w/ inference, validation, E2E type safety

.eslintrc.json

@@ -41,7 +41,8 @@
 		"react-refresh/only-export-components": ["error", { "allowConstantExport": true }],
 		"no-unused-labels": "off",
 		"@typescript-eslint/array-type": ["error", { "default": "array-simple" }],
-		"no-control-regex": "off"
+		"no-control-regex": "off",
+		"@typescript-eslint/no-dynamic-delete": "off"
 	},
 	"parserOptions": {
 		"project": ["tsconfig.tools.json"]

README.md

@@ -104,12 +104,6 @@ pnpm analyze # bundle size analysis
 
 ## TODO
 
-- finish auth
-  - better utils for "protected" stuff (client & server)
-  - add endpoint for "which providers are already associated with current user"
-    - on the client side, this can be used to hide the "associate" button for these providers
-    - on the client side, this gives us the opportunity to make an "online-only" component demo
-    - this is a good opportunity to make a trpc-like fullstack type-safe query system
 - database
   - figure out migrations story
 - cleanup bento

client/package.json

@@ -22,6 +22,7 @@
 	},
 	"dependencies": {
 		"assets": "workspace:assets@*",
+		"server": "workspace:server@*",
 		"shared": "workspace:shared@*"
 	},
 	"devDependencies": {

client/src/api/helpers.ts

@@ -0,0 +1,24 @@
+import type { ClientDefinition } from "server/api/helpers"
+import type { StringAsNumber } from "shared/typeHelpers"
+
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+type Fail = 1 | 3 | 4 | 5
+
+type SuccessCodes = StringAsNumber<`2${Digit}${Digit}`> | "2xx"
+type FailCodes = StringAsNumber<`${Fail}${Digit}${Digit}`> | `${Fail}xx`
+
+export type DefResponse<Def extends ClientDefinition> = Def["schema"]["Reply"][SuccessCodes &
+	keyof Def["schema"]["Reply"]]
+export type DefError<Def extends ClientDefinition> = Def["schema"]["Reply"][FailCodes &
+	keyof Def["schema"]["Reply"]]
+
+export function makeHeaders(data?: Record<string, unknown>) {
+	if (!data) return undefined
+	// TS doesn't like Headers being constructed with arbitrary data, but `Headers` will stringify every value.
+	const headers = new Headers(data as Record<string, string>)
+	return headers
+}
+
+export function getKey(url: string, method: string, data?: object | null) {
+	return [url.split("/"), method, data ?? {}]
+}

client/src/api/useApiMutation.ts

@@ -0,0 +1,73 @@
+import { type UseMutationOptions, useMutation } from "@tanstack/react-query"
+import { makeHeaders, type DefError, type DefResponse, getKey } from "client/api/helpers"
+import type { ClientDefinition } from "server/api/helpers"
+import { replaceParams } from "shared/replaceParams"
+import type { Prettify } from "shared/typeHelpers"
+
+type MutData = "Querystring" | "Params" | "Headers" | "Body"
+
+type DefVariables<Def extends ClientDefinition> =
+	object extends Prettify<Pick<Def["schema"], MutData & keyof Def["schema"]>>
+		? null
+		: Prettify<Pick<Def["schema"], MutData & keyof Def["schema"]>>
+
+type MissingKeys<from, provided extends Partial<from>> = from extends object
+	? object extends provided
+		? from
+		: Pick<
+				from,
+				{
+					[key in keyof from]: key extends keyof provided ? never : key
+				}[keyof from]
+			>
+	: void
+
+export function useApiMutation<
+	Def extends ClientDefinition,
+	Early extends Partial<DefVariables<Def>> = object,
+>(
+	{ url, method }: Def,
+	early?: Early | null,
+	options?: Omit<
+		UseMutationOptions<
+			Prettify<DefResponse<Def>>,
+			Prettify<DefError<Def>>,
+			Prettify<MissingKeys<DefVariables<Def>, Early>>
+		>,
+		"mutationKey" | "mutationFn"
+	>
+) {
+	return useMutation<
+		Prettify<DefResponse<Def>>,
+		Prettify<DefError<Def>>,
+		Prettify<MissingKeys<DefVariables<Def>, Early>>
+	>({
+		...options,
+		mutationKey: getKey(url, method, early),
+		async mutationFn(lazy: Prettify<MissingKeys<DefVariables<Def>, Early>>) {
+			const data = { ...early, ...lazy } as unknown as DefVariables<Def>
+			// Params are placed in the pathname
+			const replaced = replaceParams(url, data?.Params ?? {})
+			// Querystring is placed in the search params
+			const withBody = data?.Querystring
+				? `${replaced}?${new URLSearchParams(data.Querystring).toString()}`
+				: replaced
+			// Body is stringified and placed in the body
+			const body = data?.Body ? JSON.stringify(data.Body) : undefined
+			// Headers are placed in the headers
+			const headers =
+				makeHeaders(data?.Headers as Record<string, unknown>) ?? body
+					? new Headers()
+					: undefined
+			if (body) headers?.set("Content-Type", "application/json")
+			const response = await fetch(withBody, {
+				method,
+				headers,
+				body,
+			})
+			const result = await response.json().catch(() => {})
+			if (response.status < 200 || response.status >= 300) throw result
+			return result as Prettify<DefResponse<Def>>
+		},
+	})
+}

client/src/api/useApiQuery.ts

@@ -0,0 +1,37 @@
+import { useQuery, type UseQueryOptions } from "@tanstack/react-query"
+import { makeHeaders, type DefError, type DefResponse, getKey } from "client/api/helpers"
+import type { ClientDefinition } from "server/api/helpers"
+import { replaceParams } from "shared/replaceParams"
+import type { Prettify } from "shared/typeHelpers"
+
+type GetData = "Querystring" | "Params" | "Headers"
+
+export function useApiQuery<Def extends ClientDefinition, T = Prettify<DefResponse<Def>>>(
+	{ url, method }: Def,
+	data: object extends Pick<Def["schema"], GetData & keyof Def["schema"]>
+		? null
+		: Prettify<Pick<Def["schema"], GetData & keyof Def["schema"]>>,
+	options?: Omit<
+		UseQueryOptions<Prettify<DefResponse<Def>>, Prettify<DefError<Def>>, T>,
+		"queryKey" | "queryFn"
+	>
+) {
+	return useQuery<Prettify<DefResponse<Def>>, Prettify<DefError<Def>>, T>({
+		...options,
+		queryKey: getKey(url, method, data),
+		async queryFn() {
+			// Params are placed in the pathname
+			const replaced = replaceParams(url, data?.Params ?? {})
+			// Querystring is placed in the search params
+			const withBody = data?.Querystring
+				? `${replaced}?${new URLSearchParams(data.Querystring).toString()}`
+				: replaced
+			// Headers are placed in the headers
+			const headers = makeHeaders(data?.Headers as Record<string, unknown>)
+			const response = await fetch(withBody, { method, headers })
+			const result = await response.json().catch(() => {})
+			if (response.status < 200 || response.status >= 300) throw result
+			return result as Prettify<DefResponse<Def>>
+		},
+	})
+}

client/src/components/ApiDemo.tsx

@@ -1,34 +1,46 @@
-import { useEffect, useState } from "react"
+import { useApiMutation } from "client/api/useApiMutation"
+import { useApiQuery } from "client/api/useApiQuery"
+import { Button } from "client/components/Button/Button"
+import { definition as openDefinition } from "server/api/open"
+import { definition as protectedDefinition } from "server/api/protected"
+import { definition as saveDefinition } from "server/api/save"
 
 export function ApiDemo() {
-	const [protectedRes, setProtectedRes] = useState<unknown>()
-	useEffect(() => {
-		fetch("/api/protected")
-			.then((res) => res.json())
-			.then(setProtectedRes)
-			.catch((e) => {
-				console.error(e)
-				setProtectedRes({ error: String(e) })
-			})
-	}, [])
+	const open = useApiQuery(openDefinition, {
+		Headers: { "x-id": "123" },
+		Querystring: { id: "42" },
+	})
 
-	const [openRes, setOpenRes] = useState<unknown>()
-	useEffect(() => {
-		fetch("/api/hello")
-			.then((res) => res.json())
-			.then(setOpenRes)
-			.catch((e) => {
-				console.error(e)
-				setOpenRes({ error: String(e) })
-			})
-	}, [])
+	const secret = useApiQuery(protectedDefinition, null, {
+		retry: false,
+	})
+
+	const save = useApiMutation(saveDefinition, null, {
+		onSuccess(data, variables, context) {
+			console.log("Saved", data, variables, context)
+			setTimeout(() => save.reset(), 1000)
+		},
+	})
 
 	return (
 		<>
 			<h2>Open</h2>
-			<pre>{openRes ? JSON.stringify(openRes, null, 2) : " \n  loading\n "}</pre>
+			<pre>{open.data ? JSON.stringify(open.data, null, 2) : " \n  loading\n "}</pre>
 			<h2>Protected</h2>
-			<pre>{protectedRes ? JSON.stringify(protectedRes, null, 2) : " \n  loading\n "}</pre>
+			<pre>
+				{secret.error
+					? JSON.stringify(secret.error, null, 2)
+					: secret.data
+						? JSON.stringify(secret.data, null, 2)
+						: " \n  loading\n "}
+			</pre>
+			<h2>Mutation</h2>
+			<Button
+				disabled={save.isPending || save.isSuccess}
+				onClick={() => save.mutate({ Body: { hello: "world", moo: 42 } })}
+			>
+				{save.isPending ? "mutating..." : save.isSuccess ? "ok" : "Save"}
+			</Button>
 		</>
 	)
 }

client/src/components/Button/Button.module.css

@@ -16,6 +16,11 @@
 	touch-action: manipulation;
 	white-space: nowrap;
 	margin-right: 10px;
+
+	&[disabled] {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
 }
 
 .dark {

client/src/components/UserAccountDemo.tsx

@@ -1,7 +1,9 @@
+import { useApiQuery } from "client/api/useApiQuery"
 import type { Provider } from "client/auth/providers"
 import { useAuthContext } from "client/auth/useAuthContext"
 import { Button } from "client/components/Button/Button"
 import { Divider } from "client/components/Divider/Divider"
+import { definition as accountsDefinition } from "server/api/accounts"
 
 export function UserAccountDemo() {
 	const auth = useAuthContext()
@@ -116,6 +118,7 @@ function LoggedIn({
 	linkAccount: (provider: string) => Promise<void>
 	providers: Provider[]
 }) {
+	const accounts = useApiQuery(accountsDefinition, null)
 	return (
 		<>
 			<div>Logged in as {userId}</div>
@@ -130,6 +133,7 @@ function LoggedIn({
 						onClick={() => void linkAccount(provider.key)}
 						dark
 						style={{ backgroundColor: provider.color }}
+						disabled={accounts.data?.accounts.includes(provider.key)}
 					>
 						{provider.name}
 					</Button>

client/tsconfig.app.json

@@ -18,6 +18,7 @@
 		"src/**/*.test.ts",
 		"types/*.d.ts",
 		"../types/*.d.ts",
-		"../shared/src/**/*.ts"
+		"../shared/src/**/*.ts",
+		"../server/src/api/**/*.ts"
 	]
 }

client/turbo.json

@@ -40,6 +40,7 @@
 				"types/*.d.ts",
 				"../types/*.d.ts",
 				"../shared/src/**/*.ts",
+				"../server/src/api/**/*.ts",
 				"tsconfig.json",
 				"tsconfig.app.json"
 			],

client/vite.config.ts

@@ -217,6 +217,8 @@ export default defineConfig({
 		alias: {
 			// use alias to avoid having "client" as a package dependency of "client"
 			"client/": `${normalizePath(__dirname)}/src/`,
+			// allow imports from "server" to resolve to the server folder, despite tsconfig aliases
+			"server/": `${normalizePath(__dirname)}/../server/src/`,
 		},
 	},
 	server: {

knip.jsonc

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://unpkg.com/knip@4/schema.json",
+	"$schema": "https://unpkg.com/knip@5/schema.json",
 	"ignoreDependencies": [
 		// used by fastify, with just a string reference, no import
 		"pino-pretty",
@@ -12,5 +12,6 @@
 		// knip doesn't grab the "sub-projects" of main tsconfig files (like tsconfig.app.json), so it never discovers .d.ts files
 		"**/types/*.d.ts"
 	],
+	"include": ["nsExports", "nsTypes"],
 	"includeEntryExports": true
 }

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "repo",
-	"version": "0.0.0-alpha.6",
+	"version": "0.0.0-alpha.7",
 	"license": "MIT",
 	"private": true,
 	"repository": {
@@ -73,6 +73,7 @@
 		"knip": "^5.0.1",
 		"prettier": "^3.2.5",
 		"rollup-plugin-visualizer": "5.12.0",
+		"json-schema-to-ts": "3.0.0",
 		"tsx": "4.7.1",
 		"turbo": "1.12.3",
 		"typed-css-modules": "^0.9.1",