@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.12

package/types/src/font/platform.node.d.ts

@@ -0,0 +1,5 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+export declare function getDeviceScale(): number;
+/** No platform builders here: the shipped tables and the built-ins are all there is. */
+export declare function getAdvanceBuilders(): AdvanceBuilder[];
+//# sourceMappingURL=platform.node.d.ts.map

package/types/src/group/Group.d.ts

@@ -96,6 +96,11 @@ export declare class Group extends AbstractMovableContent<State, IGroup.JSON, IG
      * @internal
      */
     _addMember(options: IMovableCollection.AddOptions): Promise<IMovable>;
+    /**
+     * What an added member waits for - its kind loaded - before the insert opens its transaction.
+     * @internal
+     */
+    _prepareMember(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
     /**
      * Places a movable whose content kind is already loaded in the group, without waiting.
      * @internal

package/types/src/group/GroupMovableCollection.d.ts

@@ -21,6 +21,10 @@ export declare class GroupMovableCollection extends AbstractCollection<IMovable,
     getCount(): number;
     /** {@inheritDoc IMovableCollection.add} */
     add(options?: IMovableCollection.AddOptions): Promise<IMovable>;
+    /** {@inheritDoc InsertableCollection._prepare} */
+    _prepare(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /** {@inheritDoc InsertableCollection._preparePicture} */
+    _preparePicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
     /** {@inheritDoc InsertableCollection._insertNow} */
     _insertNow(options: InsertableCollection.InsertOptions): IMovable;
     /** {@inheritDoc IMovableCollection.addPicture} */

package/types/src/history/IHistory.d.ts

@@ -25,15 +25,32 @@ export declare namespace IHistory {
      * @template R What `copyTo` resolves with; the coordinates unless the source has more to report.
      */
     interface ISnapshot<D = any, S = any, C = any, J = any, R = C> {
+        /**
+         * Does the asynchronous work a copy needs, before {@link copyTo} is called.
+         *
+         * @remarks
+         * A copy is made inside the destination's transaction, which must not be held open across an
+         * `await`. Anything that has to wait - loading a kind of content, decoding an image - is done
+         * here, with the destination the copy will be made to, so that `copyTo` can complete
+         * synchronously. A snapshot with nothing to wait for leaves this out, or returns `void`.
+         *
+         * @param destination The destination the snapshot will be copied to.
+         * @param options {@link IHistory.CopyToOptions}
+         */
+        prepare?(destination: D, options?: IHistory.CopyToOptions): Promise<void> | void;
         /**
          * Copies the snapshot to the specified range.
          *
+         * @remarks
+         * The copy is made inside the destination's transaction, so it completes synchronously;
+         * anything that has to wait belongs in {@link prepare}.
+         *
          * @param destination The destination `Snapshot source` where the snapshot will be copied.
          * @param options {@link IHistory.CopyToOptions}
          *
-         * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required.
+         * @returns The result of the copy.
          */
-        copyTo(destination: D, options?: IHistory.CopyToOptions): Promise<R> | R;
+        copyTo(destination: D, options?: IHistory.CopyToOptions): R;
         /**
          * The source that created the snapshot.
          * This is used to quickly do comparisons.

package/types/src/hyperlink/IHyperlink.d.ts

@@ -57,8 +57,18 @@ export interface IHyperlink {
     getTarget(): string;
     /**
      * Removes the link from the cell it is attached to. The cell's text stays.
+     *
+     * @throws When the link is read-only ({@link isReadOnly}).
      */
     delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * Whether the link can only be followed: it is not edited or removed as a link.
+     *
+     * @remarks
+     * A link that is the cell's value (a `HYPERLINK()` result) is read-only; it changes with its
+     * formula.
+     */
+    isReadOnly(): boolean;
     /**
      * For runtime type checking.
      */
@@ -106,6 +116,12 @@ export declare namespace IHyperlink {
     /**
      * A JSON representation useful for persistence.
      */
-    type JSON = Partial<Omit<IHyperlink.Properties, 'textToDisplay'>> | string;
+    type JSON = (Partial<Omit<IHyperlink.Properties, 'textToDisplay'>> & {
+        /**
+         * The text a file recorded for the link (`hyperlink/@display`). Kept and written back as
+         * read; what shows is the cell's own text.
+         */
+        display?: string;
+    }) | string;
 }
 //# sourceMappingURL=IHyperlink.d.ts.map

package/types/src/hyperlink/_Hyperlink.d.ts

@@ -12,7 +12,10 @@ export declare class Hyperlink implements IHyperlink {
     protected _p: IHyperlink.Properties;
     protected _r: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>;
     protected _d: ((options?: ITransaction.OperationOptions) => void) | undefined;
-    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void);
+    protected _readOnly: boolean;
+    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void, readOnly?: boolean);
+    /** {@inheritDoc IHyperlink.isReadOnly} */
+    isReadOnly(): boolean;
     /** {@inheritDoc IHyperlink.delete} */
     delete(options?: ITransaction.OperationOptions): void;
     /** {@inheritDoc IHyperlink.open} */

package/types/src/index.d.ts

@@ -28,7 +28,9 @@ export * from './hyperlink';
 export * from './numFmt';
 export * from './style';
 export * from './resource';
+export * from './fetch';
 export * from './string';
+export * from './richData';
 export * from './anchored';
 export * from './chart';
 export * from './pivot';
@@ -49,6 +51,7 @@ export * from './externalBook';
 export * from './dataValidation';
 export * from './conditionalFormat';
 export * from './protectedRange';
+export * from './cellControl';
 export * from './slicer';
 export * from './table';
 export { Table } from './table/Table';
@@ -61,6 +64,7 @@ export * from './sheetView';
 export * from './workbook';
 export * from './workbookProtection';
 export * from './workbookView';
+export * from './documentProperties';
 /**
  * The current version of the SDK.
  * @hidden

package/types/src/license/LicenseManager.d.ts

@@ -24,6 +24,27 @@ declare class LM {
      * Return the current license details.
      */
     getDetails(): Promise<LicenseDetails>;
+    /**
+     * Return the current license details, after confirming this runtime may run under them.
+     *
+     * @remarks
+     * {@link getDetails} only reports. This also enforces: in a browser it always resolves, because
+     * an unlicensed page runs with the evaluation watermark. Outside a browser an evaluation runs
+     * for a limited period from the build's date; past it a valid license key is required, and this
+     * rejects with the reason and what to do. The engine calls it when it starts, so a host that
+     * wants to fail at startup instead of at the first workbook calls it itself.
+     */
+    assertUsable(): Promise<LicenseDetails>;
+    /**
+     * Return the license key in use, or `null` for an evaluation.
+     *
+     * @remarks
+     * The key set by {@link setLicenseKey}, else the one found where it runs: in a browser, the
+     * `sheetxl.lic` served beside the page; outside a browser, the `SHEETXL_LICENSE_KEY` environment
+     * variable, then the key saved by `sheetxl license activate`. The key is returned as found; use
+     * {@link getDetails} to learn whether it is valid here.
+     */
+    getLicenseKey(): Promise<string | null>;
     /**
      * Print just the banner
      */

package/types/src/license/_Utils.d.ts

@@ -8,8 +8,25 @@ export declare function isPlaceholderLicenseKey(key: string | null | undefined):
 export declare function getBuildVersion(): string;
 /** When this build was made, as an ISO 8601 instant, or `''` when unstamped. */
 export declare function getBuildDate(): string;
-/** An evaluation build runs for 120 days from its build date. */
+/**
+ * How long a build runs as an evaluation, in days from its build date.
+ *
+ * @remarks
+ * Every release restamps the date, so a current install never reaches the end of the window;
+ * only one that is never updated does. Ninety days gives a pinned install (CI, a locked
+ * lockfile) a quarter before it has to move, and bounds how long any one build can run unlicensed.
+ */
+export declare const EVAL_PERIOD_DAYS = 90;
+/** When this build's evaluation period ends, or `null` for an unstamped (workspace, test) build. */
+export declare function getEvalPeriodEnd(): Date | null;
+/** Whether this build's evaluation period is over. An unstamped build never expires. */
 export declare function isEvalPeriodExpired(): boolean;
+/**
+ * The exception an expired evaluation carries. It names the date and the two ways out, because
+ * every surface that lists exceptions (the banner, `sheetxl info`, the MCP handshake) shows it
+ * verbatim and none of them knows more than the text.
+ */
+export declare function evalPeriodExpiredMessage(): string;
 /**
  * The build as a person reads it: the stamped version, or `local` plus the local build time.
  *

package/types/src/license/runtime.browser.d.ts

@@ -18,6 +18,11 @@ export declare function isDevEnv(): Promise<boolean>;
  * reached, the key last read from any of those locations; with none cached, `unreachable`.
  */
 export declare function readLicenseKey(): Promise<LicenseKeySource>;
+/**
+ * A page always runs: an unlicensed one runs with the evaluation watermark, which is the browser's
+ * enforcement. Never throws.
+ */
+export declare function assertUsable(_details: LicenseDetails): void;
 /**
  * An evaluation: unrestricted on localhost, and with the evaluation watermark anywhere else.
  */

package/types/src/license/runtime.node.d.ts

@@ -12,6 +12,16 @@ export declare function getEvalLicense(keyFrom: string): Promise<LicenseDetails>
  * or an evaluation.
  */
 export declare function getLicense(): Promise<LicenseDetails>;
+/**
+ * Whether this process may run under `details`; throws with the reason when it may not.
+ *
+ * @remarks
+ * Outside a browser there is no watermark to fall back on, so the evaluation period is the
+ * enforcement: once it is over, only a current license key that covers a server runs. A key's
+ * capacity exceptions (an oversize host) are still reported rather than enforced, exactly as before
+ * the period ended. An unstamped build has no period and always runs.
+ */
+export declare function assertUsable(details: LicenseDetails): void;
 export declare function setKey(key: string, force?: boolean): Promise<void>;
 export declare function getKey(): Promise<string | undefined>;
 export declare function printBanner(isUser: boolean): Promise<void>;

package/types/src/listener/IListener.d.ts

@@ -27,10 +27,22 @@ export declare namespace IListener {
         /**
          * Whether the listener takes part in the operation that notifies it.
          *
-         * @defaultValue `true` when the listener is added during an operation - a listener added as a
-         * consequence of one is part of it - and `false` otherwise.
+         * @defaultValue `true` when the listener is added through the object a batch hands its
+         * callback ({@link IWorkbook.doBatch}, {@link IWorksheet.doBatch}, {@link ICellRange.doBatch}),
+         * and `false` otherwise - however long a batch stays open.
          *
          * @remarks
+         * A script, or code acting for one, adds its listeners through its batch and takes part by
+         * default. A view, or anything else watching the document, adds them the ordinary way and is
+         * an observer by default. Neither needs to set this.
+         *
+         * A participant hears what is announced while an operation is under way. A worksheet announces
+         * each write as it is made ({@link IWorksheet.Events.onDataChange}, `onStyleChange`,
+         * `onMergesChange`, `onSpillsChange`), so a participant hears each write and an observer hears
+         * the operation once, every write merged. An event that is announced only once the operation
+         * has landed never reaches a participant; to hear one from a batch, add the listener with
+         * `transactional: false`.
+         *
          * A transactional listener:
          * * is told inline, inside the operation, so anything it writes joins that same commit, and
          *   is told during an undo or a redo for the same reason;

package/types/src/listener/ListenerEmitter.d.ts

@@ -13,14 +13,20 @@ export interface NotifyOptions<T = any> {
      * says. `false` is for a signal that is not a change to the document (a dirty flag).
      */
     transactional?: boolean;
+    /**
+     * Combines the params of two notifications that are delivered to one callback as one, after an
+     * operation lands. Without it the first notification's params are delivered.
+     */
+    merge?: (prev: T | null | undefined, next: T | null | undefined) => T | null | undefined;
 }
 /**
  * Manages listeners.
  *
  * @remarks
  * `transactional` ({@link IListener.Options}) says whether a listener takes part in the operation
- * that notifies it. Unless the caller says, it is inferred from where the listener was added: one
- * added as a consequence of an operation is part of it.
+ * that notifies it. Unless the caller says, it does when it was added through the handle of a batch
+ * open on this emitter's store (`IWorkbook.doBatch`), and does not otherwise, however long a batch
+ * stays open.
  *
  * * A transactional listener is told inline, inside the operation, so what it writes joins that
  *   commit; it is told during a restore's dispatch for the same reason. It is versioned with the
@@ -63,7 +69,9 @@ export declare class ListenerEmitter<SOURCE, EVENTS> {
      * where a listener added as a consequence of it belongs.
      */
     protected _updateEntries(mutate: (entries: EntrySet<SOURCE, EVENTS>) => void): void;
-    protected _doNotify<T = unknown>(listeners: IListener.Callback<SOURCE>[], removes?: IListener.Remove[] | null, options?: NotifyOptions<T>, fired?: Set<IListener.Callback<SOURCE>>): Promise<any>;
+    protected _doNotify<T = unknown>(listeners: IListener.Callback<SOURCE>[], removes?: IListener.Remove[] | null, options?: NotifyOptions<T>, fired?: Set<IListener.Callback<SOURCE>>, merged?: Map<IListener.Callback<SOURCE>, any> | null): Promise<any>;
+    /** Whether a transactional listener is told of `key`: one is, and it is told inline. */
+    hasTransactional(key: keyof EVENTS): boolean;
     /** The callbacks for `key` in a bucket, gathered first so a removal during delivery is safe. */
     protected _collect(entries: EntrySet<SOURCE, EVENTS> | undefined, key: keyof EVENTS): Collected<SOURCE> | null;
     /**

package/types/src/movable/IMovable.d.ts

@@ -78,7 +78,7 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * holds none.
      *
      * @remarks
-     * A group's movable holds its members. As on a sheet ({@link ISheet.getMovables}), adding to the
+     * A group's movable holds its members. As on a sheet ({@link IWorksheet.getMovables}), adding to the
      * collection places a movable here, at canvas bounds; deleting a member's content takes it out.
      * Each member's {@link getParent} is this movable.
      *
@@ -230,6 +230,17 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * {@link setLockAspectRatio}
      */
     isLockAspectRatio(): boolean;
+    /**
+     * Whether the movable is printed with the sheet. Excel's **Print object**.
+     *
+     * @defaultValue true
+     */
+    setPrintObject(printObject: boolean): IMovable;
+    /**
+     * @see
+     * {@link setPrintObject}
+     */
+    isPrintObject(): boolean;
     /**
      * Ses the anchor type.
      */
@@ -550,7 +561,7 @@ export declare namespace IMovable {
         /**
          * Called when the movable is copied to a new container.
          */
-        copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Promise<Bounds> | Bounds;
+        copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Bounds;
     }
     interface CopyOptions extends ReferenceableClipboard.CopyOptions {
         /** {@inheritDoc IMovable.SelectOptions} */
@@ -566,18 +577,6 @@ export declare namespace IMovable {
         tl: OffsetCoords;
         br: OffsetCoords;
     }
-    interface ClientData {
-        /**
-         * disable selection on movable elements when the sheet is protected
-         * @defaultValue false
-         */
-        fLocksWithSheet?: boolean;
-        /**
-         * print movable elements when printing the sheet
-         * @defaultValue true
-         */
-        fPrintsWithSheet?: boolean;
-    }
     interface ContentJSON<J> {
         /**
          * Identifies the type of movable object.
@@ -653,7 +652,21 @@ export declare namespace IMovable {
         /**
          * lock specific fields*/
         locks?: any;
-        clientData?: IMovable.ClientData;
+        /**
+         * If true then the movable is left out when the sheet is printed.
+         *
+         * @defaultValue false
+         */
+        noPrint?: boolean;
+        /**
+         * If true then the movable can still be selected and edited while the sheet is protected.
+         *
+         * @remarks
+         * Carried for the file; sheet protection does not guard movables yet.
+         *
+         * @defaultValue false
+         */
+        unlocked?: boolean;
     }
 }
 //# sourceMappingURL=IMovable.d.ts.map

package/types/src/movable/IMovableCollection.d.ts

@@ -169,7 +169,7 @@ export declare namespace IMovableCollection {
         rotation?: number;
         /**
          * Placement hint used only when {@link bounds} is omitted. `'viewport'` centers the (default-sized)
-         * movable in the visible viewport via {@link ISheet.IListeners.onRequestViewport}, falling back to the
+         * movable in the visible viewport via {@link IWorksheet.IListeners.onRequestViewport}, falling back to the
          * default cursor placement when no viewport responds (headless). Omit ⇒ default cursor placement.
          */
         autoPlace?: 'viewport';

package/types/src/movable/Movable.d.ts

@@ -75,7 +75,12 @@ export declare class Movable<J extends IMovable.JSON = IMovable.JSON, STATE exte
     protected _clone(): Movable;
     /** {@inheritDoc IHistory.ISnapshotSource.getSnapshot} */
     getSnapshot(bounds: Bounds, options?: ReferenceableClipboard.CopyOptions): IHistory.ISnapshot<IMovable.SnapshotDestination, IMovable, Bounds>;
-    protected _doCopy(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Promise<void>;
+    /**
+     * Places a copy of this movable in `destination`, inside the caller's transaction: the kind is
+     * loaded already (the snapshot's `prepare`), and the bounds are given, so there is nothing to wait
+     * for.
+     */
+    protected _doCopy(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): void;
     /** For easy overriding in subclass to implement ISnapshot */
     protected _toText(): Promise<string> | string;
     /** For easy overriding in subclass to implement ISnapshot */
@@ -90,6 +95,10 @@ export declare class Movable<J extends IMovable.JSON = IMovable.JSON, STATE exte
     setLockAspectRatio(lockAspectRatio: boolean): this;
     /** {@inheritDoc IMovable.isLockAspectRatio} */
     isLockAspectRatio(): boolean;
+    /** {@inheritDoc IMovable.setPrintObject} */
+    setPrintObject(printObject: boolean): this;
+    /** {@inheritDoc IMovable.isPrintObject} */
+    isPrintObject(): boolean;
     /** What the content says when the movable states no aspect lock of its own. */
     protected _isDefaultLockAspectRatio(): boolean;
     /** {@inheritDoc IMovable.getConnectionSites} */
@@ -306,6 +315,8 @@ interface State extends AbstractAnchored.State {
     lockAspectRatio?: boolean | null;
     /** Edit locks by the file's own names, kept as read. */
     locks?: Record<string, boolean> | null;
+    noPrint?: boolean;
+    unlocked?: boolean;
     offsets?: MovableOffsets;
     /**
      * Where a movable that does not size with its cells is placed, in pixels. `null` for one that

package/types/src/movable/MovableCollection.d.ts

@@ -5,17 +5,21 @@ import { IMovable } from './IMovable';
 import { IMovableCollection } from './IMovableCollection';
 import { InsertableCollection } from './_InsertableCollection';
 export declare class MovableCollection extends AbstractCollection<IMovable, IMovableCollection.GetItemsOptions> implements IMovableCollection, InsertableCollection {
-    private _add;
+    private _prepareDelegate;
+    private _preparePictureDelegate;
     private _insert;
     private _getItemsDelegate;
     private _getCount;
     private _updateSelected;
     private _addListeners;
-    private _addPicture;
     private _group;
-    constructor(add: (options?: IMovableCollection.AddOptions) => Promise<IMovable>, insert: (options: InsertableCollection.InsertOptions) => IMovable, getItems: (options?: IMovableCollection.GetItemsOptions) => IMovable[], getCount: () => number, updateSelected: (update: (movable: IMovable) => void, action?: string) => void, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove, addPicture: (image: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions) => Promise<IMovable>, group: (movables: readonly IMovable[], options?: IMovableCollection.GroupOptions) => Promise<IMovable>);
+    constructor(prepare: (options: IMovableCollection.AddOptions) => Promise<InsertableCollection.InsertOptions>, preparePicture: (image: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions) => Promise<InsertableCollection.InsertOptions>, insert: (options: InsertableCollection.InsertOptions) => IMovable, getItems: (options?: IMovableCollection.GetItemsOptions) => IMovable[], getCount: () => number, updateSelected: (update: (movable: IMovable) => void, action?: string) => void, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove, group: (movables: readonly IMovable[], options?: IMovableCollection.GroupOptions) => Promise<IMovable>);
     /** {@inheritDoc IMovableCollection.add} */
     add(options?: IMovableCollection.AddOptions): Promise<IMovable>;
+    /** {@inheritDoc InsertableCollection._prepare} */
+    _prepare(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /** {@inheritDoc InsertableCollection._preparePicture} */
+    _preparePicture(image: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
     /** {@inheritDoc InsertableCollection._insertNow} */
     _insertNow(options: InsertableCollection.InsertOptions): IMovable;
     /** {@inheritDoc AbstractCollection._getItems} */

package/types/src/movable/_InsertableCollection.d.ts

@@ -1,17 +1,28 @@
 import { IMovable } from './IMovable';
 import { IMovableCollection } from './IMovableCollection';
+import { IResource, IResourceCollection } from '../resource';
 /**
- * A movable collection that can insert without waiting, for a movable whose content kind is
- * already loaded.
+ * A movable collection whose add is in two parts: the waiting, then an insert that does not wait.
  *
  * @remarks
- * {@link IMovableCollection.add} waits for the kind to load. An operation that frees a movable it
- * already holds - a delete that dissolves a group - knows the kind is loaded and cannot wait: it
- * runs inside a synchronous delete.
+ * {@link IMovableCollection.add} waits for the kind to load, and for a picture's image to decode,
+ * before it inserts. An operation that runs inside a transaction cannot wait there - a paste, or a
+ * delete that dissolves a group - so it does the waiting first ({@link _prepare},
+ * {@link _preparePicture}), or knows there is none, and then inserts with {@link _insertNow}.
  *
  * @internal
  */
 export interface InsertableCollection {
+    /**
+     * Everything {@link IMovableCollection.add} waits for, answered as the options
+     * {@link _insertNow} takes: the kind loaded, the position settled.
+     */
+    _prepare(options: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
+    /**
+     * Everything {@link IMovableCollection.addPicture} waits for, answered as the options
+     * {@link _insertNow} takes: the image decoded and sized, the kind loaded, the position settled.
+     */
+    _preparePicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<InsertableCollection.InsertOptions>;
     /** Inserts a movable as {@link IMovableCollection.add} does, once its kind is loaded. */
     _insertNow(options: InsertableCollection.InsertOptions): IMovable;
 }

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

@@ -223,6 +223,36 @@ export declare namespace INamed {
          * This is interpreted by the named item
          */
         ref?: string;
+        /** {@inheritDoc INamed.FileAttributes} */
+        fileAttributes?: INamed.FileAttributes;
+    }
+    /**
+     * What a file says about a defined name beyond its value: macro bindings, Excel 4.0 and
+     * publishing flags. Kept and written back as read; none of it changes how the name evaluates.
+     */
+    interface FileAttributes {
+        /** The name is a macro function (rather than a command). */
+        function?: boolean;
+        /** The name's macro is a VBA procedure. */
+        vbProcedure?: boolean;
+        /** The name is an Excel 4.0 (XLM) macro, or a `_xlpm.` lambda parameter Excel marks the same way. */
+        xlm?: boolean;
+        /** The category the macro function is listed under. */
+        functionGroupId?: number;
+        /** The keyboard shortcut that runs the macro. */
+        shortcutKey?: string;
+        /** The menu text for the macro. */
+        customMenu?: string;
+        /** The description of the macro. */
+        description?: string;
+        /** The help topic for the macro. */
+        help?: string;
+        /** The status bar text for the macro. */
+        statusBar?: string;
+        /** The name is published to a server with the workbook. */
+        publishToServer?: boolean;
+        /** The name is a parameter a server-side workbook takes. */
+        workbookParameter?: boolean;
     }
 }
 //# sourceMappingURL=INamed.d.ts.map

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

@@ -13,7 +13,7 @@ import { INamed } from './INamed';
  * | 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 |
+ * | {@link IWorksheet.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.
@@ -24,7 +24,7 @@ import { INamed } from './INamed';
  * 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
+ * globally visible items do. For the tables anchored to one sheet, ask `IWorksheet.getTables()` — that is
  * the location question, and it has its own call.
  *
  * **Porting from Excel's Office Scripts.** Deliberately close but not identical. There,
@@ -78,6 +78,25 @@ export interface INamedCollection extends ICollection<INamed> {
      * take the first.
      */
     getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+    /**
+     * Deletes the defined names nothing reads, as one operation.
+     *
+     * @param options `hiddenOnly` limits it to names flagged hidden; `dryRun` counts without deleting.
+     * @returns How many names were deleted, or with `dryRun`, would be.
+     * @throws `Error` if the names are read-only (a protected workbook structure) and this is not a dry run.
+     *
+     * @remarks
+     * A name is read when a cell formula, a conditional format, a data validation, a chart or another
+     * name refers to it — the readers `ICalculation.INamedFormula.getDependents` reports. A name
+     * that a kept name's definition mentions is kept too, whether or not anything reads that one.
+     * Only defined names are considered; a table is named by the table it belongs to. Excel's built-in
+     * names (`_xlnm.Print_Area`, `_xlnm.Print_Titles`, `_xlnm._FilterDatabase`) are read by the sheet
+     * itself, not by formulas, and are never removed.
+     *
+     * One operation, so one undo puts every name back. Asked of a sheet's collection
+     * (`IWorksheet.getNames()`), only the names scoped to that sheet are considered.
+     */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
     /**
      * Lookup a named range with a given name.
      *
@@ -216,6 +235,23 @@ export declare namespace INamedCollection {
          */
         includeHidden?: boolean;
     }
+    /**
+     * Options for {@link INamedCollection.removeUnused}.
+     */
+    interface RemoveUnusedOptions {
+        /**
+         * Only names flagged hidden — the ones a user cannot see to delete.
+         *
+         * @defaultValue false
+         */
+        hiddenOnly?: boolean;
+        /**
+         * Count the names that would be deleted, and delete none.
+         *
+         * @defaultValue false
+         */
+        dryRun?: boolean;
+    }
     /**
      * Options for {@link INamedCollection.getByRanges}.
      *