metal-orm 1.0.77 → 1.0.78

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/scripts/inflection/pt-br.mjs

@@ -349,6 +349,36 @@ export const singularizeWordPtBr = (
   return normalized;
 };
 
+// ═══════════════════════════════════════════════════════════════════════════
+// NOUN SPECIFIERS (SUBSTANTIVOS DETERMINANTES)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Portuguese words that act as specifiers/delimiters in compound nouns.
+ * When these appear as the second term, only the first term varies.
+ * @type {ReadonlySet<string>}
+ */
+export const PT_BR_NOUN_SPECIFIERS = Object.freeze(new Set(
+  [
+    'correcao', 'padrao', 'limite', 'chave', 'base', 'chefe',
+    'satelite', 'fantasma', 'monstro', 'escola', 'piloto',
+    'femea', 'macho', 'geral', 'solicitacao'
+  ].map(normalizeLookup)
+));
+
+const isCompoundWithSpecifier = (term, specifiers = PT_BR_NOUN_SPECIFIERS) => {
+  if (!term || !String(term).trim()) return false;
+  const original = String(term).trim();
+  const format = detectTextFormat(original);
+  const words = splitIntoWords(original, format);
+
+  if (words.length < 2) return false;
+
+  // Check if the last word is a known specifier
+  const lastWord = words[words.length - 1];
+  return specifiers.has(normalizeLookup(lastWord));
+};
+
 // ═══════════════════════════════════════════════════════════════════════════
 // COMPOUND TERM HANDLING
 // ═══════════════════════════════════════════════════════════════════════════
@@ -358,22 +388,26 @@ export const singularizeWordPtBr = (
  */
 export const pluralizeRelationPropertyPtBr = (
   term,
-  { pluralizeWord = pluralizeWordPtBr, connectors = PT_BR_CONNECTORS } = {}
-) =>
-  hasConnectorWord(term, connectors)
-    ? applyToCompoundHead(term, { connectors, transformWord: pluralizeWord })
-    : applyToCompoundWords(term, { connectors, transformWord: pluralizeWord });
+  { pluralizeWord = pluralizeWordPtBr, connectors = PT_BR_CONNECTORS, specifiers = PT_BR_NOUN_SPECIFIERS } = {}
+) => {
+  if (hasConnectorWord(term, connectors) || isCompoundWithSpecifier(term, specifiers)) {
+    return applyToCompoundHead(term, { connectors, transformWord: pluralizeWord });
+  }
+  return applyToCompoundWords(term, { connectors, transformWord: pluralizeWord });
+}
 
 /**
  * Singularizes a compound property/relation name in Portuguese.
  */
 export const singularizeRelationPropertyPtBr = (
   term,
-  { singularizeWord = singularizeWordPtBr, connectors = PT_BR_CONNECTORS } = {}
-) =>
-  hasConnectorWord(term, connectors)
-    ? applyToCompoundHead(term, { connectors, transformWord: singularizeWord })
-    : applyToCompoundWords(term, { connectors, transformWord: singularizeWord });
+  { singularizeWord = singularizeWordPtBr, connectors = PT_BR_CONNECTORS, specifiers = PT_BR_NOUN_SPECIFIERS } = {}
+) => {
+  if (hasConnectorWord(term, connectors) || isCompoundWithSpecifier(term, specifiers)) {
+    return applyToCompoundHead(term, { connectors, transformWord: singularizeWord });
+  }
+  return applyToCompoundWords(term, { connectors, transformWord: singularizeWord });
+}
 
 // ═══════════════════════════════════════════════════════════════════════════
 // INFLECTOR FACTORY
@@ -393,14 +427,17 @@ export const createPtBrInflector = ({ customIrregulars = {} } = {}) => {
     ...buildSingularIrregulars(customIrregulars)
   });
 
+  const pluralizeWord = (w) => pluralizeWordPtBr(w, irregularPlurals);
+  const singularizeWord = (w) => singularizeWordPtBr(w, irregularSingulars);
+
   return Object.freeze({
     locale: 'pt-BR',
     irregularPlurals,
     irregularSingulars,
-    pluralizeWord: (w) => pluralizeWordPtBr(w, irregularPlurals),
-    singularizeWord: (w) => singularizeWordPtBr(w, irregularSingulars),
-    pluralizeRelationProperty: pluralizeRelationPropertyPtBr,
-    singularizeRelationProperty: singularizeRelationPropertyPtBr,
+    pluralizeWord,
+    singularizeWord,
+    pluralizeRelationProperty: (term) => pluralizeRelationPropertyPtBr(term, { pluralizeWord }),
+    singularizeRelationProperty: (term) => singularizeRelationPropertyPtBr(term, { singularizeWord }),
     normalizeForLookup: normalizeWord
   });
 };

package/src/query-builder/select/select-operations.ts

@@ -1,79 +1,86 @@
-import { TableDef } from '../../schema/table.js';
-import { ColumnDef } from '../../schema/column-types.js';
-import { OrderingTerm, SelectQueryNode } from '../../core/ast/query.js';
-import { FunctionNode, ExpressionNode, exists, notExists } from '../../core/ast/expression.js';
-import { derivedTable } from '../../core/ast/builders.js';
-import { SelectQueryState } from '../select-query-state.js';
-import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
-import { SelectPredicateFacet } from './predicate-facet.js';
-import { SelectRelationFacet } from './relation-facet.js';
-import { ORDER_DIRECTIONS, OrderDirection } from '../../core/sql/sql.js';
-import { OrmSession } from '../../orm/orm-session.js';
-import type { SelectQueryBuilder } from '../select.js';
-
-export type WhereHasOptions = {
-  correlate?: ExpressionNode;
-};
-
-export type RelationCallback = <TChildTable extends TableDef>(
-  qb: SelectQueryBuilder<unknown, TChildTable>
-) => SelectQueryBuilder<unknown, TChildTable>;
-
-type ChildBuilderFactory = <R, TChild extends TableDef>(table: TChild) => SelectQueryBuilder<R, TChild>;
-
-/**
- * Builds a new query context with an ORDER BY clause applied.
- */
-export function applyOrderBy(
-  context: SelectQueryBuilderContext,
-  predicateFacet: SelectPredicateFacet,
-  term: ColumnDef | OrderingTerm,
-  directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string }
-): SelectQueryBuilderContext {
-  const options =
-    typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
-  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
-  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
+import { TableDef } from '../../schema/table.js';
+import { ColumnDef } from '../../schema/column-types.js';
+import { OrderingTerm, SelectQueryNode } from '../../core/ast/query.js';
+import { FunctionNode, ExpressionNode, exists, notExists } from '../../core/ast/expression.js';
+import { derivedTable } from '../../core/ast/builders.js';
+import { SelectQueryState } from '../select-query-state.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { SelectPredicateFacet } from './predicate-facet.js';
+import { SelectRelationFacet } from './relation-facet.js';
+import { ORDER_DIRECTIONS, OrderDirection } from '../../core/sql/sql.js';
+import { OrmSession } from '../../orm/orm-session.js';
+import type { SelectQueryBuilder } from '../select.js';
+
+export type WhereHasOptions = {
+  correlate?: ExpressionNode;
+};
+
+export type RelationCallback = <TChildTable extends TableDef>(
+  qb: SelectQueryBuilder<unknown, TChildTable>
+) => SelectQueryBuilder<unknown, TChildTable>;
+
+type ChildBuilderFactory = <R, TChild extends TableDef>(table: TChild) => SelectQueryBuilder<R, TChild>;
+
+/**
+ * Builds a new query context with an ORDER BY clause applied.
+ */
+export function applyOrderBy(
+  context: SelectQueryBuilderContext,
+  predicateFacet: SelectPredicateFacet,
+  term: ColumnDef | OrderingTerm,
+  directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string }
+): SelectQueryBuilderContext {
+  const options =
+    typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
+  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
+  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
+}
+
+/**
+ * Runs the count query for the provided context and session.
+ */
+export async function executeCount(
+  context: SelectQueryBuilderContext,
+  env: SelectQueryBuilderEnvironment,
+  session: OrmSession
+): Promise<number> {
+  const unpagedAst: SelectQueryNode = {
+    ...context.state.ast,
+    orderBy: undefined,
+    limit: undefined,
+    offset: undefined
+  };
+
+  const nextState = new SelectQueryState(env.table as TableDef, unpagedAst);
+  const nextContext: SelectQueryBuilderContext = {
+    ...context,
+    state: nextState
+  };
+
+  const subAst = nextContext.hydration.applyToAst(nextState.ast);
+  const countQuery: SelectQueryNode = {
+    type: 'SelectQuery',
+    from: derivedTable(subAst, '__metal_count'),
+    columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
+    joins: []
+  };
+
+  const execCtx = session.getExecutionContext();
+  const compiled = execCtx.dialect.compileSelect(countQuery);
+  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const value = results[0]?.values?.[0]?.[0];
+
+  if (typeof value === 'number') return value;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'string') return Number(value);
+  return value === null || value === undefined ? 0 : Number(value);
 }
 
-/**
- * Runs the count query for the provided context and session.
- */
-export async function executeCount(
-  context: SelectQueryBuilderContext,
-  env: SelectQueryBuilderEnvironment,
-  session: OrmSession
-): Promise<number> {
-  const unpagedAst: SelectQueryNode = {
-    ...context.state.ast,
-    orderBy: undefined,
-    limit: undefined,
-    offset: undefined
-  };
-
-  const nextState = new SelectQueryState(env.table as TableDef, unpagedAst);
-  const nextContext: SelectQueryBuilderContext = {
-    ...context,
-    state: nextState
-  };
-
-  const subAst = nextContext.hydration.applyToAst(nextState.ast);
-  const countQuery: SelectQueryNode = {
-    type: 'SelectQuery',
-    from: derivedTable(subAst, '__metal_count'),
-    columns: [{ type: 'Function', name: 'COUNT', args: [], alias: 'total' } as FunctionNode],
-    joins: []
-  };
-
-  const execCtx = session.getExecutionContext();
-  const compiled = execCtx.dialect.compileSelect(countQuery);
-  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const value = results[0]?.values?.[0]?.[0];
-
-  if (typeof value === 'number') return value;
-  if (typeof value === 'bigint') return Number(value);
-  if (typeof value === 'string') return Number(value);
-  return value === null || value === undefined ? 0 : Number(value);
+export interface PaginatedResult<T> {
+  items: T[];
+  totalItems: number;
+  page: number;
+  pageSize: number;
 }
 
 /**
@@ -84,7 +91,7 @@ export async function executePagedQuery<T, TTable extends TableDef>(
   session: OrmSession,
   options: { page: number; pageSize: number },
   countCallback: (session: OrmSession) => Promise<number>
-): Promise<{ items: T[]; totalItems: number }> {
+): Promise<PaginatedResult<T>> {
   const { page, pageSize } = options;
 
   if (!Number.isInteger(page) || page < 1) {
@@ -101,44 +108,44 @@ export async function executePagedQuery<T, TTable extends TableDef>(
     countCallback(session)
   ]);
 
-  return { items, totalItems };
-}
-
-/**
- * Builds an EXISTS or NOT EXISTS predicate for a related table.
- */
-export function buildWhereHasPredicate<TTable extends TableDef>(
-  env: SelectQueryBuilderEnvironment,
-  context: SelectQueryBuilderContext,
-  relationFacet: SelectRelationFacet,
-  createChildBuilder: ChildBuilderFactory,
-  relationName: keyof TTable['relations'] & string,
-  callbackOrOptions?: RelationCallback | WhereHasOptions,
-  maybeOptions?: WhereHasOptions,
-  negate = false
-): ExpressionNode {
-  const relation = env.table.relations[relationName as string];
-  if (!relation) {
-    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
-  }
-
-  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
-  const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as
-    | WhereHasOptions
-    | undefined;
-
-  let subQb = createChildBuilder<unknown, TableDef>(relation.target);
-  if (callback) {
-    subQb = callback(subQb);
-  }
-
-  const subAst = subQb.getAST();
-  const finalSubAst = relationFacet.applyRelationCorrelation(
-    context,
-    relationName,
-    subAst,
-    options?.correlate
-  );
-
-  return negate ? notExists(finalSubAst) : exists(finalSubAst);
+  return { items, totalItems, page, pageSize };
 }
+
+/**
+ * Builds an EXISTS or NOT EXISTS predicate for a related table.
+ */
+export function buildWhereHasPredicate<TTable extends TableDef>(
+  env: SelectQueryBuilderEnvironment,
+  context: SelectQueryBuilderContext,
+  relationFacet: SelectRelationFacet,
+  createChildBuilder: ChildBuilderFactory,
+  relationName: keyof TTable['relations'] & string,
+  callbackOrOptions?: RelationCallback | WhereHasOptions,
+  maybeOptions?: WhereHasOptions,
+  negate = false
+): ExpressionNode {
+  const relation = env.table.relations[relationName as string];
+  if (!relation) {
+    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
+  }
+
+  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
+  const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as
+    | WhereHasOptions
+    | undefined;
+
+  let subQb = createChildBuilder<unknown, TableDef>(relation.target);
+  if (callback) {
+    subQb = callback(subQb);
+  }
+
+  const subAst = subQb.getAST();
+  const finalSubAst = relationFacet.applyRelationCorrelation(
+    context,
+    relationName,
+    subAst,
+    options?.correlate
+  );
+
+  return negate ? notExists(finalSubAst) : exists(finalSubAst);
+}

package/src/query-builder/select.ts

@@ -50,14 +50,16 @@ import { executeHydrated, executeHydratedPlain, executeHydratedWithContexts } fr
 import { EntityConstructor } from '../orm/entity-metadata.js';
 import { materializeAs } from '../orm/entity-materializer.js';
 import { resolveSelectQuery } from './query-resolution.js';
-import {
-  applyOrderBy,
-  buildWhereHasPredicate,
-  executeCount,
-  executePagedQuery,
-  RelationCallback,
-  WhereHasOptions
-} from './select/select-operations.js';
+import {
+  applyOrderBy,
+  buildWhereHasPredicate,
+  executeCount,
+  executePagedQuery,
+  PaginatedResult,
+  RelationCallback,
+  WhereHasOptions
+} from './select/select-operations.js';
+export type { PaginatedResult };
 import { SelectFromFacet } from './select/from-facet.js';
 import { SelectJoinFacet } from './select/join-facet.js';
 import { SelectProjectionFacet } from './select/projection-facet.js';
@@ -792,19 +794,19 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     return executeCount(this.context, this.env, session);
   }
 
-  /**
-   * Executes the query and returns both the paged items and the total.
-   *
-   * @example
-   * const { items, totalItems } = await qb.executePaged(session, { page: 1, pageSize: 20 });
-   */
-  async executePaged(
-    session: OrmSession,
-    options: { page: number; pageSize: number }
-  ): Promise<{ items: T[]; totalItems: number }> {
-    const builder = this.ensureDefaultSelection();
-    return executePagedQuery(builder, session, options, sess => this.count(sess));
-  }
+  /**
+   * Executes the query and returns both the paged items and the total.
+   *
+   * @example
+   * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
+   */
+  async executePaged(
+    session: OrmSession,
+    options: { page: number; pageSize: number }
+  ): Promise<PaginatedResult<T>> {
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, sess => this.count(sess));
+  }
 
   /**
    * Executes the query with provided execution and hydration contexts