querier-ts 2.6.0 → 2.7.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## v2.7.1
+
+### Summary
+
+- [x] Documentation updates
+- [ ] Bug fixes
+- [ ] Code refactoring
+- [ ] New features
+- [ ] Breaking changes
+
+### New features
+
+- Update `README.md` documentation for `orderBy()` method with new overload and examples.
+
+## 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

package/README.md

@@ -144,23 +144,30 @@ const query = Query.from()
 
 ### Ordering results
 
-#### `orderBy(...columns)`
+#### `orderBy(...columns | (callback, order?))`
 
-Sorts the results. You can pass multiple columns.
+Sorts the results.
 
-```ts
-.orderBy('name', 'id')
-```
+- `columns`: the columns to order by.
+- `callback`: A function that maps each row to a value.
+- `order`: The order to sort in.
 
-In this example, `name` has higher priority than `id`.
+You can specify column names or a callback function to map each row to a value.
 
-You can also sort in descending order by prefixing the column with `-`:
+Examples:
 
 ```ts
-const lastId = Query.from(users)
-  .select('id')
-  .orderBy('-id')
-  .scalar();
+// Column names with ASC and DESC (-) order
+.orderBy('name', '-createdAt')
+
+// callback with ASC order by default
+.orderBy((user) => user.address.country)
+
+// callback with ASC order set explicitly
+.orderBy((user) => user.address.country, 'asc')
+
+// callback with DESC order
+.orderBy((user) => user.address.country, 'desc')
 ```
 
 ---
@@ -227,6 +234,8 @@ const countries = Query.from(addresses)
   .column('country');
 ```
 
+> Passing a non-integer or a negative number to `limit` will throw an `InvalidArgumentError`.
+
 ---
 
 #### `top(limit, options?)`
@@ -273,6 +282,7 @@ const countries = Query.from(addresses)
   .column('country'); // ['Brazil', 'Chile', 'Argentina']
 ```
 
+> 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) {

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.
      *

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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "querier-ts",
   "type": "module",
-  "version": "2.6.0",
+  "version": "2.7.1",
   "description": "A lightweight, type-safe in-memory query engine for JavaScript and TypeScript",
   "repository": {
     "type": "git",
@@ -68,7 +68,7 @@
     "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",