@noy-db/hub 0.1.0-pre.14 → 0.1.0-pre.16

package/dist/periods/index.d.cts

@@ -1,10 +1,11 @@
-import { a5 as PeriodsStrategy } from '../types-2JGVRzO2.cjs';
-export { a6 as CarryForwardContext, a7 as ClosePeriodOptions, a8 as OpenPeriodOptions, a9 as PERIODS_COLLECTION, aa as PeriodRecord, ab as ReadOnlyCollection, ac as appendPeriodLedgerEntry, ad as assertTsWritable, ae as chainAnchor, af as loadPeriods, ag as validatePeriodName } from '../types-2JGVRzO2.cjs';
+import { a5 as PeriodsStrategy } from '../types-DDy02bWN.cjs';
+export { a6 as CarryForwardContext, a7 as ClosePeriodOptions, a8 as OpenPeriodOptions, a9 as PERIODS_COLLECTION, aa as PeriodRecord, ab as ReadOnlyCollection, ac as appendPeriodLedgerEntry, ad as assertTsWritable, ae as chainAnchor, af as loadPeriods, ag as validatePeriodName } from '../types-DDy02bWN.cjs';
 import '../lazy-builder-C-rPfWG0.cjs';
 import '../predicate-Dnu81tsS.cjs';
-import '../strategy-D-SrOLCl.cjs';
+import '../strategy-DSTrsZ8t.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-CFJKJXWa.cjs';
+import '../index-CmVgTkqk.cjs';
+import '@noy-db/on-shamir';
 
 /**
  * Active periods strategy factory. Only reachable through the

package/dist/periods/index.d.ts

@@ -1,10 +1,11 @@
-import { a5 as PeriodsStrategy } from '../types-DIOLYPUq.js';
-export { a6 as CarryForwardContext, a7 as ClosePeriodOptions, a8 as OpenPeriodOptions, a9 as PERIODS_COLLECTION, aa as PeriodRecord, ab as ReadOnlyCollection, ac as appendPeriodLedgerEntry, ad as assertTsWritable, ae as chainAnchor, af as loadPeriods, ag as validatePeriodName } from '../types-DIOLYPUq.js';
+import { a5 as PeriodsStrategy } from '../types-DImsOlJe.js';
+export { a6 as CarryForwardContext, a7 as ClosePeriodOptions, a8 as OpenPeriodOptions, a9 as PERIODS_COLLECTION, aa as PeriodRecord, ab as ReadOnlyCollection, ac as appendPeriodLedgerEntry, ad as assertTsWritable, ae as chainAnchor, af as loadPeriods, ag as validatePeriodName } from '../types-DImsOlJe.js';
 import '../lazy-builder-Rpd-V3jP.js';
 import '../predicate-Dnu81tsS.js';
-import '../strategy-D-SrOLCl.js';
+import '../strategy-DSTrsZ8t.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-7nd15fgy.js';
+import '../index-CNwA-B6-.js';
+import '@noy-db/on-shamir';
 
 /**
  * Active periods strategy factory. Only reachable through the

package/dist/periods/index.js

@@ -6,13 +6,13 @@ import {
   loadPeriods,
   validatePeriodName,
   withPeriods
-} from "../chunk-FB34MDSJ.js";
+} from "../chunk-KJJKHKFP.js";
 import "../chunk-UF3BUNQZ.js";
-import "../chunk-E3VAKWJ7.js";
-import "../chunk-WLZWITX3.js";
-import "../chunk-PMMNH7VZ.js";
-import "../chunk-7AQKLLI5.js";
-import "../chunk-W7M3E5M5.js";
+import "../chunk-QQUUAXDY.js";
+import "../chunk-2AXFIYHT.js";
+import "../chunk-H7XROQJM.js";
+import "../chunk-WCA2NROQ.js";
+import "../chunk-ADQ5MQ54.js";
 export {
   PERIODS_COLLECTION,
   appendPeriodLedgerEntry,

package/dist/{public-envelope-66ZBXVXK.js → public-envelope-CRJAVW3E.js}

@@ -12,9 +12,9 @@ import {
   resolveLocale,
   savePublicEnvelope,
   validatePublicEnvelopeInput
-} from "./chunk-PPJA7KL6.js";
-import "./chunk-PMMNH7VZ.js";
-import "./chunk-W7M3E5M5.js";
+} from "./chunk-V6SGP2KX.js";
+import "./chunk-H7XROQJM.js";
+import "./chunk-ADQ5MQ54.js";
 export {
   DEFAULT_PUBLIC_ENVELOPE_SCHEMA,
   PUBLIC_ENVELOPE_FIELDS,
@@ -28,4 +28,4 @@ export {
   savePublicEnvelope,
   validatePublicEnvelopeInput
 };
-//# sourceMappingURL=public-envelope-66ZBXVXK.js.map
+//# sourceMappingURL=public-envelope-CRJAVW3E.js.map

package/dist/query/index.cjs

@@ -29,6 +29,7 @@ __export(query_exports, {
   GroupCardinalityError: () => GroupCardinalityError,
   GroupedAggregation: () => GroupedAggregation,
   GroupedQuery: () => GroupedQuery,
+  GroupedQueryN: () => GroupedQueryN,
   IndexRequiredError: () => IndexRequiredError,
   IndexWriteFailureError: () => IndexWriteFailureError,
   JoinTooLargeError: () => JoinTooLargeError,
@@ -457,6 +458,9 @@ var NO_AGGREGATE = {
   groupBy() {
     throw NOT_ENABLED;
   },
+  groupByN() {
+    throw NOT_ENABLED;
+  },
   scanAggregate() {
     throw NOT_ENABLED;
   }
@@ -840,53 +844,10 @@ var Query = class _Query {
     }
     return this.aggregateStrategy.aggregate(executeRecords, spec, upstreams);
   }
-  /**
-   * Partition matching records into buckets keyed by a field, then
-   * terminate with `.aggregate(spec)` to compute per-bucket
-   * reducers..
-   *
-   * ```ts
-   * const byClient = invoices.query()
-   *   .where('status', '==', 'open')
-   *   .groupBy('clientId')
-   *   .aggregate({ total: sum('amount'), n: count() })
-   *   .run()
-   * // → [ { clientId: 'c1', total: 5250, n: 3 }, … ]
-   * ```
-   *
-   * Result rows carry the group key value under the grouping field
-   * name plus every reducer output from the spec. Buckets are
-   * emitted in first-seen order — consumers who want a specific
-   * ordering should `.sort()` downstream.
-   *
-   * **Cardinality caps:** a one-shot warning fires at 10_000
-   * distinct groups; `GroupCardinalityError` throws at 100_000.
-   * Grouping on a high-uniqueness field like `id` or `createdAt` is
-   * almost always a query mistake — the error message names the
-   * field and observed cardinality and suggests narrowing with
-   * `.where()` first.
-   *
-   * **Null / undefined keys:** records with a missing or explicitly
-   * `null` group field get their own buckets. `Map`-based
-   * partitioning distinguishes `undefined` from `null`, so the two
-   * cases do NOT merge. Consumers who want them merged should
-   * coalesce upstream with `.filter()`.
-   *
-   * **Joins are not applied** — same rationale as `.count()` and
-   * `.aggregate()`. Joined fields in are projection-only, so
-   * running a join inside a grouping pipeline would be wasteful and
-   * could trigger `DanglingReferenceError` in strict mode for a
-   * call whose intent is purely to bucket-and-reduce. Grouping by
-   * a joined field is explicitly out of scope for — file an
-   * issue if a real consumer needs it.
-   *
-   * **Filter clauses (`.filter(fn)`):** grouped queries still
-   * support filter clauses in the underlying plan — they run in
-   * the same candidate/filter pipeline that `.aggregate()` uses.
-   * The performance caveat is the same: filter clauses cost O(N)
-   * per record and can't be index-accelerated.
-   */
-  groupBy(field) {
+  groupBy(...fields) {
+    if (fields.length === 0) {
+      throw new Error(".groupBy() requires at least one field");
+    }
     const source = this.source;
     const clauses = this.plan.clauses;
     const executeRecords = () => {
@@ -898,36 +859,21 @@ var Query = class _Query {
       const subscribe = source.subscribe.bind(source);
       upstreams.push({ subscribe: (cb) => subscribe(cb) });
     }
-    const joinCtx = this.joinContext;
-    const dictLabelResolver = joinCtx?.resolveDictSource ? (() => {
-      const dictSource = joinCtx.resolveDictSource(field);
-      if (!dictSource) return void 0;
-      const snapshot = dictSource.snapshot();
-      const dictMap = /* @__PURE__ */ new Map();
-      for (const entry of snapshot) {
-        const k = entry["key"];
-        const labels = entry["labels"];
-        if (typeof k === "string" && labels && typeof labels === "object") {
-          dictMap.set(k, labels);
-        }
-      }
-      return async (key, locale, fallback) => {
-        const labels = dictMap.get(key);
-        if (!labels) return void 0;
-        if (labels[locale] !== void 0) return labels[locale];
-        const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
-        for (const fb of chain) {
-          if (fb === "any") {
-            const any = Object.values(labels)[0];
-            if (any !== void 0) return any;
-          } else if (labels[fb] !== void 0) {
-            return labels[fb];
-          }
-        }
-        return void 0;
-      };
-    })() : void 0;
-    return this.aggregateStrategy.groupBy(executeRecords, field, upstreams, dictLabelResolver);
+    if (fields.length === 1) {
+      const field = fields[0];
+      const dictLabelResolver = buildDictLabelResolver(this.joinContext, field);
+      return this.aggregateStrategy.groupBy(
+        executeRecords,
+        field,
+        upstreams,
+        dictLabelResolver
+      );
+    }
+    return this.aggregateStrategy.groupByN(
+      executeRecords,
+      fields,
+      upstreams
+    );
   }
   /**
    * Re-run the query whenever the source notifies of changes.
@@ -1190,6 +1136,35 @@ function canonicalCtxHash(ctx) {
   }
   return (h >>> 0).toString(16).padStart(8, "0");
 }
+function buildDictLabelResolver(joinCtx, field) {
+  if (!joinCtx?.resolveDictSource) return void 0;
+  const dictSource = joinCtx.resolveDictSource(field);
+  if (!dictSource) return void 0;
+  const snapshot = dictSource.snapshot();
+  const dictMap = /* @__PURE__ */ new Map();
+  for (const entry of snapshot) {
+    const k = entry["key"];
+    const labels = entry["labels"];
+    if (typeof k === "string" && labels && typeof labels === "object") {
+      dictMap.set(k, labels);
+    }
+  }
+  return async (key, locale, fallback) => {
+    const labels = dictMap.get(key);
+    if (!labels) return void 0;
+    if (labels[locale] !== void 0) return labels[locale];
+    const chain = Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
+    for (const fb of chain) {
+      if (fb === "any") {
+        const any = Object.values(labels)[0];
+        if (any !== void 0) return any;
+      } else if (labels[fb] !== void 0) {
+        return labels[fb];
+      }
+    }
+    return void 0;
+  };
+}
 
 // src/indexing/eager-indexes.ts
 var CollectionIndexes = class {
@@ -1526,31 +1501,53 @@ function buildLiveAggregation(recompute, upstreams) {
   return new LiveAggregationImpl(recompute, upstreams);
 }
 
+// src/aggregate/canonical-key.ts
+function canonicalGroupKey(fields, row) {
+  const sorted = [...fields].sort();
+  const parts = [];
+  for (const name of sorted) {
+    const v = row[name];
+    const serialised = v === void 0 ? "undefined" : JSON.stringify(v);
+    parts.push(`${name}=${serialised}`);
+  }
+  return parts.join("|");
+}
+
 // src/aggregate/groupby.ts
 var GROUPBY_WARN_CARDINALITY = 1e4;
 var GROUPBY_MAX_CARDINALITY = 1e5;
 var warnedCardinalityFields = /* @__PURE__ */ new Set();
-function warnCardinalityApproaching(field, observed) {
-  if (warnedCardinalityFields.has(field)) return;
-  warnedCardinalityFields.add(field);
+function warnCardinalityApproaching(fields, observed) {
+  const key = JSON.stringify([...fields].sort());
+  if (warnedCardinalityFields.has(key)) return;
+  warnedCardinalityFields.add(key);
+  const label = `[${fields.join(", ")}]`;
   console.warn(
-    `[noy-db] .groupBy("${field}") produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
+    `[noy-db] .groupBy(${label}) produced ${observed} distinct groups, ${Math.round(observed / GROUPBY_MAX_CARDINALITY * 100)}% of the ${GROUPBY_MAX_CARDINALITY}-group ceiling. Narrow the query with .where() before grouping, or switch to a lower-cardinality field.`
   );
 }
 function resetGroupByWarnings() {
   warnedCardinalityFields.clear();
 }
-var GroupedQuery = class {
-  constructor(executeRecords, field, upstreams, dictLabelResolver) {
+var GroupedQueryBase = class {
+  constructor(executeRecords, fieldOrFields, upstreams, dictLabelResolver) {
     this.executeRecords = executeRecords;
-    this.field = field;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.fields = typeof fieldOrFields === "string" ? [fieldOrFields] : [...fieldOrFields];
   }
   executeRecords;
-  field;
   upstreams;
   dictLabelResolver;
+  /**
+   * Field set this grouped query buckets on. Stored in declaration
+   * order — the same order is preserved on every result row by
+   * `groupAndReduce`. For the single-field constructor, this is
+   * `[field]`.
+   */
+  fields;
+};
+var GroupedQuery = class extends GroupedQueryBase {
   /**
    * Build a grouped aggregation. Returns a `GroupedAggregation`
    * with `.run()`, `.runAsync()`, and `.live()` terminals — same shape
@@ -1560,70 +1557,93 @@ var GroupedQuery = class {
   aggregate(spec) {
     return new GroupedAggregation(
       this.executeRecords,
-      this.field,
+      this.fields,
+      spec,
+      this.upstreams,
+      this.dictLabelResolver
+    );
+  }
+};
+var GroupedQueryN = class extends GroupedQueryBase {
+  aggregate(spec) {
+    return new GroupedAggregation(
+      this.executeRecords,
+      this.fields,
       spec,
       this.upstreams,
       this.dictLabelResolver
     );
   }
 };
-function groupAndReduce(records, field, spec) {
+function groupAndReduce(records, fieldOrFields, spec) {
+  const fields = typeof fieldOrFields === "string" ? [fieldOrFields] : fieldOrFields;
+  if (fields.length === 0) {
+    throw new Error(".groupBy() requires at least one field");
+  }
   const buckets = /* @__PURE__ */ new Map();
+  const fieldLabel = fields.length === 1 ? fields[0] : `[${fields.join(", ")}]`;
   for (const record of records) {
-    const key = readPath(record, field);
-    let bucket = buckets.get(key);
+    const keyValues = {};
+    for (const f of fields) {
+      keyValues[f] = readPath(record, f);
+    }
+    const dedupKey = canonicalGroupKey(fields, keyValues);
+    let bucket = buckets.get(dedupKey);
     if (bucket === void 0) {
       if (buckets.size >= GROUPBY_MAX_CARDINALITY) {
         throw new GroupCardinalityError(
-          field,
+          fieldLabel,
           buckets.size + 1,
           GROUPBY_MAX_CARDINALITY
         );
       }
-      bucket = [];
-      buckets.set(key, bucket);
+      bucket = { keyValues, records: [] };
+      buckets.set(dedupKey, bucket);
     }
-    bucket.push(record);
+    bucket.records.push(record);
   }
   if (buckets.size >= GROUPBY_WARN_CARDINALITY) {
-    warnCardinalityApproaching(field, buckets.size);
+    warnCardinalityApproaching(fields, buckets.size);
   }
-  const keys = Object.keys(spec);
+  const reducerKeys = Object.keys(spec);
   const out = [];
-  for (const [groupKey, bucketRecords] of buckets) {
+  for (const bucket of buckets.values()) {
     const state = {};
-    for (const key of keys) {
-      state[key] = spec[key].init();
+    for (const rk of reducerKeys) {
+      state[rk] = spec[rk].init();
     }
-    for (const record of bucketRecords) {
-      for (const key of keys) {
-        state[key] = spec[key].step(state[key], record);
+    for (const record of bucket.records) {
+      for (const rk of reducerKeys) {
+        state[rk] = spec[rk].step(state[rk], record);
       }
     }
-    const row = { [field]: groupKey };
-    for (const key of keys) {
-      row[key] = spec[key].finalize(state[key]);
+    const row = {};
+    for (const f of fields) {
+      row[f] = bucket.keyValues[f];
+    }
+    for (const rk of reducerKeys) {
+      row[rk] = spec[rk].finalize(state[rk]);
     }
     out.push(row);
   }
   return out;
 }
 var GroupedAggregation = class {
-  constructor(executeRecords, field, spec, upstreams, dictLabelResolver) {
+  constructor(executeRecords, fields, spec, upstreams, dictLabelResolver) {
     this.executeRecords = executeRecords;
-    this.field = field;
     this.spec = spec;
     this.upstreams = upstreams;
     this.dictLabelResolver = dictLabelResolver;
+    this.fields = typeof fields === "string" ? [fields] : [...fields];
   }
   executeRecords;
-  field;
   spec;
   upstreams;
   dictLabelResolver;
+  fields;
   /** Execute the query, group, reduce, and return an array of rows. */
   run() {
-    return groupAndReduce(this.executeRecords(), this.field, this.spec);
+    return groupAndReduce(this.executeRecords(), this.fields, this.spec);
   }
   /**
    * Execute the query, group, reduce, and resolve `<field>Label` for
@@ -1633,17 +1653,22 @@ var GroupedAggregation = class {
    *
    * The `<field>Label` field is appended to each row. Rows whose group
    * key has no dictionary entry get `<field>Label: undefined`.
+   *
+   * Dict-label resolution is single-field only — multi-key groupings
+   * do not produce a `<field>Label`. The resolver is only attached
+   * by the builder when `fields.length === 1`.
    */
   async runAsync(opts) {
-    const rows = groupAndReduce(this.executeRecords(), this.field, this.spec);
-    if (!opts?.locale || !this.dictLabelResolver) return rows;
+    const rows = groupAndReduce(this.executeRecords(), this.fields, this.spec);
+    if (!opts?.locale || !this.dictLabelResolver || this.fields.length !== 1) return rows;
     const resolve = this.dictLabelResolver;
     const locale = opts.locale;
     const fallback = opts.fallback;
-    const labelKey = `${this.field}Label`;
+    const field = this.fields[0];
+    const labelKey = `${field}Label`;
     return Promise.all(
       rows.map(async (row) => {
-        const key = row[this.field];
+        const key = row[field];
         if (typeof key !== "string") return row;
         const label = await resolve(key, locale, fallback);
         return { ...row, [labelKey]: label };
@@ -1667,7 +1692,7 @@ var GroupedAggregation = class {
    * Always call `live.stop()` when finished.
    */
   live() {
-    const recompute = () => groupAndReduce(this.executeRecords(), this.field, this.spec);
+    const recompute = () => groupAndReduce(this.executeRecords(), this.fields, this.spec);
     return buildLiveAggregation(recompute, this.upstreams);
   }
 };
@@ -2084,6 +2109,7 @@ function coerceRefKey2(value) {
   GroupCardinalityError,
   GroupedAggregation,
   GroupedQuery,
+  GroupedQueryN,
   IndexRequiredError,
   IndexWriteFailureError,
   JoinTooLargeError,