querier-ts 2.5.4 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v2.7.0
+
+### Summary
+
+- [ ] Bug fixes
+- [ ] Code refactoring
+- [x] New features
+- [ ] Build and packaging updates
+- [ ] Breaking changes
+
+### New features
+
+- Added new overload to `orderBy()` method, allowing to specify a function that returns the values to be sorted and the order to be applied.
+
+## v2.6.0
+
+### Summary
+
+- [ ] Bug fixes
+- [ ] Code refactoring
+- [x] New features
+- [ ] Build and packaging updates
+- [ ] Breaking changes
+
+### New features
+
+- Added `limitPerGroup()` and `top()` methods to `Query`.
+
 ## v2.5.4
 
 ### Summary

package/README.md

@@ -165,7 +165,28 @@ const lastId = Query.from(users)
 
 ---
 
-### Limiting results
+### Paginating results
+
+#### `skip(numberOfRows)`
+
+Skips the first results.
+
+```ts
+.skip(5)
+```
+
+Example:
+
+```ts
+const secondId = Query.from(users)
+  .select('id')
+  .skip(1)
+  .scalar();
+```
+
+> Passing a non-integer or a negative number will throw an `InvalidArgumentError`.
+
+---
 
 #### `limit(limit)`
 
@@ -179,24 +200,82 @@ Limits the number of results returned.
 
 ---
 
-#### `skip(numberOfRows)`
+#### `limitPerGroup(key | fn, limit)`
 
-Skips the first results.
+Limits the number of rows per group.
+
+- `key`: The property name to group by.
+- `fn`: A function that maps each row to a grouping value.
+- `limit`: The maximum number of rows to keep per group.
+
+> ⚠️ The rows kept depend on the current ordering of the query.
+> Use `orderBy()` beforehand to control which rows are selected.
+
+Examples:
 
 ```ts
-.skip(5)
+// with key
+const countries = Query.from(addresses)
+  .orderBy('-createdAt')
+  .limitPerGroup('country', 2)
+  .column('country'); // ['Argentina', 'Argentina', 'Brazil', 'Brazil', 'Chile', 'Chile']
+
+// with callback
+const countries = Query.from(addresses)
+  .orderBy('-createdAt')
+  .limitPerGroup((row) => row.country, 2)
+  .column('country');
 ```
 
-Example:
+> Passing a non-integer or a negative number to `limit` will throw an `InvalidArgumentError`.
+
+---
+
+#### `top(limit, options?)`
+
+Keeps the top N rows, optionally partitioned by a key or callback.
+
+- `limit`: The maximum number of rows to keep.
+- `options.partitionBy`: A property name or function to define groups.
+- `options.orderBy`: A column or list of columns to define ordering.
+
+If `partitionBy` is provided, the limit is applied per group.
+
+The rows kept depend on the ordering. Use `orderBy` (either here or before)
+to control which rows are selected.
+
+Examples:
 
 ```ts
-const secondId = Query.from(users)
-  .select('id')
-  .skip(1)
-  .scalar();
+// top N globally
+const ids = Query.from(addresses)
+  .orderBy('-createdAt')
+  .top(3)
+  .column('id'); // [6, 5, 4]
+
+// top N per group (key)
+const countries = Query.from(addresses)
+  .top(2, {
+    partitionBy: 'country',
+    orderBy: '-createdAt',
+  })
+  .column('country'); // ['Argentina', 'Argentina', 'Brazil', 'Brazil', 'Chile', 'Chile']
+
+// top N per group (callback)
+const countries = Query.from(addresses)
+  .top(1, {
+    partitionBy: (row) => row.country,
+    orderBy: '-createdAt',
+  })
+  .column('country'); // ['Argentina', 'Brazil', 'Chile']
+
+// without orderBy (keeps original order)
+const countries = Query.from(addresses)
+  .top(1, { partitionBy: 'country' })
+  .column('country'); // ['Brazil', 'Chile', 'Argentina']
 ```
 
-> Passing a non-integer or a negative number will throw an `InvalidArgumentError`.
+> Passing a non-integer or a negative number to `limit` will throw an `InvalidArgumentError`.
 
 ---
 

package/dist/cjs/index.cjs

@@ -185,6 +185,21 @@ function getObjectPropertyNames(obj) {
   );
 }
 
+// src/utils/functions/sort/sort-values.ts
+function sortValues(a, b, order) {
+  if (a == null && b == null) return 0;
+  if (a == null) return 1 * order;
+  if (b == null) return -1 * order;
+  if (a < b) return -1 * order;
+  if (a > b) return 1 * order;
+  return 0;
+}
+
+// src/utils/functions/sort/sort-by-callback.ts
+function sortByCallback(callback, sortOrder) {
+  return (a, b) => sortValues(callback(a), callback(b), sortOrder);
+}
+
 // src/utils/functions/sort/sort-by-property.ts
 function sortByProperty(property) {
   let sortOrder = 1;
@@ -197,12 +212,7 @@ function sortByProperty(property) {
   return (a, b) => {
     const valueA = a[key];
     const valueB = b[key];
-    if (valueA == null && valueB == null) return 0;
-    if (valueA == null) return 1 * sortOrder;
-    if (valueB == null) return -1 * sortOrder;
-    if (valueA < valueB) return -1 * sortOrder;
-    if (valueA > valueB) return 1 * sortOrder;
-    return 0;
+    return sortValues(valueA, valueB, sortOrder);
   };
 }
 
@@ -339,32 +349,19 @@ var _Query = class _Query {
     this.filterRows(condition, { ignoreNullValues: true });
     return this;
   }
-  /**
-   * Adds ordering to the results.
-   *
-   * This method should be called after `select()`; otherwise, the ordering will
-   * be applied only to the selected columns.
-   *
-   * @example
-   * ```ts
-   * // ❌ "age" will not be ordered, because it is not part of the selected columns
-   * const query = Query.from(users)
-   *   .orderBy('-age')
-   *   .select('name');
-   *
-   * // ✅ "age" will be ordered
-   * const query = Query.from(users)
-   *   .select('name', 'age')
-   *   .orderBy('-age');
-   * ```
-   *
-   * @param columns Ascending or descending columns. To mark a field as
-   * descending, prefix it with `-`.
-   *
-   * @returns Current query.
-   */
-  orderBy(...columns) {
-    this.#rows = this.#rows.sort(sortByProperties(...columns));
+  orderBy(...arg) {
+    if (arg.length === 0) {
+      return this;
+    }
+    if (isFunction(arg[0])) {
+      this.#rows = this.#rows.sort(
+        sortByCallback(arg[0], arg[1] === "desc" ? -1 : 1)
+      );
+    } else {
+      this.#rows = this.#rows.sort(
+        sortByProperties(...arg)
+      );
+    }
     return this;
   }
   skip(numberOfRows) {
@@ -375,6 +372,52 @@ var _Query = class _Query {
     this.#limit = limit;
     return this;
   }
+  limitPerGroup(arg, limit) {
+    const counts = /* @__PURE__ */ new Map();
+    const result = [];
+    const rows = this.#rows;
+    const isFn = isFunction(arg);
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const group = isFn ? arg(row) : row[arg];
+      const count = counts.get(group) ?? 0;
+      if (count < limit) {
+        result.push(row);
+        counts.set(group, count + 1);
+      }
+    }
+    this.#rows = result;
+    return this;
+  }
+  top(limit, options) {
+    const rows = this.getLimitedRows();
+    if (rows.length === 0) {
+      return this;
+    }
+    const { partitionBy, orderBy } = options ?? {};
+    if (orderBy) {
+      const columns = Array.isArray(orderBy) ? orderBy : [orderBy];
+      this.#rows = rows.sort(sortByProperties(...columns));
+    }
+    if (!partitionBy) {
+      this.#rows = rows.slice(0, limit);
+      return this;
+    }
+    const isFn = isFunction(partitionBy);
+    const counts = /* @__PURE__ */ new Map();
+    const result = [];
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const group = isFn ? partitionBy(row) : row[partitionBy];
+      const count = counts.get(group) ?? 0;
+      if (count < limit) {
+        result.push(row);
+        counts.set(group, count + 1);
+      }
+    }
+    this.#rows = result;
+    return this;
+  }
   /**
    * Returns all results.
    *
@@ -616,6 +659,16 @@ __decorateClass([
   __decorateParam(0, integer),
   __decorateParam(0, min(0))
 ], _Query.prototype, "limit");
+__decorateClass([
+  validateNumbers,
+  __decorateParam(1, integer),
+  __decorateParam(1, min(0))
+], _Query.prototype, "limitPerGroup");
+__decorateClass([
+  validateNumbers,
+  __decorateParam(0, integer),
+  __decorateParam(0, min(0))
+], _Query.prototype, "top");
 var Query = _Query;
 
 exports.Query = Query;

package/dist/esm/index.d.ts

@@ -154,28 +154,21 @@ declare class Query<T extends object> {
     /**
      * Adds ordering to the results.
      *
-     * This method should be called after `select()`; otherwise, the ordering will
-     * be applied only to the selected columns.
-     *
-     * @example
-     * ```ts
-     * // ❌ "age" will not be ordered, because it is not part of the selected columns
-     * const query = Query.from(users)
-     *   .orderBy('-age')
-     *   .select('name');
-     *
-     * // ✅ "age" will be ordered
-     * const query = Query.from(users)
-     *   .select('name', 'age')
-     *   .orderBy('-age');
-     * ```
-     *
      * @param columns Ascending or descending columns. To mark a field as
      * descending, prefix it with `-`.
      *
      * @returns Current query.
      */
     orderBy(...columns: OrderingColumn<T>[]): this;
+    /**
+     * Adds ordering to the results.
+     *
+     * @param fn Function to map each row to a value.
+     * @param order Sort order. Defaults to `asc`.
+     *
+     * @returns Current query.
+     */
+    orderBy<TReturn>(fn: (row: T) => TReturn, order?: 'asc' | 'desc'): this;
     /**
      * Defines the number of rows to skip.
      *
@@ -197,6 +190,56 @@ declare class Query<T extends object> {
      * @throws {InvalidArgumentError} If the given limit is less than 0.
      */
     limit(limit: number): this;
+    /**
+     * Limits the number of rows per group.
+     *
+     * @param key Key to group by.
+     * @param limit Maximum number of rows per group.
+     *
+     * @returns Current query.
+     */
+    limitPerGroup<K extends keyof T>(key: K, limit: number): this;
+    /**
+     * Limits the number of rows per group using a callback.
+     *
+     * @param fn Function to define the group key.
+     * @param limit Maximum number of rows per group.
+     *
+     * @returns Current query.
+     */
+    limitPerGroup<TValue>(fn: (row: T) => TValue, limit: number): this;
+    /**
+     * Keep the top N rows.
+     *
+     * @param limit Maximum number of rows per group.
+     *
+     * @returns Current query.
+     */
+    top(limit: number): this;
+    /**
+     * Keep the top N rows, optionally partitioned by a key or callback.
+     *
+     * @param limit Maximum number of rows per group (or globally if no partition is provided).
+     * @param options Options to define partitioning and ordering.
+     *
+     * @returns Current query.
+     */
+    top<K extends keyof T>(limit: number, options: {
+        partitionBy: K;
+        orderBy?: OrderingColumn<T> | OrderingColumn<T>[];
+    }): this;
+    /**
+     * Keep the top N rows, optionally partitioned by a key or callback.
+     *
+     * @param limit Maximum number of rows per group (or globally if no partition is provided).
+     * @param options Options to define partitioning and ordering.
+     *
+     * @returns Current query.
+     */
+    top<TValue>(limit: number, options: {
+        partitionBy: (row: T) => TValue;
+        orderBy?: OrderingColumn<T> | OrderingColumn<T>[];
+    }): this;
     /**
      * Returns all results.
      *

package/dist/esm/index.js

@@ -183,6 +183,21 @@ function getObjectPropertyNames(obj) {
   );
 }
 
+// src/utils/functions/sort/sort-values.ts
+function sortValues(a, b, order) {
+  if (a == null && b == null) return 0;
+  if (a == null) return 1 * order;
+  if (b == null) return -1 * order;
+  if (a < b) return -1 * order;
+  if (a > b) return 1 * order;
+  return 0;
+}
+
+// src/utils/functions/sort/sort-by-callback.ts
+function sortByCallback(callback, sortOrder) {
+  return (a, b) => sortValues(callback(a), callback(b), sortOrder);
+}
+
 // src/utils/functions/sort/sort-by-property.ts
 function sortByProperty(property) {
   let sortOrder = 1;
@@ -195,12 +210,7 @@ function sortByProperty(property) {
   return (a, b) => {
     const valueA = a[key];
     const valueB = b[key];
-    if (valueA == null && valueB == null) return 0;
-    if (valueA == null) return 1 * sortOrder;
-    if (valueB == null) return -1 * sortOrder;
-    if (valueA < valueB) return -1 * sortOrder;
-    if (valueA > valueB) return 1 * sortOrder;
-    return 0;
+    return sortValues(valueA, valueB, sortOrder);
   };
 }
 
@@ -337,32 +347,19 @@ var _Query = class _Query {
     this.filterRows(condition, { ignoreNullValues: true });
     return this;
   }
-  /**
-   * Adds ordering to the results.
-   *
-   * This method should be called after `select()`; otherwise, the ordering will
-   * be applied only to the selected columns.
-   *
-   * @example
-   * ```ts
-   * // ❌ "age" will not be ordered, because it is not part of the selected columns
-   * const query = Query.from(users)
-   *   .orderBy('-age')
-   *   .select('name');
-   *
-   * // ✅ "age" will be ordered
-   * const query = Query.from(users)
-   *   .select('name', 'age')
-   *   .orderBy('-age');
-   * ```
-   *
-   * @param columns Ascending or descending columns. To mark a field as
-   * descending, prefix it with `-`.
-   *
-   * @returns Current query.
-   */
-  orderBy(...columns) {
-    this.#rows = this.#rows.sort(sortByProperties(...columns));
+  orderBy(...arg) {
+    if (arg.length === 0) {
+      return this;
+    }
+    if (isFunction(arg[0])) {
+      this.#rows = this.#rows.sort(
+        sortByCallback(arg[0], arg[1] === "desc" ? -1 : 1)
+      );
+    } else {
+      this.#rows = this.#rows.sort(
+        sortByProperties(...arg)
+      );
+    }
     return this;
   }
   skip(numberOfRows) {
@@ -373,6 +370,52 @@ var _Query = class _Query {
     this.#limit = limit;
     return this;
   }
+  limitPerGroup(arg, limit) {
+    const counts = /* @__PURE__ */ new Map();
+    const result = [];
+    const rows = this.#rows;
+    const isFn = isFunction(arg);
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const group = isFn ? arg(row) : row[arg];
+      const count = counts.get(group) ?? 0;
+      if (count < limit) {
+        result.push(row);
+        counts.set(group, count + 1);
+      }
+    }
+    this.#rows = result;
+    return this;
+  }
+  top(limit, options) {
+    const rows = this.getLimitedRows();
+    if (rows.length === 0) {
+      return this;
+    }
+    const { partitionBy, orderBy } = options ?? {};
+    if (orderBy) {
+      const columns = Array.isArray(orderBy) ? orderBy : [orderBy];
+      this.#rows = rows.sort(sortByProperties(...columns));
+    }
+    if (!partitionBy) {
+      this.#rows = rows.slice(0, limit);
+      return this;
+    }
+    const isFn = isFunction(partitionBy);
+    const counts = /* @__PURE__ */ new Map();
+    const result = [];
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const group = isFn ? partitionBy(row) : row[partitionBy];
+      const count = counts.get(group) ?? 0;
+      if (count < limit) {
+        result.push(row);
+        counts.set(group, count + 1);
+      }
+    }
+    this.#rows = result;
+    return this;
+  }
   /**
    * Returns all results.
    *
@@ -614,6 +657,16 @@ __decorateClass([
   __decorateParam(0, integer),
   __decorateParam(0, min(0))
 ], _Query.prototype, "limit");
+__decorateClass([
+  validateNumbers,
+  __decorateParam(1, integer),
+  __decorateParam(1, min(0))
+], _Query.prototype, "limitPerGroup");
+__decorateClass([
+  validateNumbers,
+  __decorateParam(0, integer),
+  __decorateParam(0, min(0))
+], _Query.prototype, "top");
 var Query = _Query;
 
 export { Query };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "querier-ts",
   "type": "module",
-  "version": "2.5.4",
+  "version": "2.7.0",
   "description": "A lightweight, type-safe in-memory query engine for JavaScript and TypeScript",
   "repository": {
     "type": "git",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.4",
     "eslint": "^10.2.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
@@ -68,12 +68,12 @@
     "husky": "^9.1.7",
     "jiti": "^2.6.1",
     "lint-staged": "^16.4.0",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.2",
     "prettier-plugin-organize-imports": "^4.3.0",
     "tsup": "^8.5.1",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.58.0",
-    "vitest": "^4.1.2"
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@10.33.0"
 }