@lorion-org/provider-selection 1.0.0-beta.1 → 1.0.0-beta.5

package/README.md

@@ -3,10 +3,12 @@
 `@lorion-org/provider-selection` is a small framework-free core for selecting one
 provider per capability from multiple candidates.
 
-It solves six things:
+It solves these things:
 
 - collect provider candidates by capability
+- collect provider-owned defaults from descriptors
 - collect provider preferences from descriptors or config-like records
+- collect explicit provider preferences from selected provider ids
 - optionally collect and resolve in one call
 - pick one provider with configured and fallback preferences
 - report misconfigured provider selections
@@ -15,19 +17,20 @@ It solves six things:
 Selection order is always:
 
 1. configured provider
-2. fallback provider
-3. first provider in deterministic sort order
+2. explicitly selected provider
+3. fallback provider
+4. first provider in deterministic sort order
 
 If a configured provider is set but not present among the candidates, the package
 does not silently fall back. It reports a mismatch and leaves that capability
 unselected.
 
-Playground examples in this repository:
+Example descriptors in this repository:
 
-- `packages/nuxt/playground/layer-extensions/payment-provider-stripe/extension.json`
-- `packages/nuxt/playground/layer-extensions/payment-provider-invoice/extension.json`
-- `packages/react/playground/capabilities/payment-provider-stripe/capability.json`
-- `packages/react/playground/capabilities/payment-provider-invoice/capability.json`
+- `examples/nuxt/layer-extensions/payment-provider-stripe/extension.json`
+- `examples/nuxt/layer-extensions/payment-provider-invoice/extension.json`
+- `examples/react-runtime/capabilities/payment-provider-stripe/capability.json`
+- `examples/react-runtime/capabilities/payment-provider-invoice/capability.json`
 
 It does not know anything about:
 
@@ -45,19 +48,77 @@ pnpm add @lorion-org/provider-selection
 
 ## Example
 
+Use provider-owned defaults when a provider descriptor should decide the normal
+provider for a capability:
+
+```ts
+import {
+  collectProviderDefaults,
+  resolveItemProviderSelection,
+} from '@lorion-org/provider-selection';
+
+const descriptors = [
+  { id: 'payment-provider-stripe', providesFor: 'checkout', defaultFor: 'checkout' },
+  { id: 'payment-provider-invoice', providesFor: 'checkout' },
+];
+
+const fallbackProviders = collectProviderDefaults({
+  items: descriptors,
+  getDefaultFor: (item) => item.defaultFor,
+  getProviderId: (item) => item.id,
+});
+
+const result = resolveItemProviderSelection({
+  items: descriptors,
+  getCapabilityId: (item) => item.providesFor,
+  getProviderId: (item) => item.id,
+  fallbackProviders,
+});
+```
+
+This selects Stripe with mode `fallback`. `providesFor` and `defaultFor` both
+accept a string or string array, so one provider can serve multiple capabilities.
+
+Use explicit selected providers for seed-owned overrides. This is useful when a
+host app lets users select descriptors through a normal feature or profile seed,
+and a selected descriptor is also a provider for a capability:
+
+```ts
+import {
+  collectSelectedProviderPreferences,
+  resolveItemProviderSelection,
+} from '@lorion-org/provider-selection';
+
+const selectedProviders = collectSelectedProviderPreferences({
+  items: descriptors,
+  getCapabilityId: (descriptor) => descriptor.providesFor,
+  getProviderId: (descriptor) => descriptor.id,
+  selectedProviderIds: ['payment-provider-invoice'],
+});
+
+const result = resolveItemProviderSelection({
+  items: descriptors,
+  getCapabilityId: (descriptor) => descriptor.providesFor,
+  getProviderId: (descriptor) => descriptor.id,
+  fallbackProviders,
+  selectedProviders,
+});
+```
+
+This selects Invoice with mode `selected`, even though Stripe owns the fallback
+default. Configured providers still have higher priority.
+
+Use configured providers for deployment-owned overrides:
+
 ```ts
 import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
 
 const result = resolveItemProviderSelection({
-  items: [
-    { providesFor: 'payment-checkout', id: 'payment-provider-stripe' },
-    { providesFor: 'payment-checkout', id: 'payment-provider-invoice' },
-  ],
+  items: descriptors,
   getCapabilityId: (item) => item.providesFor,
   getProviderId: (item) => item.id,
-  configuredProviders: {
-    'payment-checkout': 'payment-provider-stripe',
-  },
+  configuredProviders: { checkout: 'payment-provider-invoice' },
+  fallbackProviders,
 });
 
 result.selections;
@@ -74,27 +135,34 @@ import { resolveProviderSelection } from '@lorion-org/provider-selection';
 
 const result = resolveProviderSelection({
   providersByCapability: new Map([
-    ['payment-checkout', ['payment-provider-invoice', 'payment-provider-stripe']],
+    ['checkout', ['payment-provider-invoice', 'payment-provider-stripe']],
   ]),
   configuredProviders: {
-    'payment-checkout': 'missing-provider',
+    checkout: 'missing-provider',
   },
 });
 
 result.selections;
 result.mismatches;
-// => [{ capabilityId: 'payment-checkout', configuredProviderId: 'missing-provider' }]
+// => [{ capabilityId: 'checkout', configuredProviderId: 'missing-provider' }]
 ```
 
-If provider preferences are stored on descriptors, collect them before resolving:
+If profile or descriptor preferences are stored on descriptors, collect them as
+fallback preferences before resolving:
 
 ```ts
 import {
+  collectProviderDefaults,
   collectProviderPreferences,
   resolveItemProviderSelection,
 } from '@lorion-org/provider-selection';
 
-const configuredProviders = collectProviderPreferences({
+const providerDefaults = collectProviderDefaults({
+  items: descriptors,
+  getDefaultFor: (descriptor) => descriptor.defaultFor,
+  getProviderId: (descriptor) => descriptor.id,
+});
+const descriptorPreferences = collectProviderPreferences({
   items: descriptors,
   getProviderPreferences: (descriptor) => descriptor.providerPreferences,
 });
@@ -103,7 +171,10 @@ const result = resolveItemProviderSelection({
   items: descriptors,
   getCapabilityId: (descriptor) => descriptor.providesFor,
   getProviderId: (descriptor) => descriptor.id,
-  configuredProviders,
+  fallbackProviders: {
+    ...providerDefaults,
+    ...descriptorPreferences,
+  },
 });
 ```
 
@@ -112,9 +183,22 @@ const result = resolveItemProviderSelection({
 ```ts
 type CapabilityId = string;
 type ProviderId = string;
-type ProviderSelectionMode = 'configured' | 'fallback' | 'first';
+type ProviderSelectionMode = 'configured' | 'selected' | 'fallback' | 'first';
 type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
 type ProvidersByCapability = Map<CapabilityId, ProviderId[]>;
+type ProviderCollectionInput<T> = {
+  items: Iterable<T>;
+  getCapabilityId: (item: T) => unknown;
+  getProviderId: (item: T) => ProviderId;
+};
+type SelectedProviderPreferenceCollectionInput<T> = ProviderCollectionInput<T> & {
+  selectedProviderIds: Iterable<ProviderId>;
+};
+type ProviderDefaultCollectionInput<T> = {
+  items: Iterable<T>;
+  getDefaultFor: (item: T) => unknown;
+  getProviderId: (item: T) => ProviderId;
+};
 
 type ProviderSelection = {
   capabilityId: CapabilityId;
@@ -141,9 +225,12 @@ type ItemProviderSelectionResolution = ProviderSelectionResolution & {
 
 The package exposes:
 
+- `collectProviderDefaults()`
 - `collectProviderPreferences()`
 - `collectProvidersByCapability()`
+- `collectSelectedProviderPreferences()`
 - `resolveItemProviderSelection()`
+- `resolveSelectedProviderRelationPreferences()`
 - `resolveProviderSelection()`
 
 ## Local commands

package/dist/index.cjs

@@ -20,15 +20,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  collectProviderDefaults: () => collectProviderDefaults,
   collectProviderPreferences: () => collectProviderPreferences,
   collectProvidersByCapability: () => collectProvidersByCapability,
+  collectSelectedProviderPreferences: () => collectSelectedProviderPreferences,
   resolveItemProviderSelection: () => resolveItemProviderSelection,
-  resolveProviderSelection: () => resolveProviderSelection
+  resolveProviderSelection: () => resolveProviderSelection,
+  resolveSelectedProviderRelationPreferences: () => resolveSelectedProviderRelationPreferences
 });
 module.exports = __toCommonJS(index_exports);
 function toSortedUniqueProviderIds(providerIds) {
   return Array.from(new Set(Array.from(providerIds).filter(Boolean))).sort();
 }
+function toCapabilityIds(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -47,6 +54,13 @@ function getSelectedProvider(input) {
     }
     return void 0;
   }
+  const selectedProviderId = input.selectedProviders?.[input.capabilityId];
+  if (selectedProviderId && input.candidateProviderIds.includes(selectedProviderId)) {
+    return {
+      selectedProviderId,
+      mode: "selected"
+    };
+  }
   const fallbackProviderId = input.fallbackProviders?.[input.capabilityId];
   if (fallbackProviderId && input.candidateProviderIds.includes(fallbackProviderId)) {
     return {
@@ -69,7 +83,8 @@ function selectProviders(input) {
       capabilityId,
       candidateProviderIds: normalizedCandidateProviderIds,
       ...input.configuredProviders ? { configuredProviders: input.configuredProviders } : {},
-      ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}
+      ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {},
+      ...input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}
     });
     if (!selected) {
       continue;
@@ -124,14 +139,13 @@ function getExcludedProviders(selections) {
 function collectProvidersByCapability(input) {
   const providersByCapability = /* @__PURE__ */ new Map();
   for (const item of input.items) {
-    const capabilityId = input.getCapabilityId(item);
-    if (!capabilityId) {
-      continue;
-    }
     const providerId = input.getProviderId(item);
-    const currentProviderIds = providersByCapability.get(capabilityId) ?? [];
-    currentProviderIds.push(providerId);
-    providersByCapability.set(capabilityId, toSortedUniqueProviderIds(currentProviderIds));
+    const capabilityIds = toCapabilityIds(input.getCapabilityId(item));
+    for (const capabilityId of capabilityIds) {
+      const currentProviderIds = providersByCapability.get(capabilityId) ?? [];
+      currentProviderIds.push(providerId);
+      providersByCapability.set(capabilityId, toSortedUniqueProviderIds(currentProviderIds));
+    }
   }
   return providersByCapability;
 }
@@ -151,6 +165,52 @@ function collectProviderPreferences(input) {
   }
   return preferences;
 }
+function normalizeDefaultFor(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function collectProviderDefaults(input) {
+  let defaults = {};
+  for (const item of input.items) {
+    const providerId = input.getProviderId(item);
+    const capabilityIds = normalizeDefaultFor(input.getDefaultFor(item));
+    defaults = {
+      ...defaults,
+      ...Object.fromEntries(capabilityIds.map((capabilityId) => [capabilityId, providerId]))
+    };
+  }
+  return defaults;
+}
+function collectSelectedProviderPreferences(input) {
+  const selectedProviderIds = new Set(input.selectedProviderIds);
+  const selectedItems = Array.from(input.items).filter((item) => selectedProviderIds.has(input.getProviderId(item))).sort((left, right) => input.getProviderId(left).localeCompare(input.getProviderId(right)));
+  const preferences = {};
+  for (const item of selectedItems) {
+    const providerId = input.getProviderId(item);
+    for (const capabilityId of toCapabilityIds(input.getCapabilityId(item))) {
+      if (!preferences[capabilityId]) {
+        preferences[capabilityId] = providerId;
+      }
+    }
+  }
+  return preferences;
+}
+function resolveSelectedProviderRelationPreferences(input) {
+  const selectedProviders = input.selectedProviders ?? {};
+  const selectedCapabilityIds = new Set(Object.keys(selectedProviders));
+  const defaultFor = toCapabilityIds(input.defaultFor).filter(
+    (capabilityId) => !selectedProviders[capabilityId] || selectedProviders[capabilityId] === input.providerId
+  );
+  const providerPreferences = Object.fromEntries(
+    Object.entries(input.providerPreferences ?? {}).filter(
+      ([capabilityId]) => !selectedCapabilityIds.has(capabilityId)
+    )
+  );
+  return {
+    ...defaultFor.length ? { defaultFor: Array.isArray(input.defaultFor) ? defaultFor : defaultFor[0] } : {},
+    ...Object.keys(providerPreferences).length ? { providerPreferences } : {}
+  };
+}
 function resolveProviderSelection(input) {
   const selections = selectProviders(input);
   const mismatches = findConfiguredProviderMismatches(input);
@@ -166,7 +226,8 @@ function resolveItemProviderSelection(input) {
   const resolution = resolveProviderSelection({
     providersByCapability,
     ...input.configuredProviders ? { configuredProviders: input.configuredProviders } : {},
-    ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}
+    ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {},
+    ...input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}
   });
   return {
     providersByCapability,
@@ -175,8 +236,11 @@ function resolveItemProviderSelection(input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  collectProviderDefaults,
   collectProviderPreferences,
   collectProvidersByCapability,
+  collectSelectedProviderPreferences,
   resolveItemProviderSelection,
-  resolveProviderSelection
+  resolveProviderSelection,
+  resolveSelectedProviderRelationPreferences
 });

package/dist/index.d.cts

@@ -1,11 +1,29 @@
 type CapabilityId = string;
 type ProviderId = string;
-type ProviderSelectionMode = 'configured' | 'fallback' | 'first';
+type ProviderSelectionMode = 'configured' | 'selected' | 'fallback' | 'first';
 type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
 type ProviderPreferenceCollectionInput<T> = {
     items: Iterable<T>;
     getProviderPreferences: (item: T) => unknown;
 };
+type ProviderDefaultCollectionInput<T> = {
+    items: Iterable<T>;
+    getDefaultFor: (item: T) => unknown;
+    getProviderId: (item: T) => ProviderId;
+};
+type SelectedProviderPreferenceCollectionInput<T> = ProviderCollectionInput<T> & {
+    selectedProviderIds: Iterable<ProviderId>;
+};
+type SelectedProviderRelationPreferenceInput = {
+    defaultFor?: CapabilityId | CapabilityId[] | undefined;
+    providerId: ProviderId;
+    providerPreferences?: ProviderPreferenceMap | undefined;
+    selectedProviders?: ProviderPreferenceMap;
+};
+type SelectedProviderRelationPreferences = {
+    defaultFor?: CapabilityId | CapabilityId[];
+    providerPreferences?: ProviderPreferenceMap;
+};
 type ProviderSelection = {
     capabilityId: CapabilityId;
     selectedProviderId: ProviderId;
@@ -27,21 +45,26 @@ type ItemProviderSelectionResolution = ProviderSelectionResolution & {
 };
 type ProviderCollectionInput<T> = {
     items: Iterable<T>;
-    getCapabilityId: (item: T) => CapabilityId | undefined;
+    getCapabilityId: (item: T) => CapabilityId | CapabilityId[] | undefined;
     getProviderId: (item: T) => ProviderId;
 };
 type ResolveProviderSelectionInput = {
     providersByCapability: ProvidersByCapability;
     configuredProviders?: ProviderPreferenceMap;
     fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 type ResolveItemProviderSelectionInput<T> = ProviderCollectionInput<T> & {
     configuredProviders?: ProviderPreferenceMap;
     fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 declare function collectProvidersByCapability<T>(input: ProviderCollectionInput<T>): ProvidersByCapability;
 declare function collectProviderPreferences<T>(input: ProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
+declare function collectProviderDefaults<T>(input: ProviderDefaultCollectionInput<T>): ProviderPreferenceMap;
+declare function collectSelectedProviderPreferences<T>(input: SelectedProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
+declare function resolveSelectedProviderRelationPreferences(input: SelectedProviderRelationPreferenceInput): SelectedProviderRelationPreferences;
 declare function resolveProviderSelection(input: ResolveProviderSelectionInput): ProviderSelectionResolution;
 declare function resolveItemProviderSelection<T>(input: ResolveItemProviderSelectionInput<T>): ItemProviderSelectionResolution;
 
-export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderId, type ProviderMismatch, type ProviderPreferenceCollectionInput, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, collectProviderPreferences, collectProvidersByCapability, resolveItemProviderSelection, resolveProviderSelection };
+export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderDefaultCollectionInput, type ProviderId, type ProviderMismatch, type ProviderPreferenceCollectionInput, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, type SelectedProviderPreferenceCollectionInput, type SelectedProviderRelationPreferenceInput, type SelectedProviderRelationPreferences, collectProviderDefaults, collectProviderPreferences, collectProvidersByCapability, collectSelectedProviderPreferences, resolveItemProviderSelection, resolveProviderSelection, resolveSelectedProviderRelationPreferences };

package/dist/index.d.ts

@@ -1,11 +1,29 @@
 type CapabilityId = string;
 type ProviderId = string;
-type ProviderSelectionMode = 'configured' | 'fallback' | 'first';
+type ProviderSelectionMode = 'configured' | 'selected' | 'fallback' | 'first';
 type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
 type ProviderPreferenceCollectionInput<T> = {
     items: Iterable<T>;
     getProviderPreferences: (item: T) => unknown;
 };
+type ProviderDefaultCollectionInput<T> = {
+    items: Iterable<T>;
+    getDefaultFor: (item: T) => unknown;
+    getProviderId: (item: T) => ProviderId;
+};
+type SelectedProviderPreferenceCollectionInput<T> = ProviderCollectionInput<T> & {
+    selectedProviderIds: Iterable<ProviderId>;
+};
+type SelectedProviderRelationPreferenceInput = {
+    defaultFor?: CapabilityId | CapabilityId[] | undefined;
+    providerId: ProviderId;
+    providerPreferences?: ProviderPreferenceMap | undefined;
+    selectedProviders?: ProviderPreferenceMap;
+};
+type SelectedProviderRelationPreferences = {
+    defaultFor?: CapabilityId | CapabilityId[];
+    providerPreferences?: ProviderPreferenceMap;
+};
 type ProviderSelection = {
     capabilityId: CapabilityId;
     selectedProviderId: ProviderId;
@@ -27,21 +45,26 @@ type ItemProviderSelectionResolution = ProviderSelectionResolution & {
 };
 type ProviderCollectionInput<T> = {
     items: Iterable<T>;
-    getCapabilityId: (item: T) => CapabilityId | undefined;
+    getCapabilityId: (item: T) => CapabilityId | CapabilityId[] | undefined;
     getProviderId: (item: T) => ProviderId;
 };
 type ResolveProviderSelectionInput = {
     providersByCapability: ProvidersByCapability;
     configuredProviders?: ProviderPreferenceMap;
     fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 type ResolveItemProviderSelectionInput<T> = ProviderCollectionInput<T> & {
     configuredProviders?: ProviderPreferenceMap;
     fallbackProviders?: ProviderPreferenceMap;
+    selectedProviders?: ProviderPreferenceMap;
 };
 declare function collectProvidersByCapability<T>(input: ProviderCollectionInput<T>): ProvidersByCapability;
 declare function collectProviderPreferences<T>(input: ProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
+declare function collectProviderDefaults<T>(input: ProviderDefaultCollectionInput<T>): ProviderPreferenceMap;
+declare function collectSelectedProviderPreferences<T>(input: SelectedProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
+declare function resolveSelectedProviderRelationPreferences(input: SelectedProviderRelationPreferenceInput): SelectedProviderRelationPreferences;
 declare function resolveProviderSelection(input: ResolveProviderSelectionInput): ProviderSelectionResolution;
 declare function resolveItemProviderSelection<T>(input: ResolveItemProviderSelectionInput<T>): ItemProviderSelectionResolution;
 
-export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderId, type ProviderMismatch, type ProviderPreferenceCollectionInput, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, collectProviderPreferences, collectProvidersByCapability, resolveItemProviderSelection, resolveProviderSelection };
+export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderDefaultCollectionInput, type ProviderId, type ProviderMismatch, type ProviderPreferenceCollectionInput, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, type SelectedProviderPreferenceCollectionInput, type SelectedProviderRelationPreferenceInput, type SelectedProviderRelationPreferences, collectProviderDefaults, collectProviderPreferences, collectProvidersByCapability, collectSelectedProviderPreferences, resolveItemProviderSelection, resolveProviderSelection, resolveSelectedProviderRelationPreferences };

package/dist/index.js

@@ -2,6 +2,10 @@
 function toSortedUniqueProviderIds(providerIds) {
   return Array.from(new Set(Array.from(providerIds).filter(Boolean))).sort();
 }
+function toCapabilityIds(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -20,6 +24,13 @@ function getSelectedProvider(input) {
     }
     return void 0;
   }
+  const selectedProviderId = input.selectedProviders?.[input.capabilityId];
+  if (selectedProviderId && input.candidateProviderIds.includes(selectedProviderId)) {
+    return {
+      selectedProviderId,
+      mode: "selected"
+    };
+  }
   const fallbackProviderId = input.fallbackProviders?.[input.capabilityId];
   if (fallbackProviderId && input.candidateProviderIds.includes(fallbackProviderId)) {
     return {
@@ -42,7 +53,8 @@ function selectProviders(input) {
       capabilityId,
       candidateProviderIds: normalizedCandidateProviderIds,
       ...input.configuredProviders ? { configuredProviders: input.configuredProviders } : {},
-      ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}
+      ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {},
+      ...input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}
     });
     if (!selected) {
       continue;
@@ -97,14 +109,13 @@ function getExcludedProviders(selections) {
 function collectProvidersByCapability(input) {
   const providersByCapability = /* @__PURE__ */ new Map();
   for (const item of input.items) {
-    const capabilityId = input.getCapabilityId(item);
-    if (!capabilityId) {
-      continue;
-    }
     const providerId = input.getProviderId(item);
-    const currentProviderIds = providersByCapability.get(capabilityId) ?? [];
-    currentProviderIds.push(providerId);
-    providersByCapability.set(capabilityId, toSortedUniqueProviderIds(currentProviderIds));
+    const capabilityIds = toCapabilityIds(input.getCapabilityId(item));
+    for (const capabilityId of capabilityIds) {
+      const currentProviderIds = providersByCapability.get(capabilityId) ?? [];
+      currentProviderIds.push(providerId);
+      providersByCapability.set(capabilityId, toSortedUniqueProviderIds(currentProviderIds));
+    }
   }
   return providersByCapability;
 }
@@ -124,6 +135,52 @@ function collectProviderPreferences(input) {
   }
   return preferences;
 }
+function normalizeDefaultFor(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  return entries.filter((entry) => typeof entry === "string" && entry.length > 0);
+}
+function collectProviderDefaults(input) {
+  let defaults = {};
+  for (const item of input.items) {
+    const providerId = input.getProviderId(item);
+    const capabilityIds = normalizeDefaultFor(input.getDefaultFor(item));
+    defaults = {
+      ...defaults,
+      ...Object.fromEntries(capabilityIds.map((capabilityId) => [capabilityId, providerId]))
+    };
+  }
+  return defaults;
+}
+function collectSelectedProviderPreferences(input) {
+  const selectedProviderIds = new Set(input.selectedProviderIds);
+  const selectedItems = Array.from(input.items).filter((item) => selectedProviderIds.has(input.getProviderId(item))).sort((left, right) => input.getProviderId(left).localeCompare(input.getProviderId(right)));
+  const preferences = {};
+  for (const item of selectedItems) {
+    const providerId = input.getProviderId(item);
+    for (const capabilityId of toCapabilityIds(input.getCapabilityId(item))) {
+      if (!preferences[capabilityId]) {
+        preferences[capabilityId] = providerId;
+      }
+    }
+  }
+  return preferences;
+}
+function resolveSelectedProviderRelationPreferences(input) {
+  const selectedProviders = input.selectedProviders ?? {};
+  const selectedCapabilityIds = new Set(Object.keys(selectedProviders));
+  const defaultFor = toCapabilityIds(input.defaultFor).filter(
+    (capabilityId) => !selectedProviders[capabilityId] || selectedProviders[capabilityId] === input.providerId
+  );
+  const providerPreferences = Object.fromEntries(
+    Object.entries(input.providerPreferences ?? {}).filter(
+      ([capabilityId]) => !selectedCapabilityIds.has(capabilityId)
+    )
+  );
+  return {
+    ...defaultFor.length ? { defaultFor: Array.isArray(input.defaultFor) ? defaultFor : defaultFor[0] } : {},
+    ...Object.keys(providerPreferences).length ? { providerPreferences } : {}
+  };
+}
 function resolveProviderSelection(input) {
   const selections = selectProviders(input);
   const mismatches = findConfiguredProviderMismatches(input);
@@ -139,7 +196,8 @@ function resolveItemProviderSelection(input) {
   const resolution = resolveProviderSelection({
     providersByCapability,
     ...input.configuredProviders ? { configuredProviders: input.configuredProviders } : {},
-    ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}
+    ...input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {},
+    ...input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}
   });
   return {
     providersByCapability,
@@ -147,8 +205,11 @@ function resolveItemProviderSelection(input) {
   };
 }
 export {
+  collectProviderDefaults,
   collectProviderPreferences,
   collectProvidersByCapability,
+  collectSelectedProviderPreferences,
   resolveItemProviderSelection,
-  resolveProviderSelection
+  resolveProviderSelection,
+  resolveSelectedProviderRelationPreferences
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/provider-selection",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.5",
   "description": "Framework-free capability provider selection primitives.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -34,8 +38,9 @@
   },
   "files": [
     "dist",
-    "examples",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "provider",

package/src/index.ts

@@ -0,0 +1,355 @@
+export type CapabilityId = string;
+export type ProviderId = string;
+
+export type ProviderSelectionMode = 'configured' | 'selected' | 'fallback' | 'first';
+export type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
+export type ProviderPreferenceCollectionInput<T> = {
+  items: Iterable<T>;
+  getProviderPreferences: (item: T) => unknown;
+};
+export type ProviderDefaultCollectionInput<T> = {
+  items: Iterable<T>;
+  getDefaultFor: (item: T) => unknown;
+  getProviderId: (item: T) => ProviderId;
+};
+export type SelectedProviderPreferenceCollectionInput<T> = ProviderCollectionInput<T> & {
+  selectedProviderIds: Iterable<ProviderId>;
+};
+export type SelectedProviderRelationPreferenceInput = {
+  defaultFor?: CapabilityId | CapabilityId[] | undefined;
+  providerId: ProviderId;
+  providerPreferences?: ProviderPreferenceMap | undefined;
+  selectedProviders?: ProviderPreferenceMap;
+};
+
+export type SelectedProviderRelationPreferences = {
+  defaultFor?: CapabilityId | CapabilityId[];
+  providerPreferences?: ProviderPreferenceMap;
+};
+
+export type ProviderSelection = {
+  capabilityId: CapabilityId;
+  selectedProviderId: ProviderId;
+  candidateProviderIds: ProviderId[];
+  mode: ProviderSelectionMode;
+};
+
+export type ProviderMismatch = {
+  capabilityId: CapabilityId;
+  configuredProviderId: ProviderId;
+};
+
+export type ProvidersByCapability = Map<CapabilityId, ProviderId[]>;
+
+export type ProviderSelectionResolution = {
+  selections: Map<CapabilityId, ProviderSelection>;
+  mismatches: ProviderMismatch[];
+  excludedProviderIds: ProviderId[];
+};
+export type ItemProviderSelectionResolution = ProviderSelectionResolution & {
+  providersByCapability: ProvidersByCapability;
+};
+
+type ProviderCollectionInput<T> = {
+  items: Iterable<T>;
+  getCapabilityId: (item: T) => CapabilityId | CapabilityId[] | undefined;
+  getProviderId: (item: T) => ProviderId;
+};
+
+export type ResolveProviderSelectionInput = {
+  providersByCapability: ProvidersByCapability;
+  configuredProviders?: ProviderPreferenceMap;
+  fallbackProviders?: ProviderPreferenceMap;
+  selectedProviders?: ProviderPreferenceMap;
+};
+
+export type ResolveItemProviderSelectionInput<T> = ProviderCollectionInput<T> & {
+  configuredProviders?: ProviderPreferenceMap;
+  fallbackProviders?: ProviderPreferenceMap;
+  selectedProviders?: ProviderPreferenceMap;
+};
+
+function toSortedUniqueProviderIds(providerIds: Iterable<ProviderId>): ProviderId[] {
+  return Array.from(new Set(Array.from(providerIds).filter(Boolean))).sort();
+}
+
+function toCapabilityIds(value: CapabilityId | CapabilityId[] | undefined): CapabilityId[] {
+  const entries = Array.isArray(value) ? value : [value];
+
+  return entries.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getSelectedProvider(input: {
+  capabilityId: CapabilityId;
+  candidateProviderIds: ProviderId[];
+  configuredProviders?: ProviderPreferenceMap;
+  fallbackProviders?: ProviderPreferenceMap;
+  selectedProviders?: ProviderPreferenceMap;
+}): { selectedProviderId: ProviderId; mode: ProviderSelectionMode } | undefined {
+  const firstProviderId = input.candidateProviderIds[0];
+  if (!firstProviderId) {
+    return undefined;
+  }
+
+  const configuredProviderId = input.configuredProviders?.[input.capabilityId];
+  if (configuredProviderId) {
+    if (input.candidateProviderIds.includes(configuredProviderId)) {
+      return {
+        selectedProviderId: configuredProviderId,
+        mode: 'configured',
+      };
+    }
+
+    return undefined;
+  }
+
+  const selectedProviderId = input.selectedProviders?.[input.capabilityId];
+  if (selectedProviderId && input.candidateProviderIds.includes(selectedProviderId)) {
+    return {
+      selectedProviderId,
+      mode: 'selected',
+    };
+  }
+
+  const fallbackProviderId = input.fallbackProviders?.[input.capabilityId];
+  if (fallbackProviderId && input.candidateProviderIds.includes(fallbackProviderId)) {
+    return {
+      selectedProviderId: fallbackProviderId,
+      mode: 'fallback',
+    };
+  }
+
+  return {
+    selectedProviderId: firstProviderId,
+    mode: 'first',
+  };
+}
+
+function selectProviders(
+  input: ResolveProviderSelectionInput,
+): Map<CapabilityId, ProviderSelection> {
+  const selections: Map<CapabilityId, ProviderSelection> = new Map();
+
+  for (const [capabilityId, candidateProviderIds] of Array.from(
+    input.providersByCapability.entries(),
+  ).sort(([left], [right]) => left.localeCompare(right))) {
+    const normalizedCandidateProviderIds = toSortedUniqueProviderIds(candidateProviderIds);
+    const selected = getSelectedProvider({
+      capabilityId,
+      candidateProviderIds: normalizedCandidateProviderIds,
+      ...(input.configuredProviders ? { configuredProviders: input.configuredProviders } : {}),
+      ...(input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}),
+      ...(input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}),
+    });
+
+    if (!selected) {
+      continue;
+    }
+
+    selections.set(capabilityId, {
+      capabilityId,
+      selectedProviderId: selected.selectedProviderId,
+      candidateProviderIds: normalizedCandidateProviderIds,
+      mode: selected.mode,
+    });
+  }
+
+  return selections;
+}
+
+function findConfiguredProviderMismatches(
+  input: ResolveProviderSelectionInput,
+): ProviderMismatch[] {
+  const mismatches: ProviderMismatch[] = [];
+
+  for (const [capabilityId, configuredProviderId] of Object.entries(
+    input.configuredProviders ?? {},
+  ).sort(([left], [right]) => left.localeCompare(right))) {
+    if (!configuredProviderId) {
+      continue;
+    }
+
+    const candidateProviderIds = toSortedUniqueProviderIds(
+      input.providersByCapability.get(capabilityId) ?? [],
+    );
+    if (!candidateProviderIds.length) {
+      continue;
+    }
+
+    if (candidateProviderIds.includes(configuredProviderId)) {
+      continue;
+    }
+
+    mismatches.push({
+      capabilityId,
+      configuredProviderId,
+    });
+  }
+
+  return mismatches;
+}
+
+function getExcludedProviders(selections: Iterable<ProviderSelection>): ProviderId[] {
+  const excludedProviderIds: ProviderId[] = [];
+
+  for (const selection of selections) {
+    if (selection.candidateProviderIds.length <= 1) {
+      continue;
+    }
+
+    for (const candidateProviderId of selection.candidateProviderIds) {
+      if (candidateProviderId !== selection.selectedProviderId) {
+        excludedProviderIds.push(candidateProviderId);
+      }
+    }
+  }
+
+  return toSortedUniqueProviderIds(excludedProviderIds);
+}
+
+export function collectProvidersByCapability<T>(
+  input: ProviderCollectionInput<T>,
+): ProvidersByCapability {
+  const providersByCapability: ProvidersByCapability = new Map();
+
+  for (const item of input.items) {
+    const providerId = input.getProviderId(item);
+    const capabilityIds = toCapabilityIds(input.getCapabilityId(item));
+
+    for (const capabilityId of capabilityIds) {
+      const currentProviderIds = providersByCapability.get(capabilityId) ?? [];
+      currentProviderIds.push(providerId);
+      providersByCapability.set(capabilityId, toSortedUniqueProviderIds(currentProviderIds));
+    }
+  }
+
+  return providersByCapability;
+}
+
+export function collectProviderPreferences<T>(
+  input: ProviderPreferenceCollectionInput<T>,
+): ProviderPreferenceMap {
+  let preferences: ProviderPreferenceMap = {};
+
+  for (const item of input.items) {
+    const value = input.getProviderPreferences(item);
+
+    if (!isRecord(value)) continue;
+
+    preferences = {
+      ...preferences,
+      ...Object.fromEntries(
+        Object.entries(value).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string' && entry[1].length > 0,
+        ),
+      ),
+    };
+  }
+
+  return preferences;
+}
+
+function normalizeDefaultFor(value: unknown): CapabilityId[] {
+  const entries = Array.isArray(value) ? value : [value];
+
+  return entries.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0);
+}
+
+export function collectProviderDefaults<T>(
+  input: ProviderDefaultCollectionInput<T>,
+): ProviderPreferenceMap {
+  let defaults: ProviderPreferenceMap = {};
+
+  for (const item of input.items) {
+    const providerId = input.getProviderId(item);
+    const capabilityIds = normalizeDefaultFor(input.getDefaultFor(item));
+
+    defaults = {
+      ...defaults,
+      ...Object.fromEntries(capabilityIds.map((capabilityId) => [capabilityId, providerId])),
+    };
+  }
+
+  return defaults;
+}
+
+export function collectSelectedProviderPreferences<T>(
+  input: SelectedProviderPreferenceCollectionInput<T>,
+): ProviderPreferenceMap {
+  const selectedProviderIds = new Set(input.selectedProviderIds);
+  const selectedItems = Array.from(input.items)
+    .filter((item) => selectedProviderIds.has(input.getProviderId(item)))
+    .sort((left, right) => input.getProviderId(left).localeCompare(input.getProviderId(right)));
+  const preferences: ProviderPreferenceMap = {};
+
+  for (const item of selectedItems) {
+    const providerId = input.getProviderId(item);
+
+    for (const capabilityId of toCapabilityIds(input.getCapabilityId(item))) {
+      if (!preferences[capabilityId]) {
+        preferences[capabilityId] = providerId;
+      }
+    }
+  }
+
+  return preferences;
+}
+
+export function resolveSelectedProviderRelationPreferences(
+  input: SelectedProviderRelationPreferenceInput,
+): SelectedProviderRelationPreferences {
+  const selectedProviders = input.selectedProviders ?? {};
+  const selectedCapabilityIds = new Set(Object.keys(selectedProviders));
+  const defaultFor = toCapabilityIds(input.defaultFor).filter(
+    (capabilityId) =>
+      !selectedProviders[capabilityId] || selectedProviders[capabilityId] === input.providerId,
+  );
+  const providerPreferences = Object.fromEntries(
+    Object.entries(input.providerPreferences ?? {}).filter(
+      ([capabilityId]) => !selectedCapabilityIds.has(capabilityId),
+    ),
+  );
+
+  return {
+    ...(defaultFor.length
+      ? { defaultFor: Array.isArray(input.defaultFor) ? defaultFor : defaultFor[0] }
+      : {}),
+    ...(Object.keys(providerPreferences).length ? { providerPreferences } : {}),
+  };
+}
+
+export function resolveProviderSelection(
+  input: ResolveProviderSelectionInput,
+): ProviderSelectionResolution {
+  const selections = selectProviders(input);
+  const mismatches = findConfiguredProviderMismatches(input);
+  const excludedProviderIds = getExcludedProviders(selections.values());
+
+  return {
+    selections,
+    mismatches,
+    excludedProviderIds,
+  };
+}
+
+export function resolveItemProviderSelection<T>(
+  input: ResolveItemProviderSelectionInput<T>,
+): ItemProviderSelectionResolution {
+  const providersByCapability = collectProvidersByCapability(input);
+
+  const resolution = resolveProviderSelection({
+    providersByCapability,
+    ...(input.configuredProviders ? { configuredProviders: input.configuredProviders } : {}),
+    ...(input.fallbackProviders ? { fallbackProviders: input.fallbackProviders } : {}),
+    ...(input.selectedProviders ? { selectedProviders: input.selectedProviders } : {}),
+  });
+
+  return {
+    providersByCapability,
+    ...resolution,
+  };
+}

package/examples/payment-checkout.ts

@@ -1,38 +0,0 @@
-import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
-
-type PaymentProviderDescriptor = {
-  id: string;
-  providesFor?: string;
-};
-
-const descriptors: PaymentProviderDescriptor[] = [
-  {
-    id: 'payment-provider-stripe',
-    providesFor: 'payment-checkout',
-  },
-  {
-    id: 'payment-provider-invoice',
-    providesFor: 'payment-checkout',
-  },
-];
-
-const result = resolveItemProviderSelection({
-  items: descriptors,
-  getCapabilityId: (descriptor) => descriptor.providesFor,
-  getProviderId: (descriptor) => descriptor.id,
-  configuredProviders: {
-    'payment-checkout': 'payment-provider-stripe',
-  },
-});
-
-console.log(result.providersByCapability);
-// Map { 'payment-checkout' => ['payment-provider-invoice', 'payment-provider-stripe'] }
-
-console.log(result.selections);
-// Map { 'payment-checkout' => { selectedProviderId: 'payment-provider-stripe', mode: 'configured', ... } }
-
-console.log(result.mismatches);
-// []
-
-console.log(result.excludedProviderIds);
-// ['payment-provider-invoice']

package/examples/provider-preferences.ts

@@ -1,42 +0,0 @@
-import {
-  collectProviderPreferences,
-  resolveItemProviderSelection,
-} from '@lorion-org/provider-selection';
-
-type PlaygroundDescriptor = {
-  id: string;
-  providerPreferences?: Record<string, string>;
-  providesFor?: string;
-};
-
-const descriptors: PlaygroundDescriptor[] = [
-  {
-    id: 'web',
-    providerPreferences: {
-      'payment-checkout': 'payment-provider-stripe',
-    },
-  },
-  {
-    id: 'payment-provider-stripe',
-    providesFor: 'payment-checkout',
-  },
-  {
-    id: 'payment-provider-invoice',
-    providesFor: 'payment-checkout',
-  },
-];
-
-const configuredProviders = collectProviderPreferences({
-  items: descriptors,
-  getProviderPreferences: (descriptor) => descriptor.providerPreferences,
-});
-
-const result = resolveItemProviderSelection({
-  items: descriptors,
-  getCapabilityId: (descriptor) => descriptor.providesFor,
-  getProviderId: (descriptor) => descriptor.id,
-  configuredProviders,
-});
-
-console.log(Object.fromEntries(result.selections));
-// { 'payment-checkout': { selectedProviderId: 'payment-provider-stripe', mode: 'configured', ... } }