@legendapp/state 2.2.0-next.7 → 2.2.0-next.71

package/src/helpers.ts

@@ -0,0 +1,221 @@
+import { beginBatch, endBatch } from './batching';
+import { getNode, globalState, isObservable, setNodeValue, symbolDelete, symbolOpaque } from './globals';
+import { isArray, isEmpty, isFunction, isObject } from './is';
+import type { ObserveEvent, OpaqueObject, Selector, TypeAtPath } from './observableInterfaces';
+import type { Observable, ObservableParam } from './observableTypes';
+
+export function computeSelector<T>(selector: Selector<T>, e?: ObserveEvent<T>, retainObservable?: boolean) {
+    let c = selector as any;
+    if (!isObservable(c) && isFunction(c)) {
+        c = e ? c(e) : c();
+    }
+
+    return isObservable(c) && !retainObservable ? c.get() : c;
+}
+
+export function getObservableIndex(obs: ObservableParam): number {
+    const node = getNode(obs);
+    const n = +node.key! as number;
+    return n - n < 1 ? +n : -1;
+}
+
+export function opaqueObject<T extends object>(value: T): OpaqueObject<T> {
+    if (value) {
+        (value as OpaqueObject<T>)[symbolOpaque] = true;
+    }
+    return value as OpaqueObject<T>;
+}
+
+export function getValueAtPath(obj: Record<string, any>, path: string[]): any {
+    let o: Record<string, any> = obj;
+    for (let i = 0; o && i < path.length; i++) {
+        const p = path[i];
+        o = o[p];
+    }
+
+    return o;
+}
+
+export function setAtPath<T extends object>(
+    obj: T,
+    path: string[],
+    pathTypes: TypeAtPath[],
+    value: any,
+    mode?: 'set' | 'merge',
+    fullObj?: T,
+    restore?: (path: string[], value: any) => void,
+) {
+    let o: Record<string, any> = obj;
+    let oFull: Record<string, any> | undefined = fullObj;
+    let p: string | undefined = undefined;
+    if (path.length > 0) {
+        for (let i = 0; i < path.length; i++) {
+            p = path[i];
+            if (o[p] === symbolDelete) {
+                // If this was previously deleted, restore it
+                if (oFull) {
+                    o[p] = oFull[p];
+                    restore?.(path.slice(0, i + 1), o[p]);
+                }
+                return obj;
+            } else if (o[p] === undefined || o[p] === null) {
+                o[p] = initializePathType(pathTypes[i]);
+            }
+            if (i < path.length - 1) {
+                o = o[p];
+                if (oFull) {
+                    oFull = oFull[p];
+                }
+            }
+        }
+    }
+
+    // Don't set if the value is the same. This prevents creating a new key
+    // when setting undefined on an object without this key
+    if (p === undefined) {
+        if (mode === 'merge') {
+            obj = _mergeIntoObservable(obj, value);
+        } else {
+            obj = value;
+        }
+    } else {
+        if (mode === 'merge') {
+            o[p] = _mergeIntoObservable(o[p], value);
+        } else {
+            o[p] = value;
+        }
+    }
+
+    return obj;
+}
+export function setInObservableAtPath(
+    obs: ObservableParam,
+    path: string[],
+    pathTypes: TypeAtPath[],
+    value: any,
+    mode: 'assign' | 'set' | 'merge',
+) {
+    let o: Record<string, any> = obs;
+    let v = value;
+    for (let i = 0; i < path.length; i++) {
+        const p = path[i];
+        if (!o.peek()[p]) {
+            o[p].set(initializePathType(pathTypes[i]));
+        }
+        o = o[p];
+        v = v[p];
+    }
+
+    if (v === symbolDelete) {
+        (o as Observable).delete();
+    }
+    // Assign if possible, or set otherwise
+    else if (mode === 'assign' && (o as Observable).assign && isObject(o.peek())) {
+        (o as Observable<{}>).assign(v);
+    } else if (mode === 'merge') {
+        mergeIntoObservable(o, v);
+    } else {
+        o.set(v);
+    }
+}
+export function mergeIntoObservable<T extends ObservableParam<Record<string, any>> | object>(
+    target: T,
+    ...sources: any[]
+): T {
+    beginBatch();
+    globalState.isMerging = true;
+    for (let i = 0; i < sources.length; i++) {
+        target = _mergeIntoObservable(target, sources[i]);
+    }
+    globalState.isMerging = false;
+    endBatch();
+    return target;
+}
+function _mergeIntoObservable<T extends ObservableParam<Record<string, any>> | object>(target: T, source: any): T {
+    if (isObservable(source)) {
+        source = source.peek();
+    }
+    const needsSet = isObservable(target);
+    const targetValue = needsSet ? target.peek() : target;
+
+    const isTargetArr = isArray(targetValue);
+    const isTargetObj = !isTargetArr && isObject(targetValue);
+
+    if ((isTargetObj && isObject(source) && !isEmpty(targetValue)) || (isTargetArr && targetValue.length > 0)) {
+        const keys: string[] = Object.keys(source);
+
+        for (let i = 0; i < keys.length; i++) {
+            const key = keys[i];
+            const sourceValue = (source as Record<string, any>)[key];
+            if (sourceValue === symbolDelete) {
+                needsSet && (target as any)[key]?.delete
+                    ? (target as any)[key].delete()
+                    : delete (target as Record<string, any>)[key];
+            } else {
+                const isObj = isObject(sourceValue);
+                const isArr = !isObj && isArray(sourceValue);
+                const targetChild = (target as Record<string, any>)[key];
+                if ((isObj || isArr) && targetChild && (needsSet || !isEmpty(targetChild))) {
+                    if (!needsSet && (!targetChild || (isObj ? !isObject(targetChild) : !isArray(targetChild)))) {
+                        (target as Record<string, any>)[key] = sourceValue;
+                    } else {
+                        _mergeIntoObservable(targetChild, sourceValue);
+                    }
+                } else {
+                    needsSet
+                        ? targetChild.set(sourceValue)
+                        : (((target as Record<string, any>)[key] as any) = sourceValue);
+                }
+            }
+        }
+    } else if (source !== undefined) {
+        needsSet ? target.set(source) : ((target as any) = source);
+    }
+
+    return target;
+}
+export function constructObjectWithPath(path: string[], pathTypes: TypeAtPath[], value: any): object {
+    let out;
+    if (path.length > 0) {
+        let o: Record<string, any> = (out = {});
+        for (let i = 0; i < path.length; i++) {
+            const p = path[i];
+            o[p] = i === path.length - 1 ? value : initializePathType(pathTypes[i]);
+            o = o[p];
+        }
+    } else {
+        out = value;
+    }
+
+    return out;
+}
+export function deconstructObjectWithPath(path: string[], pathTypes: TypeAtPath[], value: any): object {
+    let o = value;
+    for (let i = 0; i < path.length; i++) {
+        const p = path[i];
+        o = o ? o[p] : initializePathType(pathTypes[i]);
+    }
+
+    return o;
+}
+export function isObservableValueReady(value: any) {
+    return !!value && ((!isObject(value) && !isArray(value)) || !isEmpty(value));
+}
+
+export function setSilently(obs: ObservableParam, newValue: any) {
+    const node = getNode(obs);
+    return setNodeValue(node, newValue).newValue;
+}
+
+export function initializePathType(pathType: TypeAtPath): any {
+    switch (pathType) {
+        case 'array':
+            return [];
+        case 'object':
+            return {};
+        case 'map':
+            return new Map();
+        case 'set':
+            return new Set();
+    }
+}

package/src/history/trackHistory.ts

@@ -0,0 +1,29 @@
+import { ObservableParam, constructObjectWithPath, mergeIntoObservable, observable } from '@legendapp/state';
+
+// This type is purely for documentation.
+type TimestampAsString = string;
+
+export function trackHistory<T>(
+    obs: ObservableParam<T>,
+    targetObservable?: ObservableParam<Record<TimestampAsString, Partial<T>>>,
+): ObservableParam<Record<TimestampAsString, any>> {
+    const history = targetObservable ?? observable<Record<TimestampAsString, Partial<T>>>();
+
+    obs.onChange(({ loading, remote, changes }) => {
+        // Don't save history if this is a remote change.
+        // History will be saved remotely by the client making the local change.
+        if (!loading && !remote) {
+            const time: TimestampAsString = Date.now().toString();
+
+            // Save to history observable by date, with the previous value
+            for (let i = 0; i < changes.length; i++) {
+                const { path, prevAtPath, pathTypes } = changes[i];
+
+                const obj = constructObjectWithPath(path, pathTypes, prevAtPath);
+                mergeIntoObservable((history as any)[time], obj);
+            }
+        }
+    });
+
+    return history as any;
+}

package/src/is.ts

@@ -0,0 +1,56 @@
+import type { ChildNodeValue, NodeValue } from './observableInterfaces';
+
+export const hasOwnProperty = Object.prototype.hasOwnProperty;
+
+export function isArray(obj: unknown): obj is Array<any> {
+    return Array.isArray(obj);
+}
+export function isString(obj: unknown): obj is string {
+    return typeof obj === 'string';
+}
+export function isObject(obj: unknown): obj is Record<any, any> {
+    return !!obj && typeof obj === 'object' && !(obj instanceof Date) && !isArray(obj);
+}
+export function isFunction(obj: unknown): obj is Function {
+    return typeof obj === 'function';
+}
+export function isPrimitive(arg: unknown): arg is string | number | bigint | boolean | symbol {
+    const type = typeof arg;
+    return arg !== undefined && (isDate(arg) || (type !== 'object' && type !== 'function'));
+}
+export function isDate(obj: unknown): obj is Date {
+    return obj instanceof Date;
+}
+export function isSymbol(obj: unknown): obj is symbol {
+    return typeof obj === 'symbol';
+}
+export function isBoolean(obj: unknown): obj is boolean {
+    return typeof obj === 'boolean';
+}
+export function isPromise<T>(obj: unknown): obj is Promise<T> {
+    return obj instanceof Promise;
+}
+export function isEmpty(obj: object): boolean {
+    // Looping and returning false on the first property is faster than Object.keys(obj).length === 0
+    // https://jsbench.me/qfkqv692c8
+    if (!obj) return false;
+    if (isArray(obj)) return obj.length === 0;
+    for (const key in obj) {
+        if (hasOwnProperty.call(obj, key)) {
+            return false;
+        }
+    }
+    return true;
+}
+export function isNullOrUndefined(value: any): value is undefined | null {
+    return value === undefined || value === null;
+}
+const setPrimitives = new Set(['boolean', 'string', 'number']);
+/** @internal */
+export function isActualPrimitive(arg: unknown): arg is boolean | string | number {
+    return setPrimitives.has(typeof arg);
+}
+/** @internal */
+export function isChildNodeValue(node: NodeValue): node is ChildNodeValue {
+    return !!node.parent;
+}

package/src/linked.ts

@@ -0,0 +1,6 @@
+import { symbolLinked } from './globals';
+import { Linked, LinkedOptions } from './observableInterfaces';
+
+export function linked<T>(params: LinkedOptions<T>): Linked<T> {
+    return (() => ({ [symbolLinked]: params })) as any;
+}

package/src/observable.ts

@@ -0,0 +1,32 @@
+import { extractPromise, getProxy, peekInternal } from './ObservableObject';
+import { ObservablePrimitiveClass } from './ObservablePrimitive';
+import { createObservable } from './createObservable';
+import { getNode } from './globals';
+import type { Observable, ObservableParam, ObservablePrimitive, RecursiveValueOrFunction } from './observableTypes';
+import type { ObservableSyncState } from './syncTypes';
+
+export function observable<T>(): Observable<T | undefined>;
+export function observable<T>(
+    value: Promise<RecursiveValueOrFunction<T>> | (() => RecursiveValueOrFunction<T>) | RecursiveValueOrFunction<T>,
+): Observable<T>;
+export function observable<T>(value: T): Observable<T>;
+export function observable<T>(value?: T): Observable<any> {
+    return createObservable(value, false, extractPromise, getProxy, ObservablePrimitiveClass) as any;
+}
+
+export function observablePrimitive<T>(value: Promise<T>): ObservablePrimitive<T>;
+export function observablePrimitive<T>(value?: T): ObservablePrimitive<T>;
+export function observablePrimitive<T>(value?: T | Promise<T>): ObservablePrimitive<T> {
+    return createObservable(value, true, extractPromise, getProxy, ObservablePrimitiveClass) as any;
+}
+
+export function syncState(obs: ObservableParam) {
+    const node = getNode(obs);
+    if (!node.state) {
+        peekInternal(node);
+    }
+    if (!node.state) {
+        node.state = observable({} as ObservableSyncState);
+    }
+    return node.state!;
+}

package/src/observableInterfaces.ts

@@ -0,0 +1,165 @@
+import type { symbolOpaque } from './globals';
+import type { Observable, ObservableParam } from './observableTypes';
+import { GetMode, ObservableSyncState, SyncedOptions } from './syncTypes';
+
+export type TrackingType = undefined | true | symbol; // true === shallow
+
+export interface GetOptions {
+    shallow: boolean;
+}
+
+export type OpaqueObject<T> = T & { [symbolOpaque]: true };
+
+export interface ListenerParams<T = any> {
+    value: T;
+    getPrevious: () => T;
+    changes: Change[];
+    remote: boolean;
+    /** @internal */
+    loading: boolean;
+}
+
+export type ListenerFn<T = any> = (params: ListenerParams<T>) => void;
+
+export interface ObservableEvent {
+    fire(): void;
+    on(cb?: () => void): ObservableListenerDispose;
+    get(): void;
+}
+
+export type TypeAtPath = 'object' | 'array' | 'map' | 'set';
+
+export interface Change {
+    path: string[];
+    pathTypes: TypeAtPath[];
+    valueAtPath: any;
+    prevAtPath: any;
+}
+
+export type RecordValue<T> = T extends Record<string, infer t> ? t : never;
+export type ArrayValue<T> = T extends Array<infer t> ? t : never;
+export type ObservableValue<T> = T extends Observable<infer t> ? t : never;
+
+export type Selector<T> = ObservableParam<T> | ObservableEvent | (() => T) | T;
+
+export type ClassConstructor<I, Args extends any[] = any[]> = new (...args: Args) => I;
+export type ObservableListenerDispose = () => void;
+
+export interface ObservableRoot {
+    _: any;
+    set?: (value: any) => void;
+}
+
+export type Primitive = boolean | string | number | Date;
+export type NotPrimitive<T> = T extends Primitive ? never : T;
+
+export interface NodeValueListener {
+    track: TrackingType;
+    noArgs?: boolean;
+    listener: ListenerFn;
+}
+export interface TrackingState {
+    nodes?: Map<NodeValue, TrackingNode>;
+    traceListeners?: (nodes: Map<NodeValue, TrackingNode>) => void;
+    traceUpdates?: (fn: Function) => Function;
+}
+
+interface BaseNodeValue {
+    children?: Map<string, ChildNodeValue>;
+    proxy?: object;
+    root: ObservableRoot;
+    listeners?: Set<NodeValueListener>;
+    listenersImmediate?: Set<NodeValueListener>;
+    isEvent?: boolean;
+    linkedToNode?: NodeValue;
+    linkedToNodeDispose?: () => void;
+    activatedObserveDispose?: () => void;
+    linkedFromNodes?: Set<NodeValue>;
+    isSetting?: number;
+    isAssigning?: number;
+    isComputing?: boolean;
+    parentOther?: NodeValue;
+    functions?: Map<string, Function | Observable<any>>;
+    lazy?: boolean;
+    lazyFn?: Function;
+    needsExtract?: boolean;
+    state?: Observable<ObservableSyncState>;
+    activated?: boolean;
+    activationState?: SyncedOptions & { onError?: () => void; persistedRetry?: boolean };
+    dirtyFn?: () => void;
+}
+
+export interface RootNodeValue extends BaseNodeValue {
+    parent?: undefined;
+    key?: undefined;
+}
+
+export interface ChildNodeValue extends BaseNodeValue {
+    parent: NodeValue;
+    key: string;
+}
+
+export type NodeValue = RootNodeValue | ChildNodeValue;
+
+export interface TrackingNode {
+    node: NodeValue;
+    track: TrackingType;
+    num: number;
+}
+export interface ObserveEvent<T> {
+    num: number;
+    previous?: T | undefined;
+    cancel?: boolean;
+    onCleanup?: () => void;
+}
+export interface ObserveEventCallback<T> {
+    num: number;
+    previous?: T | undefined;
+    value?: T;
+    cancel: boolean;
+    nodes: Map<NodeValue, TrackingNode> | undefined;
+    refresh: () => void;
+    onCleanup?: () => void;
+    onCleanupReaction?: () => void;
+}
+
+export type SetParams<T> = ListenerParams<T extends Promise<infer t> ? t : T>;
+
+export interface LinkedOptions<T = any> {
+    get?: () => Promise<T> | T;
+    set?: (params: SetParams<T>) => void | Promise<any>;
+    waitFor?: Selector<any>;
+    waitForSet?:
+        | ((params: { value: T; changes: Change[] }) => any)
+        | Promise<any>
+        | ObservableParam<any>
+        | ObservableEvent;
+    initial?: T extends Promise<infer t> ? t : T;
+}
+
+export interface UpdateFnParams {
+    value: unknown;
+    mode?: GetMode;
+    lastSync?: number | undefined;
+}
+export type UpdateFn = (params: UpdateFnParams) => void;
+export interface RetryOptions {
+    infinite?: boolean;
+    times?: number;
+    delay?: number;
+    backoff?: 'constant' | 'exponential';
+    maxDelay?: number;
+}
+
+export interface SubscribeOptions {
+    node: NodeValue;
+    update: UpdateFn;
+    refresh: () => void;
+}
+export interface CacheReturnValue {
+    lastSync: number;
+    value: any;
+}
+
+export type Synced<T> = T;
+export type Linked<T> = T;