@beignet/core 0.0.48 → 0.0.50

package/src/contracts/contract-builder.ts

@@ -5,6 +5,7 @@ import {
   mergeCatalogErrors,
   responsesFromErrors,
 } from "./catalog-errors.js";
+import { assertContractQueryTransport } from "./contract-like.js";
 import {
   assertValidContractDeprecation,
   assertValidContractLifecycle,
@@ -13,6 +14,10 @@ import {
 import { mergeContractMeta } from "./metadata.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
 import { parsePathTemplate } from "./path-template.js";
+import type {
+  QueryTransport,
+  QueryTransportCompatibility,
+} from "./query-transport.js";
 import type {
   BodyHttpMethod,
   ContractErrorResponses,
@@ -56,6 +61,7 @@ export class ContractBuilder<
   private readonly _path: TPath;
   private readonly _pathParams: TPathParams;
   private readonly _query: TQuery;
+  private readonly _queryTransport: QueryTransport | null;
   private readonly _body: TBody;
   private readonly _headers: THeaders;
   private readonly _responses: TResponses;
@@ -74,6 +80,7 @@ export class ContractBuilder<
     >,
   ) {
     assertValidContractLifecycle(config);
+    assertContractQueryTransport(config);
     if (config.body && !methodSupportsRequestBody(config.method)) {
       throw new Error(
         `Request bodies are not supported for ${config.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
@@ -87,6 +94,7 @@ export class ContractBuilder<
     this._path = config.path;
     this._pathParams = config.pathParams;
     this._query = config.query;
+    this._queryTransport = config.queryTransport ?? null;
     this._body = config.body;
     this._headers = config.headers ?? (null as THeaders);
     this._responses = config.responses;
@@ -152,6 +160,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -186,6 +195,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: schema as unknown as TNewPathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -194,10 +204,21 @@ export class ContractBuilder<
   }
 
   /**
-   * Attach a schema for query parameters.
+   * Attach a query schema and the deterministic URL transport for its input.
+   *
+   * The schema owns validation, defaults, and transforms. The transport owns
+   * client encoding, server decoding, and OpenAPI serialization.
    */
-  query<TNewQuery extends StandardSchemaV1>(
+  query<
+    TNewQuery extends StandardSchemaV1,
+    const TTransport extends QueryTransport,
+  >(
     schema: TNewQuery,
+    transport: TTransport &
+      QueryTransportCompatibility<
+        StandardSchemaV1.InferInput<TNewQuery>,
+        TTransport
+      >,
   ): ContractBuilder<
     TMethod,
     TPathParams,
@@ -217,6 +238,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: schema as unknown as TNewQuery,
+      queryTransport: transport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -270,6 +292,7 @@ export class ContractBuilder<
       path: self._path,
       pathParams: self._pathParams,
       query: self._query,
+      queryTransport: self._queryTransport,
       headers: self._headers,
       body: schema as unknown as TNewBody,
       responses: self._responses,
@@ -315,6 +338,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: [
         ...existingHeaders,
         schema,
@@ -360,6 +384,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: {
@@ -410,6 +435,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: {
@@ -456,6 +482,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -488,6 +515,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -519,6 +547,7 @@ export class ContractBuilder<
       path: this._path,
       pathParams: this._pathParams,
       query: this._query,
+      queryTransport: this._queryTransport,
       headers: this._headers,
       body: this._body,
       responses: this._responses,
@@ -588,6 +617,7 @@ export function defineContract<
     path: options.path,
     pathParams: null,
     query: null,
+    queryTransport: null,
     headers: null,
     body: null,
     responses: {},

package/src/contracts/contract-group.ts

@@ -467,6 +467,7 @@ export class ContractGroup<
       path: fullPath,
       pathParams: null,
       query: null,
+      queryTransport: null,
       headers: this._headers,
       body: null,
       responses: { ...this._responses } as unknown as TSharedResponses,

package/src/contracts/contract-like.ts

@@ -1,5 +1,42 @@
+import {
+  compareQueryTransportFields,
+  formatQueryTransportMismatch,
+  getObjectSchemaShape,
+} from "./schema-shape.js";
 import type { HttpContractConfig } from "./types.js";
 
+/** Assert that a plain contract config declares one transport per query. */
+export function assertContractQueryTransport(
+  contract: HttpContractConfig,
+): void {
+  if (contract.query && !contract.queryTransport) {
+    throw new Error(
+      `Contract "${contract.name}" declares a query schema without a query transport. Pass defineQueryTransport(...) as the second argument to .query(...).`,
+    );
+  }
+  if (!contract.query && contract.queryTransport) {
+    throw new Error(
+      `Contract "${contract.name}" declares a query transport without a query schema.`,
+    );
+  }
+  if (contract.query && contract.queryTransport) {
+    const shape = getObjectSchemaShape(contract.query);
+    if (!shape) return;
+
+    const schemaKeys = Object.keys(shape);
+    const transportKeys = Object.keys(contract.queryTransport.fields);
+    if (!compareQueryTransportFields({ schemaKeys, transportKeys })) {
+      throw new Error(
+        formatQueryTransportMismatch({
+          contractName: contract.name,
+          schemaKeys,
+          transportKeys,
+        }),
+      );
+    }
+  }
+}
+
 /**
  * Contract input accepted by APIs that can unwrap builders.
  */
@@ -25,5 +62,7 @@ export type ResolveContract<T> = T extends { config: infer C }
 export function resolveContract<T extends ContractLike>(
   c: T,
 ): ResolveContract<T> {
-  return ("config" in c ? c.config : c) as ResolveContract<T>;
+  const contract = ("config" in c ? c.config : c) as ResolveContract<T>;
+  assertContractQueryTransport(contract);
+  return contract;
 }

package/src/contracts/index.ts

@@ -55,6 +55,29 @@ export {
   type PathTemplateSegment,
   parsePathTemplate,
 } from "./path-template.js";
+/**
+ * Query transport declarations shared by servers, clients, and OpenAPI.
+ */
+export {
+  decodeQueryTransport,
+  defineQueryTransport,
+  encodeQueryTransport,
+  type QueryArrayTransport,
+  type QueryDeepObjectFields,
+  type QueryDeepObjectTransport,
+  type QueryEmptyBehavior,
+  type QueryFieldTransport,
+  type QueryFieldTransportInput,
+  type QueryScalarTransport,
+  type QueryTransport,
+  type QueryTransportCompatibility,
+  QueryTransportError,
+  type QueryTransportFields,
+  type QueryTransportInput,
+  type QueryTransportIssue,
+  query,
+  queryTransportSchema,
+} from "./query-transport.js";
 /**
  * Rate limit metadata types for contracts.
  */