/** * @file * * Mock of Obsidian's `ListValue`, the Bases value wrapping a list of values. */ import type { ListValue as ListValueOriginal } from 'obsidian'; import type { RenderContext } from './RenderContext.cjs'; import { NotNullValue } from './NotNullValue.cjs'; import { StringValue } from './StringValue.cjs'; import { Value } from './Value.cjs'; /** * Mock of Obsidian's `ListValue`: a non-null value wrapping an array whose elements are `Value`s or raw data, not * necessarily of one type. A raw element is converted to a `Value` the first time {@link ListValue.get} reads it. */ export declare class ListValue extends NotNullValue { /** * The value type's identifier, `'List'` - Obsidian's own name for this class of value. */ static type: string; /** * The list's elements, each a `Value` or raw data not yet converted. The array passed to the constructor, not a * copy. */ data: (unknown | Value)[]; /** * The lucide icon name standing for this value's type. */ icon: string; /** * Creates a list value. * * @param value - The list's elements, stored as {@link ListValue.data}. */ constructor(value: (unknown | Value)[]); /** * Mock-only factory: creates a list value, spyable via `vi.spyOn(ListValue, 'create__')`. * * @param value - The list's elements. * @returns The new list value. */ static create__(value: (unknown | Value)[]): ListValue; /** * Mock-only: views a value typed as Obsidian's `ListValue` as this mock. * * @param value - The value typed as the original `ListValue`. * @returns The same object, typed as the mock. */ static fromOriginalType3__(value: ListValueOriginal): ListValue; /** * Mock-only: views this mock as Obsidian's `ListValue` type. * * @returns The same object, typed as the original `ListValue`. */ asOriginalType3__(): ListValueOriginal; /** * Compares this list with another element by element. * * @param other - The list to compare with. * @param comparator - Decides whether two elements count as equal. * @returns `true` when the two lists share one array; `false` when their lengths differ; otherwise whether * every pair of elements is either the same raw element or accepted by `comparator`, which is handed the * two elements read through {@link ListValue.get}. */ compare(other: ListValue, comparator: (a: Value, b: Value) => boolean): boolean; /** * Joins this list with another. * * @param other - The list whose elements come second. * @returns A new list holding this list's elements followed by `other`'s. */ concat(other: ListValue): ListValue; /** * Mock-only construction hook, called at the end of the constructor; a no-op meant for * `vi.spyOn(ListValue.prototype, 'constructor3__')`. * * @param _value - The contents the list was created with. */ constructor3__(_value: (unknown | Value)[]): void; /** * Finds the earliest of the list's dates. * * @returns A `DateValue` over the earliest date {@link ListValue.getDates} finds, with its time, or * `NullValue.value` when the list holds no date. The returned value wraps that very `Date` rather than a * copy, as Obsidian's does. */ earliest(): Value; /** * Compares this list with another for equality. * * @param other - The list to compare with. * @returns Whether {@link ListValue.compare} holds under `Value.equals`. Unlike the inherited comparison, * this is element-wise rather than over the two lists' string forms, so a one-element list never equals a * longer one that happens to print the same. */ equals(other: this): boolean; /** * Flattens nested lists into this one. * * @returns A new list holding this list's elements with every nested `ListValue` and every nested raw array * replaced, recursively, by its own elements. The elements are moved as they are, raw or converted. */ flatten(): ListValue; /** * Gets the element at an index. * * @param index - The zero-based index. * @returns `NullValue.value` when the index is out of range or the element is `null` or `undefined`. A `Value` * element as it is. Any other element converted by {@link ListValue.lazyEvaluator}, which replaces it in * {@link ListValue.data}. */ get(index: number): Value; /** * Extracts the dates the list's elements stand for. * * It reads the RAW elements and never goes through {@link ListValue.get}, so nothing is converted or * cached by asking, and only three shapes count: a raw string and a `StringValue` are each parsed with * `DateValue.parseFromString`, and a `DateValue` is taken as it is. Everything else — a `NumberValue` * holding a timestamp, a raw `Date`, a nested list — is skipped. * * @returns The dates found, in the list's own order. Each is the `DateValue`'s own `Date`, not a copy. */ getDates(): Date[]; /** * Extracts the numbers among the list's elements. * * It reads the RAW elements and never goes through {@link ListValue.get}, so nothing is converted or * cached by asking, and only two shapes count: a raw number other than `NaN`, and a `NumberValue`. A * numeric string is NOT one of them. * * @returns The numbers found, in the list's own order. */ getNumbers(): number[]; /** * Tells whether the list contains a value. * * @param value - The value to look for. * @returns Whether `Value.looseEquals` holds between `value` and any element. */ includes(value: Value): boolean; /** * Tells whether the value counts as true in a Bases formula. * * @returns Whether the list has at least one element. */ isTruthy(): boolean; /** * Joins the elements' text. * * @param separator - The text between two elements. * @returns A string value of the joined elements. A raw string, boolean or number is written with `String`; any * other element is read through {@link ListValue.get} and written with its `toString`. */ join(separator: string): StringValue; /** * Lists the property keys {@link ListValue.objectAccess} answers for. * * @returns The inherited keys followed by `length`. */ keys(): string[]; /** * Finds the latest of the list's dates. * * @returns A `DateValue` over the latest date {@link ListValue.getDates} finds, with its time, or * `NullValue.value` when the list holds no date. The returned value wraps that very `Date` rather than a * copy, as Obsidian's does. */ latest(): Value; /** * Converts a raw element to a `Value`, as Obsidian's default evaluator does. * * @param _index - The element's index. * @param raw - The raw element. * @returns `NullValue.value` for `null`, `undefined` or a function; a `StringValue`, `NumberValue` (`NaN` * excluded) or `BooleanValue` for a primitive; a `ListValue` over a copy of an array; a `DateValue` over a copy of * a `Date`; and an `ObjectValue` over a shallow copy of any other object. * @throws {Error} For any other raw value, such as a `symbol`, a `bigint` or `NaN`. */ lazyEvaluator(_index: number, raw: unknown): Value; /** * Gets the number of elements in the list. * * @returns The element count. */ length(): number; /** * Loosely compares this list with any value. * * @param other - The value to compare with. * @returns For another list, whether {@link ListValue.compare} holds under `Value.looseEquals`. For * anything else, whether this list holds exactly one element that loosely equals it — so `[1]` loosely * equals `1` while `[1, 2]` equals nothing but a list. */ looseEquals(other: Value): boolean; /** * Finds the largest of the list's numbers. * * @returns A `NumberValue` over the largest number {@link ListValue.getNumbers} finds, or * `NullValue.value` when the list holds none. */ max(): Value; /** * Averages the list's numbers. * * @returns A `NumberValue` over the sum of the numbers {@link ListValue.getNumbers} finds divided by * {@link ListValue.length} — the WHOLE list's length, not the count of numbers, which is Obsidian's own * arithmetic and means a list mixing numbers with anything else averages low. `NullValue.value` when the * list holds no number. */ mean(): Value; /** * Finds the middle of the list's numbers. * * @returns A `NumberValue` over the median of the numbers {@link ListValue.getNumbers} finds — the mean of * the middle two when there is an even count of them — or `NullValue.value` when the list holds none. */ median(): Value; /** * Finds the smallest of the list's numbers. * * @returns A `NumberValue` over the smallest number {@link ListValue.getNumbers} finds, or * `NullValue.value` when the list holds none. */ min(): Value; /** * Reads a named sub-property of this value. * * @param key - The property key, matched without regard to case. * @returns The element count as a `NumberValue` for `length`, and otherwise whatever the base answers. */ objectAccess(key: string): null | Value; /** * Renders the list into an element, as Obsidian does: a `.value-list-container` div holding one * `.value-list-element` span per item, with a `.value-list-gap` span carrying a newline between each pair. * * Each element is rendered by the item's OWN `renderTo`, with the same context, so a list of links renders * links and a nested list nests another container. Items are read through {@link ListValue.get}, which is * what evaluates a raw element into a `Value` first - so a list built from raw data renders the same way * one built from values does. * * @param el - The element to render into. * @param context - The rendering context, passed on to each element. */ renderTo(el: HTMLElement, context: RenderContext): void; /** * Reverses the list. * * @returns A new list over a copy of this list's elements in the opposite order. This list is untouched. */ reverse(): ListValue; /** * Takes a run of the list's elements. * * @param start - The index to start at; the list's start when omitted, counted from the end when negative. * @param end - The index to stop before; the list's end when omitted, counted from the end when negative. * @returns A new list over those elements, moved as they are, raw or converted. */ slice(start?: number, end?: number): ListValue; /** * Sorts the list. * * @returns A new list over a copy of this list's elements in ascending order. Each element is sorted by its * wrapped primitive when it is a `PrimitiveValue`, by its string form when it is any other `Value`, and by * itself when it is raw; two numbers compare numerically and anything else through Obsidian's collator, * which ignores case and accents and orders embedded digits numerically. This list is untouched. */ sort(): ListValue; /** * Measures how far the list's numbers spread around their mean. * * @returns A `NumberValue` over the POPULATION standard deviation of the numbers * {@link ListValue.getNumbers} finds — divided by their count, not by one less — or `NullValue.value` when * the list holds none. */ stddev(): Value; /** * Adds up the list's numbers. * * @returns A `NumberValue` over the sum of the numbers {@link ListValue.getNumbers} finds, or * `NullValue.value` when the list holds none. */ sum(): Value; /** * Renders the list as a string. * * @returns The elements joined with `, `, as {@link ListValue.join} writes them. */ toString(): string; /** * Drops the list's duplicates. * * @returns A new list over the CONVERTED elements, every one of them a `Value`, keeping the first of each * run that `Value.equals` accepts. Obsidian buckets them by string form in a plain object and then reads * the buckets back in key order, so elements whose string form is an integer come FIRST, in numeric order, * ahead of everything else in its original order — a quirk this mirrors rather than corrects. */ unique(): ListValue; }