@sheetxl/formulas 0.8.0-beta.1 → 0.8.0-beta.2

package/types/src/logical/Logical.d.ts

@@ -1,100 +1,106 @@
-import { IRange, AcceptError, AcceptRefError, IReferenceRange, Scalar, Lambda, Omittable, Repeating } from '@sheetxl/primitives';
+import { IRange, AcceptError, IReferenceRange, Scalar, Lambda, Lazy, Omittable, Repeating } from '@sheetxl/primitives';
 /**
- * @summary Checks whether all arguments are TRUE, and returns TRUE if all arguments are TRUE.
+ * Checks whether all arguments are TRUE, and returns TRUE if all arguments are TRUE.
  * @param logical are 1 to 255 conditions you want to test that can be either TRUE or FALSE and can be logical values, arrays, or references.
  */
-export declare function AND(logical: IRange[]): Scalar;
+export declare function AND(logical: IRange<boolean>[]): Scalar;
 /**
- * @summary Applies a LAMBDA function to each column and returns an array of the results.
+ * Applies a LAMBDA function to each column and returns an array of the results.
  * @param array is an array to be separated by column.
  * @param fn is a LAMBDA that takes a column as its single parameter and returns one result for it.
  */
-export declare function BYCOL(array: AcceptRefError<IRange>, fn?: Lambda<[column: IRange], Scalar>): IRange;
+export declare function BYCOL(array: IRange, fn?: Lambda<[column: IRange], Scalar>): IRange;
 /**
- * @summary Applies a LAMBDA function to each row and returns an array of the results.
+ * Applies a LAMBDA function to each row and returns an array of the results.
  * @param array is an array to be separated by row.
  * @param fn is a LAMBDA that takes a row as its single parameter and returns one result for it.
  */
-export declare function BYROW(array: AcceptRefError<IRange>, fn?: Lambda<[row: IRange], Scalar>): IRange;
+export declare function BYROW(array: IRange, fn?: Lambda<[row: IRange], Scalar>): IRange;
 /**
- * @summary Returns the logical value FALSE.
+ * Returns the logical value FALSE.
  */
 export declare function FALSE(): boolean;
 /**
- * @summary Flattens all the values from one or more ranges into a single column.
+ * Flattens all the values from one or more ranges into a single column.
  * @param ranges One or more ranges or scalar values to flatten.
  * @category Sheets
  */
-export declare function FLATTEN(ranges: AcceptError<IRange>[]): IRange;
+export declare function FLATTEN(ranges: IRange[]): IRange;
 /**
- * @summary Checks whether a condition is met, and returns one value if TRUE, and another value if FALSE.
+ * Checks whether a condition is met, and returns one value if TRUE, and another value if FALSE.
  * @param logicalTest is any value or expression that can be evaluated to TRUE or FALSE.
  * @param valueIfTrue is the value that is returned if logicalTest is TRUE. If omitted, TRUE is returned. You can nest up to seven IF functions.
  * @param valueIfFalse is the value that is returned if logicalTest is FALSE. If omitted, FALSE is returned.
  */
-export declare function IF(logicalTest: boolean, valueIfTrue: AcceptError<any>, valueIfFalse?: AcceptError<any>): any;
+export declare function IF(logicalTest: boolean, valueIfTrue: Lazy<AcceptError<any>>, valueIfFalse: Lazy<AcceptError<any>, false>): any;
 /**
- * @summary Returns valueIfError if expression is an error and the value of the expression itself otherwise.
+ * Returns valueIfError if expression is an error and the value of the expression itself otherwise.
  * @param value is any value or expression or reference.
  * @param valueIfError is any value or expression or reference.
  */
-export declare function IFERROR(value: AcceptError<Scalar>, valueIfError: AcceptError<any>): Scalar;
+export declare function IFERROR(value: AcceptError<Scalar>, valueIfError: Lazy<AcceptError<any>>): Scalar;
 /**
- * @summary Returns the value you specify if the expression resolves to #N/A, otherwise returns the result of the expression.
+ * Returns the value you specify if the expression resolves to #N/A, otherwise returns the result of the expression.
  * @param value is any value or expression or reference.
  * @param valueIfNA is any value or expression or reference.
  */
-export declare function IFNA(value: AcceptError<Scalar>, valueIfNA: AcceptError<any>): Scalar;
+export declare function IFNA(value: AcceptError<Scalar>, valueIfNA: Lazy<AcceptError<any>>): Scalar;
 /**
- * @summary Checks whether one or more conditions are met and returns a value corresponding to the first TRUE condition.
+ * Checks whether one or more conditions are met and returns a value corresponding to the first TRUE condition.
  * @param condition the conditions to test and the values to return for them.
  * @param condition.logicalTest is any value or expression that can be evaluated to TRUE or FALSE.
  * @param condition.logicalTrue is the value returned if logicalTest is TRUE.
+ *
+ * @remarks
+ * The search STOPS at the first TRUE condition, and a condition past it is never read: a
+ * `#DIV/0!` or an uncoercible text there does not surface. A fault reached BEFORE the match is
+ * fatal, which is why the test slot accepts errors and this body decides — the engine's own
+ * left-to-right propagation would refuse the whole call for a condition Excel never evaluates.
  */
-export declare function IFS(condition: Repeating<[logicalTest: boolean, logicalTrue: AcceptError<any>]>): any;
+export declare function IFS(condition: Repeating<[logicalTest: AcceptError<boolean>, logicalTrue: AcceptError<any>], 254>): any;
 /**
- * @summary Creates a function value which can be called within formulas.
+ * Creates a function value which can be called within formulas.
  * @param parameterOrCalculation a parameter or a calculation that returns a value. If a parameter, it must be the last argument.
  */
-export declare function LAMBDA(parameterOrCalculation: AcceptError<IRange>[]): Lambda;
+export declare function LAMBDA(parameterOrCalculation: Repeating<AcceptError<IRange>, 254>): Lambda;
 /**
- * @summary Assigns calculation results to names. Useful for storing intermediate calculations and values by defining names inside a formula. These names only apply within the scope of the LET function.
+ * Assigns calculation results to names. Useful for storing intermediate calculations and values by defining names inside a formula. These names only apply within the scope of the LET function.
  * @param name the name, or a calculation which can make use of all names within the LET. Names must start with a letter, cannot be the output of a formula, or conflict with range syntax.
  * @param nameOrValue the value associated with the name.
  */
-export declare function LET(name: AcceptError<any>, nameOrValue: AcceptError<IRange>, calculationOrName: AcceptError<IRange>, ...rest: AcceptError<IRange>[]): any;
+export declare function LET(name: AcceptError<any>, nameOrValue: AcceptError<IRange>, calculationOrName: AcceptError<IRange>, ...rest: Repeating<AcceptError<IRange>, 254>): any;
 /**
- * @summary Returns a calculated array of a specified row and column size, by applying a LAMBDA function.
+ * Returns a calculated array of a specified row and column size, by applying a LAMBDA function.
  * @param rows is the number of rows in the array. Must be greater than zero.
  * @param columns is the number of columns in the array. Must be greater than zero.
  * @param fn is a LAMBDA that is called to create the array. The LAMBDA takes two parameters, row index and column index.
  */
 export declare function MAKEARRAY(rows: Omittable<number, 1>, columns: Omittable<number, 1>, fn: Lambda<[rowIndex: number, colIndex: number], Scalar>): IRange;
 /**
- * @summary Returns an array formed by 'mapping' each value in the array(s) to a new value by applying a lambda to create a new value.
+ * Returns an array formed by 'mapping' each value in the array(s) to a new value by applying a lambda to create a new value.
  * @param array is an array to be mapped.
  * @param lambdaOrArray is a LAMBDA which must be the last argument and must have a parameter for each array passed, or another array to be mapped.
  */
-export declare function MAP(array: AcceptRefError<IRange>, lambdaOrArray: (any | Lambda<any[], Scalar>)[]): IRange;
+export declare function MAP(array: IRange, lambdaOrArray: AcceptError<any | Lambda<any[], Scalar>>[]): IRange;
 /**
- * @summary Changes FALSE to TRUE, or TRUE to FALSE.
+ * Changes FALSE to TRUE, or TRUE to FALSE.
  * @param logical is a value or expression that can be evaluated to TRUE or FALSE.
  */
 export declare function NOT(logical: boolean): boolean;
 /**
- * @summary Checks whether any of the arguments are TRUE, and returns TRUE or FALSE. Returns FALSE only if all arguments are FALSE.
+ * Checks whether any of the arguments are TRUE, and returns TRUE or FALSE. Returns FALSE only if all arguments are FALSE.
  * @param logical are 1 to 255 conditions that you want to test that can be either TRUE or FALSE.
  */
-export declare function OR(logical: IRange[]): Scalar;
+export declare function OR(logical: IRange<boolean>[]): Scalar;
 /**
- * @summary Reduces an array to an accumulated value by applying a LAMBDA function to each value and returning the total value in the accumulator.
+ * Reduces an array to an accumulated value by applying a LAMBDA function to each value and returning the total value in the accumulator.
  * @param initialValue is the starting value for the accumulator.
  * @param array is an array to be reduced.
  * @param fn is a LAMBDA that is called to reduce the array. The LAMBDA takes two parameters, accumulator and value.
  */
-export declare function REDUCE(initialValue: Omittable<AcceptError<any>>, array: AcceptRefError<IRange>, fn: Lambda<[accumulator: any, value: Scalar], any>): any;
+export declare function REDUCE(initialValue: Omittable<AcceptError<any>>, array: IRange, fn: Lambda<[accumulator: any, value: IRange | Scalar], any>): any;
 /**
- * @summary Reduces the cells specified by a given condition or criteria.
+ * Reduces the cells specified by a given condition or criteria.
  * @param range is the range of cells you want evaluated.
  * @param criteria is the condition or criteria in the form of a number, expression, or text that defines which cells will be reduced.
  * @param reduceRange are the actual cells to reduce. If omitted, the cells in range are used. This can be blank.
@@ -104,30 +110,30 @@ export declare function REDUCE(initialValue: Omittable<AcceptError<any>>, array:
  * @remarks
  * This is a lambda equivalent to SUMIF, COUNTIF, and AVERAGEIF.
  */
-export declare function REDUCEIF(range: AcceptError<IReferenceRange>, criteria: AcceptError<Scalar>, reduceRange: Omittable<AcceptError<IReferenceRange>>, fn: Lambda<[accumulator: Scalar, value: Scalar], Scalar>): Scalar;
+export declare function REDUCEIF(range: IReferenceRange, criteria: AcceptError<Scalar>, reduceRange: Omittable<IReferenceRange>, fn: Lambda<[accumulator: Scalar, value: Scalar], Scalar>): Scalar;
 /**
- * @summary Scans an array by applying a LAMBDA function to each value and returns an array that has each intermediate value.
+ * Scans an array by applying a LAMBDA function to each value and returns an array that has each intermediate value.
  * @param initialValue is the starting value for the accumulator.
  * @param array is an array to be reduced.
  * @param fn is a LAMBDA that is called to reduce the array. The LAMBDA takes two parameters, accumulator and value.
  */
-export declare function SCAN(initialValue: Omittable<Scalar>, array: AcceptRefError<IRange>, fn: Lambda<[accumulator: Scalar, value: Scalar], Scalar>): IRange;
+export declare function SCAN(initialValue: Omittable<AcceptError<any>>, array: IRange, fn: Lambda<[accumulator: any, value: IRange | Scalar], Scalar>): IRange;
 /**
- * @summary Evaluates an expression against a list of values and returns the result corresponding to the first matching value. If there is no match, an optional default value is returned.
+ * Evaluates an expression against a list of values and returns the result corresponding to the first matching value. If there is no match, an optional default value is returned.
  * @param match the values to compare against expression and the results to return for them.
  * @param match.value is a value to compare against expression.
  * @param match.result is a result to be returned if the corresponding value matches expression.
  * @param expression is an expression to be evaluated.
  * @param defaultResult is the result to be returned when no value matches expression.
  */
-export declare function SWITCH(expression: Scalar, match: Repeating<[value: Scalar, result: AcceptError<any>]>, defaultResult?: Omittable<AcceptError<any>, 0>): any;
+export declare function SWITCH(expression: Scalar, match: Repeating<[value: AcceptError<Scalar>, result: AcceptError<any>], 254>, defaultResult?: Omittable<AcceptError<any>, 0>): any;
 /**
- * @summary Returns the logical value TRUE.
+ * Returns the logical value TRUE.
  */
 export declare function TRUE(): boolean;
 /**
- * @summary Returns a logical 'Exclusive Or' of all arguments.
+ * Returns a logical 'Exclusive Or' of all arguments.
  * @param logical are 1 to 254 conditions you want to test that can be either TRUE or FALSE and can be logical values, arrays, or references.
  */
-export declare function XOR(logical: IRange[]): Scalar;
+export declare function XOR(logical: Repeating<IRange<boolean>, 254>): Scalar;
 //# sourceMappingURL=Logical.d.ts.map

package/types/src/lookupReference/GroupBy.d.ts

@@ -1,7 +1,7 @@
-import { IRange, AcceptRefError, Flatten, Omittable, Scalar } from '@sheetxl/primitives';
+import { IRange, Flatten, Omittable, Scalar } from '@sheetxl/primitives';
 /**
- * @hidden Unimplemented TODO
- * @summary Aggregate values by row fields.
+ * Aggregate values by row fields.
+ * @hidden Not yet implemented.
  * @param rowFields The range or array containing the row fields.
  * @param values The range or array containing the values to aggregate.
  * @param fn The function used to do the aggregations.
@@ -11,7 +11,7 @@ import { IRange, AcceptRefError, Flatten, Omittable, Scalar } from '@sheetxl/pri
  * @param filterArray param-534 paramName-535.
  * @param fieldRelationship The relationship of fields when multiple columns are supplied to the rowFields argument.
  */
-export declare function GROUPBY(rowFields: AcceptRefError<IRange>, values: IRange, fn: Flatten<any>, // This can be either a Lamda function or a builtIn.
+export declare function GROUPBY(rowFields: IRange, values: IRange, fn: Flatten<any>, // This can be either a lambda function or a built-in.
 fieldHeaders?: Omittable<number>, // 0-no, 1-yes, 2-no but generate, 3-yes and show
 totalDepth?: number, // 0-no totals, 1-grand totals, 2-grand and subtotals, -1-grand totals at top, -2 grand and sub totals at top
 sortOrder?: Omittable<Flatten<any>>, // <0, >0

package/types/src/lookupReference/PivotBy.d.ts

@@ -1,7 +1,7 @@
-import { IRange, AcceptRefError, Flatten, Omittable, Scalar } from '@sheetxl/primitives';
+import { IRange, Flatten, Omittable, Scalar } from '@sheetxl/primitives';
 /**
- * @hidden Unimplemented TODO
- * @summary Aggregate values by rows and columns.
+ * Aggregate values by rows and columns.
+ * @hidden Not yet implemented.
  * @param rowFields The range or array containing the row fields.
  * @param colFields The range or array containing the column fields.
  * @param values The range or array containing the value fields.
@@ -14,7 +14,7 @@ import { IRange, AcceptRefError, Flatten, Omittable, Scalar } from '@sheetxl/pri
  * @param filterArray An array of boolean where TRUE represents a row to retain.
  * @param relativeTo Defines what PERCENTOF is calculated relative to.
  */
-export declare function PIVOTBY(rowFields: AcceptRefError<IRange>, colFields: AcceptRefError<IRange>, values: Flatten<IRange>, fn: Flatten<IRange>, // Wow, this is a lambda function? No. I don't think so...
+export declare function PIVOTBY(rowFields: IRange, colFields: IRange, values: Flatten<IRange>, fn: Flatten<IRange>, // This can be either a lambda function or a built-in.
 fieldHeaders?: Omittable<number>, // 0-no, 1-yes, 2-no but generate, 3-yes and show
 rowTotalDepth?: number, // 0-no totals, 1-grand totals, 2-grand and subtotals, -1-grand totals at top, -2 grand and sub totals at top
 rowSortOrder?: Omittable<Flatten<any>>, // <0, >0