@trebco/treb 32.9.3 → 32.11.0

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v32.9. Copyright 2018-2025 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v32.11. Copyright 2018-2025 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 /*
  * This file is part of TREB.
  *

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "@trebco/treb",
-  "version": "32.9.3",
-  "license": "LGPL-3.0-or-later",
-  "homepage": "https://treb.app",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/trebco/treb.git"
-  },
-  "main": "dist/treb-spreadsheet.mjs",
-  "types": "dist/treb.d.ts",
-  "type": "module",
-  "devDependencies": {
-    "@types/html-minifier": "^4.0.2",
-    "@types/node": "^22.5.2",
-    "@types/uzip": "^0.20201231.0",
-    "base64-js": "^1.5.1",
-    "cssnano": "^7.0.4",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.9.1",
-    "fast-xml-parser": "^4.0.7",
-    "html-minifier-terser": "^7.2.0",
-    "sass": "^1.69.3",
-    "treb-base-types": "file:treb-base-types",
-    "treb-calculator": "file:treb-calculator",
-    "treb-charts": "file:treb-charts",
-    "treb-data-model": "file:treb-data-model",
-    "treb-export": "file:treb-export",
-    "treb-format": "file:treb-format",
-    "treb-grid": "file:treb-grid",
-    "treb-parser": "file:treb-parser",
-    "treb-utils": "file:treb-utils",
-    "ts-node": "^10.9.2",
-    "tslib": "^2.7.0",
-    "tsx": "^4.19.1",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "^8.3.0",
-    "uzip": "^0.20201231.0"
-  },
-  "scripts": {
-    "build": "node esbuild-composite.mjs",
-    "dev": "node esbuild-composite.mjs --dev",
-    "clean": "rm -fr build dist declaration",
-    "watch": "node --watch esbuild-composite.mjs --watch --dev",
-    "watch-production": "node --watch esbuild-composite.mjs --watch",
-    "tsc": "tsc -b treb-embed/tsconfig.json",
-    "rebuild-tsc": "tsc -b --force treb-embed/tsconfig.json",
-    "watch-tsc": "tsc -b treb-embed/tsconfig.json -w",
-    "watch-api": "tsx --watch api-generator/api-generator.ts --config api-config.json",
-    "generate-api": "tsx api-generator/api-generator.ts --config api-config.json",
-    "release": "npm run rebuild-tsc && npm run build && npm run generate-api"
-  }
-}
+{
+  "name": "@trebco/treb",
+  "version": "32.11.0",
+  "license": "LGPL-3.0-or-later",
+  "homepage": "https://treb.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/trebco/treb.git"
+  },
+  "main": "dist/treb-spreadsheet.mjs",
+  "types": "dist/treb.d.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/html-minifier": "^4.0.5",
+    "@types/node": "^24.3.1",
+    "@types/uzip": "^0.20201231.2",
+    "base64-js": "^1.5.1",
+    "cssnano": "^7.1.1",
+    "esbuild": "^0.25.9",
+    "eslint": "^9.35.0",
+    "fast-xml-parser": "^5.2.5",
+    "html-minifier-terser": "^7.2.0",
+    "sass": "^1.92.1",
+    "treb-base-types": "file:treb-base-types",
+    "treb-calculator": "file:treb-calculator",
+    "treb-charts": "file:treb-charts",
+    "treb-data-model": "file:treb-data-model",
+    "treb-export": "file:treb-export",
+    "treb-format": "file:treb-format",
+    "treb-grid": "file:treb-grid",
+    "treb-parser": "file:treb-parser",
+    "treb-utils": "file:treb-utils",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0",
+    "uzip": "^0.20201231.0"
+  },
+  "scripts": {
+    "build": "node esbuild-composite.mjs",
+    "dev": "node esbuild-composite.mjs --dev",
+    "clean": "rm -fr build dist declaration",
+    "watch": "node --watch esbuild-composite.mjs --watch --dev",
+    "watch-production": "node --watch esbuild-composite.mjs --watch",
+    "tsc": "tsc -b treb-embed/tsconfig.json",
+    "rebuild-tsc": "tsc -b --force treb-embed/tsconfig.json",
+    "watch-tsc": "tsc -b treb-embed/tsconfig.json -w",
+    "watch-api": "tsx --watch api-generator/api-generator.ts --config api-config.json",
+    "generate-api": "tsx api-generator/api-generator.ts --config api-config.json",
+    "release": "npm run rebuild-tsc && npm run build && npm run generate-api"
+  }
+}

package/treb-calculator/src/expression-calculator.ts

@@ -87,6 +87,7 @@ export interface ReferenceMetadata {
 }
 
 export type BindingFrame = Record<string, ExpressionUnit>; // FIXME (type?)
+
 export type PositionalFrame = ExpressionUnit[];
 
 export interface CalculationContext {
@@ -464,8 +465,6 @@ export class ExpressionCalculator {
       return ExpressionError();
     }
 
-    // let frame = value.bindings(expr.args);
-
     const frame: BindingFrame = {};
 
     for (let i = 0; i < value.bindings.length; i++) {
@@ -479,8 +478,6 @@ export class ExpressionCalculator {
       }
     }
 
-    // frame = this.NormalizeBindings(frame); // inline
-
     const munged = JSON.parse(JSON.stringify(value.func));
     
     this.parser.Walk2(munged, (unit: ExpressionUnit) => {
@@ -493,11 +490,6 @@ export class ExpressionCalculator {
       }
       return true;
     });
-    
-    // console.info({frame, func, munged});
-   
-    // const exec_result = this.CalculateExpression(munged as ExtendedExpressionUnit);
-    // return exec_result || ExpressionError();
 
     return this.CalculateExpression(munged as ExtendedExpressionUnit);
 
@@ -582,6 +574,7 @@ export class ExpressionCalculator {
    * the parsing stage, it's a simple translation between the two
    */
   protected ImplicitCall(): (expr: UnitImplicitCall|UnitCall) => UnionValue {
+
     return (expr: UnitImplicitCall|UnitCall) => {
 
       if (expr.type === 'call') {
@@ -634,6 +627,7 @@ export class ExpressionCalculator {
       const upper_case = outer.name.toUpperCase();
 
       const binding = this.LookupBinding(upper_case);
+
       if (binding) {
         return this.ImplicitCall();
       }

package/treb-calculator/src/functions/base-functions.ts

@@ -234,6 +234,79 @@ const TrigFunction = (real: (value: number) => number, complex: (value: Complex)
   };
 }
 
+/**
+ * helper for sorting. kind of weird rules
+ */
+const SortHelper = (order: number, av: CellValue, bv: CellValue) => {
+  
+  // OK from what I can tell the rules are
+  //
+  // (1) no type coercion (but see below for blanks)
+  // (2) strings are sorted case-insensitive
+  // (3) blank values are coerced -> 0 but these are not sorted as numbers
+  // (4) order is numbers, strings, booleans, then blanks
+  //
+  // some of which makes sense, I guess...
+  // 
+  // blanks are always sorted last, irrespective of sort order. which
+  // means we can't sort and then reverse, because reverse sort is not
+  // the inverse of forward sort
+
+  // special case
+
+  if (av === bv) {
+    return 0;
+  }
+
+  // special case
+
+  if (av === undefined) {
+    return 1;
+  }
+  if (bv === undefined) {
+    return -1;
+  }
+
+  // actual comparisons
+
+  if (typeof av === 'number' && typeof bv === 'number') {
+    return (av - bv) * order;
+  }
+
+  if (typeof av === 'string' && typeof bv === 'string') {
+    return av.toLocaleLowerCase().localeCompare(bv.toLowerCase()) * order;
+  }
+
+  if (typeof av === 'boolean' && typeof bv === 'boolean') {
+    return av ? order : -order;
+  }
+
+  if (IsComplex(av) && IsComplex(bv)) {
+    return 0; // no sort order
+  }
+
+  // type rules
+
+  const types = [av, bv].map(x => {
+    switch (typeof x) {
+      case 'number':
+        return 0;
+      case 'string': 
+        return 2; 
+      case 'boolean':
+        return 3;
+      default: 
+        if (IsComplex(x)) {
+          return 1;
+        }
+        return 4;
+    }
+  });
+
+  return (types[0] - types[1]) * order;
+
+};
+
 /**
  * alternate functions. these are used (atm) only for changing complex 
  * behavior.
@@ -1176,29 +1249,149 @@ export const BaseFunctionLibrary: FunctionMap = {
 
     },
 
+    /**
+     * sortby allows multiple sort indexes, but no column sorting
+     */
+    SortBy: {
+      arguments: [
+        { name: 'array', },
+        { name: 'index', },
+        { name: 'order', description: 'Set to -1 to sort in descending order', default: 1 }
+      ],
+      fn: (ref: CellValue|CellValue[][], ...args: (CellValue|CellValue[][])[]): UnionValue => {
+
+        if (!Array.isArray(ref)) {
+          ref = [[ref]];
+        }
+
+        // must have at least one sort order? 
+
+        if (args.length < 1) {
+          return ArgumentError();
+        }
+
+        // ensure any sort argument pairs are valid... I guess they
+        // need to be the same length? what happens if not? [A: error]
+
+        const rows = ref[0]?.length || 0;
+        const orders: number[] = [];
+        const values: CellValue[][] = [];
+
+        for (let i = 0; i < args.length; i += 2) {
+          
+          const target = i/2;
+
+          let sort_range = args[i];
+          if (!Array.isArray(sort_range)) {
+            sort_range = [[sort_range]];
+          }
+
+          const check = sort_range[0]?.length || 0;
+          if (check !== rows) {
+            return ArgumentError();
+          }
+
+          let order = 1;
+          const arg = args[i+1];
+          if (typeof arg === 'number' && arg < 0) {
+            order = -1;
+          }
+
+          orders[target] = order;
+          values[target] = sort_range[0]; // (sort_range[0]).slice(0);
+          
+        }
+
+        const mapped = ref[0]?.map((value, index) => (index));
+        mapped.sort((a, b) => {
+
+          for (let i = 0; i < orders.length; i++) {
+            const order = orders[i];
+            const value_set = values[i];
+            const result = SortHelper(order, value_set[a], value_set[b]);
+            if (result) {
+              return result;
+            }
+          }
+
+          return 0;
+
+        });
+
+        // output is same shape
+
+        const columns = ref.length;
+        const result: UnionValue[][] = [];
+
+        for (let c = 0; c < columns; c++) {
+          const column: UnionValue[] = [];
+          for (const index of mapped) {
+            column.push(Box(ref[c][index]));
+          }
+          result.push(column);
+        }
+
+        return { type: ValueType.array, value: result };
+
+
+      },
+    },
+
     /**
      * sort arguments, but ensure we return empty strings to
      * fill up the result array
      * 
      * FIXME: instead of boxing all the values, why not pass them in boxed?
      * was this function just written at the wrong time?
+     * 
+     * UPDATE: rewriting to match Excel args
+     * 
      */
     Sort: {
       arguments: [
-        { name: 'values' }
+        { name: 'array', },
+        { name: 'index', },
+        { name: 'order', description: 'Set to -1 to sort in descending order', default: 1 }
       ],
-      fn: (...args: CellValue[]): UnionValue => {
+      fn: (ref: CellValue|CellValue[][], index = 1, order = 1): UnionValue => {
 
-        args = Utils.FlattenCellValues(args);
+        if (!Array.isArray(ref)) {
+          ref = [[ref]];
+        }
+
+        // FIXME: transpose for column sort
 
-        if(args.every(test => typeof test === 'number')) {
-          (args as number[]).sort((a, b) => a - b);
+        const sort_column = ref[index - 1];
+        if (!sort_column) {
+          return ArgumentError();
+        }
+
+        // clean (and be lenient)
+
+        if (order < 0) {
+          order = -1;
         }
         else {
-          args.sort(); // lexical
+          order = 1;
+        }
+        
+        const mapped = sort_column.map((value, index) => ({value, index}));
+        mapped.sort((a, b) => SortHelper(order, a.value, b.value));
+
+        // output is same shape
+
+        const columns = ref.length;
+        const result: UnionValue[][] = [];
+
+        for (let c = 0; c < columns; c++) {
+          const column: UnionValue[] = [];
+          for (const { index } of mapped) {
+            column.push(Box(ref[c][index]));
+          }
+          result.push(column);
         }
 
-        return { type: ValueType.array, value: [args.map(value => Box(value))] };
+        return { type: ValueType.array, value: result };
 
       },
     },

package/treb-parser/src/parser.ts

@@ -636,8 +636,13 @@ export class Parser {
         // function. in that case we don't want a space in front of the 
         // operator.
 
+        // UPDATE: for aesthetic reasons, also remove spaces around a
+        // power operator (caret, "^")
+
+        // FIXME: parameterize?
+
         {
-          const separator = (unit.operator === ':' ? '': ' ');
+          const separator = ((unit.operator === ':' || unit.operator === '^') ? '': ' ');
 
           return (
             this.Render(unit.left, options) +