@orq-ai/node 3.9.4 → 3.10.0-rc.2

package/packages/orq-rc/FUNCTIONS.md

@@ -1,103 +0,0 @@
-# Standalone Functions
-
-> [!NOTE]
-> This section is useful if you are using a bundler and targetting browsers and
-> runtimes where the size of an application affects performance and load times. 
-
-Every method in this SDK is also available as a standalone function. This
-alternative API is suitable when targetting the browser or serverless runtimes
-and using a bundler to build your application since all unused functionality
-will be tree-shaken away. This includes code for unused methods, Zod schemas,
-encoding helpers and response handlers. The result is dramatically smaller
-impact on the application's final bundle size which grows very slowly as you use
-more and more functionality from this SDK.
-
-Calling methods through the main SDK class remains a valid and generally more
-more ergonomic option. Standalone functions represent an optimisation for a
-specific category of applications.
-
-## Example
-
-```typescript
-import { OrqCore } from "@orq-ai/node/core.js";
-import { contactsCreate } from "@orq-ai/node/funcs/contactsCreate.js";
-
-// Use `OrqCore` for best tree-shaking performance.
-// You can create one instance of it to use across an application.
-const orq = new OrqCore({
-  apiKey: process.env["ORQ_API_KEY"] ?? "",
-});
-
-async function run() {
-  const res = await contactsCreate(orq, {
-    externalId: "user_12345",
-    displayName: "Jane Smith",
-    email: "jane.smith@example.com",
-    avatarUrl: "https://example.com/avatars/jane-smith.jpg",
-    tags: [
-      "premium",
-      "beta-user",
-      "enterprise",
-    ],
-    metadata: {
-      "department": "Engineering",
-      "role": "Senior Developer",
-      "subscription_tier": "premium",
-      "last_login": "2024-01-15T10:30:00Z",
-    },
-  });
-  if (res.ok) {
-    const { value: result } = res;
-    console.log(result);
-  } else {
-    console.log("contactsCreate failed:", res.error);
-  }
-}
-
-run();
-```
-
-## Result types
-
-Standalone functions differ from SDK methods in that they return a
-`Result<Value, Error>` type to capture _known errors_ and document them using
-the type system. By avoiding throwing errors, application code maintains clear
-control flow and error-handling become part of the regular flow of application
-code.
-
-> We use the term "known errors" because standalone functions, and JavaScript
-> code in general, can still throw unexpected errors such as `TypeError`s,
-> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
-> something this SDK addresses in the future. Nevertheless, there is still a lot
-> of benefit from capturing most errors and turning them into values.
-
-The second reason for this style of programming is because these functions will
-typically be used in front-end applications where exception throwing is
-sometimes discouraged or considered unidiomatic. React and similar ecosystems
-and libraries tend to promote this style of programming so that components
-render useful content under all states (loading, success, error and so on).
-
-The general pattern when calling standalone functions looks like this:
-
-```typescript
-import { Core } from "<sdk-package-name>";
-import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
-
-const client = new Core();
-
-async function run() {
-  const result = await fetchSomething(client, { id: "123" });
-  if (!result.ok) {
-    // You can throw the error or handle it. It's your choice now.
-    throw result.error;
-  }
-
-  console.log(result.value);
-}
-
-run();
-```
-
-Notably, `result.error` above will have an explicit type compared to a try-catch
-variation where the error in the catch block can only be of type `unknown` (or
-`any` depending on your TypeScript settings).