metal-orm 1.1.0 → 1.1.2

package/README.md

@@ -110,8 +110,10 @@ Full docs live in the `docs/` folder:
 - **Table-valued functions**: use the new `tvf(key, …)` helper when you want portable intents such as `ARRAY_UNNEST`, letting the dialects’ `TableFunctionStrategy` renderers emit dialect-specific syntax (`LATERAL`/`WITH ORDINALITY`, alias validation, quoting, etc.). `fnTable()` remains available as the raw escape hatch when you need to emit a specific SQL function directly.
 - **String helpers**: `lower`, `upper`, `trim`, `ltrim/rtrim`, `concat/concatWs`, `substr/left/right`, `position/instr/locate`, `replace`, `repeat`, `lpad/rpad`, `space`, and more with dialect-aware rendering.
 - **Set operations**: `union`, `unionAll`, `intersect`, `except` across all dialects (ORDER/LIMIT apply to the combined result; hydration is disabled for compound queries so rows are returned as-is without collapsing duplicates).
-- **Expression builders**: `eq`, `and`, `or`, `between`, `inList`, `exists`, `jsonPath`, `caseWhen`, window functions like `rowNumber`, `rank`, `lag`, `lead`, etc., all backed by typed AST nodes.
-- **Relation-aware hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.) using a hydration plan derived from the AST metadata.
+- **Expression builders**: `eq`, `and`, `or`, `between`, `inList`, `exists`, `jsonPath`, `caseWhen`, window functions like `rowNumber`, `rank`, `lag`, `lead`, etc., all backed by typed AST nodes.
+- **Operator safety**: scalar operators (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`) are for single values; for arrays, use `inList`/`notInList`.
+  - Migration example: `where(eq(tipoAcao.columns.codigo, codigos))` -> `where(inList(tipoAcao.columns.codigo, codigos))`.
+- **Relation-aware hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.) using a hydration plan derived from the AST metadata.
 - **Multi-dialect**: compile once, run on MySQL/MariaDB, PostgreSQL, SQLite, or SQL Server via pluggable dialects.
 - **DML**: type-safe INSERT / UPDATE / DELETE with `RETURNING` where supported.
 

package/dist/index.cjs

@@ -202,6 +202,7 @@ __export(index_exports, {
   eq: () => eq,
   esel: () => esel,
   exclude: () => exclude,
+  executeFilteredPaged: () => executeFilteredPaged,
   executeHydrated: () => executeHydrated,
   executeHydratedPlain: () => executeHydratedPlain,
   executeHydratedPlainWithContexts: () => executeHydratedPlainWithContexts,
@@ -802,6 +803,11 @@ var toOperandNode = (value) => {
   if (isLiteralValue(value)) {
     return toLiteralNode(value);
   }
+  if (Array.isArray(value)) {
+    throw new Error(
+      "Array operands are not supported in scalar comparisons. Use inList/notInList for array matching."
+    );
+  }
   return columnRefToNode(value);
 };
 var valueToOperand = (value) => {
@@ -16208,6 +16214,129 @@ function computePaginationMetadata(totalItems, page, pageSize) {
   };
 }
 
+// src/dto/execute-filtered-paged.ts
+var normalizeSortBy = (sortBy) => {
+  if (!sortBy) {
+    return void 0;
+  }
+  const normalized = sortBy.trim();
+  return normalized.length > 0 ? normalized : void 0;
+};
+var detectPrimaryKeyName = (table) => {
+  const pk = Object.values(table.columns).find((column) => column.primary);
+  return pk?.name;
+};
+var toColumnNode = (table, name) => ({
+  type: "Column",
+  table: table.name,
+  name
+});
+var getColumnByName = (table, name) => {
+  return Object.values(table.columns).find((column) => column.name === name);
+};
+var resolveSortTermFromAllowed = (sortBy, allowedSortColumns) => {
+  if (!allowedSortColumns) {
+    throw new Error("allowedSortColumns is required when sortBy/defaultSortBy is provided.");
+  }
+  const term = allowedSortColumns[sortBy];
+  if (term) {
+    return term;
+  }
+  const allowedKeys = Object.keys(allowedSortColumns);
+  throw new Error(
+    `Invalid sortBy "${sortBy}". Allowed values: ${allowedKeys.length > 0 ? allowedKeys.join(", ") : "(none)"}.`
+  );
+};
+var resolvePrimarySort = (table, sortBy, sortDirection, allowedSortColumns, defaultSortBy, defaultSortDirection) => {
+  const requestedSortBy = normalizeSortBy(sortBy);
+  if (requestedSortBy) {
+    return {
+      term: resolveSortTermFromAllowed(requestedSortBy, allowedSortColumns),
+      direction: sortDirection ?? ORDER_DIRECTIONS.ASC
+    };
+  }
+  const configuredDefaultSortBy = normalizeSortBy(defaultSortBy);
+  if (configuredDefaultSortBy) {
+    return {
+      term: resolveSortTermFromAllowed(configuredDefaultSortBy, allowedSortColumns),
+      direction: defaultSortDirection ?? ORDER_DIRECTIONS.ASC
+    };
+  }
+  const detectedPkName = detectPrimaryKeyName(table);
+  if (detectedPkName) {
+    const detectedPkColumn = getColumnByName(table, detectedPkName);
+    if (detectedPkColumn) {
+      return {
+        term: detectedPkColumn,
+        direction: ORDER_DIRECTIONS.ASC
+      };
+    }
+  }
+  const idColumn = getColumnByName(table, "id");
+  return {
+    term: idColumn ?? toColumnNode(table, "id"),
+    direction: ORDER_DIRECTIONS.ASC
+  };
+};
+var resolveTieBreaker = (table, tieBreakerColumn) => {
+  const configuredName = normalizeSortBy(tieBreakerColumn);
+  if (configuredName) {
+    const configuredColumn = getColumnByName(table, configuredName);
+    if (!configuredColumn) {
+      throw new Error(
+        `Invalid tieBreakerColumn "${configuredName}" for table "${table.name}".`
+      );
+    }
+    return configuredColumn;
+  }
+  const idColumn = getColumnByName(table, "id");
+  if (idColumn) {
+    return idColumn;
+  }
+  const detectedPkName = detectPrimaryKeyName(table);
+  if (detectedPkName) {
+    const detectedPkColumn = getColumnByName(table, detectedPkName);
+    if (detectedPkColumn) {
+      return detectedPkColumn;
+    }
+  }
+  return toColumnNode(table, "id");
+};
+var extractSortColumnName = (term) => {
+  if (typeof term === "object" && term !== null && "name" in term && typeof term.name === "string") {
+    return term.name;
+  }
+  return void 0;
+};
+var executeFilteredPaged = async (options) => {
+  const table = options.qb.getTable();
+  const primarySort = resolvePrimarySort(
+    table,
+    options.sortBy,
+    options.sortDirection,
+    options.allowedSortColumns,
+    options.defaultSortBy,
+    options.defaultSortDirection
+  );
+  const tieBreaker = resolveTieBreaker(table, options.tieBreakerColumn);
+  let qb = applyFilter(
+    options.qb,
+    options.tableOrEntity,
+    options.filters
+  );
+  qb = qb.orderBy(primarySort.term, primarySort.direction);
+  const primarySortColumnName = extractSortColumnName(primarySort.term);
+  const tieBreakerColumnName = extractSortColumnName(tieBreaker);
+  if (primarySortColumnName !== tieBreakerColumnName) {
+    qb = qb.orderBy(tieBreaker, ORDER_DIRECTIONS.ASC);
+  }
+  const result = await qb.executePaged(options.session, {
+    page: options.page,
+    pageSize: options.pageSize
+  });
+  return toPagedResponse(result);
+};
+
 // src/dto/openapi/type-mappings.ts
 var IntegerTypeStrategy = class {
   types = ["INT", "INTEGER"];
@@ -19043,6 +19172,7 @@ var TagIndex = class {
   eq,
   esel,
   exclude,
+  executeFilteredPaged,
   executeHydrated,
   executeHydratedPlain,
   executeHydratedPlainWithContexts,