inferred-types 0.24.3 → 0.26.0

package/dist/index.d.ts

@@ -165,12 +165,6 @@ declare type If<C extends boolean, T, F> = C extends T ? C | F : never;
  */
 declare type Include<T, U, L extends boolean = false> = L extends true ? T extends U ? U extends T ? T : never : never : T extends U ? T : never;
 
-/**
- * A type takes the two arguments. The first is an array of string values, the second is the value
- * which is being tested as it whether or not it's _included_ in the array. Result is true or false.
- */
-declare type Includes<T extends readonly any[], U> = U extends T[number] ? true : false;
-
 /**
  * A "KeyedRecord" is intended to store a value without
  * losing any ability to infer type information later.
@@ -1198,6 +1192,11 @@ declare type PureFluentApi<TApi extends Record<string, (...args: any[]) => PureF
  */
 declare type FinalReturn<T extends any> = T extends (...args: any[]) => any ? FinalReturn<ReturnType<T>> : T;
 
+/**
+ * A function which returns a boolean value
+ */
+declare type LogicFunction<T extends any[]> = (...args: T) => boolean;
+
 declare type DictFromKv<T extends readonly Readonly<{
     key: string;
     value: unknown;
@@ -1348,6 +1347,51 @@ declare type FromDictArray<T extends [string, Record<string, unknown>][]> = Expa
  */
 declare type SecondOfEach<T extends any[][]> = T[number][1] extends T[number][number] ? T[number][1] : never;
 
+/**
+ * **IsBooleanLiteral**
+ *
+ * Type utility which returns true/false if the boolean value is a _boolean literal_ versus
+ * just the wider _boolean_ type.
+ */
+declare type IsBooleanLiteral<T extends boolean> = boolean extends T ? false : true;
+
+/**
+ * **IsStringLiteral**
+ *
+ * Type utility which returns true/false if the string a _string literal_ versus
+ * just the _string_ type.
+ */
+declare type IsStringLiteral<T extends string> = string extends T ? false : true;
+
+/**
+ * **IsNumericLiteral**
+ *
+ * Type utility which returns true/false if the numeric value a _numeric literal_ versus
+ * just the _number_ type.
+ */
+declare type IsNumericLiteral<T extends number> = number extends T ? false : true;
+
+/**
+ * **IsLiteral**
+ *
+ * Type utility which returns true/false if the value passed -- a form of a
+ * string, number, or boolean -- is a _literal_ value of that type (true) or
+ * the more generic wide type (false).
+ */
+declare type IsLiteral<T extends string | number | boolean> = [T] extends [string] ? IsStringLiteral<T> : [T] extends [boolean] ? IsBooleanLiteral<T> : [T] extends [number] ? IsNumericLiteral<T> : never;
+
+/**
+ * **Includes<TSource, TValue>**
+ *
+ * Type utility which returns `true` or `false` based on whether `TValue` is found
+ * in `TSource`. Where `TSource` can be a string literal or an array of string literals.
+ *
+ * **Note:** if the source is a _wide_ type (aka, `string` or `string[]`) then there is
+ * no way to know at design-time whether the value includes `TValue` and so it will return
+ * a type of `boolean`.
+ */
+declare type Includes<TSource extends string | string[], TValue extends string> = TSource extends string[] ? IsStringLiteral<TupleToUnion<TSource>> extends true ? IsLiteral<TValue> extends true ? TValue extends TupleToUnion<TSource> ? true : false : boolean : boolean : TSource extends string ? IsLiteral<TSource> extends true ? IsLiteral<TValue> extends true ? TSource extends `${string}${TValue}${string}` ? true : false : boolean : boolean : boolean;
+
 declare function createFnWithProps<F extends Function, P extends {}>(fn: F, props: P): F & P;
 /**
  * Adds a dictionary of key/value pairs to a function.
@@ -1383,6 +1427,116 @@ declare function ruleSet<N extends Narrowable, TState extends Record<keyof TStat
 
 declare const api: <N extends Narrowable, TPrivate extends Readonly<Record<any, N>>>(priv: TPrivate) => <TPublic extends object>(pub: TPublic) => () => TPublic;
 
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **AND** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+declare const and: <T extends any[]>(...ops: readonly LogicFunction<T>[]) => LogicFunction<T>;
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **OR** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+declare const or: <T extends any[]>(...ops: LogicFunction<T>[]) => LogicFunction<T>;
+
+/**
+ * Groups a number of "logic functions" together by combining their results using
+ * the logical **NOT** operator.
+ *
+ * **Note:** a "logic function" is any function which returns a boolean
+ */
+declare const not: <T extends any[]>(op: LogicFunction<T>) => LogicFunction<T>;
+
+declare type FilterStarts = {
+    /** one or more string which the value is allowed to start with */
+    startsWith: string | string[];
+};
+declare type FilterIs = {
+    /** whether a string _**is**_ of a particular value */
+    is: string | string[];
+};
+declare type FilterEnds = {
+    endsWith: string | string[];
+};
+declare type FilterContains = {
+    /** whether any of the strings specified are _contained_ in the value */
+    contains: string | string[];
+};
+declare type FilterEquals = {
+    /** one or more values which _equal_ the value passed in */
+    equals: number | number[];
+};
+declare type FilterNotEqual = {
+    /** one or more values which ALL _do not equal_ the value passed in */
+    notEqual: number | number[];
+};
+declare type FilterGreaterThan = {
+    /** the incoming value is greater than this value */
+    greaterThan: number;
+};
+declare type FilterLessThan = {
+    /** the incoming value is less than this value */
+    lessThan: number;
+};
+declare type StringFilter = FilterIs | FilterStarts | FilterEnds | FilterContains | (FilterStarts & FilterEnds) | (FilterStarts & FilterContains) | (FilterEnds & FilterContains) | (FilterStarts & FilterEnds & FilterContains);
+declare type NumericFilter = FilterEquals | FilterNotEqual | FilterGreaterThan | FilterLessThan | (FilterEquals & FilterNotEqual) | (FilterEquals & FilterGreaterThan) | (FilterEquals & FilterLessThan) | (FilterNotEqual & FilterGreaterThan) | (FilterNotEqual & FilterLessThan) | (FilterGreaterThan & FilterLessThan) | (FilterEquals & FilterGreaterThan & FilterLessThan) | (FilterNotEqual & FilterGreaterThan & FilterLessThan) | (FilterEquals & FilterNotEqual & FilterGreaterThan & FilterLessThan);
+declare type FilterDefn = StringFilter | NumericFilter;
+declare type NotFilter = {
+    /**
+     * **not**
+     *
+     * If you want to build a filter who's conditions being met results in _filtering_
+     * the value rather than accepting it then choose this.
+     */
+    not: FilterDefn;
+};
+declare function isNotFilter(f: FilterDefn | NotFilter): f is NotFilter;
+declare type UnwrapNot<T extends FilterDefn | NotFilter> = T extends NotFilter ? T["not"] extends StringFilter ? StringFilter : NumericFilter : T;
+declare function isNumericFilter(filter: FilterDefn): filter is NumericFilter;
+declare type UndefinedValue<U extends boolean> = true extends U ? "undefined treated as 'true'" : U extends "no-impact" ? "undefined treated in no-impact fashion" : "undefined treated as 'false'";
+declare type UndefinedTreatment = "undefined treated as 'true'" | "undefined treated as 'false'";
+declare type LogicalCombinator = "AND" | "OR";
+/**
+ * **FilterFn**
+ *
+ * A filter function derived from the `filter()` configurator. This function is intended to provide a type-strong _filter_ function which can be used like so:
+ * be used like:
+ * ```ts
+ * const onlyPrivate = filter({ startsWith: "_" });
+ * const privateFiles = files.filter(onlyPrivate);
+ * ```
+ *
+ */
+declare type FilterFn<T extends StringFilter | NumericFilter> = T extends StringFilter ? <V extends string | undefined>(input: V) => boolean : <V extends number | undefined>(input: V) => boolean;
+/**
+ * Defines a logical function for each condition type
+ */
+declare type ConditionFilter<T extends StringFilter | NumericFilter> = T extends StringFilter ? (input: string) => boolean : (input: number) => boolean;
+/**
+ * **filter**
+ *
+ * A higher order helper utility which builds a boolean _filter_ function based on a simple
+ * configuration object. Support either _string_ or _numeric_ filters.
+ *
+ * ```ts
+ * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
+ * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
+ * ```
+ *
+ * All conditions (e.g., `startsWith`, `contains`, `notEqual`, etc.) that a particular filter
+ * is defined as having -- if there is more than one -- will be logically combined using AND
+ * unless specified otherwise in the third parameter.
+ *
+ * How a value of _undefined_ will be treated is stated in the second parameter but defaults
+ * to "no-impact" which means it's `false` when the logicCombinator is OR but defaults
+ * to `true` when the logicCombinator is AND.
+ */
+declare const filter: <F extends FilterDefn | NotFilter, U extends boolean | "no-impact", C extends LogicalCombinator>(config: F, logicCombinator?: C, ifUndefined?: U) => FilterFn<UnwrapNot<F>>;
+
 /**
  * Passing in an array of strings, you are passed back a dictionary with
  * all the keys being the strings and values set to `true`.
@@ -1553,6 +1707,24 @@ declare function kvToDict<K extends string, V extends Narrowable, T extends read
     value: V;
 }>[]>(kvArr: T): DictFromKv<T>;
 
+/**
+ * Type utility which converts `undefined[]` to `unknown[]`
+ */
+declare type UndefinedArrayIsUnknown<T extends any[]> = undefined[] extends T ? unknown[] : T;
+declare type AsArray<T, W extends boolean = false> = T extends any[] ? W extends true ? Widen<T> : T : W extends true ? UndefinedArrayIsUnknown<Widen<T>[]> : UndefinedArrayIsUnknown<T[]>;
+/**
+ * Ensures that any input passed in is passed back as an array:
+ *
+ * - if it was already an array than this just serves as an _identity_ function
+ * - if it was not then it wraps the element into a one element array of the
+ * given type
+ *
+ * Note: by default the _type_ of values will be intentionally widened so that the value "abc"
+ * is of type `string` not the literal `abc`. If you want to keep literal types then
+ * change the optional _widen_ parameter to _false_.
+ */
+declare const asArray: <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W | undefined) => AsArray<T, W>;
+
 /**
  * Groups an array of data based on the value of a property
  * in the objects within the array.
@@ -1668,33 +1840,6 @@ declare function idTypeGuard<T extends {
  */
 declare function literal<N extends Narrowable, T extends Record<keyof T, N>>(obj: T): T;
 
-declare type Filter<A> = {
-    kind: "Equals";
-    field: keyof A;
-    val: A[keyof A];
-} | {
-    kind: "Greater";
-    field: keyof A;
-    val: A[keyof A];
-} | {
-    kind: "Less";
-    field: keyof A;
-    val: A[keyof A];
-} | {
-    kind: "And";
-    a: Filter<A>;
-    b: Filter<A>;
-} | {
-    kind: "Or";
-    a: Filter<A>;
-    b: Filter<A>;
-};
-declare const equals: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
-declare const greater: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
-declare const less: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
-declare const and: <A>(a: Filter<A>, b: Filter<A>) => Filter<A>;
-declare const or: <A>(a: Filter<A>, b: Filter<A>) => Filter<A>;
-
 declare function Model<N extends string, _R extends {} = {}, _O extends {} = {}>(name: N): {
     required<P extends string>(_prop: P): {
         required<P_1 extends string>(_prop: P_1): any;
@@ -1782,4 +1927,4 @@ interface IFluentConfigurator<C> {
  */
 declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
 
-export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, ClosingBracket, Condition, Configurator, Constructor, DashToSnake, DashUppercase, Dasherize, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, ExtendsClause, ExtendsNarrowlyClause, Filter, FinalReturn, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfExtends, IfExtendsThen, Include, Includes, IsArray, IsBoolean, IsCapitalized, IsFalse, IsFunction, IsObject, IsString, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LowerAllCaps, LowerAlpha, MapTo, MapToWithFiltering, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, Numeric, NumericKeys, NumericString, ObjectType, Opaque, OpeningBracket, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefinition, TypeGuard, TypeOptions, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, equals, filterDictArray, fnWithProps, greater, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNull, isNumber, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, less, literal, mapTo, mapValues, nameLiteral, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };
+export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AsArray, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, ClosingBracket, Condition, ConditionFilter, Configurator, Constructor, DashToSnake, DashUppercase, Dasherize, DefinePropertiesApi, DictArrApi, DictArray, DictArrayFilterCallback, DictArrayKv, DictChangeValue, DictFromKv, DictKvTuple, DictPartialApplication, DictPrependWithFn, DictReturnValues, DynamicRule, DynamicRuleSet, Email, EnumValues, ExpandRecursively, ExpectExtends, ExplicitFunction, ExtendsClause, ExtendsNarrowlyClause, FilterContains, FilterDefn, FilterEnds, FilterEquals, FilterFn, FilterGreaterThan, FilterIs, FilterLessThan, FilterNotEqual, FilterStarts, FinalReturn, First, FirstKey, FirstKeyValue, FirstOfEach, FluentConfigurator, FluentFunction, FromDictArray, FunctionType, GeneralDictionary, Get, HasUppercase, IConfigurator, IFluentConfigurator, If, IfExtends, IfExtendsThen, Include, Includes, IsArray, IsBoolean, IsBooleanLiteral, IsCapitalized, IsFalse, IsFunction, IsLiteral, IsNumericLiteral, IsObject, IsString, IsStringLiteral, IsTrue, KebabCase, KeyValue, KeyedRecord, Keys, KeysWithValue, KvFrom, KvTuple, LastInUnion, LeftWhitespace, Length, LogicFunction, LogicalCombinator, LowerAllCaps, LowerAlpha, MapTo, MapToWithFiltering, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, NotFilter, Numeric, NumericFilter, NumericKeys, NumericString, ObjectType, Opaque, OpeningBracket, OptionalKeys, OptionalProps, Parenthesis, PascalCase, Pluralize, PrivateKey, PrivateKeys, PublicKeys, Punctuation, PureFluentApi, Replace, RequireProps, RequiredKeys, RequiredProps, Retain, RightWhitespace, RuleDefinition, RuntimeProp, RuntimeType, SameKeys, SecondOfEach, SimplifyObject, SnakeCase, SpecialCharacters, StringDelimiter, StringFilter, StringKeys, StringLength, ToFluent, Transformer, Trim, TrimLeft, TrimRight, TupleToUnion, Type, TypeApi, TypeCondition, TypeDefinition, TypeGuard, TypeOptions, UndefinedArrayIsUnknown, UndefinedTreatment, UndefinedValue, UnionToIntersection, UnionToTuple, UniqueDictionary, UniqueForProp, Uniqueness, UnwrapNot, UpperAlpha, ValueTuple, ValueTypeFunc, ValueTypes, Where, WhereNot, Whitespace, Widen, WithNumericKeys, WithStringKeys, WithValue, ZipCode, and, api, arrayToKeyLookup, arrayToObject, asArray, condition, createFnWithProps, createMutationFunction, defineProperties, defineType, dictArr, dictToKv, dictionaryTransform, entries, filter, filterDictArray, fnWithProps, groupBy, idLiteral, idTypeGuard, identity, ifTypeOf, isArray, isBoolean, isFalse, isFunction, isNotFilter, isNull, isNumber, isNumericFilter, isObject, isString, isSymbol, isTrue, isType, isUndefined, keys, kindLiteral, kv, kvToDict, literal, mapTo, mapValues, nameLiteral, not, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };