Add support for derived properties (#2065)

Author: davidpaquin

.changeset/ready-onions-join.md

@@ -0,0 +1,6 @@
+---
+"@osdk/client.unstable": patch
+"@osdk/maker": patch
+---
+
+Support derived properties

packages/client.unstable/src/index.ts

@@ -72,3 +72,9 @@ export type {
   OntologyIrValueTypeBlockData,
   OntologyIrValueTypeBlockDataEntry,
 } from "./blockDataIr.js";
+
+export type {
+  DerivedPropertyLinkTypeSide,
+  OntologyIrDerivedPropertiesDefinition,
+  OntologyIrDerivedPropertyAggregation,
+} from "./generated/ontology-metadata/api/derivedproperties/__components.js";

packages/maker/README.md

@@ -15,6 +15,7 @@ The Maker package provides a type-safe, programmatic way to define ontologies, w
 - [Interface Link Constraints](#interface-link-constraints)
 - [Defining Actions](#defining-actions)
 - [Importing Ontology Entities](#importing-ontology-entities)
+- [Advanced](#advanced)
 
 ## Getting Started
 
@@ -441,7 +442,7 @@ const customerObject = defineObject({
 });
 ```
 
-### Object with Datasource
+### Object with Custom Datasources
 
 ```typescript
 // Stream-backed object with retention period
@@ -456,27 +457,10 @@ const eventObject = defineObject({
     "eventName": { type: "string", displayName: "Event Name" },
     "timestamp": { type: "timestamp" },
   },
-  datasource: {
+  datasources: [{
     type: "stream",
     retentionPeriod: "P90D", // 90 days retention (ISO 8601 duration format)
-  },
-});
-
-// Dataset-backed object
-const productObject = defineObject({
-  apiName: "product",
-  displayName: "Product",
-  pluralDisplayName: "Products",
-  titlePropertyApiName: "name",
-  primaryKeyPropertyApiName: "id",
-  properties: {
-    "id": { type: "string", displayName: "ID" },
-    "name": { type: "string" },
-    "price": { type: "decimal" },
-  },
-  datasource: {
-    type: "dataset",
-  },
+  }],
 });
 ```
 
@@ -663,10 +647,12 @@ const modifyPersonAction = defineModifyInterfaceObjectAction({
 });
 ```
 
-### Custom Action
+## Advanced
+
+### Custom Actions
 
 More customization such as security/submission criteria, constraints on parameter values, parameter overrides, etc.
-can also be added.
+can be added to actions.
 
 ```typescript
 import {
@@ -741,3 +727,81 @@ const modifyObjectActionType = defineModifyObjectAction(
   },
 );
 ```
+
+### Derived Properties
+
+Objects can have derived properties, which are computed at runtime from other linked objects. Properties can be mapped directly, or an aggregation function (e.g. `collectList`, `avg`, `max`, etc.) can be used.
+
+```typescript
+const passenger = defineObject({
+  displayName: "Passenger",
+  pluralDisplayName: "Passengers",
+  apiName: "passenger",
+  primaryKeyPropertyApiName: "name",
+  titlePropertyApiName: "name",
+  properties: {
+    name: {
+      type: "string",
+      displayName: "Name",
+    },
+    flight_id: {
+      type: "string",
+      displayName: "Flight ID",
+    },
+  },
+});
+const flightToPassengers = defineLink({
+  apiName: "flightToPassengersLink",
+  one: {
+    // because the object has not been created yet,
+    // reference it by its fully qualified API name manually
+    object: "com.palantir.flight",
+    metadata: {
+      apiName: "flightFromPassengers",
+    },
+  },
+  toMany: {
+    object: passenger.apiName,
+    metadata: {
+      apiName: "passengersFromFlight",
+    },
+  },
+  manyForeignKeyProperty: "flight_id",
+});
+const flight = defineObject({
+  displayName: "Flight",
+  pluralDisplayName: "Flights",
+  apiName: "flight",
+  primaryKeyPropertyApiName: "id",
+  titlePropertyApiName: "id",
+  properties: {
+    id: {
+      type: "string",
+      displayName: "ID",
+    },
+    passengersList: {
+      type: "string",
+      array: true,
+      displayName: "Passengers",
+    },
+  },
+  datasources: [
+    // the dataset will back all of the properties not specified in other datasources
+    { type: "dataset" },
+    {
+      type: "derived",
+      // multi-hop link traversals are also supported, just extend this list!
+      linkDefinition: [{
+        linkType: flightToPassengers,
+      }],
+      propertyMapping: {
+        passengersList: {
+          type: "collectList",
+          property: "name",
+          limit: 100,
+        },
+      },
+    },
+  ],
+});
+```

packages/maker/src/api/defineCreateObjectAction.ts

@@ -27,6 +27,7 @@ import {
   validateActionParameters,
   validateParameterOrdering,
 } from "./defineAction.js";
+import { isStruct } from "./properties/PropertyTypeType.js";
 
 export function defineCreateObjectAction(
   def: ActionTypeUserDefinition,
@@ -36,9 +37,16 @@ export function defineCreateObjectAction(
     Object.keys(def.objectType.properties ?? {}),
     def.objectType.apiName,
   );
+  const propertiesWithDerivedDatasources = (def.objectType.datasources ?? [])
+    .filter(ds => ds.type === "derived").flatMap(ds =>
+      Object.keys(ds.propertyMapping)
+    );
   const propertyParameters = Object.keys(def.objectType.properties ?? {})
     .filter(
-      id => isPropertyParameter(def, id, def.objectType.properties?.[id].type!),
+      id =>
+        isPropertyParameter(def, id, def.objectType.properties?.[id].type!)
+        && !isStruct(def.objectType.properties?.[id].type!)
+        && !propertiesWithDerivedDatasources.includes(id),
     );
   const parameterNames = new Set(propertyParameters);
   Object.keys(def.parameterConfiguration ?? {}).forEach(param =>

packages/maker/src/api/defineCreateOrModifyObjectAction.ts

@@ -37,13 +37,18 @@ export function defineCreateOrModifyObjectAction(
     Object.keys(def.objectType.properties ?? {}),
     def.objectType.apiName,
   );
+  const propertiesWithDerivedDatasources = (def.objectType.datasources ?? [])
+    .filter(ds => ds.type === "derived").flatMap(ds =>
+      Object.keys(ds.propertyMapping)
+    );
   const propertyParameters = Object.keys(def.objectType.properties ?? {})
     .filter(
       id =>
         !Object.keys(def.nonParameterMappings ?? {}).includes(id)
         && !def.excludedProperties?.includes(id)
         && !isStruct(def.objectType.properties?.[id].type!)
-        && id !== def.objectType.primaryKeyPropertyApiName,
+        && id !== def.objectType.primaryKeyPropertyApiName
+        && !propertiesWithDerivedDatasources.includes(id),
     );
   const parameterNames = new Set(propertyParameters);
   Object.keys(def.parameterConfiguration ?? {}).forEach(param =>

packages/maker/src/api/defineLink.ts

@@ -15,7 +15,6 @@
  */
 
 import type { LinkTypeMetadata } from "@osdk/client.unstable";
-import invariant from "tiny-invariant";
 import { OntologyEntityTypeEnum } from "./common/OntologyEntityTypeEnum.js";
 import {
   convertToPluralDisplayName,
@@ -34,50 +33,13 @@ import type {
   OneToManyObjectLinkReferenceUserDefinition,
 } from "./links/LinkType.js";
 
-const typeIdPattern = /([a-z][a-z0-9\\-]*)/;
-
 export function defineLink(
   linkDefinition: LinkTypeDefinition,
 ): LinkType {
-  if ("one" in linkDefinition) {
-    const foreignKey = linkDefinition.toMany.object.properties
-      ?.[linkDefinition.manyForeignKeyProperty];
-    invariant(
-      foreignKey !== undefined,
-      `Foreign key ${linkDefinition.manyForeignKeyProperty} on link ${linkDefinition.apiName} does not exist on object ${linkDefinition.toMany.object.apiName}}`,
-    );
-
-    invariant(
-      typeIdPattern.test(linkDefinition.apiName),
-      `Top level link api names are expected to match the regex pattern ([a-z][a-z0-9\\-]*) ${linkDefinition.apiName} does not match`,
-    );
+  // NOTE: we would normally do validation here, but because of circular dependencies
+  // we have to wait to validate until everything has been defined. The code for validation
+  // was moved to convertLink.ts.
 
-    const typesMatch = foreignKey.type
-      === linkDefinition.one.object.properties
-        ?.[linkDefinition.one.object.primaryKeyPropertyApiName].type;
-    invariant(
-      typesMatch,
-      `Link ${linkDefinition.apiName} has type mismatch between the one side's primary key and the foreign key on the many side`,
-    );
-  }
-  if ("intermediaryObjectType" in linkDefinition) {
-    invariant(
-      "one" in linkDefinition.many.linkToIntermediary
-        && linkDefinition.many.linkToIntermediary.one.object.apiName
-          === linkDefinition.many.object.apiName
-        && linkDefinition.many.linkToIntermediary.toMany.object.apiName
-          === linkDefinition.intermediaryObjectType.apiName,
-      `LinkTypeA ${linkDefinition.many.linkToIntermediary.apiName} must be a many to one link from intermediary object ${linkDefinition.intermediaryObjectType.apiName} to objectA ${linkDefinition.many.object.apiName}`,
-    );
-    invariant(
-      "one" in linkDefinition.toMany.linkToIntermediary
-        && linkDefinition.toMany.linkToIntermediary.one.object.apiName
-          === linkDefinition.toMany.object.apiName
-        && linkDefinition.toMany.linkToIntermediary.toMany.object.apiName
-          === linkDefinition.intermediaryObjectType.apiName,
-      `LinkTypeB ${linkDefinition.toMany.linkToIntermediary.apiName} must be a many to one link from intermediary object ${linkDefinition.intermediaryObjectType.apiName} to objectB ${linkDefinition.toMany.object.apiName}`,
-    );
-  }
   let fullLinkDefinition;
   if ("one" in linkDefinition) {
     fullLinkDefinition = {
@@ -107,6 +69,7 @@ export function defineLink(
       ? linkDefinition.cardinality
       : undefined,
     ...fullLinkDefinition,
+    apiName: linkDefinition.apiName,
     __type: OntologyEntityTypeEnum.LINK_TYPE,
   };
   updateOntology(linkType);