Experimental object set asyncIterLinks (#2209)

bryantpark04 · web-flow · commit 1e3c147d6dd9 · 2025-12-16T16:57:56.000-05:00
* Sketch out implementation of asyncIterLinks * Add asyncIterLinks to createObjectSet * Add preview=true to platform SDK call * Fix target type and add type tests * Add e2e test * Add test for single link * Add changeset * Fix tests * Update e2e test * Add request context * Add fetchLinksPage tests * Add more detailed example of usage * Add more docs * Rename {ObjectLink,LinksForObject} -> MinimalDirectedObjectLinkInstance * Rename asyncIterLinks -> experimental_asyncIterLinks * Revert "Add changeset" This reverts commit 6620283. * Add patch changeset
diff --git a/.changeset/busy-needles-follow.md b/.changeset/busy-needles-follow.md
@@ -0,0 +1,6 @@
+---
+"@osdk/client": patch
+"@osdk/api": patch
+---
+
+Add experimental_asyncIterLinks method on object sets
diff --git a/etc/api.report.api.md b/etc/api.report.api.md
@@ -602,6 +602,15 @@ export const DurationMapping: {
 // @public (undocumented)
 export type DurationPrecision = "DAYS" | "HOURS" | "MINUTES" | "SECONDS" | "AUTO";
 
+// @public (undocumented)
+export type FetchLinksPageResult<
+	Q extends ObjectOrInterfaceDefinition,
+	LINK_TYPE extends LinkTypeApiNamesFor<Q>
+> = {
+    	data: Array<MinimalDirectedObjectLinkInstance<Q, LINK_TYPE>>
+    	nextPageToken?: string
+};
+
 // @public (undocumented)
 export interface FetchPageArgs<
 	Q extends ObjectOrInterfaceDefinition,
@@ -794,6 +803,9 @@ export type LinkedType<
 // @public (undocumented)
 export type LinkNames<Q extends ObjectOrInterfaceDefinition> = Q extends InterfaceDefinition ? keyof CompileTimeMetadata<Q>["links"] : keyof CompileTimeMetadata<Q>["links"] & string;
 
+// @public (undocumented)
+export type LinkTypeApiNamesFor<Q extends ObjectOrInterfaceDefinition> = Extract<keyof CompileTimeMetadata<Q>["links"], string>;
+
 // @public (undocumented)
 export interface Logger {
     	// (undocumented)
@@ -879,6 +891,16 @@ export interface MediaUpload {
     readonly fileName: string;
 }
 
+// @public (undocumented)
+export type MinimalDirectedObjectLinkInstance<
+	Q extends ObjectOrInterfaceDefinition,
+	LINK_TYPE_API_NAME extends LinkTypeApiNamesFor<Q>
+> = {
+    	source: ObjectIdentifiers<Q>
+    	target: ObjectIdentifiers<LinkedObjectType<Q, LINK_TYPE_API_NAME>>
+    	linkType: LINK_TYPE_API_NAME
+};
+
 // @public (undocumented)
 export type NotWhereClause<
 	T extends ObjectOrInterfaceDefinition,
@@ -1858,6 +1880,7 @@ export type WirePropertyTypes = BaseWirePropertyTypes | Record<string, BaseWireP
 // src/aggregate/AggregateOpts.ts:25:3 - (ae-forgotten-export) The symbol "OrderedAggregationClause" needs to be exported by the entry point index.d.ts
 // src/aggregate/AggregationResultsWithGroups.ts:36:5 - (ae-forgotten-export) The symbol "MaybeNullable_2" needs to be exported by the entry point index.d.ts
 // src/aggregate/AggregationResultsWithGroups.ts:36:5 - (ae-forgotten-export) The symbol "OsdkObjectPropertyTypeNotUndefined" needs to be exported by the entry point index.d.ts
+// src/objectSet/ObjectSetLinks.ts:36:3 - (ae-forgotten-export) The symbol "LinkedObjectType" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
@@ -91,6 +91,11 @@ export { isOk } from "./object/Result.js";
 export type { Result } from "./object/Result.js";
 export type { BaseObjectSet } from "./objectSet/BaseObjectSet.js";
 export type { ObjectSet } from "./objectSet/ObjectSet.js";
+export type {
+  FetchLinksPageResult,
+  LinkTypeApiNamesFor,
+  MinimalDirectedObjectLinkInstance,
+} from "./objectSet/ObjectSetLinks.js";
 export type { ObjectSetSubscription } from "./objectSet/ObjectSetListener.js";
 export type {
   ActionDefinition,
diff --git a/packages/api/src/objectSet/ObjectSet.test.ts b/packages/api/src/objectSet/ObjectSet.test.ts
@@ -19,6 +19,7 @@ import { describe, expectTypeOf, it, test, vi } from "vitest";
 import type {
   DerivedProperty,
   NullabilityAdherence,
+  ObjectIdentifiers,
   ObjectOrInterfaceDefinition,
   ObjectSet as $ObjectSet,
   Osdk,
@@ -29,6 +30,15 @@ import type { DerivedObjectOrInterfaceDefinition } from "../ontology/ObjectOrInt
 import { EmployeeApiTest } from "../test/EmployeeApiTest.js";
 import { FooInterfaceApiTest } from "../test/FooInterfaceApiTest.js";
 
+async function* asyncIterateLinkOnce() {
+  const obj = { $apiName: undefined, $primaryKey: undefined };
+  yield Promise.resolve({
+    source: obj,
+    target: obj,
+    linkTypeApiName: undefined,
+  });
+}
+
 export function createMockObjectSet<
   Q extends ObjectOrInterfaceDefinition,
 >(): $ObjectSet<Q, never> {
@@ -73,6 +83,7 @@ export function createMockObjectSet<
     nearestNeighbors: vi.fn(() => {
       return fauxObjectSet;
     }),
+    experimental_asyncIterLinks: vi.fn(asyncIterateLinkOnce),
   } as any as $ObjectSet<Q>;
 
   return fauxObjectSet;
@@ -1491,4 +1502,55 @@ describe("ObjectSet", () => {
       >();
     });
   });
+
+  describe("asyncIterLinks", async () => {
+    it("typechecks self-referential one link", async () => {
+      for await (
+        const { source, target, linkType } of fauxObjectSet
+          .experimental_asyncIterLinks([
+            "lead",
+          ])
+      ) {
+        expectTypeOf(source).toEqualTypeOf<
+          ObjectIdentifiers<EmployeeApiTest>
+        >();
+
+        expectTypeOf(target).toEqualTypeOf<
+          ObjectIdentifiers<EmployeeApiTest>
+        >();
+
+        expectTypeOf(source.$apiName).toBeString();
+        expectTypeOf(target.$apiName).toBeString();
+        expectTypeOf(source.$primaryKey).toBeNumber();
+        expectTypeOf(target.$primaryKey).toBeNumber();
+
+        expectTypeOf(linkType).toEqualTypeOf<"lead">();
+      }
+    });
+
+    it("typechecks self-referential multiple links", async () => {
+      for await (
+        const { source, target, linkType } of fauxObjectSet
+          .experimental_asyncIterLinks([
+            "lead",
+            "peeps",
+          ])
+      ) {
+        expectTypeOf(source).toEqualTypeOf<
+          ObjectIdentifiers<EmployeeApiTest>
+        >();
+
+        expectTypeOf(target).toEqualTypeOf<
+          ObjectIdentifiers<EmployeeApiTest>
+        >();
+
+        expectTypeOf(source.$apiName).toBeString();
+        expectTypeOf(target.$apiName).toBeString();
+        expectTypeOf(source.$primaryKey).toBeNumber();
+        expectTypeOf(target.$primaryKey).toBeNumber();
+
+        expectTypeOf(linkType).toEqualTypeOf<"lead" | "peeps">();
+      }
+    });
+  });
 });
diff --git a/packages/api/src/objectSet/ObjectSet.ts b/packages/api/src/objectSet/ObjectSet.ts
@@ -50,6 +50,10 @@ import type {
 import type { PageResult } from "../PageResult.js";
 import type { LinkedType, LinkNames } from "../util/LinkUtils.js";
 import type { BaseObjectSet } from "./BaseObjectSet.js";
+import type {
+  LinkTypeApiNamesFor,
+  MinimalDirectedObjectLinkInstance,
+} from "./ObjectSetLinks.js";
 import type { ObjectSetSubscription } from "./ObjectSetListener.js";
 
 type MergeObjectSet<
@@ -107,7 +111,8 @@ export interface MinimalObjectSet<
   BaseObjectSet<Q>,
   FetchPage<Q, RDPs>,
   AsyncIter<Q, RDPs, ORDER_BY_OPTIONS>,
-  Where<Q, RDPs>
+  Where<Q, RDPs>,
+  AsyncIterLinks<Q>
 {
 }
 
@@ -586,6 +591,28 @@ type ExtractImplementingTypes<T extends InterfaceDefinition> =
     ? (ObjectTypeDefinition & { apiName: API_NAME }) | InterfaceDefinition
     : InterfaceDefinition;
 
+interface AsyncIterLinks<Q extends ObjectOrInterfaceDefinition> {
+  /**
+   * Batch load links on an object set. This is an experimental method that may change while in beta.
+   * Use this method in conjunction with `.asyncIter()` and `.pivotTo(...).asyncIter()` to build an
+   * object graph in memory.
+   *
+   * Please keep these limitations in mind:
+   * - Links returned may be stale. For example, primary keys returned by this endpoint may not exist anymore.
+   * - The backend API fetches pages of *n* objects at a time. If, for any page of *n* objects, there are more
+   *   than 100,000 links present, results are limited to 100,000 links and should be considered partial.
+   * - This method does not support OSv1 links and will throw an exception if links provided are backed by OSv1.
+   * - This method currently does not support interface links, but support will be added in the near future.
+   */
+  readonly experimental_asyncIterLinks: <
+    LINK_TYPE_API_NAME extends LinkTypeApiNamesFor<Q>,
+  >(
+    links: LINK_TYPE_API_NAME[],
+  ) => AsyncIterableIterator<
+    MinimalDirectedObjectLinkInstance<Q, LINK_TYPE_API_NAME>
+  >;
+}
+
 interface ObjectSetCleanedTypes<
   Q extends ObjectOrInterfaceDefinition,
   D extends Record<string, SimplePropertyDef>,
diff --git a/packages/api/src/objectSet/ObjectSetLinks.ts b/packages/api/src/objectSet/ObjectSetLinks.ts
@@ -0,0 +1,46 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * 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 type { ObjectOrInterfaceDefinition } from "../ontology/ObjectOrInterface.js";
+import type { CompileTimeMetadata } from "../ontology/ObjectTypeDefinition.js";
+import type { ObjectIdentifiers } from "../OsdkBase.js";
+
+export type LinkTypeApiNamesFor<Q extends ObjectOrInterfaceDefinition> =
+  Extract<keyof CompileTimeMetadata<Q>["links"], string>;
+
+type LinkedObjectType<
+  Q extends ObjectOrInterfaceDefinition,
+  LINK_TYPE_API_NAME extends LinkTypeApiNamesFor<Q>,
+> = NonNullable<
+  CompileTimeMetadata<Q>["links"][LINK_TYPE_API_NAME]["__OsdkLinkTargetType"]
+>;
+
+export type MinimalDirectedObjectLinkInstance<
+  Q extends ObjectOrInterfaceDefinition,
+  LINK_TYPE_API_NAME extends LinkTypeApiNamesFor<Q>,
+> = {
+  source: ObjectIdentifiers<Q>;
+  target: ObjectIdentifiers<LinkedObjectType<Q, LINK_TYPE_API_NAME>>;
+  linkType: LINK_TYPE_API_NAME;
+};
+
+export type FetchLinksPageResult<
+  Q extends ObjectOrInterfaceDefinition,
+  LINK_TYPE extends LinkTypeApiNamesFor<Q>,
+> = {
+  data: Array<MinimalDirectedObjectLinkInstance<Q, LINK_TYPE>>;
+  nextPageToken?: string;
+};
diff --git a/packages/client/src/objectSet/createObjectSet.ts b/packages/client/src/objectSet/createObjectSet.ts
@@ -21,6 +21,8 @@ import type {
   InterfaceDefinition,
   LinkedType,
   LinkNames,
+  LinkTypeApiNamesFor,
+  MinimalDirectedObjectLinkInstance,
   NullabilityAdherence,
   ObjectOrInterfaceDefinition,
   ObjectSet,
@@ -52,6 +54,7 @@ import { fetchSingle, fetchSingleWithErrors } from "../object/fetchSingle.js";
 import { augmentRequestContext } from "../util/augmentRequestContext.js";
 import { resolveBaseObjectSetType } from "../util/objectSetUtils.js";
 import { isWireObjectSet } from "../util/WireObjectSet.js";
+import { fetchLinksPage } from "./fetchLinksPage.js";
 import { ObjectSetListenerWebsocket } from "./ObjectSetListenerWebsocket.js";
 
 function isObjectTypeDefinition(
@@ -325,6 +328,32 @@ export function createObjectSet<Q extends ObjectOrInterfaceDefinition>(
       );
     },
 
+    experimental_asyncIterLinks: async function*<
+      LINK_TYPE_API_NAME extends LinkTypeApiNamesFor<Q>,
+    >(
+      links: LINK_TYPE_API_NAME[],
+    ): AsyncIterableIterator<
+      MinimalDirectedObjectLinkInstance<Q, LINK_TYPE_API_NAME>
+    > {
+      let $nextPageToken: string | undefined = undefined;
+      do {
+        const result = await fetchLinksPage(
+          augmentRequestContext(
+            clientCtx,
+            _ => ({ finalMethodCall: "asyncIterLinks" }),
+          ),
+          objectType,
+          objectSet,
+          links,
+        );
+        $nextPageToken = result.nextPageToken;
+
+        for (const obj of result.data) {
+          yield obj;
+        }
+      } while ($nextPageToken != null);
+    },
+
     $objectSetInternals: {
       def: objectType,
     },
diff --git a/packages/client/src/objectSet/fetchLinksPage.test.ts b/packages/client/src/objectSet/fetchLinksPage.test.ts
@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 Palantir Technologies, Inc. All rights reserved.
+ *
+ * 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 { describe, expect, it } from "vitest";
+import { remapLinksPage, remapObjectLocator } from "./fetchLinksPage.js";
+
+describe("remapObjectLocator", () => {
+  it("works", () => {
+    expect(
+      remapObjectLocator({
+        __apiName: "Foo",
+        __primaryKey: "bar",
+        prop: "BAZ",
+      }),
+    ).toEqual({ $apiName: "Foo", $primaryKey: "bar" });
+  });
+});
+
+describe("remapLinksPage", () => {
+  it("works", () => {
+    expect(
+      remapLinksPage({
+        nextPageToken: "foo",
+        data: [
+          {
+            sourceObject: { __apiName: "Object", __primaryKey: 0 },
+            linkedObjects: [
+              {
+                targetObject: { __apiName: "LinkedObject", __primaryKey: 1 },
+                linkType: "link",
+              },
+            ],
+          },
+          {
+            sourceObject: { __apiName: "Object", __primaryKey: 1 },
+            linkedObjects: [
+              {
+                targetObject: { __apiName: "LinkedObject", __primaryKey: 2 },
+                linkType: "link",
+              },
+              {
+                targetObject: { __apiName: "LinkedObject", __primaryKey: 3 },
+                linkType: "link",
+              },
+            ],
+          },
+        ],
+      }),
+    ).toEqual({
+      nextPageToken: "foo",
+      data: [
+        {
+          source: { $apiName: "Object", $primaryKey: 0 },
+          target: { $apiName: "LinkedObject", $primaryKey: 1 },
+          linkType: "link",
+        },
+        {
+          source: { $apiName: "Object", $primaryKey: 1 },
+          target: { $apiName: "LinkedObject", $primaryKey: 2 },
+          linkType: "link",
+        },
+        {
+          source: { $apiName: "Object", $primaryKey: 1 },
+          target: { $apiName: "LinkedObject", $primaryKey: 3 },
+          linkType: "link",
+        },
+      ],
+    });
+  });
+});
diff --git a/packages/client/src/objectSet/fetchLinksPage.ts b/packages/client/src/objectSet/fetchLinksPage.ts
diff --git a/packages/e2e.sandbox.catchall/src/public/checkUnstableBulkLinks.ts b/packages/e2e.sandbox.catchall/src/public/checkUnstableBulkLinks.ts
