Merge pull request #29 from CrowdStrike/collection-hook

feat: useCollectionObject

Author: evanstoner

.github/workflows/build.yml

@@ -2,9 +2,9 @@ name: Build
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
 
 jobs:
   build:
@@ -16,26 +16,29 @@ jobs:
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
 
     steps:
-    - uses: actions/checkout@v4
-
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-
-    - name: Install dependencies
-      run: npm ci
-
-    - name: Build
-      run: npm run build
-
-    - name: Cache build artifacts
-      uses: actions/cache@v4
-      with:
-        path: |
-          dist
-          node_modules
-        key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
-        restore-keys: |
-          ${{ runner.os }}-build-
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Cache build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            dist
+            node_modules
+          key: ${{ runner.os }}-build-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-

README.md

@@ -135,3 +135,25 @@ return (
 
 > [!IMPORTANT]
 > Note that the `data` object returned by `useFoundry()` is a React state object, which the Foundry provider correctly updates via a `falcon.events.on('data')` event handler. Do not use the `falcon.data` object, since it will not correctly re-render your UI when a data event occurs.
+
+### `useCollectionObject`
+
+Query a collection object. This hook is useful to look up a well known value when a component renders, for example a configuration value.
+
+```javascript
+const [config, configReady, configError] = useCollectionObject(
+  "config",
+  "default"
+);
+useEffect(() => {
+  if (!configReady) return;
+  if (configError) return; // TODO: handle error
+  // TODO: use config value
+}, [configReady]);
+```
+
+### Types
+
+Use these types to perform type assertions on responses from foundry-js and safely interact with those responses (rather than asserting them as `any`). See the documentation for each type for more details.
+
+- `CollectionReadResponse` - Returned from `falcon.collection().read()`.

__mocks__/@crowdstrike/foundry-js.ts

@@ -0,0 +1,19 @@
+import { jest } from "@jest/globals";
+
+/**
+ * Stub that enables `jest.mock("@crowdstrike/foundry-js")` since we won't be able to interact with
+ * Foundry from a local test. Mock specific function calls in individual tests, for example:
+ *
+ * ```
+ * const mockReadResponse = { special_key: "special_value" };
+ * const mockCollection = {
+ *   read: jest
+ *     .fn<() => Promise<CollectionReadResponse>>()
+ *     .mockResolvedValue(mockReadResponse),
+ * };
+ * const mockFalcon = {
+ *   collection: jest.fn().mockReturnValue(mockCollection),
+ * };
+ * ```
+ */
+export const FalconApi = jest.fn();

__mocks__/foundry-context.ts

@@ -0,0 +1,15 @@
+import { jest } from "@jest/globals";
+
+/**
+ * Stub that enables `jest.mock("./foundry-context")` since we won't have an actual `FoundryProvider`
+ * in a local test. Return a mock `FalconApi` (see `FalconApi` mock docs):
+
+ *
+ * ```javascript
+ * (useFoundry as jest.Mock).mockReturnValue({
+ *   isInitialized: true,
+ *   falcon: mockFalcon,
+ * });
+ * ```
+ */
+export const useFoundry = jest.fn();

jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+export default {
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+  transform: {
+    "^.+.tsx?$": ["ts-jest", {}],
+  },
+};

package-lock.json

@@ -21,7 +21,8 @@
   "scripts": {
     "build": "rollup -c",
     "clean": "rm -rf dist",
-    "prepack": "npm run clean && npm run build"
+    "prepack": "npm run clean && npm run build",
+    "test": "jest"
   },
   "dependencies": {
     "@crowdstrike/foundry-js": "^0.17.1",
@@ -31,18 +32,23 @@
   "devDependencies": {
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-react": "^7.26.3",
+    "@jest/globals": "^29.7.0",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-commonjs": "^28.0.2",
     "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@testing-library/react": "^16.2.0",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "html-webpack-plugin": "^5.6.3",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "postcss": "^8.5.3",
     "rollup": "^4.34.8",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "rollup-plugin-postcss": "^4.0.2",
+    "ts-jest": "^29.2.6",
     "ts-loader": "^9.4.2",
     "typescript": "^5.8.2",
     "webpack": "^5.98.0",

package.json

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, jest, test } from "@jest/globals";
+import { renderHook, waitFor } from "@testing-library/react";
+import { useFoundry } from "./foundry-context";
+import { useCollectionObject } from "./hooks";
+import { CollectionReadResponse } from "./types";
+
+jest.mock("./foundry-context");
+jest.mock("@crowdstrike/foundry-js");
+
+describe("useCollectionObject", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test("returns object when read succeeds", async () => {
+    // mock falcon api collection response
+    const mockReadResponse = { special_key: "special_value" };
+    const mockCollection = {
+      read: jest
+        .fn<() => Promise<CollectionReadResponse>>()
+        .mockResolvedValue(mockReadResponse),
+    };
+    const mockFalcon = {
+      collection: jest.fn().mockReturnValue(mockCollection),
+    };
+
+    // mock useFoundry to use mock falcon api
+    (useFoundry as jest.Mock).mockReturnValue({
+      isInitialized: true,
+      falcon: mockFalcon,
+    });
+
+    const { result } = renderHook(() =>
+      useCollectionObject("test-collection", "test-key")
+    );
+
+    // wait for ready
+    await waitFor(() => {
+      expect(result.current[1]).toBe(true);
+    });
+
+    // ensure falcon api called correctly
+    expect(mockFalcon.collection).toHaveBeenCalledWith({
+      collection: "test-collection",
+    });
+    expect(mockCollection.read).toHaveBeenCalledWith("test-key");
+
+    // ensure response contains value
+    expect(result.current[0]).toEqual(mockReadResponse); // value
+    expect(result.current[1]).toBe(true); // complete
+    expect(result.current[2]).toBe(null); // error
+  });
+
+  test("returns error when read fails", async () => {
+    // mock falcon api collection response
+    const errorMessage = "error_message";
+    const mockReadResponse = { errors: [{ code: 500, message: errorMessage }] };
+    const mockCollection = {
+      read: jest
+        .fn<() => Promise<CollectionReadResponse>>()
+        .mockResolvedValue(mockReadResponse),
+    };
+    const mockFalcon = {
+      collection: jest.fn().mockReturnValue(mockCollection),
+    };
+
+    // mock useFoundry to use mock falcon api
+    (useFoundry as jest.Mock).mockReturnValue({
+      isInitialized: true,
+      falcon: mockFalcon,
+    });
+
+    const { result } = renderHook(() =>
+      useCollectionObject("test-collection", "test-key")
+    );
+
+    // wait for ready
+    await waitFor(() => {
+      expect(result.current[1]).toBe(true);
+    });
+
+    // ensure response contains value
+    expect(result.current[0]).toEqual(null); // value
+    expect(result.current[1]).toBe(true); // complete
+    expect(result.current[2]).toBe(errorMessage); // error
+  });
+});

src/lib/hooks.test.tsx

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react";
+import { useFoundry } from "./foundry-context";
+import { CollectionReadResponse } from "./types";
+
+/** Query a collection object. This hook is useful to look up a well known value when a component
+ * renders, for example a configuration value.
+ *
+ * Example:
+ *
+ * ```
+ * const [config, configReady, configError] = useCollectionObject("config", "default");
+ * useEffect(() => {
+ *   if (!configReady) return;
+ *   if (configError) return; // TODO: handle error
+ *   // TODO: use config value
+ * }, [configReady])
+ * ```
+ */
+export function useCollectionObject(
+  /** Collection name to query */
+  collection: string,
+  /** Object key to query */
+  key: string
+): [
+  /** The object value, if exists, otherwise `null` */
+  any,
+  /** True when the query is complete (regardless of the result of the query, including error) */
+  boolean,
+  /** Error response message, if any, otherwise `null` */
+  string | null
+] {
+  const { falcon, isInitialized } = useFoundry();
+  const [value, setValue] = useState<object | null>(null);
+  const [complete, setComplete] = useState(false);
+  const [error, setError] = useState<null | string>(null);
+
+  useEffect(() => {
+    if (!isInitialized) return;
+    falcon!
+      .collection({ collection: collection })
+      .read(key)
+      .then((r: CollectionReadResponse) => {
+        if (r.errors && r.errors.length > 0) {
+          setError(r.errors[0].message);
+        } else {
+          setValue(r);
+        }
+        setComplete(true);
+      });
+  }, [isInitialized]);
+
+  return [value, complete, error];
+}

src/lib/hooks.tsx

@@ -1 +1,3 @@
 export { FoundryProvider, useFoundry } from "./foundry-context";
+export { useCollectionObject } from "./hooks";
+export { CollectionReadResponse } from "./types";

src/lib/index.ts

@@ -0,0 +1,26 @@
+interface CanError {
+  /** Errors returned by the API call */
+  errors?: {
+    code: number;
+    message: string;
+  }[];
+}
+
+/**
+ * Returned by `falcon.collection().read()`. Example:
+ * ```
+ * falcon
+ *   .collection({ collection: "foo" })
+ *   .read("bar")
+ *   .then((r: CollectionReadResponse) => {
+ *     if (r.errors && r.errors.length > 0) {
+ *       setError(r.errors[0].message);
+ *     } else {
+ *       setValue(r);
+ *     }});
+ * ```
+ */
+export interface CollectionReadResponse extends CanError {
+  /** Arbitrary data matching the collection's schema */
+  [key: string]: any;
+}