@sheetxl/primitives 0.8.0-beta.2 → 0.8.0-beta.20

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';

package/browser/cjs/index.cjs

@@ -1 +0,0 @@
-var e;Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`}),function(e){e.MAX_TEXT_LENGTH=32767;let t=e.MAX_SIGNIFICANT_DIGITS=15;e.truncateNumberText=function(e){let n=e.length;if(n<=t)return e;let r=0,i=null;for(let a=0;a<n;a++){let n=e.charCodeAt(a);if(n>=48&&n<=57){if(r===0&&n===48)continue;r++,r>t&&((i??=e.split(``))[a]=`0`)}else if((n===69||n===101)&&r>0)break}return i===null?e:i.join(``)}}(e||={});var t,n,r,i,a={Number:`number`,String:`string`,Boolean:`boolean`,Error:`error`,RichData:`richData`,Null:`null`},o={...a,Date:`date`},s={...a,Reference:`reference`,Array:`array`,Lambda:`lambda`,Omitted:`omitted`},c=/[.*+?^${}()|[\]\\]/,l=e=>c.test(e)?`\\`+e:e,u={isWildCard:e=>typeof e==`string`&&/[*?]/.test(e),toRegex:(e,t,n=!1)=>{let r=``,i=e.length;for(let t=0;t<i;t++){let n=e[t];if(n===`~`){let n=e[t+1];n!==`*`&&n!==`?`&&n!==`~`||(r+=l(n),t++);continue}n===`*`?r+=`[\\s\\S]*`:r+=n===`?`?`[\\s\\S]`:l(n)}return RegExp(n===`start`?`^${r}`:n?`^${r}$`:r,t)}};(n=t||={}).Axis={Column:`column`,Row:`row`},n.AxisSelection={...t.Axis,Both:`both`},n.Direction={Up:`up`,Down:`down`,Left:`left`,Right:`right`},(r||={}).Aggregate={Count:`count`,NumericalCount:`numericalCount`,Sum:`sum`,Average:`average`,StdDev:`stdDev`,PopulationStdDev:`stdDevP`,Variance:`var`,PopulationVariance:`varP`,Min:`min`,Max:`max`},function(e){let t=e.Code={Parse:0,Null:1,Div0:2,Value:3,Ref:4,Name:5,Num:6,NA:7,GettingData:8,Spill:9,Connect:10,Blocked:11,Unknown:12,Field:13,Calc:14,Busy:16,Python:19,Timeout:20},n=e.Label={Parse:`#PARSE!`,Null:`#NULL!`,Div0:`#DIV/0!`,Value:`#VALUE!`,Ref:`#REF!`,Name:`#NAME?`,Num:`#NUM!`,NA:`#N/A`,GettingData:`#GETTING_DATA`,Spill:`#SPILL!`,Connect:`#CONNECT!`,Blocked:`#BLOCKED!`,Unknown:`#UNKNOWN!`,Field:`#FIELD!`,Calc:`#CALC!`,Busy:`#BUSY!`,Python:`#PYTHON!`,Timeout:`#TIMEOUT!`};class r extends Error{constructor(e,t,n,r){super(n,r),this._label=t,this._code=e,this.details=r}static{this.code=i.Code.Unknown}get isFormulaError(){return!0}getLabel(){return this._label}getCode(){return this._code}equals(e){return!!e&&(this._code===e._code||this._code===e.code)}get[Symbol.toStringTag](){return`[FormulaError]`}toString(){return this._label}}e.Known=r;class a extends r{constructor(e,r){super(t.Parse,n.Parse,e,r)}static{this.code=i.Code.Parse}getDetails(){let e=this.details;return{line:e?.line??1,column:e?.column??1,offset:e?.offset??0,length:e?.length??0}}}e.Parse=a;class o extends r{constructor(e,r){super(t.Null,n.Null,e,r)}static{this.code=i.Code.Null}}e.Null=o;class s extends r{constructor(e,r){super(t.Div0,n.Div0,e,r)}static{this.code=i.Code.Div0}}e.Div0=s;class c extends r{constructor(e,r){super(t.Value,n.Value,e,r)}static{this.code=i.Code.Value}}e.Value=c;class l extends r{constructor(e,r){super(t.Ref,n.Ref,e,r)}static{this.code=i.Code.Ref}}e.Ref=l;class u extends r{constructor(e,r){super(t.Name,n.Name,e,r)}static{this.code=i.Code.Name}}e.Name=u;class d extends r{constructor(e,r){super(t.Num,n.Num,e,r)}static{this.code=i.Code.Num}}e.Num=d;class f extends r{constructor(e,r){super(t.NA,n.NA,e,r)}static{this.code=i.Code.NA}}e.NA=f;class p extends r{constructor(e,r){super(t.GettingData,n.GettingData,e,r)}static{this.code=i.Code.GettingData}}e.GettingData=p;class m extends r{constructor(e,r){super(t.Spill,n.Spill,e,r)}static{this.code=i.Code.Spill}}e.Spill=m;class h extends r{constructor(e,r){super(t.Connect,n.Connect,e,r)}static{this.code=i.Code.Connect}}e.Connect=h;class g extends r{constructor(e,r){super(t.Blocked,n.Blocked,e,r)}static{this.code=i.Code.Blocked}}e.Blocked=g;class _ extends r{constructor(e,r){super(t.Unknown,n.Unknown,e,r)}static{this.code=i.Code.Unknown}}e.Unknown=_;class v extends r{constructor(e,r){super(t.Field,n.Field,e,r)}static{this.code=i.Code.Field}}e.Field=v;class y extends r{constructor(e,r){super(t.Calc,n.Calc,e,r)}static{this.code=i.Code.Calc}}e.Calc=y;class b extends r{constructor(e,r){super(t.Busy,n.Busy,e,r)}static{this.code=i.Code.Busy}}e.Busy=b;class x extends r{constructor(e,r){super(t.Python,n.Python,e,r)}static{this.code=i.Code.Python}}e.Python=x;class S extends r{constructor(e,r){super(t.Timeout,n.Timeout,e,r)}static{this.code=i.Code.Timeout}}e.Timeout=S}(i||={});var d={};d[i.Code.Parse]=i.Parse,d[i.Code.Null]=i.Null,d[i.Code.Div0]=i.Div0,d[i.Code.Value]=i.Value,d[i.Code.Ref]=i.Ref,d[i.Code.Name]=i.Name,d[i.Code.Num]=i.Num,d[i.Code.NA]=i.NA,d[i.Code.GettingData]=i.GettingData,d[i.Code.Spill]=i.Spill,d[i.Code.Connect]=i.Connect,d[i.Code.Blocked]=i.Blocked,d[i.Code.Unknown]=i.Unknown,d[i.Code.Field]=i.Field,d[i.Code.Calc]=i.Calc,d[i.Code.Busy]=i.Busy,d[i.Code.Python]=i.Python,d[i.Code.Timeout]=i.Timeout;var f=new Map,p=new Map,m=new Map,h=new Map,g=Object.keys(d);for(let e=0;e<g.length;e++){let t=d[g[e]],n=new t;m.set(n.getLabel(),t),h.set(n.getCode(),t),f.set(n.getLabel(),n),p.set(n.getCode(),n)}(function(e){let t=e.getBuiltInByCode=e=>p.get(e);e.BuiltIn={Parse:t(i.Code.Parse),Null:t(i.Code.Null),Div0:t(i.Code.Div0),Value:t(i.Code.Value),Ref:t(i.Code.Ref),Name:t(i.Code.Name),Num:t(i.Code.Num),NA:t(i.Code.NA),GettingData:t(i.Code.GettingData),Spill:t(i.Code.Spill),Connect:t(i.Code.Connect),Blocked:t(i.Code.Blocked),Unknown:t(i.Code.Unknown),Field:t(i.Code.Field),Calc:t(i.Code.Calc),Busy:t(i.Code.Busy),Python:t(i.Code.Python),Timeout:t(i.Code.Timeout)},e.newTypedError=(e,t,n)=>{let r;return r=typeof e==`string`?m.get(e):h.get(e),r||=i.Unknown,new r(t,n)},e.getBuiltInByLabel=e=>f.get(e),e.isError=function(e,t){return!!e&&!0===e.isFormulaError&&(t===void 0||e.getCode()===t)}})(i||={});var _=class{createRange(e,t,n){throw new b}flattenAreas(e){throw new b}getReference(e,t){throw new b}getResizedReference(e,t,n){throw new b}getNumberFormat(e,t){throw new b}fromSerialDate(e,t){throw new b}toSerialDate(e,t){throw new b}getDateParts(e,t){throw new b}getSerialDate(e,t,n,r,i,a,o){throw new b}getNow(){throw new b}getRandom(){return Math.random()}getValueAt(e,t,n,r){return null}getEntireCoords(){return x}isValidDate(e,t){return e instanceof Date||Object.prototype.toString.call(e)===`[object Date]`?!isNaN(e.getTime()):!t&&typeof e==`number`&&!(e<0||e>C)}getRow(){return 0}getColumn(){return 0}isImplicitIntersect(){return!1}getFormulaAt(e,t,n){return null}getSpillAt(e,t,n){return null}getSheetIndex(e){return-1}getSheetCount(){return 1}markVolatile(){}formatResults(e){}filterHidden(e,t){return e}filterTotals(e){return e}getFunction(e){return null}getAddress(e,t){throw new b}parseAsSerialDate(e,t){throw new b}parseAsDate(e,t){throw new b}parseAsNumber(e,t){throw new b}createCriteria(e,t){throw new b}parseAsLiteral(e){let t=e.toUpperCase();return t===`TRUE`||t!==`FALSE`&&i.getBuiltInByLabel(t)}toText(e){return typeof e==`string`?e:e==null?``:typeof e==`boolean`?e?`TRUE`:`FALSE`:e?.isFormulaError?e.getLabel():String(e)}compare(e,t,n){if(e===t)return 0;let r=v(e),i=v(t);return r===i?e<t?-1:+(e>t):r<i?-1:1}getRuntime(){return S}getArgs(){throw new b(y)}},v=e=>{if(e==null)return 0;switch(typeof e){case`number`:return 1;case`string`:return 2;case`boolean`:return 3;default:return 4}},y=`FormulaContext.getArgs() is only valid while a function body is running`,b=class extends Error{constructor(e=`Not implemented in StubbedFormulaContext`){super(e),this.name=`NotImplementedError`}},x=Object.freeze({colStart:0,rowStart:0,colEnd:2**14-1,rowEnd:2**20-1}),S={isDate1904:()=>!1,getLocale:()=>E.tag,getLocaleProfile:()=>E,isR1C1:()=>!1,getNow:()=>0,getRandom:()=>Math.random(),getLocation:()=>`unknown`,getVersion:()=>`1.0.0`,getOS:()=>`unknown`,getUser:()=>`unidentified`,getDescription:()=>`Stubbed Formula Context`},C=2958465,w=new _,T=class{constructor(){this._scope=w,this._argsFn=null}_setScope(e){this._scope=e??w}_getScope(){return this._scope}_setArgsProvider(e){this._argsFn=e}getNumberFormat(e,t){return this._getScope().getNumberFormat(e,t)}getEntireCoords(){return this._getScope().getEntireCoords()??x}parseAsSerialDate(e,t){return this._getScope().parseAsSerialDate(e,t)}parseAsDate(e,t){return this._getScope().parseAsDate(e,t)}parseAsNumber(e,t){return this._getScope().parseAsNumber(e,t)}createCriteria(e,t){return this._getScope().createCriteria(e,t)}parseAsLiteral(e){let t=this._getScope();return t.parseAsLiteral?t.parseAsLiteral(e):w.parseAsLiteral(e)}toText(e){return this._getScope().toText(e)}isValidDate(e,t=!1){return this._getScope().isValidDate(e,t)}fromSerialDate(e,t=!1){return this._getScope().fromSerialDate(e,t)}toSerialDate(e,t=!1){return this._getScope().toSerialDate(e,t)}getDateParts(e,t){return this._getScope().getDateParts(e,t)}getSerialDate(e,t,n,r=0,i=0,a=0,o=0){return this._getScope().getSerialDate(e,t,n,r,i,a,o)}getNow(){return this._getScope().getNow()}getRandom(){return this._getScope().getRandom?.()??Math.random()}createRange(e,t,n){return this._getScope().createRange(e,t,n)}flattenAreas(e){if(!Array.isArray(e))return e;let t=[];for(let n=0;n<e.length;n++){let r=e[n],{rows:i,columns:a}=r.getShape();for(let e=0;e<i;e++)for(let n=0;n<a;n++)t.push(r.getValueAt(e,n))}return this.createRange(t.length,1,(e,n)=>t[n.rowIndex])}getRow(){return this._getScope().getRow?.()??0}getColumn(){return this._getScope().getColumn?.()??0}isImplicitIntersect(){return this._getScope().isImplicitIntersect?.()??!1}getReference(e,t){return this._getScope().getReference(e,t)}getResizedReference(e,t,n){return this._getScope().getResizedReference(e,t,n)}getValueAt(e,t,n){return this._getScope().getValueAt(e,t,n)}getFormulaAt(e,t,n){return this._getScope().getFormulaAt?.(e,t,n)??null}getSpillAt(e,t,n){return this._getScope().getSpillAt?.(e,t,n)??null}getSheetIndex(e){return this._getScope().getSheetIndex?.(e)??-1}getSheetCount(){return this._getScope().getSheetCount?.()??1}markVolatile(){this._getScope().markVolatile?.()}formatResults(e){this._getScope().formatResults?.(e)}filterHidden(e,t){return this._getScope().filterHidden?.(e,t)??e}filterTotals(e){return this._getScope().filterTotals?.(e)??e}getFunction(e){return this._getScope().getFunction?.(e)??null}getAddress(e,t){return this._getScope().getAddress(e,t)}compare(e,t,n){return this._getScope().compare?.(e,t,n)??w.compare(e,t,n)}getRuntime(){return this._getScope().getRuntime()}getArgs(){let e=this._argsFn,t=e?e():null;if(!t)throw new b(y);return t}get[Symbol.toStringTag](){return`[FormulaContext]`}toString(){return this._getScope()?.toString?.()??`{STUB SCOPE}`}},E=Object.freeze({tag:`en-US`,numberingSystem:`latn`,decimal:`.`,group:`,`,grouping:[3],minusSign:`-`,percentSign:`%`,permilleSign:`‰`,currencyCode:`USD`,currencySymbol:`$`,currencyDisplay:`symbol`,currencyPosition:`before`,currencySpacing:`tight`,date:Object.freeze({calendar:`gregory`,short:`M/d/yy`,medium:`MMM d, y`,long:`MMMM d, y`,timeShort:`h:mm a`,timeLong:`h:mm:ss a`,am:`AM`,pm:`PM`,firstDay:0,weekend:[6,0],monthsWide:[`January`,`February`,`March`,`April`,`May`,`June`,`July`,`August`,`September`,`October`,`November`,`December`],monthsAbbr:[`Jan`,`Feb`,`Mar`,`Apr`,`May`,`Jun`,`Jul`,`Aug`,`Sep`,`Oct`,`Nov`,`Dec`],weekdaysWide:[`Sunday`,`Monday`,`Tuesday`,`Wednesday`,`Thursday`,`Friday`,`Saturday`],weekdaysAbbr:[`Sun`,`Mon`,`Tue`,`Wed`,`Thu`,`Fri`,`Sat`],hour12:!0}),listSeparator:`,`,csvDelimiter:`,`,rtl:!1,collator:Object.freeze({sensitivity:`base`,numeric:!0})}),D=new T;exports.DEFAULT_LOCALE_PROFILE=E,exports.FormulaContext=D,Object.defineProperty(exports,"FormulaError",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"IRange",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"IRangeStats",{enumerable:!0,get:function(){return r}}),exports.InteropScalarType=o,exports.Observable=class{constructor(e){this._subscribeFn=e}subscribe(e,t,n){let r=typeof e==`object`?{next:e.next||(()=>{}),error:e.error||(()=>{}),complete:e.complete||(()=>{}),unsubscribe:()=>{}}:{next:e||(()=>{}),error:t||(()=>{}),complete:n||(()=>{}),unsubscribe:()=>{}},i=this._subscribeFn(r);return r.unsubscribe=()=>{typeof i==`function`&&i()},r}},Object.defineProperty(exports,"Scalar",{enumerable:!0,get:function(){return e}}),exports.ScalarType=a,exports.ScopedFormulaContext=T,exports.StubbedFormulaContext=_,exports.ValueKind=s,exports.WildCard=u,exports.isLazyValue=e=>typeof e==`object`&&!!e&&!0===e.isLazy;