Selective Option


A simple selective option resolver

> Version 0.1.0 is a complete rewrite. Please read the documentation before you consider to switch, many exports have been removed and new ones have been added. It is highly recommended to switch to 0.1.0, just read the documentation before you do.

In this page

* Install
* npm
* yarn
* pnpm
* CDN
* jsDelivr
* unpkg
* API
* Resolvers
function* createValueBasedResolver
function* createBoolBasedResolver
* Potential Resolvers
function* createValueResolver
function* createFunctionResolver
function* createKeyResolver
function* createKeyListResolver
function* createObjectResolver
* Others
function* createResolver
function* createResult
* Exported Types
* Input Types
type* FunctionOption
type* SingleKeyOption
type* KeyListOption
type* KeyOption
type* ObjectOption
type* ValueBasedSelectiveOption
type* BoolBasedSelectiveOption
* Resolver related Types
type* KeyList
type* SpecialKeys
type* Resolved
type* PotentiallyResolved
type* PotentialResolver
type* Resolver
type* ValueBasedResolver
type* BoolBasedResolver
* Other Types
type* PositiveKey
type* NegativeKey
type* TypeCheckFunction

Install

$3

``bash
npm install selective-option
`

$3

`bash
yarn add selective-option
`

$3

`bash
pnpm add selective-option
`

CDN

$3

UMD*

`html

`

`html

`

ES Module*

`html

`

`html

`

more options...

$3

UMD*

`html

`

`html

`

ES Module*

`html

`

`html

`

more options...

API

$3

Creates a value based resolver. It resolves input as valid value (V), null, undefined, FunctionOption or ObjectOption. It internally uses createValueResolver, createFunctionResolver and createObjectResolver to create a Resolver using createResolver. See the examples for more info.

`typescript
function createValueBasedResolver(
keys: readonly K[],
isValidValue: TypeCheckFunction,
defaultValue: D,
overrideKey: O,
special?: SpecialKeys | null | undefined,
): ValueBasedResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object. They will also be used to validate keys if input is an object.
* isValidValue: A function which returns wether or not a value is valid.
* defaultValue: A valid value to be used as default in case the value is null or undefined.
* overrideKey: A string to be used to detect the override key if the input is an object.
* special: An optional object mapping special keys to multiple regular keys. They can be used as keys if the input is an object.

See TypeCheckFunction, SpecialKeys and ValueBasedResolver.

Example*

`typescript
const resolveNumber = createValueBasedResolver(
['a', 'b', 'c'] as const,
(value: unknown): value is number => typeof value === 'number',
0,
'override',
{ ac: ['a', 'c'] },
);

resolveNumber(18); // set value { a: 18, b: 18, c: 18 }
resolveNumber(true); // Throws because true doesn't pass the test
resolveNumber({}); // default value { a: 0, b: 0, c: 0 }
resolveNumber({ override: 40 }); // overridden value { a: 40, b: 40, c: 40 }
resolveNumber({ override: 'string' }); // Throws because 'string' doesn't pass the test
resolveNumber({ b: 40 }); // default + set value { a: 0, b: 40 c: 0 }
resolveNumber({ c: [] }); // Throws because [] doesn't pass the test
resolveNumber({ ac: 40 }); // default + special set value { a: 40, b: 0 c: 40 }
resolveNumber({ override: 40, a: 12 }); // overridden + set value { a: 12, b: 40, c: 40 }
resolveNumber({ override: 40, ac: 12 }); // overridden + special set value { a: 12, b: 40, c: 12 }
// ... you get the idea...
`

$3

Creates a boolean based resolver. It resolves input as valid value (V), boolean, null, undefined, FunctionOption, KeyOption or ObjectOption. It internally uses createValueResolver, createFunctionResolver, createKeyResolver, createKeyListResolver and createObjectResolver to create a Resolver using createResolver. See the examples for more info.

`typescript
function createBoolBasedResolver(
keys: readonly K[],
isValidValue: AllowNullish>,
defaultValue: D,
overrideKey: O,
special?: SpecialKeys | null | undefined,
): BoolBasedResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object. They will also be used to validate positive keys and negative keys if input is a string or an array, and to validate keys if input is an object.
* isValidValue: A function which returns wether or not a value is valid. Note that this function doesn't need to test for boolean values as they will be included by default. If pass null or undefined, it will only test for boolean values.
* defaultValue: A valid value to be used as default in case the value is null or undefined.
* overrideKey: A string to be used to detect the override key if the input is an object.
* special: An optional object mapping special keys to multiple regular keys. They can be used as keys if the input is an object and as positive keys or negative keys if input is a string or an array.

See TypeCheckFunction, SpecialKeys and BoolBasedResolver.

Example*

`typescript
const resolve = createBoolBasedResolver(
['a', 'b', 'c'] as const,
(value: unknown): value is ('yes' | 'not' | 'unknown') => {
return ['yes', 'no', 'unknown'].includes(value as never);
},
'unknown',
'default',
{ ab: ['a', 'b'] },
);

resolveEvenNumber(null); // default value { a: 'unknown', b: 'unknown', c: 'unknown' }
resolveEvenNumber('yes'); // set value { a: 'yes', b: 'yes', c: 'yes' }
resolveEvenNumber(17); // Throws because 17 doesn't pass the test
resolveEvenNumber('a'); // set key { a: true, b: false, c: false }
resolveEvenNumber('ab'); // set key { a: true, b: true, c: false }
resolveEvenNumber(['a', 'c']); // set key { a: true, b: false, c: true }
resolveEvenNumber(['a', 'b', 'c']); // set key { a: true, b: true, c: true }
resolveEvenNumber(['ab', 'c']); // set key { a: true, b: true, c: true }
resolveEvenNumber({}); // default value { a: 'unknown', b: 'unknown', c: 'unknown' }
resolveEvenNumber({ default: true }); // overridden value { a: true, b: true, c: true }
resolveEvenNumber({ default: 15 }); // Throws because 15 doesn't pass the test
resolveEvenNumber({ default: 'yes', a: true }); // overridden + set value { a: true, b: 'yes', c: 'yes' }
// ... you get the idea...
`

$3

Creates a potential resolver function that resolves to the input value if it satisfies isValidValue function, or defaultValue if input is null or undefined. It returns undefined otherwise.

`typescript
function createValueResolver(
keys: readonly K[],
isValidValue: TypeCheckFunction,
defaultValue: V,
): PotentialResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object.
* isValidValue: A function which returns wether or not a value is valid.
* defaultValue: A value to be used as default in case the input value is null or undefined.

See TypeCheckFunction and PotentialResolver.

$3

Creates a potential resolver function that resolves if the input value is a function. It returns undefined otherwise.

The input function will receive the result key as only argument. The value returned by the input function will be used as value for the specific result key if it satisfies isValidValue, if it's null or undefined, defaultValue will be used instead. It will throw otherwise. See example below...

`typescript
function createFunctionResolver(
keys: readonly K[],
isValidValue: TypeCheckFunction,
defaultValue: D,
): PotentialResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object.
* isValidValue: A function which returns wether or not a value is valid.
* defaultValue: A value to be used as default in case the input function returns null or undefined.

Example*

`typescript
const resolve = createFunctionResolver(['a', 'b', 'c'], isNumber, 'none');

resolve((key) => key === 'b' ? 40 : 10); // resolves to { a: 10, b: 40, c: 10 }
resolve((key) => key === 'a' ? null : 33); // resolves to { a: 'none', b: 33, c: 33 }

// function returning an invalid value will throw
resolve((key) => 40) // throws

// non function inputs will be ignored by this resolver
resolve(40) // resolves to undefined
`

See TypeCheckFunction and PotentialResolver.

$3

Creates a potential resolver function that resolves if the input value is a string and is present in keys array, or if it is one of the special object keys. It also resolves if input follow the PositiveKey or NegativeKey format. It returns undefined otherwise.

This key determines the result. A positive key means "only that key". A negative key means "all other keys but that one". See example.

`typescript
function createKeyResolver(
keys: KeyList,
special?: SpecialKeys | null | undefined,
): PotentialResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object. They will also be used to validate positive keys or negative keys.
* special: An optional object mapping special keys to multiple regular keys. These special keys can also be used as positive keys or negative keys.

See KeyList, SpecialKeys and PotentialResolver.

Example*

`typescript
const resolve = createKeyResolver<'a' | 'b' | 'c', 'd'>(
['a', 'b', 'c'],
{ d: ['a', 'c'] },
);

resolve('c'); // Resolves to { a: false, b: false, c: true }
resolve('b'); // Resolves to { a: false, b: true, c: false }

resolve('a') // Resolves to { a: true, b: false, c: false } ::: Only "a" is set
resolve('!a') // Resolves to { a: false, b: true, c: true } ::: Everything but "a" is set

resolve('d'); // Resolves to { a: true, b: false, c: true } ::: Only "a" & "c" is set
resolve('!d'); // Resolves to { a: false, b: true, c: false } ::: Everything but "a" & "c" is set
`

$3

Creates a potential resolver function that resolves if the input value is an array of string and every string is present in keys array, or if it is one of the special object keys. It also resolves if any of the string in the array follow the PositiveKey or NegativeKey format. It returns undefined otherwise.

The keys will be processed in the order they were added. The first key in the array will determine the default result, and the rest will mutate the result accordingly. A positive first key means "only that key". A negative first key means "all other keys but that one". See example.

`typescript
function createKeyListResolver(
keys: KeyList,
special?: SpecialKeys | null | undefined,
): PotentialResolver;
`

See KeyList, SpecialKeys and PotentialResolver.

Example*

`typescript
const resolve = createKeyListResolver<'a' | 'b' | 'c', 'd'>(
['a', 'b', 'c'],
{ d: ['a', 'c'] },
);

resolve([]); // Resolves to { a: false, b: false, c: false }
resolve(['a', 'b']); // Resolves to { a: true, b: true, c: false }

// The first item sets the default
resolve(['a']) // Resolves to { a: true, b: false, c: false } ::: Only "a" is set
resolve(['!a']) // Resolves to { a: false, b: true, c: true } ::: Everything but "a" is set

// Watch the items order!!!

resolve(['a', '!a']) // Resolves to { a: false, b: false, c: false }
// because...
// step1 - 'a' => { a: true, b: false, c: false }
// step2 - '!a' => { ...step1, a: false }
// return step2

resolve(['!a', 'a']) // Resolves to { a: true, b: true, c: true }
// because...
// step1 - '!a' => { a: false, b: true, c: true }
// step2 - 'a' => { ...step1, a: true }
// return step2

resolve(['d', '!c']); // Resolves to { a: true, b: false, c: false }
// because...
// step1 = 'd' => { a: true, b: false, c: true }
// step2 = '!c' => { ...step1, c: false }
// return step2

resolve(['!c', 'd']); // Resolves to { a: true, b: true, c: true }
// because...
// step1 '!c' => { a: true, b: true, c: false }
// step2 'd' => { ...step1, a: true, c: true }
// return step2
`

$3

Creates a potential resolver function that resolves if the input value is an object and it follows the ObjectOption format. It returns undefined otherwise.

`typescript
function createObjectResolver(
keys: KeyList,
isValidValue: TypeCheckFunction,
defaultValue: V,
overrideKey: O,
special?: SpecialKeys | null | undefined,
): PotentialResolver;
`

Arguments*
* keys: An array of string to be used as keys in the final Resolved object. They will also be used to validate input object keys.
* isValidValue: A function which returns wether or not a value is valid.
* defaultValue: A valid value to be used as default in case the value is null or undefined.
* overrideKey: A string to be used to detect the override key if the input is an object.
* special: An optional object mapping special keys to multiple regular keys. They can also be used as keys in input object.

See KeyList, TypeCheckFunction, SpecialKeys and PotentialResolver.

$3

Creates a resolver base on a series of potential resolvers. I will iterate through every potential resolver until one resolves and return the Resolved object result. It will throw if no potential resolver resolves.

`typescript
function createResolver(
...resolvers: Array>
): Resolver;
`

See PotentialResolver and Resolver.

$3

Creates a Resolved object. Used internally in every potential resolver function. It is exported in case you need to write your own potential resolver function.

`typescript
function createResult(
keys: KeyList,
value: V,
): Resolved;
`

Arguments*
* keys: An array of string to be used as keys in the Resolved object.
* value: A value to be assigned to every key in the Resolved object.

See KeyList and Resolved.

Example*

Creating a Resolved object.

`typescript
createResult(['a', 'b', 'c'], true); // { a: true, b: true, c: true }
createResult(['a', 'b', 'c'], 10); // { a: 10, b: 10, c: 10 }
`

DEPRECATION NOTICE

This function accepts a third argument as input object, this is deprecated now and will be removed in the future. To extend a previous result use the object spread operator or Object.assign.

`typescript
/* @deprecated /
function createResult(
keys: KeyList,
value: V,
input?: Resolved
): Resolved;
`

Arguments*
* keys: An array of string to be used as keys in the Resolved object.
* value: A value to be assigned to every key in the Resolved object.
* input: An optional Resolved object to be used as base for the new Resolved object. This input object won't be modified, a new one will be created instead. If you pass an empty array as keys, the input object will be returned, unless input is null or undefined in which case a new empty object will be returned.

Example*

Extending a previously created Resolved object (DEPRECATED).

`typescript
const base = createResult(['a', 'b', 'c'], 0); // base = { a: 0, b: 0, c: 0 }
const result = createResult(['a', 'c'], 40, base); // { a: 40, b: 0, c: 40 }
`

To extend a previously create result use...

`typescript
const base = createResult(['a', 'b', 'c'], 0); // base = { a: 0, b: 0, c: 0 }
const override = createResult(['a', 'c'], 40); // { a: 40, c: 40 }
const result = { ...base, ...override }; // { a: 40, b: 0, c: 40 };
`

Exported Types

$3

A function to be called for every key in the the final Resolved object.

`typescript
export type FunctionOption = (key: K) => V | null | undefined;
`

$3

`typescript
type SingleKeyOption = PositiveKey | NegativeKey;
`

See PositiveKey and NegativeKey. Used in type KeyListOption and KeyOption.

Example*

`typescript
function logKey(key: SingleKeyOption<'a' | 'b'>) {
console.log(key);
}

logKey('a'); // OK
logKey('b'); // OK
logKey('!a'); // OK
logKey('!b'); // OK
logKey('-a'); // OK
logKey('-b'); // OK

logKey('x') // Type Error
logKey('z') // Type Error
logKey('!z') // Type Error
`

$3

`typescript
type KeyListOption = KeyList>;
`

See KeyList and SingleKeyOption. Used in type KeyOption.

Example*

`typescript
function logKeys(keys: KeyListOption<'a' | 'b'>) {
console.log(keys);
}

logKeys(['a']); // OK
logKeys(['a', '!b']); // OK
logKeys(['b', '-a']); // OK
logKeys(['a', 'b', '-a']); // OK

logKeys(['x']) // Type Error
logKeys(['!z']) // Type Error
logKeys(['x', 'a']) // Type Error
logKeys(['a', '!z']) // Type Error
`

$3

`typescript
type KeyOption = SingleKeyOption | KeyListOption;
`

See SingleKeyOption and KeyListOption. Used in type BoolBasedSelectiveOption.

Example*

`typescript
function logOption(option: KeyOption<'a' | 'b'>) {
console.log(option);
}

logOption('a'); // OK
logOption('b'); // OK
logOption('!a'); // OK
logOption('-b'); // OK
logOption(['-b', 'a']); // OK
logOption(['-b', '!a']); // OK

logOption('z') // Type Error
logOption('!z') // Type Error
logOption(['!z']) // Type Error
logOption(['!z', 'a']) // Type Error
`

$3

An object containing the keys defined by K | O and the values of V, null or undefined. It will be used by the PotentialResolver created by createObjectResolver in order to create a result using createResult.

`typescript
type ObjectOption = Partial>;
`

Generics*
K: keys allowed in the input object.
V: value type allowed inside input object.

Used in type ValueBasedSelectiveOption.

Example*

`typescript
function logOption(option: ObjectOption<'a' | 'b' | 'override', number>) {
console.log(option);
}

logOption({}); // OK
logOption({ override: 10 }); // OK
logOption({ override: 10, a: 8 }); // OK
logOption({ a: 45 }); // OK
logOption({ a: 45, b: 10 }); // OK

logOption('z') // Type Error
logOption([]) // Type Error
logOption({ override: 'string' }) // Type Error
logOption({ override: 'string', b: 0 }) // Type Error
logOption({ a: 10, b: true }) // Type Error
`

$3

`typescript
type ValueBasedSelectiveOption =
| V
| null
| undefined
| ObjectOption;
`

Generics*
K: keys allowed if the input is an object.
V: value type allowed as input value and inside input if it's an object.

See ObjectOption. Used in type BoolBasedSelectiveOption and ValueBasedResolver.

$3

`typescript
type BoolBasedSelectiveOption =
| KeyOption
| ValueBasedSelectiveOption;
`

Generics*
K: keys allowed as positive keys or negative keys, and as keys if input is an object.
V: value type allowed as input value and inside input if it's an object. It will also allow boolean as valid value.
O: key name allowed for the override key if input is an object.

See KeyOption and ValueBasedSelectiveOption. Used in type BoolBasedResolver.

$3

An immutable list of keys.

`typescript
type KeyList = readonly K[];
`

Used in function createKeyResolver, createKeyListResolver, createObjectResolver, createResult and type SpecialKeys.

$3

An object mapping special keys to a list of regular keys.

`typescript
type SpecialKeys = Readonly>>;
`

See type KeyList. Used in function createValueBasedResolver, createBoolBasedResolver, createKeyResolver, createKeyListResolver and createObjectResolver.

Example*

`typescript
type Country = 'american' | 'japanese';
type Car = 'chevrolet' | 'toyota' | 'suzuki' | 'ford';

const special: SpecialKeys = {
american: ['ford', 'chevrolet'],
japanese: ['toyota', 'suzuki'],
};
`

$3

`typescript
type Resolved = Readonly>;
`

Used in function createResult and type PotentialResolver, Resolver.

$3

`typescript
type PotentiallyResolved = Resolved | null | undefined;
`

Used in type PotentialResolver.

$3

`typescript
type PotentialResolver = (input: unknown) => PotentiallyResolved | void;
`

See PotentiallyResolved. Used in function createValueResolver, createFunctionResolver, createKeyResolver, createKeyListResolver, createObjectResolver and createResolver.

$3

`typescript
type Resolver = (input: I) => Resolved;
`

See Resolved. Used in function createResolver and type ValueBasedResolver and BoolBasedResolver.

$3

`typescript
type ValueBasedResolver = Resolver>;
`

See Resolver and ValueBasedSelectiveOption. Used in function createValueBasedResolver.

$3

`typescript
type BoolBasedResolver = Resolver>;
`

See Resolver and BoolBasedSelectiveOption. Used in function createBoolBasedResolver.

Other Types

These are types which are not exported but help to understand some of the exported types.

$3

A key name or a key name prefixed with a + sign.

`typescript
type PositiveKey = K | +${K};
`

Used in type SingleKeyOption.

$3

A key name prefixed with a ! or - sign.

`typescript
type NegativeKey = !${K} | -${K};
`

Used in type SingleKeyOption.

$3

`typescript
type TypeCheckFunction = (input: unknown) => input is V;
`

Used in function createValueBasedResolver, createBoolBasedResolver, createValueResolver, createFunctionResolver and createObjectResolver.

Example*

`typescript
const isString: TypeCheckFunction = (input) => {
return typeof input === 'string';
};

const isRGB: TypeCheckFunction<'red' | 'green' | 'blue'> = (input) => {
return ['red', 'green', 'blue'].includes(input as never);
}
``

License

MIT © 2020-2024 Manuel Fernández (@manferlo81)