@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

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

@@ -0,0 +1,141 @@
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICell } from '../cell';
+import { INamed } from '../named';
+import { ICalculation } from './ICalculation';
+/**
+ * Collection of named formulas available in the calculation engine.
+ */
+export interface INamedFormulasCollection extends ICollection<ICalculation.INamedFormula> {
+    /**
+     * Add a named formula to the collection.
+     *
+     * @param options {@link INamedFormulasCollection.AddOptions}
+     */
+    add(options: INamedFormulasCollection.AddOptions): ICalculation.INamedFormula;
+    /**
+     * Returns items that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link INamedFormulasCollection.GetItemsOptions}
+     */
+    getItems(options?: INamedFormulasCollection.GetItemsOptions): ICalculation.INamedFormula[];
+    /**
+     * Returns a named formula by its stable internal id, or `null` if not found.
+     * Will be made required in a future release.
+     */
+    getById(id: string): ICalculation.INamedFormula | null;
+    /**
+     * Convenience method for filter by name.
+     * This is functionally equivalent to getItems({ name }).
+     *
+     * @param name The name to search for. This is case insensitive.
+     */
+    getByName(name: string): ICalculation.INamedFormula | null;
+    /**
+     * Register listeners for collection changes.
+     */
+    addListeners(listeners: INamedFormulasCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Serializes to `IWorkbook.JSON.names` form, or `null` when there is nothing to write.
+     *
+     * @remarks
+     * This is the authority for `<definedName>` on save. An `INamedCollection` aggregates several
+     * registries — tables among them — and is not.
+     */
+    toJSON(): INamed.JSON[] | null;
+}
+/**
+ * {@inheritDoc INamedFormulasCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link INamedFormulasCollection}
+ */
+export declare namespace INamedFormulasCollection {
+    /**
+     * Options for adding a named formula to the collection.
+     */
+    interface AddOptions extends ITransaction.OperationOptions {
+        /**
+         * Required. The name that identifies this formula in expressions.
+         */
+        name: string;
+        /**
+         * Required. The formula expression string, e.g. `"=SUM(A:A)"`.
+         */
+        expression: string;
+        /**
+         * Optional reference for the formula.
+         */
+        cell?: ICell.Address;
+        /**
+         * A string identifying the scope. This is normally a sheet name.
+         *
+         * @defaultValue `null` — global scope
+         */
+        scope?: string | null;
+        /**
+         * Optional comment for the named formula.
+         */
+        comment?: string;
+        /**
+         * If true the named formula is not visible in the UI.
+         *
+         * @defaultValue false
+         */
+        hidden?: boolean;
+        /**
+         * If `true`, redefine an existing name in the same scope instead of throwing.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Mirrors `INamedCollection.addFormula` and the Name Manager, where editing an existing
+         * name is a redefinition. Without it a collision throws — a silent no-op would drop the new
+         * expression on the floor.
+         */
+        replaceExisting?: boolean;
+        /**
+         * A structural transform applied when this name's expression compiles — the READ half of the
+         * format-dialect hook, supplied by format loads (hydration) so a legacy on-disk spelling
+         * normalizes. Kept for the item's lifetime so an undo back to the loaded text re-applies it.
+         *
+         * @see {@link ICalculation.FormulaTransform}
+         */
+        formulaTransform?: ICalculation.FormulaTransform;
+    }
+    /**
+     * Options for getting items from the collection.
+     */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Filter with the given name. This is case insensitive.
+         */
+        name?: string;
+        /**
+         * Filter by scope. Pass `null` to return only global-scoped formulas.
+         */
+        scope?: string | null;
+    }
+    interface Events {
+        /**
+         * Called when the names this collection holds, or the regions they designate, change.
+         *
+         * @remarks
+         * Fires for the usual add / remove / rename, and again once a name is bound to its ranges —
+         * defining one is two steps, and `getRanges()` is null between them. Redefining a name and
+         * undoing onto a different definition recompile through that same path and announce it too.
+         *
+         * Wiring notifications are batched per drain, so loading a workbook emits once rather than
+         * once per name. Re-emitted verbatim by the aggregating `INamedCollection`, which is what
+         * consumers outside the engine listen to.
+         */
+        onCollectionChange?(source: INamedFormulasCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<INamedFormulasCollection, INamedFormulasCollection.Events> {
+    }
+}
+//# sourceMappingURL=INamedFormulasCollection.d.ts.map