@xh/hoist 82.0.1 → 82.0.3

package/build/types/data/Store.d.ts

@@ -0,0 +1,424 @@
+import type { GridFilterBindTarget } from '@xh/hoist/cmp/grid';
+import { HoistBase, PlainObject, Some } from '@xh/hoist/core';
+import { Field, FieldSpec, Filter, FilterBindTarget, FilterLike, FilterValueSource, StoreRecord, StoreRecordId, StoreRecordOrId, StoreValidationMessagesMap, StoreValidationResultsMap, ValidationResult } from '@xh/hoist/data';
+import { StoreValidator } from '@xh/hoist/data/impl/StoreValidator';
+import { RecordSet } from './impl/RecordSet';
+export interface StoreConfig {
+    /** Field names, configs, or instances. */
+    fields?: Array<string | FieldSpec | Field>;
+    /**
+     * Default configs applied to `Field` instances constructed internally by this Store.
+     * @see FieldSpec
+     */
+    fieldDefaults?: Omit<FieldSpec, 'name'>;
+    /**
+     * Specification for producing an immutable unique id for each record. May be provided as
+     * either a string property name (default is 'id') or a function that receives the raw data
+     * and returns a string. This property will be normalized to a function upon Store construction.
+     * If there is no natural id to select/generate, you can use `XH.genId` to generate a unique id
+     * on the fly. NOTE that in this case, grids and other components bound to this store will not
+     * be able to maintain record state across reloads.
+     */
+    idSpec?: StoreRecordIdSpec;
+    /**
+     * Initial data to load in to the Store.
+     */
+    data?: PlainObject[];
+    /**
+     * Function to run on each individual data object presented to `loadData()` prior to creating
+     * a `StoreRecord` from that object. This function must return an object, cloning the original
+     * object if edits are necessary.
+     */
+    processRawData?: (data: PlainObject) => PlainObject;
+    /**
+     * One or more filters or configs to create one. If an array, a single 'AND' filter
+     * will be created.
+     */
+    filter?: FilterLike;
+    /** True if all children of a passing record should also be considered passing (default false).*/
+    filterIncludesChildren?: boolean;
+    /** True (default) to load hierarchical/tree data, if any. */
+    loadTreeData?: boolean;
+    /**
+     * The property on each raw data object that holds its (raw) child objects, if any.
+     * Default 'children', no effect if `loadTreeData: false`.
+     */
+    loadTreeDataFrom?: string;
+    /** True to treat the root node in hierarchical data as the summary record (default false). */
+    loadRootAsSummary?: boolean;
+    /**
+     * True to freeze the internal data object of the record. May be set to false to maximize
+     * performance.  Note that the internal data of the record should in all cases be considered
+     * immutable (default true).
+     */
+    freezeData?: boolean;
+    /**
+     * Set to true to indicate that the id for a record implies a fixed position of the record
+     * within the tree hierarchy.  May be set to true to maximize performance (default false).
+     */
+    idEncodesTreePath?: boolean;
+    /**
+     * Performance optimization for large datasets with immutable raw data objects.
+     *
+     * By default, Store reuses existing StoreRecord instances when new data is loaded with
+     * matching IDs and identical field values (determined via deep equality comparison). This
+     * preserves row state in grids for unchanged records.
+     *
+     * When `reuseRecords` is true, the Store skips the fieldwise comparison and instead reuses
+     * records when the raw data object itself is **reference-identical** to the previously loaded
+     * object. This avoids equality checks, record creation, and raw data processing overhead.
+     *
+     * Only use this when your data source provides stable object references for unchanged records.
+     * Should not be used with a `processRawData` function that depends on external state, as that
+     * function will be bypassed on subsequent reloads of reference-identical data.
+     *
+     * Default false.
+     */
+    reuseRecords?: boolean;
+    /**
+     * Set to true to always validate all uncommitted records on every change to
+     * uncommitted records (add, modify, or remove). Default false.
+     */
+    validationIsComplex?: boolean;
+    /**
+     *  Flags for experimental features. These features are designed for early client-access and
+     *  testing, but are not yet part of the Hoist API.
+     */
+    experimental?: PlainObject;
+}
+/**
+ * Object representing data changes to perform on a Store's committed record set in a single
+ * transaction.
+ */
+export interface StoreTransaction {
+    /**
+     * List of raw data objects representing records to be updated.
+     * Updates must be matched to existing records by id in order to be applied. The form of the
+     * update objects should be the same as presented to loadData(), with the exception that any
+     * children property will be ignored, and any existing children for the record being updated
+     * will be preserved. If the record is a child, the new updated instance will be assigned to
+     * the same parent. (Meaning: parent/child relationships *cannot* be modified via updates.)
+     */
+    update?: PlainObject[];
+    /** Raw data of new records to be added, */
+    add?: Array<PlainObject | ChildRawData>;
+    /** IDs of existing records to be removed. Any descendents will also be removed. */
+    remove?: StoreRecordId[];
+    /**
+     *  Update to the dedicated summary record(s) for this store.  If the store has its
+     *  `loadRootAsSummary` flag set to true, the summary record should instead be provided via the
+     *  `update` property.
+     */
+    rawSummaryData?: Some<PlainObject>;
+}
+/**
+ * Collection of changes made to a Store's RecordSet. Unlike `StoreTransaction` which is used to
+ * specify changes, this object is used to report the actual changes made in a single transaction.
+ */
+export interface StoreChangeLog {
+    update?: StoreRecord[];
+    add?: StoreRecord[];
+    remove?: StoreRecordId[];
+    summaryRecords?: StoreRecord[];
+}
+export interface ChildRawData {
+    /** ID of the pre-existing parent record. */
+    parentId: string;
+    /**
+     * Data for the child records to be added. Can include a `children` property to be processed
+     * into new (grand)child records.
+     */
+    rawData: PlainObject[];
+}
+export type StoreRecordIdSpec = string | ((data: PlainObject) => StoreRecordId);
+/**
+ * A managed and observable set of local, in-memory Records.
+ */
+export declare class Store extends HoistBase implements FilterBindTarget, FilterValueSource, GridFilterBindTarget {
+    static isStore(obj: unknown): obj is Store;
+    readonly isFilterValueSource = true;
+    fields: Field[];
+    idSpec: (data: PlainObject) => StoreRecordId;
+    processRawData: (raw: any) => any;
+    filterIncludesChildren: boolean;
+    loadTreeData: boolean;
+    loadTreeDataFrom: string;
+    loadRootAsSummary: boolean;
+    idEncodesTreePath: boolean;
+    freezeData: boolean;
+    reuseRecords: boolean;
+    validationIsComplex: boolean;
+    filter: Filter;
+    /** Timestamp (ms) of the last time this store's data was changed. */
+    lastUpdated: number;
+    /** Timestamp (ms) of the last time this store's data was loaded.*/
+    lastLoaded: number;
+    /**
+     * Records containing summary data, such as top-level aggregations produced by a Hoist Cube
+     * or any other custom aggregation(s) calculated and installed by the application. Set via
+     * {@link loadData} or by loading a tree structure with `loadRootAsSummary` set to true.
+     */
+    summaryRecords: StoreRecord[];
+    /** @internal - used internally by any StoreFilterField bound to this store. */
+    xhFilterText: string;
+    validator: StoreValidator;
+    private _committed;
+    private _current;
+    _filtered: RecordSet;
+    private _dataDefaults;
+    _created: number;
+    private _fieldMap;
+    experimental: any;
+    constructor({ fields, fieldDefaults, idSpec, processRawData, filter, filterIncludesChildren, loadTreeData, loadTreeDataFrom, loadRootAsSummary, freezeData, idEncodesTreePath, reuseRecords, validationIsComplex, experimental, data }: StoreConfig);
+    /** Remove all records from the store. Equivalent to calling `loadData([])`. */
+    clear(): void;
+    /**
+     * Load a new and complete dataset, replacing any/all pre-existing Records as needed.
+     *
+     * If raw data objects have a `children` property, it will be expected to be an array and its
+     * items will be recursively processed into child Records, each created with a pointer to its
+     * parent's newly assigned StoreRecord ID.
+     *
+     * Note that this process will re-use pre-existing StoreRecord object instances if they are present
+     * in the new dataset (as identified by their ID), contain the same data, and occupy the same
+     * place in any hierarchy across old and new loads. This is to maximize the ability of
+     * downstream consumers (e.g. ag-Grid) to recognize Records that have not changed and do not
+     * need to be re-evaluated / re-rendered.
+     *
+     * Summary data can be provided via `rawSummaryData` or as the root data if the Store was
+     * created with its `loadRootAsSummary` flag set to true.
+     *
+     * @param rawData - source data to load
+     * @param rawSummaryData - source data for optional summary record(s), representing
+     *      custom aggregations for the dataset, if desired.
+     */
+    loadData(rawData: PlainObject[], rawSummaryData?: Some<PlainObject>): void;
+    /**
+     * Add, update, or delete Records in this Store. Note that objects passed to this method
+     * for adds and updates should have all the raw source data required to create those Records -
+     * i.e. they should be in the same form as when passed to `loadData()`. The added/updated
+     * source data will be run through this Store's `idSpec` and `processRawData` functions.
+     *
+     * Adds can also be provided as a {@link ChildRawData} object of the form `{rawData, parentId}`
+     * to add new Records under a known, pre-existing parent StoreRecord.
+     *
+     * Unlike `loadData()`, existing Records that are *not* included in this update transaction
+     * will be left in place and as is.
+     *
+     * Records loaded or removed via this method will be considered to be "committed", with the
+     * expectation that inputs to this method were provided by the server or other data source of
+     * record. For modifying particular fields on existing Records, see `modifyRecords()`. For local
+     * adds/removes not sourced from the server, see `addRecords()` and `removeRecords()`. Those
+     * APIs will modify the current RecordSet but leave those changes in an uncommitted state.
+     *
+     * @param rawData - data changes to process. If provided as an array, rawData will be processed
+     *      into adds and updates, with updates determined by matching existing records by ID.
+     * @returns changes applied, or null if no record changes were made.
+     */
+    updateData(rawData: PlainObject[] | StoreTransaction): StoreChangeLog;
+    /**
+     * Re-runs the Filter on the current data. Applications only need to call this method if
+     * the state underlying the filter, other than the record data itself, has changed. Store will
+     * re-filter automatically whenever StoreRecord data is updated or modified.
+     */
+    refreshFilter(): void;
+    /**
+     * Add new Records to this Store in a local, uncommitted state - i.e. with data that has yet to
+     * be persisted back to, or sourced from, the server or other data source of record.
+     *
+     * Note that data objects passed to this method must include a unique ID - callers can generate
+     * one with `XH.genId()` if no natural ID can be produced locally on the client.
+     *
+     * For StoreRecord additions that originate from the server, call `updateData()` instead.
+     *
+     * @param data - source data for new StoreRecord(s). Note that this data will
+     *      *not* be processed by this Store's `processRawData` or `idSpec` functions, but will be
+     *      parsed and potentially transformed according to this Store's Field definitions.
+     * @param parentId - ID of the pre-existing parent record under which this new
+     *      record should be added, if any.
+     */
+    addRecords(data: Some<PlainObject>, parentId?: StoreRecordId): void;
+    /**
+     * Remove Records from the Store in a local, uncommitted state - i.e. when queuing up a set of
+     * deletes on the client to be flushed back to the server at a later time.
+     *
+     * For StoreRecord deletions that originate from the server, call `updateData()` instead.
+     *
+     * @param records - list of StoreRecord IDs or Records to remove
+     */
+    removeRecords(records: StoreRecordOrId | StoreRecordOrId[]): void;
+    /**
+     * Modify individual StoreRecord field values in a local, uncommitted state - i.e. when updating a
+     * StoreRecord or Records via an inline grid editor or similar control.
+     *
+     * This method accepts partial updates for any Records to be modified; modifications need only
+     * include the StoreRecord ID and any fields that have changed.
+     *
+     * For StoreRecord updates that originate from the server, call `updateData()` instead.
+     *
+     * @param modifications - field-level modifications to apply to existing
+     *      Records in this Store. Each object in the list must have an `id` property identifying
+     *      the StoreRecord to modify, plus any other properties with updated field values to apply,
+     *      e.g. `{id: 4, quantity: 100}, {id: 5, quantity: 99, customer: 'bob'}`.
+     * @returns changes applied, or null if no record changes were made.
+     */
+    modifyRecords(modifications: Some<PlainObject>): StoreChangeLog;
+    /**
+     * Revert all changes made to the specified Records since they were last committed.
+     *
+     * This restores these Records to the state they were in when last loaded into this Store via
+     * `loadData()` or `updateData()`, undoing any local modifications that might have been applied.
+     *
+     * @param records - StoreRecord IDs or instances to revert
+     */
+    revertRecords(records: StoreRecordOrId | StoreRecordOrId[]): void;
+    /**
+     * Revert all changes made to the Store since data was last committed.
+     *
+     * This restores all Records to the state they were in when last loaded into this Store via
+     * `loadData()` or `updateData()`, undoing any local modifications that might have been applied,
+     * removing any uncommitted records added locally, and restoring any uncommitted deletes.
+     */
+    revert(): void;
+    /** Get a specific Field by name.*/
+    getField(name: string): Field;
+    get fieldNames(): string[];
+    /** Records in this store, respecting any filter (if applied).*/
+    get records(): StoreRecord[];
+    /** All records in this store, unfiltered.*/
+    get allRecords(): StoreRecord[];
+    /** All records that were originally loaded into this store.*/
+    get committedRecords(): StoreRecord[];
+    /** Records added locally which have not been committed.*/
+    get addedRecords(): StoreRecord[];
+    /** Records removed locally which have not been committed.*/
+    get removedRecords(): StoreRecord[];
+    /** Records modified locally since they were last loaded. */
+    get dirtyRecords(): StoreRecord[];
+    /** Alias for {@link Store.dirtyRecords} */
+    get modifiedRecords(): StoreRecord[];
+    /**
+     * Root records in this store, respecting any filter (if applied).
+     * If this store is not hierarchical, this will be identical to 'records'.
+     */
+    get rootRecords(): StoreRecord[];
+    /**
+     * Root records in this store, unfiltered.
+     * If this store is not hierarchical, this will be identical to 'allRecords'.
+     */
+    get allRootRecords(): StoreRecord[];
+    /**
+     * Single summary data record, if only one (or null if none). Maintained for convenience and
+     * for backwards compat with app code predating support for multiple {@link summaryRecords}.
+     */
+    get summaryRecord(): StoreRecord;
+    /** True if the store has changes which need to be committed. */
+    get isDirty(): boolean;
+    /** Alias for {@link Store.isDirty} */
+    get isModified(): boolean;
+    /**
+     * Set a filter on this store.
+     *
+     * @param filter - one or more filters or configs to create one.  If an
+     *      array, a single 'AND' filter will be created.
+     */
+    setFilter(filter: FilterLike): void;
+    setFilterIncludesChildren(val: boolean): void;
+    /** Convenience method to clear the Filter applied to this store. */
+    clearFilter(): void;
+    /**
+     * @returns true if the StoreRecord is in the store but currently excluded by a filter;
+     *      false if the record is either not in the Store at all or not filtered out.
+     */
+    recordIsFiltered(recOrId: StoreRecordOrId): boolean;
+    getValuesForFieldFilter(fieldName: string, filter?: Filter): any[];
+    /**
+     * Set whether the root should be loaded as summary data in loadData().
+     */
+    setLoadRootAsSummary(loadRootAsSummary: boolean): void;
+    /** The count of the filtered records in the store. */
+    get count(): number;
+    /** The count of all records in the store. */
+    get allCount(): number;
+    /** The count of the filtered root records in the store. */
+    get rootCount(): number;
+    /** The count of all root records in the store. */
+    get allRootCount(): number;
+    /** True if the store is empty after filters have been applied */
+    get empty(): boolean;
+    /** True if the store is empty before filters have been applied */
+    get allEmpty(): boolean;
+    get maxDepth(): number;
+    get errors(): StoreValidationMessagesMap;
+    get validationResults(): StoreValidationResultsMap;
+    /** Count of all validation errors for the store. */
+    get errorCount(): number;
+    /** Array of all errors for this store. */
+    get allErrors(): string[];
+    /** Array of all ValidationResults for this store. */
+    get allValidationResults(): ValidationResult[];
+    /**
+     * Get a record by ID, or null if no matching record found.
+     *
+     * @param id - ID of record to be queried.
+     * @param respectFilter - false (default) to return a StoreRecord with the given ID even if an
+     *      active filter is excluding it from the primary `records` collection. True to restrict
+     *      matches to this Store's post-filter StoreRecord collection only.
+     */
+    getById(id: StoreRecordId, respectFilter?: boolean): StoreRecord;
+    /**
+     * Get children records for a record.
+     *
+     * See also the 'children' and 'allChildren' properties on StoreRecord - those getters will likely
+     * be more convenient for most app-level callers.
+     *
+     * @param id - ID of record to be queried.
+     * @param respectFilter - true to skip records excluded by any active filter.
+     */
+    getChildrenById(id: StoreRecordId, respectFilter?: boolean): StoreRecord[];
+    /**
+     * Get descendant records for a record.
+     *
+     * See also the 'descendants' and 'allDescendants' properties on StoreRecord - those getters will
+     * likely be more convenient for most app-level callers.
+     *
+     * @param id - ID of record to be queried.
+     * @param respectFilter - true to skip records excluded by any active filter.
+     */
+    getDescendantsById(id: StoreRecordId, respectFilter?: boolean): StoreRecord[];
+    /**
+     * Get ancestor records for a record.
+     *
+     * See also the 'ancestors' and 'allAncestors' properties on StoreRecord - those getters will
+     * likely be more convenient for most app-level callers.
+     *
+     * @param id - ID of record to be queried.
+     * @param respectFilter - true to skip records excluded by any active filter.
+     */
+    getAncestorsById(id: StoreRecordId, respectFilter?: boolean): StoreRecord[];
+    /** True if the store is confirmed to be Valid. */
+    get isValid(): boolean;
+    /** True if the store is confirmed to be NotValid. */
+    get isNotValid(): boolean;
+    /** Recompute ValidationResults for all records and return true if the store is valid. */
+    validateAsync(): Promise<boolean>;
+    /** Destroy this store, cleaning up any resources used. */
+    destroy(): void;
+    protected get defaultFieldClass(): typeof Field;
+    setXhFilterText(s: string): void;
+    private getOrThrow;
+    private getCommittedOrThrow;
+    private resetRecords;
+    private parseFields;
+    private rebuildFiltered;
+    private createRecord;
+    private createRecords;
+    private get summaryRecordIds();
+    private parseRaw;
+    private parseUpdate;
+    private createDataDefaults;
+    private createFieldMap;
+    private parseExperimental;
+    private parseIdSpec;
+    private revertSummaryRecords;
+}

package/build/types/data/StoreRecord.d.ts

@@ -0,0 +1,186 @@
+import { PlainObject } from '@xh/hoist/core';
+import { ValidationResult } from '@xh/hoist/data/validation/Types';
+import { Store } from './Store';
+import { ValidationState } from './validation/ValidationState';
+import { RecordValidator } from './impl/RecordValidator';
+import { Field } from './Field';
+/**
+ * Wrapper object for each data element within a {@link Store}. Records must be assigned a unique ID
+ * within their Store and manage a bundle of data with fields defined by the Store. They track the
+ * state of that data through possible updates, with support for tracking edits and "committing"
+ * changes to provide dirty state.
+ *
+ * Each StoreRecord holds a pointer to its parent record, if any, via that parent's ID. (Note this
+ * is deliberately not a direct object reference, to allow parent records to be recreated without
+ * requiring children to also be recreated.)
+ *
+ * Records are intended to be created and managed internally by Store implementations and should
+ * most not typically be constructed directly within application code.
+ */
+export declare class StoreRecord {
+    readonly id: StoreRecordId;
+    readonly parentId: StoreRecordId;
+    readonly store: Store;
+    readonly isSummary: boolean;
+    readonly treePath: StoreRecordId[];
+    /** Raw data loaded into via Store.loadData() or Store.updateData(). */
+    readonly raw: PlainObject;
+    /**
+     * An object containing the current field values for this record.
+     *
+     * Note that this object will only contain explicit 'own' properties for fields that are
+     * not at their default values - default values will be present via the prototype.
+     *
+     * Call {@link getValues} for an object providing an explicit enumeration of all field values.
+     */
+    readonly data: PlainObject;
+    /**
+     * An object containing the fully committed field values for this record.
+     *
+     * This object has the same form as `data`. If this record has not been locally modified, this
+     * property will point to the same object as `data`.
+     */
+    readonly committedData: PlainObject;
+    /**
+     * Unique ID for representing record within ag-Grid node API.
+     *
+     * A string variant of the main record ID.  It should be used when trying to identify or
+     * locate the record using the ag-Grid callbacks and API.
+     */
+    readonly agId: string;
+    get isRecord(): boolean;
+    /** True if the StoreRecord has never been committed. */
+    get isAdd(): boolean;
+    /** True if the StoreRecord has been modified since it was last committed. */
+    get isDirty(): boolean;
+    /** Alias for {@link StoreRecord.isDirty} */
+    get isModified(): boolean;
+    /** False if the StoreRecord has been added or modified. */
+    get isCommitted(): boolean;
+    get parent(): StoreRecord;
+    get depth(): number;
+    get fields(): Field[];
+    /** The current value of a field.*/
+    get(fieldName: string): any;
+    /** Children of this record, respecting any filter (if applied). */
+    get children(): StoreRecord[];
+    /** All children of this record, unfiltered. */
+    get allChildren(): StoreRecord[];
+    /** Descendants of this record, respecting any filter (if applied). */
+    get descendants(): StoreRecord[];
+    /** All descendants of this record, unfiltered. */
+    get allDescendants(): StoreRecord[];
+    /** Ancestors of this record, respecting any filter (if applied). */
+    get ancestors(): StoreRecord[];
+    /** All ancestors of this record, unfiltered. */
+    get allAncestors(): StoreRecord[];
+    /** True if the record is confirmed to be Valid. */
+    get isValid(): boolean;
+    /** True if the record is confirmed to be NotValid. */
+    get isNotValid(): boolean;
+    /** The current validation state of the record. */
+    get validationState(): ValidationState;
+    /** Map of field names to list of errors. */
+    get errors(): Record<string, string[]>;
+    /** Map of field names to list of ValidationResults. */
+    get validationResults(): Record<string, ValidationResult[]>;
+    /** Array of all errors for this record. */
+    get allErrors(): string[];
+    /** Array of all ValidationResults for this record. */
+    get allValidationResults(): ValidationResult[];
+    /** Count of all validation errors for the record. */
+    get errorCount(): number;
+    /** True if any fields are currently recomputing their validation state. */
+    get isValidationPending(): boolean;
+    get validator(): RecordValidator;
+    /**
+     * Get a new object with enumerated values for all Fields in this StoreRecord.
+     * Unlike 'data', the object returned by this method contains an 'own' property for every
+     * Field in the Store. Useful for cloning/iterating over all values (including defaults).
+     */
+    getValues(): PlainObject;
+    /**
+     * Get a map of modified values only.
+     *
+     * If record has no modifications, this method will return null.
+     * If modifications are returned, the returned object will include id,
+     * for convenience.
+     */
+    getModifiedValues(): PlainObject;
+    /**
+     * Construct a StoreRecord from a pre-processed `data` source object.
+     *
+     * Not typically called by applications directly - `Store` instances create `StoreRecord`s when
+     * loading or updating data through their public APIs. See {@link Store.createRecord} for the
+     * primary implementation, which includes parsing based on the Store's {@link Field} types
+     * and definitions.
+     *
+     * @internal
+     */
+    constructor(config: StoreRecordConfig);
+    /**
+     * Calls 'fn' for each child record of this record.
+     * @param fn - the function to call.
+     * @param fromFiltered - true to skip records excluded by any active filter.
+     */
+    forEachChild(fn: (r: StoreRecord) => void, fromFiltered?: boolean): void;
+    /**
+     * Calls 'fn' for each descendant record of this record.
+     * @param fn - the function to call.
+     * @param fromFiltered - true to skip records excluded by any active filter.
+     */
+    forEachDescendant(fn: (r: StoreRecord) => void, fromFiltered?: boolean): void;
+    /**
+     * Calls 'fn' for each ancestor record of this record.
+     * @param fn - the function to call.
+     * @param fromFiltered - true to skip records excluded by any active filter.
+     */
+    forEachAncestor(fn: (r: StoreRecord) => void, fromFiltered?: boolean): void;
+    /**
+     * Tests to see if this Record's data matches the given partial data object.
+     */
+    matchesData(partialData: PlainObject): boolean;
+    /**
+     * Finalize this record for use in Store, post acceptance by RecordSet.
+     *
+     * We finalize the StoreRecord post-construction in RecordSet, only once we know that it is
+     * going to be accepted in the new RecordSet (and is not a duplicate). This is a performance
+     * optimization to avoid operations like freezing on transient records.
+     *
+     * @internal
+     */
+    finalize(): void;
+}
+/** Unique identifier for a StoreRecord within a Store. */
+export type StoreRecordId = number | string;
+/** A Hoist StoreRecord, or an ID for one. */
+export type StoreRecordOrId = StoreRecordId | StoreRecord;
+/** StoreRecord constructor arguments. */
+export interface StoreRecordConfig {
+    /** Unique ID for the Record. */
+    id: StoreRecordId;
+    /** Store containing this StoreRecord. */
+    store: Store;
+    /**
+     * Data for this StoreRecord, pre-processed if applicable by `Store.processRawData()` and
+     * `Field.parseVal()`. Note this must be a new object dedicated to this StoreRecord.
+     * This object will be enhanced with an id and frozen.
+     */
+    data: PlainObject;
+    /**
+     * The original data for the StoreRecord, prior to any Store pre-processing.
+     * This data is for reference only and will not be altered by this object.
+     */
+    raw?: PlainObject;
+    /**
+     * The version of the data that was last loaded via the Store load APIs. Pass `null` to
+     * signal that this is a "new" StoreRecord that has been added since the last load.
+     */
+    committedData?: PlainObject;
+    parent?: StoreRecord;
+    /**
+     * True to indicate this is a summary StoreRecord, used to show aggregate, grand-total level
+     * information in grids when enabled.
+     */
+    isSummary?: boolean;
+}

package/build/types/data/StoreSelectionModel.d.ts

@@ -0,0 +1,52 @@
+import { HoistModel } from '@xh/hoist/core';
+import { Store } from './Store';
+import { StoreRecord, StoreRecordId, StoreRecordOrId } from './StoreRecord';
+export interface StoreSelectionConfig {
+    store?: Store;
+    mode?: 'single' | 'multiple' | 'disabled';
+    xhImpl?: boolean;
+}
+/**
+ * Model for managing store selections.
+ * Typically accessed from a GridModel to observe/control Grid selection.
+ */
+export declare class StoreSelectionModel extends HoistModel {
+    readonly store: Store;
+    mode: 'single' | 'multiple' | 'disabled';
+    private _ids;
+    get isEnabled(): boolean;
+    constructor({ store, mode, xhImpl }: StoreSelectionConfig);
+    get selectedRecords(): StoreRecord[];
+    get selectedIds(): StoreRecordId[];
+    /**
+     * Single selected record, or null if multiple/no records selected.
+     *
+     * Note that this getter will also change if just the data of selected record is changed
+     * due to store loading or editing.  Applications only interested in the *identity*
+     * of the selection should use {@link selectedId} instead.
+     */
+    get selectedRecord(): StoreRecord;
+    /**
+     * ID of selected record, or null if multiple/no records selected.
+     *
+     * Note that this getter will *not* change if just the data of selected record is changed
+     * due to store loading or editing.  Applications also interested in the *contents* of the
+     * selection should use the {@link selectedRecord} getter instead.
+     */
+    get selectedId(): StoreRecordId;
+    /** @returns true if selection is empty. */
+    get isEmpty(): boolean;
+    /** @returns count of currently selected records. */
+    get count(): number;
+    /**
+     * Set the selection.
+     * @param records - single record/ID or array of records/IDs to select.
+     * @param clearSelection - true to clear previous selection (rather than add to it).
+     */
+    select(records: StoreRecordOrId | StoreRecordOrId[], clearSelection?: boolean): void;
+    /** Select all filtered records. */
+    selectAll(): void;
+    /** Clear the selection. */
+    clear(): void;
+    private cullSelectionReaction;
+}