@sheetxl/formulas 0.8.0-beta.10 → 0.8.0-beta.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/formulas",
   "description": "Formulas - TypeScript formulas compatible with Excel built-ins.",
-  "version": "0.8.0-beta.10",
+  "version": "0.8.0-beta.12",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -10,6 +10,12 @@
       "browser": "./browser/esm/index.mjs",
       "node": "./node/esm/index.mjs",
       "default": "./browser/esm/index.mjs"
+    },
+    "./declarations": {
+      "types": "./types/declarations.d.ts",
+      "browser": "./browser/esm/declarations.mjs",
+      "node": "./node/esm/declarations.mjs",
+      "default": "./browser/esm/declarations.mjs"
     }
   },
   "types": "./types/index.d.ts",
@@ -36,8 +42,8 @@
     "formulas"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.10",
-    "@sheetxl/scripting": "^0.8.0-beta.10",
+    "@sheetxl/primitives": "^0.8.0-beta.12",
+    "@sheetxl/scripting": "^0.8.0-beta.12",
     "bahttext": "^2.4.0",
     "bessel": "^1.0.2"
   }

package/types/declarations.d.ts

@@ -0,0 +1,4 @@
+export {}
+import Formulas from './src/.generated/declarations'
+export default Formulas
+export {}

package/types/src/.generated/decl/financial/MarketHistory.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=MarketHistory.decl.d.ts.map

package/types/src/.generated/declarations.d.ts

@@ -0,0 +1,7 @@
+import { FunctionDeclarationModule } from '@sheetxl/scripting';
+/**
+ * This package's declarations, one entry per source module, in binding order.
+ */
+declare const declarations: readonly FunctionDeclarationModule[];
+export default declarations;
+//# sourceMappingURL=declarations.d.ts.map

package/types/src/.generated/desc/financial/MarketHistory.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=MarketHistory.desc.d.ts.map

package/types/src/_utils/Arithmetic.d.ts

@@ -12,6 +12,22 @@
  * the arctangent.
  */
 export declare const flushSubnormal: (value: number) => number;
+/**
+ * The shift Excel adds to a count or position argument before truncating it.
+ *
+ * It is a small ABSOLUTE constant, so a value just under an integer counts as that integer at any
+ * magnitude: `LEFT("hello",0.9999999)` is "h" and `LEFT("hello",0.999999)` — one digit less — is
+ * the empty string.
+ *
+ * Which functions shift is a PER-FUNCTION fact, not an engine one, and the family is split down
+ * the middle: LEFT, RIGHT, FIND, SEARCH, REPLACE, SUBSTITUTE, CHAR, INDEX and ROUND shift, while
+ * MID, REPT and UNICHAR truncate the double as it stands (`MID("hello",0.9999999,1)` is #VALUE!
+ * and `UNICHAR(0.9999999)` is too). So this is applied per call site rather than in the
+ * declaration.
+ */
+export declare const COUNT_EPSILON: number;
+/** A count or position argument, shifted by {@link COUNT_EPSILON} and truncated. */
+export declare const excelCount: (count: number) => number;
 /**
  * The inverse hyperbolic tangent, decomposed the way a C library does it — the log form above
  * half and `log1p` below — rather than through the platform's `Math.atanh`.

package/types/src/_utils/Distributions.d.ts

@@ -62,8 +62,8 @@ export declare const binomialPdf: (k: number, n: number, p: number) => number;
  * The CDF is the complement of a `1e-10` incomplete beta, ROUNDED to that same tolerance.
  *
  * The rounding is EXCEL'S, not a leftover: it is why a cumulative binomial in the bulk carries
- * ten decimal places and no more. Taking it out moves answers AWAY from Excel — it costs sixty
- * of BINOM.DIST's rows on its own — so it is not a cleanup to make.
+ * ten decimal places and no more. Taking it out moves answers AWAY from Excel, so it is not a
+ * cleanup to make.
  */
 export declare function binomialCdf(x: number, n: number, p: number): number;
 export declare function negbinPdf(k: number, r: number, p: number): number;
@@ -85,8 +85,7 @@ export declare const betaInv: (p: number, alpha: number, beta: number) => number
  * Half-width of the confidence interval around a mean, from the normal quantile.
  *
  * The `(1 + h) - 1` round trip is not redundant: it rounds the half-width against a unit
- * magnitude, which moves the answer on most shapes. Whether Excel rounds there too is not
- * established, so the round trip stays.
+ * magnitude, which moves the answer on most shapes.
  */
 export declare function normalConfidence(alpha: number, standardDev: number, size: number): number;
 /** The same half-width from Student's t on `size - 1` degrees of freedom. */

package/types/src/_utils/Matrix.d.ts

@@ -9,8 +9,8 @@
  * them, and one without pivoting produces a different residue again.
  *
  * The inverse is this same decomposition followed by a forward and back SUBSTITUTION per unit
- * column. Gauss-Jordan over `[A | I]` — the textbook alternative, and in five spellings — lands
- * further from Excel on the same matrices.
+ * column. Gauss-Jordan over `[A | I]` — the textbook alternative — gives different answers on
+ * the same matrices.
  */
 /**
  * The determinant, as the signed product of the pivots.

package/types/src/_utils/SpecialFunctions.d.ts

@@ -57,8 +57,8 @@ export declare const upRegGamma: (a: number, x: number) => number;
  *   -a (u - ln(1+u)) - ln(1+u) - ln(a)/2 - ln(2 pi)/2 - stirlerr(a),   u = x/a - 1
  * ```
  *
- * whose every term is the size of the answer. Excel's own `GAMMA.DIST(1E7,1E7,1,FALSE)` is bit
- * for bit the value this returns, so it is what Excel computes too.
+ * whose every term is the size of the answer. It is Excel's form: `GAMMA.DIST(1E7,1E7,1,FALSE)`
+ * is exactly the value this returns.
  */
 export declare function gammaLogPdf(a: number, x: number): number;
 /** The inverse of {@link lowRegGamma} in its second argument. */

package/types/src/financial/MarketHistory.d.ts

@@ -0,0 +1,40 @@
+import { Scalar, Flatten, Omittable } from '@sheetxl/primitives';
+/**
+ * Returns an array of historical quote data for a symbol and date range you specify.
+ * @param stock the ticker symbol of the financial instrument (`"IBM"`).
+ * @param startDate the first date to return data from.
+ * @param endDate the last date to return data from. Default is the start date.
+ * @param interval the granularity of the data: `0` daily, `1` weekly, `2` monthly. Default is `0`.
+ * @param headers whether to add column headers: `0` none, `1` a header row, `2` the instrument identifier and a header row. Default is `1`.
+ * @param properties the columns to return, each a number: `0` Date, `1` Close, `2` Open, `3` High, `4` Low, `5` Volume. Default is Date and Close.
+ *
+ * @remarks
+ * * The cell shows `#BUSY!` until the quotes arrive, then spills one row per bar, ascending.
+ * * Quotes come from [Alpha Vantage](https://www.alphavantage.co), which needs an API key:
+ *   `ALPHAVANTAGE_API_KEY` on the global object or in the environment. Without one the service's
+ *   `demo` key is used, which answers for `IBM` only. A free key allows 25 requests a day.
+ * * An unknown symbol is `#N/A`. A spent request budget is `#VALUE!` carrying the service's notice.
+ * * A recalculation does not ask again; the quotes are kept with the cell. Reopening the file does.
+ * * Excel accepts a Stock data type for `stock`; here it is the ticker text.
+ */
+export declare function STOCKHISTORY(stock: string, startDate: number, endDate?: Omittable<number>, interval?: Omittable<number>, headers?: Omittable<number>, properties?: Flatten<Scalar>): Scalar[][];
+/**
+ * Returns the daily exchange rate of one currency in another over a period, from the European
+ * Central Bank's reference rates.
+ * @param from the currency to convert from, as an ISO code (`"USD"`).
+ * @param to the currency to convert to, as an ISO code (`"EUR"`).
+ * @param startDate the first date of the period.
+ * @param endDate the last date of the period. Default is the start date.
+ * @param headers whether to add column headers: `0` none, `1` a header row, `2` the pair and a header row. Default is `1`.
+ *
+ * @remarks
+ * * Spills one row per business day in the period, with the date and the rate. The cell shows
+ *   `#BUSY!` until the rates arrive.
+ * * Rates are the ECB's daily reference rates (about 16:00 CET), published on TARGET business
+ *   days; weekends and holidays have no row.
+ * * Both currencies must be among the roughly thirty the ECB publishes; another is `#N/A`.
+ * * A recalculation does not ask again; the rates are kept with the cell. Reopening the file does.
+ * * Data by [Frankfurter](https://frankfurter.dev), a free service with no key. Please do not abuse it.
+ */
+export declare function FXHISTORY(from: string, to: string, startDate: number, endDate?: Omittable<number>, headers?: Omittable<number>): Scalar[][];
+//# sourceMappingURL=MarketHistory.d.ts.map

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

@@ -70,11 +70,10 @@ export declare function DROP(array: IRange, row: number, columns?: Omittable<num
 export declare function EXPAND(array: IRange | Scalar, row: Omittable<number>, columns?: Omittable<number>, padWith?: NoLift<Omittable<AcceptError<Scalar>>>): IRange;
 /**
  * Extracts a value from a field of a given record.
- * @hidden Unimplemented RichData
  * @param value The record from which you want to extract the field.
  * @param fieldName The names of the field or fields that you want to extract.
  */
-export declare function FIELDVALUE(value: IRichData, fieldName: string): Scalar[][];
+export declare function FIELDVALUE(value: AcceptError<IRichData>, fieldName: string): Scalar | IRange;
 /**
  * Filter a range or array.
  * @param array the range or array to filter.
@@ -112,21 +111,51 @@ export declare function HLOOKUP(lookupValue: Scalar, tableArray: Flatten<IRange>
 export declare function HSTACK(array: Repeating<IRange, 254>): IRange;
 /**
  * Creates a shortcut or jump that opens a document stored on your hard drive, a network server, or on the Internet.
- * @hidden Unimplemented RichData
  * @param linkLocation is the text giving the path and file name to the document to be opened, a hard drive location, UNC address, or URL path.
  * @param friendlyName is text or a number that is displayed in the cell. If omitted, the cell displays the linkLocation text.
+ * @returns A link that reads as its friendly name; a reference to it is a link too.
  */
-export declare function HYPERLINK(linkLocation: string, friendlyName?: string): Scalar;
+export declare function HYPERLINK(linkLocation: string, friendlyName?: Scalar): IRichData;
+/**
+ * How IMAGE sizes the picture in its cell.
+ *
+ * @remarks
+ * Declared `ReportType`: the body truncates the argument and refuses one outside 0-3.
+ */
+declare enum ImageSizing {
+    /**
+     * Fits the picture in the cell, keeping its aspect ratio.
+     * @name Fit to cell
+     */
+    Fit = 0,
+    /**
+     * Fills the cell, ignoring the picture's aspect ratio.
+     * @name Fill cell
+     */
+    Fill = 1,
+    /**
+     * Keeps the picture's own size, which may overflow the cell.
+     * @name Original size
+     */
+    Original = 2,
+    /**
+     * Uses the height and width given.
+     * @name Custom size
+     */
+    Custom = 3
+}
 /**
  * Returns an image from a given source.
- * @hidden Unimplemented RichData
  * @param source The path of the source that points to the image.
  * @param alternateText The alternative text that describes the image for accessibility.
  * @param sizing The setting that determines the dimensions in which the image will be rendered in the cell.
  * @param height The custom height of the image in pixels.
  * @param width The custom width of the image in pixels.
+ * @returns The image, once it has loaded; `#BUSY!` until then, or the image it showed when a
+ * recalculation loads it again. A source that cannot be loaded is
+ * `#VALUE!`, or `#CONNECT!` when the server answers with an error.
  */
-export declare function IMAGE(source: string, alternateText?: string, sizing?: number, height?: number, width?: number): IRichData;
+export declare function IMAGE(source: string, alternateText?: Omittable<string>, sizing?: Omittable<ReportType<ImageSizing>>, height?: Omittable<number>, width?: Omittable<number>): IRichData;
 /**
  * Returns a value or reference of the cell at the intersection of a particular row and column, in a given range.
  * @param array is a range of cells or an array constant.
@@ -156,7 +185,7 @@ export declare function LOOKUP(lookupValue: Scalar, lookupVector: Flatten<IRange
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: the body keeps the verdict. It reads the
- * argument by its SIGN; what Excel does with a value outside the set is not measured.
+ * argument by its SIGN.
  */
 declare enum MatchType {
     /**
@@ -258,7 +287,7 @@ export declare function TAKE(array: IRange, rows: Omittable<number>, columns?: O
  *
  * @remarks
  * Declared `ReportType`: Excel TRUNCATES this argument on the way in (`TOCOL(a,1.9)` reads 1 and
- * `3.9` reads 3, measured), which an enum's gate does not, so the body keeps the verdict.
+ * `3.9` reads 3), which an enum's gate does not, so the body keeps the verdict.
  */
 declare enum IgnoreValues {
     /**
@@ -347,7 +376,7 @@ export declare function WRAPROWS(vector: IRange | Scalar, wrapCount: number, pad
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: the body keeps the verdict (anything
- * else is #VALUE!). Excel's out-of-set behavior is not measured.
+ * else is #VALUE!).
  */
 declare enum MatchMode {
     /**
@@ -376,7 +405,7 @@ declare enum MatchMode {
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: the body keeps the verdict (anything
- * else is #VALUE!). Excel's out-of-set behavior is not measured.
+ * else is #VALUE!).
  */
 declare enum SearchMode {
     /**

package/types/src/mathTrig/Math.d.ts

@@ -9,8 +9,8 @@ export declare function ABS(number: number): number;
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`9.9`
- * is SUM, measured), which an enum's gate does not, so the body keeps the verdict. Also the
- * overload discriminant of DESIGN-REPEATING §6: 14-19 take a trailing `k`.
+ * is SUM), which an enum's gate does not, so the body keeps the verdict. Also the
+ * overload discriminant: 14-19 take a trailing `k`.
  */
 declare enum AggregateFunction {
     /**
@@ -114,7 +114,7 @@ declare enum AggregateFunction {
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`6.9`
- * is 6, measured), which an enum's gate does not, so the body keeps the verdict.
+ * is 6), which an enum's gate does not, so the body keeps the verdict.
  */
 declare enum AggregateOptions {
     /**
@@ -597,7 +597,7 @@ export declare function SQRTPI(number: NoLift<Omittable<AcceptError<Scalar>>>):
  *
  * @remarks
  * Declared `ReportType`, as every numeric built-in enum is: Excel TRUNCATES this argument (`9.9`
- * is SUM, measured), which an enum's gate does not, so the body keeps the verdict. Excel labels
+ * is SUM), which an enum's gate does not, so the body keeps the verdict. Excel labels
  * 101-111 with the bare function name, as 1-11; a member name keys the descriptor and the
  * language packs, so each must be unique.
  */

package/types/src/testing/Testing.d.ts

@@ -7,7 +7,7 @@ import { Scalar, IRange } from '@sheetxl/primitives';
  * @param label optional label for the delay function.
  * @category SheetXL
  */
-export declare function DELAY(time: number, input: Scalar, label?: string): Promise<Scalar>;
+export declare function DELAY(time: number, input: Scalar, label?: string): Scalar;
 declare global {
     var debugEventTarget: EventTarget | undefined;
 }
@@ -24,5 +24,5 @@ declare global {
  *   (e.g. globalThis.debugEventTarget.dispatchEvent(new CustomEvent('test', { detail: "ping" }));
  * @category SheetXL
  */
-export declare function WAIT(type: string, input?: IRange): Promise<string>;
+export declare function WAIT(type: string, input?: IRange): string;
 //# sourceMappingURL=Testing.d.ts.map

package/types/src/web/FilterXML.d.ts

@@ -4,5 +4,5 @@ import { Scalar } from '@sheetxl/primitives';
  * @param xml is a string in valid XML format.
  * @param xpath is a string in standard XPath format.
  */
-export declare function FILTERXML(xml: string, xpath: string): Promise<Scalar[][]>;
+export declare function FILTERXML(xml: string, xpath: string): Scalar[][];
 //# sourceMappingURL=FilterXML.d.ts.map

package/types/src/web/Web.d.ts

@@ -7,5 +7,5 @@ export declare function ENCODEURL(text: string): string;
  * Retrieves data from a web service.
  * @param url is the URL of the web service.
  */
-export declare function WEBSERVICE(url: string): Promise<string>;
+export declare function WEBSERVICE(url: string): string;
 //# sourceMappingURL=Web.d.ts.map