feat: JS sticky resolve support with materialized assignments

[nicklasl]

Summary

Implements sticky resolve functionality for the JavaScript OpenFeature provider to ensure consistent variant assignments even when user context changes or new assignments are paused. This includes support for both local storage (MaterializationRepository) and remote fallback (ResolverFallback) strategies.

Changes

Core Implementation

• Protocol Buffers: Added sticky resolve messages (ResolveWithStickyRequest, ResolveWithStickyResponse, MaterializationInfo) to api.proto
• Strategy Interfaces: Created StickyResolveStrategy with two implementations:
  • MaterializationRepository: For local storage of materialized assignments (Redis, DB, etc.)
  • ResolverFallback: For remote API fallback when materializations are missing
• Type Guards: Added isResolverFallback() and isMaterializationRepository() for runtime type checking

Provider Integration

• Always-on Sticky Resolve: Updated ConfidenceServerProviderLocal to always use sticky resolve
• Recursive Resolution: Implemented resolveWithStickyInternal() matching Java SDK pattern
• Default Strategy: RemoteResolverFallback is now the default, simplifying setup
• Fire-and-Forget Storage: Non-blocking materialization updates for optimal performance

Remote Fallback

• RemoteResolverFallback: New class that delegates to Confidence API (https://resolver.confidence.dev/v1/flags:resolve)
• Configurable: Supports custom base URL and fetch implementation
• Automatic TTL: Server-side 90-day TTL for materializations

Utilities

• materializationUtils.ts: Extracted utility functions:
  • handleMissingMaterializations(): Bulk loads materializations from repository
  • storeUpdates(): Fire-and-forget storage of new assignments

Test Coverage

• ✅ 14 tests for StickyResolveStrategy (type guards, interface contracts)
• ✅ 16 tests for RemoteResolverFallback (remote API integration)
• ✅ 11 tests for sticky resolve in ConfidenceServerProviderLocal
• Total: 55 tests passing

API Changes

New Exports

// Strategy interfaces
export type { StickyResolveStrategy, MaterializationRepository, ResolverFallback }

// Default implementation
export { RemoteResolverFallback }
export type { RemoteResolverFallbackOptions }

// Proto types
export type { MaterializationInfo, ResolveFlagsRequest, ResolveFlagsResponse }

Provider Options

interface ProviderOptions {
  // ... existing options
  stickyResolveStrategy?: StickyResolveStrategy; // Defaults to RemoteResolverFallback
}

Usage Examples

Default (Remote Fallback)

const provider = createConfidenceServerProvider({
  flagClientSecret: 'client-secret',
  apiClientId: 'api-id',
  apiClientSecret: 'api-secret'
  // RemoteResolverFallback used automatically
});

Custom Repository

class RedisMaterializationRepository implements MaterializationRepository {
  async loadMaterializedAssignmentsForUnit(unit: string, materialization: string) {
    const data = await this.redis.get(`unit:${unit}`);
    return new Map(Object.entries(JSON.parse(data || '{}')));
  }

  async storeAssignment(unit: string, assignments: Map<string, MaterializationInfo>) {
    await this.redis.set(`unit:${unit}`, JSON.stringify(Object.fromEntries(assignments)));
  }

  close() { this.redis.disconnect(); }
}

const provider = createConfidenceServerProvider({
  flagClientSecret: 'client-secret',
  apiClientId: 'api-id',
  apiClientSecret: 'api-secret',
  stickyResolveStrategy: new RedisMaterializationRepository(redis)
});

Implementation Notes

• Matches Java SDK implementation for consistency
• Fire-and-forget storage prevents blocking flag resolution path
• Bulk loading of materializations for efficiency
• Type-safe with no non-null assertions
• Fully backward compatible (sticky resolve is transparent to users)

Test Plan

• All existing tests still pass
• New strategy type guard tests
• RemoteResolverFallback unit tests
• Provider integration tests with both strategies
• Missing materialization retry flow
• Update storage flow

🤖 Generated with Claude Code

[nicklasl]

should we remove resolveFlags() since it is never used?

[andreas-karlsson]

Yes. There's a lot we should remove from the guest interface that we never use.