js-bao 0.12.0-alpha.4 → 0.12.0-alpha.6

package/README.md

@@ -1142,7 +1142,11 @@ const topTags = await Article.aggregate({
 
 ```typescript
 interface AggregationOptions {
-  groupBy: (string | { field: string; contains: string })[];
+  groupBy: (
+    | string // a plain field, or a StringSet facet
+    | { field: string; contains: string } // StringSet membership: has_<field>_<contains>
+    | { field: string; period: "month" | "quarter" | "year" } // date period: <field>_<period>
+  )[];
   operations: {
     type: "count" | "sum" | "avg" | "min" | "max";
     field?: string; // Required for sum, avg, min, max
@@ -1157,6 +1161,22 @@ interface AggregationOptions {
 }
 ```
 
+A period level groups a `date` (or `string`) field by calendar month, quarter
+or year. Its value in `group` is `YYYY-MM`, `YYYY-Qn` or `YYYY`, read from the
+stored text with no time-zone conversion (a UTC ISO timestamp buckets by its
+UTC date); a missing or non-date value is `null`. The keys sort
+chronologically, so `sort` can name them:
+
+```typescript
+const monthly = await Transaction.aggregate({
+  filter: { date: { $gte: "2025-11-01", $lte: "2026-10-31" } },
+  groupBy: ["categoryId", { field: "date", period: "month" }],
+  operations: [{ type: "sum", field: "amount" }, { type: "count" }],
+  sort: { field: "date_month", direction: 1 },
+});
+// [{ group: { categoryId: "food", date_month: "2025-11" }, sum_amount: -50, count: 2 }, ...]
+```
+
 ## StringSet Fields
 
 StringSet is a special field type optimized for tag-like data, providing efficient membership queries and faceting capabilities.
@@ -1576,6 +1596,19 @@ See the `examples/` directory for complete working examples:
 Changes a consumer of this package can observe, including the on-disk
 behaviour of `js-bao/cloudflare/do` (`DurableObjectEngine`). Newest first.
 
+- **Breaking: format 2 (large document) is removed** (0.12.0). Every
+  `models/format2*` export that served the epoch overlay is gone — the record
+  store and its asynchronous host, the overlay observer and fold, the epoch
+  handoff and rotation, the cold start and snapshot loader, the offline window
+  (`DocumentOfflineWindowError`) and offline replay — with `utils/largeDocuments`
+  and `utils/overlaySql`. `InitJsBaoOptions` loses `largeDocumentStorage` and
+  `InitJsBaoResult` its `format2*` hooks and `whenFormat2ProjectionSettled`;
+  `connectDocument` refuses `documentFormat: 2` with `DOCUMENT_FORMAT_UNSUPPORTED`.
+  The OPFS worker and broker, `Format2StoreSql`, `createFormat2Sql()`,
+  `largeDocumentStoreScope` and the row cache stay: a record-log document
+  (`documentFormat: 3`) runs on them. The worker answers `serve`,
+  `storedEpoch`, `exportLegacy`, `importLegacy` and `dropLegacy` as unknown
+  commands.
 - **Breaking: `createModelClass` is removed** (#4285). It is no longer exported
   from `js-bao` (or re-exported from `js-bao-wss-client`). Define a model as
   `class X extends BaseModel {}` and attach its schema with