bazis 0.98.0 → 0.98.2

package/cli/templates/module.ts

@@ -355,7 +355,7 @@ function listQueryFile(n: ModuleNaming): string {
   return `import { Filterable, ListOptions, ListRequest, Sortable } from "bazis/core/http";
 import type { ${n.entity} } from "../../model/${n.module}.model";
 
-@ListOptions({ defaultSize: 20, maxSize: 100 })
+@ListOptions({ defaultSize: 20, maxSize: 100, defaultSort: "-createdAt" })
 export class ${n.module}ListQuery extends ListRequest<${n.entity}> {
   @Sortable()
   @Filterable("eq", "contains", "startsWith")

package/core/http/Binding/ParameterBinder.ts

@@ -24,6 +24,21 @@ function bindValue(binding: ParameterBinding, raw: string | undefined, kind: str
   return binding.type && binding.type !== "string" ? convertOr400(raw, binding.type, binding.name ?? "?") : raw;
 }
 
+/**
+ * `?tag=a&tag=b` → `["a", "b"]`, each value converted by the element type.
+ * Without the parameter: the default, `undefined` for `tag?: string[]`, or `[]`.
+ */
+function bindArray(binding: ParameterBinding, ctx: HttpContext): unknown {
+  const raw = ctx.url.searchParams.getAll(binding.name ?? "");
+  if (raw.length === 0) {
+    if (binding.defaultValue !== undefined) return binding.defaultValue;
+    return binding.optional ? undefined : [];
+  }
+  return binding.type && binding.type !== "string"
+    ? raw.map((value) => convertOr400(value, binding.type!, binding.name ?? "?"))
+    : raw;
+}
+
 /**
  * Resolves generated binding descriptors into the action's argument list.
  * All conversions fail with 400 (never 500); body parse errors and model
@@ -52,7 +67,7 @@ export async function bindArguments(
         break;
       }
       case "query":
-        args[index] = bindValue(binding, ctx.query(binding.name ?? ""), "query");
+        args[index] = binding.array ? bindArray(binding, ctx) : bindValue(binding, ctx.query(binding.name ?? ""), "query");
         break;
       case "body": {
         const contentType = ctx.header("content-type") ?? "";

package/core/http/Binding/autoBindings.ts

@@ -55,7 +55,7 @@ function toBinding(spec: GeneratedBindingSpec, controllerName: string, methodNam
     case "route":
       return { source: "route", name: spec.name, type: spec.type, optional: spec.optional };
     case "query":
-      return { source: "query", name: spec.name, type: spec.type, optional: spec.optional };
+      return { source: "query", name: spec.name, type: spec.type, optional: spec.optional, array: spec.array };
     case "context":
       return { source: "context" };
     case "request":

package/core/http/Binding/bindings.ts

@@ -11,6 +11,8 @@ export interface ParameterBinding {
   readonly type?: ValueType;
   readonly defaultValue?: unknown;
   readonly optional?: boolean;
+  /** Query array: all values of the name (`?tag=a&tag=b`), each converted by `type`. */
+  readonly array?: boolean;
   /** Body model class (instantiated, sanitized and validated). */
   readonly model?: Class<object>;
   /** Whitelist/limits for the class-based list binding (JSON:API list query). */

package/core/http/Binding/generatedSpec.ts

@@ -13,6 +13,8 @@ export interface GeneratedBindingSpec {
   readonly type?: "int" | "number" | "bool" | "string";
   /** The parameter is declared with `?` or a default value. */
   readonly optional?: boolean;
+  /** A query array (`tag: string[]`): every `?tag=` value, each converted by `type`. */
+  readonly array?: boolean;
   /** DTO class name (resolved through the generated target; `@RequestModel()` classes are the fallback). */
   readonly model?: string;
 }

package/core/http/OpenApi/openApiDocument.ts

@@ -173,8 +173,8 @@ function collectParameters(
           parameters.push({
             name: binding.name,
             in: "query",
-            required: binding.optional !== true && binding.defaultValue === undefined,
-            schema: schemaForValueType(binding.type),
+            required: binding.array !== true && binding.optional !== true && binding.defaultValue === undefined,
+            schema: binding.array ? { type: "array", items: schemaForValueType(binding.type) } : schemaForValueType(binding.type),
           });
         }
         break;

package/core/http/Routing/Router.ts

@@ -17,6 +17,8 @@ export interface RouteAction {
 
 interface RouteEntry {
   readonly action: RouteAction;
+  /** The registered path, for diagnostics: `/tasks/:id`. */
+  readonly template: string;
   /** Names belong to the selected declaration, never to shared tree edges. */
   readonly bindings: readonly { readonly name: string; readonly index: number }[];
 }
@@ -58,6 +60,7 @@ export class Router {
   register(segments: readonly TemplateSegment[], httpMethod: string, versionKey: string, action: RouteAction): void {
     const entry: RouteEntry = {
       action,
+      template: renderTemplate(segments),
       bindings: segments.flatMap((segment, index) => segment.kind === "static" ? [] : [{ name: segment.name, index }]),
     };
     let node = this.root;
@@ -101,8 +104,11 @@ export class Router {
       leaf.set(httpMethod, versions);
     }
     if (versions.has(versionKey)) {
+      const existing = versions.get(versionKey)!;
+      const version = versionKey ? ` (version ${versionKey})` : "";
       throw new HttpSetupError(
-        `Duplicate route: ${httpMethod} (version "${versionKey || "-"}") already mapped to ${versions.get(versionKey)!.action.name}, cannot map ${entry.action.name}.`,
+        `Duplicate route: ${httpMethod} ${entry.template}${version} is mapped to both ${existing.action.name} (${existing.template}) and ${entry.action.name}. `
+          + "Routes that differ only in parameter names are the same route; change one of the paths.",
       );
     }
     versions.set(versionKey, entry);
@@ -199,3 +205,10 @@ function constraintPriority(constraint: SegmentConstraint | undefined): number {
       return 0;
   }
 }
+
+/** `/tasks/:id(int)/files/*path` from parsed segments. */
+function renderTemplate(segments: readonly TemplateSegment[]): string {
+  return `/${segments.map((segment) => segment.kind === "static" ? segment.value
+    : segment.kind === "param" ? `:${segment.name}${segment.constraint ? `(${segment.constraint.name})` : ""}`
+    : `*${segment.name}`).join("/")}`;
+}

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.2" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/scripts/di-generate.ts

@@ -178,6 +178,7 @@ interface HttpBindingSpec {
   type?: "int" | "number" | "bool" | "string";
   optional?: boolean;
   model?: string;
+  array?: boolean;
 }
 let httpBindings: Record<string, Record<string, HttpBindingSpec[]>> = {};
 interface GrpcRequestBinding {
@@ -1030,6 +1031,16 @@ function readConstructorTypeNames(node: ts.ClassDeclaration): ConstructorDepende
 }
 
 /** Resolve imported type aliases/re-exports; runtime named binding stays module-scoped. */
+/** The element keyword of an array type: `string[]`, `Array<string>`, `readonly string[]` -> "string". */
+function arrayElementKeyword(node: ts.TypeNode): string | undefined {
+  if (ts.isTypeOperatorNode(node) && node.operator === ts.SyntaxKind.ReadonlyKeyword) return arrayElementKeyword(node.type);
+  if (ts.isArrayTypeNode(node)) return node.elementType.getText().trim();
+  if (ts.isTypeReferenceNode(node) && ["Array", "ReadonlyArray"].includes(node.typeName.getText()) && node.typeArguments?.length === 1) {
+    return node.typeArguments[0]!.getText().trim();
+  }
+  return undefined;
+}
+
 function getDependencyTypeName(node: ts.TypeNode): string | undefined {
   if (!ts.isTypeReferenceNode(node)) return undefined;
   const symbol = checker.getSymbolAtLocation(node.typeName);
@@ -1425,6 +1436,13 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
         specs.push({ source: "route", name: paramName, type: type === "string" ? undefined : type, optional });
         continue;
       }
+      // `tag: string[]`, `Array<number>`, `readonly boolean[]` -> every ?tag= value.
+      const elementKeyword = typeNode ? arrayElementKeyword(typeNode) : undefined;
+      const elementType = elementKeyword !== undefined ? PRIMITIVE_QUERY_TYPES[elementKeyword] : undefined;
+      if (elementType !== undefined) {
+        specs.push({ source: "query", name: paramName, type: elementType === "string" ? undefined : elementType, optional, array: true });
+        continue;
+      }
       const primitiveType =
         keywordType !== undefined ? PRIMITIVE_QUERY_TYPES[keywordType] : inferTypeFromInitializer(param.initializer);
       if (primitiveType !== undefined) {

package/library/jsonapi/decorators.ts

@@ -18,6 +18,7 @@ export interface ListSchema {
   readonly fields: Record<string, FieldSchema>;
   page?: PageOptions;
   include?: readonly string[];
+  defaultSort?: string;
 }
 
 interface SchemaMetadata {
@@ -32,6 +33,11 @@ export interface ListOptionsConfig {
   readonly maxSize?: number;
   /** Allowed include paths (`?include=`). */
   readonly include?: readonly string[];
+  /**
+   * Sorting when the request has no `sort`: `"-createdAt"`, `"-createdAt,name"`.
+   * Every field must be `@Sortable()`. The primary key still breaks ties.
+   */
+  readonly defaultSort?: string;
 }
 
 /**
@@ -43,7 +49,7 @@ function ensureOwnSchema(metadata: SchemaMetadata): ListSchema {
   if (!Object.prototype.hasOwnProperty.call(metadata, LIST_SCHEMA)) {
     const inherited = metadata[LIST_SCHEMA];
     metadata[LIST_SCHEMA] = inherited
-      ? { fields: cloneFields(inherited.fields), page: inherited.page, include: inherited.include }
+      ? { fields: cloneFields(inherited.fields), page: inherited.page, include: inherited.include, defaultSort: inherited.defaultSort }
       : { fields: {} };
   }
   return metadata[LIST_SCHEMA]!;
@@ -124,6 +130,16 @@ export function ListOptions(config: ListOptionsConfig) {
     if (config.include !== undefined) {
       schema.include = config.include;
     }
+    if (config.defaultSort !== undefined) {
+      // Field decorators have already run: check the declared fields now, at import time.
+      for (const token of config.defaultSort.split(",").map((part) => part.trim()).filter(Boolean)) {
+        const field = token.replace(/^[-+]/, "");
+        if (schema.fields[field]?.sortable !== true) {
+          throw new Error(`@ListOptions on ${String(context.name)}: defaultSort field "${field}" is not @Sortable().`);
+        }
+      }
+      schema.defaultSort = config.defaultSort;
+    }
   };
 }
 
@@ -157,5 +173,5 @@ export function optionsFromSchema(ctor: unknown): ListQueryOptions {
       filter[name] = field.filterOps;
     }
   }
-  return { sort, filter, include: schema.include, page: schema.page };
+  return { sort, filter, include: schema.include, page: schema.page, defaultSort: schema.defaultSort };
 }

package/library/jsonapi/document.ts

@@ -38,6 +38,12 @@ export interface BuildListDocumentOptions {
    * `links` are not built.
    */
   readonly basePath?: string;
+  /**
+   * JSON:API resource type for sparse fieldsets: `?fields[tasks]=name` keeps
+   * only `id` and `name` in every item. Default: the last segment of
+   * `basePath` (`"/api/tasks"` → `"tasks"`).
+   */
+  readonly type?: string;
 }
 
 /**
@@ -59,10 +65,29 @@ export function buildListDocument<T>(
   const pageCount = size > 0 ? Math.max(1, Math.ceil(total / size)) : 1;
   const meta: ListMeta = { total, page: query.page.number, size, pageCount };
 
+  const data = sparseFieldset(items, query, options.type ?? lastSegment(options.basePath));
   if (options.basePath === undefined) {
-    return { data: items, meta };
+    return { data, meta };
+  }
+  return { data, meta, links: buildLinks(query, options.basePath, meta) };
+}
+
+/** Items reduced to `id` and the fields requested with `fields[type]`; unchanged without it. */
+function sparseFieldset<T>(items: readonly T[], query: ListQuery, type: string | undefined): readonly T[] {
+  const fields = type === undefined ? undefined : query.fields[type];
+  if (fields === undefined || fields.length === 0) {
+    return items;
   }
-  return { data: items, meta, links: buildLinks(query, options.basePath, meta) };
+  const keep = new Set(["id", ...fields]);
+  return items.map((item) => {
+    if (item === null || typeof item !== "object") return item;
+    return Object.fromEntries(Object.entries(item as Record<string, unknown>).filter(([key]) => keep.has(key))) as T;
+  });
+}
+
+function lastSegment(basePath: string | undefined): string | undefined {
+  const segment = basePath?.split("?")[0]?.split("/").filter(Boolean).at(-1);
+  return segment === undefined || segment === "" ? undefined : segment;
 }
 
 /**

package/library/jsonapi/parseListQuery.ts

@@ -77,7 +77,9 @@ function parseSort(
   problems: ListQueryProblem[],
 ): SortField[] {
   const result: SortField[] = [];
-  for (const token of splitCsv(params.getAll("sort"))) {
+  const requested = splitCsv(params.getAll("sort"));
+  const tokens = requested.length === 0 && options.defaultSort !== undefined ? splitCsv([options.defaultSort]) : requested;
+  for (const token of tokens) {
     const dir: SortDirection = token.startsWith("-") ? "desc" : "asc";
     const field = token.replace(/^[-+]/, "");
     if (field === "") {

package/library/jsonapi/types.ts

@@ -122,4 +122,6 @@ export interface ListQueryOptions {
   readonly include?: readonly string[];
   /** Paging limits. */
   readonly page?: PageOptions;
+  /** Sorting when the request has no `sort`, in the same syntax: `"-createdAt,name"`. */
+  readonly defaultSort?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.0",
+  "version": "0.98.2",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",