adorn-api 1.0.6 → 1.0.8

package/README.md

@@ -140,6 +140,58 @@ export class ProductsController {
 }
 ```
 
+### Query Objects
+
+Use an object-typed parameter to bind flat query keys:
+
+```typescript
+import type { Query } from "adorn-api";
+
+type Filters = {
+  status?: string;
+  responsavelId?: number;
+};
+
+@Get("/")
+async list(query?: Query<Filters>) {
+  return query;
+}
+```
+
+`GET /posts?status=published&responsavelId=1`
+
+### Deep Object Query (opt-in)
+
+For bracketed query serialization, opt in with `@QueryStyle({ style: "deepObject" })`:
+
+```typescript
+import { QueryStyle } from "adorn-api";
+
+type WhereFilter = {
+  responsavel?: {
+    perfil?: {
+      nome?: string;
+    };
+  };
+  tags?: string[];
+};
+
+@Get("/")
+  @QueryStyle({ style: "deepObject" })
+async list(where?: WhereFilter) {
+  return where;
+}
+```
+
+- `GET /posts?where[responsavel][perfil][nome]=Admin`
+- `GET /posts?where[tags]=a&where[tags]=b`
+- `GET /posts?where[comments][author][name]=Ali` (matches `Alice`)
+
+Notes:
+- Deep object is explicit and only applies to the query object parameter on that method.
+- Repeated keys become arrays (for example, `where[tags]=a&where[tags]=b`).
+- The `[]` shorthand is not supported; use repeated keys instead.
+
 ## Examples
 
 ### Basic Example
@@ -275,8 +327,8 @@ import { Controller, Get, Post, Put, Delete } from "adorn-api";
 import { BlogPost } from "../entities/index.js";
 import { getSession, selectFromEntity, eq } from "metal-orm";
 
-@Controller("/posts")
-export class PostsController {
+@Controller("/blog-posts")
+export class BlogPostsController {
   @Get("/")
   async getPosts(query?: { authorId?: number; status?: string }) {
     const session = getSession();
@@ -652,6 +704,7 @@ await bootstrap({
   swaggerJsonPath?: string,   // Default: "/docs/openapi.json"
   middleware?: CreateRouterOptions["middleware"],
   auth?: CreateRouterOptions["auth"],
+  coerce?: CreateRouterOptions["coerce"],
 });
 ```
 
@@ -672,6 +725,15 @@ const router = await createExpressRouter({
   auth?: {
     schemes: Record<string, AuthSchemeRuntime>,
   },
+  coerce?: {
+    body?: boolean,
+    query?: boolean,
+    path?: boolean,
+    header?: boolean,
+    cookie?: boolean,
+    dateTime?: boolean,
+    date?: boolean,
+  },
   middleware?: {
     global?: Middleware[],
     named?: Record<string, Middleware>,
@@ -679,6 +741,8 @@ const router = await createExpressRouter({
 });
 ```
 
+Date properties in TypeScript map to OpenAPI `type: "string"` with `format: "date-time"`. Enable `coerce` to convert ISO 8601 date-time strings into `Date` instances before your handler runs. For date-only strings, use `@Format("date")` and keep `date` coercion off to avoid timezone shifts. You can disable per-field coercion with `@Schema({ "x-adorn-coerce": false })`.
+
 ### setupSwagger()
 
 Add Swagger UI to any Express app:

package/dist/adapter/express/bootstrap.d.ts

@@ -11,6 +11,7 @@ export interface BootstrapOptions {
     swaggerJsonPath?: string;
     middleware?: CreateRouterOptions["middleware"];
     auth?: CreateRouterOptions["auth"];
+    coerce?: CreateRouterOptions["coerce"];
 }
 export interface BootstrapResult {
     server: Server;

package/dist/adapter/express/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../src/adapter/express/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAAuB,KAAK,mBAAmB,EAA0C,MAAM,YAAY,CAAC;AAGnH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqG7E"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../src/adapter/express/bootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAAuB,KAAK,mBAAmB,EAA0C,MAAM,YAAY,CAAC;AAGnH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuG7E"}

package/dist/adapter/express/index.d.ts

@@ -7,8 +7,18 @@ interface OpenAPI31 {
         schemas: Record<string, Record<string, unknown>>;
         securitySchemes?: Record<string, Record<string, unknown>>;
     };
+    paths?: Record<string, Record<string, any>>;
     security?: Array<Record<string, string[]>>;
 }
+export interface CoerceOptions {
+    body?: boolean;
+    query?: boolean;
+    path?: boolean;
+    header?: boolean;
+    cookie?: boolean;
+    dateTime?: boolean;
+    date?: boolean;
+}
 export interface CreateRouterOptions {
     controllers: Array<new (...args: any[]) => any>;
     artifactsDir?: string;
@@ -17,6 +27,7 @@ export interface CreateRouterOptions {
     auth?: {
         schemes: Record<string, AuthSchemeRuntime>;
     };
+    coerce?: CoerceOptions;
     middleware?: {
         global?: Array<string | ((req: any, res: any, next: (err?: any) => void) => any)>;
         named?: Record<string, (req: any, res: any, next: (err?: any) => void) => any>;

package/dist/adapter/express/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapter/express/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAGpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAIvE,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACjD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KAC3D,CAAC;IACF,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C;AAMD,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,IAAI,CAAC,EAAE;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;KAC5C,CAAC;IACF,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC;KAChF,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACvD,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8OvF;AA8PD,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA4BtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapter/express/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAGpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAIvE,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACjD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KAC3D,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;CAC5C;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,IAAI,CAAC,EAAE;QACL,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;KAC5C,CAAC;IACF,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC;KAChF,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACvD,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAcD,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwSvF;AAijBD,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElE,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,MAAM,CA4BtE"}

package/dist/cli.cjs

@@ -214,7 +214,8 @@ function classifyParameters(parameters, httpMethod, pathParamIndices, checker) {
   for (let i = 0; i < parameters.length; i++) {
     const param = parameters[i];
     if (usedIndices.has(i)) continue;
-    const typeStr = param.type.getSymbol()?.getName() ?? "";
+    const nonNullableType = checker.getNonNullableType(param.type);
+    const typeStr = getTypeName(param.type) || getTypeName(nonNullableType);
     if (typeStr === "Body") {
       bodyParamIndex = i;
       usedIndices.add(i);
@@ -240,7 +241,7 @@ function classifyParameters(parameters, httpMethod, pathParamIndices, checker) {
       usedIndices.add(i);
       continue;
     }
-    const isObj = isObjectType(param.type, checker);
+    const isObj = isObjectType(nonNullableType, checker);
     if (isObj && queryObjectParamIndex === null && !isBodyMethod) {
       queryObjectParamIndex = i;
       usedIndices.add(i);
@@ -269,6 +270,12 @@ function isObjectType(type, checker) {
   if (callSignatures && callSignatures.length > 0) return false;
   return true;
 }
+function getTypeName(type) {
+  const aliasSymbol = type.aliasSymbol ?? type.aliasSymbol;
+  if (aliasSymbol) return aliasSymbol.getName();
+  const symbol = type.getSymbol();
+  return symbol?.getName() ?? "";
+}
 function findDecorator(node, name) {
   const decorators = import_typescript2.default.getDecorators(node);
   if (!decorators) return null;
@@ -303,7 +310,7 @@ function unwrapPromise(type, checker) {
 }
 
 // src/compiler/schema/openapi.ts
-var import_typescript5 = __toESM(require("typescript"), 1);
+var import_typescript6 = __toESM(require("typescript"), 1);
 
 // src/compiler/schema/typeToJsonSchema.ts
 var import_typescript3 = __toESM(require("typescript"), 1);
@@ -315,6 +322,9 @@ function typeToJsonSchema(type, ctx, typeNode) {
   if (type.flags & import_typescript3.default.TypeFlags.Null) {
     return { type: "null" };
   }
+  if (isDateType(type, checker)) {
+    return { type: "string", format: "date-time" };
+  }
   if (type.flags & import_typescript3.default.TypeFlags.String) {
     return { type: "string" };
   }
@@ -364,6 +374,19 @@ function typeToJsonSchema(type, ctx, typeNode) {
   }
   return {};
 }
+function isDateType(type, checker) {
+  const symbol = type.getSymbol();
+  const aliasSymbol = type.aliasSymbol;
+  if (aliasSymbol && aliasSymbol.flags & import_typescript3.default.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(aliasSymbol);
+    return aliased?.getName() === "Date";
+  }
+  if (symbol && symbol.flags & import_typescript3.default.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(symbol);
+    return aliased?.getName() === "Date";
+  }
+  return symbol?.getName() === "Date";
+}
 function isSetType(type, checker) {
   const symbol = type.getSymbol();
   if (!symbol) return false;
@@ -761,6 +784,56 @@ function mergeFragments(base, ...frags) {
   return result;
 }
 
+// src/compiler/analyze/extractQueryStyle.ts
+var import_typescript5 = __toESM(require("typescript"), 1);
+function extractQueryStyleOptions(checker, method) {
+  if (!import_typescript5.default.canHaveDecorators(method)) return null;
+  const decorators = import_typescript5.default.getDecorators(method);
+  if (!decorators || decorators.length === 0) return null;
+  for (const decorator of decorators) {
+    const expr = decorator.expression;
+    const isCall = import_typescript5.default.isCallExpression(expr);
+    const callee = isCall ? expr.expression : expr;
+    const args = isCall ? expr.arguments : import_typescript5.default.factory.createNodeArray([]);
+    const sym = checker.getSymbolAtLocation(callee);
+    if (!sym) continue;
+    const resolved = sym.flags & import_typescript5.default.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+    const name = resolved.getName();
+    if (name !== "QueryStyle") continue;
+    const optsNode = args[0];
+    if (!optsNode || !import_typescript5.default.isObjectLiteralExpression(optsNode)) {
+      return {};
+    }
+    return parseQueryStyleOptions(optsNode);
+  }
+  return null;
+}
+function parseQueryStyleOptions(node) {
+  const opts = {};
+  for (const prop of node.properties) {
+    if (!import_typescript5.default.isPropertyAssignment(prop)) continue;
+    const name = getPropName(prop.name);
+    if (!name) continue;
+    if (name === "style" && import_typescript5.default.isStringLiteral(prop.initializer)) {
+      const style = prop.initializer.text;
+      opts.style = style;
+    } else if (name === "explode" && isBooleanLiteral(prop.initializer)) {
+      opts.explode = prop.initializer.kind === import_typescript5.default.SyntaxKind.TrueKeyword;
+    } else if (name === "allowReserved" && isBooleanLiteral(prop.initializer)) {
+      opts.allowReserved = prop.initializer.kind === import_typescript5.default.SyntaxKind.TrueKeyword;
+    }
+  }
+  return opts;
+}
+function getPropName(name) {
+  if (import_typescript5.default.isIdentifier(name)) return name.text;
+  if (import_typescript5.default.isStringLiteral(name)) return name.text;
+  return null;
+}
+function isBooleanLiteral(node) {
+  return node.kind === import_typescript5.default.SyntaxKind.TrueKeyword || node.kind === import_typescript5.default.SyntaxKind.FalseKeyword;
+}
+
 // src/compiler/schema/openapi.ts
 function generateOpenAPI(controllers, checker, options = {}) {
   const components = /* @__PURE__ */ new Map();
@@ -852,12 +925,12 @@ function mergeBodySchemaAnnotations(bodyParam, ctx, schema) {
   const declarations = typeSymbol.getDeclarations();
   if (!declarations || declarations.length === 0) return schema;
   const classDecl = declarations[0];
-  if (!import_typescript5.default.isClassDeclaration(classDecl)) return schema;
+  if (!import_typescript6.default.isClassDeclaration(classDecl)) return schema;
   const result = { ...schema };
   const props = { ...result.properties };
   for (const member of classDecl.members) {
-    if (!import_typescript5.default.isPropertyDeclaration(member) || !member.name) continue;
-    const propName = import_typescript5.default.isIdentifier(member.name) ? member.name.text : null;
+    if (!import_typescript6.default.isPropertyDeclaration(member) || !member.name) continue;
+    const propName = import_typescript6.default.isIdentifier(member.name) ? member.name.text : null;
     if (!propName) continue;
     if (!props[propName]) continue;
     const frags = extractPropertySchemaFragments(ctx.checker, member);
@@ -892,19 +965,36 @@ function buildQueryParameters(operation, ctx, parameters) {
   if (operation.queryObjectParamIndex !== null) {
     const queryParam = operation.parameters[operation.queryObjectParamIndex];
     if (!queryParam) return;
+    const queryStyle = extractQueryStyleOptions(ctx.checker, operation.methodDeclaration);
     const querySchema = typeToJsonSchema(queryParam.type, ctx);
-    if (!querySchema.properties) return;
-    const queryObjProps = querySchema.properties;
-    for (const [propName, propSchema] of Object.entries(queryObjProps)) {
-      const isRequired = querySchema.required?.includes(propName) ?? false;
-      const serialization = determineQuerySerialization(propSchema.type);
-      parameters.push({
-        name: propName,
+    if (queryStyle?.style === "deepObject") {
+      const explode = queryStyle.explode ?? true;
+      const deepParam = {
+        name: queryParam.name,
         in: "query",
-        required: isRequired,
-        schema: propSchema,
-        ...Object.keys(serialization).length > 0 ? serialization : {}
-      });
+        required: !queryParam.isOptional,
+        schema: querySchema.$ref ? { $ref: querySchema.$ref } : querySchema,
+        style: "deepObject",
+        explode
+      };
+      if (queryStyle.allowReserved !== void 0) {
+        deepParam.allowReserved = queryStyle.allowReserved;
+      }
+      parameters.push(deepParam);
+    } else {
+      if (!querySchema.properties) return;
+      const queryObjProps = querySchema.properties;
+      for (const [propName, propSchema] of Object.entries(queryObjProps)) {
+        const isRequired = querySchema.required?.includes(propName) ?? false;
+        const serialization = determineQuerySerialization(propSchema.type);
+        parameters.push({
+          name: propName,
+          in: "query",
+          required: isRequired,
+          schema: propSchema,
+          ...Object.keys(serialization).length > 0 ? serialization : {}
+        });
+      }
     }
   }
   for (const paramIndex of operation.queryParamIndices) {
@@ -974,7 +1064,7 @@ function buildCookieParameters(operation, ctx, parameters) {
 }
 
 // src/compiler/manifest/emit.ts
-var import_typescript6 = __toESM(require("typescript"), 1);
+var import_typescript7 = __toESM(require("typescript"), 1);
 function generateManifest(controllers, checker, version, validationMode = "ajv-runtime") {
   const components = /* @__PURE__ */ new Map();
   const ctx = {
@@ -995,7 +1085,7 @@ function generateManifest(controllers, checker, version, validationMode = "ajv-r
     generator: {
       name: "adorn-api",
       version,
-      typescript: import_typescript6.default.version
+      typescript: import_typescript7.default.version
     },
     schemas: {
       kind: "openapi-3.1",
@@ -1080,21 +1170,38 @@ function buildQueryArgs(op, ctx, args) {
   if (op.queryObjectParamIndex !== null) {
     const queryParam = op.parameters[op.queryObjectParamIndex];
     if (queryParam) {
+      const queryStyle = extractQueryStyleOptions(ctx.checker, op.methodDeclaration);
       const querySchema = typeToJsonSchema(queryParam.type, ctx);
-      if (!querySchema.properties) return;
-      for (const [propName, propSchema] of Object.entries(querySchema.properties)) {
-        const isRequired = querySchema.required?.includes(propName) ?? false;
-        let schemaRef = propSchema.$ref;
-        if (!schemaRef) {
-          schemaRef = "#/components/schemas/InlineQueryParam";
-        }
+      if (queryStyle?.style === "deepObject") {
+        const schemaRef = querySchema.$ref ?? "#/components/schemas/InlineQueryParam";
         args.query.push({
-          name: propName,
+          name: queryParam.name,
           index: queryParam.index,
-          required: !isRequired,
+          required: !queryParam.isOptional,
           schemaRef,
-          schemaType: propSchema.type
+          schemaType: querySchema.type,
+          serialization: {
+            style: "deepObject",
+            explode: queryStyle.explode ?? true,
+            allowReserved: queryStyle.allowReserved
+          }
         });
+      } else {
+        if (!querySchema.properties) return;
+        for (const [propName, propSchema] of Object.entries(querySchema.properties)) {
+          const isRequired = querySchema.required?.includes(propName) ?? false;
+          let schemaRef = propSchema.$ref;
+          if (!schemaRef) {
+            schemaRef = "#/components/schemas/InlineQueryParam";
+          }
+          args.query.push({
+            name: propName,
+            index: queryParam.index,
+            required: !isRequired,
+            schemaRef,
+            schemaType: propSchema.type
+          });
+        }
       }
     }
   }
@@ -1297,7 +1404,7 @@ export function validateResponse(operationId, status, contentType, data) {
 // src/compiler/cache/isStale.ts
 var import_node_fs3 = __toESM(require("fs"), 1);
 var import_node_path3 = __toESM(require("path"), 1);
-var import_typescript7 = require("typescript");
+var import_typescript8 = require("typescript");
 var import_meta = {};
 function readJson(p) {
   try {
@@ -1404,7 +1511,7 @@ async function isStale(params) {
 // src/compiler/cache/writeCache.ts
 var import_node_fs4 = __toESM(require("fs"), 1);
 var import_node_path4 = __toESM(require("path"), 1);
-var import_typescript8 = __toESM(require("typescript"), 1);
+var import_typescript9 = __toESM(require("typescript"), 1);
 function statMtimeMs2(p) {
   return import_node_fs4.default.statSync(p).mtimeMs;
 }
@@ -1437,7 +1544,7 @@ function writeCache(params) {
     generator: {
       name: "adorn-api",
       version: params.adornVersion,
-      typescript: import_typescript8.default.version
+      typescript: import_typescript9.default.version
     },
     project: {
       tsconfigPath: params.tsconfigAbs,
@@ -1450,7 +1557,7 @@ function writeCache(params) {
 }
 
 // src/cli.ts
-var import_typescript9 = __toESM(require("typescript"), 1);
+var import_typescript10 = __toESM(require("typescript"), 1);
 var import_node_process = __toESM(require("process"), 1);
 var ADORN_VERSION = "0.1.0";
 function log(msg) {
@@ -1478,7 +1585,7 @@ async function buildCommand(args) {
       outDir: outputDir,
       project: projectPath,
       adornVersion: ADORN_VERSION,
-      typescriptVersion: import_typescript9.default.version
+      typescriptVersion: import_typescript10.default.version
     });
     if (!stale.stale) {
       log("adorn-api: artifacts up-to-date");