@sheetxl/primitives 0.8.0-beta.11 → 0.8.0-beta.13

package/types/src/IRichData.d.ts

@@ -1,17 +1,24 @@
 import { Scalar } from './Scalar';
+import { IRichMeta, IRichType } from './IRichType';
 /**
  * A complex object type. This allows for more complex data types to be stored in a cell.
  */
 export interface IRichData {
     /**
-     * Reference to either a known typename or a JSON Type Definition.
-     * * {@link https://jsontypedef.com/}
+     * The value's kind: the properties it has and how they show. Every value of a kind returns the
+     * same instance.
      */
-    getType(): string;
+    getKind(): IRichType;
     /**
      * @param name The name of the property to retrieve.
      */
     getProperty(name: string): Scalar;
+    /**
+     * How the property `name` shows on this value: the value's own presentation where it differs
+     * from its kind's (a price in another currency), else the kind's ({@link IRichType.Property.meta}).
+     * `null`, or the method absent, for none.
+     */
+    getPropertyMeta?(name: string): IRichMeta | null;
     /**
      * The text shown for this value where nothing renders it: a client with no renderer for the
      * kind, a log, a placeholder. A rich text shows its text; an image a short description.
@@ -23,32 +30,48 @@ export interface IRichData {
     toString(): string;
     /**
      * The primitive this value reads as wherever one is consumed: `LEN`, `&`, `+`, comparison,
-     * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an image reads as
-     * nothing (`null`, or the method absent), and is `#VALUE!` wherever a primitive is needed.
+     * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an error that carries
+     * more than its code reads as that error; an image reads as nothing (`null`, or the method
+     * absent), and is `#VALUE!` wherever a primitive is needed.
      *
      * @remarks
-     * The ordinary rules then apply to the primitive (text-to-number coercion, collation), so a
-     * value adds no coercions of its own.
+     * The ordinary rules then apply to the primitive (text-to-number coercion, collation, error
+     * propagation), so a value adds no coercions of its own.
      */
-    toPrimitive?(): number | string | boolean | null;
+    toPrimitive?(): Exclude<Scalar, IRichData>;
     /**
      * The items this value unpacks to where a range or array is accepted (a list); `null`, or the
      * method absent, for a value that is one value.
      */
     toArray?(): Scalar[][] | null;
     /**
-     * Indicates this is an IRichData type.
+     * The value as JSON, which its kind makes it again from. A value that holds a resource (a
+     * picture's bytes) names it by the id `toResourceId` answers, and the file saves the resource;
+     * without `toResourceId` it names none.
      */
-    toJSON?(): IRichData.JSON | Promise<IRichData.JSON>;
+    toJSON?(toResourceId?: IRichData.ToResourceId): IRichData.JSON | Promise<IRichData.JSON>;
     /**
      * For runtime type checking.
      */
     get isIRichData(): true;
 }
 export declare namespace IRichData {
+    /**
+     * The id a file being saved gives a resource a value holds (an `IResource`); `null` when the
+     * file does not save it.
+     */
+    type ToResourceId = (resource: any) => number | null;
     interface JSON {
+        /** The name of the value's kind ({@link IRichType.getName}). */
         type: string;
+        /** The value's own data, as its kind reads it. */
         data?: any;
+        /**
+         * Presentation for the properties where this value differs from its kind, by property name.
+         */
+        meta?: {
+            readonly [property: string]: IRichMeta;
+        };
     }
 }
 //# sourceMappingURL=IRichData.d.ts.map

package/types/src/IRichType.d.ts

@@ -0,0 +1,139 @@
+import { Scalar } from './Scalar';
+/**
+ * The kind of a rich value: its class. A kind is a static set of typed property definitions, and
+ * every value of a kind shares the one `IRichType` its {@link IRichData.getKind} returns.
+ *
+ * @remarks
+ * For introspection: a renderer, a card, a formula editor offering `A1.` completions, or a
+ * function reading a field asks the value's kind which properties it has. What a value reads as
+ * where a primitive is consumed is the value's own answer ({@link IRichData.toPrimitive}).
+ */
+export interface IRichType {
+    /**
+     * The kind's name: what a value's JSON names as its `type`.
+     */
+    getName(): string;
+    /**
+     * The name a UI shows for the kind, such as in a list of what can be inserted. The name when the
+     * kind has no label of its own.
+     */
+    getLabel(): string;
+    /**
+     * The kind's properties, in the order the kind declares them.
+     */
+    getProperties(): readonly IRichType.Property[];
+    /**
+     * The property `name`, or `null` when the kind has none by that name.
+     */
+    getProperty(name: string): IRichType.Property | null;
+    /**
+     * The property whose value is the text a cell shows for a value of this kind, or `null` when
+     * the kind shows none (an image).
+     */
+    getDisplayProperty(): string | null;
+    /**
+     * The kind's own presentation (a card, an icon, a provider), or `null` for none.
+     */
+    getMeta(): IRichMeta | null;
+}
+export declare namespace IRichType {
+    /**
+     * What a property holds.
+     *
+     * @remarks
+     * `rich` is another rich value (a capital city, an image); `array` is an array value; `resource`
+     * is a workbook resource such as a picture's bytes.
+     */
+    type ValueType = 'number' | 'integer' | 'string' | 'boolean' | 'error' | 'rich' | 'array' | 'resource';
+    /**
+     * One property a kind declares.
+     */
+    interface Property {
+        /** The property's name. */
+        readonly name: string;
+        /** What it holds. */
+        readonly valueType: ValueType;
+        /** What it reads as on a value that holds none. Omitted, `null`. */
+        readonly defaultValue?: Scalar;
+        /** How the property shows, unless a value says otherwise. */
+        readonly meta?: IRichMeta;
+    }
+    /**
+     * A kind saved with the workbook whose values name it: one that is not registered in code, such
+     * as a kind read from a file.
+     */
+    interface JSON {
+        /** {@inheritDoc IRichType.getName} */
+        name: string;
+        /** {@inheritDoc IRichType.getLabel} */
+        label?: string;
+        /** {@inheritDoc IRichType.getProperties} */
+        properties?: readonly Property[];
+        /** {@inheritDoc IRichType.getDisplayProperty} */
+        displayProperty?: string | null;
+        /** {@inheritDoc IRichType.getMeta} */
+        meta?: IRichMeta;
+    }
+}
+/**
+ * How a rich value, or one of its properties, is presented: the number format and caption of a
+ * property, where it is offered, its sources; a kind's card, icon and provider.
+ *
+ * @remarks
+ * Presentation only, never a value. A kind gives each of its properties a default; a value gives
+ * one only for a property where it differs (a price in another currency).
+ */
+export interface IRichMeta {
+    /** The number format a number property shows in. */
+    readonly numberFormat?: string;
+    /** A short caption shown beside the property, such as its unit or the year of its data. */
+    readonly sublabel?: string;
+    /** Where the property is not offered. Each omitted entry is `false`. */
+    readonly excludeFrom?: IRichMeta.ExcludeFrom;
+    /** Where the property's data comes from and under what license. */
+    readonly attribution?: readonly IRichMeta.Attribution[];
+    /** A kind's card. */
+    readonly card?: IRichMeta.Card;
+    /** A kind's icon, by name. */
+    readonly icon?: string;
+    /** Who provides a kind's data. */
+    readonly provider?: IRichMeta.Provider;
+}
+export declare namespace IRichMeta {
+    /** Where a property is not offered. */
+    interface ExcludeFrom {
+        /** Not shown on the card. */
+        readonly cardView?: boolean;
+        /** Not offered after `A1.` in a formula. */
+        readonly dotNotation?: boolean;
+        /** Not offered by formula autocomplete. */
+        readonly autoComplete?: boolean;
+        /** A change to the property is not a change to the value. */
+        readonly calcCompare?: boolean;
+    }
+    /** One source of a property's data. */
+    interface Attribution {
+        readonly sourceText?: string;
+        readonly sourceAddress?: string;
+        readonly licenseText?: string;
+        readonly licenseAddress?: string;
+    }
+    /** A kind's card: which properties it shows, and how. */
+    interface Card {
+        /** The properties shown, in order. Omitted, the kind's order. */
+        readonly order?: readonly string[];
+        /** The property shown as the title. */
+        readonly title?: string;
+        /** The property shown under the title. */
+        readonly subTitle?: string;
+        /** The image property shown at the top. */
+        readonly mainImage?: string;
+    }
+    /** Who provides a kind's data. */
+    interface Provider {
+        readonly description?: string;
+        readonly logoSourceAddress?: string;
+        readonly logoTargetAddress?: string;
+    }
+}
+//# sourceMappingURL=IRichType.d.ts.map

package/types/src/Repeating.d.ts

@@ -46,12 +46,12 @@
  * omitted when there is a single repetition. `SORTBY`'s legal arities are 2 and 1+2n and nothing
  * else — `SORTBY(array, by1)` is legal, `SORTBY(array, by1, o1, by2)` is not. It is not a general
  * "the final element of the final group may be omitted" rule; that rule would accept a formula
- * Excel refuses. An optional slot anywhere else in the group is a compiler error.
+ * that must be refused. An optional slot anywhere else in the group is a compiler error.
  *
  * ### The maximum, `Max`
  *
- * The second type argument is the largest number of arguments the WHOLE CALL accepts, which is
- * how Excel states it: one number per NAME, compared against the call's total argument count and
+ * The second type argument is the largest number of arguments the WHOLE CALL accepts: one
+ * number per NAME, compared against the call's total argument count and
  * refused at entry (`Excess_function_arguments`), never a count of this parameter's own share.
  * `SWITCH`'s 254 therefore covers its `expression` and its trailing `default` as well as the
  * pairs, and `CHOOSEROWS`' covers its `array`.

package/types/src/ReportType.d.ts

@@ -27,8 +27,8 @@
  * what can arrive and {@link IFunctionArguments.getAreaCountAt} answers the union question the
  * kind cannot — a plain reference is one area, a union is more.
  *
- * Its use is meant to stay countable: a slot earns it with a rule Excel actually shows, never
- * with a guess.
+ * Its use is meant to stay countable: a slot earns it with a concrete behavior that needs it,
+ * never speculatively.
  *
  * @example
  * ```ts

package/types/src/Scalar.d.ts

@@ -31,8 +31,8 @@ export declare namespace Scalar {
      */
     const MAX_SIGNIFICANT_DIGITS = 15;
     /**
-     * Applies Excel's entry rule to numeric text: every significand digit past the
-     * 15th becomes `0`, so the text parses to the double Excel would store.
+     * Applies the 15-digit entry rule to numeric text: every significand digit past the
+     * 15th becomes `0`, so the text parses to the double a cell stores.
      *
      * @param text Numeric text in any accepted form — signed, grouped, percent,
      * currency-affixed, or scientific. The scan is locale-blind: only digit
@@ -46,6 +46,57 @@ export declare namespace Scalar {
      * truncation, not rounding: `1234567890.123456789` stores `…345`, never `…346`.
      */
     function truncateNumberText(text: string): string;
+    /**
+     * The smallest magnitude a stored number can have: the smallest normal double. A smaller one is
+     * stored as `0`.
+     */
+    const MIN_NUMBER = 2.2250738585072014e-308;
+    /**
+     * Applies the stored-number floor to a number entering a workbook — typed, parsed from text, written
+     * through the API or loaded from a file: a magnitude below {@link MIN_NUMBER} becomes `0`.
+     */
+    function flushSubnormal(value: number): number;
+    /**
+     * Whether numeric text is inside the range accepted as a number, judged from the text as
+     * written rather than the double it parses to.
+     *
+     * @param text Numeric text in any accepted form, as {@link truncateNumberText} takes it. Only
+     * digits, `decimal` and an exponent marker are read.
+     * @param decimal The decimal separator `text` is written with.
+     * @returns `false` when the leading significant digit sits outside `1E-309` … `1E+307`
+     * (`1E-310`, `0.00001E-305`, `1E+308`); for a zero mantissa, when its scale — exponent less
+     * fraction digits — is outside ±308 (`0E-309`, `0.0E-308` and `0E+309`, but not `0E-308`,
+     * `000E-308` or `0.0E+309`). Text out of range is not a number: a formula literal will not
+     * commit, `VALUE` is `#VALUE!` and typed entry stays text.
+     */
+    function isNumberTextInRange(text: string, decimal?: string): boolean;
+    /**
+     * Encodings of `ScalarType` for persistence.
+     */
+    type JSONType = 'n' | 's' | 'b' | 'e' | 'r' | 'z';
+    /**
+     * A value encoded as a number with an associated type.
+     */
+    interface JSONTypedValue {
+        t: JSONType;
+        /**
+         * The number, string id, error code or boolean flag; for `'r'`, the rich data's own JSON
+         * (`IRichData.JSON`), which its registered kind reads back.
+         */
+        v: number | IRichData.JSON;
+    }
+    /**
+     * JSON values whose type is implied by their JavaScript type.
+     *
+     * @remarks
+     * What a string means is up to the container: a worksheet stores the id of the string in its
+     * strings collection, while an external link cache stores the string itself.
+     */
+    type JSONUnTypedValue = number | boolean | string;
+    /**
+     * For persisting a single scalar value and its type.
+     */
+    type JSON = JSONUnTypedValue | JSONTypedValue;
 }
 /**
  * Represents a cell value in JavaScript, including `Date` for convenience.

package/types/src/ValueKind.d.ts

@@ -4,7 +4,7 @@
  *
  * @remarks
  * A value's kind and its extent are different axes: `{10}`, `A1` and a bare `10` all reach a
- * range-typed parameter as a 1x1 container, yet Excel separates them:
+ * range-typed parameter as a 1x1 container, yet they are distinct:
  * `VLOOKUP(10,10,1,TRUE)` is `#N/A` while `VLOOKUP(10,{10},1,TRUE)` is 10, and `TYPE` answers
  * 1 vs 64. The kind is what the CALLER supplied; the extent is merely its size.
  *
@@ -13,7 +13,7 @@
  * argument can be: a reference, a non-reference array, a callable, and no argument at all. As an
  * argument kind, {@link ScalarType.Null} means a BLANK value.
  *
- * The names and values are ours. The numeric codes Excel's `TYPE` function answers are a
+ * The names and values are ours. The numeric codes the `TYPE` function answers are a
  * PROJECTION of this kind (see `TYPE`'s implementation), not the kind itself.
  *
  * @see {@link IFunctionArguments.getKindAt}

package/types/src/WildCard.d.ts

@@ -11,7 +11,7 @@ export declare const WildCard: {
      * Compiles Excel wildcard text into a regex.
      *
      * @param anchor Where the pattern has to line up: `true` for the WHOLE string, `'start'` for a
-     * PREFIX, `false` for anywhere in it. Excel matches a whole cell, so every lookup and criteria
+     * PREFIX, `false` for anywhere in it. A criterion matches a whole cell, so every lookup and criteria
      * caller anchors; `SEARCH`, which looks for a substring, does not; and a `D` function's criteria
      * table is the prefix form — `DSUM` with the criterion `appl` takes the row whose value is
      * `Apple`, where `COUNTIF` with the same criterion takes none.

package/types/src/index.d.ts

@@ -15,6 +15,7 @@ export * from './Volatile';
 export * from './IRange';
 export * from './IReferenceRange';
 export * from './IRichData';
+export * from './IRichType';
 export * from './IFunction';
 export * from './IFormulaContext';
 export * from './IFunctionArguments';