feat: useCollectionObject

.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

@@ -99,3 +99,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", {}],
+  },
+};