From 8ba3f0640ae99e2d83ceb576b86725d2877857d7 Mon Sep 17 00:00:00 2001 From: D045778 Date: Fri, 19 Jun 2026 14:27:58 +0200 Subject: [PATCH] node.js: string decimals in best practices --- node.js/best-practices.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/node.js/best-practices.md b/node.js/best-practices.md index 14fbd2fccb..be7c0cded2 100644 --- a/node.js/best-practices.md +++ b/node.js/best-practices.md @@ -382,6 +382,22 @@ srv.before("UPDATE", "EntityName", (req) => { Internally the [timestamp](events#timestamp) is a JavaScript `Date` object, that is converted to the right format, when sent to the database. So if in any case a date string is needed, the best solution would be to initialize a Date object, that is then translated to the correct UTC String for the database. +## Decimals and Int64 as Strings { #decimals-int64 } + +`Decimal` and `Int64` values are always returned as **strings**, not JavaScript numbers. JavaScript's `Number` type cannot represent these values without risk of losing precision, so CAP aligns all databases — [HANA](../guides/databases/hana), [PostgreSQL](../guides/databases/postgres), and [SQLite](../guides/databases/sqlite) — on this behavior. + +#### Do arithmetic in the database { .good } + +Avoid calculations on `Decimal` / `Int64` fields in JavaScript — do them in the database instead: + +```js +await UPDATE(Books).set('stock = stock + 1').where({ ID: 1 }) +``` + +::: warning Integer arithmetic can exceed JavaScript's safe range +Multiplication or addition on integer fields can produce values beyond `Number.MAX_SAFE_INTEGER`. Doing such calculations in JavaScript risks silently losing precision — do them in the database instead. +::: + ## Custom Streaming { #custom-streaming-beta } [Media Data](../guides/services/media-data) can be served from custom handlers of the type `READ`, `action`, or `function`.