@zapier/zapier-sdk 0.4.1 → 0.5.1

package/src/utils/function-utils.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from "vitest";
+import { createFunction, createPaginatedFunction } from "./function-utils";
+import { ZapierValidationError, ZapierUnknownError } from "../types/errors";
+import { ALL_ITEMS, listTestItems } from "./pagination-utils.test";
+
+describe("createFunction", () => {
+  it("should return result from core function", async () => {
+    const mockCoreFn = async (options: { name: string }) => {
+      return `Hello, ${options.name}!`;
+    };
+
+    const wrappedFn = createFunction(mockCoreFn);
+    const result = await wrappedFn({ name: "World" });
+
+    expect(result).toBe("Hello, World!");
+  });
+});
+
+describe.each([
+  { name: "createFunction", createFn: createFunction },
+  { name: "createPaginatedFunction", createFn: createPaginatedFunction },
+])("$name", ({ createFn }) => {
+  it("should preserve function name", async () => {
+    async function testCoreFn(options: { value: number }) {
+      return options.value * 2;
+    }
+
+    const wrappedFn = createFn(testCoreFn);
+
+    expect(wrappedFn.name).toBe("testCoreFn");
+  });
+
+  it("should normalize and rethrow ZapierError instances", async () => {
+    const mockError = new ZapierValidationError("Validation failed", {
+      details: { field: "name" },
+    });
+    const mockCoreFn = async () => {
+      throw mockError;
+    };
+
+    const wrappedFn = createFn(mockCoreFn);
+
+    await expect(wrappedFn({})).rejects.toBe(mockError);
+  });
+
+  it("should normalize generic Error to ZapierUnknownError", async () => {
+    const mockCoreFn = async () => {
+      throw new Error("Something went wrong");
+    };
+
+    const wrappedFn = createFn(mockCoreFn);
+
+    await expect(wrappedFn({})).rejects.toThrow(ZapierUnknownError);
+  });
+
+  it("should normalize non-Error values to ZapierUnknownError", async () => {
+    const mockCoreFn = async () => {
+      throw "String error";
+    };
+
+    const wrappedFn = createFn(mockCoreFn);
+
+    await expect(wrappedFn({})).rejects.toThrow(ZapierUnknownError);
+  });
+});
+
+describe("createPaginatedFunction", () => {
+  it("should wrap non-array result in {data: [result]}", async () => {
+    const mockCoreFn = async (options: { name: string }) => {
+      return `Hello, ${options.name}!`;
+    };
+
+    const wrappedFn = createPaginatedFunction(mockCoreFn);
+    const result = await wrappedFn({ name: "World" });
+
+    expect(result).toEqual({ data: ["Hello, World!"] });
+  });
+
+  it("should wrap array result in {data: result}", async () => {
+    const mockCoreFn = async (options: { count: number }) => {
+      return Array.from({ length: options.count }, (_, i) => `Item ${i + 1}`);
+    };
+
+    const wrappedFn = createPaginatedFunction(mockCoreFn);
+    const result = await wrappedFn({ count: 3 });
+
+    expect(result).toEqual({ data: ["Item 1", "Item 2", "Item 3"] });
+  });
+
+  it("should return {data} object unchanged", async () => {
+    const mockCoreFn = async (options: { items: string[] }) => {
+      return { data: options.items };
+    };
+
+    const wrappedFn = createPaginatedFunction(mockCoreFn);
+    const result = await wrappedFn({ items: ["A", "B", "C"] });
+
+    expect(result).toEqual({ data: ["A", "B", "C"] });
+  });
+
+  it("should allow for await iteration over pages", async () => {
+    const listItems = createPaginatedFunction(listTestItems);
+
+    const pages = [];
+    for await (const page of listItems({ pageSize: 3 })) {
+      pages.push(page);
+      if (pages.length >= 3) break;
+    }
+
+    // Should have collected 3 pages
+    expect(pages).toHaveLength(3);
+
+    // Check first page structure
+    expect(pages[0]).toEqual({
+      data: ALL_ITEMS.slice(0, 3),
+      nextCursor: "cursor-3",
+    });
+
+    // Check second page
+    expect(pages[1]).toEqual({
+      data: ALL_ITEMS.slice(3, 6),
+      nextCursor: "cursor-6",
+    });
+  });
+
+  it("should allow for await iteration over individual items", async () => {
+    const listItems = createPaginatedFunction(listTestItems);
+
+    const items = [];
+    for await (const item of listItems({ pageSize: 3 }).items()) {
+      items.push(item);
+      if (items.length >= 7) break; // Get first 7 items across pages
+    }
+
+    // Should have collected 7 individual items
+    expect(items).toHaveLength(7);
+
+    // Should be the first 7 items from ALL_ITEMS (flattened from pages)
+    expect(items).toEqual(ALL_ITEMS.slice(0, 7));
+  });
+});

package/src/utils/function-utils.ts

@@ -0,0 +1,245 @@
+/**
+ * Generic utility functions for creating paginated SDK functions
+ */
+
+import { z } from "zod";
+import { ZapierError, ZapierUnknownError } from "../types/errors";
+import { paginate } from "./pagination-utils";
+import { createValidator, validateOptions } from "./validation";
+
+/**
+ * Helper function to extract cursor from pagination data
+ */
+export function extractCursor(
+  data: { next?: string | null } | null | undefined,
+): string | undefined {
+  if (!data?.next) {
+    return undefined;
+  }
+
+  try {
+    const urlObj = new URL(data.next);
+    const offset = urlObj.searchParams.get("offset");
+    return offset || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Helper function to convert unknown errors to SDK errors
+ */
+function normalizeError(error: unknown): ZapierError {
+  if (error instanceof ZapierError) {
+    return error;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return new ZapierUnknownError(`Unknown error: ${message}`, { cause: error });
+}
+
+/**
+ * Higher-order function that creates a function from a core function
+ *
+ * @param coreFn - Function that returns T directly or throws errors
+ * @param schema - Optional Zod schema for validation
+ * @returns A function that normalizes and rethrows errors
+ */
+export function createFunction<
+  TOptions,
+  TResult,
+  TSchemaOptions extends TOptions = TOptions,
+>(
+  coreFn: (options: TOptions) => Promise<TResult>,
+  schema?: z.ZodSchema<TSchemaOptions>,
+) {
+  const functionName = coreFn.name;
+
+  // Create a named function using dynamic property access
+  const namedFunctions = {
+    [functionName]: async function (options?: TOptions): Promise<TResult> {
+      try {
+        // Convert undefined options to empty object
+        const normalizedOptions = (options ?? {}) as TOptions;
+
+        if (schema) {
+          const validatedOptions = validateOptions(schema, normalizedOptions);
+          return await coreFn({
+            ...normalizedOptions,
+            ...validatedOptions,
+          });
+        }
+        return await coreFn(normalizedOptions);
+      } catch (error) {
+        // Catch and normalize any errors, then rethrow
+        throw normalizeError(error);
+      }
+    },
+  };
+
+  return namedFunctions[functionName];
+}
+
+/**
+ * Higher-order function that creates a page function that wraps results in {data}
+ * Internal utility used by createPaginatedFunction
+ */
+function createPageFunction<TOptions, TResult>(
+  coreFn: (options: TOptions) => Promise<TResult>,
+) {
+  const functionName = coreFn.name + "Page";
+
+  // Create a named function using dynamic property access
+  const namedFunctions = {
+    [functionName]: async function (
+      options: TOptions & {
+        cursor?: string;
+        maxItems?: number;
+        pageSize?: number;
+      },
+    ): Promise<{ data: any[]; nextCursor?: string }> {
+      try {
+        const result = await coreFn(options);
+
+        // If result already has a data property, ensure it's an array
+        if (result && typeof result === "object" && "data" in result) {
+          const data = (result as any).data;
+          return {
+            data: Array.isArray(data) ? data : [data],
+            nextCursor: (result as any).nextCursor,
+          };
+        }
+
+        // If result is an array, wrap in {data: result}
+        if (Array.isArray(result)) {
+          return { data: result };
+        }
+
+        // If result is non-array, wrap in {data: [result]}
+        return { data: [result] };
+      } catch (error) {
+        // Catch and normalize any errors, then rethrow
+        throw normalizeError(error);
+      }
+    },
+  };
+
+  return namedFunctions[functionName];
+}
+
+/**
+ * Higher-order function that creates a paginated function that wraps results in {data}
+ *
+ * @param coreFn - Function that returns T directly or throws errors
+ * @returns A function that normalizes errors and wraps results in {data}
+ */
+type PaginatedResult<TResult> = TResult extends {
+  data: any;
+  nextCursor?: string;
+}
+  ? TResult
+  : { data: TResult; nextCursor?: string };
+
+type ItemType<TResult> = TResult extends { data: infer TData }
+  ? TData extends readonly (infer TItem)[]
+    ? TItem
+    : TData
+  : TResult extends readonly (infer TItem)[]
+    ? TItem
+    : TResult;
+
+export function createPaginatedFunction<
+  TOptions,
+  TResult,
+  TSchemaOptions extends TOptions = TOptions,
+>(
+  coreFn: (options: TOptions & { pageSize: number }) => Promise<TResult>,
+  schema?: z.ZodSchema<TSchemaOptions>,
+): (
+  options?: TOptions & {
+    cursor?: string;
+    pageSize?: number;
+    maxItems?: number;
+  },
+) => Promise<PaginatedResult<TResult>> &
+  AsyncIterable<PaginatedResult<TResult>> & {
+    items(): AsyncIterable<ItemType<TResult>>;
+  } {
+  const pageFunction = createPageFunction(coreFn);
+  const functionName = coreFn.name;
+  const validator = schema ? createValidator(schema) : null;
+
+  // Create the main paginated function
+  const namedFunctions = {
+    [functionName]: function (
+      options?: TOptions & {
+        cursor?: string;
+        pageSize?: number;
+        maxItems?: number;
+      },
+    ) {
+      // Convert undefined options to empty object
+      const normalizedOptions = (options ?? {}) as TOptions & {
+        cursor?: string;
+        pageSize?: number;
+        maxItems?: number;
+      };
+
+      // Validate options if schema provided (validated fields take precedence)
+      const validatedOptions = {
+        ...normalizedOptions,
+        ...(validator ? validator(normalizedOptions) : normalizedOptions),
+      };
+
+      // Set default pageSize if not provided
+      const pageSize = validatedOptions.pageSize || 100;
+      const optimizedOptions = {
+        ...validatedOptions,
+        pageSize,
+      };
+
+      const iterator = paginate(pageFunction, optimizedOptions as any);
+
+      // Get a promise for the first iteration
+      const firstPagePromise = iterator.next().then((result) => {
+        if (result.done) {
+          throw new Error("Paginate should always iterate at least once");
+        }
+        return result.value;
+      });
+
+      // Add Symbol.asyncIterator to make the promise iterable
+      return Object.assign(firstPagePromise, {
+        [Symbol.asyncIterator]: async function* () {
+          // Yield the first page (await the promise)
+          yield await firstPagePromise;
+
+          // Yield the rest of the pages
+          for await (const page of iterator) {
+            yield page;
+          }
+        },
+        items: function () {
+          return {
+            [Symbol.asyncIterator]: async function* () {
+              // Yield the first page items
+              const firstPage = await firstPagePromise;
+              for (const item of firstPage.data) {
+                yield item;
+              }
+
+              // Yield items from the rest of the pages
+              for await (const page of iterator) {
+                for (const item of page.data) {
+                  yield item;
+                }
+              }
+            },
+          };
+        },
+      });
+    },
+  };
+
+  return namedFunctions[functionName] as any;
+}