js-bao 0.12.0-alpha.3 → 0.12.0-alpha.5

package/README.md

@@ -1023,6 +1023,12 @@ const electronicsCount = await Product.count({
 
 Perform complex data analysis with grouping, statistical operations, and faceting.
 
+`aggregate` answers one row per group: the `groupBy` values under `group`, as
+stored (`null` for a missing field), and each operation's value beside it under
+`count` or `<type>_<field>` — even when it is the only operation. Rows come back
+in `sort` order; no matching records gives `[]`. Two `groupBy` entries that
+would share a key in `group` throw `Ambiguous aggregation group keys`.
+
 ### Basic Aggregation
 
 ```typescript
@@ -1031,7 +1037,11 @@ const categoryCounts = await Product.aggregate({
   groupBy: ["category"],
   operations: [{ type: "count" }],
 });
-// Result: { "Electronics": 25, "Books": 18, "Clothing": 12 }
+// Result: [
+//   { group: { category: "Electronics" }, count: 25 },
+//   { group: { category: "Books" }, count: 18 },
+//   { group: { category: "Clothing" }, count: 12 }
+// ]
 
 // Multiple statistical operations
 const categoryStats = await Product.aggregate({
@@ -1044,8 +1054,9 @@ const categoryStats = await Product.aggregate({
     { type: "max", field: "price" },
   ],
 });
-// Result: {
-//   "Electronics": {
+// Result: [
+//   {
+//     group: { category: "Electronics" },
 //     count: 25,
 //     avg_price: 299.99,
 //     sum_price: 7499.75,
@@ -1053,7 +1064,7 @@ const categoryStats = await Product.aggregate({
 //     max_price: 1299.99
 //   },
 //   ...
-// }
+// ]
 ```
 
 ### Multi-Dimensional Grouping
@@ -1064,15 +1075,11 @@ const salesData = await Product.aggregate({
   groupBy: ["category", "brand"],
   operations: [{ type: "count" }, { type: "sum", field: "revenue" }],
 });
-// Result: {
-//   "Electronics": {
-//     "Apple": { count: 12, sum_revenue: 15000 },
-//     "Samsung": { count: 8, sum_revenue: 9500 }
-//   },
-//   "Books": {
-//     "Penguin": { count: 25, sum_revenue: 450 }
-//   }
-// }
+// Result: [
+//   { group: { category: "Electronics", brand: "Apple" }, count: 12, sum_revenue: 15000 },
+//   { group: { category: "Electronics", brand: "Samsung" }, count: 8, sum_revenue: 9500 },
+//   { group: { category: "Books", brand: "Penguin" }, count: 25, sum_revenue: 450 }
+// ]
 ```
 
 ### StringSet Aggregation
@@ -1105,14 +1112,21 @@ const tagCounts = await Article.aggregate({
   groupBy: ["tags"], // StringSet faceting
   operations: [{ type: "count" }],
 });
-// Result: { "javascript": 45, "react": 32, "tutorial": 28 }
+// Result: [
+//   { group: { tags: "javascript" }, count: 45 },
+//   { group: { tags: "react" }, count: 32 },
+//   { group: { tags: "tutorial" }, count: 28 }
+// ]
 
 // Membership-based grouping (articles that have specific tag vs don't)
 const urgentCounts = await Article.aggregate({
   groupBy: [{ field: "tags", contains: "urgent" }],
   operations: [{ type: "count" }],
 });
-// Result: { "true": 5, "false": 120 }
+// Result: [
+//   { group: { has_tags_urgent: "true" }, count: 5 },
+//   { group: { has_tags_urgent: "false" }, count: 120 }
+// ]
 
 // Complex aggregation with filtering and sorting
 const topTags = await Article.aggregate({
@@ -1128,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
@@ -1143,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.
@@ -1254,7 +1288,10 @@ const tagStats = await Article.aggregate({
   groupBy: [{ field: "tags", contains: "tutorial" }],
   operations: [{ type: "count" }],
 });
-// Result: { "true": 25, "false": 75 }
+// Result: [
+//   { group: { has_tags_tutorial: "true" }, count: 25 },
+//   { group: { has_tags_tutorial: "false" }, count: 75 }
+// ]
 ```
 
 ## Database Engine Specifics
@@ -1556,9 +1593,43 @@ See the `examples/` directory for complete working examples:
 
 ## Release notes
 
-Changes to the on-disk behaviour of `js-bao/cloudflare/do` (`DurableObjectEngine`)
-that a store's owner can observe. Newest first.
-
+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
+  `attachAndRegisterModel(X, schema)`, as [Defining Models](#defining-models-schema-first-no-decorators)
+  shows; instance methods, getters and statics go on the class body. The v1
+  codegen (`js-bao-codegen`) no longer recognises a `createModelClass(...)`
+  call as a model definition; it reads the class-based pattern as before.
+- **New stores get a keyed StringSet table** (#3881). A store the engine
+  creates declares `stringset_index` as `PRIMARY KEY (_type, _record_id, field,
+  value) WITHOUT ROWID` with `idx_ss_type_field_value` as its one named index,
+  so a StringSet value costs two rows written instead of three.
+  `DURABLE_OBJECT_SCHEMA_OPTIONS.memberShape` is `"keyed"`, and
+  `engine.memberTableShape` answers `"keyed"` for such a store. An existing
+  store keeps its record-first or field-first table; all three shapes return
+  the same results. On the platform, a plain document converts at its next
+  projection rebuild; databases and large documents keep their shape.
+  `rebuildMemberTable` now builds the keyed table. Rollback floor: a keyed table
+  has no `rowid`, so once a keyed store exists do not roll back past the
+  release that first returned StringSet values sorted by code point (it reads
+  `ORDER BY value`); an older release fails on a keyed table with `no such
+  column: rowid`.
 - **New stores get a record-first StringSet table** (#3877). A store the
   engine creates declares `stringset_index` with `UNIQUE(_type, _record_id,
   field, value)` (record-first) instead of `UNIQUE(_type, field, _record_id,