ts-procedures 9.1.0 → 9.3.0

package/src/core/create-http.test-d.ts

@@ -0,0 +1,154 @@
+import { Type } from 'typebox'
+import { describe, expectTypeOf, test } from 'vitest'
+
+import { Procedures } from './procedures.js'
+import type { HttpReturn } from './create-http.js'
+import type {
+  HttpReq,
+  HttpSchemaInput,
+  TCreateHttpConfig,
+  THttpReqInput,
+  THttpResInput,
+} from './types.js'
+import type { APIInput } from '../server/types.js'
+
+// ---------------------------------------------------------------------------
+// Type tests for HTTP input shape autocomplete / DX contract
+// These guard the shapes that power IDE autocomplete for schema.req / schema.res.
+// ---------------------------------------------------------------------------
+
+describe('THttpReqInput / THttpResInput / APIInput', () => {
+  test('APIInput accepts only the four known channels', () => {
+    // Valid
+    const good: APIInput = {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({}),
+      body: Type.Object({}),
+      headers: Type.Object({}),
+    }
+    expectTypeOf(good).toEqualTypeOf<APIInput>()
+
+    // Invalid channel should not be assignable
+    // @ts-expect-error - unknown channel name
+    const _bad: APIInput = { wrong: Type.Object({}) as any }
+  })
+
+  test('THttpResInput shape', () => {
+    const resShape: THttpResInput = {
+      body: Type.Object({ ok: Type.Boolean() }),
+      headers: Type.Object({ 'x-foo': Type.String() }),
+    }
+    expectTypeOf(resShape).toEqualTypeOf<THttpResInput>()
+  })
+})
+
+describe('TCreateHttpConfig shapes for literals', () => {
+  test('config literal gets the channel keys from the shape (autocomplete contract)', () => {
+    const cfg: TCreateHttpConfig = {
+      path: '/x',
+      method: 'get',
+      schema: {
+        req: {
+          // These keys should be suggested by the IDE
+          pathParams: Type.Object({ id: Type.String() }),
+          query: undefined,
+        },
+        res: {
+          body: Type.Object({}),
+        },
+      },
+    }
+    expectTypeOf(cfg).toEqualTypeOf<TCreateHttpConfig>()
+  })
+
+  test('using satisfies APIInput on req is valid and preserves specific types', () => {
+    const req = {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({ q: Type.Optional(Type.String()) }),
+    } satisfies APIInput
+
+    const cfg: TCreateHttpConfig<typeof req> = {
+      path: '/y',
+      method: 'get',
+      schema: { req },
+    }
+
+    // The assignment succeeded, proving the shape accepted the keys
+    // (specific inference of TReq from literal is a bonus)
+  })
+})
+
+describe('handler inference via HttpReq / HttpReturn', () => {
+  const procs = Procedures()
+
+  test('full req shape produces correctly typed handler param', () => {
+    const { Get } = procs.CreateHttp(
+      'Get',
+      {
+        path: '/u/:id',
+        method: 'get',
+        schema: {
+          req: {
+            pathParams: Type.Object({ id: Type.String() }),
+            query: Type.Object({ verbose: Type.Optional(Type.Boolean()) }),
+          },
+        },
+      },
+      async (_ctx, req) => {
+        expectTypeOf(req).toEqualTypeOf<{
+          pathParams: { id: string }
+          query: { verbose?: boolean }
+        }>()
+        // no res schema => void
+        return undefined
+      }
+    )
+
+    type Handler = typeof Get
+    expectTypeOf<Parameters<Handler>[1]>().toEqualTypeOf<{
+      pathParams: { id: string }
+      query: { verbose?: boolean }
+    }>()
+  })
+
+  test('res with headers produces { body, headers } return shape', () => {
+    const { WithHeaders } = procs.CreateHttp(
+      'WithHeaders',
+      {
+        path: '/h',
+        method: 'get',
+        schema: {
+          res: {
+            body: Type.Object({ data: Type.String() }),
+            headers: Type.Object({ 'x-trace': Type.String() }),
+          },
+        },
+      },
+      async () => ({ body: { data: 'hi' }, headers: { 'x-trace': 'abc' } })
+    )
+
+    type R = Awaited<ReturnType<typeof WithHeaders>>
+    expectTypeOf<R>().toEqualTypeOf<{ body: { data: string }; headers: { 'x-trace': string } }>()
+  })
+
+  test('no schema.res yields void (204-style)', () => {
+    const { Logout } = procs.CreateHttp(
+      'Logout',
+      { path: '/logout', method: 'post' },
+      async () => undefined
+    )
+
+    type R = Awaited<ReturnType<typeof Logout>>
+    expectTypeOf<R>().toEqualTypeOf<void>()
+  })
+})
+
+// Smoke test that HttpReq and HttpSchemaInput are exported and usable
+test('HttpReq and HttpSchemaInput are exported and usable', () => {
+  type ExampleReq = HttpSchemaInput<THttpReqInput, { pathParams: { id: string } }>
+  expectTypeOf<ExampleReq>().toHaveProperty('pathParams')
+
+  // HttpReq resolves through Infer; we just check it doesn't error and has shape
+  type H = HttpReq<{ query: { q?: string } }>
+  expectTypeOf<H>().toHaveProperty('query')
+})

package/src/core/create-http.ts

@@ -10,7 +10,15 @@ import {
   validateReqChannels,
 } from './internal.js'
 import type { FactoryRuntime } from './internal.js'
-import type { ProcedureResult, TCreateHttpConfig, TLocalContext, THttpProcedureRegistration } from './types.js'
+import type {
+  HttpReq,
+  ProcedureResult,
+  TCreateHttpConfig,
+  THttpProcedureRegistration,
+  THttpReqInput,
+  THttpResInput,
+  TLocalContext,
+} from './types.js'
 
 /**
  * The handler return shape is gated by the DECLARED response schema, not by
@@ -26,10 +34,6 @@ export type HttpReturn<TRes> =
   : TRes extends { body: infer B }                 ? Infer<B>
   : void
 
-type HttpReq<TReq> = TReq extends Record<string, unknown>
-  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
-  : undefined
-
 export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>) {
   /**
    * Defines a REST-shaped HTTP procedure with per-channel input validation
@@ -40,8 +44,8 @@ export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>)
    */
   return function CreateHttp<
     TName extends string,
-    TReq extends Record<string, unknown> | undefined = undefined,
-    TRes extends { body?: unknown; headers?: unknown } | undefined = undefined,
+    TReq extends THttpReqInput | undefined = undefined,
+    TRes extends THttpResInput | undefined = undefined,
     TErrorKey extends string = string,
   >(
     name: TName,

package/src/core/types.ts

@@ -1,7 +1,7 @@
 import type * as AJV from 'ajv'
 import type { ProcedureError } from './errors.js'
 import type { SchemaAdapter } from '../schema/adapter.js'
-import type { TJSONSchema } from '../schema/json-schema.js'
+import type { Infer, Prettify, TJSONSchema } from '../schema/json-schema.js'
 import type { Validate } from '../schema/compile.js'
 
 export type TNoContextProvided = unknown
@@ -69,7 +69,64 @@ export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = u
 
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
 
-export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+/**
+ * Canonical shape for `schema.req` channels.
+ * Used both to constrain generics and to provide autocomplete when writing
+ * `CreateHttp` / `CreateHttpStream` config objects.
+ *
+ * Note: RPC `Create` / `CreateStream` use a flatter `schema: { params?, yieldType?, returnType? }`
+ * directly (no extra container generic), so they don't need an equivalent named input shape.
+ */
+export type THttpReqInput = {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+}
+
+/**
+ * Canonical shape for `schema.res` on CreateHttp (CreateHttpStream only supports `headers`).
+ */
+export type THttpResInput = {
+  body?: unknown
+  headers?: unknown
+}
+
+/**
+ * @internal Helper to surface literal channel keys for autocomplete
+ * while still threading the user's concrete generic schemas through for inference.
+ */
+export type HttpSchemaInput<Base, T> = Base & (T extends undefined ? {} : T)
+
+/**
+ * @internal Shared helper for typing the destructured `req` argument passed to
+ * CreateHttp / CreateHttpStream handlers. Mirrors the per-channel Infer.
+ */
+export type HttpReq<TReq> = TReq extends Record<string, unknown>
+  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
+  : undefined
+
+/**
+ * Shape used for the `schema` option of `CreateHttpStream`.
+ * Reuses the same req input shape as CreateHttp for autocomplete consistency.
+ */
+export type THttpStreamSchema<
+  TReq extends THttpReqInput | undefined = undefined,
+  TYield = unknown,
+  TReturn = void,
+  TResHeaders = undefined,
+> = {
+  req?: HttpSchemaInput<THttpReqInput, TReq>
+  yield?: TYield
+  returnType?: TReturn
+  res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
+}
+
+export type TCreateHttpConfig<
+  TReq extends THttpReqInput | undefined = undefined,
+  TRes extends THttpResInput | undefined = undefined,
+  TErrorKey extends string = string,
+> = {
   path: string
   method: HttpMethod
   successStatus?: number
@@ -78,8 +135,10 @@ export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
   description?: string
   /** Optional — a no-input, no-output route (e.g. a 204 logout) may omit it. */
   schema?: {
-    req?: TReq
-    res?: TRes
+    // HttpSchemaInput surfaces the channel keys for IDE autocomplete / excess-property checking
+    // while the generic part carries the caller's concrete schema (for Infer + handler typing).
+    req?: HttpSchemaInput<THttpReqInput, TReq>
+    res?: HttpSchemaInput<THttpResInput, TRes>
   }
 }
 

package/src/exports.ts

@@ -23,6 +23,11 @@ export type {
   THttpProcedureRegistration,
   THttpStreamProcedureRegistration,
   TCreateHttpConfig,
+  THttpReqInput,
+  THttpResInput,
+  THttpStreamSchema,
+  HttpSchemaInput,
+  HttpReq,
   TLocalContext,
   TStreamContext,
   TNoContextProvided,

package/src/server/types.ts

@@ -6,7 +6,7 @@
  * guarantees byte-identical generated output vs v8. Do not change field names,
  * optionality, or nesting without re-validating the codegen goldens.
  */
-import type { ProcedureKind } from '../core/types.js'
+import type { ProcedureKind, THttpReqInput } from '../core/types.js'
 import type { ErrorTaxonomy } from './errors/taxonomy.js'
 
 /**
@@ -97,6 +97,9 @@ export interface APIHttpRouteDoc {
  * Constrains `schema.req` channel names to valid HTTP input sources.
  * Use with `satisfies` to catch typos at compile time:
  *
+ * The same shape also powers autocomplete inside `schema.req` when using
+ * CreateHttp / CreateHttpStream.
+ *
  * @example
  * schema: {
  *   req: {
@@ -105,17 +108,10 @@ export interface APIHttpRouteDoc {
  *   } satisfies APIInput
  * }
  */
-export type APIInput<T extends {
-  pathParams?: unknown
-  query?: unknown
-  body?: unknown
-  headers?: unknown
-} = {
-  pathParams?: unknown
-  query?: unknown
-  body?: unknown
-  headers?: unknown
-}> = T
+export type APIInput<T extends THttpReqInput = THttpReqInput> = T
+
+// Re-export the canonical input shapes (useful for advanced typing or custom wrappers)
+export type { THttpReqInput, THttpResInput } from '../core/types.js'
 
 export interface StreamHttpRouteDoc extends RPCConfig {
   kind: 'stream'