feat: Add datastore mode data transforms

src/entity.ts

@@ -1452,8 +1452,29 @@
   excludeFromIndexes?: boolean;
 }
 
+/*
+ * This is the interface the user would provide transform operations in before
+ * they are converted to the google.datastore.v1.IPropertyTransform
+ * interface.
+ *
+ */
+export type PropertyTransform = {
+  property: string;
+  setToServerValue: boolean;
+  increment: any;
+  maximum: any;
+  minimum: any;
+  appendMissingElements: any[];
+  removeAllFromArray: any[];
+};
+
+interface EntityWithTransforms {
+  transforms?: PropertyTransform[];
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type Entity = any;
+// TODO: Call out this interface change
+export type Entity = any & EntityWithTransforms;
 export type Entities = Entity | Entity[];
 
 interface KeyProtoPathElement extends google.datastore.v1.Key.IPathElement {

src/index.ts

@@ -37,9 +37,16 @@ import {
   ServiceError,
 } from 'google-gax';
 import * as is from 'is';
-import {Transform, pipeline} from 'stream';
+import {pipeline, Transform} from 'stream';
 
-import {entity, Entities, Entity, EntityProto, ValueProto} from './entity';
+import {
+  entity,
+  Entities,
+  Entity,
+  EntityProto,
+  ValueProto,
+  PropertyTransform,
+} from './entity';
 import {AggregateField} from './aggregate';
 import Key = entity.Key;
 export {Entity, Key, AggregateField};
@@ -70,6 +77,10 @@ import {AggregateQuery} from './aggregate';
 import {SaveEntity} from './interfaces/save';
 import {extendExcludeFromIndexes} from './utils/entity/extendExcludeFromIndexes';
 import {buildEntityProto} from './utils/entity/buildEntityProto';
+import IValue = google.datastore.v1.IValue;
+import IEntity = google.datastore.v1.IEntity;
+import ServerValue = google.datastore.v1.PropertyTransform.ServerValue;
+import {buildPropertyTransforms} from './utils/entity/buildPropertyTransforms';
 
 const {grpc} = new GrpcClient();
 
@@ -1098,7 +1109,8 @@ class Datastore extends DatastoreRequest {
     entities
       .map(DatastoreRequest.prepareEntityObject_)
       .forEach((entityObject: Entity, index: number) => {
-        const mutation: Mutation = {};
+        const mutation: google.datastore.v1.IMutation = {};
+
         let method = 'upsert';
 
         if (entityObject.method) {
@@ -1120,7 +1132,15 @@ class Datastore extends DatastoreRequest {
 
         entityProto.key = entity.keyToKeyProto(entityObject.key);
 
-        mutation[method] = entityProto;
+        mutation[method as 'upsert' | 'update' | 'insert' | 'delete'] =
+          entityProto as IEntity;
+
+        // We built the entityProto, now we should add the data transforms:
+        if (entityObject.transforms) {
+          mutation.propertyTransforms = buildPropertyTransforms(
+            entityObject.transforms,
+          );
+        }
         mutations.push(mutation);
       });
 

src/utils/entity/buildPropertyTransforms.ts

@@ -0,0 +1,57 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {entity, PropertyTransform} from '../../entity';
+import {google} from '../../../protos/protos';
+import IValue = google.datastore.v1.IValue;
+import ServerValue = google.datastore.v1.PropertyTransform.ServerValue;
+
+export function buildPropertyTransforms(transforms: PropertyTransform[]) {
+  const propertyTransforms: google.datastore.v1.IPropertyTransform[] = [];
+  transforms.forEach((transform: PropertyTransform) => {
+    const property = transform.property;
+    if (transform.setToServerValue) {
+      propertyTransforms.push({
+        property,
+        setToServerValue: ServerValue.REQUEST_TIME,
+      });
+    }
+    ['increment', 'maximum', 'minimum'].forEach(type => {
+      const castedType = type as 'increment' | 'maximum' | 'minimum';
+      if (transform[castedType]) {
+        propertyTransforms.push({
+          property,
+          [castedType]: entity.encodeValue(
+            transform[castedType],
+            property,
+          ) as IValue,
+        });
+      }
+    });
+    ['appendMissingElements', 'removeAllFromArray'].forEach(type => {
+      const castedType = type as 'appendMissingElements' | 'removeAllFromArray';
+      if (transform[castedType]) {
+        propertyTransforms.push({
+          property,
+          [castedType]: {
+            values: transform[castedType].map(element => {
+              return entity.encodeValue(element, property) as IValue;
+            }),
+          },
+        });
+      }
+    });
+  });
+  return propertyTransforms;
+}

system-test/datastore.ts

@@ -26,6 +26,7 @@
 import {Query, RunQueryInfo, ExecutionStats} from '../src/query';
 import KEY_SYMBOL = entity.KEY_SYMBOL;
 import {transactionExpiredError} from '../src/request';
+const sinon = require('sinon');
 
 const async = require('async');
 
@@ -3295,6 +3296,237 @@
           assert.strictEqual(entity, undefined);
         });
       });
+      describe.only('Datastore mode data transforms', () => {
+        const key = datastore.key(['Post', 'post1']);
+        async.each(
+          [
+            {
+              name: 'should perform a basic data transform',
+              saveArg: {
+                key: key,
+                data: {
+                  name: 'test',
+                  p1: 3,
+                  p2: 4,
+                  p3: 5,
+                  a1: [3, 4, 5],
+                },
+                transforms: [
+                  {
+                    property: 'p1',
+                    setToServerValue: true,
+                  },
+                  {
+                    property: 'p2',
+                    increment: 4,
+                  },
+                  {
+                    property: 'p3',
+                    maximum: 9,
+                  },
+                  {
+                    property: 'p2',
+                    minimum: 6,
+                  },
+                  {
+                    property: 'a1',
+                    appendMissingElements: [5, 6],
+                  },
+                  {
+                    property: 'a1',
+                    removeAllFromArray: [3],
+                  },
+                ],
+              },
+              saveResult: [
+                {
+                  mutationResults: [
+                    {
+                      transformResults: [
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          valueType: 'timestampValue',
+                        },
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          integerValue: '8',
+                          valueType: 'integerValue',
+                        },
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          integerValue: '9',
+                          valueType: 'integerValue',
+                        },
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          integerValue: '6',
+                          valueType: 'integerValue',
+                        },
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          nullValue: 'NULL_VALUE',
+                          valueType: 'nullValue',
+                        },
+                        {
+                          meaning: 0,
+                          excludeFromIndexes: false,
+                          nullValue: 'NULL_VALUE',
+                          valueType: 'nullValue',
+                        },
+                      ],
+                      key: null,
+                      conflictDetected: false,
+                    },
+                  ],
+                  commitTime: null,
+                },
+              ],
+              serverValue: {
+                name: 'test',
+                a1: [4, 5, 6],
+                p2: 6,
+                p3: 9,
+              },
+              gapicRequest: {
+                client: 'DatastoreClient',
+                method: 'commit',
+                reqOpts: {
+                  mutations: [
+                    {
+                      upsert: {
+                        key: {
+                          path: [
+                            {
+                              kind: 'Post',
+                              name: 'post1',
+                            },
+                          ],
+                          partitionId: {},
+                        },
+                        properties: {
+                          name: {
+                            stringValue: 'test',
+                          },
+                          p1: {
+                            integerValue: '3',
+                          },
+                          p2: {
+                            integerValue: '4',
+                          },
+                          p3: {
+                            integerValue: '5',
+                          },
+                          a1: {
+                            arrayValue: {
+                              values: [
+                                {
+                                  integerValue: '3',
+                                },
+                                {
+                                  integerValue: '4',
+                                },
+                                {
+                                  integerValue: '5',
+                                },
+                              ],
+                            },
+                          },
+                        },
+                      },
+                      propertyTransforms: [
+                        {
+                          property: 'p1',
+                          setToServerValue: 1,
+                        },
+                        {
+                          property: 'p2',
+                          increment: {
+                            integerValue: '4',
+                          },
+                        },
+                        {
+                          property: 'p3',
+                          maximum: {
+                            integerValue: '9',
+                          },
+                        },
+                        {
+                          property: 'p2',
+                          minimum: {
+                            integerValue: '6',
+                          },
+                        },
+                        {
+                          property: 'a1',
+                          appendMissingElements: {
+                            values: [
+                              {
+                                integerValue: '5',
+                              },
+                              {
+                                integerValue: '6',
+                              },
+                            ],
+                          },
+                        },
+                        {
+                          property: 'a1',
+                          removeAllFromArray: {
+                            values: [
+                              {
+                                integerValue: '3',
+                              },
+                            ],
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+                gaxOpts: {},
+              },
+            },
+          ],
+          async (testParameters: any) => {
+            it(testParameters.name, async () => {
+              const requestSpy = sinon.spy(datastore.request_);
+              datastore.request_ = requestSpy;
+              const result = await datastore.save(testParameters.saveArg);
+              // Clean the data from the server first before comparing:
+              result.forEach(serverResult => {
+                delete serverResult['indexUpdates'];
+                serverResult.mutationResults?.forEach(mutationResult => {
+                  delete mutationResult['updateTime'];
+                  delete mutationResult['createTime'];
+                  delete mutationResult['version'];
+                  mutationResult.transformResults?.forEach(transformResult => {
+                    delete transformResult['timestampValue'];
+                  });
+                });
+              });
+              // Now the data should have fixed values.
+              // Do a comparison against the expected result.
+              assert.deepStrictEqual(result, testParameters.saveResult);
+              // Now check the value that was actually saved to the server:
+              const [entity] = await datastore.get(key);
+              const parsedResult = JSON.parse(JSON.stringify(entity));
+              delete parsedResult['p1']; // This is a timestamp so we can't consistently test this.
+              assert.deepStrictEqual(parsedResult, testParameters.serverValue);
+              delete requestSpy.args[0][0].reqOpts.mutations[0].upsert.key
+                .partitionId['namespaceId'];
+              assert.deepStrictEqual(
+                requestSpy.args[0][0],
+                testParameters.gapicRequest,
+              );
+            });
+          },
+        );
+      });
     });
   },
 );