Add experimental link subscriptions by jbusa22 · Pull Request #3886 · palantir/osdk-ts

jbusa22 · 2026-08-14T17:40:00Z

Summary

add an experimental subscribeToLinks API for subscribing to directed link changes from selected OSDK objects
infer the object type from the first object and require every remaining object to have that same concrete type
infer valid directed link API names and each update target type from the generated ontology types
deliver backend update batches over the ontology subscriptions WebSocket
reuse the existing object-set subscription retry and WebSocket test infrastructure

Usage

This example watches two managers for changes to their direct reports. fetchOne returns real Osdk.Instance<Employee> values, and peeps is the generated directed link API name from a manager to their reports.

import {
  __EXPERIMENTAL__NOT_SUPPORTED_YET__linkSubscriptions,
} from "@osdk/api/unstable";
import { Employee } from "./generated/ontology/objects/Employee.js";

const [managerOne, managerTwo] = await Promise.all([
  client(Employee).fetchOne(managerOneId),
  client(Employee).fetchOne(managerTwoId),
]);

# Still need to get the links from a separate service
const directReportsLink = "peeps"

const subscription = client(
  __EXPERIMENTAL__NOT_SUPPORTED_YET__linkSubscriptions,
).subscribeToLinks({
  objects: [managerOne, managerTwo],
  links: [directReportsLink],
  listener: {
    onSuccessfulSubscription() {
      console.log("Listening for direct-report changes");
    },
    onChange({ updates }) {
      for (const update of updates) {
        // source is the manager; target is the added or removed report.
        console.log(update.state, update.source, update.target);
      }
    },
    onOutOfDate({ links }) {
      // Re-fetch any local state derived from these links.
      console.log("Links need refreshing", links);
    },
    onError({ error, subscriptionClosed }) {
      console.error({ error, subscriptionClosed });
    },
  },
});

subscription.unsubscribe();

jbusa22 · 2026-08-14T21:12:58Z

+
+  async #prepare(): Promise<void> {
+    try {
+      const [firstObject] = this.#args.objects;


I think ts should enforce that all objects are the same type so this is safe

nihalbhatnagar · 2026-08-24T19:34:16Z

      | QueryDefinition<any>
      | Experiment<"2.0.8">
      | Experiment<"2.1.0">
+      | Experiment<"2.17.0">


This probably needs to be 2.59 and updated to the version at which we ship osdk/client. @ssanjay1 we def need to review this paradigm since we're shipping minor versions rapidly now

nihalbhatnagar · 2026-08-24T19:34:39Z

    "@osdk/foundry.admin": 2.70.0
    "@osdk/foundry.mediasets": 2.70.0
-    "@osdk/foundry.ontologies": 2.70.0
+    "@osdk/foundry.ontologies": 2.73.0


Lets go ahead and bump the rest to keep in sync

nihalbhatnagar · 2026-08-24T19:37:34Z

-const EXPONENTIAL_BACKOFF_JITTER_FACTOR = 0.3;
-const WEBSOCKET_IDLE_DISCONNECT_DELAY_MS = 15000;
-const WEBSOCKET_HEARTBEAT_INTERVAL_MS = 45 * 1000;
+export const EXPONENTIAL_BACKOFF_INITIAL_DELAY_MS: number = 1000;


Probably should move these to a shared util file instead of exporting from here

nihalbhatnagar · 2026-08-24T19:44:11Z

+}
+
+/** @internal */
+export class LinkSubscriptionWebsocket {


Can we create a super class that both of these websockets now use for websocket connection/retry/heartbeat logic? I'd imagine that we can basically reuse onMessage, onOpen, initiateSubscribe, all the way upto the specific message ser/de and request payloads?

nihalbhatnagar · 2026-08-24T19:45:17Z

@@ -810,9 +810,39 @@ export class ObjectSetListenerWebsocket {

 /** @internal */
 export function constructWebsocketUrl(baseUrl: string, ontologyRid: string) {


Yeah I think keeping these in the same utils file as above will be helpful

nihalbhatnagar · 2026-08-24T20:13:47Z

+    ];
+  }
+
+  export interface ChangeEvent<


Maybe LinkUpdate to match ObjectSetUpdate?

Can we flatten this out too? We did the same for object set updates where youc an get multiple object updates back on one message, but the handler should be triggered once per specific update/object

nihalbhatnagar · 2026-08-24T20:53:43Z

+    Q extends ObjectTypeDefinition,
+    L extends LinkTypeApiNamesFor<Q>,
+  > {
+    readonly links: readonly [L, ...ReadonlyArray<NoInfer<L>>];


Can we leave this as a regular array? (NoInfer is fine). We generally try to avoid non-empty array type in this codebase

nihalbhatnagar · 2026-08-24T20:55:21Z

+    : never;
+}
+
+type SubscribeToLinks = <


Can we add javadoc for this method. Also, will this work for updates to one to many link types backed by a FK? If not, we should document that here

nihalbhatnagar · 2026-08-24T20:56:33Z

+    unsubscribe: () => {},
+  });
+
+  it("infers links and updates from the first object", () => {


Thank you for the type test

nihalbhatnagar · 2026-08-24T21:02:01Z

+    vi.useRealTimers();
+  });
+
+  it("multiplexes subscriptions and routes update batches", async () => {


Could you make this description a bit more clear, like "uses one WebSocket for multiple subscriptions and sends updates to the correct listener", I was a bit confused by the wording

nihalbhatnagar · 2026-08-25T17:34:06Z

-    L extends LinkTypeApiNamesFor<Q>,
-  > {
-    readonly updates: ReadonlyArray<Update<Q, L>>;
+    readonly objects: ReadonlyArray<Osdk.Instance<Q>>;


We should probably have this mimic the queries and actions API that take objects like here

osdk-ts/packages/api/src/queries/Queries.ts

Line 57 in 830d791

| OsdkObjectPrimaryKeyType<T>;

, which probably means just using that same union

nihalbhatnagar · 2026-08-25T17:39:14Z

-    if (isDone(subscription)) return;
+    if (isSubscriptionDone(subscription)) return;
    try {
      subscription.listener.onError?.({ error, subscriptionClosed: true });


Should we try catch this error call too?

nihalbhatnagar · 2026-08-26T14:33:11Z

Nitty but I think the API should be (Employee, {listener, objects,links})

Invalidated by push of 5d34c94

…tions

Invalidated by push of 1e71fd5

Invalidated by push of bd55880

Invalidated by push of 1311a36

jbusa22 commented Aug 14, 2026

View reviewed changes

nihalbhatnagar reviewed Aug 24, 2026

View reviewed changes

nihalbhatnagar reviewed Aug 25, 2026

View reviewed changes

nihalbhatnagar reviewed Aug 26, 2026

View reviewed changes

nihalbhatnagar previously approved these changes Aug 26, 2026

View reviewed changes

jbusapalantir and others added 6 commits August 26, 2026 09:42

Add link subscriptions

2b55122

Multiplex link subscriptions

3999654

Extract shared SubscriptionWebsocket for object set and link subscrip…

5722e79

…tions

Use shared websocket for subscriptions

0e6b9be

Address link subscription review

a7c293b

Update link subscription API

1e71fd5

jbusa22 force-pushed the jbusa-osdk-link-subscriptions branch from 5d34c94 to 1e71fd5 Compare August 26, 2026 16:46

nihalbhatnagar previously approved these changes Aug 26, 2026

View reviewed changes

Format mock websocket

bd55880

nihalbhatnagar previously approved these changes Aug 26, 2026

View reviewed changes

Wait for object set revalidation

1311a36

nihalbhatnagar approved these changes Aug 26, 2026

View reviewed changes

nihalbhatnagar merged commit bdf45fa into palantir:main Aug 27, 2026
23 checks passed

		@@ -810,9 +810,39 @@ export class ObjectSetListenerWebsocket {

		/** @internal */
		export function constructWebsocketUrl(baseUrl: string, ontologyRid: string) {

Uh oh!

Conversation

jbusa22 commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Usage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jbusa22 commented Aug 14, 2026 •

edited

Loading