@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/named/INamed.d.ts

@@ -0,0 +1,225 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITypes } from '../type';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICellRanges } from '../cellRange';
+import { IModel } from '../model';
+/**
+ * Defined names are descriptive texts that are used to represents a cell, range of cells, formula, or constant value.
+ */
+export interface INamed<T = any> extends IModel {
+    /**
+     * A string to identify the type of named item.
+     *
+     * @remarks Immutable
+     */
+    getType(): string;
+    /**
+     * The underlying item that is being referenced.
+     *
+     * @remarks Immutable
+     *
+     * **What `T` is depends on {@link getType}, and for the common case it is text.** A defined name
+     * (`type` `'formula'`) is an `ICalculation.INamedFormula`, so this is its refers-to
+     * EXPRESSION as a string with no leading `=` — `Sheet1!$B$4`, or `0.21` for a name holding a
+     * constant. A table's is the `ITable`. It is never the *target*: the string `Sheet1!$B$4` is
+     * what the name says, not the cells it designates and not what they contain.
+     *
+     * The two questions this is mistaken for have their own calls:
+     * - **Which cells?** {@link getRanges} — the ranges, or `null` for a name holding an expression.
+     * - **What is it worth right now?** `ICalculation.IFormula.evaluate()`, which every named
+     *   formula has. Returns a `Scalar` for a value name and an `IRange` for a reference one, so
+     *   there is no parse-the-text-and-re-query hop. Note that a name written with relative
+     *   references evaluates per calling CELL, so its one anchored answer is not the answer every
+     *   dependent sees.
+     */
+    getValue(): T;
+    /**
+     * Selects the current item.
+     *
+     * @returns An async `INamed`.
+     */
+    select(options?: ITypes.SelectOptions): Promise<this>;
+    /**
+     * The comment for the defined name.
+     *
+     * @remarks
+     * If null then no comment
+     */
+    setComment(comment: string | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * {@link setComment}
+     *
+     * @returns The comment or `null` if none has been set.
+     */
+    getComment(): string | null;
+    /**
+     * Return the ranges that are associated with the named item or null if no ranges are available.
+     *
+     * @remarks
+     * * Optional — but only at this level of the hierarchy. Every defined name implements it
+     *   (`ICalculation.INamedFormula` redeclares it as required), so a caller holding one does not
+     *   need a guard. Optionality here is what lets a named thing that designates no cells exist at
+     *   all; it is not an invitation to reach for `?.()` on a name.
+     */
+    getRanges?(): ICellRanges | null;
+    /**
+     * A reference to a *part* of this item that the given coords designate exactly, or `null`.
+     *
+     * @param coords The coords to match, sheet-qualified (`scope`) and in row-first order.
+     *
+     * @remarks
+     * * Optional
+     *
+     * Backs {@link INamedCollection.getByRanges} with `includeParts`. Some named things address
+     * regions that are not themselves names: a table's column is written `Sales[Amount]`, its header
+     * row `Sales[#Headers]`. Those are structured references, not entries in the collection — there
+     * is no `INamed` to return for one, which is why this returns text rather than an item.
+     *
+     * Implemented by whatever owns the parts (a table), so the collection stays out of the business
+     * of knowing what kinds of items have insides.
+     */
+    getPartReference?(coords: readonly IRange.Coords[]): string | null;
+    /**
+     * If true then the name is not visible.
+     *
+     * @defaultValue false
+     *
+     * @remarks
+     * * Optional
+     * * This does not affect the item itself
+     */
+    setHidden?(hidden: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * {@link setHidden}
+     */
+    isHidden(): boolean;
+    /**
+     * This is the name that identifies the item.
+     *
+     * @param name The name.
+     */
+    setName(name: string, options?: ITransaction.OperationOptions): this;
+    /**
+     * {@link setName}
+     */
+    getName(): string;
+    /**
+     * A unique stable id.
+     */
+    getId(): string;
+    /**
+     * A string identifying the scope. This is normally a sheet name.
+     *
+     * @remarks
+     * If `null` then this will be treated as a global scope.
+     *
+     * **Read-only — there is deliberately no `setScope`.** Scope is half a name's identity, not a
+     * property of it: it decides the symbol the definition compiles into, so `Total` and
+     * `Sheet1!Total` are two names rather than one name in two states. Excel takes the same line —
+     * its `Name` object has no scope property, the Name Manager greys the dropdown out when editing,
+     * and assigning a prefixed string to `.Name` does not move a name (Excel re-applies the original
+     * scope, turning `One!Beta` into `One!One!Beta`).
+     *
+     * To change scope, delete the name and define it again in the new one — which is also what
+     * dependent formulas expect, since they re-resolve by name.
+     */
+    getScope(): string | null;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: INamed.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Return a JSON if this can be serialize.
+     */
+    toJSON?(): INamed.JSON | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isINamed: true;
+}
+/**
+ * {@inheritDoc INamed}
+ * @see
+ * ### **Interface**
+ *
+ * {@link INamed}
+ */
+export declare namespace INamed {
+    /**
+     * Minimal value contract for items that can be stored in an {@link INamed} wrapper.
+     *
+     * @remarks
+     * Used to constrain `T` in {@link INamed}<T> when callers need typed access to
+     * `getValue()` beyond the raw model methods (`getId`, `getName`) that `INamed`
+     * itself already exposes.
+     */
+    interface INamedValue {
+        getId(): string;
+        getName(): string;
+    }
+    /**
+     * IListener for {@link INamed} events.
+     */
+    interface Events<T = any> extends IModel.Events {
+        /**
+         * Called when the range is updated.
+         */
+        onRangesChange?(source: INamed<T>): void;
+    }
+    interface IListeners extends IListener.Callbacks<INamed, INamed.Events> {
+    }
+    interface ConstructorOptions<T> extends Omit<IModel.ConstructorOptions<INamed.JSON>, "type"> {
+        value?: T | null;
+    }
+    /**
+     * Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value.
+     */
+    interface Properties<R extends IRange.Coords = IRange.Coords> {
+        /**
+         * The name of the defined name.
+         * @remarks
+         * This is the name that is used in formulas.
+         */
+        name: string;
+        /**
+         * We track named items based on the reference.
+         *
+         * @remarks
+         * If the name is used in a formula this is what will be returned.
+         */
+        ref: R[];
+        /**
+         * The comment for the defined name.
+         */
+        comment?: string;
+        /**
+         * If true not shown in the ui.
+         *
+         * @defaultValue false
+         */
+        hidden?: boolean;
+        /**
+         * If scope this will be the sheetName.
+         */
+        scope?: string;
+        /**
+         * The type of named range item
+         */
+        type?: string;
+    }
+    interface JSON {
+        name: string;
+        comment?: string;
+        hidden?: boolean;
+        scope?: string;
+        /**
+         * This is interpreted by the named item
+         */
+        ref?: string;
+    }
+}
+//# sourceMappingURL=INamed.d.ts.map

package/types/src/named/INamedCollection.d.ts

@@ -0,0 +1,230 @@
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+import { ICellRanges } from '../cellRange';
+import { INamed } from './INamed';
+/**
+ * A collection of `INamed` items — defined names AND tables.
+ *
+ * @remarks
+ * **Which items it holds is decided by where you got it from, not by an option.** There is no scope
+ * argument anywhere on this interface:
+ *
+ * | Reached through        | Holds                                                          |
+ * | ---------------------- | -------------------------------------------------------------- |
+ * | {@link IWorkbook.getNames} | EVERY named item in the workbook, whatever its scope        |
+ * | {@link ISheet.getNames}    | only what is visible FROM that sheet — the global items (tables included) plus that sheet's own, shadowing resolved |
+ *
+ * The two exist because the two consumers genuinely differ: a name manager lists everything that
+ * exists, while a formula editor may only offer what a formula written *here* can actually refer to.
+ * Both get it from `getItems()` with no arguments, which is the point — the scope question is
+ * answered by the call you make, so it cannot be got wrong by omitting an option.
+ *
+ * **Scope is visibility, never location.** A defined name lives on no sheet and may be visible
+ * everywhere or on exactly one sheet. A table lives ON a sheet but its name is always visible
+ * everywhere and workbook-unique — so `getScope()` is `null` for every table, and tables appear in
+ * BOTH collections. That is not a special case: they are globally visible, so they turn up wherever
+ * globally visible items do. For the tables anchored to one sheet, ask `ISheet.getTables()` — that is
+ * the location question, and it has its own call.
+ *
+ * **Porting from Excel's Office Scripts.** Deliberately close but not identical. There,
+ * `Workbook.getNames()` is global-scoped names ONLY and `Worksheet.getNames()` is that sheet's own
+ * ONLY, with tables kept out of names entirely. Both of ours are supersets of their counterpart, so a
+ * direct port is over-inclusive rather than wrong — it will never see another sheet's private names.
+ * Filter on {@link INamed.getScope} (`null` = global) for exact parity.
+ */
+export interface INamedCollection extends ICollection<INamed> {
+    /**
+     * Define a name.
+     *
+     * @param name The name. Case insensitive, must be unique, and must not contain spaces.
+     * @param expression The expression to bind it to, with or without a leading `=`. A plain range
+     * address (`Sheet1!$A$1:$B$2`) is simply a reference expression.
+     * @param replaceExisting If `true`, redefine an existing name instead of throwing. *default* `false`.
+     * @throws `Error` if the name is invalid, or already exists and `replaceExisting` is not set.
+     *
+     * @remarks
+     * Created in the registry that owns defined names — the calculation engine — so it is the same
+     * kind of item as one loaded from a file, and `getType()` is `'formula'`. Use
+     * `ICalculation.INamedFormula.setExpression` to redefine it afterwards.
+     */
+    addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /**
+     * Return the named items.
+     * These are sorted by type then by name.
+     */
+    getItems(options?: INamedCollection.GetItemsOptions): INamed[];
+    /**
+     * The reference text for every name that designates *exactly* the given ranges.
+     *
+     * @param ranges The ranges to match. Unqualified coords are read as being on the current scope
+     * (the selected sheet), which is what lets a sheet's own selection be passed straight through.
+     * @param options `includeParts` additionally matches the insides of an item — see
+     * {@link INamedCollection.GetByRangesOptions.includeParts}.
+     *
+     * @returns The names, whole-item matches first, then part references. Empty when nothing matches.
+     *
+     * @remarks
+     * The inverse of resolving a name: given a region, what is it called? This is what lets a name
+     * box show `Sales` in place of `$B$2:$C$3`, and what lets a formula editor substitute the name
+     * for an address the user picked by dragging.
+     *
+     * **Exact, not containing.** A selection *inside* `Sales` is not `Sales` — the ranges must
+     * coincide. Multi-range names match irrespective of the order the ranges are given in.
+     *
+     * **Text, not items.** A part has no `INamed` to return (`Sales[Amount]` is a structured
+     * reference, not an entry in this collection), so every match comes back as the text a formula
+     * would use. Several names may share one region, hence an array; callers wanting a single answer
+     * take the first.
+     */
+    getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+    /**
+     * Lookup a named range with a given name.
+     *
+     * @param name Case insensitive name to lookup.
+     * @param global If `true` then will search all scopes. *default* `false`.
+     */
+    getByName(name: string, global?: boolean): INamed | null;
+    /**
+     * Lookup a named item by its unique stable id.
+     *
+     * @param id The id returned by {@link INamed.getId}.
+     */
+    getById(id: string): INamed | null;
+    /**
+     * Returns a new valid name given the name return a valid name that closely matches.
+     * This function works by incrementing either the last number or append a number.
+     *
+     * @param template The range to used as a template.
+     * @param scope The scope of the range. If null then this will look for a globally scoped. *default* `null`.
+     * @param ignoreExisting If true then won't check to see if the name is already used. *default* `false`.
+     * @throws `Error` If the template name is invalid.
+     * @returns A valid name. If the name used is valid then will return the same name.
+     */
+    findValidName(template: string, scope?: string, ignoreExisting?: boolean): string;
+    /**
+     * Validates a name is valid. This is a convenience method That calls `findValidName`
+     * and throws an error if the name returned is not the same.
+     *
+     * @throws `Error` If `findValidName` does not return the same value as the name checking.
+     *
+     * @see
+     * {@link INamedCollection.findValidName}
+     */
+    validateName(name: string, scope?: string, ignoreExisting?: boolean): void;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ITransaction.ITransactional.isClosed} */
+    isClosed(): boolean;
+    /** {@inheritDoc ITransaction.ITransactional.close} */
+    close(): void;
+    /**
+     * For runtime type checking.
+     */
+    readonly isINamedCollection: true;
+}
+/**
+ * {@inheritDoc INamedCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link INamedCollection}
+ */
+export declare namespace INamedCollection {
+    type JSON = INamed.JSON[];
+    interface Events {
+        /**
+         * Called when the names this collection holds, or the regions they designate, change.
+         *
+         * @remarks
+         * Not a per-item change event: editing a name's comment or hiding it does not surface here,
+         * and a consumer wanting that listens to the item.
+         *
+         * What a name *refers to* does surface, though — it is part of what the collection holds, and a
+         * consumer asking "what is this region called?" ({@link INamedCollection.getByRanges}) has
+         * nowhere else to hear about it. It cannot subscribe to an item it does not yet hold, and
+         * defining a name is two steps: it is added, and then bound to a region. Both are announced,
+         * as are a redefinition and an undo that moves one. So this can fire more than once for a
+         * single definition, and a listener that re-reads the collection is the intended response.
+         */
+        onCollectionChange?(source: INamedCollection): void;
+        /**
+         * Transaction items have a close event.
+         */
+        onClose?(source: INamedCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<INamedCollection, INamedCollection.Events> {
+    }
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * A string indicating the type.
+         */
+        type?: string;
+        /**
+         * Only items with this name, compared case-insensitively.
+         *
+         * @remarks
+         * Several items can share a name (a global and a sheet-scoped `Rate`), which is what makes
+         * this a filter rather than a lookup — {@link INamedCollection.getByName} answers the
+         * "which one wins" question; this returns every holder of the name. Mirrors
+         * `INamedFormulasCollection.getItems`.
+         */
+        name?: string;
+        /**
+         * Only items with this scope: a sheet name, or `null` for globally scoped items only.
+         *
+         * @remarks
+         * Filters on {@link INamed.getScope} — visibility, never location — and the KEY being present
+         * is what turns it on: `{ scope: null }` returns only global items, while omitting `scope`
+         * applies no filter at all. Mirrors `INamedFormulasCollection.getItems`.
+         */
+        scope?: string | null;
+        /**
+         * The search area.
+         *
+         * @defaultValue Search the global scope of the NamedCollection.
+         */
+        address?: ICellRanges.Address;
+        /**
+         * If true return any Named that is in the bounds even if only partially bounded.
+         *
+         * @defaultValue false
+         */
+        allowExtrudes?: boolean;
+        /**
+         * If 'true' then include hidden named ranges.
+         */
+        includeHidden?: boolean;
+    }
+    /**
+     * Options for {@link INamedCollection.getByRanges}.
+     *
+     * @remarks
+     * The same filters {@link GetItemsOptions} offers, minus the two that describe a *spatial* query:
+     * `address` is the method's own argument, and `allowExtrudes` loosens a match that this method
+     * defines as exact. Neither has a meaning here, so neither is accepted.
+     */
+    interface GetByRangesOptions extends Omit<GetItemsOptions, 'address' | 'allowExtrudes'> {
+        /**
+         * If `true` also match the *insides* of an item, returning a reference to the part.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * A table's column, header row, totals row and full extent are all addressable
+         * (`Sales[Amount]`, `Sales[#Headers]`, `Sales[#Totals]`, `Sales[#All]`) without being names in
+         * their own right. Off by default because the two consumers genuinely differ: a name box shows
+         * the address for a column selection, whereas a formula editor substituting a dragged range
+         * wants `Sales[Amount]`.
+         *
+         * Part references sort after whole-item matches — a real name beats a synthesized reference to
+         * the same region.
+         */
+        includeParts?: boolean;
+    }
+}
+//# sourceMappingURL=INamedCollection.d.ts.map