@framesquared/data 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1028 @@
+import { Base } from '@framesquared/core';
+
+/**
+ * @framesquared/data – Field system
+ *
+ * Defines field types with type coercion, serialization, and defaults.
+ */
+declare enum FieldType {
+    STRING = "string",
+    INT = "int",
+    FLOAT = "float",
+    BOOLEAN = "boolean",
+    DATE = "date",
+    AUTO = "auto"
+}
+type Validator = (value: unknown, record?: any) => string | null;
+interface FieldDefinition {
+    name: string;
+    type?: FieldType;
+    defaultValue?: unknown;
+    convert?: (value: unknown, record?: any) => unknown;
+    serialize?: (value: unknown, record?: any) => unknown;
+    mapping?: string;
+    persist?: boolean;
+    critical?: boolean;
+    allowNull?: boolean;
+    sortType?: string;
+    validators?: Validator[];
+}
+declare abstract class Field {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly mapping: string | undefined;
+    readonly persist: boolean;
+    readonly critical: boolean;
+    readonly allowNull: boolean;
+    readonly sortType: string | undefined;
+    readonly validators: Validator[];
+    private readonly customConvert?;
+    private readonly customSerialize?;
+    private readonly customDefault;
+    constructor(def: FieldDefinition);
+    /** Type-specific default (overridden by subclasses). */
+    get defaultValue(): unknown;
+    /** Subclass provides the type-specific default. */
+    protected abstract getTypeDefault(): unknown;
+    /**
+     * Converts a raw value to the field's type.
+     * If a custom `convert` was specified in the definition, it is used.
+     * Otherwise delegates to the subclass's `coerce()`.
+     */
+    convert(value: unknown, record?: any): unknown;
+    /** Type-specific coercion (subclasses override). */
+    protected abstract coerce(value: unknown): unknown;
+    /**
+     * Serializes a value for transport.
+     */
+    serialize(value: unknown, record?: any): unknown;
+}
+declare class StringField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+}
+declare class IntField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+}
+declare class FloatField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+}
+declare class BooleanField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+}
+declare class DateField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+    serialize(value: unknown): unknown;
+}
+declare class AutoField extends Field {
+    constructor(def: Omit<FieldDefinition, 'type'> & {
+        type?: FieldType;
+    });
+    protected getTypeDefault(): unknown;
+    protected coerce(value: unknown): unknown;
+}
+/**
+ * Creates a Field instance from a definition or shorthand string.
+ */
+declare function createField(def: FieldDefinition | string): Field;
+
+/**
+ * @framesquared/data – ModelCollection
+ *
+ * A lightweight collection of Model instances, used by HasMany and
+ * ManyToMany associations.  Provides add/remove/filter/getById.
+ */
+
+declare class ModelCollection {
+    private items;
+    getCount(): number;
+    getAll(): Model[];
+    add(record: Model): void;
+    remove(record: Model): void;
+    getById(id: string | number): Model | undefined;
+    filter(fn: (record: Model) => boolean): Model[];
+    destroyAll(): void;
+}
+/**
+ * Extended collection for ManyToMany that exposes link/unlink semantics.
+ */
+declare class ManyToManyCollection extends ModelCollection {
+    private junctions;
+    link(record: Model, _junctionData?: Record<string, unknown>): void;
+    unlink(record: Model): void;
+}
+
+/**
+ * @framesquared/data – Model
+ *
+ * The foundation of the data layer.  A Model represents a record with
+ * typed fields, dirty tracking, validation, and event notification.
+ *
+ * Instances are wrapped in a Proxy so `record.name` transparently
+ * delegates to `get('name')` / `set('name', value)` for field access.
+ */
+
+interface ValidationError {
+    field: string;
+    message: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+declare class Model extends Base {
+    static $className: string;
+    /** Field definitions — override in subclasses. */
+    static fields: (FieldDefinition | string)[];
+    /** Name of the ID field. */
+    static idProperty: string;
+    /** Resolved Field instances keyed by name. */
+    $fieldMap: Map<string, Field>;
+    /** Current field values. */
+    $data: Record<string, unknown>;
+    /** Previous values for dirty fields (fieldName → old value). */
+    modified: Record<string, unknown>;
+    /** Per-instance association storage: assocName → Model | ModelCollection */
+    $associations: Map<string, Model | ModelCollection | ManyToManyCollection>;
+    constructor(_data?: Record<string, unknown>);
+    /**
+     * Factory method that sets up fields, applies data, wraps in proxy.
+     */
+    static create(this: typeof Model, data?: Record<string, unknown>): Model;
+    /** @internal Loads initial data without marking as dirty. */
+    $loadData(rawData: Record<string, unknown>): void;
+    get(fieldName: string): unknown;
+    set(fieldNameOrData: string | Record<string, unknown>, value?: unknown): string[];
+    getData(options?: {
+        serialize?: boolean;
+    }): Record<string, unknown>;
+    isModified(fieldName?: string): boolean;
+    getChanges(): Record<string, unknown>;
+    commit(silent?: boolean): void;
+    reject(silent?: boolean): void;
+    getId(): string | number;
+    setId(id: string | number): void;
+    get phantom(): boolean;
+    validate(): ValidationResult;
+    isValid(): boolean;
+}
+
+/**
+ * @framesquared/data – Built-in validators
+ *
+ * Each factory returns a Validator function: (value) => errorMsg | null
+ */
+
+/**
+ * Value must not be null, undefined, or empty string.
+ */
+declare function presence(message?: string): Validator;
+/**
+ * String length must be within min/max bounds.
+ */
+declare function length(opts: {
+    min?: number;
+    max?: number;
+    message?: string;
+}): Validator;
+/**
+ * Value must match the given regex.
+ */
+declare function formatValidator(pattern: RegExp, message?: string): Validator;
+/**
+ * Value must be in the allowed list.
+ */
+declare function inclusion(list: unknown[], message?: string): Validator;
+/**
+ * Value must NOT be in the disallowed list.
+ */
+declare function exclusion(list: unknown[], message?: string): Validator;
+/**
+ * Numeric value must be within min/max.
+ */
+declare function rangeValidator(opts: {
+    min?: number;
+    max?: number;
+    message?: string;
+}): Validator;
+declare function email(message?: string): Validator;
+
+/**
+ * @framesquared/data – Association (base class)
+ */
+
+interface AssociationConfig {
+    model: string | typeof Model;
+    foreignKey: string;
+    primaryKey?: string;
+    getterName?: string;
+    setterName?: string;
+    cascade?: boolean;
+    /** For ManyToMany: junction model name or class */
+    through?: string;
+    /** For ManyToMany: the other foreign key in the junction */
+    otherKey?: string;
+}
+type AssociationType = 'hasOne' | 'hasMany' | 'belongsTo' | 'manyToMany';
+declare class Association {
+    readonly type: AssociationType;
+    readonly config: AssociationConfig;
+    readonly ownerModelName: string;
+    /** Resolved associated model class (may be null until forward ref resolves). */
+    associatedModel: typeof Model | null;
+    constructor(type: AssociationType, ownerModelName: string, config: AssociationConfig);
+    /**
+     * The property name used for nested JSON loading and as the
+     * default getter/collection accessor name.
+     */
+    get associationName(): string;
+    get getterName(): string;
+    get setterName(): string;
+    get foreignKey(): string;
+    get primaryKey(): string;
+    get cascade(): boolean;
+}
+
+/**
+ * @framesquared/data – Schema
+ *
+ * Singleton registry for Model classes and their associations.
+ * Handles forward references: if Model A declares an association to
+ * Model B by string name before B is registered, the reference is
+ * resolved when B is later registered.
+ */
+
+declare class SchemaImpl {
+    /**
+     * Registers a Model class and processes its association declarations.
+     * If the model has `static hasOne`, `static hasMany`, `static belongsTo`,
+     * or `static manyToMany` arrays, creates Association instances for each.
+     */
+    register(ModelClass: typeof Model): void;
+    /**
+     * Retrieves a registered Model class by name.
+     */
+    get(name: string): typeof Model | undefined;
+    /**
+     * Returns all Association instances owned by the given model name.
+     */
+    getAssociations(modelName: string): Association[];
+    /**
+     * Clears all registrations (for testing).
+     */
+    clear(): void;
+    private processAssociations;
+}
+/** Singleton. */
+declare const Schema: SchemaImpl;
+
+/**
+ * @framesquared/data – HasOne association
+ */
+
+declare class HasOne extends Association {
+    constructor(ownerModelName: string, config: AssociationConfig);
+}
+
+/**
+ * @framesquared/data – HasMany association
+ */
+
+declare class HasMany extends Association {
+    constructor(ownerModelName: string, config: AssociationConfig);
+}
+
+/**
+ * @framesquared/data – BelongsTo association
+ */
+
+declare class BelongsTo extends Association {
+    constructor(ownerModelName: string, config: AssociationConfig);
+}
+
+/**
+ * @framesquared/data – ManyToMany association
+ */
+
+declare class ManyToMany extends Association {
+    constructor(ownerModelName: string, config: AssociationConfig);
+    get through(): string;
+    get otherKey(): string;
+}
+
+/**
+ * @framesquared/data – Collection
+ *
+ * An ordered, optionally keyed collection used internally by Store.
+ * Provides add, insert, remove, sort, find, and iteration.
+ */
+declare class Collection<T> {
+    private items;
+    private keyMap;
+    private keyFn;
+    constructor(keyFn?: (item: T) => unknown);
+    getCount(): number;
+    getAt(index: number): T | undefined;
+    getByKey(key: unknown): T | undefined;
+    indexOf(item: T): number;
+    contains(item: T): boolean;
+    add(item: T): void;
+    insert(index: number, item: T): void;
+    remove(item: T): T | undefined;
+    removeAt(index: number, count?: number): T[];
+    clear(): void;
+    toArray(): T[];
+    each(fn: (item: T, index: number) => boolean | void): void;
+    find(fn: (item: T) => boolean): T | undefined;
+    filter(fn: (item: T) => boolean): T[];
+    sort(compareFn: (a: T, b: T) => number): void;
+    first(): T | undefined;
+    last(): T | undefined;
+    getRange(start?: number, end?: number): T[];
+    /** Rebuilds the key map (call after sort or external mutation). */
+    rekey(): void;
+}
+
+/**
+ * @framesquared/data – Store
+ *
+ * A client-side collection of Model records with sorting, filtering,
+ * grouping, events, and sync/change tracking.
+ */
+
+interface Sorter {
+    property: string;
+    direction: 'ASC' | 'DESC';
+    sorterFn?: (a: Model, b: Model) => number;
+}
+type FilterOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'like' | 'in' | 'notin';
+interface Filter {
+    property: string;
+    value: unknown;
+    operator?: FilterOperator;
+    filterFn?: (record: Model) => boolean;
+    anyMatch?: boolean;
+    caseSensitive?: boolean;
+}
+interface Group {
+    name: string;
+    children: Model[];
+}
+interface StoreConfig {
+    model: typeof Model;
+    data?: Record<string, unknown>[];
+}
+declare class Store extends Base {
+    static $className: string;
+    private ModelClass;
+    private data;
+    private allData;
+    private currentSorters;
+    private currentFilters;
+    private groupField;
+    private groupDirection;
+    private cachedGroups;
+    private removedRecords;
+    $destroyHooks: (() => void)[];
+    constructor(config: StoreConfig);
+    private loadData;
+    add(...records: Model[]): Model[];
+    insert(index: number, ...records: Model[]): Model[];
+    remove(...records: Model[]): Model[];
+    removeAt(index: number, count?: number): Model[];
+    removeAll(silent?: boolean): void;
+    getAt(index: number): Model | undefined;
+    getById(id: string | number): Model | undefined;
+    getRange(start?: number, end?: number): Model[];
+    getCount(): number;
+    getTotalCount(): number;
+    indexOf(record: Model): number;
+    contains(record: Model): boolean;
+    first(): Model | undefined;
+    last(): Model | undefined;
+    each(fn: (record: Model, index: number) => boolean | void): void;
+    collect(fieldName: string): unknown[];
+    getData(): Collection<Model>;
+    sort(fieldOrSorters?: string | Sorter[], direction?: 'ASC' | 'DESC'): void;
+    getSorters(): Sorter[];
+    filter(fieldOrFilters: string | Filter[], value?: unknown): void;
+    clearFilter(suppressEvent?: boolean): void;
+    getFilters(): Filter[];
+    private applyFilters;
+    group(field: string, direction?: 'ASC' | 'DESC'): void;
+    clearGrouping(): void;
+    isGrouped(): boolean;
+    getGroups(): Group[];
+    private invalidateGroups;
+    getModifiedRecords(): Model[];
+    getNewRecords(): Model[];
+    getRemovedRecords(): Model[];
+    commitChanges(): void;
+    rejectChanges(): void;
+    private fire;
+}
+
+/**
+ * @framesquared/data – ResultSet
+ */
+
+interface ResultSetConfig {
+    records: Model[];
+    total?: number;
+    success: boolean;
+    message?: string;
+}
+declare class ResultSet {
+    readonly records: Model[];
+    readonly total: number;
+    readonly success: boolean;
+    readonly message: string | undefined;
+    constructor(config: ResultSetConfig);
+}
+
+/**
+ * @framesquared/data – Operation
+ */
+
+type OperationAction = 'create' | 'read' | 'update' | 'destroy';
+interface OperationConfig {
+    action: OperationAction;
+    records?: Model[];
+    params?: Record<string, unknown>;
+    filters?: any[];
+    sorters?: any[];
+    start?: number;
+    limit?: number;
+    page?: number;
+}
+declare class Operation {
+    readonly action: OperationAction;
+    readonly records: Model[];
+    readonly params: Record<string, unknown>;
+    readonly filters: any[] | undefined;
+    readonly sorters: any[] | undefined;
+    readonly start: number | undefined;
+    readonly limit: number | undefined;
+    readonly page: number | undefined;
+    result: ResultSet | null;
+    constructor(config: OperationConfig);
+    setResult(rs: ResultSet): void;
+}
+
+/**
+ * @framesquared/data – Readers
+ *
+ * Parse raw server response data into ResultSet instances.
+ */
+
+interface JsonReaderConfig {
+    model: typeof Model;
+    rootProperty?: string;
+    totalProperty?: string;
+    successProperty?: string;
+    messageProperty?: string;
+}
+declare class JsonReader {
+    protected config: JsonReaderConfig;
+    constructor(config: JsonReaderConfig);
+    read(data: unknown): ResultSet;
+}
+interface ArrayReaderConfig {
+    model: typeof Model;
+}
+declare class ArrayReader {
+    private config;
+    constructor(config: ArrayReaderConfig);
+    read(data: unknown[][]): ResultSet;
+}
+interface XmlReaderConfig {
+    model: typeof Model;
+    record: string;
+}
+declare class XmlReader {
+    private config;
+    constructor(config: XmlReaderConfig);
+    read(xmlString: string): ResultSet;
+}
+
+/**
+ * @framesquared/data – Writers
+ *
+ * Serialize Model records for transport to the server.
+ */
+
+interface JsonWriterConfig {
+    writeAllFields?: boolean;
+    allowSingle?: boolean;
+    encode?: boolean;
+    rootProperty?: string;
+}
+declare class JsonWriter {
+    private config;
+    constructor(config: JsonWriterConfig);
+    write(records: Model[]): unknown;
+    private serializeRecord;
+}
+interface XmlWriterConfig {
+    documentRoot?: string;
+    record?: string;
+}
+declare class XmlWriter {
+    private config;
+    constructor(config: XmlWriterConfig);
+    write(records: Model[]): string;
+}
+
+/**
+ * @framesquared/data – Proxy (abstract base)
+ */
+
+interface BatchOptions {
+    create?: Model[];
+    update?: Model[];
+    destroy?: Model[];
+}
+interface Batch {
+    success: boolean;
+    operations: Operation[];
+}
+interface ProxyConfig {
+    model: typeof Model;
+    [key: string]: unknown;
+}
+declare abstract class Proxy {
+    readonly model: typeof Model;
+    constructor(config: ProxyConfig);
+    abstract read(operation: Operation, signal?: AbortSignal): Promise<ResultSet>;
+    abstract create(operation: Operation): Promise<ResultSet>;
+    abstract update(operation: Operation): Promise<ResultSet>;
+    abstract destroy(operation: Operation): Promise<ResultSet>;
+    batch(options: BatchOptions): Promise<Batch>;
+}
+
+/**
+ * @framesquared/data – Client Proxies
+ *
+ * MemoryProxy, LocalStorageProxy, SessionStorageProxy
+ */
+
+interface MemoryProxyConfig extends ProxyConfig {
+    data?: Record<string, unknown>[];
+}
+declare class MemoryProxy extends Proxy {
+    private store;
+    constructor(config: MemoryProxyConfig);
+    read(operation: Operation): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+}
+interface WebStorageProxyConfig extends ProxyConfig {
+    id: string;
+}
+declare abstract class WebStorageProxy extends Proxy {
+    protected storageId: string;
+    protected abstract getStorage(): Storage;
+    constructor(config: WebStorageProxyConfig);
+    private loadAll;
+    private saveAll;
+    read(_operation: Operation): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+}
+declare class LocalStorageProxy extends WebStorageProxy {
+    protected getStorage(): Storage;
+}
+declare class SessionStorageProxy extends WebStorageProxy {
+    protected getStorage(): Storage;
+}
+
+/**
+ * @framesquared/data – Server Proxies
+ *
+ * AjaxProxy (fetch-based) and RestProxy (RESTful URL patterns).
+ */
+
+interface AjaxProxyConfig extends ProxyConfig {
+    url: string;
+    api?: Partial<Record<string, string>>;
+    headers?: Record<string, string>;
+    timeout?: number;
+    withCredentials?: boolean;
+}
+declare class AjaxProxy extends Proxy {
+    protected url: string;
+    protected api: Partial<Record<string, string>>;
+    protected headers: Record<string, string>;
+    protected timeout: number;
+    protected withCredentials: boolean;
+    protected reader: JsonReader;
+    protected writer: JsonWriter;
+    constructor(config: AjaxProxyConfig);
+    read(operation: Operation, signal?: AbortSignal): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+    protected buildUrl(operation: Operation, action: string): string;
+    protected doRequest(operation: Operation, action: string, signal?: AbortSignal): Promise<ResultSet>;
+}
+interface RestProxyConfig extends AjaxProxyConfig {
+    appendId?: boolean;
+}
+declare class RestProxy extends AjaxProxy {
+    private appendId;
+    constructor(config: RestProxyConfig);
+    protected buildUrl(operation: Operation, action: string): string;
+}
+
+/**
+ * @framesquared/data – NodeInterface
+ *
+ * Mixin applied to Model instances to give them tree-node capabilities:
+ * parent/child/sibling navigation, depth, expand/collapse state,
+ * cascadeBy, bubble, getPath, findChild, sort, and nested serialization.
+ */
+
+interface NodeInterface extends Model {
+    parentNode: NodeInterface | null;
+    childNodes: NodeInterface[];
+    firstChild: NodeInterface | null;
+    lastChild: NodeInterface | null;
+    previousSibling: NodeInterface | null;
+    nextSibling: NodeInterface | null;
+    depth: number;
+    /** Node state */
+    expanded: boolean;
+    loaded: boolean;
+    isLeaf(): boolean;
+    isRoot(): boolean;
+    isExpanded(): boolean;
+    isLoaded(): boolean;
+    appendChild(child: NodeInterface): void;
+    removeChild(child: NodeInterface): void;
+    insertBefore(newChild: NodeInterface, refChild: NodeInterface): void;
+    getPath(separator?: string): string;
+    cascadeBy(fn: (node: NodeInterface) => boolean | void): void;
+    bubble(fn: (node: NodeInterface) => boolean | void): void;
+    contains(child: NodeInterface): boolean;
+    findChild(field: string, value: unknown, deep?: boolean): NodeInterface | undefined;
+    sort(sorters: Sorter[]): void;
+    serialize(): any;
+    eachChild(fn: (child: NodeInterface, index: number) => boolean | void, scope?: object): void;
+    indexOf(child: NodeInterface): number;
+    getChildAt(index: number): NodeInterface | undefined;
+    childCount(): number;
+    hasChildNodes(): boolean;
+    getChildren(deep?: boolean): NodeInterface[];
+    findChildBy(predicate: (node: NodeInterface) => boolean | void, deep?: boolean): NodeInterface | undefined;
+    removeAll(): NodeInterface[];
+    copy(deep?: boolean): NodeInterface;
+    getDepth(): number;
+}
+declare function applyNodeInterface(model: Model, depth?: number): void;
+
+/**
+ * @framesquared/data – TreeStore
+ *
+ * Manages hierarchical (tree) data.  Records are enhanced with
+ * NodeInterface for parent/child navigation, expand/collapse,
+ * and nested serialization.
+ */
+
+interface TreeStoreConfig {
+    model?: typeof Model;
+    root?: Record<string, unknown>;
+    proxy?: any;
+}
+declare class TreeStore extends Base {
+    static $className: string;
+    private ModelClass;
+    private rootNode;
+    private nodeMap;
+    $destroyHooks: (() => void)[];
+    constructor(config: TreeStoreConfig);
+    getRoot(): NodeInterface;
+    getRootNode(): NodeInterface;
+    /**
+     * Replaces the root with new data (or a pre-built node).
+     * Fires 'rootchange'.
+     */
+    setRoot(nodeOrData: NodeInterface | Record<string, unknown>): NodeInterface;
+    private isNodeInterface;
+    private replaceRoot;
+    getNodeById(id: string | number): NodeInterface | undefined;
+    appendChild(parent: NodeInterface, child: NodeInterface): void;
+    removeChild(parent: NodeInterface, child: NodeInterface): void;
+    insertBefore(node: NodeInterface, refNode: NodeInterface): void;
+    expandNode(node: NodeInterface): void;
+    collapseNode(node: NodeInterface): void;
+    findNode(field: string, value: unknown): NodeInterface | undefined;
+    private findNodeImpl;
+    collapseAll(): void;
+    expandAll(): void;
+    getCount(): number;
+    getTotalCount(): number;
+    flattenNodes(): Model[];
+    private flattenWalk;
+    private buildNode;
+    private registerRecursive;
+    private unregisterRecursive;
+    private fire;
+}
+
+/**
+ * @framesquared/data – TreeModel
+ *
+ * A convenience Model subclass with NodeInterface pre-applied via create().
+ */
+
+declare class TreeModel extends Model {
+    static $className: string;
+    static idProperty: string;
+    static defaultRootId: string;
+    static defaultRootText: string;
+    static fields: ({
+        name: string;
+        type: FieldType;
+        defaultValue?: undefined;
+    } | {
+        name: string;
+        type: FieldType;
+        defaultValue: string;
+    } | {
+        name: string;
+        type: FieldType;
+        defaultValue: boolean;
+    })[];
+    /**
+     * Factory method that creates a TreeModel instance with NodeInterface
+     * already applied.
+     */
+    static create(this: typeof Model, data?: Record<string, unknown>): InstanceType<typeof Model> & NodeInterface;
+}
+
+/**
+ * @framesquared/data – TreeReader
+ *
+ * Reads nested (hierarchical) JSON data, flattening it into a ResultSet
+ * while preserving the children references.
+ */
+
+interface TreeReaderConfig extends JsonReaderConfig {
+    /** Name of the property that holds child records. Defaults to 'children'. */
+    childrenProperty?: string;
+}
+declare class TreeReader extends JsonReader {
+    readonly childrenProperty: string;
+    constructor(config: TreeReaderConfig);
+    /**
+     * Reads data, recursively collecting ALL nodes (at all levels) into a flat
+     * ResultSet.  The original children references are preserved on the raw
+     * objects, so the tree structure is available to callers (e.g. TreeStore).
+     */
+    read(data: unknown): ResultSet;
+    /**
+     * Returns `{ root, records }` where `root` is the first raw record and
+     * `records` is the full flat list of all nodes.
+     */
+    readTree(data: Record<string, unknown>): {
+        root: Record<string, unknown>;
+        records: Record<string, unknown>[];
+    };
+    private extractRootArray;
+    private collectFlat;
+}
+
+/**
+ * @framesquared/data – TreeWriter
+ *
+ * Serializes tree nodes (NodeInterface) into nested JSON structures.
+ */
+
+interface TreeWriterConfig {
+    /** Name of the property used for child records. Defaults to 'children'. */
+    childrenProperty?: string;
+}
+declare class TreeWriter {
+    readonly childrenProperty: string;
+    constructor(config?: TreeWriterConfig);
+    /**
+     * Serializes an array of root-level NodeInterface records to plain objects.
+     * Children are nested under the configured `childrenProperty`.
+     */
+    writeRecords(records: NodeInterface[]): Record<string, unknown>[];
+    private writeRecord;
+}
+
+/**
+ * @framesquared/data – BufferedStore
+ *
+ * For large datasets — loads pages of data on demand via a proxy.
+ * Uses a sparse page map instead of loading all records.
+ * Prefetches adjacent pages based on configurable buffer zones.
+ */
+
+interface BufferedStoreConfig {
+    model: typeof Model;
+    pageSize?: number;
+    leadingBufferZone?: number;
+    trailingBufferZone?: number;
+    proxy?: any;
+}
+declare class BufferedStore extends Base {
+    static $className: string;
+    private pageSize;
+    private leadingBufferZone;
+    private trailingBufferZone;
+    private proxyRef;
+    /** Page number → array of Model records for that page. */
+    private pageMap;
+    /** Total count from the server. */
+    private totalCount;
+    /** All loaded records in a flat sparse index. */
+    private recordMap;
+    /** Pages currently being fetched (to avoid duplicate requests). */
+    private pendingPages;
+    $destroyHooks: (() => void)[];
+    constructor(config: BufferedStoreConfig);
+    getPageSize(): number;
+    getCount(): number;
+    getTotalCount(): number;
+    getAt(index: number): Model | undefined;
+    isPageLoaded(pageNumber: number): boolean;
+    /**
+     * Ensures the given range [start, end] of row indices is loaded.
+     * Loads missing pages from the proxy and fires 'guaranteedrange'
+     * when the requested range is fully available.
+     */
+    guaranteeRange(start: number, end: number): Promise<void>;
+    private loadPage;
+    private prefetchBufferZones;
+    private fire;
+}
+
+/**
+ * @framesquared/data – GraphQLProxy
+ *
+ * Sends GraphQL queries for read and mutations for CUD operations.
+ * Parses response using a rootProperty path into the GraphQL data.
+ */
+
+interface GraphQLProxyConfig extends ProxyConfig {
+    url: string;
+    query?: string;
+    mutation?: string;
+    rootProperty?: string;
+    headers?: Record<string, string>;
+}
+declare class GraphQLProxy extends Proxy {
+    private url;
+    private query;
+    private mutation;
+    private rootProperty;
+    private headers;
+    constructor(config: GraphQLProxyConfig);
+    read(operation: Operation): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+    private doRequest;
+    private extractByPath;
+}
+
+/**
+ * @framesquared/data – WebSocketProxy
+ *
+ * Maintains a WebSocket connection for real-time data.  Sends
+ * CRUD operations as JSON messages.  Auto-reconnects on disconnect.
+ */
+
+interface WebSocketProxyConfig extends ProxyConfig {
+    url: string;
+    protocol?: string;
+    reconnect?: boolean;
+    reconnectInterval?: number;
+}
+declare class WebSocketProxy extends Proxy {
+    private url;
+    private reconnect;
+    private reconnectInterval;
+    private ws;
+    private listeners;
+    private intentionalClose;
+    private reconnectTimer;
+    constructor(config: WebSocketProxyConfig);
+    connect(): void;
+    disconnect(): void;
+    send(operation: Operation): void;
+    read(operation: Operation): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+    on(event: string, fn: Function): void;
+    off(event: string, fn: Function): void;
+    private fire;
+}
+
+/**
+ * @framesquared/data – BatchProxy
+ *
+ * Combines multiple operations into a single HTTP request.
+ * Unwraps the batch response into individual ResultSets.
+ */
+
+interface BatchProxyConfig extends ProxyConfig {
+    url: string;
+    headers?: Record<string, string>;
+}
+declare class BatchProxy extends Proxy {
+    private url;
+    private headers;
+    constructor(config: BatchProxyConfig);
+    /**
+     * Send multiple operations as a single batched request.
+     * Returns an array of ResultSets, one per operation.
+     */
+    sendBatch(operations: Operation[]): Promise<ResultSet[]>;
+    read(operation: Operation): Promise<ResultSet>;
+    create(operation: Operation): Promise<ResultSet>;
+    update(operation: Operation): Promise<ResultSet>;
+    destroy(operation: Operation): Promise<ResultSet>;
+}
+
+/**
+ * @framesquared/data – Connection
+ *
+ * Centralized fetch() wrapper.  Supports request and response
+ * interceptors, default headers, and global error handling.
+ */
+type RequestInterceptor = (url: string, init: RequestInit) => [string, RequestInit];
+type ResponseInterceptor = (response: any) => any;
+type ErrorHandler = (error: Error) => void;
+declare const Connection: {
+    /**
+     * Fetch with interceptors and default headers applied.
+     */
+    fetch(url: string, init?: RequestInit): Promise<any>;
+    addRequestInterceptor(fn: RequestInterceptor): void;
+    addResponseInterceptor(fn: ResponseInterceptor): void;
+    setDefaultHeaders(headers: Record<string, string>): void;
+    setErrorHandler(handler: ErrorHandler): void;
+    reset(): void;
+};
+
+/**
+ * @framesquared/data – Session
+ *
+ * Manages a set of related model instances.  Tracks all CRUD
+ * operations as a unit.  save() sends all changes via a BatchProxy.
+ * commit()/reject() clear tracked changes.
+ */
+
+interface SessionChanges {
+    create: Model[];
+    update: Model[];
+    destroy: Model[];
+}
+declare class Session {
+    private created;
+    private updated;
+    private destroyed;
+    trackCreate(record: Model): void;
+    trackUpdate(record: Model): void;
+    trackDestroy(record: Model): void;
+    getCreated(): Model[];
+    getUpdated(): Model[];
+    getDestroyed(): Model[];
+    getChanges(): SessionChanges;
+    isDirty(): boolean;
+    save(proxy: BatchProxy): Promise<{
+        success: boolean;
+        results: ResultSet[];
+    }>;
+    commit(): void;
+    reject(): void;
+    private recordKey;
+}
+
+export { AjaxProxy, type AjaxProxyConfig, ArrayReader, type ArrayReaderConfig, Association, type AssociationConfig, type AssociationType, AutoField, type Batch, type BatchOptions, BatchProxy, type BatchProxyConfig, BelongsTo, BooleanField, BufferedStore, type BufferedStoreConfig, Collection, Connection, DateField, Field, type FieldDefinition, FieldType, type Filter, type FilterOperator, FloatField, GraphQLProxy, type GraphQLProxyConfig, type Group, HasMany, HasOne, IntField, JsonReader, type JsonReaderConfig, JsonWriter, type JsonWriterConfig, LocalStorageProxy, ManyToMany, ManyToManyCollection, MemoryProxy, type MemoryProxyConfig, Model, ModelCollection, type NodeInterface, Operation, type OperationAction, type OperationConfig, Proxy, type ProxyConfig, RestProxy, type RestProxyConfig, ResultSet, type ResultSetConfig, Schema, Session, type SessionChanges, SessionStorageProxy, type Sorter, Store, type StoreConfig, StringField, TreeModel, TreeReader, type TreeReaderConfig, TreeStore, type TreeStoreConfig, TreeWriter, type TreeWriterConfig, type ValidationError, type ValidationResult, type Validator, WebSocketProxy, type WebSocketProxyConfig, type WebStorageProxyConfig, XmlReader, type XmlReaderConfig, XmlWriter, type XmlWriterConfig, applyNodeInterface, createField, email, exclusion, formatValidator, inclusion, length, presence, rangeValidator };