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

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the 'Software'), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,9 +3,10 @@
 `@lorion-org/provider-selection` is a small framework-free core for selecting one
 provider per capability from multiple candidates.
 
-It solves four things:
+It solves six things:
 
 - collect provider candidates by capability
+- collect provider preferences from descriptors or config-like records
 - optionally collect and resolve in one call
 - pick one provider with configured and fallback preferences
 - report misconfigured provider selections
@@ -21,10 +22,12 @@ If a configured provider is set but not present among the candidates, the packag
 does not silently fall back. It reports a mismatch and leaves that capability
 unselected.
 
-Example files in this repository:
+Playground examples in this repository:
 
-- `examples/command-handlers.ts`
-- `examples/storage-drivers.ts`
+- `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`
 
 It does not know anything about:
 
@@ -47,17 +50,13 @@ import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
 
 const result = resolveItemProviderSelection({
   items: [
-    { capability: 'auth', providerId: 'keycloak' },
-    { capability: 'auth', providerId: 'auth-local-jwt' },
-    { capability: 'mailer', providerId: 'mailer-postmark' },
+    { providesFor: 'payment-checkout', id: 'payment-provider-stripe' },
+    { providesFor: 'payment-checkout', id: 'payment-provider-invoice' },
   ],
-  getCapabilityId: (item) => item.capability,
-  getProviderId: (item) => item.providerId,
+  getCapabilityId: (item) => item.providesFor,
+  getProviderId: (item) => item.id,
   configuredProviders: {
-    auth: 'keycloak',
-  },
-  fallbackProviders: {
-    mailer: 'mailer-postmark',
+    'payment-checkout': 'payment-provider-stripe',
   },
 });
 
@@ -74,52 +73,37 @@ resolver directly:
 import { resolveProviderSelection } from '@lorion-org/provider-selection';
 
 const result = resolveProviderSelection({
-  providersByCapability: new Map([['auth', ['auth-local-jwt', 'keycloak']]]),
+  providersByCapability: new Map([
+    ['payment-checkout', ['payment-provider-invoice', 'payment-provider-stripe']],
+  ]),
   configuredProviders: {
-    auth: 'missing-provider',
+    'payment-checkout': 'missing-provider',
   },
 });
 
 result.selections;
 result.mismatches;
-// => [{ capabilityId: 'auth', configuredProviderId: 'missing-provider' }]
+// => [{ capabilityId: 'payment-checkout', configuredProviderId: 'missing-provider' }]
 ```
 
-## Example: command handlers
+If provider preferences are stored on descriptors, collect them before resolving:
 
 ```ts
-import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
-
-const result = resolveItemProviderSelection({
-  items: [
-    { commandId: 'open', handlerId: 'open-native' },
-    { commandId: 'open', handlerId: 'open-web' },
-    { commandId: 'share', handlerId: 'share-link' },
-  ],
-  getCapabilityId: (item) => item.commandId,
-  getProviderId: (item) => item.handlerId,
-  configuredProviders: {
-    open: 'open-web',
-  },
+import {
+  collectProviderPreferences,
+  resolveItemProviderSelection,
+} from '@lorion-org/provider-selection';
+
+const configuredProviders = collectProviderPreferences({
+  items: descriptors,
+  getProviderPreferences: (descriptor) => descriptor.providerPreferences,
 });
-```
-
-## Example: storage drivers
-
-```ts
-import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
 
 const result = resolveItemProviderSelection({
-  items: [
-    { storageKind: 'blob', driverId: 's3' },
-    { storageKind: 'blob', driverId: 'filesystem' },
-    { storageKind: 'queue', driverId: 'redis-streams' },
-  ],
-  getCapabilityId: (item) => item.storageKind,
-  getProviderId: (item) => item.driverId,
-  fallbackProviders: {
-    blob: 'filesystem',
-  },
+  items: descriptors,
+  getCapabilityId: (descriptor) => descriptor.providesFor,
+  getProviderId: (descriptor) => descriptor.id,
+  configuredProviders,
 });
 ```
 
@@ -157,6 +141,7 @@ type ItemProviderSelectionResolution = ProviderSelectionResolution & {
 
 The package exposes:
 
+- `collectProviderPreferences()`
 - `collectProvidersByCapability()`
 - `resolveItemProviderSelection()`
 - `resolveProviderSelection()`

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  collectProviderPreferences: () => collectProviderPreferences,
   collectProvidersByCapability: () => collectProvidersByCapability,
   resolveItemProviderSelection: () => resolveItemProviderSelection,
   resolveProviderSelection: () => resolveProviderSelection
@@ -28,6 +29,9 @@ module.exports = __toCommonJS(index_exports);
 function toSortedUniqueProviderIds(providerIds) {
   return Array.from(new Set(Array.from(providerIds).filter(Boolean))).sort();
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function getSelectedProvider(input) {
   const firstProviderId = input.candidateProviderIds[0];
   if (!firstProviderId) {
@@ -131,6 +135,22 @@ function collectProvidersByCapability(input) {
   }
   return providersByCapability;
 }
+function collectProviderPreferences(input) {
+  let preferences = {};
+  for (const item of input.items) {
+    const value = input.getProviderPreferences(item);
+    if (!isRecord(value)) continue;
+    preferences = {
+      ...preferences,
+      ...Object.fromEntries(
+        Object.entries(value).filter(
+          (entry) => typeof entry[1] === "string" && entry[1].length > 0
+        )
+      )
+    };
+  }
+  return preferences;
+}
 function resolveProviderSelection(input) {
   const selections = selectProviders(input);
   const mismatches = findConfiguredProviderMismatches(input);
@@ -155,6 +175,7 @@ function resolveItemProviderSelection(input) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  collectProviderPreferences,
   collectProvidersByCapability,
   resolveItemProviderSelection,
   resolveProviderSelection

package/dist/index.d.cts

@@ -2,6 +2,10 @@ type CapabilityId = string;
 type ProviderId = string;
 type ProviderSelectionMode = 'configured' | 'fallback' | 'first';
 type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
+type ProviderPreferenceCollectionInput<T> = {
+    items: Iterable<T>;
+    getProviderPreferences: (item: T) => unknown;
+};
 type ProviderSelection = {
     capabilityId: CapabilityId;
     selectedProviderId: ProviderId;
@@ -36,7 +40,8 @@ type ResolveItemProviderSelectionInput<T> = ProviderCollectionInput<T> & {
     fallbackProviders?: ProviderPreferenceMap;
 };
 declare function collectProvidersByCapability<T>(input: ProviderCollectionInput<T>): ProvidersByCapability;
+declare function collectProviderPreferences<T>(input: ProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
 declare function resolveProviderSelection(input: ResolveProviderSelectionInput): ProviderSelectionResolution;
 declare function resolveItemProviderSelection<T>(input: ResolveItemProviderSelectionInput<T>): ItemProviderSelectionResolution;
 
-export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderId, type ProviderMismatch, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, collectProvidersByCapability, resolveItemProviderSelection, resolveProviderSelection };
+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 };

package/dist/index.d.ts

@@ -2,6 +2,10 @@ type CapabilityId = string;
 type ProviderId = string;
 type ProviderSelectionMode = 'configured' | 'fallback' | 'first';
 type ProviderPreferenceMap = Partial<Record<CapabilityId, ProviderId>>;
+type ProviderPreferenceCollectionInput<T> = {
+    items: Iterable<T>;
+    getProviderPreferences: (item: T) => unknown;
+};
 type ProviderSelection = {
     capabilityId: CapabilityId;
     selectedProviderId: ProviderId;
@@ -36,7 +40,8 @@ type ResolveItemProviderSelectionInput<T> = ProviderCollectionInput<T> & {
     fallbackProviders?: ProviderPreferenceMap;
 };
 declare function collectProvidersByCapability<T>(input: ProviderCollectionInput<T>): ProvidersByCapability;
+declare function collectProviderPreferences<T>(input: ProviderPreferenceCollectionInput<T>): ProviderPreferenceMap;
 declare function resolveProviderSelection(input: ResolveProviderSelectionInput): ProviderSelectionResolution;
 declare function resolveItemProviderSelection<T>(input: ResolveItemProviderSelectionInput<T>): ItemProviderSelectionResolution;
 
-export { type CapabilityId, type ItemProviderSelectionResolution, type ProviderId, type ProviderMismatch, type ProviderPreferenceMap, type ProviderSelection, type ProviderSelectionMode, type ProviderSelectionResolution, type ProvidersByCapability, type ResolveItemProviderSelectionInput, type ResolveProviderSelectionInput, collectProvidersByCapability, resolveItemProviderSelection, resolveProviderSelection };
+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 };

package/dist/index.js

@@ -2,6 +2,9 @@
 function toSortedUniqueProviderIds(providerIds) {
   return Array.from(new Set(Array.from(providerIds).filter(Boolean))).sort();
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function getSelectedProvider(input) {
   const firstProviderId = input.candidateProviderIds[0];
   if (!firstProviderId) {
@@ -105,6 +108,22 @@ function collectProvidersByCapability(input) {
   }
   return providersByCapability;
 }
+function collectProviderPreferences(input) {
+  let preferences = {};
+  for (const item of input.items) {
+    const value = input.getProviderPreferences(item);
+    if (!isRecord(value)) continue;
+    preferences = {
+      ...preferences,
+      ...Object.fromEntries(
+        Object.entries(value).filter(
+          (entry) => typeof entry[1] === "string" && entry[1].length > 0
+        )
+      )
+    };
+  }
+  return preferences;
+}
 function resolveProviderSelection(input) {
   const selections = selectProviders(input);
   const mismatches = findConfiguredProviderMismatches(input);
@@ -128,6 +147,7 @@ function resolveItemProviderSelection(input) {
   };
 }
 export {
+  collectProviderPreferences,
   collectProvidersByCapability,
   resolveItemProviderSelection,
   resolveProviderSelection

package/examples/payment-checkout.ts

@@ -0,0 +1,38 @@
+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

@@ -0,0 +1,42 @@
+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', ... } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/provider-selection",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "description": "Framework-free capability provider selection primitives.",
   "license": "MIT",
   "repository": {

package/examples/command-handlers.ts

@@ -1,45 +0,0 @@
-import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
-
-type CommandHandler = {
-  commandId: string;
-  handlerId: string;
-};
-
-const handlers: CommandHandler[] = [
-  {
-    commandId: 'open',
-    handlerId: 'open-native',
-  },
-  {
-    commandId: 'open',
-    handlerId: 'open-web',
-  },
-  {
-    commandId: 'share',
-    handlerId: 'share-link',
-  },
-];
-
-const result = resolveItemProviderSelection({
-  items: handlers,
-  getCapabilityId: (handler) => handler.commandId,
-  getProviderId: (handler) => handler.handlerId,
-  configuredProviders: {
-    open: 'open-web',
-  },
-});
-
-console.log(result.providersByCapability);
-// { open: ['open-native', 'open-web'], share: ['share-link'] }
-
-console.log(result.selections);
-// {
-//   open: { selectedProviderId: 'open-web', mode: 'configured' },
-//   share: { selectedProviderId: 'share-link', mode: 'first' }
-// }
-
-console.log(result.mismatches);
-// []
-
-console.log(result.excludedProviderIds);
-// ['open-native']

package/examples/storage-drivers.ts

@@ -1,39 +0,0 @@
-import { resolveItemProviderSelection } from '@lorion-org/provider-selection';
-
-type StorageDriver = {
-  storageKind: string;
-  driverId: string;
-};
-
-const drivers: StorageDriver[] = [
-  {
-    storageKind: 'blob',
-    driverId: 's3',
-  },
-  {
-    storageKind: 'blob',
-    driverId: 'filesystem',
-  },
-  {
-    storageKind: 'queue',
-    driverId: 'redis-streams',
-  },
-];
-
-const result = resolveItemProviderSelection({
-  items: drivers,
-  getCapabilityId: (driver) => driver.storageKind,
-  getProviderId: (driver) => driver.driverId,
-  fallbackProviders: {
-    blob: 'filesystem',
-  },
-});
-
-console.log(result.selections);
-// {
-//   blob: { selectedProviderId: 'filesystem', mode: 'fallback' },
-//   queue: { selectedProviderId: 'redis-streams', mode: 'first' }
-// }
-
-console.log(result.mismatches);
-// []