dotvvm-types 4.3.4 → 4.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotvvm-types",
-  "version": "4.3.4",
+  "version": "4.3.6",
   "description": "MVVM framework for ASP.NET",
   "types": "./types/index.d.ts",
   "repository": {

package/types/index.d.ts

@@ -212,6 +212,8 @@ declare module "validation/error" {
 }
 declare module "state-manager" {
     import { DotvvmEvent } from "events";
+    import { ValidationError } from "validation/error";
+    import { errorsSymbol } from "validation/common";
     export const currentStateSymbol: unique symbol;
     export const notifySymbol: unique symbol;
     export const lastSetErrorSymbol: unique symbol;
@@ -224,29 +226,69 @@ declare module "state-manager" {
         [currentStateSymbol]: T;
         [updateSymbol]?: UpdateDispatcher<T>;
     };
+    /** Manages the consistency of DotVVM immutable ViewModel state object with the knockout observables.
+     * Knockout observables are by-default updated asynchronously after a state change, but the synchronization can be forced by calling `doUpdateNow`.
+     * The newState event is also called asynchronously right before the knockout observables are updated.
+     * Changes from observables to state are immediate.
+     */
     export class StateManager<TViewModel extends {
         $type?: TypeDefinition;
-    }> {
+    }> implements DotvvmStateContainer<TViewModel> {
         stateUpdateEvent: DotvvmEvent<DeepReadonly<TViewModel>>;
+        /** The knockout observable containing the root objects, equivalent to `dotvvm.viewModels.root.viewModel` */
         readonly stateObservable: DeepKnockoutObservable<TViewModel>;
         private _state;
+        /** Returns the current  */
         get state(): DeepReadonly<TViewModel>;
         private _isDirty;
+        /** Indicates whether there is a pending update of the knockout observables. */
         get isDirty(): boolean;
         private _currentFrameNumber;
         constructor(initialState: DeepReadonly<TViewModel>, stateUpdateEvent: DotvvmEvent<DeepReadonly<TViewModel>>);
-        dispatchUpdate(): void;
+        private dispatchUpdate;
+        /** Performs a synchronous update of knockout observables with the data currently stored in `state`.
+         *  Consequently, if ko.options.deferUpdates is false (default), the UI will be updated immediately.
+         *  If ko.options.deferUpdates is true, the UI can be manually updated by also calling the `ko.tasks.runEarly()` function. */
         doUpdateNow(): void;
         private rerender;
+        /** Sets a new view model state, after checking its type compatibility and possibly performing implicit conversions.
+         *  Only the changed objects are re-checked and updated in the knockout observables.
+         *  It is therefore recommended to clone only the changed parts of the view model using the `{... x, ChangedProp: 1 }` syntax.
+         *  In the rarely occuring complex cases where this is difficult, you can use `structuredClone` to obtain a writable clone of some part of the viewmodel.
+         *
+         *  @throws CoerceError if the new state has incompatible type.
+         *  @returns The type-coerced version of the new state. */
         setState(newState: DeepReadonly<TViewModel>): DeepReadonly<TViewModel>;
-        patchState(patch: Partial<TViewModel>): DeepReadonly<TViewModel>;
-        update(updater: StateUpdate<TViewModel>): DeepReadonly<TViewModel>;
+        /** Applies a patch to the current view model state.
+         *  @throws CoerceError if the new state has incompatible type.
+         *  @returns The type-coerced version of the new state. */
+        patchState(patch: DeepReadonly<DeepPartial<TViewModel>>): DeepReadonly<TViewModel>;
+        /** Updates the view model state using the provided `State => State` function.
+         *  @throws CoerceError if the new state has incompatible type.
+         *  @returns The type-coerced version of the new state.  */
+        updateState(updater: StateUpdate<TViewModel>): DeepReadonly<TViewModel>;
+        /** @deprecated Use updateState method instead */
+        update: UpdateDispatcher<TViewModel>;
+    }
+    class FakeObservableObject<T extends object> implements UpdatableObjectExtensions<T> {
+        [currentStateSymbol]: T;
+        [errorsSymbol]: Array<ValidationError>;
+        [updateSymbol]: UpdateDispatcher<T>;
+        [notifySymbol](newValue: T): void;
+        [internalPropCache]: {
+            [name: string]: (KnockoutObservable<any> & UpdatableObjectExtensions<any>) | null;
+        };
+        [updatePropertySymbol](propName: keyof DeepReadonly<T>, valUpdate: StateUpdate<any>): void;
+        constructor(initialValue: T, getter: () => DeepReadonly<T> | undefined, updater: UpdateDispatcher<T>, typeId: TypeDefinition, typeInfo: ObjectTypeMetadata | DynamicTypeMetadata | undefined, additionalProperties: string[]);
     }
+    export function isDotvvmObservable(obj: any): obj is DotvvmObservable<any>;
+    export function isFakeObservableObject(obj: any): obj is FakeObservableObject<any>;
     /**
      * Recursively unwraps knockout observables from the object / array hierarchy. When nothing needs to be unwrapped, the original object is returned.
      * @param allowStateUnwrap Allows accessing [currentStateSymbol], which makes it faster, but doesn't register in the knockout dependency tracker
+     * @param preferStateAccess Also allows accessing observable.state, which also doesn't register in the knockout dependency tracker, but returns an realtime updated value directly from dotvvm.state
     */
-    export function unmapKnockoutObservables(viewModel: any, allowStateUnwrap?: boolean): any;
+    export function unmapKnockoutObservables(viewModel: any, allowStateUnwrap?: boolean, preferStateAccess?: boolean): any;
 }
 declare module "serialization/deserialize" {
     export function deserialize(viewModel: any, target?: any, deserializeAll?: boolean): any;
@@ -887,6 +929,7 @@ declare module "dotvvm-root" {
         patchState(a: any): void;
         setState(a: any): void;
         updateState(updateFunction: StateUpdate<any>): void;
+        readonly rootStateManager: StateManager<RootViewModel>;
         viewModelObservables: {
             readonly root: KnockoutObservable<DeepKnockoutObservableObject<RootViewModel>>;
         };