adorn-api 1.0.7 → 1.0.9

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();

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,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,CAmRvF;AAwdD,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);
@@ -777,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();
@@ -868,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);
@@ -908,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) {
@@ -990,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 = {
@@ -1011,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",
@@ -1096,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
+          });
+        }
       }
     }
   }
@@ -1313,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 {
@@ -1420,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;
 }
@@ -1453,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,
@@ -1466,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) {
@@ -1494,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");