Skip to main content

@idpass/data-collect-core / ExternalSyncManager

Class: ExternalSyncManager

Defined in: components/ExternalSyncManager.ts:110

Manages synchronization with external third-party systems using pluggable adapters.

This class provides a unified interface for syncing DataCollect data with various external systems (e.g., OpenSPP, custom APIs) by utilizing a Strategy pattern with pluggable adapters.

Key features:

  • Pluggable Adapters: Support for multiple external systems via adapter pattern.
  • V1/V2 Compatibility: Supports both legacy ExternalSyncAdapter and ExternalSyncAdapterV2.
  • AdapterRegistry Integration: Uses the centralized AdapterRegistry for V2 adapters.
  • Dynamic Loading: Adapters are instantiated based on configuration type.
  • Credential Management: Secure handling of authentication credentials.
  • Health Checks: Validate connectivity before sync operations.
  • Structured Results: Returns SyncResult from sync operations.
  • Config Validation: Validates config against adapter's Zod schema (V2 adapters).

Architecture:

  • Uses Strategy pattern for different external system integrations.
  • V2 adapters are resolved from the AdapterRegistry first.
  • Falls back to legacy adapter registries (built-in and runtime) for backwards compatibility.
  • Each adapter implements ExternalSyncAdapterV2 (or is wrapped via LegacyAdapterWrapper).
  • Configuration determines which adapter to instantiate and how to configure it.

Example​

Basic usage with a V2 adapter (mock registry server):

const config: ExternalSyncConfig = {
  type: 'mock',
  url: 'http://localhost:9999',
  adapterConfig: {
    clientId: 'mock-client',
    clientSecret: 'mock-secret',
  },
};

const externalSync = new ExternalSyncManager(
  eventStore,
  eventApplierService,
  config
);

await externalSync.initialize();
const result = await externalSync.synchronize();
console.log(`Pulled ${result.pulled}, pushed ${result.pushed}`);

Constructors​

Constructor​

new ExternalSyncManager(eventStore, eventApplierService, config): ExternalSyncManager

Defined in: components/ExternalSyncManager.ts:138

Creates a new ExternalSyncManager instance.

Parameters​

eventStore​

EventStore

Store for managing events and audit logs.

eventApplierService​

EventApplierService

Service for applying events to entities.

config​

ExternalSyncConfig

Configuration object specifying the external system type and settings.

Returns​

ExternalSyncManager

Example​

const config: ExternalSyncConfig = {
  type: 'openspp',
  url: 'http://openspp.example.com',
  database: 'openspp_production',
  timeout: 60000
};

const manager = new ExternalSyncManager(
  eventStore,
  eventApplierService,
  config
);

Accessors​

isSyncing​

Get Signature​

get isSyncing(): boolean

Defined in: components/ExternalSyncManager.ts:289

Whether an external sync is currently in progress.

Returns​

boolean

Methods​

registerAdapter()​

static registerAdapter(type, adapterClass): void

Defined in: components/ExternalSyncManager.ts:162

Registers an external adapter class for a given type identifier.

Call this at application startup to make adapters from external packages (e.g., @idpass/adapter-openspp, @idpass/adapter-openfn) available to the manager.

Parameters​

type​

string

The adapter type string used in ExternalSyncConfig.type

adapterClass​

LegacyAdapterConstructor

The adapter constructor to register

Returns​

void

Example​

import { OpenSppV2SyncAdapter } from '@idpass/adapter-openspp';
import { OpenFnSyncAdapter } from '@idpass/adapter-openfn';

ExternalSyncManager.registerAdapter('openspp-v2-adapter', OpenSppV2SyncAdapter);
ExternalSyncManager.registerAdapter('openfn-adapter', OpenFnSyncAdapter);

initialize()​

initialize(): Promise<void>

Defined in: components/ExternalSyncManager.ts:196

Initializes the external sync manager by instantiating the appropriate adapter.

Resolution order:

  1. Check AdapterRegistry for V2 adapters (preferred)
  2. Check built-in legacy adapter registry
  3. Check runtime legacy adapter registry

For V2 adapters, the config is validated against the adapter's Zod schema and the adapter is initialized with the validated config.

This method must be called before attempting synchronization.

Returns​

Promise<void>

A Promise that resolves when the adapter is initialized.

Throws​

When adapter instantiation or config validation fails.

Example​

const manager = new ExternalSyncManager(eventStore, eventApplierService, config);

await manager.initialize();

// Check if adapter was successfully loaded
if (manager.isInitialized()) {
  await manager.synchronize();
} else {
  console.log('No adapter available for type:', config.type);
}

synchronize()​

synchronize(credentials?, options?): Promise<SyncResult>

Defined in: components/ExternalSyncManager.ts:274

Performs synchronization with the external system using the configured adapter.

For V2 adapters, returns a combined SyncResult with push and pull counts. For legacy adapters, returns a SyncResult wrapping the push/pull operations.

Parameters​

credentials?​

ExternalSyncCredentials

Optional authentication credentials for the external system.

options?​

SyncOptions

Returns​

Promise<SyncResult>

A SyncResult with counts and any errors from the sync operation.

Throws​

When adapter is not initialized or sync operation fails.

Example​

// Simple sync without credentials (if adapter doesn't require them)
const result = await manager.synchronize();
console.log(`Pushed: ${result.pushed}, Pulled: ${result.pulled}`);

// Sync with basic authentication
const result = await manager.synchronize({
  username: 'integration_user',
  password: 'secure_password'
});

healthCheck()​

healthCheck(): Promise<HealthCheckResult>

Defined in: components/ExternalSyncManager.ts:417

Checks connectivity and health of the external system.

For V2 adapters, delegates to the adapter's healthCheck() method. For legacy adapters, returns a basic result indicating that health checks are not supported.

Returns​

Promise<HealthCheckResult>

A HealthCheckResult with status and optional latency/message.

Throws​

When adapter is not initialized.

Example​

const health = await manager.healthCheck();
if (health.healthy) {
  console.log(`External system is reachable (latency: ${health.latency}ms)`);
} else {
  console.error(`External system is down: ${health.message}`);
}

isInitialized()​

isInitialized(): boolean

Defined in: components/ExternalSyncManager.ts:446

Checks if the external sync manager has been properly initialized with an adapter.

Returns​

boolean

true if an adapter is loaded and ready for synchronization, false otherwise.

Example​

const manager = new ExternalSyncManager(eventStore, eventApplierService, config);
await manager.initialize();

if (manager.isInitialized()) {
  console.log('Ready for external sync');
} else {
  console.log('No adapter available for:', config.type);
}