feat: Add datastore mode data transforms (#1369)

* Work in progress property transforms

* Change entity back to any

* Add the new interfaces and middleware code

* Pull the build property transform into separate fn

* Add arrays to the build transform function

* Add a test for property transforms

* Correct test comments

* More modular build function

* Update the test to check for the final result

* Add the request spy

* Fix the bug making property always increment

* Fix the test based on the most recent source code

change

* Refactor code for the array transforms

* Add a guard in case the casted type doesn’t exist

* Remove only

* Add a header

* Remove TODO

* Remove TODO

* Parameterize the test

* Ran linter

* Run the linter

* Add a comment to buildPropertyTransforms

* Add comments for building the property transforms

* Add two more test cases

* Build the 3 test cases

* should process string inputs for max/min/increment

* Produce test cases for different situations

* Delete invalid test cases and run linter

* Correct the order of operations test

* Remove only

Author: danieljbruce

src/entity.ts

@@ -1452,8 +1452,28 @@ export interface EntityProto {
   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;
+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,73 @@
+// 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;
+
+/**
+ * This method takes the user supplied transforms object and returns a list of
+ * corresponding transforms that are instead in the shape of the protos so that
+ * they can be included in the grpc request to the service directly.
+ *
+ * @param transforms The transforms supplied by the user that the user intends
+ * to apply.
+ */
+export function buildPropertyTransforms(transforms: PropertyTransform[]) {
+  const propertyTransforms: google.datastore.v1.IPropertyTransform[] = [];
+  transforms.forEach((transform: PropertyTransform) => {
+    const property = transform.property;
+    // If the user's transform has a setToServerValue property then ensure the
+    // propertyTransforms sent in the request have a setToServerValue transform.
+    if (transform.setToServerValue) {
+      propertyTransforms.push({
+        property,
+        setToServerValue: ServerValue.REQUEST_TIME,
+      });
+    }
+    // If the transform has an 'increment', 'maximum' or 'minimum' property then
+    // add the corresponding property transform to the propertyTransforms in the
+    // request.
+    ['increment', 'maximum', 'minimum'].forEach(type => {
+      const castedType = type as 'increment' | 'maximum' | 'minimum';
+      if (transform[castedType]) {
+        propertyTransforms.push({
+          property,
+          [castedType]: entity.encodeValue(
+            parseFloat(transform[castedType]),
+            property,
+          ) as IValue,
+        });
+      }
+    });
+    // If the transform has an 'appendMissingElements' or 'removeAllFromArray'
+    // property then add the corresponding property transform to the
+    // propertyTransforms in the request.
+    ['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;
+}