@osdk/react 0.9.0-beta.6 → 0.9.0-beta.8

package/build/esm/public/experimental.js.map

@@ -1 +1 @@
-{"version":3,"file":"experimental.js","names":["OsdkProvider2","useCurrentFoundryUser","useFoundryUser","useFoundryUsersList","useLinks","useObjectSet","useOsdkAction","useOsdkAggregation","useOsdkObject","useOsdkObjects","useOsdkClient","useOsdkMetadata","useDebouncedCallback"],"sources":["experimental.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\nexport { OsdkProvider2 } from \"../new/OsdkProvider2.js\";\nexport { useCurrentFoundryUser } from \"../new/platform-apis/admin/useCurrentFoundryUser.js\";\nexport { useFoundryUser } from \"../new/platform-apis/admin/useFoundryUser.js\";\nexport { useFoundryUsersList } from \"../new/platform-apis/admin/useFoundryUsersList.js\";\nexport { useLinks } from \"../new/useLinks.js\";\nexport { useObjectSet } from \"../new/useObjectSet.js\";\nexport { useOsdkAction } from \"../new/useOsdkAction.js\";\nexport type { UseOsdkAggregationResult } from \"../new/useOsdkAggregation.js\";\nexport { useOsdkAggregation } from \"../new/useOsdkAggregation.js\";\nexport { useOsdkObject } from \"../new/useOsdkObject.js\";\nexport type { UseOsdkListResult } from \"../new/useOsdkObjects.js\";\nexport { useOsdkObjects } from \"../new/useOsdkObjects.js\";\nexport { useOsdkClient } from \"../useOsdkClient.js\";\nexport { useOsdkMetadata } from \"../useOsdkMetadata.js\";\nexport type { UseOsdkMetadataResult } from \"../useOsdkMetadata.js\";\nexport { useDebouncedCallback } from \"../utils/useDebouncedCallback.js\";\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,aAAa,QAAQ,yBAAyB;AACvD,SAASC,qBAAqB,QAAQ,qDAAqD;AAC3F,SAASC,cAAc,QAAQ,8CAA8C;AAC7E,SAASC,mBAAmB,QAAQ,mDAAmD;AACvF,SAASC,QAAQ,QAAQ,oBAAoB;AAC7C,SAASC,YAAY,QAAQ,wBAAwB;AACrD,SAASC,aAAa,QAAQ,yBAAyB;AAEvD,SAASC,kBAAkB,QAAQ,8BAA8B;AACjE,SAASC,aAAa,QAAQ,yBAAyB;AAEvD,SAASC,cAAc,QAAQ,0BAA0B;AACzD,SAASC,aAAa,QAAQ,qBAAqB;AACnD,SAASC,eAAe,QAAQ,uBAAuB;AAEvD,SAASC,oBAAoB,QAAQ,kCAAkC","ignoreList":[]}
+{"version":3,"file":"experimental.js","names":["OsdkProvider2","useCurrentFoundryUser","useFoundryUser","useFoundryUsersList","useLinks","useObjectSet","useOsdkAction","useOsdkAggregation","useOsdkFunction","useOsdkObject","useOsdkObjects","useOsdkClient","useOsdkMetadata","useDebouncedCallback"],"sources":["experimental.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\nexport { OsdkProvider2 } from \"../new/OsdkProvider2.js\";\nexport { useCurrentFoundryUser } from \"../new/platform-apis/admin/useCurrentFoundryUser.js\";\nexport { useFoundryUser } from \"../new/platform-apis/admin/useFoundryUser.js\";\nexport { useFoundryUsersList } from \"../new/platform-apis/admin/useFoundryUsersList.js\";\nexport { useLinks } from \"../new/useLinks.js\";\nexport { useObjectSet } from \"../new/useObjectSet.js\";\nexport { useOsdkAction } from \"../new/useOsdkAction.js\";\nexport type { UseOsdkAggregationResult } from \"../new/useOsdkAggregation.js\";\nexport { useOsdkAggregation } from \"../new/useOsdkAggregation.js\";\nexport type {\n  UseOsdkFunctionOptions,\n  UseOsdkFunctionResult,\n} from \"../new/useOsdkFunction.js\";\nexport { useOsdkFunction } from \"../new/useOsdkFunction.js\";\nexport { useOsdkObject } from \"../new/useOsdkObject.js\";\nexport type { UseOsdkListResult } from \"../new/useOsdkObjects.js\";\nexport { useOsdkObjects } from \"../new/useOsdkObjects.js\";\nexport { useOsdkClient } from \"../useOsdkClient.js\";\nexport { useOsdkMetadata } from \"../useOsdkMetadata.js\";\nexport type { UseOsdkMetadataResult } from \"../useOsdkMetadata.js\";\nexport { useDebouncedCallback } from \"../utils/useDebouncedCallback.js\";\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,aAAa,QAAQ,yBAAyB;AACvD,SAASC,qBAAqB,QAAQ,qDAAqD;AAC3F,SAASC,cAAc,QAAQ,8CAA8C;AAC7E,SAASC,mBAAmB,QAAQ,mDAAmD;AACvF,SAASC,QAAQ,QAAQ,oBAAoB;AAC7C,SAASC,YAAY,QAAQ,wBAAwB;AACrD,SAASC,aAAa,QAAQ,yBAAyB;AAEvD,SAASC,kBAAkB,QAAQ,8BAA8B;AAKjE,SAASC,eAAe,QAAQ,2BAA2B;AAC3D,SAASC,aAAa,QAAQ,yBAAyB;AAEvD,SAASC,cAAc,QAAQ,0BAA0B;AACzD,SAASC,aAAa,QAAQ,qBAAqB;AACnD,SAASC,eAAe,QAAQ,uBAAuB;AAEvD,SAASC,oBAAoB,QAAQ,kCAAkC","ignoreList":[]}

package/build/types/new/useLinks.d.ts

@@ -1,6 +1,6 @@
-import type { LinkedType, LinkNames } from "@osdk/api";
-import type { InterfaceDefinition, ObjectTypeDefinition, Osdk, PropertyKeys, WhereClause } from "@osdk/client";
-export interface UseLinksOptions<T extends ObjectTypeDefinition | InterfaceDefinition> {
+import type { LinkedType, LinkNames, ObjectOrInterfaceDefinition } from "@osdk/api";
+import type { Osdk, PropertyKeys, WhereClause } from "@osdk/client";
+export interface UseLinksOptions<T extends ObjectOrInterfaceDefinition> {
 	/**
 	* Standard OSDK Where clause for filtering linked objects
 	*/
@@ -39,7 +39,7 @@ export interface UseLinksOptions<T extends ObjectTypeDefinition | InterfaceDefin
 	*/
 	enabled?: boolean;
 }
-export interface UseLinksResult<Q extends ObjectTypeDefinition | InterfaceDefinition> {
+export interface UseLinksResult<Q extends ObjectOrInterfaceDefinition> {
 	links: Osdk.Instance<Q>[] | undefined;
 	isLoading: boolean;
 	error: Error | undefined;
@@ -65,6 +65,6 @@ export interface UseLinksResult<Q extends ObjectTypeDefinition | InterfaceDefini
 * @returns UseLinksResult with links data and metadata
 */
 export declare function useLinks<
-	T extends ObjectTypeDefinition,
+	T extends ObjectOrInterfaceDefinition,
 	L extends LinkNames<T>
 >(objects: Osdk.Instance<T> | Array<Osdk.Instance<T>> | undefined, linkName: L, options?: UseLinksOptions<LinkedType<T, L>>): UseLinksResult<LinkedType<T, L>>;

package/build/types/new/useLinks.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cAAc,YAAY,iBAAiB,WAAY;AACvD,cACE,qBACA,sBACA,MACA,cACA,mBACK,cAAe;AAMtB,iBAAiB,gBACf,UAAU,uBAAuB,qBACjC;;;;CAIA,QAAQ,YAAY;;;;CAKpB;;CAGA,aACG,KAAK,aAAa,OAAM,QAAQ;;;;;;;CASnC,OAAO,UAAU;;;;;;;;;;;;;;;;;;;;CAqBjB;AACD;AAED,iBAAiB,eACf,UAAU,uBAAuB,qBACjC;CACA,OAAO,KAAK,SAAS;CACrB;CACA,OAAO;;;;CAKP;;;;CAKA,kBAAkB;;;;CAKlB;AACD;;;;;;;;;AAYD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,UAAU;EAEpBA,SAAS,KAAK,SAAS,KAAK,MAAM,KAAK,SAAS,iBAChDC,UAAU,GACVC,UAAS,gBAAgB,WAAW,GAAG,MACtC,eAAe,WAAW,GAAG","names":["objects: Osdk.Instance<T> | Array<Osdk.Instance<T>> | undefined","linkName: L","options: UseLinksOptions<LinkedType<T, L>>"],"sources":["../../../src/new/useLinks.ts"],"version":3,"file":"useLinks.d.ts"}
+{"mappings":"AAgBA,cACE,YACA,WACA,mCACK,WAAY;AACnB,cAAc,MAAM,cAAc,mBAAmB,cAAe;AAMpE,iBAAiB,gBACf,UAAU,6BACV;;;;CAIA,QAAQ,YAAY;;;;CAKpB;;CAGA,aACG,KAAK,aAAa,OAAM,QAAQ;;;;;;;CASnC,OAAO,UAAU;;;;;;;;;;;;;;;;;;;;CAqBjB;AACD;AAED,iBAAiB,eACf,UAAU,6BACV;CACA,OAAO,KAAK,SAAS;CACrB;CACA,OAAO;;;;CAKP;;;;CAKA,kBAAkB;;;;CAKlB;AACD;;;;;;;;;AAYD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,UAAU;EAEpBA,SAAS,KAAK,SAAS,KAAK,MAAM,KAAK,SAAS,iBAChDC,UAAU,GACVC,UAAS,gBAAgB,WAAW,GAAG,MACtC,eAAe,WAAW,GAAG","names":["objects: Osdk.Instance<T> | Array<Osdk.Instance<T>> | undefined","linkName: L","options: UseLinksOptions<LinkedType<T, L>>"],"sources":["../../../src/new/useLinks.ts"],"version":3,"file":"useLinks.d.ts"}

package/build/types/new/useOsdkAggregation.d.ts

@@ -1,8 +1,7 @@
-import type { AggregateOpts, AggregationsResults, DerivedProperty, WhereClause } from "@osdk/api";
-import type { ObjectTypeDefinition } from "@osdk/client";
+import type { AggregateOpts, AggregationsResults, DerivedProperty, ObjectOrInterfaceDefinition, WhereClause } from "@osdk/api";
 import type { InferRdpTypes } from "./types.js";
 export interface UseOsdkAggregationOptions<
-	T extends ObjectTypeDefinition,
+	T extends ObjectOrInterfaceDefinition,
 	A extends AggregateOpts<T>,
 	WithProps extends DerivedProperty.Clause<T> | undefined = undefined
 > {
@@ -28,7 +27,7 @@ export interface UseOsdkAggregationOptions<
 	dedupeIntervalMs?: number;
 }
 export interface UseOsdkAggregationResult<
-	T extends ObjectTypeDefinition,
+	T extends ObjectOrInterfaceDefinition,
 	A extends AggregateOpts<T>
 > {
 	data: AggregationsResults<T, A> | undefined;
@@ -61,7 +60,7 @@ export interface UseOsdkAggregationResult<
 * ```
 */
 export declare function useOsdkAggregation<
-	Q extends ObjectTypeDefinition,
-	A extends AggregateOpts<Q>,
+	Q extends ObjectOrInterfaceDefinition,
+	const A extends AggregateOpts<Q>,
 	WP extends DerivedProperty.Clause<Q> | undefined = undefined
 >(type: Q, { where, withProperties, aggregate, dedupeIntervalMs }: UseOsdkAggregationOptions<Q, A, WP>): UseOsdkAggregationResult<Q, A>;

package/build/types/new/useOsdkAggregation.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cACE,eACA,qBACA,iBACA,mBACK,WAAY;AACnB,cAAc,4BAA4B,cAAe;AAKzD,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;CACxB,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;;CAMxC,iBAAiB;;;;CAKjB,WAAW;;;;;;;CAQX;AACD;AAED,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;EACxB;CACA,MAAM,oBAAoB,GAAG;CAC7B;CACA,OAAO;CACP;AACD;;;;;;;;;;;;;;;;;;;;;;;;;AAgCD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,cAAc;CACxB,WAAW,gBAAgB,OAAO;EAElCA,MAAM,GACN,EACE,OACA,gBACA,WACA,kBACoC,EAAnC,0BAA0B,GAAG,GAAG,MAClC,yBAAyB,GAAG","names":["type: Q"],"sources":["../../../src/new/useOsdkAggregation.ts"],"version":3,"file":"useOsdkAggregation.d.ts"}
+{"mappings":"AAgBA,cACE,eACA,qBACA,iBACA,6BACA,mBACK,WAAY;AAKnB,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;CACxB,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;;CAMxC,iBAAiB;;;;CAKjB,WAAW;;;;;;;CAQX;AACD;AAED,iBAAiB;CACf,UAAU;CACV,UAAU,cAAc;EACxB;CACA,MAAM,oBAAoB,GAAG;CAC7B;CACA,OAAO;CACP;AACD;;;;;;;;;;;;;;;;;;;;;;;;;AAgCD,OAAO,iBAAS;CACd,UAAU;OACJ,UAAU,cAAc;CAC9B,WAAW,gBAAgB,OAAO;EAElCA,MAAM,GACN,EACE,OACA,gBACA,WACA,kBACoC,EAAnC,0BAA0B,GAAG,GAAG,MAClC,yBAAyB,GAAG","names":["type: Q"],"sources":["../../../src/new/useOsdkAggregation.ts"],"version":3,"file":"useOsdkAggregation.d.ts"}

package/build/types/new/useOsdkFunction.d.ts

@@ -0,0 +1,112 @@
+import type { CompileTimeMetadata, ObjectTypeDefinition, Osdk, QueryDefinition } from "@osdk/api";
+import type { QueryParameterType, QueryReturnType } from "@osdk/client/unstable-do-not-use";
+export interface UseOsdkFunctionOptions<Q extends QueryDefinition<unknown>> {
+	/**
+	* Parameters to pass to the function.
+	* Must include all required parameters; optional parameters can be omitted.
+	*/
+	params?: CompileTimeMetadata<Q>["parameters"] extends Record<string, never> ? undefined : QueryParameterType<CompileTimeMetadata<Q>["parameters"]>;
+	/**
+	* Object types this function depends on.
+	* When actions modify objects of these types, the function will automatically refetch.
+	*
+	* @example
+	* ```tsx
+	* // Refetch when any Employee object changes
+	* { dependsOn: [Employee] }
+	* ```
+	*/
+	dependsOn?: Array<ObjectTypeDefinition | string>;
+	/**
+	* Specific object instances this function depends on.
+	* When any of these specific objects change, the function will refetch.
+	* More fine-grained than dependsOn for precise invalidation control.
+	*
+	* @example
+	* ```tsx
+	* // Refetch when this specific employee changes
+	* { dependsOnObjects: [employee] }
+	* ```
+	*/
+	dependsOnObjects?: Array<Osdk.Instance<ObjectTypeDefinition>>;
+	/**
+	* The number of milliseconds to dedupe identical function calls.
+	* Two calls with the same function and params will share results
+	* if the second call is within this interval of the first.
+	* @default 2000
+	*/
+	dedupeIntervalMs?: number;
+	/**
+	* Whether to enable the query. When false, the query will not execute.
+	* Useful for:
+	* - Dependent queries that need to wait for other data
+	* - Conditional queries based on component state
+	*
+	* @default true
+	* @example
+	* // Dependent query - wait for required data
+	* const { data: employee } = useOsdkObject(Employee, employeeId);
+	* const { data: report } = useOsdkFunction(getEmployeeReport, {
+	*   params: { employeeId: employee?.$primaryKey },
+	*   enabled: !!employee
+	* });
+	*/
+	enabled?: boolean;
+}
+export interface UseOsdkFunctionResult<Q extends QueryDefinition<unknown>> {
+	/**
+	* The function result, or undefined if not yet loaded or on error.
+	*/
+	data: QueryReturnType<CompileTimeMetadata<Q>["output"]> | undefined;
+	/**
+	* True while the function is executing.
+	*/
+	isLoading: boolean;
+	/**
+	* Error if the function execution failed.
+	*/
+	error: Error | undefined;
+	/**
+	* Timestamp (ms since epoch) of when the result was last fetched.
+	*/
+	lastUpdated: number;
+	/**
+	* Manually refetch the function.
+	* Useful for "pull to refresh" or retry patterns.
+	*/
+	refetch: () => void;
+}
+/**
+* React hook for executing and observing OSDK functions.
+*
+* Provides automatic caching, deduplication, and reactive updates for function calls.
+* Functions are automatically re-fetched when dependencies change (configured via options).
+*
+* @param queryDef - The QueryDefinition to execute
+* @param options - Configuration options for the function call
+* @returns Object containing result, loading state, error, and refetch function
+*
+* @example Basic usage
+* ```tsx
+* const { data, isLoading, error } = useOsdkFunction(getEmployeeStats, {
+*   params: { departmentId: "engineering" }
+* });
+* ```
+*
+* @example With dependency tracking
+* ```tsx
+* const { data, refetch } = useOsdkFunction(calculateMetrics, {
+*   params: { startDate, endDate },
+*   dependsOn: [Employee, Project],
+* });
+* ```
+*
+* @example With specific object dependencies
+* ```tsx
+* const { data } = useOsdkFunction(getEmployeeReport, {
+*   params: { employeeId: employee.$primaryKey },
+*   dependsOnObjects: [employee],
+* });
+* ```
+*/
+export declare function useOsdkFunction<Q extends QueryDefinition<unknown>>(queryDef: Q, options?: UseOsdkFunctionOptions<Q>): UseOsdkFunctionResult<Q>;

package/build/types/new/useOsdkFunction.d.ts.map

@@ -0,0 +1 @@
+{"mappings":"AAgBA,cACE,qBACA,sBACA,MACA,uBACK,WAAY;AACnB,cAEE,oBACA,uBACK,kCAAmC;AAK1C,iBAAiB,uBAAuB,UAAU,0BAA0B;;;;;CAK1E,SAAS,oBAAoB,GAAG,sBAAsB,oCAElD,mBAAmB,oBAAoB,GAAG;;;;;;;;;;;CAY9C,YAAY,MAAM;;;;;;;;;;;;CAalB,mBAAmB,MAAM,KAAK,SAAS;;;;;;;CAQvC;;;;;;;;;;;;;;;;CAiBA;AACD;AAED,iBAAiB,sBAAsB,UAAU,0BAA0B;;;;CAIzE,MAAM,gBAAgB,oBAAoB,GAAG;;;;CAK7C;;;;CAKA,OAAO;;;;CAKP;;;;;CAMA;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCD,OAAO,iBAAS,gBAAgB,UAAU,0BACxCA,UAAU,GACVC,UAAS,uBAAuB,KAC/B,sBAAsB","names":["queryDef: Q","options: UseOsdkFunctionOptions<Q>"],"sources":["../../../src/new/useOsdkFunction.ts"],"version":3,"file":"useOsdkFunction.d.ts"}

package/build/types/new/useOsdkObjects.d.ts

@@ -1,7 +1,7 @@
-import type { DerivedProperty, InterfaceDefinition, LinkedType, LinkNames, ObjectTypeDefinition, Osdk, PropertyKeys, SimplePropertyDef, WhereClause } from "@osdk/api";
+import type { DerivedProperty, LinkedType, LinkNames, ObjectOrInterfaceDefinition, Osdk, PropertyKeys, SimplePropertyDef, WhereClause } from "@osdk/api";
 import type { InferRdpTypes } from "./types.js";
 export interface UseOsdkObjectsOptions<
-	T extends ObjectTypeDefinition | InterfaceDefinition,
+	T extends ObjectOrInterfaceDefinition,
 	WithProps extends DerivedProperty.Clause<T> | undefined = undefined
 > {
 	/**
@@ -107,7 +107,7 @@ export interface UseOsdkObjectsOptions<
 	enabled?: boolean;
 }
 export interface UseOsdkListResult<
-	T extends ObjectTypeDefinition | InterfaceDefinition,
+	T extends ObjectOrInterfaceDefinition,
 	RDPs extends Record<string, SimplePropertyDef> = {}
 > {
 	fetchMore: (() => Promise<void>) | undefined;
@@ -124,12 +124,12 @@ export interface UseOsdkListResult<
 	isOptimistic: boolean;
 }
 export declare function useOsdkObjects<
-	Q extends ObjectTypeDefinition,
+	Q extends ObjectOrInterfaceDefinition,
 	L extends LinkNames<Q>
 >(type: Q, options: UseOsdkObjectsOptions<Q> & {
 	pivotTo: L
 }): UseOsdkListResult<LinkedType<Q, L>>;
 export declare function useOsdkObjects<
-	Q extends ObjectTypeDefinition | InterfaceDefinition,
+	Q extends ObjectOrInterfaceDefinition,
 	WP extends DerivedProperty.Clause<Q> | undefined
 >(type: Q, options?: UseOsdkObjectsOptions<Q, WP>): UseOsdkListResult<Q, InferRdpTypes<Q, WP>>;

package/build/types/new/useOsdkObjects.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,cACE,iBACA,qBACA,YACA,WACA,sBACA,MACA,cACA,mBACA,mBACK,WAAY;AAKnB,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU,uBAAuB;CACjC,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;CAKxC;;CAGA,aACG,KAAK,aAAa,OAAM,QAAQ;;;;;CAOnC,iBAAiB;;;;;;CAOjB,gBAAgB,MAAM;EACpB,OAAO,YAAY,GAAG,cAAc,GAAG;CACxC;;;;;CAMD,UAAU,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CA0BpB;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BA;CAEA;;;;;;;;;;;;;;;;;;;;;CAsBA;AACD;AAED,iBAAiB;CACf,UAAU,uBAAuB;CACjC,aAAa,eAAe,qBAAqB,CAAE;EACnD;CACA,kBAAkB;CAClB,MACI,KAAK,SAAS,GAAG,sBAAsB,aAAa,IAAI;CAE5D;CAEA,OAAO;;;;;;;;CASP;AACD;AAQD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,UAAU;EAEpBA,MAAM,GACNC,SAAS,sBAAsB,KAAK;CAAE,SAAS;AAAG,IACjD,kBAAkB,WAAW,GAAG;AAEnC,OAAO,iBAAS;CACd,UAAU,uBAAuB;CACjC,WAAW,gBAAgB,OAAO;EAElCD,MAAM,GACNE,UAAU,sBAAsB,GAAG,MAClC,kBAAkB,GAAG,cAAc,GAAG","names":["type: Q","options: UseOsdkObjectsOptions<Q> & { pivotTo: L }","options?: UseOsdkObjectsOptions<Q, WP>"],"sources":["../../../src/new/useOsdkObjects.ts"],"version":3,"file":"useOsdkObjects.d.ts"}
+{"mappings":"AAgBA,cACE,iBACA,YACA,WACA,6BACA,MACA,cACA,mBACA,mBACK,WAAY;AAKnB,cAAc,qBAAqB,YAAa;AAEhD,iBAAiB;CACf,UAAU;CACV,kBAAkB,gBAAgB,OAAO;EACzC;;;;CAIA,QAAQ,YAAY,GAAG,cAAc,GAAG;;;;CAKxC;;CAGA,aACG,KAAK,aAAa,OAAM,QAAQ;;;;;CAOnC,iBAAiB;;;;;;CAOjB,gBAAgB,MAAM;EACpB,OAAO,YAAY,GAAG,cAAc,GAAG;CACxC;;;;;CAMD,UAAU,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;CA0BpB;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BA;CAEA;;;;;;;;;;;;;;;;;;;;;CAsBA;AACD;AAED,iBAAiB;CACf,UAAU;CACV,aAAa,eAAe,qBAAqB,CAAE;EACnD;CACA,kBAAkB;CAClB,MACI,KAAK,SAAS,GAAG,sBAAsB,aAAa,IAAI;CAE5D;CAEA,OAAO;;;;;;;;CASP;AACD;AAQD,OAAO,iBAAS;CACd,UAAU;CACV,UAAU,UAAU;EAEpBA,MAAM,GACNC,SAAS,sBAAsB,KAAK;CAAE,SAAS;AAAG,IACjD,kBAAkB,WAAW,GAAG;AAEnC,OAAO,iBAAS;CACd,UAAU;CACV,WAAW,gBAAgB,OAAO;EAElCD,MAAM,GACNE,UAAU,sBAAsB,GAAG,MAClC,kBAAkB,GAAG,cAAc,GAAG","names":["type: Q","options: UseOsdkObjectsOptions<Q> & { pivotTo: L }","options?: UseOsdkObjectsOptions<Q, WP>"],"sources":["../../../src/new/useOsdkObjects.ts"],"version":3,"file":"useOsdkObjects.d.ts"}

package/build/types/public/experimental.d.ts

@@ -7,6 +7,8 @@ export { useObjectSet } from "../new/useObjectSet.js";
 export { useOsdkAction } from "../new/useOsdkAction.js";
 export type { UseOsdkAggregationResult } from "../new/useOsdkAggregation.js";
 export { useOsdkAggregation } from "../new/useOsdkAggregation.js";
+export type { UseOsdkFunctionOptions, UseOsdkFunctionResult } from "../new/useOsdkFunction.js";
+export { useOsdkFunction } from "../new/useOsdkFunction.js";
 export { useOsdkObject } from "../new/useOsdkObject.js";
 export type { UseOsdkListResult } from "../new/useOsdkObjects.js";
 export { useOsdkObjects } from "../new/useOsdkObjects.js";

package/build/types/public/experimental.d.ts.map

@@ -1 +1 @@
-{"mappings":"AAgBA,SAAS,qBAAqB;AAC9B,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAC/B,SAAS,2BAA2B;AACpC,SAAS,gBAAgB;AACzB,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,cAAc,gCAAgC;AAC9C,SAAS,0BAA0B;AACnC,SAAS,qBAAqB;AAC9B,cAAc,yBAAyB;AACvC,SAAS,sBAAsB;AAC/B,SAAS,qBAAqB;AAC9B,SAAS,uBAAuB;AAChC,cAAc,6BAA6B;AAC3C,SAAS,4BAA4B","names":[],"sources":["../../../src/public/experimental.ts"],"version":3,"file":"experimental.d.ts"}
+{"mappings":"AAgBA,SAAS,qBAAqB;AAC9B,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAC/B,SAAS,2BAA2B;AACpC,SAAS,gBAAgB;AACzB,SAAS,oBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,cAAc,gCAAgC;AAC9C,SAAS,0BAA0B;AACnC,cACE,wBACA,6BACK;AACP,SAAS,uBAAuB;AAChC,SAAS,qBAAqB;AAC9B,cAAc,yBAAyB;AACvC,SAAS,sBAAsB;AAC/B,SAAS,qBAAqB;AAC9B,SAAS,uBAAuB;AAChC,cAAc,6BAA6B;AAC3C,SAAS,4BAA4B","names":[],"sources":["../../../src/public/experimental.ts"],"version":3,"file":"experimental.d.ts"}

package/docs/actions.md

@@ -0,0 +1,414 @@
+---
+sidebar_position: 3
+---
+
+# Actions
+
+This guide covers executing actions, validation, optimistic updates, and debouncing patterns.
+
+## useOsdkAction
+
+*Experimental - import from `@osdk/react/experimental`*
+
+Execute and validate actions with automatic state management.
+
+### Basic Usage
+
+```tsx
+import { $Actions, Todo } from "@my/osdk";
+import { useOsdkAction, useOsdkObject } from "@osdk/react/experimental";
+import { useCallback } from "react";
+
+function TodoView({ todo }: { todo: Todo.OsdkInstance }) {
+  const { isLoading } = useOsdkObject(todo);
+  const { applyAction, data, error, isPending } = useOsdkAction(
+    $Actions.completeTodo,
+  );
+
+  const onClick = useCallback(() => {
+    applyAction({
+      todo: todo,
+      isComplete: true,
+    });
+  }, [applyAction, todo]);
+
+  return (
+    <div>
+      <div>
+        {todo.title}
+        {todo.isComplete === false && (
+          <button onClick={onClick} disabled={isPending}>
+            Mark Complete
+          </button>
+        )}
+        {isPending && "(Applying)"}
+        {data && "(Action completed successfully)"}
+      </div>
+      {error && (
+        <div>
+          An error occurred:
+          <pre>{JSON.stringify(error, null, 2)}</pre>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Return Values
+
+- `applyAction` - Function to execute the action (accepts single args object or array for batch)
+- `data` - Return value from the last successful action execution
+- `error` - Error object (see error handling below)
+- `isPending` - True while action is executing
+- `isValidating` - True while validation is in progress
+- `validateAction` - Function to validate without executing
+- `validationResult` - Result of last validation
+
+---
+
+## Error Handling
+
+The `error` object has the following structure:
+
+```ts
+{
+  actionValidation?: ActionValidationError;
+  unknown?: unknown;
+}
+```
+
+`ActionValidationError` extends `Error` and has:
+- `message` - Error message string
+- `validation` - Full validation response from server
+
+Example:
+
+```tsx
+import { $Actions, Todo } from "@my/osdk";
+import { useOsdkAction } from "@osdk/react/experimental";
+
+function TodoActionWithErrorHandling({ todo }: { todo: Todo.OsdkInstance }) {
+  const { applyAction, error, isPending } = useOsdkAction($Actions.completeTodo);
+
+  const onClick = async () => {
+    try {
+      await applyAction({ todo, isComplete: true });
+    } catch (e) {
+      console.error("Action failed", e);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={onClick} disabled={isPending}>
+        Complete Todo
+      </button>
+
+      {error?.actionValidation && (
+        <div style={{ color: "red" }}>
+          Validation failed: {JSON.stringify(error.actionValidation.validation)}
+        </div>
+      )}
+
+      {error?.unknown && (
+        <div style={{ color: "red" }}>
+          An unexpected error occurred: {String(error.unknown)}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Validation
+
+Validate action parameters without executing using `validateAction`.
+
+```tsx
+import { $Actions } from "@my/osdk";
+import { useOsdkAction } from "@osdk/react/experimental";
+import { useState } from "react";
+
+function TodoForm() {
+  const [title, setTitle] = useState("");
+  const [assignee, setAssignee] = useState("");
+
+  const {
+    applyAction,
+    validateAction,
+    isValidating,
+    validationResult,
+    isPending,
+    error,
+  } = useOsdkAction($Actions.createTodo);
+
+  const handleTitleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newTitle = e.target.value;
+    setTitle(newTitle);
+    validateAction({ title: newTitle, assignee });
+  };
+
+  const handleAssigneeChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newAssignee = e.target.value;
+    setAssignee(newAssignee);
+    validateAction({ title, assignee: newAssignee });
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (validationResult?.result === "VALID") {
+      await applyAction({ title, assignee });
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="text"
+        value={title}
+        onChange={handleTitleChange}
+        placeholder="Todo title"
+      />
+      <input
+        type="text"
+        value={assignee}
+        onChange={handleAssigneeChange}
+        placeholder="Assignee"
+      />
+
+      {isValidating && <span>Validating...</span>}
+
+      {validationResult?.result === "INVALID" && (
+        <div style={{ color: "red" }}>
+          Invalid: {JSON.stringify(validationResult)}
+        </div>
+      )}
+
+      <button
+        type="submit"
+        disabled={isPending || isValidating || validationResult?.result !== "VALID"}
+      >
+        Create Todo
+      </button>
+
+      {error?.actionValidation && (
+        <div style={{ color: "red" }}>
+          Validation error: {error.actionValidation.message}
+        </div>
+      )}
+    </form>
+  );
+}
+```
+
+Key features:
+
+- `validateAction` - Validates action parameters without executing
+- `isValidating` - True while validation is in progress
+- `validationResult` - Contains `{ result: "VALID" | "INVALID", ... }`
+- Calling `validateAction` while a previous validation is in progress cancels the previous one
+- Validation and execution are mutually exclusive
+
+---
+
+## Batch Actions
+
+Apply the same action to multiple items in a single call:
+
+```tsx
+import { $Actions, Todo } from "@my/osdk";
+import { useOsdkAction } from "@osdk/react/experimental";
+import { useCallback } from "react";
+
+function BulkCompleteButton({ todos }: { todos: Todo.OsdkInstance[] }) {
+  const { applyAction, isPending } = useOsdkAction($Actions.completeTodo);
+
+  const onClick = useCallback(() => {
+    applyAction(
+      todos.map(todo => ({
+        todo: todo,
+        isComplete: true,
+      })),
+    );
+  }, [applyAction, todos]);
+
+  return (
+    <button onClick={onClick} disabled={isPending}>
+      Complete All ({todos.length})
+    </button>
+  );
+}
+```
+
+---
+
+## Optimistic Updates
+
+Apply changes to the cache immediately while waiting for the server response.
+
+```tsx
+import { $Actions, Todo } from "@my/osdk";
+import { useOsdkAction, useOsdkObject } from "@osdk/react/experimental";
+import { useCallback } from "react";
+
+function TodoView({ todo }: { todo: Todo.OsdkInstance }) {
+  const { isLoading, isOptimistic } = useOsdkObject(todo);
+  const { applyAction, error, isPending } = useOsdkAction($Actions.completeTodo);
+
+  const onClick = useCallback(() => {
+    applyAction({
+      todo: todo,
+      isComplete: true,
+
+      $optimisticUpdate: (ou) => {
+        ou.updateObject(todo.$clone({ isComplete: true }));
+      },
+    });
+  }, [applyAction, todo]);
+
+  return (
+    <div>
+      {todo.title}
+      {todo.isComplete === false && !isOptimistic && (
+        <button onClick={onClick} disabled={isPending}>Mark Complete</button>
+      )}
+      {isPending && "(Saving)"}
+      {isLoading && "(Loading)"}
+      {isOptimistic && "(Optimistic)"}
+      {error && (
+        <div style={{ color: "red" }}>
+          {error.actionValidation?.message ?? String(error.unknown)}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### How Optimistic Updates Work
+
+1. When you call `applyAction` with `$optimisticUpdate`, the cache is updated immediately
+2. The UI shows the optimistic state (tracked via `isOptimistic`)
+3. If the action succeeds, the cache is refreshed with server data
+4. If the action fails, the optimistic changes are rolled back automatically
+
+### Optimistic Update API
+
+The `$optimisticUpdate` callback receives an object with the following methods:
+
+```tsx
+$optimisticUpdate: (ou) => {
+  ou.updateObject(todo.$clone({ isComplete: true }));
+  ou.updateObject(anotherObject.$clone({ ... }));
+}
+```
+
+:::note The `$clone` method
+Every OSDK object instance has a `$clone()` method that creates a new object with modified properties. This is essential for optimistic updates because OSDK objects are immutable.
+
+```tsx
+// Create a modified copy without mutating the original
+const completedTodo = todo.$clone({ isComplete: true });
+
+// Clone with multiple property changes
+const updatedTodo = todo.$clone({
+  title: "New Title",
+  priority: "high",
+});
+```
+:::
+
+---
+
+## useDebouncedCallback
+
+*Experimental - import from `@osdk/react/experimental`*
+
+Debounce callback functions for auto-save patterns or expensive operations.
+
+### Basic Usage
+
+```tsx
+import { useDebouncedCallback } from "@osdk/react/experimental";
+import { useState } from "react";
+
+function SearchableList({ onSearch }: { onSearch: (query: string) => void }) {
+  const [query, setQuery] = useState("");
+
+  const debouncedSearch = useDebouncedCallback((q: string) => {
+    onSearch(q);
+  }, 500);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const value = e.target.value;
+    setQuery(value);
+    debouncedSearch(value);
+  };
+
+  return (
+    <input
+      value={query}
+      onChange={handleChange}
+      placeholder="Search..."
+    />
+  );
+}
+```
+
+### Auto-Save Pattern
+
+Combine with actions for auto-saving:
+
+```tsx
+import { $Actions, Todo } from "@my/osdk";
+import { useDebouncedCallback, useOsdkAction } from "@osdk/react/experimental";
+import { useState } from "react";
+
+function AutoSaveTodo({ todo }: { todo: Todo.OsdkInstance }) {
+  const [title, setTitle] = useState(todo.title);
+  const { applyAction } = useOsdkAction($Actions.updateTodo);
+
+  const debouncedSave = useDebouncedCallback((newTitle: string) => {
+    applyAction({
+      todo,
+      title: newTitle,
+      $optimisticUpdate: (ou) => {
+        ou.updateObject(todo.$clone({ title: newTitle }));
+      },
+    });
+  }, 1000);
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const newTitle = e.target.value;
+    setTitle(newTitle);
+    debouncedSave(newTitle);
+  };
+
+  return (
+    <input
+      value={title}
+      onChange={handleChange}
+      placeholder="Click to edit title..."
+    />
+  );
+}
+```
+
+### Debounced Callback Methods
+
+The returned function has utility methods:
+
+```tsx
+import { useDebouncedCallback } from "@osdk/react/experimental";
+
+const debouncedFn = useDebouncedCallback((value: string) => {
+  console.log("Called with:", value);
+}, 500);
+
+debouncedFn("hello");
+debouncedFn.cancel();
+debouncedFn.flush();
+```