@memberjunction/ng-workspace-initializer

Reusable workspace initialization service for MemberJunction Angular applications. Handles GraphQL client setup, metadata loading, user validation, error classification, and authentication retry logic.

Overview

This package extracts the workspace initialization logic that was originally embedded in the MJExplorer AppComponent into a standalone, reusable service. Any MemberJunction Angular application can use WorkspaceInitializerService to bootstrap an authenticated workspace session with proper error handling and retry semantics.

graph TD
    WIS["WorkspaceInitializerService"] --> GQL["GraphQL Client Setup"]
    WIS --> META["Metadata + User Validation"]
    WIS --> CLASSIFY["Error Classification"]
    WIS --> RETRY["Auth Retry Logic"]

    GQL --> CONFIG["GraphQLProviderConfigData"]
    META --> SHARED["SharedService.RefreshData()"]
    CLASSIFY --> TYPES["no_roles | no_access |\ntoken_expired | network | unknown"]
    RETRY --> AUTHBASE["MJAuthBase.login()"]

    style WIS fill:#7c5295,stroke:#563a6b,color:#fff
    style GQL fill:#2d6a9f,stroke:#1a4971,color:#fff
    style META fill:#2d6a9f,stroke:#1a4971,color:#fff
    style CLASSIFY fill:#2d8659,stroke:#1a5c3a,color:#fff
    style RETRY fill:#2d8659,stroke:#1a5c3a,color:#fff
    style CONFIG fill:#64748b,stroke:#475569,color:#fff
    style SHARED fill:#64748b,stroke:#475569,color:#fff
    style TYPES fill:#b8762f,stroke:#8a5722,color:#fff
    style AUTHBASE fill:#64748b,stroke:#475569,color:#fff

Features

• GraphQL client setup: Configures the GraphQL data provider with token refresh callbacks
• Metadata loading: Loads entity metadata and validates the current user
• Startup validation: Triggers system configuration checks after initialization
• Error classification: Categorizes errors into actionable types (no_roles, no_access, token_expired, network, unknown)
• Auth retry: One-time automatic retry for expired tokens with 24-hour backoff

Installation

npm install @memberjunction/ng-workspace-initializer

Key Dependencies

| Dependency | Purpose | |---|---| | @memberjunction/core | Metadata, LogError, LogStatus | | @memberjunction/graphql-dataprovider | setupGraphQLClient, GraphQLProviderConfigData | | @memberjunction/ng-auth-services | MJAuthBase for token operations | | @memberjunction/ng-shared | SharedService for data refresh | | @memberjunction/ng-explorer-core | StartupValidationService |

Usage

Module Import

import { WorkspaceInitializerModule } from '@memberjunction/ng-workspace-initializer';

@NgModule({
  imports: [WorkspaceInitializerModule]
})
export class AppModule {}

Initialize a Workspace

import { WorkspaceInitializerService } from '@memberjunction/ng-workspace-initializer';

class MyAppComponent {
  constructor(private workspaceInit: WorkspaceInitializerService) {}

  async onLogin(token: string, userInfo: StandardUserInfo) {
    const result = await this.workspaceInit.initializeWorkspace(token, userInfo, {
      GRAPHQL_URI: 'http://localhost:4000',
      GRAPHQL_WS_URI: 'ws://localhost:4000',
      MJ_CORE_SCHEMA_NAME: '__mj'
    });

    if (result.success) {
      // Workspace ready - navigate to app
    } else if (result.error) {
      // Handle typed error
      console.error(result.error.type, result.error.userMessage);

      // Optionally retry for retryable errors
      const retried = await this.workspaceInit.handleAuthRetry(
        result.error,
        window.location.pathname
      );
    }
  }
}

API Reference

WorkspaceInitializerService

| Method | Returns | Description | |---|---|---| | initializeWorkspace(token, userInfo, environment) | Promise<WorkspaceInitResult> | Sets up GraphQL client, loads metadata, validates user | | classifyError(err) | WorkspaceInitError | Categorizes an error into an actionable type | | handleAuthRetry(error, currentPath) | Promise<boolean> | Attempts auth retry for retryable errors (24h backoff) |

Interfaces

interface WorkspaceEnvironment {
  GRAPHQL_URI: string;
  GRAPHQL_WS_URI: string;
  MJ_CORE_SCHEMA_NAME: string;
}

interface WorkspaceInitResult {
  success: boolean;
  error?: WorkspaceInitError;
}

interface WorkspaceInitError {
  type: 'no_roles' | 'no_access' | 'token_expired' | 'network' | 'unknown';
  message: string;
  userMessage: string;
  shouldRetry: boolean;
}

Exported API

| Export | Type | Description | |---|---|---| | WorkspaceInitializerModule | NgModule | Module providing the service | | WorkspaceInitializerService | Service | Main initialization service | | WorkspaceEnvironment | Interface | Environment configuration shape | | WorkspaceInitResult | Interface | Initialization result | | WorkspaceInitError | Interface | Typed error with classification |

Build

cd packages/Angular/Explorer/workspace-initializer && npm run build

Related Packages

• @memberjunction/ng-explorer-app - Application shell that consumes this service
• @memberjunction/ng-explorer-core - Shell and validation services
• @memberjunction/ng-auth-services - Authentication abstraction

License

ISC