@osdk/react 0.10.0-beta.1 → 0.10.0-beta.10

package/AGENTS.md

@@ -1,21 +1,20 @@
-# @osdk/react - AI Agent Instructions
+# @osdk/react
 
-## Critical Rules
+## Rules
 
-1. **Use `OsdkProvider2`** - Not `OsdkProvider`. All modern hooks require `OsdkProvider2`.
-2. **Import from `@osdk/react/experimental`** - Not `@osdk/react`. The main entry point only has legacy hooks.
-3. **Never conditionally call hooks** - Use the `enabled` option instead.
-4. **Keep rendering during loading** - No early returns like `if (isLoading) return <Spinner />`. Show loading indicators while rendering existing data.
+1. **Use `OsdkProvider2`**, not `OsdkProvider`. All modern hooks require it.
+2. **Import from `@osdk/react/experimental`**, not `@osdk/react`. Main entry only has legacy hooks.
+3. **Never conditionally call hooks.** Use the `enabled` option instead.
+4. **Keep rendering during loading.** No early returns like `if (isLoading) return <Spinner />`. Show loading indicators alongside existing data to prevent UI flashing. Exception: `if (!data && isLoading)` is acceptable for initial load.
+5. **`useOsdkObject` `enabled` is positional**, not in an options object: `useOsdkObject(Type, id, false)`.
 
 ## Exports
 
-**Stable** (`@osdk/react`):
+**Stable** (`@osdk/react`): `OsdkProvider` (legacy), `useOsdkClient`, `useOsdkMetadata`
 
-- `OsdkProvider` - Legacy provider
-- `useOsdkClient` - Access client
-- `useOsdkMetadata` - Fetch metadata
+**Experimental** (`@osdk/react/experimental`): `OsdkProvider2`, `useOsdkObjects`, `useOsdkObject`, `useOsdkAction`, `useLinks`, `useObjectSet`, `useOsdkAggregation`, `useOsdkFunction`, `useDebouncedCallback`, `useCurrentFoundryUser`, `useFoundryUser`, `useFoundryUsersList`
 
-**Experimental** (`@osdk/react/experimental`):
+## Hook Options
 
 - `OsdkProvider2` - Modern provider (use this)
 - `useOsdkObjects` - Query lists of objects
@@ -24,230 +23,56 @@
 - `useLinks` - Navigate object relationships
 - `useObjectSet` - Advanced set operations (union, intersect, subtract, pivot)
 - `useOsdkAggregation` - Server-side aggregations with groupBy/select
-- `useCurrentFoundryUser`, `useFoundryUser`, `useFoundryUsersList` - Platform APIs
 - `useOsdkClient`, `useOsdkMetadata` - Also available from experimental
 
-## Correct Patterns
-
-### Loading States
-
-```tsx
-import { Todo } from "@my/osdk";
-import { useOsdkObjects } from "@osdk/react/experimental";
-
-function TodoList() {
-  const { data, isLoading, error } = useOsdkObjects(Todo);
-
-  return (
-    <div>
-      {isLoading && <LoadingIndicator />}
-      {error && <ErrorMessage error={error} />}
-      {data?.map(todo => <TodoItem key={todo.$primaryKey} todo={todo} />)}
-    </div>
-  );
-}
-```
+**Experimental Admin** (`@osdk/react/experimental/admin`):
 
-### Single Object (useOsdkObject)
-
-```tsx
-import { Employee } from "@my/osdk";
-import { useOsdkObject } from "@osdk/react/experimental";
-
-// By type + primary key (enabled is 3rd positional param)
-const { object, isLoading, error, isOptimistic } = useOsdkObject(
-  Employee,
-  "employee-123",
-  true, // enabled (optional, defaults to true)
-);
-
-// By existing instance (enabled is 2nd positional param)
-const { object: refreshed } = useOsdkObject(existingEmployee, true);
-```
-
-### Conditional Fetching
-
-```tsx
-// useOsdkObjects uses options object
-const { data: reports } = useOsdkObjects(Employee, {
-  where: { managerId: selectedManagerId },
-  enabled: !!selectedManagerId,
-});
-
-// useOsdkObject uses positional enabled parameter
-const { object: manager } = useOsdkObject(Employee, managerId, !!managerId);
-```
+- `useCurrentFoundryUser`, `useFoundryUser`, `useFoundryUsersList` - Platform APIs (requires `@osdk/foundry.admin`)
 
-### Actions (useOsdkAction)
+## Correct Patterns
 
-```tsx
-import { $Actions } from "@my/osdk";
-import { useOsdkAction } from "@osdk/react/experimental";
-
-function CompleteTodoButton({ todo }) {
-  const {
-    applyAction,
-    validateAction,
-    isPending,
-    isValidating,
-    error,
-    data,
-    validationResult,
-  } = useOsdkAction($Actions.completeTodo);
-
-  // Validate before applying
-  const handleValidate = async () => {
-    const result = await validateAction({ todo, isComplete: true });
-  };
-
-  // Apply the action
-  const handleComplete = async () => {
-    await applyAction({ todo, isComplete: true });
-  };
-
-  // With optimistic update (use $ prefix for client options)
-  const handleOptimistic = async () => {
-    await applyAction({
-      todo,
-      isComplete: true,
-      $optimisticUpdate: (ctx) => {
-        ctx.updateObject(todo, { isComplete: true });
-      },
-    });
-  };
-
-  return (
-    <button onClick={handleComplete} disabled={isPending}>
-      Complete
-    </button>
-  );
-}
-```
+| Hook                 | Key Options                                                                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useOsdkObjects`     | `where`, `orderBy`, `pageSize`, `withProperties`, `enabled`, `autoFetchMore`, `dedupeIntervalMs`, `streamUpdates`, `intersectWith`, `pivotTo` |
+| `useObjectSet`       | Same as above plus `union`, `intersect`, `subtract`. Use when you need set operations.                                                        |
+| `useOsdkObject`      | `enabled` is **positional** (2nd param for instance, 3rd for type+key)                                                                        |
+| `useLinks`           | `where`, `pageSize`, `enabled`, `mode` (`"force"` / `"offline"`), `dedupeIntervalMs`. Accepts single object or array.                         |
+| `useOsdkAction`      | Returns `applyAction`, `validateAction`, `isPending`, `error`, `validationResult`. Pass `$optimisticUpdate` with `$` prefix in action params. |
+| `useOsdkAggregation` | `where`, `aggregate: { $groupBy, $select }`. Metrics: `$count`, `sum`, `avg`, `min`, `max`, `exactDistinct`, `approximateDistinct`.           |
+| `useOsdkFunction`    | `params`, `dependsOn` (object types), `dependsOnObjects` (instances), `enabled`, `dedupeIntervalMs`                                           |
 
-### Links (useLinks)
+## Text Search Filters
 
-```tsx
-import { useLinks } from "@osdk/react/experimental";
-
-// Single object
-const { links, isLoading, hasMore, fetchMore, error } = useLinks(
-  employee,
-  "directReports",
-  { pageSize: 20 },
-);
-
-// Multiple objects (returns all linked objects)
-const { links: allReports } = useLinks(
-  [employee1, employee2],
-  "directReports",
-);
-```
+`$startsWith`, `$containsAnyTerm`, `$containsAllTerms`, `$containsAllTermsInOrder`. All support `{ term, fuzzySearch: true }`.
 
-### Object Set Operations (useObjectSet)
+## useOsdkObjects vs useObjectSet
 
-```tsx
-import { Employee } from "@my/osdk";
-import { useObjectSet } from "@osdk/react/experimental";
-
-const { data, isLoading, fetchMore, objectSet } = useObjectSet(
-  Employee.all(),
-  {
-    where: { department: "Engineering" },
-    orderBy: { hireDate: "desc" },
-    pageSize: 50,
-    union: [otherObjectSet],
-    intersect: [anotherObjectSet],
-    autoFetchMore: 100, // fetch until 100 items
-    streamUpdates: true,
-    enabled: true,
-  },
-);
-```
+Use `useOsdkObjects` by default (more optimized). Use `useObjectSet` only when you need `union`/`intersect`/`subtract` set operations.
 
-### Aggregations (useOsdkAggregation)
+## Cache
 
-```tsx
-import { Employee } from "@my/osdk";
-import { useOsdkAggregation } from "@osdk/react/experimental";
-
-const { data, isLoading, error, refetch } = useOsdkAggregation(Employee, {
-  where: { department: "Engineering" },
-  aggregate: {
-    groupBy: { department: "exact" },
-    select: {
-      avgSalary: { $avg: "salary" },
-      count: { $count: {} },
-    },
-  },
-});
-```
+The `ObservableClient` maintains a normalized cache. Objects update automatically after actions. For manual invalidation: `observableClient.invalidateObjects()`, `.invalidateObjectType()`, `.invalidateFunction()`, `.invalidateAll()`.
 
 ## Anti-Patterns
 
-### Wrong: Conditional Hook Call
-
-```tsx
-if (shouldLoad) {
-  const { data } = useOsdkObjects(Todo); // NEVER do this
-}
-```
-
-### Wrong: Early Return During Loading
-
-```tsx
-if (isLoading) return <Spinner />; // Causes UI flashing
-if (!data) return null; // Loses state
-```
-
-### Wrong: Importing from Main Entry
-
-```tsx
-import { useOsdkObjects } from "@osdk/react"; // WRONG - doesn't exist here
-```
-
-### Wrong: Using OsdkProvider Instead of OsdkProvider2
-
 ```tsx
-<OsdkProvider client={client}> // WRONG - new hooks won't work
-```
-
-### Wrong: Using options object for useOsdkObject enabled
-
-```tsx
-// WRONG - enabled is positional, not in options
-const { object } = useOsdkObject(Employee, id, { enabled: false });
-
+// WRONG: conditional hook
+if (x) { useOsdkObjects(Todo); }
+// CORRECT: use enabled
+useOsdkObjects(Todo, { enabled: x });
+
+// WRONG: early return
+if (isLoading) return <Spinner />;
+// CORRECT: render together
+<div>{isLoading && <Spinner />}{data?.map(...)}</div>
+
+// WRONG: import from main entry
+import { useOsdkObjects } from "@osdk/react";
 // CORRECT
-const { object } = useOsdkObject(Employee, id, false);
-```
-
-## Hook Options Reference
-
-**useOsdkObjects / useObjectSet:**
-
-- `where` - Filter conditions
-- `orderBy` - Sort order (`{ field: "asc" | "desc" }`)
-- `pageSize` - Results per page
-- `withProperties` - Derived properties
-- `enabled` - Enable/disable query
-- `autoFetchMore` - Auto-pagination (`true` | `number`)
-- `dedupeIntervalMs` - Request deduplication
-- `streamUpdates` - WebSocket updates
-
-**useObjectSet additional:**
-
-- `union`, `intersect`, `subtract` - Set operations
-- `pivotTo` - Pivot to linked type
-
-**useOsdkObject:**
-
-- `enabled` is a **positional parameter**, not in options
-
-**useLinks:**
-
-- `where`, `pageSize`, `enabled`
-- `mode` - `"force"` | `"offline"`
-
-**useOsdkAction:**
+import { useOsdkObjects } from "@osdk/react/experimental";
 
-- `$optimisticUpdate` - Passed to action with `$` prefix
+// WRONG: useOsdkObject enabled in options
+useOsdkObject(Employee, id, { enabled: false });
+// CORRECT: positional
+useOsdkObject(Employee, id, false);
+```

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # @osdkkit/react
 
+## 0.10.0-beta.10
+
+### Minor Changes
+
+- dbbfb6f: Add experimental ActionForm component with field renderers, form state hook, and tests
+
+### Patch Changes
+
+- Updated dependencies [cbfa135]
+- Updated dependencies [f4604c2]
+  - @osdk/client@2.8.0-beta.22
+  - @osdk/api@2.8.0-beta.22
+
+## 0.10.0-beta.9
+
+### Minor Changes
+
+- c40444b: Add linkedObjectsBySourcePrimaryKey to link observation responses
+
+### Patch Changes
+
+- Updated dependencies [c40444b]
+- Updated dependencies [dda14be]
+  - @osdk/client@2.8.0-beta.21
+  - @osdk/api@2.8.0-beta.21
+
+## 0.10.0-beta.8
+
+### Minor Changes
+
+- 9720083: Add AGENTS.md files for AI IDE context
+- 09e5659: add $select support to observable client and react hooks
+- 8a82492: Move admin hooks to @osdk/react/experimental/admin subpath to avoid bundler crash when @osdk/foundry.admin is not installed
+- 2ebe62c: package and bundle size optimizations
+
+### Patch Changes
+
+- Updated dependencies [09e5659]
+- Updated dependencies [2ebe62c]
+  - @osdk/client@2.8.0-beta.16
+  - @osdk/api@2.8.0-beta.16
+
+## 0.10.0-beta.7
+
+### Minor Changes
+
+- 9156827: Preserve object set data between loads
+- 35f2f1a: Add Media inputs/outputs for Queries
+- 71e28ef: Allow interface object sets in useObjectSet
+
+### Patch Changes
+
+- Updated dependencies [e64bf0b]
+- Updated dependencies [baba327]
+- Updated dependencies [d1ad4d1]
+- Updated dependencies [35f2f1a]
+- Updated dependencies [71e28ef]
+  - @osdk/client@2.8.0-beta.14
+  - @osdk/api@2.8.0-beta.14
+
+## 0.10.0-beta.6
+
+### Minor Changes
+
+- 993c023: ObjectTable supports objectSet input
+
+### Patch Changes
+
+- Updated dependencies [8825f8c]
+  - @osdk/client@2.8.0-beta.12
+  - @osdk/api@2.8.0-beta.12
+
+## 0.10.0-beta.5
+
+### Minor Changes
+
+- 525f277: update useOsdkAggregation to support composed object sets, async
+- d80c234: add interface support to useOsdkObject
+- 996d8e4: memoize hook responses
+
+### Patch Changes
+
+- Updated dependencies [642be5f]
+- Updated dependencies [525f277]
+- Updated dependencies [f5f95e2]
+- Updated dependencies [d80c234]
+  - @osdk/client@2.8.0-beta.11
+  - @osdk/api@2.8.0-beta.11
+
+## 0.10.0-beta.4
+
+### Minor Changes
+
+- 727fd0e: fix dual @types/react version mismatch
+
+### Patch Changes
+
+- Updated dependencies [8c60682]
+- Updated dependencies [15e1686]
+- Updated dependencies [c9d954d]
+- Updated dependencies [044eb80]
+- Updated dependencies [9d234b9]
+  - @osdk/client@2.8.0-beta.6
+  - @osdk/api@2.8.0-beta.6
+
+## 0.10.0-beta.3
+
+### Minor Changes
+
+- 73e617e: expose dedupeInterval on useLinks and fix forced revalidation bypassing dedupeInterval
+- a027f3c: stabilize subscription deps in useOsdkObjects and useOsdkAggregation
+
+### Patch Changes
+
+- Updated dependencies [73e617e]
+- Updated dependencies [5848e3c]
+  - @osdk/client@2.8.0-beta.4
+  - @osdk/api@2.8.0-beta.4
+
+## 0.10.0-beta.2
+
+### Minor Changes
+
+- 0d174a2: useOsdkFunction typing updates
+
+### Patch Changes
+
+- Updated dependencies [26cec61]
+- Updated dependencies [0d174a2]
+  - @osdk/client@2.8.0-beta.3
+  - @osdk/api@2.8.0-beta.3
+
 ## 0.9.0-beta.10
 
 ### Minor Changes

package/build/browser/new/makeExternalStore.js

@@ -42,4 +42,65 @@ export function makeExternalStore(createObservation, _name, initialValue) {
     getSnapShot
   };
 }
+
+/**
+ * Like makeExternalStore but for async subscription creation.
+ *
+ * Uses an isActive flag to handle race conditions:
+ * If cleanup runs before promise resolves, the stale subscription is
+ * immediately unsubscribed when it eventually resolves
+ */
+export function makeExternalStoreAsync(createObservation, _name, initialValue) {
+  let lastResult = initialValue;
+  function getSnapShot() {
+    return lastResult;
+  }
+  function subscribe(notifyUpdate) {
+    let isActive = true;
+    let currentSubscription;
+    const subscriptionPromise = createObservation({
+      next: payload => {
+        if (isActive) {
+          lastResult = payload;
+          notifyUpdate();
+        }
+      },
+      error: error => {
+        if (isActive) {
+          lastResult = {
+            ...(lastResult ?? {}),
+            error: error instanceof Error ? error : new Error(String(error))
+          };
+          notifyUpdate();
+        }
+      },
+      complete: () => {}
+    });
+    subscriptionPromise.then(sub => {
+      if (isActive) {
+        currentSubscription = sub;
+      } else {
+        sub.unsubscribe();
+      }
+    }).catch(error => {
+      if (isActive) {
+        lastResult = {
+          ...(lastResult ?? {}),
+          error: error instanceof Error ? error : new Error(String(error))
+        };
+        notifyUpdate();
+      }
+    });
+    return () => {
+      isActive = false;
+      if (currentSubscription) {
+        currentSubscription.unsubscribe();
+      }
+    };
+  }
+  return {
+    subscribe,
+    getSnapShot
+  };
+}
 //# sourceMappingURL=makeExternalStore.js.map

package/build/browser/new/makeExternalStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"makeExternalStore.js","names":["makeExternalStore","createObservation","_name","initialValue","lastResult","getSnapShot","subscribe","notifyUpdate","obs","next","payload","error","Error","String","complete","unsubscribe"],"sources":["makeExternalStore.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  Observer,\n  Unsubscribable,\n} from \"@osdk/client/unstable-do-not-use\";\n\nexport type Snapshot<X> =\n  | X & { error?: Error }\n  | (Partial<X> & { error?: Error })\n  | undefined;\n\nexport function makeExternalStore<X>(\n  createObservation: (callback: Observer<X | undefined>) => Unsubscribable,\n  _name?: string,\n  initialValue?: Snapshot<X>,\n): {\n  subscribe: (notifyUpdate: () => void) => () => void;\n  getSnapShot: () => Snapshot<X>;\n} {\n  let lastResult: Snapshot<X> = initialValue;\n\n  function getSnapShot(): Snapshot<X> {\n    return lastResult;\n  }\n\n  function subscribe(notifyUpdate: () => void) {\n    const obs = createObservation({\n      next: (payload) => {\n        lastResult = payload as Snapshot<X>;\n        notifyUpdate();\n      },\n      error: (error: unknown) => {\n        lastResult = {\n          ...(lastResult ?? {}),\n          error: error instanceof Error ? error : new Error(String(error)),\n        } as Snapshot<X>;\n        notifyUpdate();\n      },\n      complete: () => {},\n    });\n\n    return (): void => {\n      obs.unsubscribe();\n    };\n  }\n\n  return {\n    subscribe,\n    getSnapShot,\n  };\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA,OAAO,SAASA,iBAAiBA,CAC/BC,iBAAwE,EACxEC,KAAc,EACdC,YAA0B,EAI1B;EACA,IAAIC,UAAuB,GAAGD,YAAY;EAE1C,SAASE,WAAWA,CAAA,EAAgB;IAClC,OAAOD,UAAU;EACnB;EAuBA,OAAO;IACLE,SAAS,EAtBX,SAASA,SAASA,CAACC,YAAwB,EAAE;MAC3C,MAAMC,GAAG,GAAGP,iBAAiB,CAAC;QAC5BQ,IAAI,EAAGC,OAAO,IAAK;UACjBN,UAAU,GAAGM,OAAsB;UACnCH,YAAY,CAAC,CAAC;QAChB,CAAC;QACDI,KAAK,EAAGA,KAAc,IAAK;UACzBP,UAAU,GAAG;YACX,IAAIA,UAAU,IAAI,CAAC,CAAC,CAAC;YACrBO,KAAK,EAAEA,KAAK,YAAYC,KAAK,GAAGD,KAAK,GAAG,IAAIC,KAAK,CAACC,MAAM,CAACF,KAAK,CAAC;UACjE,CAAgB;UAChBJ,YAAY,CAAC,CAAC;QAChB,CAAC;QACDO,QAAQ,EAAEA,CAAA,KAAM,CAAC;MACnB,CAAC,CAAC;MAEF,OAAO,MAAY;QACjBN,GAAG,CAACO,WAAW,CAAC,CAAC;MACnB,CAAC;IACH,CAGW;IACTV;EACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"file":"makeExternalStore.js","names":["makeExternalStore","createObservation","_name","initialValue","lastResult","getSnapShot","subscribe","notifyUpdate","obs","next","payload","error","Error","String","complete","unsubscribe","makeExternalStoreAsync","isActive","currentSubscription","subscriptionPromise","then","sub","catch"],"sources":["makeExternalStore.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  Observer,\n  Unsubscribable,\n} from \"@osdk/client/unstable-do-not-use\";\n\nexport type Snapshot<X> =\n  | X & { error?: Error }\n  | (Partial<X> & { error?: Error })\n  | undefined;\n\nexport function makeExternalStore<X>(\n  createObservation: (callback: Observer<X | undefined>) => Unsubscribable,\n  _name?: string,\n  initialValue?: Snapshot<X>,\n): {\n  subscribe: (notifyUpdate: () => void) => () => void;\n  getSnapShot: () => Snapshot<X>;\n} {\n  let lastResult: Snapshot<X> = initialValue;\n\n  function getSnapShot(): Snapshot<X> {\n    return lastResult;\n  }\n\n  function subscribe(notifyUpdate: () => void) {\n    const obs = createObservation({\n      next: (payload) => {\n        lastResult = payload as Snapshot<X>;\n        notifyUpdate();\n      },\n      error: (error: unknown) => {\n        lastResult = {\n          ...(lastResult ?? {}),\n          error: error instanceof Error ? error : new Error(String(error)),\n        } as Snapshot<X>;\n        notifyUpdate();\n      },\n      complete: () => {},\n    });\n\n    return (): void => {\n      obs.unsubscribe();\n    };\n  }\n\n  return {\n    subscribe,\n    getSnapShot,\n  };\n}\n\n/**\n * Like makeExternalStore but for async subscription creation.\n *\n * Uses an isActive flag to handle race conditions:\n * If cleanup runs before promise resolves, the stale subscription is\n * immediately unsubscribed when it eventually resolves\n */\nexport function makeExternalStoreAsync<X>(\n  createObservation: (\n    callback: Observer<X | undefined>,\n  ) => Promise<Unsubscribable>,\n  _name?: string,\n  initialValue?: Snapshot<X>,\n): {\n  subscribe: (notifyUpdate: () => void) => () => void;\n  getSnapShot: () => Snapshot<X>;\n} {\n  let lastResult: Snapshot<X> = initialValue;\n\n  function getSnapShot(): Snapshot<X> {\n    return lastResult;\n  }\n\n  function subscribe(notifyUpdate: () => void) {\n    let isActive = true;\n    let currentSubscription: Unsubscribable | undefined;\n\n    const subscriptionPromise = createObservation({\n      next: (payload) => {\n        if (isActive) {\n          lastResult = payload as Snapshot<X>;\n          notifyUpdate();\n        }\n      },\n      error: (error: unknown) => {\n        if (isActive) {\n          lastResult = {\n            ...(lastResult ?? {}),\n            error: error instanceof Error ? error : new Error(String(error)),\n          } as Snapshot<X>;\n          notifyUpdate();\n        }\n      },\n      complete: () => {},\n    });\n\n    subscriptionPromise.then((sub) => {\n      if (isActive) {\n        currentSubscription = sub;\n      } else {\n        sub.unsubscribe();\n      }\n    }).catch((error: unknown) => {\n      if (isActive) {\n        lastResult = {\n          ...(lastResult ?? {}),\n          error: error instanceof Error ? error : new Error(String(error)),\n        } as Snapshot<X>;\n        notifyUpdate();\n      }\n    });\n\n    return (): void => {\n      isActive = false;\n      if (currentSubscription) {\n        currentSubscription.unsubscribe();\n      }\n    };\n  }\n\n  return {\n    subscribe,\n    getSnapShot,\n  };\n}\n"],"mappings":"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","ignoreList":[]}

package/build/browser/new/useLinks.js

@@ -18,6 +18,7 @@ import React from "react";
 import { makeExternalStore } from "./makeExternalStore.js";
 import { OsdkContext2 } from "./OsdkContext2.js";
 const emptyArray = Object.freeze([]);
+const emptyMap = new Map();
 
 /**
  * Hook to observe links from an object or array of objects.
@@ -37,6 +38,7 @@ export function useLinks(objects, linkName, options = {}) {
   } = options;
   const stableWhere = React.useMemo(() => otherOptions.where, [JSON.stringify(otherOptions.where)]);
   const stableOrderBy = React.useMemo(() => otherOptions.orderBy, [JSON.stringify(otherOptions.orderBy)]);
+  const stableSelect = React.useMemo(() => otherOptions.$select, [JSON.stringify(otherOptions.$select)]);
   const objectsKey = React.useMemo(() => {
     if (objects === undefined) return "";
     const arr = Array.isArray(objects) ? objects : [objects];
@@ -61,17 +63,22 @@ export function useLinks(objects, linkName, options = {}) {
       where: stableWhere,
       pageSize: otherOptions.pageSize,
       orderBy: stableOrderBy,
-      mode: otherOptions.mode
+      mode: otherOptions.mode,
+      dedupeInterval: otherOptions.dedupeIntervalMs ?? 2_000,
+      ...(stableSelect ? {
+        select: stableSelect
+      } : {})
     }, observer), `links ${linkName} for ${objectsKey}`);
-  }, [enabled, observableClient, objectsArray, objectsKey, linkName, stableWhere, otherOptions.pageSize, stableOrderBy, otherOptions.mode]);
+  }, [enabled, observableClient, objectsArray, objectsKey, linkName, stableWhere, otherOptions.pageSize, stableOrderBy, otherOptions.mode, otherOptions.dedupeIntervalMs, stableSelect]);
   const payload = React.useSyncExternalStore(subscribe, getSnapShot);
-  return {
+  return React.useMemo(() => ({
     links: payload?.resolvedList,
+    linkedObjectsBySourcePrimaryKey: payload?.linkedObjectsBySourcePrimaryKey ?? emptyMap,
     isLoading: enabled ? payload?.status === "loading" || payload?.status === "init" || !payload : false,
     isOptimistic: payload?.isOptimistic ?? false,
     error: payload?.error,
     fetchMore: payload?.hasMore ? payload?.fetchMore : undefined,
     hasMore: payload?.hasMore ?? false
-  };
+  }), [payload, enabled]);
 }
 //# sourceMappingURL=useLinks.js.map

package/build/browser/new/useLinks.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLinks.js","names":["React","makeExternalStore","OsdkContext2","emptyArray","Object","freeze","useLinks","objects","linkName","options","observableClient","useContext","enabled","otherOptions","stableWhere","useMemo","where","JSON","stringify","stableOrderBy","orderBy","objectsKey","undefined","arr","Array","isArray","map","obj","$apiName","$primaryKey","join","objectsArray","subscribe","getSnapShot","unsubscribe","observer","observeLinks","pageSize","mode","payload","useSyncExternalStore","links","resolvedList","isLoading","status","isOptimistic","error","fetchMore","hasMore"],"sources":["useLinks.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  LinkedType,\n  LinkNames,\n  ObjectOrInterfaceDefinition,\n} from \"@osdk/api\";\nimport type { Osdk, PropertyKeys, WhereClause } from \"@osdk/client\";\nimport type { ObserveLinks } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\n\nexport interface UseLinksOptions<\n  T extends ObjectOrInterfaceDefinition,\n> {\n  /**\n   * Standard OSDK Where clause for filtering linked objects\n   */\n  where?: WhereClause<T>;\n\n  /**\n   * The preferred page size for the links list.\n   */\n  pageSize?: number;\n\n  /** Sorting options for the linked objects */\n  orderBy?: {\n    [K in PropertyKeys<T>]?: \"asc\" | \"desc\";\n  };\n\n  /**\n   * The mode to use for fetching data.\n   * - undefined: Fetch data if not already in cache\n   * - \"force\": Always fetch fresh data\n   * - \"offline\": Only use cached data, don't make network requests\n   */\n  mode?: \"force\" | \"offline\";\n\n  /**\n   * Enable or disable the query.\n   *\n   * When `false`, the query will not automatically execute. It will still\n   * return any cached data, but will not fetch from the server.\n   *\n   * This is useful for:\n   * - Lazy/on-demand queries that should wait for user interaction\n   * - Dependent queries that need data from another query first\n   * - Conditional queries based on component state\n   *\n   * @default true\n   * @example\n   * // Dependent query - wait for employee data\n   * const { object: employee } = useOsdkObject(Employee, employeeId);\n   * const { links: reports } = useLinks(employee, \"reports\", {\n   *   enabled: !!employee\n   * });\n   */\n  enabled?: boolean;\n}\n\nexport interface UseLinksResult<\n  Q extends ObjectOrInterfaceDefinition,\n> {\n  links: Osdk.Instance<Q>[] | undefined;\n  isLoading: boolean;\n  error: Error | undefined;\n\n  /**\n   * Refers to whether the links are optimistic or not.\n   */\n  isOptimistic: boolean;\n\n  /**\n   * Fetch more linked objects if pagination is supported\n   */\n  fetchMore: (() => Promise<unknown>) | undefined;\n\n  /**\n   * Indicates if there are more linked objects available to fetch\n   */\n  hasMore: boolean;\n}\n\nconst emptyArray = Object.freeze([]);\n\n/**\n * Hook to observe links from an object or array of objects.\n *\n * @param objects The source object(s) to observe links from\n * @param linkName The name of the link to observe\n * @param options Optional configuration for the link query\n * @returns UseLinksResult with links data and metadata\n */\nexport function useLinks<\n  T extends ObjectOrInterfaceDefinition,\n  L extends LinkNames<T>,\n>(\n  objects: Osdk.Instance<T> | Array<Osdk.Instance<T>> | undefined,\n  linkName: L,\n  options: UseLinksOptions<LinkedType<T, L>> = {},\n): UseLinksResult<LinkedType<T, L>> {\n  const { observableClient } = React.useContext(OsdkContext2);\n\n  const { enabled = true, ...otherOptions } = options;\n\n  const stableWhere = React.useMemo(\n    () => otherOptions.where,\n    [JSON.stringify(otherOptions.where)],\n  );\n\n  const stableOrderBy = React.useMemo(\n    () => otherOptions.orderBy,\n    [JSON.stringify(otherOptions.orderBy)],\n  );\n\n  const objectsKey = React.useMemo(() => {\n    if (objects === undefined) return \"\";\n    const arr = Array.isArray(objects) ? objects : [objects];\n    return arr.map(obj => `${obj.$apiName}:${obj.$primaryKey}`).join(\",\");\n  }, [objects]);\n\n  // Convert single object to array for consistent handling\n  const objectsArray: ReadonlyArray<Osdk.Instance<T>> = React.useMemo(() => {\n    return objects === undefined\n      ? emptyArray\n      : Array.isArray(objects)\n      ? objects\n      : [objects];\n  }, [objectsKey, objects]);\n\n  const { subscribe, getSnapShot } = React.useMemo(\n    () => {\n      if (!enabled) {\n        return makeExternalStore<ObserveLinks.CallbackArgs<T>>(\n          () => ({ unsubscribe: () => {} }),\n          `links ${linkName} for ${objectsKey} [DISABLED]`,\n        );\n      }\n      return makeExternalStore<ObserveLinks.CallbackArgs<T>>(\n        (observer) =>\n          observableClient.observeLinks(\n            objectsArray,\n            linkName,\n            {\n              linkName,\n              where: stableWhere,\n              pageSize: otherOptions.pageSize,\n              orderBy: stableOrderBy,\n              mode: otherOptions.mode,\n            },\n            observer,\n          ),\n        `links ${linkName} for ${objectsKey}`,\n      );\n    },\n    [\n      enabled,\n      observableClient,\n      objectsArray,\n      objectsKey,\n      linkName,\n      stableWhere,\n      otherOptions.pageSize,\n      stableOrderBy,\n      otherOptions.mode,\n    ],\n  );\n\n  const payload = React.useSyncExternalStore(\n    subscribe,\n    getSnapShot,\n  );\n\n  return {\n    links: payload?.resolvedList,\n    isLoading: enabled\n      ? (payload?.status === \"loading\" || payload?.status === \"init\"\n        || !payload)\n      : false,\n    isOptimistic: payload?.isOptimistic ?? false,\n    error: payload?.error,\n    fetchMore: payload?.hasMore ? payload?.fetchMore : undefined,\n    hasMore: payload?.hasMore ?? false,\n  };\n}\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"useLinks.js","names":["React","makeExternalStore","OsdkContext2","emptyArray","Object","freeze","emptyMap","Map","useLinks","objects","linkName","options","observableClient","useContext","enabled","otherOptions","stableWhere","useMemo","where","JSON","stringify","stableOrderBy","orderBy","stableSelect","$select","objectsKey","undefined","arr","Array","isArray","map","obj","$apiName","$primaryKey","join","objectsArray","subscribe","getSnapShot","unsubscribe","observer","observeLinks","pageSize","mode","dedupeInterval","dedupeIntervalMs","select","payload","useSyncExternalStore","links","resolvedList","linkedObjectsBySourcePrimaryKey","isLoading","status","isOptimistic","error","fetchMore","hasMore"],"sources":["useLinks.ts"],"sourcesContent":["/*\n * Copyright 2025 Palantir Technologies, Inc. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  LinkedType,\n  LinkNames,\n  ObjectOrInterfaceDefinition,\n} from \"@osdk/api\";\nimport type { Osdk, PropertyKeys, WhereClause } from \"@osdk/client\";\nimport type { ObserveLinks } from \"@osdk/client/unstable-do-not-use\";\nimport React from \"react\";\nimport { makeExternalStore } from \"./makeExternalStore.js\";\nimport { OsdkContext2 } from \"./OsdkContext2.js\";\n\nexport interface UseLinksOptions<\n  T extends ObjectOrInterfaceDefinition,\n> {\n  /**\n   * Standard OSDK Where clause for filtering linked objects\n   */\n  where?: WhereClause<T>;\n\n  /**\n   * The preferred page size for the links list.\n   */\n  pageSize?: number;\n\n  /** Sorting options for the linked objects */\n  orderBy?: {\n    [K in PropertyKeys<T>]?: \"asc\" | \"desc\";\n  };\n\n  /**\n   * Restrict which properties are returned for each linked object.\n   * When provided, only the specified properties will be fetched,\n   * reducing payload sizes for list views.\n   */\n  $select?: readonly PropertyKeys<T>[];\n\n  /**\n   * The mode to use for fetching data.\n   * - undefined: Fetch data if not already in cache\n   * - \"force\": Always fetch fresh data\n   * - \"offline\": Only use cached data, don't make network requests\n   */\n  mode?: \"force\" | \"offline\";\n\n  /**\n   * The number of milliseconds to wait after the last observed link change.\n   *\n   * Two uses of `useLinks` with the same parameters will only trigger one\n   * network request if the second is within `dedupeIntervalMs`.\n   */\n  dedupeIntervalMs?: number;\n\n  /**\n   * Enable or disable the query.\n   *\n   * When `false`, the query will not automatically execute. It will still\n   * return any cached data, but will not fetch from the server.\n   *\n   * This is useful for:\n   * - Lazy/on-demand queries that should wait for user interaction\n   * - Dependent queries that need data from another query first\n   * - Conditional queries based on component state\n   *\n   * @default true\n   * @example\n   * // Dependent query - wait for employee data\n   * const { object: employee } = useOsdkObject(Employee, employeeId);\n   * const { links: reports } = useLinks(employee, \"reports\", {\n   *   enabled: !!employee\n   * });\n   */\n  enabled?: boolean;\n}\n\nexport interface UseLinksResult<\n  Q extends ObjectOrInterfaceDefinition,\n> {\n  links: Osdk.Instance<Q>[] | undefined;\n\n  /**\n   * Maps each source object's primary key to its linked object instances.\n   * Useful when observing links from multiple source objects to determine\n   * which source links to which targets.\n   */\n  linkedObjectsBySourcePrimaryKey: ReadonlyMap<\n    string | number,\n    ReadonlyArray<Osdk.Instance<Q>>\n  >;\n\n  isLoading: boolean;\n  error: Error | undefined;\n\n  /**\n   * Refers to whether the links are optimistic or not.\n   */\n  isOptimistic: boolean;\n\n  /**\n   * Fetch more linked objects if pagination is supported\n   */\n  fetchMore: (() => Promise<unknown>) | undefined;\n\n  /**\n   * Indicates if there are more linked objects available to fetch\n   */\n  hasMore: boolean;\n}\n\nconst emptyArray = Object.freeze([]);\nconst emptyMap: ReadonlyMap<string | number, ReadonlyArray<never>> = new Map();\n\n/**\n * Hook to observe links from an object or array of objects.\n *\n * @param objects The source object(s) to observe links from\n * @param linkName The name of the link to observe\n * @param options Optional configuration for the link query\n * @returns UseLinksResult with links data and metadata\n */\nexport function useLinks<\n  T extends ObjectOrInterfaceDefinition,\n  L extends LinkNames<T>,\n>(\n  objects: Osdk.Instance<T> | Array<Osdk.Instance<T>> | undefined,\n  linkName: L,\n  options: UseLinksOptions<LinkedType<T, L>> = {},\n): UseLinksResult<LinkedType<T, L>> {\n  const { observableClient } = React.useContext(OsdkContext2);\n\n  const { enabled = true, ...otherOptions } = options;\n\n  const stableWhere = React.useMemo(\n    () => otherOptions.where,\n    [JSON.stringify(otherOptions.where)],\n  );\n\n  const stableOrderBy = React.useMemo(\n    () => otherOptions.orderBy,\n    [JSON.stringify(otherOptions.orderBy)],\n  );\n\n  const stableSelect = React.useMemo(\n    () => otherOptions.$select,\n    [JSON.stringify(otherOptions.$select)],\n  );\n\n  const objectsKey = React.useMemo(() => {\n    if (objects === undefined) return \"\";\n    const arr = Array.isArray(objects) ? objects : [objects];\n    return arr.map(obj => `${obj.$apiName}:${obj.$primaryKey}`).join(\",\");\n  }, [objects]);\n\n  // Convert single object to array for consistent handling\n  const objectsArray: ReadonlyArray<Osdk.Instance<T>> = React.useMemo(() => {\n    return objects === undefined\n      ? emptyArray\n      : Array.isArray(objects)\n      ? objects\n      : [objects];\n  }, [objectsKey, objects]);\n\n  const { subscribe, getSnapShot } = React.useMemo(\n    () => {\n      if (!enabled) {\n        return makeExternalStore<ObserveLinks.CallbackArgs<T>>(\n          () => ({ unsubscribe: () => {} }),\n          `links ${linkName} for ${objectsKey} [DISABLED]`,\n        );\n      }\n      return makeExternalStore<ObserveLinks.CallbackArgs<T>>(\n        (observer) =>\n          observableClient.observeLinks(\n            objectsArray,\n            linkName,\n            {\n              linkName,\n              where: stableWhere,\n              pageSize: otherOptions.pageSize,\n              orderBy: stableOrderBy,\n              mode: otherOptions.mode,\n              dedupeInterval: otherOptions.dedupeIntervalMs ?? 2_000,\n              ...(stableSelect ? { select: stableSelect } : {}),\n            },\n            observer,\n          ),\n        `links ${linkName} for ${objectsKey}`,\n      );\n    },\n    [\n      enabled,\n      observableClient,\n      objectsArray,\n      objectsKey,\n      linkName,\n      stableWhere,\n      otherOptions.pageSize,\n      stableOrderBy,\n      otherOptions.mode,\n      otherOptions.dedupeIntervalMs,\n      stableSelect,\n    ],\n  );\n\n  const payload = React.useSyncExternalStore(\n    subscribe,\n    getSnapShot,\n  );\n\n  return React.useMemo(() => ({\n    links: payload?.resolvedList,\n    linkedObjectsBySourcePrimaryKey: payload?.linkedObjectsBySourcePrimaryKey\n      ?? emptyMap,\n    isLoading: enabled\n      ? (payload?.status === \"loading\" || payload?.status === \"init\"\n        || !payload)\n      : false,\n    isOptimistic: payload?.isOptimistic ?? false,\n    error: payload?.error,\n    fetchMore: payload?.hasMore ? payload?.fetchMore : undefined,\n    hasMore: payload?.hasMore ?? false,\n  }), [payload, enabled]);\n}\n"],"mappings":"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","ignoreList":[]}