inferred-types 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,7 @@
5
5
  "Aint",
6
6
  "Dasherize",
7
7
  "dasherized",
8
+ "fooy",
8
9
  "ruleset",
9
10
  "tokei",
10
11
  "Uncapitalize"
package/dist/index.d.ts CHANGED
@@ -579,26 +579,52 @@ O extends (...args: any[]) => any = (...args: any[]) => any> = SimplifyObject<{
579
579
  declare type Get<T, K> = K extends `${infer FK}.${infer L}` ? FK extends keyof T ? Get<T[FK], L> : never : K extends keyof T ? T[K] : never;
580
580
 
581
581
  /**
582
- * **MapTo**
582
+ * Expresses whether an option is "opt" (optional) or "req" (required)
583
+ */
584
+ declare type OptRequired = "opt" | "req";
585
+
586
+ /**
587
+ * Expresses relationship between inputs/outputs:
588
+ */
589
+ declare enum MapDirection {
590
+ /** every input results in 0:M outputs */
591
+ OneToMany = "I -> O[]",
592
+ /** every input results in 0:1 outputs */
593
+ OneToOne = "I -> O",
594
+ /** every input is an array of type I and reduced to a single O */
595
+ ManyToOne = "I[] -> O"
596
+ }
597
+ declare type MapDirectionVal = EnumValues<MapDirection>;
598
+ declare type MapInput<I, IR, D extends MapDirectionVal> = D extends MapDirection.OneToMany | "I -> O[]" ? IR extends "opt" ? I | undefined : I : D extends MapDirection.OneToOne | "I -> O" ? IR extends "opt" ? I | undefined : I : D extends MapDirection.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | undefined : I[] : never;
599
+ declare type MapOutput<O, OR, D extends MapDirectionVal> = D extends MapDirection.OneToMany | "I -> O[]" ? OR extends "opt" ? O[] : [O, ...O[]] : D extends MapDirection.OneToOne | "I -> O" ? OR extends "opt" ? O | null : O : D extends MapDirection.ManyToOne | "I[] -> O" ? OR extends "opt" ? O | null : O : never;
600
+ /**
601
+ * **MapTo<I, O>**
583
602
  *
584
- * Maps from one type `I` to another `O[]`
603
+ * A mapping function between an input type `I` and output type `O`.
585
604
  *
586
- * **Note:** because the output is an array you can easily support `1:1` and `1:M` mappings
587
- * but not a filtering operation (e.g., `1:0`); if you need this then use `MapToWithFiltering`
588
- * instead.
605
+ * **Note:** this type is designed to guide the userland mapping; refer
606
+ * to `MapFn` if you want the type output by the `mapFn()` utility.
589
607
  */
590
- declare type MapTo<I extends {}, O extends {}> = (i: I) => O[];
608
+ declare type MapTo<I, O, IR extends OptRequired = "req", D extends MapDirectionVal = MapDirection.OneToMany, OR extends OptRequired = "opt"> = IR extends "opt" ? (source?: MapInput<I, IR, D>) => MapOutput<O, OR, D> : (source: MapInput<I, IR, D>) => MapOutput<O, OR, D>;
609
+ declare type MapFnOutput<I, O, S, OR extends OptRequired, D extends MapDirectionVal> = D extends "I -> O[]" | MapDirection.OneToMany ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O[] | null : O[] : D extends MapDirection.OneToOne | "I -> O" ? S extends I[] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O | null : O : D extends MapDirection.ManyToOne | "I[] -> O" ? S extends I[][] ? OR extends "opt" ? O[] : [O, ...O[]] : OR extends "opt" ? O | null : O : never;
610
+ declare type MapFnInput<I, IR extends OptRequired, D extends MapDirectionVal> = D extends "I -> O[]" | MapDirection.OneToMany ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapDirection.OneToOne | "I -> O" ? IR extends "opt" ? I | I[] | undefined : I | I[] : D extends MapDirection.ManyToOne | "I[] -> O" ? IR extends "opt" ? I[] | I[][] | undefined : I[] | I[][] : never;
591
611
  /**
592
- * **MapToWithFiltering**
593
- *
594
- * Maps from one type `I` to another `(O | null)[]`
612
+ * The mapping function provided by the `mapFn()` utility. This _fn_
613
+ * is intended to be used in two ways:
595
614
  *
596
- * **Note:** because the output is an array you can easily support `1:1` and `1:M` mappings
597
- * and the allowance of the conversion to result in a `null` value also means that filter
598
- * out an input value entirely is possible. If you don't need _filtering_ then use the
599
- * `MapTo` type instead.
615
+ * 1. Iterative:
616
+ * ```ts
617
+ * const m = mapTo<I,O>(i => [ ... ]);
618
+ * // maps inputs to outputs
619
+ * const out = inputs.map(m);
620
+ * ```
621
+ * 2. Block:
622
+ * ```ts
623
+ * // maps inputs to outputs (filtering or splitting where approp)
624
+ * const out2 = m(inputs);
625
+ * ```
600
626
  */
601
- declare type MapToWithFiltering<I extends {}, O extends {}> = (i: I) => O[] | null;
627
+ declare type MapFn<I, O, IR extends OptRequired = "req", D extends MapDirectionVal = MapDirection.OneToMany, OR extends OptRequired = "opt"> = IR extends "opt" ? <S extends MapFnInput<I, IR, D>>(source?: S) => MapFnOutput<I, O, S, OR, D> : <S extends MapFnInput<I, IR, D>>(source: S) => MapFnOutput<I, O, S, OR, D>;
602
628
 
603
629
  /**
604
630
  * Given a dictionary of type `<T>`, this utility function will
@@ -1061,6 +1087,77 @@ declare type _DU<T extends string> = T extends Lowercase<T> ? T : `-${Lowercase<
1061
1087
  */
1062
1088
  declare type DashUppercase<T extends string> = HasUppercase<T> extends false ? T : T extends `${infer C0}${infer C1}${infer R}` ? `${_DU<C0>}${_DU<C1>}${DashUppercase<R>}` : T extends `${infer C0}${infer R}` ? `${_DU<C0>}${DashUppercase<R>}` : "";
1063
1089
 
1090
+ /**
1091
+ * Converts a Tuple type into a _union_ of the tuple elements
1092
+ * ```ts
1093
+ * const arr = [1, 3, 5] as const;
1094
+ * // 1 | 3 | 5
1095
+ * type U = TupleToUnion<typeof arr>;
1096
+ * ```
1097
+ */
1098
+ declare type TupleToUnion<T> = Mutable<T> extends any[] ? Mutable<T>[number] : never;
1099
+
1100
+ /**
1101
+ * LastInUnion<1 | 2> = 2.
1102
+ */
1103
+ declare type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
1104
+ /**
1105
+ * UnionToTuple<1 | 2> = [1, 2].
1106
+ */
1107
+ declare type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
1108
+
1109
+ declare type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
1110
+
1111
+ declare type OneToOne = `1:1`;
1112
+ declare type OneToMany = `1:M`;
1113
+ declare type OneToZero = `1:0`;
1114
+ declare type ZeroToOne = `0:1`;
1115
+ declare type ZeroToMany = `0:M`;
1116
+ declare type ZeroToZero = `0:0`;
1117
+ declare type ManyToMany = "M:M";
1118
+ declare type ManyToOne = "M:1";
1119
+ declare type ManyToZero = "M:0";
1120
+ declare type CardinalityNode = "0" | "1" | "M";
1121
+ /**
1122
+ * Cardinality which expects a singular input and requires
1123
+ * 1 or many outputs.
1124
+ *
1125
+ * Note: choose `CardinalityFilter1` if you want to allow output
1126
+ * to have no outputs.
1127
+ */
1128
+ declare type Cardinality1 = OneToOne | OneToMany;
1129
+ /**
1130
+ * Cardinality which expects a singular input and maps to 0,
1131
+ * 1, or many outputs.
1132
+ */
1133
+ declare type CardinalityFilter1 = OneToOne | OneToMany | OneToZero;
1134
+ /**
1135
+ * Cardinality which expects a singular input which is allowed to be
1136
+ * _undefined_ or the expected type.
1137
+ */
1138
+ declare type Cardinality0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany;
1139
+ /**
1140
+ * Cardinality which expects a singular input -- which is allowed to be
1141
+ * _undefined_ -- and maps to 0,
1142
+ * 1, or many outputs.
1143
+ */
1144
+ declare type CardinalityFilter0 = ZeroToOne | ZeroToMany | OneToOne | OneToMany | OneToZero | ZeroToZero;
1145
+ declare type CardinalityExplicit = `${number}:${number}`;
1146
+ /**
1147
+ * Cardinality of any sort between two types
1148
+ */
1149
+ declare type Cardinality = CardinalityFilter0 | CardinalityFilter1 | ManyToMany | ManyToOne | ManyToZero | CardinalityExplicit;
1150
+ declare type CardinalityTuple<T extends Cardinality> = UnionToTuple<T>;
1151
+ /**
1152
+ * The first or _input_ part of the Cardinality relationship
1153
+ */
1154
+ declare type CardinalityIn<T extends Cardinality> = T extends `${infer IN}:${string}` ? IN : never;
1155
+ /**
1156
+ * The second or _output_ part of the Cardinality relationship
1157
+ */
1158
+ declare type CardinalityOut<T extends Cardinality> = T extends `${string}:${infer OUT}` ? OUT : never;
1159
+ declare type CardinalityInput<T, C extends Cardinality> = CardinalityTuple<C>[0] extends 0 ? T | undefined : CardinalityTuple<C>[0] extends 1 ? T : T[];
1160
+
1064
1161
  /**
1065
1162
  * Converts a string literal into a _dasherized_ format while ignoring _exterior_ whitespace.
1066
1163
  *
@@ -1192,6 +1289,11 @@ declare type PureFluentApi<TApi extends Record<string, (...args: any[]) => PureF
1192
1289
  */
1193
1290
  declare type FinalReturn<T extends any> = T extends (...args: any[]) => any ? FinalReturn<ReturnType<T>> : T;
1194
1291
 
1292
+ /**
1293
+ * A function which returns a boolean value
1294
+ */
1295
+ declare type LogicFunction<T extends any[]> = (...args: T) => boolean;
1296
+
1195
1297
  declare type DictFromKv<T extends readonly Readonly<{
1196
1298
  key: string;
1197
1299
  value: unknown;
@@ -1272,15 +1374,6 @@ declare type DictArray<T> = Array<{
1272
1374
  [K in keyof T]: DictArrayKv<K, T>;
1273
1375
  }[keyof T]>;
1274
1376
 
1275
- /**
1276
- * LastInUnion<1 | 2> = 2.
1277
- */
1278
- declare type LastInUnion<U> = UnionToIntersection<U extends unknown ? (x: U) => 0 : never> extends (x: infer L) => 0 ? L : never;
1279
- /**
1280
- * UnionToTuple<1 | 2> = [1, 2].
1281
- */
1282
- declare type UnionToTuple<U, Last = LastInUnion<U>> = [U] extends [never] ? [] : [...UnionToTuple<Exclude<U, Last>>, Last];
1283
-
1284
1377
  /**
1285
1378
  * Returns the _first_ key in an object.
1286
1379
  *
@@ -1309,18 +1402,6 @@ declare type FirstKeyValue<T extends object> = FirstKey<T> extends keyof T ? T[F
1309
1402
  */
1310
1403
  declare type FirstOfEach<T extends readonly any[][]> = T[number][0] extends T[number][number] ? T[number][0] : never;
1311
1404
 
1312
- /**
1313
- * Converts a Tuple type into a _union_ of the tuple elements
1314
- * ```ts
1315
- * const arr = [1, 3, 5] as const;
1316
- * // 1 | 3 | 5
1317
- * type U = TupleToUnion<typeof arr>;
1318
- * ```
1319
- */
1320
- declare type TupleToUnion<T> = Mutable<T> extends any[] ? Mutable<T>[number] : never;
1321
-
1322
- declare type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
1323
-
1324
1405
  /**
1325
1406
  * Typescript utility which receives `T` as shape which resembles `DictArray<D>`
1326
1407
  * and if the type `D` can be inferred it is returned.
@@ -1422,6 +1503,116 @@ declare function ruleSet<N extends Narrowable, TState extends Record<keyof TStat
1422
1503
 
1423
1504
  declare const api: <N extends Narrowable, TPrivate extends Readonly<Record<any, N>>>(priv: TPrivate) => <TPublic extends object>(pub: TPublic) => () => TPublic;
1424
1505
 
1506
+ /**
1507
+ * Groups a number of "logic functions" together by combining their results using
1508
+ * the logical **AND** operator.
1509
+ *
1510
+ * **Note:** a "logic function" is any function which returns a boolean
1511
+ */
1512
+ declare const and: <T extends any[]>(...ops: readonly LogicFunction<T>[]) => LogicFunction<T>;
1513
+
1514
+ /**
1515
+ * Groups a number of "logic functions" together by combining their results using
1516
+ * the logical **OR** operator.
1517
+ *
1518
+ * **Note:** a "logic function" is any function which returns a boolean
1519
+ */
1520
+ declare const or: <T extends any[]>(...ops: LogicFunction<T>[]) => LogicFunction<T>;
1521
+
1522
+ /**
1523
+ * Groups a number of "logic functions" together by combining their results using
1524
+ * the logical **NOT** operator.
1525
+ *
1526
+ * **Note:** a "logic function" is any function which returns a boolean
1527
+ */
1528
+ declare const not: <T extends any[]>(op: LogicFunction<T>) => LogicFunction<T>;
1529
+
1530
+ declare type FilterStarts = {
1531
+ /** one or more string which the value is allowed to start with */
1532
+ startsWith: string | string[];
1533
+ };
1534
+ declare type FilterIs = {
1535
+ /** whether a string _**is**_ of a particular value */
1536
+ is: string | string[];
1537
+ };
1538
+ declare type FilterEnds = {
1539
+ endsWith: string | string[];
1540
+ };
1541
+ declare type FilterContains = {
1542
+ /** whether any of the strings specified are _contained_ in the value */
1543
+ contains: string | string[];
1544
+ };
1545
+ declare type FilterEquals = {
1546
+ /** one or more values which _equal_ the value passed in */
1547
+ equals: number | number[];
1548
+ };
1549
+ declare type FilterNotEqual = {
1550
+ /** one or more values which ALL _do not equal_ the value passed in */
1551
+ notEqual: number | number[];
1552
+ };
1553
+ declare type FilterGreaterThan = {
1554
+ /** the incoming value is greater than this value */
1555
+ greaterThan: number;
1556
+ };
1557
+ declare type FilterLessThan = {
1558
+ /** the incoming value is less than this value */
1559
+ lessThan: number;
1560
+ };
1561
+ declare type StringFilter = FilterIs | FilterStarts | FilterEnds | FilterContains | (FilterStarts & FilterEnds) | (FilterStarts & FilterContains) | (FilterEnds & FilterContains) | (FilterStarts & FilterEnds & FilterContains);
1562
+ 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);
1563
+ declare type FilterDefn = StringFilter | NumericFilter;
1564
+ declare type NotFilter = {
1565
+ /**
1566
+ * **not**
1567
+ *
1568
+ * If you want to build a filter who's conditions being met results in _filtering_
1569
+ * the value rather than accepting it then choose this.
1570
+ */
1571
+ not: FilterDefn;
1572
+ };
1573
+ declare function isNotFilter(f: FilterDefn | NotFilter): f is NotFilter;
1574
+ declare type UnwrapNot<T extends FilterDefn | NotFilter> = T extends NotFilter ? T["not"] extends StringFilter ? StringFilter : NumericFilter : T;
1575
+ declare function isNumericFilter(filter: FilterDefn): filter is NumericFilter;
1576
+ 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'";
1577
+ declare type UndefinedTreatment = "undefined treated as 'true'" | "undefined treated as 'false'";
1578
+ declare type LogicalCombinator = "AND" | "OR";
1579
+ /**
1580
+ * **FilterFn**
1581
+ *
1582
+ * 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:
1583
+ * be used like:
1584
+ * ```ts
1585
+ * const onlyPrivate = filter({ startsWith: "_" });
1586
+ * const privateFiles = files.filter(onlyPrivate);
1587
+ * ```
1588
+ *
1589
+ */
1590
+ declare type FilterFn<T extends StringFilter | NumericFilter> = T extends StringFilter ? <V extends string | undefined>(input: V) => boolean : <V extends number | undefined>(input: V) => boolean;
1591
+ /**
1592
+ * Defines a logical function for each condition type
1593
+ */
1594
+ declare type ConditionFilter<T extends StringFilter | NumericFilter> = T extends StringFilter ? (input: string) => boolean : (input: number) => boolean;
1595
+ /**
1596
+ * **filter**
1597
+ *
1598
+ * A higher order helper utility which builds a boolean _filter_ function based on a simple
1599
+ * configuration object. Support either _string_ or _numeric_ filters.
1600
+ *
1601
+ * ```ts
1602
+ * const str = filter({startsWith: ["_", "."], endsWith: ".md"});
1603
+ * const num = filter({ greaterThan: 55, notEqual: [66, 77]});
1604
+ * ```
1605
+ *
1606
+ * All conditions (e.g., `startsWith`, `contains`, `notEqual`, etc.) that a particular filter
1607
+ * is defined as having -- if there is more than one -- will be logically combined using AND
1608
+ * unless specified otherwise in the third parameter.
1609
+ *
1610
+ * How a value of _undefined_ will be treated is stated in the second parameter but defaults
1611
+ * to "no-impact" which means it's `false` when the logicCombinator is OR but defaults
1612
+ * to `true` when the logicCombinator is AND.
1613
+ */
1614
+ declare const filter: <F extends FilterDefn | NotFilter, U extends boolean | "no-impact", C extends LogicalCombinator>(config: F, logicCombinator?: C, ifUndefined?: U) => FilterFn<UnwrapNot<F>>;
1615
+
1425
1616
  /**
1426
1617
  * Passing in an array of strings, you are passed back a dictionary with
1427
1618
  * all the keys being the strings and values set to `true`.
@@ -1509,32 +1700,74 @@ declare function entries<N extends Narrowable, T extends Record<string, N>, I ex
1509
1700
  */
1510
1701
  declare function mapValues<N extends Narrowable, T extends Record<string, N>, V>(obj: T, valueMapper: (k: T[keyof T]) => V): { [K in keyof T]: V; };
1511
1702
 
1703
+ interface MapConfig<IR extends OptRequired = "req", D extends MapDirectionVal = "I -> O[]", OR extends OptRequired = "opt"> {
1704
+ input?: IR;
1705
+ output?: OR;
1706
+ direction?: D;
1707
+ }
1512
1708
  /**
1513
- * **mapTo**
1514
- *
1515
- * A utility function which maps one dictionary structure `I` to another `O`; which allows
1516
- * the transform to:
1517
- *
1518
- * - _split_ inputs into multiple outputs
1519
- * - _map_ 1:1 between input and output
1520
- * - _filter_ inputs which don't meet certain criteria (by returning `null`)
1521
- *
1522
- * This higher order function first asks for the mapping criteria:
1523
- * ```ts
1524
- * const mapper = mapTo<I,O>(i => i.name
1525
- * ? [
1526
- * { name: i.name, a: "static text", b: i.products.length }
1527
- * ]
1528
- * : null
1529
- * );
1530
- * ```
1709
+ * Provides a mapper function using the default configuration
1710
+ */
1711
+ declare type MapperApiDefault = <I, O>(map: MapTo<I, O>) => MapFn<I, O>;
1712
+ /**
1713
+ * Provides opportunity to configure _input_ and _output_ relationships
1714
+ * prior to providing a mapping function.
1715
+ */
1716
+ declare type MapperApiConfigured = <IR extends OptRequired = "req", D extends MapDirectionVal = "I -> O[]", OR extends OptRequired = "opt">(config: MapConfig<IR, D, OR>) => <I, O>(map: MapTo<I, O, IR, D, OR>) => MapFn<I, O, IR, D, OR>;
1717
+ /**
1718
+ * **mapTo** _utility_
1531
1719
  *
1532
- * and now you'll have a _mapper_ variable will be assigned as a mapping fn:
1720
+ * This utility creates a strongly typed data mapper which maps from one
1721
+ * known source `I` to another `O`:
1533
1722
  * ```ts
1534
- * function (source: I | I[]): O[]
1723
+ * const mapper = mapTo<I, O>(i => [{
1724
+ * foo: i.bar
1725
+ * }]);
1535
1726
  * ```
1536
1727
  */
1537
- declare const mapTo: <I extends {}, O extends {}>(cb: MapToWithFiltering<I, O>) => (source: I | I[]) => O[];
1728
+ declare const mapToFn: <I, O>(map: (source: I) => O[]) => <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null;
1729
+ /**
1730
+ * Provides a `config` method which allows the relationships between _inputs_
1731
+ * and _outputs_ to be configured.
1732
+ */
1733
+ declare const mapToDict: {
1734
+ /** configure the relationship between the _inputs_ and _outputs_ */
1735
+ config: <IR extends OptRequired = "req", D extends "I -> O[]" | "I -> O" | "I[] -> O" = "I -> O[]", OR extends OptRequired = "opt">(c?: MapConfig<IR, D, OR>) => {
1736
+ /**
1737
+ * create your mapping with your recently setup configuration:
1738
+ * ```ts
1739
+ * const mapper = mapTo
1740
+ * .config({ ... })
1741
+ * .map<I, O>(i => [{
1742
+ * foo: i.bar
1743
+ * }]);
1744
+ * ```
1745
+ */
1746
+ map<I, O>(map: MapTo<I, O, IR, D, OR>): MapFn<I, O, IR, D, OR>;
1747
+ };
1748
+ };
1749
+ /**
1750
+ * **mapTo** _utility_
1751
+ *
1752
+ * This utility creates a strongly typed data mapper which maps from one
1753
+ * known source `I` to another `O`.
1754
+ */
1755
+ declare const mapTo: (<I, O>(map: (source: I) => O[]) => <S extends I | I[]>(source: S) => S extends I[] ? O[] : O[] | null) & {
1756
+ /** configure the relationship between the _inputs_ and _outputs_ */
1757
+ config: <IR extends OptRequired = "req", D extends "I -> O[]" | "I -> O" | "I[] -> O" = "I -> O[]", OR extends OptRequired = "opt">(c?: MapConfig<IR, D, OR>) => {
1758
+ /**
1759
+ * create your mapping with your recently setup configuration:
1760
+ * ```ts
1761
+ * const mapper = mapTo
1762
+ * .config({ ... })
1763
+ * .map<I, O>(i => [{
1764
+ * foo: i.bar
1765
+ * }]);
1766
+ * ```
1767
+ */
1768
+ map<I, O>(map: MapTo<I, O, IR, D, OR>): MapFn<I, O, IR, D, OR>;
1769
+ };
1770
+ };
1538
1771
 
1539
1772
  /**
1540
1773
  * converts an array of strings `["a", "b", "c"]` into a more type friendly
@@ -1592,6 +1825,24 @@ declare function kvToDict<K extends string, V extends Narrowable, T extends read
1592
1825
  value: V;
1593
1826
  }>[]>(kvArr: T): DictFromKv<T>;
1594
1827
 
1828
+ /**
1829
+ * Type utility which converts `undefined[]` to `unknown[]`
1830
+ */
1831
+ declare type UndefinedArrayIsUnknown<T extends any[]> = undefined[] extends T ? unknown[] : T;
1832
+ 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[]>;
1833
+ /**
1834
+ * Ensures that any input passed in is passed back as an array:
1835
+ *
1836
+ * - if it was already an array than this just serves as an _identity_ function
1837
+ * - if it was not then it wraps the element into a one element array of the
1838
+ * given type
1839
+ *
1840
+ * Note: by default the _type_ of values will be intentionally widened so that the value "abc"
1841
+ * is of type `string` not the literal `abc`. If you want to keep literal types then
1842
+ * change the optional _widen_ parameter to _false_.
1843
+ */
1844
+ declare const asArray: <T extends Narrowable, W extends boolean = true>(thing: T, _widen?: W | undefined) => AsArray<T, W>;
1845
+
1595
1846
  /**
1596
1847
  * Groups an array of data based on the value of a property
1597
1848
  * in the objects within the array.
@@ -1707,33 +1958,6 @@ declare function idTypeGuard<T extends {
1707
1958
  */
1708
1959
  declare function literal<N extends Narrowable, T extends Record<keyof T, N>>(obj: T): T;
1709
1960
 
1710
- declare type Filter<A> = {
1711
- kind: "Equals";
1712
- field: keyof A;
1713
- val: A[keyof A];
1714
- } | {
1715
- kind: "Greater";
1716
- field: keyof A;
1717
- val: A[keyof A];
1718
- } | {
1719
- kind: "Less";
1720
- field: keyof A;
1721
- val: A[keyof A];
1722
- } | {
1723
- kind: "And";
1724
- a: Filter<A>;
1725
- b: Filter<A>;
1726
- } | {
1727
- kind: "Or";
1728
- a: Filter<A>;
1729
- b: Filter<A>;
1730
- };
1731
- declare const equals: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
1732
- declare const greater: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
1733
- declare const less: <A, K extends keyof A>(field: K, val: A[K]) => Filter<A>;
1734
- declare const and: <A>(a: Filter<A>, b: Filter<A>) => Filter<A>;
1735
- declare const or: <A>(a: Filter<A>, b: Filter<A>) => Filter<A>;
1736
-
1737
1961
  declare function Model<N extends string, _R extends {} = {}, _O extends {} = {}>(name: N): {
1738
1962
  required<P extends string>(_prop: P): {
1739
1963
  required<P_1 extends string>(_prop: P_1): any;
@@ -1821,4 +2045,4 @@ interface IFluentConfigurator<C> {
1821
2045
  */
1822
2046
  declare function FluentConfigurator<I>(initial?: I): IFluentConfigurator<{}>;
1823
2047
 
1824
- 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, IsBooleanLiteral, IsCapitalized, IsFalse, IsFunction, IsLiteral, IsNumericLiteral, IsObject, IsString, IsStringLiteral, 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 };
2048
+ export { AllCaps, Alpha, AlphaNumeric, Api, ApiFunction, ApiValue, AppendToDictionary, AppendToObject, ArrConcat, Array$1 as Array, ArrayConverter, AsArray, AssertExtends, Bracket, Break, CamelCase, CapitalizeWords, Cardinality, Cardinality0, Cardinality1, CardinalityExplicit, CardinalityFilter0, CardinalityFilter1, CardinalityIn, CardinalityInput, CardinalityNode, CardinalityOut, CardinalityTuple, 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, ManyToMany, ManyToOne, ManyToZero, MapConfig, MapDirection, MapDirectionVal, MapFn, MapFnInput, MapFnOutput, MapInput, MapOutput, MapTo, MapperApiConfigured, MapperApiDefault, MaybeFalse, MaybeTrue, Model, Mutable, MutableProps, MutationFunction, MutationIdentity, Narrowable, NonAlpha, NonNumericKeys, NonStringKeys, Not, NotFilter, Numeric, NumericFilter, NumericKeys, NumericString, ObjectType, OneToMany, OneToOne, OneToZero, Opaque, OpeningBracket, OptRequired, 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, ZeroToMany, ZeroToOne, ZeroToZero, 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, mapToDict, mapToFn, mapValues, nameLiteral, not, or, randomString, readonlyFnWithProps, ruleSet, strArrayToDict, type, typeApi, uuid, valueTypes, withValue };