@palbase/backend 28.0.0 → 30.0.0

package/docs/README.md

@@ -73,7 +73,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 28.
+> and will not compile against `@palbase/backend` 30.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 

package/docs/database.md

@@ -261,8 +261,57 @@ shift into the wrong column — both silently. A differing row is refused with
 its index and the columns that differ. Write `null` for a column you do not
 have, or insert differently-shaped rows in separate calls.
 
+### Totals — `aggregate`
+
+`count` was the only aggregate, so "the total on this account" meant raw SQL or
+pulling every row and adding it up in JavaScript. The second is wrong twice:
+it is an N-row read, and money loses precision the moment it becomes a JS
+number.
+
+```ts
+const r = await Database.public.entries.aggregate({
+  where: { account_id },
+  sum: ["amount_kurus"],
+  count: true,
+});
+r.sum.amount_kurus;   // string | null — exact
+r.count;              // number
+```
+
+`sum` and `avg` return **strings**, always. Measured on live pg16:
+`sum(numeric)` = `1000041.50821234567890124`, which as a JS number becomes
+`1000041.5082123457` — seven digits gone; `sum(bigint)` = `18014398509481987`
+becomes `18014398509481988`, a different number. The engine casts both to text
+so the driver never gets the chance.
+
+`| null` is not decoration: Postgres answers an empty set with NULL, not 0
+(measured: `sum(...) IS NULL` while `count(*)` = 0). "No rows" and "the total
+was zero" are different answers, and the type makes you say which one you mean.
+
+`sum` and `avg` are offered on numeric columns only — the column's Postgres type
+is in the type, so `sum(["note"])` on a text column is a compile error rather
+than `function sum(text) does not exist`.
+
+Add `groupBy` and the result becomes an array, each row carrying its group:
+
+```ts
+const rows = await Database.public.entries.aggregate({
+  where: { household_id },
+  groupBy: ["category"],
+  sum: ["amount_kurus"],
+});
+// rows[0].category, rows[0].sum.amount_kurus
+```
+
 ### Bulk writes refuse an empty filter
 
+For a bulk job, pass `returning: false` and `updateMany` resolves to a COUNT
+instead of the rows — the same shape `deleteMany` already has. Measured at
+200k rows on live pg16: `RETURNING *` costs 55% more server time (7.2s → 11.1s)
+and 45 MB of JS heap, 236 bytes per row, so a million-row update carries 225 MB
+for rows nobody reads. Reading the returned rows is right for most calls and
+stays the default.
+
 `updateMany({}, …)` and `deleteMany({})` throw with the table named. `UPDATE …
 WHERE true` is a whole-table write, and the way to reach it by accident — a
 filter object built from request input that happened to come back empty — is

package/docs/llms-full.txt

@@ -81,7 +81,7 @@ service the controllers call.
 
 > **Never** emit `defineController`, `defineHandler`, `defineEndpoint`, `route.get(...)`,
 > `req.input`, `req.params`, or `req.errors` — those are the removed legacy model
-> and will not compile against `@palbase/backend` 28.
+> and will not compile against `@palbase/backend` 30.
 
 ### Complete CRUD example (copy-pasteable, compiles)
 
@@ -1147,8 +1147,57 @@ shift into the wrong column — both silently. A differing row is refused with
 its index and the columns that differ. Write `null` for a column you do not
 have, or insert differently-shaped rows in separate calls.
 
+### Totals — `aggregate`
+
+`count` was the only aggregate, so "the total on this account" meant raw SQL or
+pulling every row and adding it up in JavaScript. The second is wrong twice:
+it is an N-row read, and money loses precision the moment it becomes a JS
+number.
+
+```ts
+const r = await Database.public.entries.aggregate({
+  where: { account_id },
+  sum: ["amount_kurus"],
+  count: true,
+});
+r.sum.amount_kurus;   // string | null — exact
+r.count;              // number
+```
+
+`sum` and `avg` return **strings**, always. Measured on live pg16:
+`sum(numeric)` = `1000041.50821234567890124`, which as a JS number becomes
+`1000041.5082123457` — seven digits gone; `sum(bigint)` = `18014398509481987`
+becomes `18014398509481988`, a different number. The engine casts both to text
+so the driver never gets the chance.
+
+`| null` is not decoration: Postgres answers an empty set with NULL, not 0
+(measured: `sum(...) IS NULL` while `count(*)` = 0). "No rows" and "the total
+was zero" are different answers, and the type makes you say which one you mean.
+
+`sum` and `avg` are offered on numeric columns only — the column's Postgres type
+is in the type, so `sum(["note"])` on a text column is a compile error rather
+than `function sum(text) does not exist`.
+
+Add `groupBy` and the result becomes an array, each row carrying its group:
+
+```ts
+const rows = await Database.public.entries.aggregate({
+  where: { household_id },
+  groupBy: ["category"],
+  sum: ["amount_kurus"],
+});
+// rows[0].category, rows[0].sum.amount_kurus
+```
+
 ### Bulk writes refuse an empty filter
 
+For a bulk job, pass `returning: false` and `updateMany` resolves to a COUNT
+instead of the rows — the same shape `deleteMany` already has. Measured at
+200k rows on live pg16: `RETURNING *` costs 55% more server time (7.2s → 11.1s)
+and 45 MB of JS heap, 236 bytes per row, so a million-row update carries 225 MB
+for rows nobody reads. Reading the returned rows is right for most calls and
+stays the default.
+
 `updateMany({}, …)` and `deleteMany({})` throw with the table named. `UPDATE …
 WHERE true` is a whole-table write, and the way to reach it by accident — a
 filter object built from request input that happened to come back empty — is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "28.0.0",
+  "version": "30.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {

package/template/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@palbase/backend": "^28.0.0",
+    "@palbase/backend": "^30.0.0",
     "reflect-metadata": "^0.2.2"
   },
   "engines": {