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

package/types/src/io/IWorkbookIO.d.ts

@@ -2,6 +2,7 @@ import { FetchArgs, Base64Args, ITaskProgress, MaybePromise } from '@sheetxl/uti
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IWorkbook } from '../workbook';
+import { ICellContainerOptions } from '../sheet';
 /**
  * Interface for workbook input/output operations across multiple source types and formats.
  *
@@ -387,6 +388,8 @@ export interface IWorkbookIO extends IListener.ISource<IWorkbookIO, IWorkbookIO.
      * {@link TransactionSaveStateManager} to track a workbook's dirty state with no extra wiring.
      */
     addCommitListener(listener: ITransaction.ICommitSource.IListeners): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIWorkbookIO: true;
 }
 export declare namespace IWorkbookIO {
     /**
@@ -394,11 +397,13 @@ export declare namespace IWorkbookIO {
      * whether it can be written back to. The IO analog of a `Uri` / `FileSystemFileHandle`.
      *
      * @remarks
-     * Minted and owned by the IO/store layer, never by the workbook model — but every workbook holds
-     * a stable, *read-only* reference to one (see {@link IWorkbook.getOrigin}), like the DOM's
-     * `document.URL`. The origin **object** is mutable in place by its owner (a save that resolves a
-     * destination fills an unbound origin; a store rename moves it), firing `onChange` so holders
-     * follow; the workbook's *reference* to it never changes.
+     * Minted and owned by the IO/store layer, never by the workbook model. An origin names **one**
+     * file for its whole life: its path and format never change. What can change in place is what is
+     * known about that file (its size, whether it is encrypted, its display label), firing `onChange`.
+     *
+     * *Which* origin a workbook lives in can change: a save that resolves a new destination (a first
+     * save, a Save As) moves the workbook to a new origin, and the one it left keeps naming its own
+     * file — see {@link IWorkbook.getOrigin}. An origin backs one open workbook at a time.
      *
      * An **unbound** origin (`getPath()` returns `null`) belongs to an in-memory workbook with no
      * destination yet. A **read-only** origin (`canWrite()` is `false`) is real provenance that cannot
@@ -493,6 +498,16 @@ export declare namespace IWorkbookIO {
          * each read/write of this handle.
          */
         getSize(): number | null;
+        /**
+         * When the file was last modified, in milliseconds since the epoch, or `null` if unknown — a
+         * stat-style property like {@link getSize} (the analog of `File.lastModified`), recorded when
+         * the file is read and updated when it is written.
+         *
+         * @remarks
+         * What the store last saw, not a live check: comparing it with the file's current time is how a
+         * host notices the file changed on disk since it was opened.
+         */
+        getLastModified(): number | null;
         /**
          * Whether this source can be written back to (a silent re-save). A read-only source (e.g. a
          * fetched URL) returns `false`, signalling callers to prompt for a destination ("Save As").
@@ -522,6 +537,39 @@ export declare namespace IWorkbookIO {
         interface IListeners extends IListener.Callbacks<Origin, Origin.Events> {
         }
     }
+    /**
+     * Supplies a workbook's current {@link IWorkbookIO.Origin} — the file it lives in now.
+     *
+     * @remarks
+     * An origin names one file for its whole life; which file a *workbook* lives in changes when a
+     * save resolves a new destination (a first save, a Save As). The workbook reads its origin
+     * through this and follows `onOriginChange`, so the same workbook moves to the new file while
+     * the origin it held keeps naming the old one.
+     *
+     * Read-only by design: the workbook consumes it and never sets it. Whoever implements it decides
+     * when it moves. The default implementation (`WorkbookOriginProvider`) is moved by the IO layer
+     * after a successful save; a host with its own save flow can pass its own implementation through
+     * `IWorkbook.ConstructorOptions.origin` and move it on {@link IWorkbookIO.Events.onWrite}.
+     */
+    interface OriginProvider extends IListener.ISource<OriginProvider, OriginProvider.IListeners> {
+        /**
+         * The origin the workbook lives in now. Always present; unbound for a never-saved workbook.
+         */
+        getOrigin(): Origin;
+    }
+    namespace OriginProvider {
+        /**
+         * IListener interface for {@link IWorkbookIO.OriginProvider} events.
+         */
+        interface Events {
+            /**
+             * Called when the provider supplies a different origin.
+             */
+            onOriginChange?(source: OriginProvider): void;
+        }
+        interface IListeners extends IListener.Callbacks<OriginProvider, OriginProvider.Events> {
+        }
+    }
     /**
      * Common fields shared by all ambient I/O events.
      */
@@ -532,8 +580,10 @@ export declare namespace IWorkbookIO {
          */
         workbook: IWorkbook;
         /**
-         * The {@link IWorkbookIO.Origin} handle the operation actually used — the workbook's own
-         * origin for a read or a save; the (distinct) target handle for an export.
+         * The {@link IWorkbookIO.Origin} handle the operation actually used — the file read, or the file
+         * written: the workbook's own origin for a plain save, a new one for a save that resolved a
+         * destination (a first save, a Save As), the target for an export. Its format is the one read or
+         * written.
          *
          * @remarks
          * Uniform across read and write, so an ambient listener (e.g. recent-files) can track "the
@@ -776,6 +826,18 @@ export declare namespace IWorkbookIO {
          * If it is set in the createWorkbookOptions it will override this value.
          */
         readonly?: boolean;
+        /**
+         * Open the source as a copy: the workbook gets its own read-only origin for the same path, so it
+         * never saves back over the original — its first save asks where.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * A file is saved back by one open workbook at a time, so opening a file that is already open
+         * gives a copy without asking. Set this to get one regardless. Writing over a file another open
+         * workbook saves back to is refused.
+         */
+        asCopy?: boolean;
         /**
          * Read the workbook for calculation only, trading visual formatting for a faster, lighter read.
          *
@@ -788,6 +850,29 @@ export declare namespace IWorkbookIO {
          * save time and memory.
          */
         calcOnly?: boolean;
+        /**
+         * What loading is allowed to calculate — {@link ICellContainerOptions.calcOnLoad},
+         * with the format handler translating what the FILE says into it.
+         *
+         * @defaultValue `'auto'`
+         *
+         * @remarks
+         * - `'auto'` — cached values are trusted; the load pass evaluates a formula cell with no
+         *   cached value (a repair — Excel always stores one) and refreshes volatiles. Everything is
+         *   recalculated only when Excel would recalculate on open: the file sets `fullCalcOnLoad`,
+         *   or for xlsx its `calcId` is missing or older than the Excel build this library is
+         *   verified against. (What this library writes carries one: the source file's, else that
+         *   build's.) To take the file's values as they are whatever it says — as openpyxl does —
+         *   pass `'none'`; to always recalculate, `'full'`.
+         * - `'full'` — everything is recalculated, whatever the file says.
+         * - `'none'` — the calculation engine is not started. Nothing is compiled or calculated, and
+         *   a save writes values and formulas exactly as they were read — the pure IO pass. The
+         *   first mutation, or an explicit {@link ICalculation.calculate} /
+         *   {@link IWorkbook.whenCalculationReady}, starts the engine.
+         *
+         * An explicit `createWorkbookOptions.calcOnLoad` wins over the translation.
+         */
+        calcOnLoad?: ICellContainerOptions.CalcOnLoad;
         /**
          * Provide options to the workbook constructor.
          */
@@ -857,6 +942,10 @@ export declare namespace IWorkbookIO {
          *
          * Used for type detection when it cannot be inferred from the destination.
          * Examples: 'xlsx', 'csv', 'application/json', 'Excel'
+         *
+         * @remarks
+         * A destination whose extension already names a different format is an error, not an
+         * override: changing a file's type means writing to a new name (see {@link IWorkbookIO.writeAs}).
          */
         format?: string;
         /**
@@ -880,8 +969,72 @@ export declare namespace IWorkbookIO {
         password?: string | null;
         /**
          * Optional progress callback for long running writes.
+         *
+         * @remarks
+         * Its `onWarning` receives each write warning (a feature the format cannot hold) once the format
+         * handler has finished, already deduplicated. It is a log channel; the decision to proceed is
+         * {@link onWarnings}.
          */
         progress?: ITaskProgress<IWorkbookIO.Origin>;
+        /**
+         * Decides whether a write that would lose something goes ahead.
+         *
+         * @remarks
+         * Called at most **once** per write, after the format handler has produced the bytes and before
+         * the store persists them, and only when the handler raised a warning that an earlier write to
+         * the same file did not already let through this session — a repeat save of the same lossy
+         * workbook does not ask again. The event carries every warning, deduplicated, so a host shows
+         * one dialog listing them rather than one per finding.
+         *
+         * Returning `false` cancels the write — {@link IWorkbookIO.write} then resolves to `null`, like
+         * a dismissed save dialog — but only when {@link WriteWarningsEvent.canCancel} is `true`. A
+         * prompted write (a Save As, a first save, a download) always proceeds, because the destination
+         * the user just chose has nothing in it to protect and a browser save picker has already created
+         * the file: an empty file there is worse than a lossy one. The workbook still holds everything
+         * that was not written, so the recovery is to save a copy in a format that can hold it.
+         *
+         * Omitted, every write proceeds and the warnings are reported through `progress.onWarning` only.
+         */
+        onWarnings?: (event: IWorkbookIO.WriteWarningsEvent) => boolean | void | Promise<boolean | void>;
+    }
+    /**
+     * One thing a format handler could not write faithfully.
+     */
+    interface WriteWarning {
+        /**
+         * What was not written, or was written degraded.
+         */
+        message: string;
+        /**
+         * Locates the finding — for xlsx, the path of the package part (`/xl/worksheets/sheet2.xml`).
+         */
+        context?: any;
+    }
+    /**
+     * What {@link WriteOptions.onWarnings} is asked to decide on.
+     */
+    interface WriteWarningsEvent extends IOEvent {
+        /**
+         * Every warning the write raised, deduplicated, in the order they were first raised.
+         */
+        warnings: WriteWarning[];
+        /**
+         * `true` for a save (the workbook will be marked clean), `false` for an export copy.
+         *
+         * @remarks
+         * Not the same as `origin === workbook.getOrigin()`: a save that resolved a new destination (a
+         * first save, a Save As) moves the workbook to `origin` only once the write succeeds.
+         */
+        save: boolean;
+        /**
+         * Whether returning `false` will cancel the write.
+         *
+         * @remarks
+         * `true` only for a silent re-save to a bound, writable destination — the one case where the
+         * bytes would replace a file that may hold what is about to be lost. See
+         * {@link WriteOptions.onWarnings} for why a prompted write cannot be cancelled.
+         */
+        canCancel: boolean;
     }
     /**
      * Options for {@link IWorkbookIO.writeAs} — everything a write takes, plus the one thing only a
@@ -925,8 +1078,8 @@ export declare namespace IWorkbookIO {
         /**
          * Persists the workbook described by the request.
          *
-         * @returns The written {@link IWorkbookIO.Origin} handle (normally `request.origin`, updated
-         *   in place), or `null` if cancelled.
+         * @returns The {@link IWorkbookIO.Origin} actually written — `request.origin` when the store
+         *   persisted to it, a new origin when it resolved a destination — or `null` if cancelled.
          *
          * @remarks
          * Optional. A read-only store omits it; {@link IWorkbookIO.canWrite} then reports `false` and
@@ -953,13 +1106,14 @@ export declare namespace IWorkbookIO {
      * The store receives the destination as an {@link IWorkbookIO.Origin} handle — never a
      * fileName-vs-provenance ambiguity. Its contract:
      * - **bound + writable** origin → persist to it silently (no dialog), *unless* {@link prompt}.
+     *   Update its stat state (the written `size`) and return it.
      * - **unbound or read-only** origin, or {@link prompt} → resolve a destination itself (a save
-     *   picker in the browser; an error in bare Node), using {@link suggestedName} for any
-     *   prompt/default, and **update the handle in place** to the resolved destination (the store
-     *   fills in a handle it resolved itself; it never overrides one that was already bound and
-     *   writable).
-     *
-     * The store returns this same handle (updated in place — including the written `size`).
+     *   picker in the browser; a suggested name in Node), using {@link suggestedName} for any
+     *   prompt/default, and **mint a new origin** for it — passing that origin to {@link encode} —
+     *   then return the new origin. The request's origin is never changed: it keeps naming its own
+     *   file. For a save, the IO layer then moves the workbook to the origin returned.
+     * - Refuse (throw) a destination another open workbook saves back to — other than this
+     *   workbook's own.
      */
     interface WriteRequest {
         /**
@@ -971,8 +1125,8 @@ export declare namespace IWorkbookIO {
          */
         format: FormatType;
         /**
-         * The destination handle: the workbook's own origin for a save, or a minted one for an
-         * explicit-target export. May be unbound (`getPath()` `null`) — see the store contract above.
+         * The destination handle: the workbook's own origin for a save, the target for a Save As or an
+         * export. May be unbound (`getPath()` `null`) — see the store contract above.
          */
         origin: IWorkbookIO.Origin;
         /**
@@ -987,13 +1141,22 @@ export declare namespace IWorkbookIO {
         /**
          * Encodes the workbook to bytes using the resolved format, or an alternate format key.
          *
+         * @param format An alternate format key — the one the user picked, for a resolved destination.
+         * @param origin The origin being written, when the store minted one for a destination it
+         *   resolved. Omitted, it is {@link origin}. The caller's
+         *   {@link WriteOptions.onWarnings | onWarnings} sees this as the destination.
+         *
          * @remarks
          * Call this **after** resolving the destination (e.g. once a Save picker / permission prompt has
          * returned). The first invocation also fires the caller's {@link ITaskProgress.onStart}, so
          * encoding before the prompt resolves would show progress UI on top of the dialog. A store that
          * is cancelled should return without calling `encode`, so `onStart` never fires for it.
+         *
+         * @returns The bytes to persist, or `null` when the caller declined the write through
+         *   {@link WriteOptions.onWarnings}. A store that receives `null` persists nothing and returns
+         *   `null` — the same outcome as a dismissed save dialog.
          */
-        encode: (format?: string) => Promise<ArrayBufferLike>;
+        encode: (format?: string, origin?: IWorkbookIO.Origin) => Promise<ArrayBufferLike | null>;
     }
     /**
      * The request passed to {@link IWorkbookIO.IBackingStore.read}.
@@ -1049,6 +1212,10 @@ export declare namespace IWorkbookIO {
          * The source size in bytes, if known.
          */
         size?: number;
+        /**
+         * When the source was last modified, in milliseconds since the epoch, if known.
+         */
+        lastModified?: number;
         /**
          * The detected source type (e.g. `'file'`, `'fetch'`), used for a fallback display name.
          */

package/types/src/io/WorkbookIO.d.ts

@@ -68,6 +68,13 @@ export declare class DefaultWorkbookIO implements IWorkbookIO {
     write<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, target?: string | IWorkbookIO.Origin | T, optionsArg?: T): Promise<IWorkbookIO.Origin | null>;
     /** @inheritdoc IWorkbookIO.writeAs */
     writeAs<T extends IWorkbookIO.WriteAsOptions = IWorkbookIO.WriteAsOptions>(workbook: IWorkbook, target: string | IWorkbookIO.Origin, options?: T): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * The one write path. `save` is whether the workbook moves to what is written and is marked
+     * clean (a save, a Save As), or stays where it is (an export).
+     *
+     * @internal
+     */
+    protected _write<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, target: string | IWorkbookIO.Origin, save: boolean, options?: T): Promise<IWorkbookIO.Origin | null>;
     /**
      * Strips a known file extension from a file name, returning the base name.
      *
@@ -83,6 +90,8 @@ export declare class DefaultWorkbookIO implements IWorkbookIO {
     protected _baseName(pathOrUrl: string | null | undefined): string | null;
     protected _writeArrayBuffer<T extends IWorkbookIO.WriteOptions = IWorkbookIO.WriteOptions>(workbook: IWorkbook, writeType: IWorkbookIO.WriteFormatType, options?: T): Promise<ArrayBufferLike>;
     protected _readArrayBuffer<T extends IWorkbookIO.ReadOptions = IWorkbookIO.ReadOptions>(arrayBuffer: ArrayBufferLike, format: IWorkbookIO.ReadFormatType, options?: T): Promise<IWorkbook>;
+    /** {@inheritDoc IWorkbookIO.isIWorkbookIO} */
+    get isIWorkbookIO(): true;
 }
 /**
  * A singleton instance of the default {@link IWorkbookIO} implementation.

package/types/src/io/WorkbookOrigin.d.ts

@@ -17,6 +17,10 @@ export interface WorkbookOriginOptions {
      * The last-known size of the source in bytes (stat-style), if known.
      */
     size?: number | null;
+    /**
+     * When the source was last modified, in milliseconds since the epoch (stat-style), if known.
+     */
+    lastModified?: number | null;
     /**
      * Whether the source can be written back to (a silent re-save).
      *
@@ -34,19 +38,20 @@ export interface WorkbookOriginOptions {
  * concrete "light virtual file handle" (see `IO-DESIGN.md`).
  *
  * @remarks
- * Mutable and observable: the IO/store layer holds the instance and calls {@link update} when the
- * source moves (a save that resolved a destination) or is renamed, firing `onChange` so holders —
- * including the workbook itself, whose `getName()`/`onNameChange` derive from this — propagate it.
+ * Names one file for its whole life. What is known about that file — its size, its encryption, its
+ * display label — can change in place ({@link update}, {@link setName}), firing `onChange` so
+ * holders — including the workbook, whose `getName()`/`onNameChange` derive from this — follow.
  * Source logic (paths, URLs, formats) lives here, in the IO layer, not in the workbook model.
  *
  * An **unbound** origin (`path: null`) belongs to an in-memory workbook with no destination yet; a
- * destination-resolving save fills it in place via {@link update}.
+ * save that resolves one moves the workbook to a new origin, leaving this one as it was.
  */
 export declare class WorkbookOrigin implements IWorkbookIO.Origin {
-    private _path;
+    private readonly _path;
     private _name;
     private _format;
     private _size;
+    private _lastModified;
     private _canWrite;
     private _encryption;
     /**
@@ -85,24 +90,28 @@ export declare class WorkbookOrigin implements IWorkbookIO.Origin {
     getPassword(): string | null;
     /** {@inheritDoc IWorkbookIO.Origin.getSize} */
     getSize(): number | null;
+    /** {@inheritDoc IWorkbookIO.Origin.getLastModified} */
+    getLastModified(): number | null;
     /** {@inheritDoc IWorkbookIO.Origin.canWrite} */
     canWrite(): boolean;
     /** {@inheritDoc IWorkbookIO.Origin.setName} */
     setName(name: string | null): void;
     /**
-     * Update one or more fields in place. Fires `onChange` if anything actually changed.
+     * Update what is known about the file in place. Fires `onChange` if anything actually changed.
      *
      * @remarks
-     * This is the **privileged mutation channel** (see `IO-DESIGN.md`): permitted callers are the
-     * backing store (rename/move, destination resolution), the IO layer (filling an unbound origin on
-     * a first destination-resolving save), and the document layer (Save As / rename). Never format
-     * handlers, never the model, never chrome.
+     * The **privileged mutation channel** (see `DESIGN-IO.md`) for the backing store and the IO layer:
+     * the written size, the encryption on disk, the format key a read resolved. Never format handlers,
+     * never the model, never chrome.
+     *
+     * There is no `path`: an origin names one file for its whole life. A save that resolves another
+     * destination mints a new origin for it (see `DESIGN-IO.md` §11).
      */
     update(next: {
-        path?: string | null;
         name?: string | null;
         format?: string | null;
         size?: number | null;
+        lastModified?: number | null;
         canWrite?: boolean;
         encryption?: string | null;
     }): this;

package/types/src/io/WorkbookOriginProvider.d.ts

@@ -0,0 +1,46 @@
+import { IListener } from '../listener';
+import { IWorkbookIO } from './IWorkbookIO';
+/**
+ * The provider currently supplying `origin`, or `null` when no open workbook lives in it.
+ *
+ * @remarks
+ * How the IO layer finds the workbook a save was for: it holds the origin it wrote from.
+ */
+export declare const getOriginProvider: (origin: IWorkbookIO.Origin) => WorkbookOriginProvider | null;
+/** The origins of every open workbook. */
+export declare const getOpenOrigins: () => IWorkbookIO.Origin[];
+/**
+ * Default {@link IWorkbookIO.OriginProvider}: holds the workbook's current origin and moves when
+ * told to.
+ *
+ * @remarks
+ * {@link setOrigin} is on this class, not the interface — the workbook only reads its origin. The
+ * IO layer moves it after a save that resolved a new destination.
+ *
+ * An origin is supplied by one provider at a time, so the origin a save wrote from identifies
+ * exactly one workbook. Supplying an origin another open provider already supplies throws.
+ */
+export declare class WorkbookOriginProvider implements IWorkbookIO.OriginProvider {
+    private _origin;
+    private _released;
+    private readonly _emitter;
+    constructor(origin: IWorkbookIO.Origin);
+    /** {@inheritDoc IWorkbookIO.OriginProvider.getOrigin} */
+    getOrigin(): IWorkbookIO.Origin;
+    /**
+     * Supplies `origin` from now on. Fires `onOriginChange` unless it is already the current one.
+     *
+     * @remarks
+     * Moves the workbook to another file; it writes nothing. The origin it replaces is left as it was
+     * — it still names its own file, and is free for another workbook.
+     */
+    setOrigin(origin: IWorkbookIO.Origin): void;
+    /**
+     * Stops supplying: the origin is free for another workbook. Called when the workbook closes.
+     */
+    release(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IWorkbookIO.OriginProvider.IListeners, options?: IListener.Options): IListener.Remove;
+    private static _assertFree;
+}
+//# sourceMappingURL=WorkbookOriginProvider.d.ts.map

package/types/src/io/_XmlFragment.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A reader over a captured markup fragment.
+ *
+ * @remarks
+ * Content the model does not hold structurally is kept as the source's markup and replayed on save
+ * (a shape, a chart part). This reads the few facts such markup can answer without a model behind
+ * it. It is a reader over a fragment, not an XML library: elements, attributes and character data,
+ * matched by LOCAL name — prefixes are the producer's choice (`xdr:sp`, `a:t` and `c:ser` are only
+ * Excel's). The markup was already parsed once, as part of a whole document, by the reader that
+ * captured it.
+ */
+/** One element of a parsed fragment. `name` is the local name. */
+export interface XmlElement {
+    name: string;
+    attrs: string;
+    children: (XmlElement | string)[];
+    /** Where the element's content starts in the source: just past its open tag. */
+    contentStart: number;
+    /** Where the element's content ends in the source: at its close tag. Equal to `contentStart` for an empty element. */
+    contentEnd: number;
+}
+export declare const decodeEntities: (text: string) => string;
+/** Character data as it has to be spelled inside an element. */
+export declare const encodeText: (text: string) => string;
+/** The fragment's root element, or `null` when there is none to read. */
+export declare const parseFragment: (xml: string) => XmlElement | null;
+export declare const getAttribute: (element: XmlElement, name: string) => string | null;
+export declare const childElements: (element: XmlElement) => XmlElement[];
+export declare const findChild: (element: XmlElement, name: string) => XmlElement | null;
+/** The element at the end of a path of local names, or `null` where the path breaks. */
+export declare const findPath: (element: XmlElement, ...names: string[]) => XmlElement | null;
+/** The element's own character data; what its child elements hold is not read. */
+export declare const readCharacters: (element: XmlElement) => string;
+/**
+ * The children to read in place of an `mc:AlternateContent`: ONE branch, never both.
+ *
+ * @remarks
+ * A producer states the same content once per consumer version, so a sweep over both branches
+ * reads every word twice. The fallback is the rendition for a reader that does not understand the
+ * choice's markup — which, for the markup that gets wrapped this way (an OMML equation), is this
+ * reader: the fallback carries the equation in its linear text form.
+ */
+export declare const alternateBranch: (element: XmlElement) => XmlElement[];
+/**
+ * The plain text of a DrawingML text body (`txBody`, `c:rich`): its paragraphs joined by a newline,
+ * blank ones trimmed from the ends.
+ */
+export declare const readTextBody: (body: XmlElement) => string;
+//# sourceMappingURL=_XmlFragment.d.ts.map

package/types/src/io/index.d.ts

@@ -1,3 +1,4 @@
+export * from './IEmbeddedPart';
 export * from './IWorkbookIO';
 export * from './WorkbookIO';
 export * from './WorkbookOrigin';

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

@@ -4,6 +4,7 @@
 export interface LicenseDetails {
     getLicensee(): string | null;
     getExpiration(): Date | null;
+    getRuntimes(): ('browser' | 'server')[];
     getDomains(): string[];
     getCpuCount(): number;
     getMemory(): number;

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

@@ -4,7 +4,10 @@ declare class LM {
     /**
      * Set the license key provided by SheetXL.
      * @remarks
-     * The license key can also be provided via a file named `sheetxl.lic` in the root of the web server.
+     * Without a call to this, the key is looked for where it runs:
+     * - In a browser, a file named `sheetxl.lic` served beside the page.
+     * - Outside a browser (Node, Bun, Deno, CI), the `SHEETXL_LICENSE_KEY` environment variable, then
+     *   the key saved by `sheetxl license activate`.
      *
      * @param licenseKey The license key as a string.
      * @param force If set to `true` will replace an existing key.

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

@@ -0,0 +1,38 @@
+/**
+ * Two-tier node fingerprint.
+ * - `stable`: hash of fields unlikely to change (arch, osType, platform, memoryGB).
+ *   Used for hard enforcement.
+ * - `full`: hash that also includes hostname.
+ *   Passes silently if stable matches but full diverges (hostname rename, container re-creation).
+ */
+export interface NodeFingerprint {
+    stable: string;
+    full: string;
+}
+export interface HostDetails {
+    cpus?: number;
+    memoryGB?: number;
+    protocol?: string | null;
+    domain?: string | null;
+    fingerprint?: NodeFingerprint;
+}
+/**
+ * What looking for a license key found, read where the runtime keeps it.
+ * - `found`: a key, and where it came from.
+ * - `absent`: the lookup completed and there is no key (`from` names where it looked).
+ * - `unreachable`: the lookup could not complete (offline, a server error); whether a key exists is
+ *   unknown, so this is never treated as an evaluation.
+ */
+export type LicenseKeySource = {
+    status: 'found';
+    key: string;
+    from: string;
+} | {
+    status: 'absent';
+    from: string;
+} | {
+    status: 'unreachable';
+    from: string;
+    reason: string;
+};
+//# sourceMappingURL=Types.d.ts.map

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

@@ -0,0 +1,22 @@
+/**
+ * A placeholder license key: the "evaluation" spellings a caller may pass to
+ * `LicenseManager.setLicenseKey` to run unlicensed on purpose (`eval`, `trial`, or the
+ * `visit …`/`email …` pointer text a starter template ships with). These select an evaluation
+ * license; they are never keys, so the persistent key store ignores them.
+ */
+export declare function isPlaceholderLicenseKey(key: string | null | undefined): boolean;
+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. */
+export declare function isEvalPeriodExpired(): boolean;
+/**
+ * The build as a person reads it: the stamped version, or `local` plus the local build time.
+ *
+ * @remarks
+ * A stamped version already names its commit, so the time adds nothing to it. A workspace build
+ * has no identity except when it was built, and to the minute, because several rebuilds a day
+ * all look alike at date resolution.
+ */
+export declare function getBuildLabel(): string;
+//# sourceMappingURL=_Utils.d.ts.map

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

@@ -0,0 +1,24 @@
+import { LicenseDetails } from './LicenseDetails';
+import { HostDetails } from './Types';
+export interface UnlicensedOptions {
+    /** The license type: `eval`, `invalid`, `unavailable`. */
+    type: string;
+    /** Where the (missing or unusable) key was looked for. */
+    keyFrom: string;
+    exceptions: readonly string[];
+    /** Whether the product runs without the watermark anyway (an evaluation on localhost). */
+    validFor: boolean;
+    isEval?: boolean;
+    licensee?: string | null;
+    developerCount?: number;
+}
+/**
+ * A license that is not a valid key: an evaluation, a key that is not a key, a key that could not
+ * be loaded. Each runtime decides which one it is running and on what terms.
+ */
+export declare const genUnlicensedDetails: (options: UnlicensedOptions) => LicenseDetails;
+/**
+ * The license a key grants on `host`. A key that does not decode is an `invalid` license.
+ */
+export declare const detailsForKey: (from: string, key: string, host: HostDetails, isDevEnv: boolean) => LicenseDetails;
+//# sourceMappingURL=details.d.ts.map