@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

package/types/src/calculation/NamedFormulaCollection.d.ts

@@ -0,0 +1,671 @@
+import { IRange, Scalar, IFormulaContext } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { _NamedGraphNode } from '../cellRange/_GraphNode';
+import { INamed } from '../named';
+import { ITypes } from '../type';
+import { IContextContainer } from './state';
+import { Formula, IFormulaBlock } from './formula';
+import { ICalculation } from './ICalculation';
+import { INamedFormulasCollection } from './INamedFormulasCollection';
+interface State {
+    /**
+     * Keyed by {@link NamedFormula.getId} — the item's own stable id, which nothing can change.
+     *
+     * @remarks
+     * Deliberately NOT keyed by (name, scope), the pair that forms a name's identity. Both halves of
+     * that pair MOVE: a rename changes one, and a sheet rename changes what the other resolves to
+     * without any setter running here at all — so the map silently held entries under keys their
+     * items no longer answered to, and a sheet rename orphaned every name private to it.
+     *
+     * Nothing is lost by not indexing on it: `getByName`, `getById` and `getItems` all scanned
+     * already, because scope shadowing is a decision over the whole set rather than a key lookup.
+     */
+    itemsById: Map<string, NamedFormula>;
+}
+/**
+ * Implementation for {@link INamedFormulasCollection}.
+ */
+export declare class NamedFormulaCollection implements INamedFormulasCollection {
+    protected _emitter: ListenerEmitter<this, INamedFormulasCollection.IListeners>;
+    private _transactions;
+    private _stateId;
+    private _transactionsRemoveListener;
+    private _closed;
+    protected _container: IContextContainer | null;
+    protected _context: IFormulaContext | null;
+    protected _ready: (() => Promise<ICalculation.Status>) | null;
+    protected _getActiveCell: () => IRange.CellCoords | null;
+    protected _createVirtualGrid: ((gridId: string) => void) | null;
+    protected _getRange: ((address: ICellRange.Address) => ICellRange) | undefined;
+    protected _getRanges: ((address: ICellRanges.Address) => ICellRanges) | undefined;
+    protected _createGraphRanges: ((cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null) | undefined;
+    protected _resolveSheetScope: ((stableId: string) => string | null) | null;
+    protected _isReadOnly: (() => boolean) | null;
+    protected _getOrBindProxyFakeId: ((name: string, scope: string | null) => string | null) | null;
+    protected _queuePendingAction: ((action: () => Promise<void>) => void) | null;
+    protected _isEngineReady: (() => boolean) | null;
+    /**
+     * A name has been bound to its ranges since the last notification — see {@link _markWired}.
+     */
+    private _wiringDirty;
+    /** Nesting depth of {@link _beginWiringBatch}; the flush happens on the way out of the last one. */
+    private _wiringBatchDepth;
+    constructor(options?: NamedFormulaCollection.ConstructorOptions);
+    /**
+     * Hydrates from `IWorkbook.JSON.names`. A malformed entry is warned and skipped rather than
+     * failing the whole load — one bad name must not cost the workbook every other name.
+     *
+     * @remarks
+     * Called by the engine AFTER it has registered the named-formula symbol provider, not from this
+     * constructor. `add()` binds each name a symbol id up front (that id is the virtual grid it
+     * compiles into), and with no provider registered yet it binds nothing — the name would load,
+     * be listed, and still evaluate to `#NAME?`.
+     *
+     * Not on `INamedFormulasCollection`: hydration belongs to whoever constructs the engine.
+     */
+    hydrate(json: INamed.JSON[] | undefined, formulaTransform?: ICalculation.FormulaTransform): void;
+    /**
+     * Serializes to `IWorkbook.JSON.names` form, sorted by scope+name so output is stable across
+     * saves.
+     *
+     * @returns `null` when empty, matching the other collections (the key is then omitted).
+     *
+     * @remarks
+     * Sorted by what each item SAYS rather than by the map's key, which is now the item's id — a
+     * uuid, so keying the sort on it would reshuffle `names` on every save and make a diff of two
+     * saves of the same workbook meaningless.
+     *
+     * `ref` is taken from the wired block, which is sheet-qualified: `_doWireCore` runs
+     * `reanchorReferences(scopeGridId)`, resolving any bare reference against the anchor sheet —
+     * matching Excel, where typing `=A1` into a name's RefersTo comes back as `=Sheet1!A1`.
+     *
+     * That qualified form is what must be persisted. The raw input may be bare, and a bare reference
+     * cannot be represented in `<definedName>` (a single static string, with no caller to anchor
+     * against), so serializing it would lose the sheet. An unwired item falls back to its raw
+     * expression — it has nothing better to offer.
+     */
+    toJSON(): INamed.JSON[] | null;
+    /** {@inheritDoc INamedFormulasCollection.add} */
+    add(options: INamedFormulasCollection.AddOptions): ICalculation.INamedFormula;
+    /**
+     * A name has just been bound to the region it designates.
+     *
+     * @internal
+     *
+     * @remarks
+     * Defining a name is two steps, and only the first is synchronous. `add()` records it — it lists,
+     * it has a name — and queues the compile that binds it to a region onto the engine's pending
+     * drain. Between the two `getRanges()` is null, so a consumer that heard only the `add` sees a
+     * name referring to nothing: the name box showed an address for a name the managed-names pane was
+     * already listing, because listing needs `getName()` and nothing more.
+     *
+     * So the second step is announced as well, through the same event — what a name refers to is part
+     * of what this collection holds, not an incidental detail of one item. The same applies when a
+     * name is redefined or an undo moves it, both of which recompile through the same path.
+     *
+     * Batched by {@link _beginWiringBatch}, because loading a workbook wires every name in one drain
+     * and a listener that re-reads the collection would otherwise do it once per name.
+     */
+    protected _markWired(): void;
+    /**
+     * The graph node for a name id, or `null` — the sheet layer's door for minting name nodes into
+     * a CELL's graph answers.
+     *
+     * @internal
+     *
+     * @remarks
+     * `live` applies the phase-5 liveness rule (TODO-RENDER-DEPENDENCIES.md): a name is reported as
+     * a cell's DEPENDENT only when it has a dependent of its own — `_xlnm.Print_Area` reads every
+     * cell in the area and nothing reads it, so it is dead by construction and minting it would put
+     * a phantom on every cell it covers. No prefix special-casing: `=SUM(_xlnm.Print_Area)` makes
+     * it genuinely live and it SHOULD show. The PRECEDENT direction never gates: a name the cell's
+     * own formula mentions is in use by that very fact.
+     */
+    _graphNode(id: string, live?: boolean): _NamedGraphNode | null;
+    /**
+     * Announces that what this collection PRESENTS has changed, without its own state having moved.
+     *
+     * @internal
+     *
+     * @remarks
+     * A rename is the case that needs this. Membership does not change, and the map is keyed by the
+     * item's id, so nothing here is written — but a consumer rendering `getItems()` is now showing
+     * the wrong text. This used to arrive as a side effect of re-filing the item under its new key;
+     * with that gone it has to be said on purpose, or the name box and the managed-names cards keep
+     * the old name until something else happens to fire.
+     *
+     * Also covers `hidden`, which decides whether an item appears in a filtered `getItems()` at all.
+     *
+     * Shares {@link _markWired}'s batching, for the same reason: a load changes every item at once.
+     */
+    protected _markContentsChanged(): void;
+    /**
+     * Holds wiring notifications until the matching {@link _endWiringBatch}.
+     *
+     * @internal
+     *
+     * @remarks
+     * Wrapped around the engine's pending-action drains. Re-entrant (counted, not a flag) because a
+     * drained action can itself drain.
+     *
+     * `private`, and reached from `Calculation._drainPending` through a declaration of this shape —
+     * how a drain batches its notifications is not part of what a collection of names offers.
+     */
+    private _beginWiringBatch;
+    /**
+     * Ends a {@link _beginWiringBatch}, emitting once if anything wired inside it.
+     *
+     * @internal
+     */
+    private _endWiringBatch;
+    protected _flushWired(): void;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<ICalculation.INamedFormula>;
+    /** {@inheritDoc INamedFormulasCollection.getItems} */
+    getItems(options?: INamedFormulasCollection.GetItemsOptions): ICalculation.INamedFormula[];
+    /**
+     * {@inheritDoc INamedFormulasCollection.getByName}
+     *
+     * @param scope - The sheet the name is being referenced FROM. A name scoped to that sheet
+     *   shadows a global of the same name, which is how a formula on that sheet resolves it.
+     *   Omitted (or null) asks the workbook-wide question — "does this name exist at all" — which
+     *   prefers the global and will settle for any scoped one.
+     *
+     * @remarks
+     * Passing a scope makes the answer STRICT: another sheet's private name is not a candidate, so
+     * the result is the sheet's own or the global, else nothing. Excel agrees — a name scoped to
+     * `One` referenced from `Two` is `#NAME?`, not `One`'s value. Without the scope there is nothing
+     * to be strict about, and the lenient fallback is what a name-exists check wants.
+     */
+    getByName(name: string, scope?: string | null): ICalculation.INamedFormula | null;
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: INamedFormulasCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Look up a named formula by its stable id.
+     */
+    getById(id: string): ICalculation.INamedFormula | null;
+    /**
+     * The item holding this exact identity — the (name, sheet) pair — or `null`.
+     *
+     * @param scopeId The sheet's stableId, or `null` for the workbook-global scope.
+     *
+     * @remarks
+     * A live scan, not a key lookup. Identity is the pair, and a defined name's `scope` half is a
+     * SHEET rather than a spelling of one, so the comparison has to be against sheet identity: after
+     * `Sheet1` becomes `Sales Data`, `Sales Data!Total` is the same name as the `Sheet1!Total` that
+     * was defined, and must still be refused as a duplicate.
+     *
+     * Backs both the duplicate check in {@link add} and the collision check on rename.
+     */
+    protected _findSameIdentity(name: string, scopeId: string | null): NamedFormula | null;
+    /**
+     * Resolves a caller's `scope` input to the sheet's stableId.
+     *
+     * @remarks
+     * Display name in, identity out — the one conversion point, so nothing downstream ever holds a
+     * spelling that a rename can invalidate. `bind` on a stableId is the identity, so passing one
+     * through (an internal caller, or a re-add of an item's own scope) is already correct.
+     *
+     * An input that names no sheet is kept verbatim rather than dropped: `getScope` falls back to it,
+     * so a name loaded from a file that references a sheet the file does not contain still reports
+     * the scope it was written with instead of silently becoming global.
+     */
+    protected _resolveScopeInput(scope: string | null): string | null;
+    /** A scope id as the sheet's current display name — see {@link NamedFormula.getScope}. */
+    protected _resolveScopeName(scopeId: string | null): string | null;
+    protected _remove(id: string): void;
+    isClosed(): boolean;
+    close(): void;
+    protected _getState(): State | null;
+    protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    protected _updateState(state: Partial<State> | ((prevState: State) => State), description?: string, options?: ITransaction.StoreOperationOptions<unknown, Partial<State>>): void;
+    protected _initState(): void;
+}
+export declare namespace NamedFormulaCollection {
+    interface ConstructorOptions {
+        /**
+         * Named items to hydrate at construction, in `IWorkbook.JSON.names` form — `ref` carries the
+         * expression.
+         *
+         * @remarks
+         * Taken here rather than through a separate `fromJSON()` call: this collection owns the
+         * items, so hydrating at construction keeps it from having a pre-load lifecycle state.
+         */
+        json?: INamed.JSON[];
+        transactions?: ITransaction.IStore;
+        container?: IContextContainer;
+        context?: IFormulaContext;
+        ready?: () => Promise<ICalculation.Status>;
+        getRange: (address: ICellRange.Address) => ICellRange;
+        /** Resolves an address to ranges. Backs {@link ICalculation.INamedFormula.getReferences}. */
+        getRanges?: (address: ICellRanges.Address) => ICellRanges;
+        /**
+         * Builds one `ICellRanges` out of cell coords plus name nodes — see
+         * `Calculation.ConstructorOptions.createGraphRanges`. Backs the graph answers
+         * ({@link ICalculation.INamedFormula.getDirectDependents} and friends) whenever a defined name
+         * belongs in one; without it those answers fall back to cells only.
+         */
+        createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+        /** Resolves a sheet stableId to its display name — calc refs carry stableId scopes. */
+        resolveSheetScope?: (stableId: string) => string | null;
+        /** Backs {@link INamed.isReadOnly} on each item. Defaults to not read-only. */
+        isReadOnly?: () => boolean;
+        getActiveCell?: () => IRange.CellCoords | null;
+        createVirtualGrid?: (gridId: string) => void;
+        /** The virtual grid a name compiles into. Keyed by name AND scope — see `add`. */
+        getOrBindProxyFakeId?: (name: string, scope: string | null) => string | null;
+        queuePendingAction?: (action: () => Promise<void>) => void;
+        /**
+         * Whether the calculation engine is running.
+         *
+         * @remarks
+         * A name added to a running engine is wired immediately; one added while it is still coming up
+         * is queued onto the pending drain. Without this every name waits for a drain that a plain
+         * `add` never causes.
+         */
+        isEngineReady?: () => boolean;
+    }
+}
+interface NamedFormulaWireOptions {
+    container: IContextContainer;
+    context: IFormulaContext;
+    ready: () => Promise<ICalculation.Status>;
+    /** Returns the scope's sheet gridId (for reference resolution). Resolved after ready(). */
+    getScopeGridId: () => string | null;
+    /** Queues a setup action to run before the next calculation cycle in ready(). */
+    queuePendingAction?: (action: () => Promise<void>) => void;
+    /** Whether the engine is running, and so whether wiring can happen now rather than on a drain. */
+    isEngineReady?: () => boolean;
+    /** Announces that this name is now bound to a region — see `NamedFormulaCollection._markWired`. */
+    markWired?: () => void;
+    /**
+     * Range resolvers backing {@link NamedFormula.getReferences} (and so {@link NamedFormula.getRanges}).
+     *
+     * @remarks
+     * These live on the wire options rather than on the item because they are only meaningful once
+     * the block is compiled — an unwired item has no references to resolve regardless. They mirror
+     * what `createFormula` supplies: workbook-level resolvers, so `getOwnScope` is required
+     * to anchor any reference that came through unscoped.
+     */
+    getRanges?: (address: ICellRanges.Address) => ICellRanges;
+    getRange?: (address: ICellRange.Address) => ICellRange;
+    /** Mixed graph answers (cells + name nodes) — see the collection option of the same name. */
+    createGraphRanges?: (cells: readonly IRange.Coords[], names: readonly _NamedGraphNode[]) => ICellRanges | null;
+    /** Resolves a sheet stableId to its display name — calc refs carry stableId scopes. */
+    resolveSheetScope?: (stableId: string) => string | null;
+    /**
+     * Resolves a name's stable id to its item — the id a virtual grid is registered under, so this
+     * doubles as the test for whether a grid id belongs to a name. See {@link NamedFormula._dependentRanges}.
+     */
+    getNamedById?: (id: string) => ICalculation.INamedFormula | null;
+}
+/**
+ * A defined name owned by the calculation engine.
+ *
+ * @remarks
+ * Implements {@link INamed} directly rather than through an adapter — the aggregating
+ * `INamedCollection` returns `INamed`, so calc's own items have to *be* `INamed` for them to flow
+ * through it. An adapter would mean a second `State` for the same name, which is the duplication
+ * this whole change exists to remove.
+ *
+ * `Formula` occupies the base-class slot (the item genuinely is a formula — it participates in the
+ * topo graph natively), so the `IModel`/`ITransactional` surface `AbstractModel` would have
+ * supplied is implemented here against the transaction store the item already holds.
+ */
+declare class NamedFormula extends Formula implements ICalculation.INamedFormula, INamed<string> {
+    /** Transactional state — see the field docs on `_transactions`. */
+    private _getNamedState;
+    private readonly _id;
+    /**
+     * Name / scope / comment / hidden live in the transaction store, not in fields, so every
+     * mutation is undoable.
+     */
+    private readonly _transactions;
+    private readonly _stateId;
+    private readonly _deleteFromCollection;
+    private readonly _wire;
+    /** Refuses a rename that would collide with a sibling — see {@link setName}. */
+    private readonly _checkRename;
+    private readonly _isReadOnly;
+    /** Resolves the scope's sheet stableId to its current display name — see {@link getScope}. */
+    private readonly _resolveSheetScope;
+    /**
+     * Tells the collection that what it presents changed — see `_markContentsChanged`.
+     *
+     * @remarks
+     * Every mutation here writes only THIS item's state, so the collection's own store never moves
+     * and its `onAfterStateChange` never fires. A rename would then be invisible to anything
+     * rendering `getItems()`.
+     */
+    private readonly _notifyCollection;
+    /** Load-time dialect unwrap — see the constructor; applied by {@link _doWireCore}'s compile. */
+    private readonly _formulaTransform;
+    private _emitter;
+    private _transactionsRemoveListener;
+    private _closed;
+    /**
+     * The compiled body, read LIVE from this name's virtual grid on every access.
+     *
+     * @remarks
+     * Deliberately not a captured instance. A name's body is versioned state like any other formula —
+     * it lives at (0,0) of the virtual grid in the ONE shared `formulaSpatial` that also holds every
+     * cell formula, inside `Calculation`'s transactional state. So the store already tracks it, and
+     * anything holding a second copy is holding a snapshot:
+     *
+     * - a structural change on a sheet the body references reaches it through `shiftPrecedents`,
+     *   which stores a NEW immutable block and calls back into nothing
+     * - an undo reverts the store to an older version, again touching no field here
+     *
+     * Left as a field, `getText` — and so `toJSON` — reports the definition as it was when the name
+     * was wired, persisting a range the engine itself no longer uses.
+     *
+     * A point lookup on a one-cell grid, so deriving it per access costs nothing worth caching.
+     * `undefined` (no grid, or nothing compiled at its origin) is the pre-wire state, which every
+     * accessor below already has a fallback for.
+     */
+    protected get _block(): IFormulaBlock;
+    constructor(coords: IRange.CellCoords | null, options: INamedFormulasCollection.AddOptions, deleteFromCollection: () => void, wire: NamedFormulaWireOptions | null, gridId?: string | null, checkRename?: (nextName: string) => void, transactions?: ITransaction.IStore, isReadOnly?: (() => boolean) | null, resolveSheetScope?: (stableId: string) => string | null, notifyCollection?: () => void);
+    /**
+     * Binds this name to the region its expression designates, now.
+     *
+     * @internal
+     *
+     * @remarks
+     * Called by the collection once the item is IN the collection, so the notification `_doWireCore`
+     * ends with describes a set that already contains it. `_doWireCore` has no awaits, so this
+     * completes before it returns and `getRanges()` answers immediately afterwards.
+     */
+    _wireNow(): void;
+    /**
+     * {@inheritDoc INamed.getId}
+     *
+     * @remarks
+     * The virtual grid UUID — the item's identity to the calculation engine, and what
+     * `IndirectSymbolProvider` keys on so a rename keeps every dependent resolving.
+     *
+     * Deliberately NOT the transaction store's state id, which `AbstractModel` conflates with it.
+     * Here the two differ: the grid id is minted first (it has to be, the symbol binds to it before
+     * any state exists), and `getVersionId` reads the state id instead.
+     */
+    getId(): string;
+    /** {@inheritDoc INamed.getName} */
+    getName(): string;
+    /**
+     * {@inheritDoc INamed.getScope}
+     *
+     * @remarks
+     * Derived on every read: the state holds the scope sheet's stableId, and this resolves it to the
+     * sheet's CURRENT display name. A rename therefore carries with no re-filing anywhere, exactly as
+     * it already does for a sheet-qualified reference (`=Sheet1!Total`) — same mechanism, applied to
+     * the name's own scope.
+     *
+     * A scope naming no sheet (a file whose `<definedName>` scopes to a sheet the file lacks) is
+     * reported verbatim rather than as global: a name that cannot be placed is not a workbook-wide
+     * name, and saying so would silently widen what it is visible to.
+     */
+    getScope(): string | null;
+    /**
+     * The scope sheet's stableId, unresolved — the identity half of this name's identity.
+     *
+     * @internal
+     *
+     * @remarks
+     * For comparing one name's scope to another's (see `_findSameIdentity`). Display names are the
+     * wrong currency for that: two sheets can be renamed into and out of a spelling, but their ids
+     * never move.
+     */
+    getScopeId(): string | null;
+    /**
+     * {@inheritDoc INamed.getType}
+     *
+     * @remarks
+     * Every defined name owned by calc is a formula — a name that "is a range" is just one whose
+     * expression is a pure reference (see {@link getRanges}). There is no separate reference type.
+     */
+    getType(): string;
+    /**
+     * {@inheritDoc INamed.getValue}
+     *
+     * @remarks
+     * The expression is what a formula name *is*, so it is the underlying value.
+     */
+    getValue(): string;
+    /**
+     * {@inheritDoc INamed.setName}
+     *
+     * @remarks
+     * A rename, NOT a redefinition — the id, the bound symbol and the virtual grid are all
+     * unchanged, so formulas referencing this name keep resolving and simply re-render with the
+     * new text (Excel's Name Manager behavior). Replacing the item instead would mint a new
+     * symbol id and leave every dependent at `#NAME?`.
+     *
+     * A plain state write. The collection is keyed by the item's own id, so there is nothing to
+     * re-file — this used to have to happen inside the same commit as the name change, or undo
+     * restored one without the other. What the collection still owes is the collision check the
+     * re-key used to give for free, which `_checkRename` supplies (and which throws BEFORE the
+     * commit opens, so a refused rename leaves nothing behind).
+     */
+    setName(name: string, options?: ITransaction.OperationOptions): this;
+    /**
+     * {@inheritDoc ICalculation.INamedFormula.setExpression}
+     *
+     * @remarks
+     * A redefinition, not a replacement: the id, the bound symbol and the virtual grid all stay, so
+     * formulas referencing this name pick up the new expression instead of going `#NAME?`. That is
+     * the Name Manager's "Refers to" edit.
+     *
+     * A leading `=` is optional — a bare range address (`Sheet1!$A$1:$B$2`) is simply a reference
+     * expression.
+     */
+    setExpression(expression: string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc INamed.getComment} */
+    getComment(): string | null;
+    /** {@inheritDoc INamed.setComment} */
+    setComment(comment: string | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc INamed.isHidden} */
+    isHidden(): boolean;
+    /**
+     * {@inheritDoc INamed.setHidden}
+     *
+     * @remarks
+     * Filters listing only. A hidden name still resolves in formulas — Excel's
+     * `_xlnm._FilterDatabase` is hidden and load-bearing.
+     */
+    setHidden(hidden?: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * A plain transactional write of this item's own state.
+     *
+     * @remarks
+     * Announced twice on purpose, to the two audiences that exist. `onAnyChange` is for a holder of
+     * THIS item; `_notifyCollection` is for anything rendering the SET — a name manager's cards, the
+     * name box — which re-reads `getItems()` and would otherwise keep showing the old name. Nothing
+     * written here moves the collection's own store, so its `onAfterStateChange` never fires.
+     *
+     * Coarse on purpose: a comment edit re-notifies the list too. The alternative is a per-field rule
+     * that has to be updated every time a field is added, and the listeners simply re-read.
+     */
+    private _updateNamedState;
+    /**
+     * {@inheritDoc INamed.select}
+     *
+     * @remarks
+     * Only a name that designates ranges can be selected; for anything else this is a no-op rather
+     * than an error, so callers can offer "go to" uniformly and let it fall flat for value names.
+     */
+    select(options?: ITypes.SelectOptions): Promise<this>;
+    /**
+     * {@inheritDoc INamed.toJSON}
+     *
+     * @remarks
+     * `scope` is written as the sheet's CURRENT display name (`getScope()`), not the state's raw
+     * stableId: `<definedName localSheetId>` addresses a sheet positionally by name, and no file
+     * format carries our internal ids. Emitting a stale name would be worse still — the workbook
+     * would reload with the name scoped to a sheet that does not answer to it, orphaned for good.
+     */
+    toJSON(): INamed.JSON | null;
+    /** {@inheritDoc IModel.isReadOnly} */
+    isReadOnly(): boolean;
+    /** {@inheritDoc IModel.isDeleted} */
+    isDeleted(): boolean;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: INamed.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ITransaction.ITransactional.getVersionId} */
+    getVersionId(): number;
+    /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
+    beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    /** {@inheritDoc ITransaction.ITransactional.doBatch} */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => Promise<R> | R, options?: string | ITransaction.OperationOptions): Promise<R> | R;
+    /** {@inheritDoc ITransaction.ITransactional.isClosed} */
+    isClosed(): boolean;
+    /**
+     * {@inheritDoc ITransaction.ITransactional.close}
+     *
+     * @remarks
+     * Terminal and not undoable, unlike {@link delete} (a state flag). Detaches the listener but
+     * does NOT `remove()` the record from the store: the collection may still hold this item in a
+     * previous commit's snapshot, and purging it would corrupt an undo back across the close.
+     */
+    close(): void;
+    /** {@inheritDoc IModel.isIModel} */
+    get isIModel(): true;
+    /** {@inheritDoc INamed.isINamed} */
+    get isINamed(): true;
+    /**
+     * {@inheritDoc INamed.getRanges}
+     *
+     * @returns The ranges this name designates, or `null` when it does not designate any.
+     *
+     * @remarks
+     * A name designates ranges exactly when its expression is a pure reference, so this is
+     * {@link getReferences} gated on {@link isReferenceOnly} — the precedents of `=$E$2:$E$6` *are* what
+     * the name points at, whereas the precedents of `=SUM(A1:A5)` are merely what it reads.
+     *
+     * `null` is returned, deliberately without guessing, in three cases:
+     *
+     * 1. **Not a reference.** `isReferenceOnly()` is false (`=1`, `=SUM(A1:A5)`). Per
+     *    {@link ICalculation.IFormula.isReferenceOnly}, only a pure-reference formula always resolves to
+     *    a range; anything else has no stable answer.
+     * 2. **Not yet wired.** Wiring is queued onto the engine's pending drain, which runs inline at
+     *    the tail of `start()` — so every name hydrated from `json.names` is unwired until
+     *    `await start()` resolves. There is no correct answer to give in that window, and a raw-text
+     *    fallback would be actively wrong: a bare `=A1` has no sheet until it is anchored.
+     *    Consumers requery once the engine has started.
+     * 3. **Wiring bailed.** `_doWireCore` returns early when the scope sheet cannot be resolved,
+     *    which leaves the item permanently unwired rather than transiently.
+     */
+    getRanges(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.INamedFormula.getDirectDependents} */
+    getDirectDependents(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.INamedFormula.getDependents} */
+    getDependents(): ICellRanges | null;
+    /**
+     * This name as a graph NODE — the backing a {@link NamedCellRange} delegates to.
+     *
+     * @internal
+     *
+     * @remarks
+     * The anchor is the defining cell (`_coords` — the active cell at authoring time), whose
+     * `scope` carries the defining sheet's stableId. A file-loaded name has neither, so the sheet
+     * falls to the name's scope sheet and finally to `null` (the consumer defaults it) — the same
+     * "self-consistent but arbitrary" anchor the body was compiled against (design doc §7).
+     */
+    _asGraphNode(): _NamedGraphNode;
+    /** {@inheritDoc ICalculation.INamedFormula.getDirectPrecedents} */
+    getDirectPrecedents(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.INamedFormula.getPrecedents} */
+    getPrecedents(): ICellRanges | null;
+    /**
+     * The precedents of this NAME — cells and names, ONE answer; the mirror of
+     * {@link _dependentRanges}.
+     *
+     * @remarks
+     * The cell half is the ordinary precedent graph: a body is a real formula on its virtual grid,
+     * and its references registered precedent ranges like any cell's — so the grid answers, one hop
+     * or deep, and only scope translation is needed. The name half is the body's `getNamedIds`:
+     * apply-at-eval means a name the body reads has no precedent edge, so the symbol list is the
+     * only carrier — one hop for `direct`, the downward closure (cycle-guarded) for the deep form,
+     * each closure member contributing its own grid's cell walk.
+     *
+     * The deep form does not take the symbol hop from UPSTREAM CELLS: with `X = A1*2` and
+     * `A1 = SomeName`, `A1` is listed and `SomeName`'s inputs are not — that hop belongs to `A1`,
+     * whose own `getDirectPrecedents` reports the `SomeName` node, which is how a TREE walk crosses
+     * it. Flattening it here would mean scanning every landed region's blocks; the tree gets it for
+     * free, one hop at a time.
+     *
+     * Everything resolves at the DEFINING anchor (the body's own compilation site) — the same
+     * answer the Name Manager gives, and the §4.1 rule for a name that is not in use.
+     */
+    private _precedentRanges;
+    /**
+     * The dependents of this NAME — cells and names, ONE answer.
+     *
+     * @remarks
+     * Two graphs meet here, and the walk has to change vehicles between them.
+     *
+     * The **symbol** edge — which formulas mention this name — is not in the precedent spatial at
+     * all. Names apply at EVAL rather than being inlined at compile, so a reference to one registers
+     * no precedent range; the edge is the nameId list each compiled block carries, read back through
+     * `container.getNamedDependents` (bucketed and memoized there — see its docs).
+     *
+     * The **cell** edge is the ordinary precedent graph, and it already carries everything downstream
+     * of those blocks. So `direct` is one hop of the first graph; the transitive form takes that hop,
+     * then hands each landing block to the grid it lives on.
+     *
+     * A block on a VIRTUAL grid is another NAME reading this one. It is not a cell — it is a NODE,
+     * and it rides in the same answer as an anchored `INamedRange` (design doc §4): one node per
+     * name, whatever the walk direction found it by, since dependents are anchor-independent. The
+     * transitive walk still passes THROUGH it on the symbol closure (`getNamedDependentNames`, the
+     * same closure the engine invalidates against), or `Base`'s dependents would stop at `Plus1`
+     * and miss every cell reading `Plus1`. This name itself is listed only when a true cycle leads
+     * back to it.
+     */
+    private _dependentRanges;
+    /**
+     * {@inheritDoc IModel.delete}
+     *
+     * @remarks
+     * Removal from the collection, the `isDeleted` flag and the grid placeholder all land in ONE
+     * commit, so undo brings the name back whole rather than half-restored.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /** {@inheritDoc ICalculation.IFormula.evaluate} */
+    evaluate(options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
+    /** {@inheritDoc ICalculation.IFormula.getCalculationStatus} */
+    getCalculationStatus(): ICalculation.ResultStatus;
+    /**
+     * {@inheritDoc ICalculation.IFormula.getExpression}
+     *
+     * @remarks
+     * Anchored at the virtual grid's origin rather than at `this._coords` (the defining cell) — see
+     * the {@link getReferences} override.
+     */
+    getExpression(options?: ICalculation.FormulaTextOptions): string;
+    /** Pre-wire fallback: return empty array before block is compiled. */
+    getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
+    /** Pre-wire fallback: return false before block is compiled. */
+    isReferenceOnly(): boolean;
+    /**
+     * {@inheritDoc ICalculation.IFormula.getReferences}
+     *
+     * @remarks
+     * Overridden to anchor at the virtual grid's origin. The inherited implementation reads
+     * `this._coords`, which for a named formula is the *defining* cell (the active cell when the
+     * name was added) — it exists only so relative refs encode their R1C1 offsets from there. The
+     * compiled block lives at (0,0) of the name's own virtual grid, so the base version would query
+     * a cell that holds nothing.
+     */
+    getReferences(): ICellRanges | null;
+    setReferenceAt(_index: number, _reference: any, _options?: any): this;
+    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: any): this;
+    private _wireAsync;
+    private _doWireCore;
+    toString(): string;
+    get [Symbol.toStringTag](): string;
+}
+export {};
+//# sourceMappingURL=NamedFormulaCollection.d.ts.map