Feat: contract definition

packages/app/api-contracts/src/apiContracts.ts

@@ -1,4 +1,5 @@
 import type { ZodSchema, z } from 'zod/v4'
+import type { AnyDeleteRoute, AnyGetRoute, AnyPayloadRoute, AnyRoute } from './contractService.js'
 import type { HttpStatusCode } from './HttpStatusCodes.ts'
 
 export type { HttpStatusCode }
@@ -264,3 +265,72 @@ export function mapRouteToPath(
 
   return routeDefinition.pathResolver(resolverParams)
 }
+
+export type InferGetDetails<Route extends AnyGetRoute> = Route extends GetRouteDefinition<
+  infer SuccessResponseBodySchema,
+  infer PathParamsSchema,
+  infer RequestQuerySchema,
+  infer RequestHeaderSchema,
+  infer IsNonJSONResponseExpected,
+  infer IsEmptyResponseExpected
+>
+  ? {
+      responseBodySchema: SuccessResponseBodySchema
+      pathParamsSchema: PathParamsSchema
+      requestQuerySchema: RequestQuerySchema
+      requestHeaderSchema: RequestHeaderSchema
+      isNonJSONResponseExpected: IsNonJSONResponseExpected
+      isEmptyResponseExpected: IsEmptyResponseExpected
+    }
+  : never
+
+export type InferDeleteDetails<Route extends AnyDeleteRoute> = Route extends DeleteRouteDefinition<
+  infer SuccessResponseBodySchema,
+  infer PathParamsSchema,
+  infer RequestQuerySchema,
+  infer RequestHeaderSchema,
+  infer IsNonJSONResponseExpected,
+  infer IsEmptyResponseExpected
+>
+  ? {
+      responseBodySchema: SuccessResponseBodySchema
+      pathParamsSchema: PathParamsSchema
+      requestQuerySchema: RequestQuerySchema
+      requestHeaderSchema: RequestHeaderSchema
+      isNonJSONResponseExpected: IsNonJSONResponseExpected
+      isEmptyResponseExpected: IsEmptyResponseExpected
+    }
+  : never
+
+export type InferPayloadDetails<Route extends AnyPayloadRoute> =
+  Route extends PayloadRouteDefinition<
+    infer RequestBodySchema,
+    infer SuccessResponseBodySchema,
+    infer PathParamsSchema,
+    infer RequestQuerySchema,
+    infer RequestHeaderSchema,
+    infer IsNonJSONResponseExpected,
+    infer IsEmptyResponseExpected
+  >
+    ? {
+        requestBodySchema: RequestBodySchema
+        responseBodySchema: SuccessResponseBodySchema
+        pathParamsSchema: PathParamsSchema
+        requestQuerySchema: RequestQuerySchema
+        requestHeaderSchema: RequestHeaderSchema
+        isNonJSONResponseExpected: IsNonJSONResponseExpected
+        isEmptyResponseExpected: IsEmptyResponseExpected
+      }
+    : never
+
+export type InferRouteDetails<Route extends AnyRoute> = Route extends AnyGetRoute
+  ? InferGetDetails<Route>
+  : Route extends AnyDeleteRoute
+    ? InferDeleteDetails<Route>
+    : Route extends AnyPayloadRoute
+      ? InferPayloadDetails<Route>
+      : never
+
+export * from './contractService.js'
+export * from './headers/createHeaderBuilderMiddleware.js'
+export * from './headers/headerBuilder.js'

packages/app/api-contracts/src/contractService.ts

@@ -0,0 +1,35 @@
+import type {
+  DeleteRouteDefinition,
+  GetRouteDefinition,
+  PayloadRouteDefinition,
+} from './apiContracts.js'
+
+// biome-ignore lint/suspicious/noExplicitAny: This can actually be any type of route
+export type AnyGetRoute = GetRouteDefinition<any, any, any, any, any, any>
+// biome-ignore lint/suspicious/noExplicitAny: This can actually be any type of route
+export type AnyDeleteRoute = DeleteRouteDefinition<any, any, any, any, any, any>
+// biome-ignore lint/suspicious/noExplicitAny: This can actually be any type of route
+export type AnyPayloadRoute = PayloadRouteDefinition<any, any, any, any, any, any>
+export type AnyRoute = AnyGetRoute | AnyDeleteRoute | AnyPayloadRoute
+
+// biome-ignore lint/suspicious/noExplicitAny: This can actually be any type of route
+export type AnyCacheKeyFn = (...args: any[]) => Array<any>
+
+export type AnyRoutes = {
+  [key: string]: {
+    route: AnyRoute
+    cacheKey: AnyCacheKeyFn
+  }
+}
+
+export type ContractDefinitions<Routes extends AnyRoutes> = {
+  serviceName: string
+  config: { routes: Routes }
+}
+
+export function definedContract<R extends AnyRoutes>(
+  service: string,
+  routes: R,
+): ContractDefinitions<R> {
+  return { serviceName: service, config: { routes } }
+}

packages/app/api-contracts/src/headers/createHeaderBuilderMiddleware.test.ts

@@ -0,0 +1,66 @@
+import { createHeaderBuilderMiddleware } from './createHeaderBuilderMiddleware.js'
+import { HeaderBuilder } from './headerBuilder.js'
+import { describe, expect, it } from 'vitest'
+
+describe('createHeaderBuilderMiddleware', () => {
+	it('should create a middleware that adds a header', async () => {
+		const middleware = createHeaderBuilderMiddleware((builder) =>
+			builder.add('X-Test-Header', 'test-value'),
+		)
+
+		const builder = HeaderBuilder.create().with(middleware)
+		const actual = await builder.resolve()
+
+		expect(actual).toEqual({ 'X-Test-Header': 'test-value' })
+	})
+
+	it('should create a middleware that adds multiple headers', async () => {
+		const middleware = createHeaderBuilderMiddleware((builder) =>
+			builder.and({
+				'X-Test-Header-1': 'value1',
+				'X-Test-Header-2': 'value2',
+			}),
+		)
+
+		const builder = HeaderBuilder.create().with(middleware)
+		const actual = await builder.resolve()
+
+		expect(actual).toEqual({
+			'X-Test-Header-1': 'value1',
+			'X-Test-Header-2': 'value2',
+		})
+	})
+
+	it('should create a middleware that adds headers asynchronously', async () => {
+		const middleware = createHeaderBuilderMiddleware(async (builder) => {
+			const token = await new Promise<string>((resolve) => resolve('async-token'))
+			return builder.add('authorization', `Bearer ${token}`)
+		})
+
+		const builder = HeaderBuilder.create().with(middleware)
+		const actual = await builder.resolve()
+
+		expect(actual).toEqual({ authorization: 'Bearer async-token' })
+	})
+
+	it('should create a middleware that merges headers from another builder', async () => {
+		const otherBuilder = HeaderBuilder.create().add('X-Other-Header', 'other-value')
+		const middleware = createHeaderBuilderMiddleware((builder) => builder.merge(otherBuilder))
+
+		const builder = HeaderBuilder.create().with(middleware)
+		const actual = await builder.resolve()
+
+		expect(actual).toEqual({ 'X-Other-Header': 'other-value' })
+	})
+
+	it('should handle middleware that returns a promise of a builder', async () => {
+		const middleware = createHeaderBuilderMiddleware((builder) =>
+			Promise.resolve(builder.add('X-Promise-Header', 'promise-value')),
+		)
+
+		const builder = HeaderBuilder.create().with(middleware)
+		const actual = await builder.resolve()
+
+		expect(actual).toEqual({ 'X-Promise-Header': 'promise-value' })
+	})
+})

packages/app/api-contracts/src/headers/createHeaderBuilderMiddleware.ts

@@ -0,0 +1,59 @@
+import { HeaderBuilder, type Headers } from './headerBuilder.js'
+
+/**
+ * A helper function that creates a HeaderBuilderMiddleware, it removed the
+ * complexity of creating a new instance of the middleware class and tracking the input types.
+ *
+ * @param middleware - A function that modifies a HeaderBuilder
+ * @returns - A new instance of HeaderBuilderMiddleware to be used with a HeaderBuilder
+ */
+export function createHeaderBuilderMiddleware<const H extends Headers>(
+    middleware: (builder: HeaderBuilder) => HeaderBuilder<H> | Promise<HeaderBuilder<H>>,
+) {
+    return new HeaderBuilderMiddleware<H>(middleware)
+}
+
+// There is no need to have access to the implementation of the HeaderBuilderMiddleware class
+// all users should use the createHeaderBuilderMiddleware function to create a new instance,
+// but I have to export the type for reference outside the file
+export type { HeaderBuilderMiddleware }
+
+type MiddlewareFn<H extends Headers> = (
+    builder: HeaderBuilder<Headers>,
+) => HeaderBuilder<H> | Promise<HeaderBuilder<H>>
+
+/**
+ * A middleware class that allows you to modify a HeaderBuilder in a type-safe way.
+ * It receives a builder and returns a new builder with the modifications applied.
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware = createHeaderBuilderMiddleware(async (builder) => {
+ *   const token = await fetchToken()
+ *   return builder.add('authorization', `Bearer ${token}`)
+ * })
+ *
+ *  const builder = HeaderBuilder.create()
+ *  .with(authMiddleware)
+ *
+ *  const headers = await builder.resolve() // Type of headers is { 'authorization': string }
+ *  console.log(headers) // { 'authorization': 'Bearer <token>' }
+ */
+class HeaderBuilderMiddleware<const H extends Headers> {
+    private readonly middleware: MiddlewareFn<H>
+
+    constructor(middleware: MiddlewareFn<H>) {
+        this.middleware = middleware
+    }
+
+    apply<const BH extends Headers>(base: HeaderBuilder<BH>): HeaderBuilder<BH & H> {
+        // Using the `from` method to make the promise lazy - it should only resolve when the builder is resolved
+        return base.from(async () => {
+            const middlewareBuilder = this.middleware(HeaderBuilder.create())
+
+            return middlewareBuilder instanceof Promise
+                ? middlewareBuilder.then((r) => r.resolve())
+                : middlewareBuilder.resolve()
+        })
+    }
+}

packages/app/api-contracts/src/headers/headerBuilder.test.ts

@@ -0,0 +1,134 @@
+import { createHeaderBuilderMiddleware } from './createHeaderBuilderMiddleware.js'
+import { HeaderBuilder } from './headerBuilder.js'
+import { describe, expect, vitest } from 'vitest'
+
+// biome-ignore lint/complexity/noBannedTypes: To test empty headers, we need to use an empty object type.
+type ExpectedEmptyHeaders = {}
+
+// It is critical that type safety is maintained when refactoring - this offers a way to unit test the type-system.
+// The call will fail to build if the expected type is not correct.
+const typeCheck = <const Expected>(_actual: Expected): void => {}
+
+describe('HeaderBuilder', () => {
+	it('should create an empty header builder', async () => {
+		const builder = HeaderBuilder.create()
+
+		const actual = await builder.resolve()
+
+		typeCheck<ExpectedEmptyHeaders>(actual)
+
+		expect(actual).toEqual({})
+	})
+
+	it('should create a header builder with default headers', async () => {
+		const builder = HeaderBuilder.create({ 'Content-Type': 'application/json' })
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json' }>(actual)
+
+		expect(actual).toEqual({ 'Content-Type': 'application/json' })
+	})
+
+	it('should allow individual headers to be added to the builder by name', async () => {
+		const builder = HeaderBuilder.create().add('Content-Type', 'application/json')
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json' }>(actual)
+
+		expect(actual).toEqual({ 'Content-Type': 'application/json' })
+	})
+
+	it('should allow multiple headers to be added in one static object', async () => {
+		const builder = HeaderBuilder.create().and({
+			'Content-Type': 'application/json',
+			'X-Api-Key': '1234',
+		})
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json'; 'X-Api-Key': '1234' }>(actual)
+
+		expect(actual).toEqual({ 'Content-Type': 'application/json', 'X-Api-Key': '1234' })
+	})
+
+	it('should allow multiple headers to be added in a promise of one static object', async () => {
+		const builder = HeaderBuilder.create().and(
+			Promise.resolve({
+				'Content-Type': 'application/json',
+				'X-Api-Key': '1234',
+			}),
+		)
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json'; 'X-Api-Key': '1234' }>(actual)
+
+		expect(actual).toEqual({ 'Content-Type': 'application/json', 'X-Api-Key': '1234' })
+	})
+
+	it('should allow headers to be added from a factory function', async () => {
+		const builder = HeaderBuilder.create().from(async () => {
+			const token = await mockGetToken()
+			return { authorization: `Bearer ${token}` }
+		})
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ authorization: string }>(actual)
+
+		expect(actual).toEqual({ authorization: 'Bearer 1234' })
+	})
+
+	const mockGetToken = async () => '1234'
+
+	it('should allow you to extend the builder with middleware functions', async () => {
+		const middleware = createHeaderBuilderMiddleware(async (builder) => {
+			const token = await mockGetToken()
+			return builder.and({ authorization: `Bearer ${token}` })
+		})
+
+		const builder = HeaderBuilder.create().with(middleware)
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ authorization: string }>(actual)
+
+		expect(actual).toEqual({ authorization: 'Bearer 1234' })
+	})
+
+	it('should lazy load promises and only resolve them when the headers are resolved', async () => {
+		const factory = vitest.fn(async () => ({ 'Content-Type': 'application/json' }) as const)
+		const middlewareMock = vitest.fn(async (builder: HeaderBuilder) =>
+			builder.add('X-Api-Key', '1234'),
+		)
+
+		const middleware = createHeaderBuilderMiddleware(middlewareMock)
+
+		const builder = HeaderBuilder.create().from(factory).with(middleware)
+
+		expect(factory).not.toHaveBeenCalled()
+		expect(middlewareMock).not.toHaveBeenCalled()
+
+		const actual = await builder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json'; 'X-Api-Key': '1234' }>(actual)
+
+		expect(factory).toHaveBeenCalled()
+		expect(actual).toEqual({ 'Content-Type': 'application/json', 'X-Api-Key': '1234' })
+	})
+
+	it('should merge two header builders', async () => {
+		const builder1 = HeaderBuilder.create().add('Content-Type', 'application/json')
+		const builder2 = HeaderBuilder.create().add('authorization', 'Bearer token')
+
+		const mergedBuilder = builder1.merge(builder2)
+
+		const actual = await mergedBuilder.resolve()
+
+		typeCheck<{ 'Content-Type': 'application/json'; authorization: 'Bearer token' }>(actual)
+
+		expect(actual).toEqual({ 'Content-Type': 'application/json', authorization: 'Bearer token' })
+	})
+})