enso
Version:
Maximalist state & form management library for React
395 lines • 14.7 kB
TypeScript
/**
* @module change
*
* State changes module. It defines event types, changes bit maps and helpers
* that help to identify the changes.
*/
/**
* Changes event class. It extends the native `Event` class and adds
* the `changes` property to it.
*/
export declare class ChangesEvent extends Event {
#private;
/**
* Batches changes events and dispatches them as a single event for each
* target after callstack is empty.
*
* @param target - Event target to dispatch the changes to.
* @param changes - Changes to dispatch.
*/
static batch(target: EventTarget, changes: AtomChange): void;
/**
* Provides context for the changes events. Nesting contexts will result
* in the context being merged.
*
* @param context - Context to assign.
*/
static context<Result>(context: ChangesEvent.Context, callback: () => Result): Result extends Promise<infer PromisedResult> ? Promise<PromisedResult> : Result;
/** Changes bitmask. */
changes: AtomChange;
/** Context record. */
context: ChangesEvent.Context;
/**
* Creates a new changes event.
*
* @param changes - Changes that happened.
*/
constructor(changes: AtomChange, context?: ChangesEvent.Context);
}
export declare namespace ChangesEvent {
type Batch = Map<EventTarget, [AtomChange, Context]>;
type Context = Record<string | number | symbol, any>;
}
/**
* Atom change type. It aliases the `bigint` type to represent the changes
* type.
*/
export type AtomChange = bigint;
/**
* Structural changes bits. It defines the allocate size for the structural
* changes. It allows to access the structural changes bits range.
*/
export declare const structuralChangesBits = 8n;
/**
* Meta changes bits. It defines the allocate size for the meta changes. It
* allows to access the meta changes bits range which goes after the structural
* changes.
*/
export declare const metaChangesBits = 8n;
/**
* Allocated change bits.
*/
export declare const changesBits: bigint;
/**
* Allocated core changes bits. It defines the allocated bits for the core
* changes. It allows extensions to allocate additional bits for their own
* changes after the core changes.
*/
export declare const coreChangesBits: bigint;
/**
* Atom changes mask. It allows to isolate the atom changes bits.
*/
export declare const atomChangesMask: bigint;
/**
* Structural atom changes mask. It allows to isolate the structural atom
* changes bits.
*/
export declare const structuralAtomChangesMask: bigint;
/**
* Meta atom changes mask. It allows to isolate the meta atom changes bits.
*/
export declare const metaAtomChangesMask: bigint;
/**
* Atom changes map.
*
* It represents the changes for the atom itself.
*/
export declare const atomChange: {
/** Atom id changed. It happens when the atom watched by a hook is replaced
* with a new atom. */
id: bigint;
/** Atom key changed. It indicates that the atom got moved. It doesn't
* apply to the atom getting detached and attached. */
key: bigint;
/** Current atom value committed as initial. */
commit: bigint;
/** Atom value reset to initial. */
reset: bigint;
/** Atom become invalid. */
invalid: bigint;
/** Atom become valid. */
valid: bigint;
/** Errors change. A new error was inserted or removed. */
errors: bigint;
/** Atom lost focus. */
blur: bigint;
/** Atom type changed. It indicates that atom type(array/object/number/etc.)
* is now different. */
type: bigint;
/** Atom value changed. It applies only to primitive atom type as
* object/array atoms value is a reference. */
value: bigint;
/** Atom attached (inserted) to object/array. Before it gets created
* the atom might be in the detached state. */
attach: bigint;
/** Atom detached from object/array. Rather than removing, the atom will
* be in detached state and won't receive any updates until it gets attached
* again. */
detach: bigint;
/** Shape of object/array changed. It means one of the following: a child
* got attached, detached or moved. */
shape: bigint;
};
/**
* Atom change map. It maps the human-readable atom change names to
* the corresponding bit mask.
*/
export type AtomChangeMap = typeof atomChange;
/**
* Child changes shift.
*/
export declare const childChangesShift: bigint;
/**
* Child changes bits mask. It allows to isolate the child changes bits.
*/
export declare const childChangesMask: bigint;
/**
* Structural child changes mask. It allows to isolate the structural child
* changes bits.
*/
export declare const structuralChildChangesMask: bigint;
/**
* Meta child changes mask. It allows to isolate the meta child changes bits.
*/
export declare const metaChildChangesMask: bigint;
/**
* Child changes map.
*
* It represents the changes for the immediate children of the atom.
*/
export declare const childChange: AtomChangeMap;
/**
* Subtree changes shift.
*/
export declare const subtreeChangesShift: bigint;
/**
* Subtree changes bits mask. It allows to isolate the subtree changes bits.
*/
export declare const subtreeChangesMask: bigint;
/**
* Structural subtree changes mask. It allows to isolate the structural subtree
* changes bits.
*/
export declare const structuralSubtreeChangesMask: bigint;
/**
* Meta subtree changes mask. It allows to isolate the meta subtree changes
* bits.
*/
export declare const metaSubtreeChangesMask: bigint;
/**
* Subtree changes map.
*
* It represents the changes for the deeply nested children of the atom.
*/
export declare const subtreeChange: AtomChangeMap;
/**
* Structural changes mask. It allows to isolate the structural changes bits on
* all levels.
*/
export declare const structuralChangesMask: bigint;
/**
* Meta changes mask. It allows to isolate the meta changes bits on all levels.
*/
export declare const metaChangesMask: bigint;
/**
* Atom changes map. Each bit indicates a certain type of change in the atom.
*
* The changes are represented as a bit mask, which allows to combine multiple
* change types into a single value. BigInt is used to represent the changes
* as bitwise operations on numbers convert their operands to 32-bit integers
* and limit the available bits range.
*
* All changes are divided into three main categories:
*
* - **Atom changes** that affect the atom itself.
* - **Child changes** that affect the immediate children of the atom.
* - **Subtree changes** that affect the deeply nested children of the atom.
*
* We allocate first 48 bits (16*3) for the category changes.
*
* Each category bit further divided into subcategories (8 bits each):
*
* - **Structural changes** that affect the inner value of the atom.
* - **Meta changes** that affect the meta state of the atom.
*
* Here is the visual representation of the changes map:
*
* Subtree Child Atom
* v v v
* 0b000000000000000000000000000000000000000000000000n
* ^ ^ ^ ^ ^ ^
* Meta Struct. Meta Struct. Meta Struct.
*
* The structural atom changes range is exclusive meaning that only one of
* the flags can be set at a time. This allows to simplify the logic and
* make it easier to understand. Initially that was not the case and
* `detach` and `attach` flags were always set with `type` change, but this
* logic warrants always setting `value` flag as well. The possible combinations
* made it harder to understand and test the logic, so it was decided to make
* the structural changes exclusive.
*
* The meta atom changes as well as any child and subtree changes are not
* exclusive and can be combined, as there might be multiple children having
* conflicting changes i.e. `detach` and `attach` at the same time.
*/
export declare const change: {
/** Atom changes that affect the atom itself. */
atom: {
/** Atom id changed. It happens when the atom watched by a hook is replaced
* with a new atom. */
id: bigint;
/** Atom key changed. It indicates that the atom got moved. It doesn't
* apply to the atom getting detached and attached. */
key: bigint;
/** Current atom value committed as initial. */
commit: bigint;
/** Atom value reset to initial. */
reset: bigint;
/** Atom become invalid. */
invalid: bigint;
/** Atom become valid. */
valid: bigint;
/** Errors change. A new error was inserted or removed. */
errors: bigint;
/** Atom lost focus. */
blur: bigint;
/** Atom type changed. It indicates that atom type(array/object/number/etc.)
* is now different. */
type: bigint;
/** Atom value changed. It applies only to primitive atom type as
* object/array atoms value is a reference. */
value: bigint;
/** Atom attached (inserted) to object/array. Before it gets created
* the atom might be in the detached state. */
attach: bigint;
/** Atom detached from object/array. Rather than removing, the atom will
* be in detached state and won't receive any updates until it gets attached
* again. */
detach: bigint;
/** Shape of object/array changed. It means one of the following: a child
* got attached, detached or moved. */
shape: bigint;
};
/** Child changes that affect the immediate children of the atom. */
child: {
/** Atom id changed. It happens when the atom watched by a hook is replaced
* with a new atom. */
id: bigint;
/** Atom key changed. It indicates that the atom got moved. It doesn't
* apply to the atom getting detached and attached. */
key: bigint;
/** Current atom value committed as initial. */
commit: bigint;
/** Atom value reset to initial. */
reset: bigint;
/** Atom become invalid. */
invalid: bigint;
/** Atom become valid. */
valid: bigint;
/** Errors change. A new error was inserted or removed. */
errors: bigint;
/** Atom lost focus. */
blur: bigint;
/** Atom type changed. It indicates that atom type(array/object/number/etc.)
* is now different. */
type: bigint;
/** Atom value changed. It applies only to primitive atom type as
* object/array atoms value is a reference. */
value: bigint;
/** Atom attached (inserted) to object/array. Before it gets created
* the atom might be in the detached state. */
attach: bigint;
/** Atom detached from object/array. Rather than removing, the atom will
* be in detached state and won't receive any updates until it gets attached
* again. */
detach: bigint;
/** Shape of object/array changed. It means one of the following: a child
* got attached, detached or moved. */
shape: bigint;
};
/** Subtree changes that affect the deeply nested children of the atom. */
subtree: {
/** Atom id changed. It happens when the atom watched by a hook is replaced
* with a new atom. */
id: bigint;
/** Atom key changed. It indicates that the atom got moved. It doesn't
* apply to the atom getting detached and attached. */
key: bigint;
/** Current atom value committed as initial. */
commit: bigint;
/** Atom value reset to initial. */
reset: bigint;
/** Atom become invalid. */
invalid: bigint;
/** Atom become valid. */
valid: bigint;
/** Errors change. A new error was inserted or removed. */
errors: bigint;
/** Atom lost focus. */
blur: bigint;
/** Atom type changed. It indicates that atom type(array/object/number/etc.)
* is now different. */
type: bigint;
/** Atom value changed. It applies only to primitive atom type as
* object/array atoms value is a reference. */
value: bigint;
/** Atom attached (inserted) to object/array. Before it gets created
* the atom might be in the detached state. */
attach: bigint;
/** Atom detached from object/array. Rather than removing, the atom will
* be in detached state and won't receive any updates until it gets attached
* again. */
detach: bigint;
/** Shape of object/array changed. It means one of the following: a child
* got attached, detached or moved. */
shape: bigint;
};
};
/**
* Shifts atom changes to child changes. The subtree changes get merged with
* existing subtree changes.
*
* @param changes - Changes to shift.
*/
export declare function shiftChildChanges(changes: AtomChange): AtomChange;
/**
* Isolates the atom changes from the changes map.
*
* @param changes - Changes to isolate the atom changes from.
* @returns Isolated atom changes.
*/
export declare function isolateAtomChanges(changes: AtomChange): AtomChange;
/**
* Isolates the child changes from the changes map.
*
* @param changes - Changes to isolate the child changes from.
* @returns Isolated child changes.
*/
export declare function isolateChildChanges(changes: AtomChange): AtomChange;
/**
* Isolates the atom changes from the changes map.
*
* @param changes - Changes to isolate the subtree changes from.
* @returns Isolated subtree changes.
*/
export declare function isolateSubtreeChanges(changes: AtomChange): AtomChange;
/**
* Checks if child changes affect atom shape and returns shape change if so.
*
* @param changes - Changes to check.
* @returns Shape change if child changes affect atom shape or `0n` otherwise.
*/
export declare function shapeChanges(changes: AtomChange): AtomChange;
/**
* Isolates structural changes.
*
* @param changes - Changes to check.
* @returns Isolates structural changes if found or `0n` otherwise.
*/
export declare function structuralChanges(changes: AtomChange): AtomChange;
/**
* Isolates meta changes.
*
* @param changes - Changes to check
* @returns Isolated meta changes if found or `0n` otherwise.
*/
export declare function metaChanges(changes: AtomChange): AtomChange;
/**
* Checks if changes contain any of changes in the given mask.
*
* @param changes - Changes to check.
* @param mask - Changes mask to check against.
* @returns Detected changes if found or `0n` otherwise.
*/
export declare function maskedChanges(changes: AtomChange, mask: AtomChange): AtomChange;
//# sourceMappingURL=index.d.ts.map