@osqd/jql 0.1.1

package/dist/group.d.ts

@@ -0,0 +1,47 @@
+import { type CompileOptions } from "./core.js";
+import type { QueryLike, Source } from "./types.js";
+/**
+ * Counting the matches by one field.
+ *
+ * Every dashboard in this family ends up doing this: a thousand requests become a dozen
+ * actors you can read down, a feed becomes counts per verdict, per rule, per path. Each
+ * one used to write the tally loop itself, which is where the disagreements crept in —
+ * whether an item with two tags counts twice, what happens to the items with no value at
+ * all, and what order the groups come back in. It is one answer now.
+ *
+ * One pass over the source, one `Map` of counts, and the items kept only when asked for.
+ */
+export interface Grouped<T> {
+    /** The value that names the group. `null` covers everything that cannot name one — see below. */
+    readonly key: unknown;
+    readonly count: number;
+    /** Present only when `items` asked for them. */
+    readonly items?: readonly T[] | undefined;
+}
+export interface GroupOptions<T, Extra extends object = {}> extends CompileOptions<Extra> {
+    /** Which items to count. Absent counts them all. */
+    readonly where?: QueryLike<T, NoInfer<Extra>> | undefined;
+    /** How many groups to return. Absent returns all of them. */
+    readonly limit?: number | undefined;
+    /** Keep the items too: `true` for all of them, a number for the first few. Default: counts only. */
+    readonly items?: boolean | number | undefined;
+    /** `"count"` (default) puts the largest group first; `"key"` orders by the value itself. */
+    readonly sort?: "count" | "key" | undefined;
+}
+/**
+ * Groups the matching items by the value at `by`, largest group first.
+ *
+ * Three rules worth knowing, each because leaving it unsaid is how two dashboards came to
+ * disagree about the same feed:
+ *
+ * - **An item counts once in each group it belongs to.** A path that reaches an array —
+ *   tags, say — puts the item in a group per distinct tag, and a repeated value inside one
+ *   item counts once.
+ * - **Everything that cannot name a group shares `null`**: a missing field, a `null`, a value
+ *   that is an object, and an empty list. That is the "no rule matched" heading, and it is a
+ *   real answer rather than a silently dropped row — which is the point, because it is what
+ *   makes the counts add up to the number of rows there are.
+ * - **Ties break by the key**, so the same data always comes back in the same order.
+ */
+export declare function group<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, by: string, options?: GroupOptions<V, Extra>): Grouped<V>[];
+export declare function group<T, Extra extends object = {}>(source: Source<T>, by: string, options?: GroupOptions<T, Extra>): Grouped<T>[];