@nlabs/reaktor 0.10.0 → 0.10.1

package/TEST_UTILITIES_GUIDE.md

@@ -0,0 +1,360 @@
+# Test Utilities Guide
+
+This guide explains how to use the test utilities in `src/utils/testUtils.ts` to optimize and consolidate your GraphQL query and mutation tests.
+
+## Overview
+
+The test utilities provide a standardized way to create tests for GraphQL resolvers, reducing code duplication and improving maintainability. They abstract common testing patterns into reusable functions.
+
+## Available Utilities
+
+### 1. Mock Context and Resolve Info
+
+```typescript
+import { createMockContext, createMockResolveInfo } from '../utils/testUtils';
+
+// Create a standard mock context
+const context = createMockContext();
+
+// Create a custom context with overrides
+const customContext = createMockContext({
+  databaseName: 'custom-db',
+  session: { userId: 'custom-user' }
+});
+
+// Create mock resolve info for GraphQL resolvers
+const resolveInfo = createMockResolveInfo('fieldName');
+```
+
+### 2. Mock Data Generators
+
+```typescript
+import {
+  createMockUser,
+  createMockPost,
+  createMockMessage,
+  createMockReaction,
+  createMockTag
+} from '../utils/testUtils';
+
+// Create mock data with defaults
+const user = createMockUser();
+const post = createMockPost();
+
+// Create mock data with custom values
+const customUser = createMockUser({
+  userId: 'custom-id',
+  email: 'custom@example.com'
+});
+```
+
+### 3. Mock Setup Utilities
+
+```typescript
+import { mockActionsModule, mockObjectType, setupCommonMocks } from '../utils/testUtils';
+
+// Mock actions module
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+
+// Mock object types
+mockObjectType('../objectTypes/user', 'user');
+
+// Setup common mocks (auth utils, etc.)
+setupCommonMocks();
+```
+
+## Test Suite Creators
+
+### 1. Query Test Suite
+
+Use `createQueryTestSuite` for testing GraphQL query resolvers:
+
+```typescript
+import { createQueryTestSuite, createMockUser } from '../utils/testUtils';
+
+// Mock dependencies
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+mockObjectType('../objectTypes/user', 'user');
+
+// Define test cases
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserById',
+    actionName: 'getUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => ({ userId: args.userId }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  }
+];
+
+// Create the test suite
+createQueryTestSuite(
+  'User Queries',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  testCases
+);
+```
+
+### 2. Mutation Test Suite
+
+Use `createMutationTestSuite` for testing GraphQL mutation resolvers:
+
+```typescript
+import { createMutationTestSuite, createMockUser, setupCommonMocks } from '../utils/testUtils';
+
+// Setup common mocks
+setupCommonMocks();
+
+// Mock mutations module (complex setup)
+jest.mock('./users', () => ({
+  userMutations: {
+    getField: jest.fn((fieldName) => ({
+      resolve: jest.fn(async (context, args) => {
+        const actions = require('../actions/users');
+        return await actions[fieldName](context, args);
+      })
+    }))
+  }
+}));
+
+// Define test cases
+const testCases = [
+  {
+    name: 'addUser',
+    actionName: 'addUser',
+    args: { username: 'testuser', email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => args,
+    mockReturnValue: createMockUser()
+  },
+  {
+    name: 'deactivateUser',
+    actionName: 'deactivateUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => args,
+    mockReturnValue: createMockUser(),
+    requiresAuth: true,
+    authUserId: 'user1'
+  }
+];
+
+// Create the test suite
+createMutationTestSuite(
+  'User',
+  '../actions/users',
+  './users',
+  testCases
+);
+```
+
+### 3. Integration Test Suite
+
+Use `createIntegrationTestSuite` for testing integration scenarios:
+
+```typescript
+import { createIntegrationTestSuite, createMockUser } from '../utils/testUtils';
+
+// Define test cases
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    successReturnValue: createMockUser(),
+    errorReturnValue: null,
+    testErrorCase: true
+  }
+];
+
+// Create the integration test suite
+createIntegrationTestSuite(
+  'User',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  testCases
+);
+```
+
+## Test Case Configuration
+
+### Query Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  mockReturnValue?: any;           // Mock return value
+  errorCase?: boolean;             // Whether to test error handling
+}
+```
+
+### Mutation Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  mockReturnValue?: any;           // Mock return value
+  requiresAuth?: boolean;          // Whether authentication is required
+  authUserId?: string;             // User ID for auth check
+  errorCase?: boolean;             // Whether to test error handling
+}
+```
+
+### Integration Test Cases
+
+```typescript
+{
+  name: string;                    // Test name
+  actionName: string;              // Action function name
+  args: any;                       // Arguments to pass
+  expectedCall: (context: any, args: any) => any;  // Expected call parameters
+  successReturnValue?: any;        // Success case return value
+  errorReturnValue?: any;          // Error case return value
+  testErrorCase?: boolean;         // Whether to test error scenarios
+}
+```
+
+## Migration Guide
+
+### From Manual Tests to Utilities
+
+**Before (Manual):**
+```typescript
+describe('User Queries', () => {
+  const mockContext = {
+    databaseName: 'test',
+    session: { userId: 'user1', username: 'testuser', userAccess: 1 }
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('getUserByEmail', () => {
+    it('should call getUser action with email parameter', async () => {
+      const mockUser = { userId: 'user1', email: 'test@example.com' };
+      const { getUser } = require('../actions/users');
+      getUser.mockResolvedValue(mockUser);
+
+      const result = await getUser(mockContext, { email: 'test@example.com' });
+
+      expect(getUser).toHaveBeenCalledWith(mockContext, { email: 'test@example.com' });
+      expect(result).toEqual(mockUser);
+    });
+  });
+});
+```
+
+**After (Using Utilities):**
+```typescript
+import { createQueryTestSuite, createMockUser } from '../utils/testUtils';
+
+const testCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser()
+  }
+];
+
+createQueryTestSuite('User Queries', '../actions/users', '../objectTypes/user', 'user', testCases);
+```
+
+## Benefits
+
+1. **Reduced Code Duplication**: Common test patterns are abstracted into reusable functions
+2. **Consistent Testing**: All tests follow the same structure and patterns
+3. **Easier Maintenance**: Changes to test patterns only need to be made in one place
+4. **Better Readability**: Test intentions are clearer with declarative test case definitions
+5. **Faster Development**: New tests can be created quickly by defining test cases
+
+## Best Practices
+
+1. **Use Descriptive Names**: Make test case names clear and descriptive
+2. **Group Related Tests**: Use the suite name to group related functionality
+3. **Test Both Success and Error Cases**: Include error handling tests where appropriate
+4. **Use Mock Data Generators**: Use the provided mock data generators for consistent test data
+5. **Keep Test Cases Focused**: Each test case should test one specific scenario
+
+## Example: Complete Optimized Test File
+
+```typescript
+import {
+  createQueryTestSuite,
+  createMockUser,
+  mockActionsModule,
+  mockObjectType
+} from '../utils/testUtils';
+
+// Mock dependencies
+mockActionsModule('../actions/users', {
+  getUser: jest.fn(),
+  getSessionUser: jest.fn()
+});
+
+mockObjectType('../objectTypes/user', 'user');
+
+// Define test cases
+const userQueryTestCases = [
+  {
+    name: 'getUserByEmail',
+    actionName: 'getUser',
+    args: { email: 'test@example.com' },
+    expectedCall: (context: any, args: any) => ({ email: args.email }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserById',
+    actionName: 'getUser',
+    args: { userId: 'user1' },
+    expectedCall: (context: any, args: any) => ({ userId: args.userId }),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  },
+  {
+    name: 'getUserBySession',
+    actionName: 'getSessionUser',
+    args: {},
+    expectedCall: (context: any, args: any) => ({}),
+    mockReturnValue: createMockUser(),
+    errorCase: true
+  }
+];
+
+// Create the test suite
+createQueryTestSuite(
+  'User Queries',
+  '../actions/users',
+  '../objectTypes/user',
+  'user',
+  userQueryTestCases
+);
+```
+
+This approach reduces the original 130-line test file to just 40 lines while maintaining the same test coverage and functionality.

package/coverage/index.html

@@ -23,30 +23,30 @@
         <div class='clearfix'>
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">89.23% </span>
+                <span class="strong">78.94% </span>
                 <span class="quiet">Statements</span>
-                <span class='fraction'>1981/2220</span>
+                <span class='fraction'>2414/3058</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">80.16% </span>
+                <span class="strong">64.96% </span>
                 <span class="quiet">Branches</span>
-                <span class='fraction'>570/711</span>
+                <span class='fraction'>777/1196</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">89.48% </span>
+                <span class="strong">75.51% </span>
                 <span class="quiet">Functions</span>
-                <span class='fraction'>434/485</span>
+                <span class='fraction'>512/678</span>
             </div>
         
             
             <div class='fl pad1y space-right2'>
-                <span class="strong">88.18% </span>
+                <span class="strong">77.19% </span>
                 <span class="quiet">Lines</span>
-                <span class='fraction'>1776/2014</span>
+                <span class='fraction'>2126/2754</span>
             </div>
         
             
@@ -61,7 +61,7 @@
             </div>
         </template>
     </div>
-    <div class='status-line high'></div>
+    <div class='status-line medium'></div>
     <div class="pad1">
 <table class="coverage-summary">
 <thead>
@@ -84,43 +84,43 @@
 	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
 	</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="8" class="abs high">8/8</td>
+	<td data-value="17" class="abs high">17/17</td>
+	<td data-value="86.66" class="pct high">86.66%</td>
+	<td data-value="15" class="abs high">13/15</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="2" class="abs high">2/2</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="2" class="abs high">2/2</td>
+	<td data-value="4" class="abs high">4/4</td>
 	<td data-value="100" class="pct high">100%</td>
-	<td data-value="8" class="abs high">8/8</td>
+	<td data-value="17" class="abs high">17/17</td>
 	</tr>
 
 <tr>
 	<td class="file high" data-value="src/actions"><a href="src/actions/index.html">src/actions</a></td>
-	<td data-value="88.4" class="pic high">
-	<div class="chart"><div class="cover-fill" style="width: 88%"></div><div class="cover-empty" style="width: 12%"></div></div>
+	<td data-value="80.23" class="pic high">
+	<div class="chart"><div class="cover-fill" style="width: 80%"></div><div class="cover-empty" style="width: 20%"></div></div>
 	</td>
-	<td data-value="88.4" class="pct high">88.4%</td>
-	<td data-value="1992" class="abs high">1761/1992</td>
-	<td data-value="75.91" class="pct medium">75.91%</td>
-	<td data-value="548" class="abs medium">416/548</td>
-	<td data-value="88.98" class="pct high">88.98%</td>
-	<td data-value="445" class="abs high">396/445</td>
-	<td data-value="87.39" class="pct high">87.39%</td>
-	<td data-value="1825" class="abs high">1595/1825</td>
+	<td data-value="80.23" class="pct high">80.23%</td>
+	<td data-value="2181" class="abs high">1750/2181</td>
+	<td data-value="64.36" class="pct medium">64.36%</td>
+	<td data-value="623" class="abs medium">401/623</td>
+	<td data-value="78.57" class="pct medium">78.57%</td>
+	<td data-value="490" class="abs medium">385/490</td>
+	<td data-value="78.57" class="pct medium">78.57%</td>
+	<td data-value="2002" class="abs medium">1573/2002</td>
 	</tr>
 
 <tr>
-	<td class="file high" data-value="src/adapters"><a href="src/adapters/index.html">src/adapters</a></td>
-	<td data-value="100" class="pic high">
-	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
+	<td class="file medium" data-value="src/adapters"><a href="src/adapters/index.html">src/adapters</a></td>
+	<td data-value="61.71" class="pic medium">
+	<div class="chart"><div class="cover-fill" style="width: 61%"></div><div class="cover-empty" style="width: 39%"></div></div>
 	</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="75" class="abs high">75/75</td>
-	<td data-value="98.21" class="pct high">98.21%</td>
-	<td data-value="112" class="abs high">110/112</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="16" class="abs high">16/16</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="57" class="abs high">57/57</td>
+	<td data-value="61.71" class="pct medium">61.71%</td>
+	<td data-value="431" class="abs medium">266/431</td>
+	<td data-value="62.26" class="pct medium">62.26%</td>
+	<td data-value="424" class="abs medium">264/424</td>
+	<td data-value="40" class="pct low">40%</td>
+	<td data-value="75" class="abs low">30/75</td>
+	<td data-value="58.99" class="pct medium">58.99%</td>
+	<td data-value="378" class="abs medium">223/378</td>
 	</tr>
 
 <tr>
@@ -138,36 +138,6 @@
 	<td data-value="20" class="abs high">20/20</td>
 	</tr>
 
-<tr>
-	<td class="file high" data-value="src/templates/email"><a href="src/templates/email/index.html">src/templates/email</a></td>
-	<td data-value="100" class="pic high">
-	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
-	</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="5" class="abs high">5/5</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="0" class="abs high">0/0</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="0" class="abs high">0/0</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="5" class="abs high">5/5</td>
-	</tr>
-
-<tr>
-	<td class="file high" data-value="src/templates/sms"><a href="src/templates/sms/index.html">src/templates/sms</a></td>
-	<td data-value="100" class="pic high">
-	<div class="chart"><div class="cover-fill cover-full" style="width: 100%"></div><div class="cover-empty" style="width: 0%"></div></div>
-	</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="4" class="abs high">4/4</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="0" class="abs high">0/0</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="0" class="abs high">0/0</td>
-	<td data-value="100" class="pct high">100%</td>
-	<td data-value="4" class="abs high">4/4</td>
-	</tr>
-
 <tr>
 	<td class="file high" data-value="src/types"><a href="src/types/index.html">src/types</a></td>
 	<td data-value="100" class="pic high">
@@ -185,17 +155,17 @@
 
 <tr>
 	<td class="file high" data-value="src/utils"><a href="src/utils/index.html">src/utils</a></td>
-	<td data-value="93.04" class="pic high">
-	<div class="chart"><div class="cover-fill" style="width: 93%"></div><div class="cover-empty" style="width: 7%"></div></div>
+	<td data-value="88.23" class="pic high">
+	<div class="chart"><div class="cover-fill" style="width: 88%"></div><div class="cover-empty" style="width: 12%"></div></div>
 	</td>
-	<td data-value="93.04" class="pct high">93.04%</td>
-	<td data-value="115" class="abs high">107/115</td>
-	<td data-value="85.71" class="pct high">85.71%</td>
-	<td data-value="49" class="abs high">42/49</td>
-	<td data-value="90.9" class="pct high">90.9%</td>
-	<td data-value="22" class="abs high">20/22</td>
-	<td data-value="91.48" class="pct high">91.48%</td>
-	<td data-value="94" class="abs high">86/94</td>
+	<td data-value="88.23" class="pct high">88.23%</td>
+	<td data-value="408" class="abs high">360/408</td>
+	<td data-value="73.88" class="pct medium">73.88%</td>
+	<td data-value="134" class="abs medium">99/134</td>
+	<td data-value="85.32" class="pct high">85.32%</td>
+	<td data-value="109" class="abs high">93/109</td>
+	<td data-value="86.9" class="pct high">86.9%</td>
+	<td data-value="336" class="abs high">292/336</td>
 	</tr>
 
 </tbody>
@@ -206,7 +176,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2025-06-17T18:38:18.536Z
+                at 2025-07-02T05:49:37.404Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/index.js

@@ -2,4 +2,4 @@
  * Copyright (c) 2019-Present, Nitrogen Labs, Inc.
  * Copyrights licensed under the MIT License. See the accompanying LICENSE file for terms.
  */
-module.exports = require('./lib');
+export * from './lib/index.js';

package/jest.config.js

@@ -0,0 +1,17 @@
+module.exports = {
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.ts$': 'ts-jest'
+  },
+  moduleFileExtensions: ['ts', 'js', 'json'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(zod)/)'
+  ],
+  extensionsToTreatAsEsm: ['.ts'],
+  globals: {
+    'ts-jest': {
+      useESM: true
+    }
+  }
+};

package/jest.setup.js

@@ -0,0 +1,36 @@
+// Centralized ArangoDB mock for all tests
+jest.mock('arangojs', () => ({
+  ...jest.requireActual('arangojs'),
+  aql: jest.fn((templateStrings, ...args) => {
+    // Concatenate template strings and interpolate arguments
+    let result = '';
+    for (let i = 0; i < templateStrings.length; i++) {
+      result += templateStrings[i];
+      if (i < args.length) {
+        // Add the actual value to the template
+        result += args[i];
+      }
+    }
+    // Normalize to single line: remove newlines and normalize whitespace
+    const singleLine = result.replace(/\s+/g, ' ').trim();
+    return [singleLine, ...args];
+  })
+}));
+
+// Mock the useDb function from arangodbUtils with a basic default
+const mockUseDb = jest.fn(() => ({
+  collection: jest.fn(() => ({
+    save: jest.fn(() => Promise.resolve()),
+    remove: jest.fn(() => Promise.resolve()),
+    update: jest.fn(() => Promise.resolve())
+  })),
+  query: jest.fn(() => Promise.resolve({
+    all: jest.fn(() => Promise.resolve([])),
+    next: jest.fn(() => Promise.resolve({}))
+  }))
+}));
+
+jest.mock('./src/utils/arangodbUtils', () => ({
+  ...jest.requireActual('./src/utils/arangodbUtils'),
+  useDb: mockUseDb
+}));

package/lex.config.cjs

@@ -1,8 +1,8 @@
 module.exports = {
   ai: {
-    provider: 'cursor',
-    model: 'cursor-code',
     maxTokens: 4000,
+    model: 'cursor-code',
+    provider: 'cursor',
     temperature: 0.1
   },
   outputPath: 'lib',