@borgar/fx 4.3.1 → 4.5.0

package/lib/translate.js

@@ -34,18 +34,19 @@ const settings = {
  * @param {string} anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
  * @param {Object} [options={}] The options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @param {boolean} [options.allowTernary=true]  Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
  * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
  */
-export function translateToR1C1 (fx, anchorCell, { xlsx = false } = {}) {
+export function translateToR1C1 (fx, anchorCell, { xlsx = false, allowTernary = true } = {}) {
   const { top, left } = fromA1(anchorCell);
   const isString = typeof fx === 'string';
 
   const tokens = isString
-    ? tokenize(fx, { ...settings, xlsx })
+    ? tokenize(fx, { ...settings, xlsx, allowTernary })
     : fx;
 
   let offsetSkew = 0;
-  const refOpts = { xlsx, allowTernary: true };
+  const refOpts = { xlsx, allowTernary };
   tokens.forEach(token => {
     if (isRange(token)) {
       const tokenValue = token.value;
@@ -108,6 +109,7 @@ function toFixed (val, abs, base, max, wrapEdges = true) {
 const defaultOptions = {
   wrapEdges: true,
   mergeRefs: true,
+  allowTernary: true,
   xlsx: false
 };
 
@@ -148,6 +150,7 @@ const defaultOptions = {
  * @param {boolean} [options.wrapEdges=true]  Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors
  * @param {boolean} [options.mergeRefs=true]   Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
+ * @param {boolean} [options.allowTernary=true]  Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
  * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
  */
 export function translateToA1 (formula, anchorCell, options = defaultOptions) {
@@ -160,13 +163,13 @@ export function translateToA1 (formula, anchorCell, options = defaultOptions) {
       withLocation: false,
       mergeRefs: opts.mergeRefs,
       xlsx: opts.xlsx,
-      allowTernary: true,
+      allowTernary: opts.allowTernary,
       r1c1: true
     })
     : formula;
 
   let offsetSkew = 0;
-  const refOpts = { xlsx: opts.xlsx, allowTernary: true };
+  const refOpts = { xlsx: opts.xlsx, allowTernary: opts.allowTernary };
   tokens.forEach(token => {
     if (isRange(token)) {
       const tokenValue = token.value;

package/lib/translate.spec.js

@@ -0,0 +1,21 @@
+import { test, Test } from 'tape';
+import { translateToR1C1, translateToA1 } from './translate.js';
+
+Test.prototype.okayRoundTrip = function roundTrip (expr, anchor, options) {
+  const rc = translateToR1C1(expr, anchor, options);
+  const a1 = translateToA1(rc, anchor, options);
+  this.is(a1, expr, 'Round trip: ' + expr);
+};
+
+test('translate absolute cells from A1 to RC', t => {
+  t.okayRoundTrip('=Sheet1!$1:$1048576', 'A1');
+  t.okayRoundTrip('=D$1:$BJ$1048576', 'A1');
+  t.okayRoundTrip('=VLOOKUP(C7,Röðun,4,0)', 'A1');
+  t.okayRoundTrip('=COUNTIF(B$1442:B$1048576,$G1442)', 'A1');
+  t.okayRoundTrip('=IF(p2m<=D5,10,0)*scene_spend', 'A1');
+  t.okayRoundTrip('=(kwh_used_daily*kwhbtu*co2btu)/1000000', 'A1');
+  t.okayRoundTrip('=NOPLATT1+g1_+ROIC1+WACC+G1+g1_+G130+ROIC2+WACC+g2_+WACC+N', 'A1');
+  // FIXME: translate needs to be be able to specify allowTernary=false
+  t.okayRoundTrip('=foo:C3:D4', 'A1', { allowTernary: false });
+  t.end();
+});

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@borgar/fx",
-  "version": "4.3.1",
+  "version": "4.5.0",
   "description": "Utilities for working with Excel formulas",
   "main": "dist/fx.js",
+  "types": "dist/fx.d.ts",
   "module": "lib/index.js",
   "exports": {
     ".": {
@@ -15,7 +16,8 @@
     "version": "npm run build",
     "lint": "eslint lib/*.js",
     "test": "tape lib/*.spec.js | tap-min",
-    "build:docs": "echo '# _Fx_ API\n'>docs/API.md; jsdoc -c .jsdoc/config.json -d console lib>>docs/API.md",
+    "build:types": "jsdoc -c tsd.json lib>dist/fx.d.ts",
+    "build:docs": "echo '# _Fx_ API\n'>docs/API.md; jsdoc -t node_modules/@borgar/jsdoc-tsmd -d console lib>>docs/API.md",
     "build": "NODE_ENV=production rollup -c"
   },
   "repository": {
@@ -39,17 +41,19 @@
   "author": "Borgar Þorsteinsson <borgar@borgar.net> (http://borgar.net/)",
   "license": "MIT",
   "devDependencies": {
-    "@babel/core": "~7.21.0",
-    "@babel/eslint-parser": "~7.19.1",
-    "@babel/preset-env": "~7.20.2",
-    "@borgar/eslint-config": "~3.0.0",
+    "@babel/core": "~7.23.0",
+    "@babel/eslint-parser": "~7.22.15",
+    "@babel/preset-env": "~7.22.20",
+    "@borgar/eslint-config": "~3.1.0",
+    "@borgar/jsdoc-tsmd": "~0.1.0",
     "@rollup/plugin-babel": "~6.0.3",
     "babel-eslint": "~10.1.0",
-    "eslint": "~8.34.0",
+    "eslint": "~8.50.0",
     "jsdoc": "~4.0.2",
-    "rollup": "~3.17.2",
+    "rollup": "~3.29.4",
     "rollup-plugin-minification": "~0.2.0",
-    "tap-min": "~2.0.0",
-    "tape": "~5.6.3"
+    "tap-min": "~3.0.0",
+    "typescript": "~5.2.2",
+    "tape": "~5.7.0"
   }
 }

package/tsd.json

@@ -0,0 +1,12 @@
+{
+  "source": {
+    "includePattern": ".+\\.js(doc|x)?$",
+    "excludePattern": "((^|\\/|\\\\)_|spec\\.js$)"
+  },
+  "opts": {
+    "template": "node_modules/@borgar/jsdoc-tsmd",
+    "destination": "console",
+    "output": "typescript",
+    "validate": true
+  }
+}

package/.jsdoc/config.json

@@ -1,17 +0,0 @@
-{
-  "source": {
-    "includePattern": ".+\\.js(doc|x)?$",
-    "excludePattern": "((^|\\/|\\\\)_|spec\\.js$)"
-  },
-  "opts": {
-    "template": "./.jsdoc",
-    "encoding": "utf8",
-    "destination": "./docs/"
-  },
-  "templates": {
-    "default": {
-      "includeDate": false,
-      "outputSourceFiles": false
-    }
-  }
-}

package/.jsdoc/publish.js

@@ -1,217 +0,0 @@
-/* eslint-disable no-undefined, no-console */
-
-function formatType (d, inTable = false) {
-  return d.names?.map(n => `\`${n}\``).join(inTable ? ' \\| ' : ' | ') || '';
-}
-
-function formatArguments (args, showDefaults = true) {
-  let inOpt = false;
-  let r = args.reduce((a, d, i) => {
-    if (d.name.includes('.')) {
-      return a;
-    }
-    if (inOpt && !d.optional) {
-      a += ']_';
-      inOpt = false;
-    }
-    if (i) {
-      a += ', ';
-    }
-    if (!inOpt && d.optional) {
-      a += '_[';
-      inOpt = true;
-    }
-    a += d.name;
-    if (showDefaults && d.defaultvalue) {
-      a += ' = `' + d.defaultvalue + '`';
-    }
-    return a;
-  }, '');
-  if (inOpt) {
-    r += ']_';
-  }
-  return r;
-}
-
-function repValue (v) {
-  if (v === undefined) {
-    return '';
-  }
-  if (v === "''") {
-    // FIXME: should transform all '' strings to "" style
-    v = '""';
-  }
-  return '`' + v + '`';
-}
-
-function repArgName (name, optional = false) {
-  const names = name.split('.');
-  const nPath = names.length > 1 ? '.' + names.slice(1).join('.') : '';
-  return (optional ? '_[' : '') + names[0] + (optional ? ']_' : '') + nPath;
-}
-
-function listToTable (args) {
-  const useDefaults = args.some(d => !!d.defaultvalue);
-  const table = useDefaults
-    ? [
-      '| Name | Type | Default | Description |',
-      '| ---- | ---- | ------- | ----------- |' ]
-    : [
-      '| Name | Type | Description |',
-      '| ---- | ---- | ----------- |' ];
-  args.forEach(d => {
-    const row = [ repArgName(d.name, d.optional) ];
-    row.push(formatType(d.type, true));
-    useDefaults && row.push(repValue(d.defaultvalue));
-    row.push(transformLinks(d.description));
-    table.push('| ' + row.join(' | ') + ' |');
-  });
-
-  return table.join('\n');
-}
-
-function adjustLineBreaks (md) {
-  return md.trim().replace(
-    /(?:```([^\0]*?)```|(\S)\n(?!\n))/g,
-    (a, b, c) => {
-      return (c ? (c + ' ') : a);
-    }
-  );
-}
-
-function formatSee (see) {
-  if (see) {
-    if (/^[a-z][a-z0-9]*$/i.test(see)) {
-      see = `{@link ${see}}`;
-    }
-    return `\n**See also:** ${transformLinks(see)}.\n`;
-  }
-  return '';
-}
-
-const re_links = /(?:\[([^\]]+)\])?\{@link(?:code|plain)? ([^} ]+)([^}]+)?\}/g;
-function transformLinks (md) {
-  return md.replace(re_links, (a, preLabel, href, postLabel) => {
-    const hash = /^[a-z][a-z0-9]*$/i.test(href) ? '#' : '';
-    return `[${preLabel || postLabel || href}](${hash}${href})`;
-  });
-}
-
-function formatHeading (text, level = 2) {
-  return '#'.repeat(level || 1) + ' ' + text;
-}
-
-function formatIndexLink (name, text) {
-  return `[${text.replace(/([[\]])/g, '\\$1')}](#${name})`;
-}
-
-const formatIndex = {
-  function: d => {
-    return '- ' + formatIndexLink(d.name,
-      `${d.name}( ${formatArguments(d.params, false)} )`
-    );
-  },
-  constant: d => {
-    return '- ' + formatIndexLink(d.name,
-      `${d.name}`
-    );
-  }
-}
-
-const format = {
-  function: d => {
-    return [
-      formatHeading(`<a name="${d.name}" href="#${d.name}">#</a> ${d.name}( ${formatArguments(d.params)} ) ⇒ ${formatType(d.returns[0].type)}`, 3),
-      adjustLineBreaks(transformLinks(d.description)),
-      formatSee(d.see),
-      formatHeading('Parameters', 4),
-      listToTable(d.params),
-      formatHeading('Returns', 4),
-      formatType(d.returns[0].type) + ' – ' + d.returns[0].description
-    ];
-  },
-  constant: d => {
-    return [
-      formatHeading(`<a name="${d.name}" href="#${d.name}">#</a> ${d.name} ⇒ ${formatType(d.type)}`, 3),
-      adjustLineBreaks(transformLinks(d.description)),
-      formatSee(d.see),
-      formatHeading('Properties', 4),
-      listToTable(d.properties)
-    ];
-  }
-};
-
-const categoryHeadings = {
-  package: null,
-  function: 'Functions',
-  constant: 'Constants'
-};
-
-exports.publish = (data, { destination }) => {
-  data({ undocumented: true }).remove();
-  const docs = data().get();
-
-  const test = '';
-  if (test) {
-    const s = docs.find(d => d.name === test);
-    const o = format[s.kind](s);
-    console.log(o.join('\n\n'));
-    return;
-  }
-
-  const categories = {};
-  docs.forEach(d => {
-    if (!categories[d.kind]) {
-      categories[d.kind] = [];
-    }
-    categories[d.kind].push(d);
-  });
-
-  let output = [];
-  const index = [];
-
-  Object.keys(categories)
-    .sort()
-    .forEach(kind => {
-      const heading = categoryHeadings[kind];
-      if (heading == null) { return; }
-      // emit category heading
-      if (index.length) { index.push(''); }
-      index.push('**' + heading + '**', '');
-      output.push(formatHeading(heading, 2));
-      // emit all members belonging to that category
-      docs
-        .filter(d => d.kind === kind)
-        .filter(d => d.access !== 'private')
-        .sort((a, b) => {
-          if (a.name < b.name) { return -1; }
-          if (a.name > b.name) { return 1; }
-          return NaN;
-        })
-        .forEach((d, i) => {
-          if (i) {
-            output.push('---');
-          }
-          if (!format[d.kind]) {
-            console.error('Unsupported member type ' + d.kind);
-            process.exit(1);
-          }
-          index.push(formatIndex[d.kind](d));
-          output.push(...format[d.kind](d));
-        });
-    });
-
-  if (destination === 'console') {
-    const outText = (
-      index.map(d => d.trim()).join('\n') +
-      '\n\n' +
-      output.map(d => d.trim()).filter(Boolean).join('\n\n') +
-      '\n'
-    );
-    console.log(outText);
-  }
-  else {
-    console.error('This template only supports output to the console. Use the option "-d console" when you run JSDoc.');
-    process.exit(1);
-  }
-};