querier-ts 2.5.4 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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,79 @@ 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:
+---
+
+#### `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`.
 
 ---
 

package/dist/cjs/index.cjs

@@ -375,6 +375,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 +662,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

@@ -197,6 +197,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

@@ -373,6 +373,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 +660,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.6.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",
@@ -72,8 +72,8 @@
     "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"
 }