@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/sort/ISort.d.ts

@@ -0,0 +1,318 @@
+import { ScalarType, Scalar, IRange } from '@sheetxl/primitives';
+import { IStyle } from '../style';
+import { ICellRange } from '../cellRange';
+/**
+ * A stateful sort object that binds criteria to a specific index within an `ITable`.
+ *
+ * - Criteria (`ISort.Criteria`) – how to sort a single index (direction, collator, value vs color, etc.).
+ * - Options (`ISort.Options`) – a single sort specification: index plus criteria.
+ * - Levels (`ISort.RangeOptions.levels`) – an ordered list of options (primary → secondary → ...).
+ */
+export interface ISort {
+    /**
+     * Sorts this index using its current criteria.
+     *
+     * @param reverse
+     * If provided, temporarily overrides the `reverse` flag for this sort.
+     *
+     * @remarks
+     * - This method mutates the owning table/range by reordering rows/columns.
+     * - If `reverse` is `undefined`, the effective direction is:
+     *   `criteria.reverse ?? rangeDefaults.reverse ?? false`.
+     */
+    sort(reverse?: boolean): void;
+    /**
+     * Sets the sort criteria.
+     *
+     * @param criteria The sort criteria to set, or `null` to clear this field.
+     * @param append If `true`, keeps existing sort levels and adds/updates this field.
+     *               If `false` or omitted, this field becomes the only sort field.
+     */
+    setCriteria(criteria: ISort.Criteria | null, append?: boolean): void;
+    /**
+     * Gets the sort criteria.
+     *
+     * @returns The sort criteria or `null` if none is set.
+     */
+    getCriteria(): Readonly<ISort.Criteria> | null;
+    /**
+     * The field index within the sort range or table.
+     *
+     * @remarks
+     * - For row-major sorts, this is a column index.
+     * - For column-major sorts, this is a row index.
+     * - It is always relative to the sorted region, not the sheet.
+     */
+    getIndex(): number;
+    /**
+     * The level of the sort (0-based).
+     *
+     * @remarks
+     * This is based on the order of the sort fields.
+     * If the sort has no criteria the level will be `-1`.
+     */
+    getLevel(): number;
+    /**
+     * Gets the range being sorted.
+     */
+    getRange(): ICellRange;
+    /**
+     * Reapplies the sort.
+     */
+    apply(): void;
+    /**
+     * Clears the sort criteria and removes from sort levels.
+     */
+    delete(): void;
+}
+/**
+ * Types used for sorting.
+ */
+export declare namespace ISort {
+    /**
+     * Default collators for sorting.
+     */
+    const SortOn: {
+        readonly Value: "value";
+        readonly FillColor: "fillColor";
+        readonly FontColor: "fontColor";
+        readonly Icon: "icon";
+    };
+    type SortOn = typeof SortOn[keyof typeof SortOn];
+    /**
+     * Function used to compare two Scalar values.
+     *
+     * @param options `defaultOptions` with any user overrides.
+     *
+     * @remarks
+     * Equal values and `null` values are presorted and  do not need to be handled in the collator implementation.
+     */
+    type CollatorFn<T = Scalar> = (a: T, b: T, options?: any) => number;
+    /**
+     * A collator for a Scalar of a specific type.
+     *
+     * @remarks
+     * Sorting supports sorting across multiple data types. Each collator
+     * will have a type.
+     */
+    interface Collator<T = Scalar> {
+        /**
+         * The scalar type this collator can handle.
+         *
+         * @remarks
+         * - For built-in types, use a `ScalarType`.
+         * - For rich data, use a string key that represents the subtype of `ScalarType.RichData`.
+         */
+        type: ScalarType | string;
+        /**
+         * Used for sorting.
+         *
+         * @remarks
+         * - If a **string** is provided, it is treated as an identifier:
+         *   - It may refer to a built-in collator.
+         *   - Or to a user-defined collator implemented as a script function.
+         *   - The engine will resolve this id at runtime.
+         * - If a **function** is provided, it is used directly as the comparator
+         *   in the current environment. This is not serialized and may not be
+         *   available in worker/sandboxed runtimes.
+         */
+        compare: string | ISort.CollatorFn<T>;
+        /**
+         * The options passed to the collator.
+         *
+         * @remarks
+         * These are merged with any per-call options before the collator is invoked.
+         */
+        defaultOptions?: Intl.CollatorOptions;
+    }
+    interface Criteria {
+        /**
+         * Determines whether to reverse the default sort order.
+         *
+         * @defaultValue false - (sorts in the default order, typically ascending)
+         *
+         * @remarks
+         * The `reverse` flag flips the sort order. When set to `true`, the sort will
+         * be performed in reverse order compared to the default (which is usually ascending).
+         *
+         * This flag is data-type agnostic, meaning it will reverse the default order
+         * regardless of whether the data is numeric, alphabetic, or complex (e.g., booleans, lists).
+         *
+         * Example usage:
+         * ```ts
+         * const criteria: ISort.Criteria = {
+         *   reverse: true, // Sorts in descending order (for numbers/alphabetic)
+         * };
+         * ```
+         */
+        reverse?: boolean;
+        /**
+         * Additional options for sorting.
+         *
+         * @remarks
+         * - Excel has a `matchCase` flag but we use `Intl.CollatorOptions`.
+         * - Excel has `Normal | TextAsNumber` but we use `Intl.CollatorOptions`.
+         */
+        collatorOptions?: Record<ScalarType, Intl.CollatorOptions> | Intl.CollatorOptions;
+        /**
+         * Only value is currently supported
+         */
+        sortOn?: SortOn;
+        /**
+         * Used with sortOn === Icon
+         * @remarks
+         * **PLACEHOLDER** - This is a placeholder for future use.
+         */
+        iconSet?: IStyle.IconSet;
+        /**
+         * Used with sortOn === Icon
+         * @remarks
+         * **PLACEHOLDER** - This is a placeholder for future use.
+         */
+        iconId?: number;
+        /**
+         * Used with sortOn === cellColor or fontColor
+         *
+         * @remarks
+         * **PLACEHOLDER** - This is a placeholder for future use.
+         */
+        dxfId?: any;
+        /**
+         * Sort by a custom list.
+         * @remarks
+         * **PLACEHOLDER** - This is a placeholder for future use.
+         */
+        customList?: string;
+    }
+    /**
+     * Sort settings for a single index.
+     */
+    interface Options {
+        /**
+         * The index to sort on.
+         *
+         * @remarks
+         * Relative to the sort range or table.
+         */
+        index?: number;
+        /**
+         * The sort criteria.
+         *
+         * @remarks
+         * * If `null` is provided then the sort entry is removed.
+         * * If not provided then a default sort will be added to the levels.
+         */
+        criteria?: ISort.Criteria | null;
+    }
+    /**
+     * Precomputed context for a sort operation.
+     *
+     * @remarks
+     * Represents the default sort configuration that will be used
+     * unless the caller overrides parts of it.
+     */
+    interface DefaultSortCriteria {
+        /**
+         * The full coordinates that will be sorted, including any header rows/columns.
+         */
+        coords: IRange.Coords;
+        /**
+         * Options to pass to sort operation.
+         */
+        options: ISort.RangeOptions;
+        /**
+         * Header labels by field offset, if headers are detected.
+         *
+         * @remarks
+         * The key is the 0-based field offset; the value is the header text.
+         * If no headers are found, this will be empty.
+         */
+        headers: Map<number, string>;
+        /**
+         * The coordinates to actually sort, excluding any headers.
+         */
+        sortCoords: IRange.Coords;
+    }
+    /**
+     * Options for sorting across multiple (rows or columns).
+     *
+     * @remarks
+     * This include axis, hasHeader, and includeHidden.
+     */
+    interface RangeOptions {
+        /**
+         * Sort levels in priority order.
+         *
+         * @remarks
+         * Each entry specifies an index plus its criteria.
+         * The array index is the sort level:
+         * - 0 = primary
+         * - 1 = secondary, etc.
+         */
+        sorts?: ISort.Options[];
+        /**
+         * The default reverse for to use for sorting.
+         *
+         * @remarks
+         * {@link ISort.Criteria.reverse}
+         */
+        reverse?: boolean;
+        /**
+         * The default collator options to use for sorting.
+         *
+         * @remarks
+         * {@link ISort.Criteria.collatorOptions}
+         */
+        collatorOptions?: Record<ScalarType, Intl.CollatorOptions> | Intl.CollatorOptions;
+        /**
+         * Indicate if the sort has a header. If the sort has a head this will be ignored.
+         *
+         * @defaultValue Use data to make a 'guess'
+         */
+        hasHeader?: boolean;
+        /**
+         * Indicate the axis to sort.
+         *
+         * @defaultValue IRange.Axis.Row
+         */
+        axis?: IRange.Axis;
+        /**
+         * Determine if sort should include values that are hidden.
+         *
+         * @defaultValue false
+         */
+        includeHidden?: boolean;
+        /**
+         * Override the collators used.
+         *
+         * @defaultValue Sort.DefaultCollators
+         */
+        collators?: readonly ISort.Collator[];
+    }
+    /**
+     * Minimal JSON representation of the sort configuration.
+     *
+     * @remarks
+     * This is intended for serialization and round-tripping.
+     * It omits non-essential runtime options (collators, defaults, etc.).
+     */
+    type JSON = {
+        /**
+         * Sort fields, in priority order.
+         */
+        sorts?: ISort.Options[];
+        /**
+         * Indicate the axis to sort.
+         *
+         * @defaultValue IRange.Axis.Row
+         */
+        axis?: IRange.Axis;
+        /**
+         * Determine if sort should include values that are hidden.
+         *
+         * @defaultValue false
+         */
+        includeHidden?: boolean;
+    };
+}
+//# sourceMappingURL=ISort.d.ts.map

package/types/src/sort/Sort.d.ts

@@ -0,0 +1,48 @@
+import { FormulaError, IRichData } from '@sheetxl/primitives';
+import { ISort } from './ISort';
+/**
+ * Contains types for {@link ISort}.
+ */
+export declare namespace Sort {
+    const CaseInsensitiveOptions: Intl.CollatorOptions;
+    const CaseSensitiveOptions: Intl.CollatorOptions;
+    /**
+     * For comparing `number` `ScalarTypes`.
+     *
+     * @remarks
+     * This will include dates.
+     */
+    const NumberCollator: ISort.Collator<number>;
+    /**
+     * For comparing `string` `ScalarTypes`.
+     */
+    const StringCollator: ISort.Collator<string>;
+    /**
+     * For comparing `error` cell types.
+     */
+    const ErrorCollator: ISort.Collator<FormulaError.Known>;
+    /**
+     * For comparing `null` cell types.
+     */
+    const NullCollator: ISort.Collator<null>;
+    /**
+     * For comparing `RichData` `ScalarTypes`.
+     *
+     * @remarks
+     * **PARTIAL IMPLEMENTATION**
+     */
+    const RichDataCollator: ISort.Collator<IRichData>;
+    /**
+     * For comparing `boolean` cell types.
+     */
+    const BooleanCollator: ISort.Collator<boolean>;
+    /**
+     * Default {@link ISort.RangeOptions}.
+     */
+    const DefaultRangeOptions: ISort.RangeOptions;
+    /**
+     * The default sorting for mixed ScalarTypes.
+     */
+    const DefaultCollators: readonly ISort.Collator<any>[];
+}
+//# sourceMappingURL=Sort.d.ts.map

package/types/src/sort/_SortUtils.d.ts

@@ -0,0 +1,12 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { ISort } from './ISort';
+/**
+ * Create fully formed sort levels from partial options.
+ * The are duplicates so say to mutate or store.
+ *
+ * 1. sets index
+ * 2. sets criteria. (can be null)
+ */
+export declare function enrichSortLevels(coords: Readonly<IRange.Coords>, options?: boolean | ISort.Options[] | ISort.RangeOptions & ITransaction.OperationOptions, headerWidth?: number, headerHeight?: number): ISort.RangeOptions & ITransaction.OperationOptions;
+//# sourceMappingURL=_SortUtils.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './ISort';
+export * from './Sort';
+//# sourceMappingURL=index.d.ts.map

package/types/src/string/IStringCollection.d.ts

@@ -0,0 +1,50 @@
+import { ICollection } from '../type';
+/**
+ * Contains a collection of interned strings.
+ */
+export interface IStringCollection extends ICollection<string>, ICollection.IPersistable {
+    /**
+     * Add a string to the collection.
+     *
+     * @param shared A string
+     *
+     * @remarks
+     * Resources are not removed from the the collection. They are autoGCed when there are no references.
+     */
+    add(shared: string): number;
+    /**
+     * Add multiple string to the collection.
+     *
+     * @param shared An array of strings
+     * @param conflateDuplicates If the same string is in the list it will be conflated. Default value `false`.
+     *
+     * @remarks
+     * There are instances where Excel may have duplicate strings so by default this is false.
+     */
+    addMultiple(shared: string[], conflateDuplicates?: boolean): void;
+    /**
+     * Returns the string for the given id, or `null` if not found.
+     *
+     * @param id The id
+     */
+    getById(id: number): string | null;
+    /** {@inheritDoc ICollection.IPersistScope} */
+    beginPersist(): ICollection.IPersistScope<IStringCollection.JSON>;
+}
+/**
+ * {@inheritDoc IStringCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IStringCollection}
+ */
+export declare namespace IStringCollection {
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        id?: number;
+    }
+    /**
+     * Alias for persist type of `string`.
+     */
+    type JSON = string;
+}
+//# sourceMappingURL=IStringCollection.d.ts.map

package/types/src/string/StringCollection.d.ts

@@ -0,0 +1,26 @@
+import { ICollection } from '../type';
+import { IStringCollection } from './IStringCollection';
+export declare class StringCollection implements IStringCollection {
+    private _persistOpen;
+    private _stringsByText;
+    private _stringsById;
+    private _nextId;
+    private _lastReadId;
+    private _lastReadValue;
+    constructor();
+    /** {@inheritDoc IStringCollection.addMultiple} */
+    addMultiple(shared: string[], conflateDuplicates?: boolean): void;
+    /** {@inheritDoc IStringCollection.add} */
+    add(shared: string): number;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<string>;
+    /** {@inheritDoc IStringCollection.getItems} */
+    getItems(options?: IStringCollection.GetItemsOptions): string[];
+    /** {@inheritDoc IStringCollection.getById} */
+    getById(id: number): string | null;
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc ICollection.IPersistable.beginPersist} */
+    beginPersist(): ICollection.IPersistScope<IStringCollection.JSON>;
+}
+//# sourceMappingURL=StringCollection.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './IStringCollection';
+export * from './StringCollection';
+//# sourceMappingURL=index.d.ts.map