Introduce Enriched Control Option

The changes to the value object will let it carry on extra data among
the business logic.

This permits third parties to fill in extra information to consume
during the presentation.

Due to the need to include an additional Data Structure the changes
involve the re-organization of the Value Objects and the Data
Structures, previously mixed under the `vo` directory.

fix #36

@types/index.d.ts

@@ -42,11 +42,6 @@ declare namespace EntitiesSearch {
 		queryArguments?: EntitiesSearch.QueryArguments<E>
 	) => Promise<Options<E>>;
 
-	type ControlOption<V extends any> = Readonly<{
-		value: V;
-		label: string;
-	}>;
-
 	type SingularControl<V> = {
 		[K in keyof BaseControl<V>]: K extends 'value'
 			? V
@@ -55,6 +50,20 @@ declare namespace EntitiesSearch {
 			: BaseControl<V>[K];
 	};
 
+	interface Record<T> {
+		get<F>(key: string, fallback?: F): T | F | undefined;
+		set(key: string, value: T): Record<T>;
+	}
+
+	interface ControlOption<V extends any> extends Readonly<{
+		value: V;
+		label: string;
+	}> {}
+
+	interface EnrichedControlOption<V extends any> extends ControlOption<V>, Readonly<{
+		readonly extra: Record<string, unknown>;
+	}> {}
+
 	interface BaseControl<V>
 		extends Readonly<{
 			value: Set<V>;

sources/client/src/api/search-entities.ts

@@ -13,7 +13,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { abortControllers } from '../services/abort-controllers';
 import { ContextualAbortController } from '../services/contextual-abort-controller';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { fetch } from './fetch';
 
 export async function searchEntities< E >(

sources/client/src/components/composite-entities-by-kind.tsx

@@ -16,7 +16,7 @@ import { useEntitiesOptionsStorage } from '../hooks/use-entities-options-storage
 import { useSearch } from '../hooks/use-search';
 import { orderSelectedOptionsAtTheTop } from '../utils/order-selected-options-at-the-top';
 import { uniqueControlOptions } from '../utils/unique-control-options';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 /**
  * A composite component that provides a way to search for entities by kind.

sources/client/src/components/plural-select-control.tsx

@@ -8,7 +8,7 @@ import React, { JSX } from 'react';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { NoOptionsMessage } from './no-options-message';
 
 export function PluralSelectControl(

sources/client/src/hooks/use-entities-options-storage.ts

@@ -14,7 +14,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { makeInitialState } from '../storage/entities/initial-state';
 import { reducer } from '../storage/entities/reducer';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 type _Reducer< E, K > = Reducer<
 	EntitiesSearch.EntitiesState< E, K >,

sources/client/src/hooks/use-entity-records.ts

@@ -11,7 +11,7 @@ import { useEntityRecords as useCoreEntityRecords } from '@wordpress/core-data';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 enum ResolveStatus {
 	ERROR = 'ERROR',

sources/client/src/hooks/use-query-viewable-post-types.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { useEntityRecords } from './use-entity-records';
 
 /**

sources/client/src/hooks/use-query-viewable-taxonomies.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { useEntityRecords } from './use-entity-records';
 
 /**

sources/client/src/hooks/use-search.ts

@@ -13,7 +13,7 @@ import { doAction } from '@wordpress/hooks';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 type SearchPhrase = Parameters<
 	EntitiesSearch.SearchControl[ 'onChange' ]

sources/client/src/index.ts

@@ -12,10 +12,12 @@ export * from './hooks/use-entity-records';
 export * from './hooks/use-query-viewable-post-types';
 export * from './hooks/use-query-viewable-taxonomies';
 
+export * from './models/set';
+export * from './models/immutable-record';
+
 export * from './utils/convert-entities-to-control-options';
 export * from './utils/is-control-option';
-export * from './utils/order-selected-options-at-the-top';
 export * from './utils/unique-control-options';
+export * from './utils/order-selected-options-at-the-top';
 
-export * from './vo/control-option';
-export * from './vo/set';
+export * from './value-objects/control-option';

sources/client/src/models/immutable-record.ts

@@ -0,0 +1,20 @@
+/**
+ * External dependencies
+ */
+import EntitiesSearch from '@types';
+
+export class ImmutableRecord< T > implements EntitiesSearch.Record< T > {
+	readonly #map: Record< string, T > = {};
+
+	public constructor( map: Record< string, T > = {} ) {
+		this.#map = map;
+	}
+
+	public get< F >( key: string, fallback?: F ): T | F | undefined {
+		return this.#map[ key ] ?? fallback;
+	}
+
+	public set( key: string, value: T ): ImmutableRecord< T > {
+		return new ImmutableRecord( { ...this.#map, [ key ]: value } );
+	}
+}

sources/client/src/storage/entities/initial-state.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../../vo/set';
+import { Set } from '../../models/set';
 
 type Options< V > = EntitiesSearch.ControlOption< V >;
 

sources/client/src/storage/entities/reducer.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../../vo/set';
+import { Set } from '../../models/set';
 
 /**
  * @internal

sources/client/src/utils/convert-entities-to-control-options.ts

@@ -6,22 +6,30 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { ControlOption } from '../vo/control-option';
-import { Set } from '../vo/set';
+import { ControlOption } from '../value-objects/control-option';
+import { Set } from '../models/set';
 import { assert } from './assert';
+import { ImmutableRecord } from '../models/immutable-record';
 
 export function convertEntitiesToControlOptions<
 	V,
 	EntitiesFields extends { [ p: string ]: any },
 >(
 	entities: Set< EntitiesFields >,
 	labelKey: string,
-	valueKey: string
+	valueKey: string,
+	...extraKeys: Array< string >
 ): Set< EntitiesSearch.ControlOption< V > > {
 	return entities.map( ( entity ) => {
 		const label = entity[ labelKey ];
 		const value = entity[ valueKey ];
-		assert( typeof label === 'string', 'Label Key must be a string' );
-		return new ControlOption( label, value );
+		assert( typeof label === 'string', 'Label key must be a string' );
+
+		const extra = extraKeys.reduce(
+			( record, key ) => ( { ...record, [ key ]: entity[ key ] } ),
+			{}
+		);
+
+		return new ControlOption( label, value, new ImmutableRecord( extra ) );
 	} );
 }

sources/client/src/utils/order-selected-options-at-the-top.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 export function orderSelectedOptionsAtTheTop< V >(
 	options: Set< EntitiesSearch.ControlOption< V > >,

sources/client/src/utils/unique-control-options.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 // TODO Is this necessary due the new Set implementation?
 export function uniqueControlOptions< V >(

sources/client/src/vo/control-option.ts → sources/client/src/value-objects/control-option.ts

@@ -7,12 +7,20 @@ import EntitiesSearch from '@types';
  * Internal dependencies
  */
 import { assert } from '../utils/assert';
+import { ImmutableRecord } from '../models/immutable-record';
 
-export class ControlOption< V > implements EntitiesSearch.ControlOption< V > {
+export class ControlOption< V >
+	implements EntitiesSearch.EnrichedControlOption< V >
+{
 	public readonly label: string;
 	public readonly value: V;
+	public readonly extra: EntitiesSearch.Record< unknown >;
 
-	public constructor( label: string, value: V ) {
+	public constructor(
+		label: string,
+		value: V,
+		extra: EntitiesSearch.Record< unknown > = new ImmutableRecord()
+	) {
 		assert(
 			label !== '',
 			'ControlOption: Label must be a non empty string.'
@@ -24,5 +32,6 @@ export class ControlOption< V > implements EntitiesSearch.ControlOption< V > {
 
 		this.label = label;
 		this.value = value;
+		this.extra = extra;
 	}
 }

tests/client/integration/components/composite-entities-by-kind.test.tsx

@@ -21,7 +21,7 @@ import { CompositeEntitiesByKind } from '../../../../sources/client/src/componen
 import { PluralSelectControl } from '../../../../sources/client/src/components/plural-select-control';
 import { SearchControl } from '../../../../sources/client/src/components/search-control';
 import { SingularSelectControl } from '../../../../sources/client/src/components/singular-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),
@@ -36,7 +36,11 @@ describe( 'CompositeEntitiesByKind', () => {
 
 		const rendered = render(
 			<CompositeEntitiesByKind
-				searchEntities={ () => Promise.resolve( new Set() ) }
+				searchEntities={ () =>
+					Promise.resolve(
+						new Set< EntitiesSearch.ControlOption< any > >()
+					)
+				}
 				entities={ {
 					value: new Set(),
 					onChange: () => {},
@@ -92,7 +96,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -335,7 +341,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -381,7 +389,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -414,7 +424,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -485,7 +497,11 @@ describe( 'CompositeEntitiesByKind', () => {
 
 		const rendered = render(
 			<CompositeEntitiesByKind
-				searchEntities={ () => Promise.resolve( new Set() ) }
+				searchEntities={ () =>
+					Promise.resolve(
+						new Set< EntitiesSearch.ControlOption< any > >()
+					)
+				}
 				entities={ {
 					value: new Set(),
 					onChange: () => {},

tests/client/unit/api/search-entities.test.ts

@@ -15,7 +15,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { fetch } from '../../../../sources/client/src/api/fetch';
 import { searchEntities } from '../../../../sources/client/src/api/search-entities';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),

tests/client/unit/components/plural-select-control.test.tsx

@@ -15,7 +15,7 @@ import { faker } from '@faker-js/faker';
  * Internal dependencies
  */
 import { PluralSelectControl } from '../../../../sources/client/src/components/plural-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 import { buildOptions } from '../utils';
 
 describe( 'Posts Select', () => {

tests/client/unit/components/radio-control.test.tsx

@@ -12,7 +12,7 @@ import { render, screen, fireEvent } from '@testing-library/react';
  * Internal dependencies
  */
 import { RadioControl } from '../../../../sources/client/src/components/radio-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 describe( 'KindRadioControl', () => {
 	it( 'renders the component', () => {

tests/client/unit/components/singular-select-control.test.tsx

@@ -15,7 +15,7 @@ import { faker } from '@faker-js/faker';
  * Internal dependencies
  */
 import { SingularSelectControl } from '../../../../sources/client/src/components/singular-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 import { buildOptions } from '../utils';
 
 describe( 'Post Types Select', () => {

tests/client/unit/components/toggle-control.test.tsx

@@ -12,7 +12,7 @@ import userEvent from '@testing-library/user-event';
  * Internal dependencies
  */
 import { ToggleControl } from '../../../../sources/client/src/components/toggle-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 const options = new Set( [
 	{ label: 'Option 1', value: '1' },

tests/client/unit/hooks/use-entities-options-storage.test.tsx

@@ -17,7 +17,7 @@ import { doAction } from '@wordpress/hooks';
  * Internal dependencies
  */
 import { useEntitiesOptionsStorage } from '../../../../sources/client/src/hooks/use-entities-options-storage';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),

tests/client/unit/hooks/use-query-viewable-post-types.test.ts

@@ -11,7 +11,7 @@ import { describe, it, jest, expect } from '@jest/globals';
  */
 import { useEntityRecords } from '../../../../sources/client/src/hooks/use-entity-records';
 import { useQueryViewablePostTypes } from '../../../../sources/client/src/hooks/use-query-viewable-post-types';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/data', () => {
 	return {

tests/client/unit/hooks/use-query-viewable-taxonomies.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, it, jest } from '@jest/globals';
  */
 import { useEntityRecords } from '../../../../sources/client/src/hooks/use-entity-records';
 import { useQueryViewableTaxonomies } from '../../../../sources/client/src/hooks/use-query-viewable-taxonomies';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '../../../../sources/client/src/hooks/use-entity-records', () => {
 	return {