@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/protection/PasswordHasher.d.ts

@@ -0,0 +1,35 @@
+export interface SaltAndHash {
+    salt: string;
+    hash: string;
+}
+export declare class PasswordHasher {
+    static DefaultAlgo: string;
+    static DefaultSpinCount: number;
+    /**
+     * Create a salt and hash from a password.
+     *
+     * @param password The password.
+     * @param algorithm The hash algorithm. Default value `SHA-512`.
+     * @param spinCount The spin count. Default value `100000`.
+     *
+     * @returns The encryption key as a base64 string.
+     */
+    static generateSaltAndHash(password: string, algorithm?: string, spinCount?: number): Promise<SaltAndHash | null>;
+    /**
+     * Verify a password again a hash a salt and hash from a password.
+     *
+     * @param password The encrypted password.
+     * @param salt The salt returned when generating the hash
+     * @param hash The hash used to encrypt the password.
+     * @param algorithm The hash algorithm. Default value `SHA-512`.
+     * @param spinCount The spin count. Default value `100000`.
+     *
+     * @returns The encryption key as a base64 string.
+     */
+    static verifyPassword(password: string, saltAndHash: SaltAndHash, algorithm?: string, spinCount?: number): Promise<boolean>;
+    /**
+     * For unit testing against existing salt and hash keys.
+     */
+    protected static _convertPasswordToHash(password: string, salt: string, algorithm: string, spinCount: number): Promise<string>;
+}
+//# sourceMappingURL=PasswordHasher.d.ts.map

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

@@ -0,0 +1,6 @@
+/**
+ * Used for OOXML import
+ * @hidden
+ */
+export * from './IProtection';
+//# sourceMappingURL=index.d.ts.map

package/types/src/resource/IResource.d.ts

@@ -0,0 +1,98 @@
+import { JSONSerializableAsync } from '@sheetxl/utils';
+/**
+ * A resource is an item referenced elsewhere with the application.
+ * This will track when a resource is no longer being used and can be removed.
+ */
+export interface IResource extends JSONSerializableAsync<IResource.JSON> {
+    /**
+     * The mimetype of the resource.
+     */
+    getType(): Promise<IResource.Type>;
+    /**
+     * An optional name for the resource.
+     */
+    getName(): string | null;
+    /**
+     * For saving to json resources.
+     */
+    toJSONAsync(): Promise<IResource.JSON>;
+    /**
+     * Returns the resource as a Promise to array buffer.
+     */
+    toBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Returns the resource as a uri if this is external.
+     */
+    getExternalURI(): Promise<string | null>;
+    /**
+     * Add a reference to the resource.
+     *
+     * @param ref The object to strongly hold the resource.
+     *
+     * @deprecated References are now strongly held by the resource collection.
+     */
+    addReference(ref: any): void;
+    /**
+     * Delete a reference to the resource.
+     *
+     * @param ref The object that held the resource.
+     *
+     * @deprecated References are now strongly held by the resource collection.
+     */
+    deleteReference(ref: any): void;
+    /**
+     * This does not follow the standard listener pattern and is only called once.
+     *
+     * @param listener The listener to call when the resource is unloaded.
+     */
+    addUnloadListener(listener: IResource.IUnloadListener): void;
+    /**
+     * `true` if the resource if all references have been deleted.
+     */
+    isClosed(): boolean;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIResource: true;
+}
+/**
+ * {@inheritDoc IResource}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IResource}
+ */
+export declare namespace IResource {
+    interface IUnloadListener {
+        onUnload: (ref: IResource) => void;
+    }
+    /**
+     * A type for the resource.
+     */
+    interface Type {
+        /**
+         * The mime type of the resource.
+         */
+        mime: string;
+        /**
+         * The file extension of the resource.
+         */
+        ext?: string;
+    }
+    interface JSON {
+        /**
+         * If the resource is embedded, this will be a base64 encoded string of the data.
+         */
+        base64?: string;
+        /**
+         * If the resource is external, this will be the uri.
+         */
+        uri?: string;
+        /**
+         * The name of the resource.
+         * This is optional but if provided then resource lookup will use this as a cache key.
+         */
+        name?: string;
+    }
+}
+//# sourceMappingURL=IResource.d.ts.map

package/types/src/resource/IResourceCollection.d.ts

@@ -0,0 +1,96 @@
+import { JSONSerializableAsync, FetchArgs, MaybePromise, OneOf } from '@sheetxl/utils';
+import { ICollection } from '../type';
+import { IResource } from './IResource';
+/**
+ * Collections of {@link IResource}.
+ */
+export interface IResourceCollection extends ICollection<IResource> {
+    /**
+     * Add a resource to a collection with an initial reference.
+     *
+     * @param resource
+     * @remarks
+     * Resources are not removed from the the collection. They are autoGCed when there are no references.
+     */
+    add(resource: string | IResource | IResourceCollection.AddOptions): IResource;
+    /**
+     * Returns a list of all resources in the collection.
+     *
+     * @param options
+     */
+    getItems(options?: ICollection.GetItemsOptions): IResource[];
+    /**
+     * Used for saving resource. Returns a visitor that will allow for a toJSON that
+     * will only save the resource that were accessed within the persist scope.
+     */
+    beginPersist(): IResourceCollection.IPersistScope<IResource.JSON>;
+}
+/**
+ * {@inheritDoc IResourceCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IResourceCollection}
+ */
+export declare namespace IResourceCollection {
+    /**
+     * When adding a shared source there are a number of ways to create it
+     * Either from a base64 string, a buffer, a fetch, or a custom resolve function.
+     */
+    interface AddOptions {
+        /**
+         * An encoding for the resource. One and only of these should be provided
+         */
+        source: MaybePromise<IResourceCollection.Source> | (() => MaybePromise<IResourceCollection.Source>);
+        /**
+         * The name of the resource.
+         * This is optional and purely for human consumption and is not used by the system.
+         */
+        name?: string;
+    }
+    /**
+     * A type that represents the various ways to provide a resource source.
+     * One and only one of the options should be provided.
+     */
+    type SourceType = {
+        base64: string;
+        buffer: ArrayBuffer;
+        file: File;
+        fetch: string | FetchArgs;
+        /**
+         * If provided, this function will be called to resolve the resource.
+         * This behaves exactly like fetch but does not internalize the results
+         */
+        external: string | FetchArgs;
+    };
+    /**
+     * A type that represents a resource source that can be one of several types.
+     */
+    type Source = OneOf<SourceType>;
+    interface IPersistScope<J extends IResource.JSON> {
+        /**
+         * For a resource this will return a number that can be used to reference the resource in the persisted json.
+         * @param resource
+         */
+        toResourceId(resource: JSONSerializableAsync<J>): number | null;
+        /**
+         * For a given resourceId this will return the resource.
+         * @param resourceId
+         */
+        fromResourceId(resourceId: number): JSONSerializableAsync<J> | null;
+        /**
+         * Called when done persisting.
+         */
+        endPersist(): void;
+        /**
+         * Loads the json.
+         * @param json
+         */
+        fromJSON(json: J[]): void;
+        /**
+         * This can be called multiple times.
+         */
+        toJSONAsync(): Promise<J[]>;
+    }
+}
+//# sourceMappingURL=IResourceCollection.d.ts.map

package/types/src/resource/Resource.d.ts

@@ -0,0 +1,39 @@
+import { IResource } from './IResource';
+import { IResourceCollection } from './IResourceCollection';
+export declare class Resource implements IResource {
+    private _name;
+    private _refs;
+    private _listeners;
+    private _isClosed;
+    private _arrayBuffer;
+    private _type;
+    private _source;
+    private _sourceResolved;
+    private _externalURI;
+    constructor(options: IResourceCollection.AddOptions);
+    /** @internal */
+    protected _resolveSource(): Promise<IResourceCollection.Source>;
+    /** @internal */
+    protected _resolveArrayBuffer(): Promise<ArrayBuffer>;
+    /** {@inheritDoc IResource.getName} */
+    getName(): string | null;
+    /** {@inheritDoc IResource.toJSONAsync} */
+    toJSONAsync(): Promise<IResource.JSON>;
+    /** {@inheritDoc IResource.toBuffer} */
+    toBuffer(): Promise<ArrayBuffer>;
+    /** {@inheritDoc IResource.getType} */
+    getType(): Promise<IResource.Type>;
+    /** {@inheritDoc IResource.getExternalURI} */
+    getExternalURI(): Promise<string | null>;
+    /** {@inheritDoc IResource.addReference} */
+    addReference(ref: any): void;
+    /** {@inheritDoc IResource.deleteReference} */
+    deleteReference(ref: any): void;
+    /** {@inheritDoc IResource.addUnloadListener} */
+    addUnloadListener(listener: IResource.IUnloadListener): void;
+    /** {@inheritDoc IResource.isIResource} */
+    get isIResource(): true;
+    /** {@inheritDoc IResource.isClosed} */
+    isClosed(): boolean;
+}
+//# sourceMappingURL=Resource.d.ts.map

package/types/src/resource/ResourceCollection.d.ts

@@ -0,0 +1,19 @@
+import { ICollection } from '../type';
+import { IResource } from './IResource';
+import { IResourceCollection } from './IResourceCollection';
+export declare class ResourceCollection implements IResourceCollection {
+    private _resources;
+    private _persistOpen;
+    constructor();
+    /** {@inheritDoc IResourceCollection.add} */
+    add(res: string | IResource | IResourceCollection.AddOptions): IResource;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<IResource>;
+    /** {@inheritDoc IResourceCollection.getItems} */
+    getItems(options?: ICollection.GetItemsOptions): IResource[];
+    /** {@inheritDoc IResourceCollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IResourceCollection.beginPersist} */
+    beginPersist(): IResourceCollection.IPersistScope<IResource.JSON>;
+}
+//# sourceMappingURL=ResourceCollection.d.ts.map

package/types/src/resource/_ResourceMessages.d.ts

@@ -0,0 +1,4 @@
+export declare const ERROR_DUPLICATE_DATA_VALUES: string;
+export declare const ERROR_NO_DATA_VALUES: string;
+export declare const CLOSED_MODEL: string;
+//# sourceMappingURL=_ResourceMessages.d.ts.map

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

@@ -0,0 +1,5 @@
+export * from './IResource';
+export * from './Resource';
+export * from './IResourceCollection';
+export * from './ResourceCollection';
+//# sourceMappingURL=index.d.ts.map

package/types/src/resource/resourceKinds.d.ts

@@ -0,0 +1,23 @@
+import { ResourceKindDefinition } from '@sheetxl/utils';
+/**
+ * The resource kinds SheetXL defines: **locales** and **fonts**.
+ *
+ * Declared here rather than in `@sheetxl/utils` because utils owns the resource *machinery*, not any
+ * particular kind — it should no more know what a locale directory contains than what a font is. The
+ * SDK is the lowest layer that is a product rather than generic utility, and it is also what the CLI
+ * depends on, so declaring them here is what lets `sheetxl resources add` understand both.
+ *
+ * Exported as DATA rather than as a self-registering side-effect module, for two reasons:
+ *  - the only import is a type (erased), so nothing is pulled into any bundle that touches this file;
+ *  - build tooling loads it as source by relative path, where a package-specifier import of another
+ *    workspace package resolves as native ESM and cannot follow extensionless TS imports.
+ *
+ * A host applies it with `registerResourceKinds(SHEETXL_RESOURCE_KINDS)`. `@sheetxl/utils-react` adds
+ * `.cmd.json` to the `locales` kind separately, because command chrome is its format, not this one's.
+ */
+/** The locale namespace: message catalogs, and (from utils-react) command catalogs. */
+export declare const LOCALES_KIND = "locales";
+/** The font namespace. */
+export declare const FONTS_KIND = "fonts";
+export declare const SHEETXL_RESOURCE_KINDS: readonly ResourceKindDefinition[];
+//# sourceMappingURL=resourceKinds.d.ts.map

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

@@ -0,0 +1 @@
+//# sourceMappingURL=index.d.ts.map

package/types/src/scripting/FunctionCollection.d.ts

@@ -0,0 +1,88 @@
+import { IFunction, IFormulaContext } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICollection } from '../type';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { IFunctionCollection } from './IFunctionCollection';
+import { FunctionMatch } from './_FunctionIndex';
+/**
+ * Implementation for `IFunctionCollection`.
+ */
+export declare class FunctionCollection implements IFunctionCollection {
+    protected _emitter: ListenerEmitter<this, IFunctionCollection.IListeners>;
+    private _options;
+    private _readonly;
+    private _transactions;
+    private _stateId;
+    private _transactionsRemoveListener;
+    private _closed;
+    /**
+     * The descriptor index behind the metadata searches. Built on first use and dropped whenever the
+     * collection's contents change — see {@link FunctionIndex}.
+     */
+    private _index;
+    constructor(options: ConstructorOptions);
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<IFunction>;
+    /** {@inheritDoc IFunctionCollection.getItems} */
+    getItems(options?: ICollection.GetItemsOptions): IFunction[];
+    /** {@inheritDoc IFunctionCollection.getByName} */
+    getByName(name: string, options?: IFunctionCollection.GetByNameOptions): IFunction | null;
+    /** {@inheritDoc IFunctionCollection.search} */
+    search(options?: IFunctionCollection.SearchOptions): Promise<IFunction[]>;
+    /**
+     * {@link search}, keeping each hit's relevance score.
+     *
+     * @remarks
+     * Not part of {@link IFunctionCollection}: it exists so a caller merging SEVERAL collections
+     * ({@link IScript.searchFunctions} — built-ins plus every module) can rank the union on one
+     * scale instead of concatenating separately-ranked lists.
+     */
+    searchScored(options?: IFunctionCollection.SearchOptions): Promise<FunctionMatch[]>;
+    /** {@inheritDoc IFunctionCollection.getCategories} */
+    getCategories(options?: IFunctionCollection.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IFunctionCollection.validateName} */
+    validateName(named: string): void;
+    _validateName(name: string, ignoreExisting?: boolean): void;
+    /** {@inheritDoc IFunctionCollection.add} */
+    add(option: string | IFunction | IFunctionCollection.AddOptions): Promise<IFunction>;
+    /**
+     * Compiles TypeScript source into runnable functions and registers each in this collection.
+     * Returns the first (primary) function.
+     */
+    private _addFromSource;
+    /**
+     * Registers a single pre-built function (or AddOptions) into this collection, rebinding it to this
+     * collection's context. Preserves the macro vs calculation function type.
+     */
+    private _addFunction;
+    /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
+    beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    private _getState;
+    private _beginCommit;
+    private _updateState;
+    protected _initState(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IFunctionCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    isClosed(): boolean;
+    close(): void;
+    get isFunctionCollection(): true;
+}
+export interface ConstructorOptions {
+    /**
+     * A transaction store that can be used to undo/redo changes to the names.
+     */
+    transactions?: ITransaction.IStore | null;
+    context?: IFormulaContext;
+    readonlyFunctions?: ReadonlyMap<string, IFunction>;
+    /**
+     * Mints an evaluation context bound to a sheet, for `getByName(name, { sheet })`'s vended
+     * instances (functions callable as a public API outside the calculation graph). Wired by the
+     * calculation layer (`CalculationContext._createScoped`); layering keeps the type opaque here.
+     * Returns null for an unknown sheet.
+     */
+    createScopedContext?: (sheet: string) => IFormulaContext | null;
+}
+//# sourceMappingURL=FunctionCollection.d.ts.map

package/types/src/scripting/IFunctionCollection.d.ts

@@ -0,0 +1,208 @@
+import { IFunction } from '@sheetxl/primitives';
+import { ICollection } from '../type';
+import { IListener } from '../listener';
+/**
+ * Collections of {@link IFunction}.
+ */
+export interface IFunctionCollection extends ICollection<IFunction> {
+    /**
+     * Add a custom function to the collection.
+     *
+     * @param option Either TypeScript source, a pre-built {@link IFunction},
+     * or {@link IFunctionCollection.AddOptions}.
+     *
+     * @returns The registered function. When source is supplied and defines multiple functions, all
+     * are registered and the first (primary) one is returned.
+     */
+    add(option: string | IFunction | IFunctionCollection.AddOptions): Promise<IFunction>;
+    /**
+     * Returns functions that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link IFunctionCollection.SearchOptions}
+     *
+     * @remarks
+     * ### Ordering
+     * A search that reads DESCRIPTORS ({@link SearchOptions.text} / {@link SearchOptions.category},
+     * see below) returns results ordered — by relevance when there is `text`, alphabetically by
+     * canonical name otherwise. Every other search returns them in registration order.
+     *
+     * With `text`, relevance is: an exact name, then a name prefix, then a name substring, then the
+     * same three for the LOCALIZED name (each one tier behind its canonical counterpart), and finally
+     * a summary substring. Matching is case-insensitive "contains" — never fuzzy.
+     *
+     * ### Cost
+     * `name`- and `type`-only searches are a cheap scan. `text`, `category` and an explicit
+     * {@link SearchOptions.includeDeprecated} read each function's {@link IFunction.IDescriptor},
+     * which loads (once, lazily, per language) the descriptor chunk of every module — pennies for a
+     * search box, but not something to put on a hot path.
+     */
+    search(options?: IFunctionCollection.SearchOptions): Promise<IFunction[]>;
+    /**
+     * The categories the collection's functions declare, each with how many functions carry it.
+     *
+     * @param options {@link IFunctionCollection.GetCategoryOptions}
+     *
+     * @returns The categories, ordered by name. Never contains an empty category — a category exists
+     * because a function is in it.
+     *
+     * @remarks
+     * The category is a display string owned by the descriptor (`Math & Trig`, `Date & Time`, …), so
+     * this is a descriptor-reading call with the same lazy cost as a `text` search — and, being
+     * per-language, it re-derives when the language changes. It exists so a function picker can build
+     * its category list from what is actually registered (custom functions included) rather than from
+     * a hard-coded table that silently drifts.
+     */
+    getCategories(options?: IFunctionCollection.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
+    /**
+     * Convenience method for filter by name.
+     * This is functionally equivalent to getItems({ name });
+     *
+     * @param name The name to search for This is case insensitive.
+     * @param options {@link IFunctionCollection.GetByNameOptions}
+     *
+     * @remarks
+     * With `options.sheet`, returns a NEW instance bound to that sheet, for calling the function
+     * as a regular API outside the calculation graph — reference arguments and address strings
+     * resolve against the bound sheet with no evaluation current, and the instance is safe to
+     * hold across awaits. Without options, the shared registry instance is returned (the one the
+     * engine evaluates with); its reference resolution requires an active evaluation.
+     */
+    getByName(name: string, options?: IFunctionCollection.GetByNameOptions): IFunction | null;
+}
+/**
+ * {@inheritDoc IFunctionCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunctionCollection}
+ */
+export declare namespace IFunctionCollection {
+    /**
+     * Options for {@link IFunctionCollection.getByName}.
+     */
+    interface GetByNameOptions {
+        /**
+         * A sheet name to bind the returned function to. Vends a NEW instance whose evaluation
+         * context resolves references against this sheet even when no calculation is running —
+         * the public-API calling convention. Throws for an unknown sheet or a function that
+         * cannot be scoped (macros).
+         */
+        sheet?: string;
+    }
+    /**
+     * Options for searching a function in the collection.
+     */
+    interface SearchOptions {
+        /**
+         * Search with the given name. This is case insensitive.
+         */
+        name?: string;
+        /**
+         * Search all function descriptors for the given text. This is case insensitive.
+         *
+         * @remarks
+         * If this is specified this will also search the name.
+         */
+        text?: string;
+        /**
+         * Search with the given name. This is case insensitive.
+         */
+        category?: string;
+        type?: string;
+        /**
+         * Include functions their descriptor marks deprecated (or hidden).
+         *
+         * @defaultValue `false` — but only where it can be read; see the remarks.
+         *
+         * @remarks
+         * Deprecation lives in the descriptor ({@link IFunction.IDescriptor.isDeprecated}), so honoring
+         * this means loading descriptors. To keep a `name`/`type` lookup free, the filter applies only
+         * when the search is already reading them — with {@link text} or {@link category}, or when this
+         * option is passed EXPLICITLY (either value forces the read).
+         */
+        includeDeprecated?: boolean;
+        /**
+         * Return at most this many functions.
+         *
+         * @remarks
+         * Applied AFTER ordering, so a limited search is the top N by relevance — not an arbitrary N.
+         * A search box wanting "the best 50 of 400" should use this rather than slicing the result, so
+         * the caller never pays to materialize the rest.
+         */
+        limit?: number;
+    }
+    /**
+     * Options for {@link IFunctionCollection.getCategories}.
+     */
+    interface GetCategoryOptions {
+        /**
+         * Count only functions of this type (`'formula'`, `'macro'`, `'autoRun'`).
+         *
+         * @defaultValue every type.
+         */
+        type?: string;
+        /**
+         * Count functions their descriptor marks deprecated (or hidden).
+         *
+         * @defaultValue `false`
+         */
+        includeDeprecated?: boolean;
+    }
+    /**
+     * One category and its population, as returned by {@link IFunctionCollection.getCategories}.
+     */
+    interface Category {
+        /**
+         * The category as the descriptor spells it — `Math & Trig`, `Date & Time`, `Text`, …
+         *
+         * @remarks
+         * This is the IDENTITY (what {@link SearchOptions.category} matches, case-insensitively) and
+         * today it is also the display string. Localizing the label is a presentation concern: a picker
+         * maps the categories it knows to its own translated label + icon and falls back to this text
+         * for one it does not (a custom function's category, most likely).
+         */
+        name: string;
+        /** How many functions are in it, after {@link GetCategoryOptions} filtering. */
+        count: number;
+    }
+    interface Events {
+        /**
+         * Called when the collection changes.
+         *
+         * @remarks
+         * This is not used to capture individual item changes.
+         */
+        onCollectionChange?(source: IFunctionCollection): void;
+        /**
+         * Transaction items have a close event.
+         */
+        onClose?(source: IFunctionCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IFunctionCollection, IFunctionCollection.Events> {
+    }
+    /**
+     * Add a custom function.
+     */
+    interface AddOptions {
+        /**
+         * Required.
+         *
+         * @param args
+         * @returns the value of the function.
+         */
+        execute: (args: any[]) => any;
+        /**
+         * Required.
+         */
+        declaration: IFunction.DeclarationJSON;
+        /**
+         * Configuration for UI descriptor.
+         * @param locale
+         * @returns
+         */
+        descriptor?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>);
+    }
+}
+//# sourceMappingURL=IFunctionCollection.d.ts.map