@osdk/react 0.9.0-beta.5 → 0.9.0-beta.7

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();
+```