@osdk/react 0.9.3 → 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,63 +1,136 @@
 # @osdkkit/react
 
-## 0.9.3
+## 0.10.0-beta.10
+
+### Minor Changes
+
+- dbbfb6f: Add experimental ActionForm component with field renderers, form state hook, and tests
 
 ### Patch Changes
 
-- 679ac34: Allow interface object sets in useObjectSet
+- 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
 
-## 0.9.2
+### Minor Changes
+
+- c40444b: Add linkedObjectsBySourcePrimaryKey to link observation responses
 
 ### Patch Changes
 
-- 16c9987: Preserve object set data between loads
+- 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
 
-## 0.9.1
+- 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
 
-- 17d4115: add interface support to useOsdkObject
+- Updated dependencies [09e5659]
+- Updated dependencies [2ebe62c]
+  - @osdk/client@2.8.0-beta.16
+  - @osdk/api@2.8.0-beta.16
 
-## 0.9.0
+## 0.10.0-beta.7
 
 ### Minor Changes
 
-- 6cfe14a: add new useOsdkFunction hook and supporting client infrastructure
-- 43d342e: Fix fetchMore in useObjectSet and useLinks
+- 9156827: Preserve object set data between loads
+- 35f2f1a: Add Media inputs/outputs for Queries
+- 71e28ef: Allow interface object sets in useObjectSet
 
 ### Patch Changes
 
-- 322c5bc: Simulated release
-- ddef59f: update docs
-- adca853: fix fetchMore behavior
-- acf6331: Include AGENTS.md and docs directory in published package for improved AI assistant support
-- 74e3ba7: Preserve aggregate option literal types in useOsdkAggregation using const type parameter
-- a6d4d49: fix useLinks stabilization
-- ba3159c: improve loading logic to make loading state consistent / reduce flashing
-- eb3a556: wire totalCount for osdk react hooks
-- a23784c: wire action edit response types through for useOsdkAction
-- ecd18e2: fix pivotTo with where usage
-- 31cd835: Revert beta changes
-- 38d5958: fix order by via key stabilization
-- 56ba08f: support interfaces for osdk react hooks
-- 0dbd0d0: add useOsdkObjects rid querying support
-- 0395d4b: Pins Foundry core and admin packages to monorepo version
-- 0b2cd91: fix SimplePropertyDef issue, wire RDPs through, update names
-- db28747: rdp typing improvements
+- 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
 
-## 0.9.0-rc.11
+### 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
 
-- a6d4d49: fix useLinks stabilization
-- eb3a556: wire totalCount for osdk react hooks
-- 31cd835: Revert beta changes
-- 0dbd0d0: add useOsdkObjects rid querying support
-- Updated dependencies [eb3a556]
-- Updated dependencies [31cd835]
-- Updated dependencies [0dbd0d0]
-  - @osdk/client@2.7.0-rc.15
-  - @osdk/api@2.7.0-rc.15
+- 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
 
@@ -177,21 +250,6 @@
   - @osdk/client@2.7.0-beta.2
   - @osdk/api@2.7.0-beta.2
 
-## 0.8.0
-
-### Patch Changes
-
-- 322c5bc: Simulated release
-- 13f229d: preserve object set data on rid change
-- c5a3815: Add new auto fetch more behavior to useOsdkObjects
-- 4b13323: update OSDK toolkit docs
-- 9961f06: fix order by via key stabilization
-- e7bf02a: Add RDP support to React toolkit
-- af4f3bf: Remove the following features for RC:
-  - Property formatting
-  - Branching
-  - Constant RDPs
-
 ## 0.8.0-beta.5
 
 ### 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