@trebco/treb 37.0.0 → 37.1.0

package/build/treb-calculator/src/dag/vertex.js

@@ -0,0 +1,274 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with TREB. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Copyright 2022-2026 trebco, llc.
+ * info@treb.app
+ *
+ */
+/**
+ * colors for the CLRS color algorithm.
+ *
+ * these colors are useful because gray is "in between" white and black, but
+ * (outside of the general move away from using white/black as identifiers) it
+ * might be easier to conceptualize with descriptive labels like "untested"
+ * (white), "being tested", (gray) and "testing complete" (black).
+ */
+export var Color;
+(function (Color) {
+    Color[Color["white"] = 0] = "white";
+    Color[Color["gray"] = 1] = "gray";
+    Color[Color["black"] = 2] = "black";
+})(Color || (Color = {}));
+export class Vertex {
+    /**
+     * vertex and its subclasses have a type parameter for type
+     * guards/reflection; each instance has a type that is set
+     * to the static class type.
+     */
+    static type = 'vertex';
+    // --- members ---
+    type = Vertex.type; // for type guard
+    color = Color.white; // for loop check
+    /** dependencies */
+    // public edges_in: Vertex[] = [];
+    edges_in = new Set();
+    /** dependents */
+    // public edges_out: Vertex[] = [];
+    edges_out = new Set();
+    // --- accessors ---
+    get has_inbound_edges() { return this.edges_in.size > 0; }
+    get has_outbound_edges() { return this.edges_out.size > 0; }
+    // --- cleanup operations ---
+    /** reset this node */
+    Reset() {
+        for (const edge of this.edges_out) {
+            edge.RemoveDependency(this);
+        }
+        for (const edge of this.edges_in) {
+            edge.RemoveDependent(this);
+        }
+        //this.edges_out = [];
+        this.edges_out.clear();
+        //this.edges_in = [];
+        this.edges_in.clear();
+    }
+    /** removes all inbound edges (dependencies) */
+    ClearDependencies() {
+        for (const edge of this.edges_in) {
+            edge.RemoveDependent(this);
+            // testing inline...
+            // edge.edges_out = edge.edges_out.filter(check => check !== this);      
+        }
+        // this.edges_in = [];
+        this.edges_in.clear();
+    }
+    // --- basic node operations ---
+    /** add a dependent. doesn't add if already in the list */
+    AddDependent(edge) {
+        if (edge === this)
+            return; // circular
+        if (this.edges_out.has(edge)) {
+            return;
+        }
+        /*
+        for (const check of this.edges_out) {
+          if (check === edge) {
+            return;
+          }
+        }
+        */
+        //this.edges_out.push(edge);
+        this.edges_out.add(edge);
+    }
+    /** remove a dependent */
+    RemoveDependent(edge) {
+        // this.edges_out = this.edges_out.filter((check) => check !== edge);
+        // updated for performance.
+        // this seems to be faster than any other method of removing an item.
+        // (also tried: temp loop and copy non-matching).
+        // this does assume that edges can't be in the list twice, but that
+        // should already be true (it would cause all sorts of other problems).
+        // actually does this just win because we break the loop earlier?
+        // (presumably in 50% of cases)? even if so, if the splice is not 
+        // more expensive this is a win.
+        // splice should be expensive, though... weird. because what splice
+        // does (AIUI) is reassign array indexes above the delete index.
+        // it would be better if we could get rid of indexes altogether, perhaps
+        // using a set?
+        // note: tried to improve on splice with some direct methods, nothing
+        // seemed to work any better (not worse, either, but if there's no 
+        // improvement we should use the native method).
+        /*
+        for (let i = 0; i < this.edges_out.length; i++) {
+          if (this.edges_out[i] === edge) {
+            this.edges_out.splice(i, 1);
+            return;
+          }
+        }
+        */
+        this.edges_out.delete(edge);
+    }
+    /** add a dependency. doesn't add if already in the list */
+    AddDependency(edge) {
+        if (edge === this)
+            return; // circular
+        /*
+        for (const check of this.edges_in) {
+          if (check === edge) {
+            return;
+          }
+        }
+        */
+        if (this.edges_in.has(edge)) {
+            return;
+        }
+        //this.edges_in.push(edge);
+        this.edges_in.add(edge);
+    }
+    /** remove a dependency */
+    RemoveDependency(edge) {
+        // this.edges_in = this.edges_in.filter((check) => check !== edge);
+        this.edges_in.delete(edge);
+    }
+    /**
+     * this is a composite operation, because the operations are always called
+     * in pairs. this means create a pair of links such that _edge_ depends on
+     * _this_.
+     */
+    LinkTo(edge) {
+        this.AddDependent(edge);
+        edge.AddDependency(this);
+    }
+    /**
+     * this is an alteranate formulation that may make more intuitive sense.
+     * it creates a pair of forward/backward links, such that _this_ depends
+     * on _edge_.
+     */
+    DependsOn(edge) {
+        this.AddDependency(edge);
+        edge.AddDependent(this);
+    }
+    /**
+     * this is called during calculation (if necessary). on a hit (loop), we
+     * reset the color of this, the test node, to white. there are two reasons
+     * for this:
+     *
+     * one, we want subsequent tests to also find the hit. in some cases we may
+     * not be marking the node as a loop (if it precedes the backref in the graph),
+     * so we want subsequent nodes to also hit the loop. [Q: this makes no sense,
+     * because this would still hit if the node were marked grey, assuming you
+     * test for that].
+     *
+     * two, if you fix the loop, on a subsequent call we want to force a re-check,
+     * which we can do if the vertex is marked white. [Q: could also be done on
+     * gray?]
+     *
+     * [A: logically you are correct, but this works, and matching grey does not].
+     */
+    LoopCheck() {
+        const stack = [this];
+        while (stack.length) {
+            // note peek: we leave it on the stack
+            const v = stack[stack.length - 1];
+            // state flag: unset if we have edges we need to check
+            let complete = true;
+            // skip this vertex if it's clean
+            if (v.color !== Color.black) {
+                v.color = Color.gray; // set here, not top of function
+                for (const edge of v.edges_out) {
+                    if (edge.color === Color.gray) {
+                        this.color = Color.white; // note: this, not v
+                        return true; // found a loop
+                    }
+                    // if (edge.color === Color.white && edge.edges_out.length) {
+                    if (edge.color === Color.white && edge.edges_out.size) {
+                        stack.push(edge);
+                        complete = false;
+                        // the only thing this break does is add loops. we can 
+                        // safely add all (white) edges as long as we don't color 
+                        // them here -- that was the issue in the last version.
+                        // break; // ?
+                        // if you really want fidelity with the recursive version
+                        // you could reverse the order, but the order is arbitrary
+                        // anyway so it makes no difference.
+                    }
+                }
+            }
+            if (complete) {
+                v.color = Color.black;
+                stack.pop();
+            }
+        }
+        /*
+        this.color = Color.gray;
+       
+        // switch to stack algorithm. see the method in Graph for details.
+    
+        // NOTE: this is bugged. need to rewrite. it's generating false positives
+        // where the recursive version still works.
+    
+        const stack: Vertex[] = [this];
+    
+        while (stack.length) {
+    
+          const v = stack[stack.length - 1];
+          let completed = true;
+    
+          if (v.color !== Color.black) {
+    
+            for (const edge of v.edges_out) {
+    
+              if (edge.color === Color.gray) {
+    
+                // this is different than the graph algo, here we reset the
+                // color when we hit a loop.
+    
+                this.color = Color.white; // someone else can test
+                return true; // loop
+       
+              }
+              else if (edge.color === Color.white) {
+                edge.color = Color.gray;
+                stack.push(edge);
+                completed = false;
+              }
+    
+            }
+    
+          }
+    
+          if (completed) {
+            stack.pop();
+            v.color = Color.black;
+          }
+    
+        }
+        */
+        /*
+        // the old recursive version
+    
+        for (const edge of this.edges_out) {
+          if (edge.color === Color.gray || (edge.color === Color.white && edge.LoopCheck())) {
+            this.color = Color.white; // someone else can test
+            return true; // loop
+          }
+        }
+        */
+        this.color = Color.black;
+        return false;
+    }
+}
+//# sourceMappingURL=vertex.js.map

package/build/treb-calculator/src/dag/vertex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertex.js","sourceRoot":"","sources":["../../../../treb-calculator/src/dag/vertex.ts"],"names":[],"mappings":"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"}

package/build/treb-calculator/src/descriptors.d.ts

@@ -0,0 +1,189 @@
+import type { RenderFunction, ClickFunction, UnionValue, ICellAddress, IArea, FunctionUnion } from 'treb-base-types';
+import type { ExpressionUnit } from 'treb-parser';
+/**
+ * FIXME: possible to add stuff in here if we need it
+ */
+export interface FunctionContext {
+    address: ICellAddress;
+    area?: IArea;
+    /** application function for fp functions */
+    apply?: (fn: FunctionUnion, args: UnionValue[]) => UnionValue;
+}
+/**
+ * descriptor for an individual argument
+ */
+export interface ArgumentDescriptor {
+    name?: string;
+    description?: string;
+    default?: number | string | boolean;
+    /** @internal TODO: rename */
+    passthrough?: boolean;
+    /**
+     * allows error values to propagate. otherwise, a function will
+     * return an #ARG error if any arguments contain errors. used for
+     * IsError and IfError, atm.
+     *
+     * UPDATE: also used in IF.
+     */
+    allow_error?: boolean;
+    /**
+     * this argument (reference) should be treated as an address, not resolved.
+     * it's used for identifying multivariate groups.
+     *
+     * UPDATE: this is used in reference + lookup functions (Offset, specifically)
+     * so don't move to MC lib.
+     */
+    address?: boolean;
+    /**
+     * require the argument to be a union
+     */
+    boxed?: boolean;
+    /**
+     * this argument repeasts. this has no impact on the function descriptor
+     * but it's useful to know for clients. UPDATE: going to use this for
+     * let, which repeats arguments at the front. not sure what that's going
+     * to do to clients. maybe it will just magically work!
+     */
+    repeat?: boolean;
+    /**
+     * similar to collector, this flag will return metadata about the cell
+     *
+     * supported in annotations only, not spreadsheet cells (atm)
+     *
+     * returns cell data type defined in chart (FIXME: move)
+     */
+    metadata?: boolean;
+    /**
+     * new flag for automating array application. set this flag to allow
+     * unrolling of array parameters. @see ApplyArray in `utilities.ts`.
+     *
+     * if this flag is set in any argument descriptor in a function, we'll
+     * apply arrays. that's done when the function is installed.
+     *
+     * FIXME: this should maybe be the default, and we have an !unroll flag
+     */
+    unroll?: boolean;
+}
+/**
+ * @internal
+ */
+export interface ContextResult {
+    context: Record<string, ExpressionUnit>;
+    /**
+     * rewrite args
+     */
+    args: any[];
+    /** possibly rewrite argument descriptors, not required */
+    argument_descriptors?: ArgumentDescriptor[];
+}
+export type FunctionImplementation = (this: FunctionContext | undefined, ...args: any[]) => UnionValue;
+/**
+ * merging the old function descriptor and decorated function types, since
+ * there's a good deal of overlap and we spend a lot of effort keeping them
+ * in sync.
+ *
+ * this is a wrapper object that contains the function and (mostly optional)
+ * metadata.
+ */
+export interface CompositeFunctionDescriptor {
+    /**
+     * description for the function wizard
+     */
+    description?: string;
+    /**
+     * list of arguments, for the function wizard and tooltip
+     */
+    arguments?: ArgumentDescriptor[];
+    /**
+     * volatile: value changes on every recalc, even if dependencies
+     * don't change
+     */
+    volatile?: boolean;
+    /**
+     * FIXME: we need to unify type with what's in the cell class
+     */
+    render?: RenderFunction;
+    click?: ClickFunction;
+    /**
+     * the actual function. if this is an object member and needs access
+     * to the containing instance, make sure to bind it to that instance.
+     *
+     * otherwise, `this` will be bound to a `CalculationContext` object
+     * if your function is defined as a function (i.e. not an arrow function).
+     *
+     */
+    fn: FunctionImplementation;
+    /**
+     * limited visibility
+     *
+     * internal functions do not show up in the spreadsheet. we have an
+     * annotation value which should be usef in the future but it's not
+     * implemented yet.
+     *
+     * should we allow these functions to be used, and just not tooltip them;
+     * or block them entirely? for now we'll do the former as it's helpful to
+     * defug.
+     */
+    visibility?: 'internal' | 'annotation';
+    /**
+     * for the future
+     */
+    category?: string[];
+    extension?: boolean;
+    /**
+     * there is some set of functions that need an "_xlfn." prefix on export.
+     * I'm not sure why or where the list comes from, but we want to flag
+     * those functions so we can export them properly.
+     */
+    xlfn?: boolean;
+    /**
+     * support returning references. 'value' is default. FIXME: could just be a bool?
+     */
+    return_type?: 'reference' | 'value';
+    /**
+     * @internal
+     */
+    export?: (...args: any[]) => string;
+    /**
+     * pass through UI functions, if possible. this is for lambda and let; we
+     * want to pass through sparklines, if a sparkline is the first function call
+     *
+     * @internal
+     */
+    pass_through_ui?: 'direct' | 'indirect';
+    /**
+     * flag indicating we've unrolled this function. it's possible functions
+     * will run through the registration process more than once and we don't
+     * want to have extra depth.
+     *
+     * @internal
+     */
+    unrolled?: boolean;
+    /**
+     * this is new: custom binding context for lambda functions (lambda, let,
+     * and maybe others?) still working out the semantics of this.
+     *
+     * @internal
+     */
+    create_binding_context?: (context: {
+        args: ExpressionUnit[];
+        descriptors: ArgumentDescriptor[];
+    }) => ContextResult | undefined;
+    /** flag indicating this function needs fp support */
+    fp?: boolean;
+}
+export interface FunctionMap {
+    [index: string]: CompositeFunctionDescriptor;
+}
+/**
+ * the stored value also includes a canonical name. this used to be separate
+ * from the registered name (because those were functions, and had to adhere
+ * to language rules) but now we use arbitrary tokens, so we can consolidate.
+ */
+export interface ExtendedFunctionDescriptor extends CompositeFunctionDescriptor {
+    canonical_name: string;
+}
+export interface ExtendedFunctionMap {
+    [index: string]: ExtendedFunctionDescriptor;
+}
+export type IntrinsicValue = number | string | boolean | undefined;

package/build/treb-calculator/src/descriptors.js

@@ -0,0 +1,22 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with TREB. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * Copyright 2022-2026 trebco, llc.
+ * info@treb.app
+ *
+ */
+export {};
+//# sourceMappingURL=descriptors.js.map

package/build/treb-calculator/src/descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.js","sourceRoot":"","sources":["../../../treb-calculator/src/descriptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

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

@@ -0,0 +1,127 @@
+import type { FunctionLibrary } from './function-library';
+import type { Cell, ICellAddress, UnionValue, CellValue, ArrayUnion, IArea, FunctionUnion } from 'treb-base-types';
+import { ValueType } from 'treb-base-types';
+import type { Parser, ExpressionUnit, UnitBinary, UnitIdentifier, UnitGroup, UnitUnary, UnitAddress, UnitCall, UnitDimensionedQuantity, UnitStructuredReference, UnitImplicitCall } from 'treb-parser';
+import type { DataModel, MacroFunction } from 'treb-data-model';
+import * as Primitives from './primitives';
+/**
+ * dynamically adding a user data field to the expression so we can
+ * cache a function call, avoiding type switching and function lookups.
+ *
+ * we use the generic type so we can cover the composite type as well
+ * before specifying
+ */
+type AttachCachedFunction<T> = (T & {
+    fn: (arg0: T) => UnionValue;
+});
+/**
+ * expression unit with cached function
+ */
+type ExpressionWithCachedFunction<T extends ExpressionUnit> = T extends {
+    type: T['type'];
+} ? AttachCachedFunction<T> : never;
+/**
+ * @internal
+ */
+export type ExtendedExpressionUnit = ExpressionWithCachedFunction<ExpressionUnit>;
+export declare const UnionIsExpressionUnit: (test: UnionValue) => test is {
+    type: ValueType.object;
+    value: ExpressionUnit;
+};
+export declare const UnionIsMetadata: (test: UnionValue) => test is {
+    type: ValueType.object;
+    value: ReferenceMetadata;
+};
+export interface ReferenceMetadata {
+    type: 'metadata';
+    address: UnitAddress;
+    value: CellValue;
+    format?: string;
+}
+export type BindingFrame = Record<string, ExpressionUnit>;
+export type PositionalFrame = ExpressionUnit[];
+export interface CalculationContext {
+    address: ICellAddress;
+    area?: IArea;
+    volatile: boolean;
+    /** new for lambdas */
+    bindings: BindingFrame[];
+}
+export declare class ExpressionCalculator {
+    protected readonly data_model: DataModel;
+    protected readonly library: FunctionLibrary;
+    protected readonly parser: Parser;
+    context: CalculationContext;
+    constructor(data_model: DataModel, library: FunctionLibrary, parser: Parser);
+    /**
+     * there's a case where we are calling this from within a function
+     * (which is weird, but hey) and to do that we need to preserve flags.
+     */
+    Calculate(expr: ExpressionUnit, addr: ICellAddress, area?: IArea, preserve_flags?: boolean): {
+        value: UnionValue;
+        volatile: boolean;
+    };
+    /**
+     * resolve value from cell. returns a function bound to specific cell.
+     */
+    protected CellFunction2(expr: UnitAddress): () => UnionValue;
+    /**
+     * returns range as union type. returns a single value for a single cell,
+     * or a 2d array (never a 1d array)
+     */
+    protected CellFunction4(start: ICellAddress, end: ICellAddress): UnionValue;
+    /** breaking this out to de-dupe */
+    protected GetMetadata<T>(arg: ExpressionUnit, transform: (cell_data: Cell, address: ICellAddress) => T): UnionValue;
+    protected RewriteMacro(unit: ExpressionUnit, names: Record<string, ExpressionUnit>): ExpressionUnit;
+    protected CallMacro(outer: UnitCall, macro: MacroFunction): (expr: UnitCall) => UnionValue;
+    /**
+     * split out from ImplicitCall so we can reuse
+     */
+    ImplicitCallTail(result: FunctionUnion, args: ExpressionUnit[]): UnionValue;
+    /**
+     * an FP call will need to set bindings and call an expression,
+     * possibly multiple times. this is a support function for that.
+     */
+    protected Apply(fn: FunctionUnion, args: UnionValue[]): UnionValue;
+    /**
+     * this method can take a `call` type if it looked like a call at
+     * the parsing stage, it's a simple translation between the two
+     */
+    protected ImplicitCall(): (expr: UnitImplicitCall | UnitCall) => UnionValue;
+    protected NormalizeBindings(context: BindingFrame): Record<string, ExpressionUnit>;
+    /**
+     * excute a function call
+     */
+    protected CallExpression(outer: UnitCall, return_reference?: boolean): (expr: UnitCall) => UnionValue;
+    protected ResolveStructuredReference(expr: UnitStructuredReference): () => UnionValue;
+    protected ResolveDimensionedQuantity(): (exp: UnitDimensionedQuantity) => UnionValue;
+    protected UnaryExpression(x: UnitUnary, return_reference?: boolean): (expr: UnitUnary) => UnionValue;
+    /**
+     * expands the size of an array by recycling values in columns and rows
+     *
+     * FIXME: seems like this is more a generic thing, -> utils lib
+     *
+     * @param arr 2d array
+     * @param columns target columns
+     * @param rows target rows
+     */
+    protected RecycleArray<T>(arr: T[][], columns: number, rows: number): T[][];
+    protected ElementwiseBinaryExpression(fn: Primitives.PrimitiveBinaryExpression, left: ArrayUnion, right: ArrayUnion): ArrayUnion;
+    /**
+     * convert expr to a cell address, possibly calculating the contents.
+     * returns single address only (ranges with len > 1 will fail)
+     */
+    protected AsReference(expr: ExpressionUnit): ICellAddress | undefined;
+    protected BinaryExpression(x: UnitBinary): (expr: UnitBinary) => UnionValue;
+    protected Identifier(expr: UnitIdentifier): () => UnionValue;
+    /**
+     * look up an identifier in any binding frames. we do LIFO binding.
+     *
+     * @param name
+     * @returns
+     */
+    protected LookupBinding(name: string): ExpressionUnit | undefined;
+    protected GroupExpression(x: UnitGroup): (expr: UnitGroup) => UnionValue;
+    protected CalculateExpression(expr: ExtendedExpressionUnit, return_reference?: boolean): UnionValue;
+}
+export {};