@sheetxl/formulas 0.8.0-beta.11 → 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.11",
+  "version": "0.8.0-beta.12",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
     "formulas"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.11",
-    "@sheetxl/scripting": "^0.8.0-beta.11",
+    "@sheetxl/primitives": "^0.8.0-beta.12",
+    "@sheetxl/scripting": "^0.8.0-beta.12",
     "bahttext": "^2.4.0",
     "bessel": "^1.0.2"
   }

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/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/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: AcceptError<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.

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