@borgar/fx 4.13.0 → 5.0.0

package/lib/types.ts

@@ -0,0 +1,179 @@
+/**
+ * A formula language token.
+ */
+export type Token = Record<string, unknown> & {
+  /** The type of the token */
+  type: string;
+  /** The value of the token */
+  value: string;
+  /** Signifies an unterminated string token */
+  unterminated?: boolean;
+  /** Source position offsets to the token */
+  loc?: number[];
+};
+
+/**
+ * A token with extra meta data.
+ */
+export type TokenEnhanced = Token & {
+  /** A zero based position in a token list */
+  index: number;
+  /** The ID of a group which this token belongs (e.g. matching parens) */
+  groupId?: string;
+  /** This token's level of nesting inside parentheses */
+  depth?: number;
+  /** Token is of unknown type or a paren without a match */
+  error?: boolean;
+};
+
+/**
+ * A range in R1C1 style coordinates.
+ */
+export type RangeR1C1 = {
+  /** Top row of the range */
+  r0?: number | null;
+  /** Bottom row of the range */
+  r1?: number | null;
+  /** Left column of the range */
+  c0?: number | null;
+  /** Right column of the range */
+  c1?: number | null;
+  /** Signifies that r0 is an absolute value */
+  $r0?: boolean | null;
+  /** Signifies that r1 is an absolute value */
+  $r1?: boolean | null;
+  /** Signifies that c0 is an absolute value */
+  $c0?: boolean | null;
+  /** Signifies that c1 is an absolute value */
+  $c1?: boolean | null;
+  /** Should empty rows and columns at the top/left or bottom/right be discarded when range is read? */
+  trim?: 'head' | 'tail' | 'both' | null;
+};
+
+/**
+ * A range in A1 style coordinates.
+ */
+export type RangeA1 = {
+  /** Top row of the range */
+  top: number | null;
+  /** Left column of the range */
+  left: number | null;
+  /** Bottom row of the range */
+  bottom?: number | null;
+  /** Right column of the range */
+  right?: number | null;
+  /** Signifies that top is a "locked" value */
+  $top?: boolean | null;
+  /** Signifies that bottom is a "locked" value */
+  $bottom?: boolean | null;
+  /** Signifies that left is a "locked" value */
+  $left?: boolean | null;
+  /** Signifies that right is a "locked" value */
+  $right?: boolean | null;
+  /** Should empty rows and columns at the top/left or bottom/right be discarded when range is read? */
+  trim?: 'head' | 'tail' | 'both' | null;
+};
+
+/**
+ * A reference containing an A1 style range. See [Prefixes.md](Prefixes.md) for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceA1 = {
+  /** A collection of scopes for the reference */
+  context?: string[];
+  /** The reference's range */
+  range: RangeA1;
+};
+
+/**
+ * A reference containing an A1 style range. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceA1Xlsx = {
+  /** A context workbook scope */
+  workbookName?: string;
+  /** A context sheet scope */
+  sheetName?: string;
+  /** The reference's range */
+  range: RangeA1;
+};
+
+/**
+ * A reference containing a name. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceName = {
+  /** A collection of scopes for the reference */
+  context?: string[];
+  /** The reference's name */
+  name: string;
+};
+
+/**
+ * A reference containing a name. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceNameXlsx = {
+  /** A context workbook scope */
+  workbookName?: string;
+  /** A context sheet scope */
+  sheetName?: string;
+  /** The reference's name */
+  name: string;
+};
+
+/**
+ * A reference containing a R1C1 style range. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceR1C1 = {
+  /** A collection of scopes for the reference */
+  context?: string[];
+  /** The reference's range */
+  range: RangeR1C1;
+};
+
+/**
+ * A reference containing a R1C1 style range. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceR1C1Xlsx = {
+  /** A context workbook scope */
+  workbookName?: string;
+  /** A context sheet scope */
+  sheetName?: string;
+  /** The reference's range */
+  range: RangeR1C1;
+};
+
+/**
+ * A reference containing a table slice definition. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceStruct = {
+  /** A collection of scopes for the reference */
+  context?: string[];
+  /** The sections this reference targets */
+  sections?: string[];
+  /** The sections this reference targets */
+  columns?: string[];
+  /** The table this reference targets */
+  table?: string;
+};
+
+/**
+ * A reference containing a table slice definition. See [Prefixes.md] for
+ * documentation on how scopes work in Fx.
+ */
+export type ReferenceStructXlsx = {
+  /** A context workbook scope */
+  workbookName?: string;
+  /** A context sheet scope */
+  sheetName?: string;
+  /** The sections this reference targets */
+  sections?: string[];
+  /** The sections this reference targets */
+  columns?: string[];
+  /** The table this reference targets */
+  table?: string;
+};

package/lib/xlsx/index.spec.ts

@@ -0,0 +1,27 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as ctxEntry from '../index.ts';
+import * as xlsxEntry from './index.ts';
+
+// What happens when B2:A1 -> should work!
+describe('xlsx interface', () => {
+  describe('should be the same as default one', () => {
+    const keys = new Set([ ...Object.keys(ctxEntry), ...Object.keys(xlsxEntry) ]);
+    for (const key of keys) {
+      it(key, () => {
+        // addTokenMeta is only exposed on the xlsx side
+        if (key === 'addTokenMeta') {
+          expect(typeof ctxEntry[key]).toBe('undefined');
+          expect(typeof xlsxEntry[key]).toBe('function');
+        }
+        else {
+          expectTypeOf(ctxEntry[key]).toEqualTypeOf(xlsxEntry[key]);
+        }
+      });
+    }
+  });
+
+  it('addTokenMeta exists', () => {
+    expect(typeof xlsxEntry.addTokenMeta === 'function').toBeTruthy();
+  });
+});
+

package/lib/xlsx/index.ts

@@ -0,0 +1,32 @@
+/**
+ * A tokenizer, parser, and other utilities to work with Excel formula code.
+ *
+ * The xslx entry-point methods expect and return the variant of references that uses properties.
+ * If you are not using xlsx files you should use the {@link fx} variant methods.
+ *
+ * See [Prefixes.md](./Prefixes.md) for documentation on how scopes work in Fx.
+ *
+ * @packageDocumentation
+ * @module fx/xlsx
+ */
+
+export * from '../index.ts';
+
+// only exported here, not in the parent module (because it assumes xlsx tokens)
+export { addTokenMeta } from '../addTokenMeta.ts';
+
+export {
+  fixTokenRangesXlsx as fixTokenRanges,
+  fixFormulaRangesXlsx as fixFormulaRanges
+} from '../fixRanges.ts';
+
+export { parseA1RefXlsx as parseA1Ref } from '../parseA1Ref.ts';
+export { parseR1C1RefXlsx as parseR1C1Ref } from '../parseR1C1Ref.ts';
+export { parseStructRefXlsx as parseStructRef } from '../parseStructRef.ts';
+
+export { stringifyA1RefXlsx as stringifyA1Ref } from '../stringifyA1Ref.ts';
+export { stringifyR1C1RefXlsx as stringifyR1C1Ref } from '../stringifyR1C1Ref.ts';
+export { stringifyStructRefXlsx as stringifyStructRef } from '../stringifyStructRef.ts';
+
+export { tokenizeXlsx as tokenize } from '../tokenize.ts';
+

package/package.json

@@ -1,27 +1,46 @@
 {
   "name": "@borgar/fx",
-  "version": "4.13.0",
+  "version": "5.0.0",
   "description": "Utilities for working with Excel formulas",
-  "main": "dist/fx.js",
-  "types": "dist/fx.d.ts",
-  "module": "lib/index.js",
+  "type": "module",
   "exports": {
     ".": {
-      "require": "./dist/fx.js",
-      "types": "./dist/fx.d.ts",
-      "default": "./lib/index.js"
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.js"
+    },
+    "./xlsx": {
+      "require": "./dist/xlsx/index.cjs",
+      "types": "./dist/xlsx/index.d.cts",
+      "default": "./dist/xlsx/index.js"
     }
   },
+  "module": "./dist/index.js",
+  "typings": "./dist/index.d.cts",
   "scripts": {
-    "preversion": "npm test && npm run lint",
-    "version": "npm run build",
-    "lint": "eslint lib/*.js",
-    "benchmark": "node benchmark/benchmark.js",
-    "test": "tape lib/*.spec.js | tap-min",
-    "build:all": "npm run build:types && npm run build:docs && npm run build",
-    "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"
+    "benchmark": "node --experimental-strip-types benchmark/benchmark.ts",
+    "lint": "eslint lib/*.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run test && npm run lint && npm run typecheck",
+    "build": "tsup",
+    "build:all": "npm run docs && npm run build",
+    "docs": "typedoc && concat-md tempdocs > docs/API.md && rm -rf tempdocs",
+    "release": "git diff --exit-code && tsup && npm publish && V=$(jq -r .version package.json) && git tag -a $V -m $V && git push origin $V && gh release create $V --generate-notes"
+  },
+  "tsup": {
+    "entry": [
+      "lib/index.ts",
+      "lib/xlsx/index.ts"
+    ],
+    "format": [
+      "esm",
+      "cjs"
+    ],
+    "splitting": false,
+    "sourcemap": true,
+    "clean": true,
+    "dts": true
   },
   "repository": {
     "type": "git",
@@ -44,21 +63,16 @@
   "author": "Borgar Þorsteinsson <borgar@borgar.net> (http://borgar.net/)",
   "license": "MIT",
   "devDependencies": {
-    "@babel/core": "~7.28.5",
-    "@babel/eslint-parser": "~7.28.5",
-    "@babel/preset-env": "~7.28.5",
-    "@borgar/eslint-config": "~3.1.0",
-    "@borgar/jsdoc-tsmd": "~0.2.2",
-    "@rollup/plugin-babel": "~6.1.0",
-    "@rollup/plugin-terser": "~0.4.4",
-    "babel-eslint": "~10.1.0",
+    "@borgar/eslint-config": "~4.0.1",
+    "concat-md": "~0.5.1",
     "benchmark": "~2.1.4",
-    "eslint": "~8.56.0",
-    "eslint-plugin-jsdoc": "~48.1.0",
-    "jsdoc": "~4.0.5",
-    "rollup": "~4.52.5",
-    "tap-min": "~3.0.0",
-    "tape": "~5.9.0",
-    "typescript": "~5.9.3"
+    "eslint": "~9.39.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "~8.46.2",
+    "vitest": "~4.0.6",
+    "globals": "~16.5.0",
+    "typedoc": "~0.28.14",
+    "typedoc-plugin-markdown": "~4.9.0",
+    "tsup": "~8.5.0"
   }
 }

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+	"include": [
+		"lib/**/*",
+		"eslint.config.mjs",
+	],
+	"compilerOptions": {
+		"jsx": "react",
+		"declaration": true,
+		"rootDir": ".",
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"allowSyntheticDefaultImports": true,
+		"allowImportingTsExtensions": true,
+		"forceConsistentCasingInFileNames": true,
+		"verbatimModuleSyntax": true,
+		"erasableSyntaxOnly": true,
+		"allowJs": true,
+		"checkJs": true,
+		"stripInternal": true,
+		"noEmit": true,
+		"noEmitOnError": true,
+		"noErrorTruncation": true,
+		"outDir": "types",
+		"declarationMap": false,
+		"skipLibCheck": true
+	}
+}

package/typedoc-ignore-links.ts

@@ -0,0 +1,17 @@
+import { Application } from 'typedoc';
+
+// This monkey patches typedocs logger to stop listing errors
+// when it can't find markdown files in relative links.
+//
+// I wish there was a better way to do this, but there currently
+// does not seem to be. :-(
+
+const reRelErr = /relative path (\.\/)?\w+\.md is not a file/;
+export function load (app: Application) {
+  const log = app.logger.log;
+  app.logger.log = function (msg, level) {
+    if (!reRelErr.test(msg)) {
+      log.call(app.logger, msg, level);
+    }
+  }
+}

package/typedoc.json

@@ -0,0 +1,41 @@
+{
+  "plugin": [
+    "typedoc-plugin-markdown",
+    "./typedoc-ignore-links.ts"
+  ],
+  "out": "./tempdocs",
+  "entryPoints": [
+    "lib/index.ts",
+    "lib/xlsx/index.ts"
+  ],
+  "cleanOutputDir": true,
+  "readme": "none",
+  "headings": {
+    "readme": false,
+    "document": false
+  },
+  "hidePageHeader": true,
+  "hideBreadcrumbs": true,
+  "hideGenerator": true,
+  "useCodeBlocks": true,
+  "expandObjects": true,
+  "expandParameters": true,
+  "propertiesFormat": "table",
+  "parametersFormat": "table",
+  "interfacePropertiesFormat": "table",
+  "typeAliasPropertiesFormat": "table",
+  "propertyMembersFormat": "table",
+  "typeDeclarationFormat": "table",
+  "disableSources": true,
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "pageTitleTemplates": {
+    "member": "{name}"
+  },
+  "validation": {
+    "invalidLink": false,
+    "notExported": true,
+    "notDocumented": true,
+  }
+}

package/.eslintrc

@@ -1,22 +0,0 @@
-{
-  "parser": "@babel/eslint-parser",
-  "extends": [ "@borgar/eslint-config", "@borgar/eslint-config/jsdoc" ],
-  "env": {
-    "es6": true,
-    "node": true,
-  },
-  "parserOptions": {
-    "ecmaVersion": 2021,
-    "sourceType": "module",
-    "requireConfigFile": false,
-  },
-  "rules": {
-    "no-trailing-spaces": [ "error", {
-      "ignoreComments": true
-    } ],
-    "jsdoc/no-undefined-types": "off"
-  },
-  "globals": {
-    "Promise"
-  }
-}

package/benchmark/benchmark.js

@@ -1,48 +0,0 @@
-/* eslint-disable no-console */
-import { readFileSync } from 'node:fs';
-import benchmark from 'benchmark';
-import { tokenize as tokenizeCurr } from '../lib/lexer.js';
-import { parse as parseCurr } from '../lib/parser.js';
-import { tokenize as tokenizePrev, parse as parsePrev } from '../dist/fx.js';
-
-const formulas = JSON.parse(readFileSync('benchmark/formulas.json', 'utf8'));
-
-function runSuite (title, current, previous) {
-  return new Promise(resolve => {
-    console.log('Running benchmark for ' + title);
-    // @ts-ignore
-    (new benchmark.Benchmark.Suite())
-      .add('lib/' + title, () => {
-        for (const expr of formulas) {
-          try {
-            current(expr);
-          }
-          catch (err) {
-            // gulp
-          }
-        }
-      })
-      .add('dist/' + title, () => {
-        for (const expr of formulas) {
-          try {
-            previous(expr);
-          }
-          catch (err) {
-            // gulp
-          }
-        }
-      })
-      .on('cycle', event => {
-        console.log(' ', String(event.target));
-      })
-      .on('complete', function () {
-        // console.log('  🥇', this.filter('fastest').map('name')[0]);
-        console.log('');
-        resolve(true);
-      })
-      .run({ async: true });
-  });
-}
-
-await runSuite('tokenizer', tokenizeCurr, tokenizePrev);
-await runSuite('parser', parseCurr, parsePrev);