mobx-keystone 0.67.4 → 0.68.1-alpha

package/src/dist/parent/findParent.d.ts

@@ -0,0 +1,41 @@
+import type { Path } from "./pathTypes";
+/**
+ * Iterates through all the parents (from the nearest until the root)
+ * until one of them matches the given predicate.
+ * If the predicate is matched it will return the found node.
+ * If none is found it will return undefined.
+ *
+ * @typeparam T Parent object type.
+ * @param child Target object.
+ * @param predicate Function that will be run for every parent of the target object, from immediate parent to the root.
+ * @param maxDepth Max depth, or 0 for infinite.
+ * @returns
+ */
+export declare function findParent<T extends object = any>(child: object, predicate: (parentNode: object) => boolean, maxDepth?: number): T | undefined;
+/**
+ * Result of `findParentPath`.
+ */
+export interface FoundParentPath<T extends object> {
+    /**
+     * Found parent object.
+     */
+    readonly parent: T;
+    /**
+     * Path from the found parent to the child.
+     */
+    readonly path: Path;
+}
+/**
+ * Iterates through all the parents (from the nearest until the root)
+ * until one of them matches the given predicate.
+ * If the predicate is matched it will return the found node plus the
+ * path to get from the parent to the child.
+ * If none is found it will return undefined.
+ *
+ * @typeparam T Parent object type.
+ * @param child Target object.
+ * @param predicate Function that will be run for every parent of the target object, from immediate parent to the root.
+ * @param maxDepth Max depth, or 0 for infinite.
+ * @returns
+ */
+export declare function findParentPath<T extends object = any>(child: object, predicate: (parentNode: object) => boolean, maxDepth?: number): FoundParentPath<T> | undefined;

package/src/dist/parent/getChildrenObjects.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns all the children objects (this is, excluding primitives) of an object.
+ *
+ * @param node Object to get the list of children from.
+ * @param [options] An optional object with the `deep` option (defaults to false) to true to get
+ * the children deeply or false to get them shallowly.
+ * @returns A readonly observable set with the children.
+ */
+export declare function getChildrenObjects(node: object, options?: {
+    deep?: boolean;
+}): ReadonlySet<object>;

package/src/dist/parent/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./detach";
+export * from "./findChildren";
+export * from "./findParent";
+export * from "./getChildrenObjects";
+export * from "./onChildAttachedTo";
+export * from "./path";
+export * from "./path2";
+export * from "./pathTypes";
+export * from "./walkTree";

package/src/dist/parent/onChildAttachedTo.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runs a callback everytime a new object is attached to a given node.
+ * The callback can optionally return a disposer which will be run when the child is detached.
+ *
+ * The optional options parameter accepts and object with the following options:
+ * - `deep: boolean` (default: `false`) - true if the callback should be run for all children deeply
+ * or false if it it should only run for shallow children.
+ * - `fireForCurrentChildren: boolean` (default: `true`) - true if the callback should be immediately
+ * called for currently attached children, false if only for future attachments.
+ *
+ * Returns a disposer, which has a boolean parameter which should be true if pending detachment
+ * callbacks should be run or false otherwise.
+ *
+ * @param target Function that returns the object whose children should be tracked.
+ * @param fn Callback called when a child is attached to the target object.
+ * @param [options]
+ * @returns
+ */
+export declare function onChildAttachedTo(target: () => object, fn: (child: object) => (() => void) | void, options?: {
+    deep?: boolean;
+    fireForCurrentChildren?: boolean;
+}): (runDetachDisposers: boolean) => void;

package/src/dist/parent/path.d.ts

@@ -0,0 +1,107 @@
+import type { Path, PathElement } from "./pathTypes";
+/**
+ * Path from an object to its immediate parent.
+ *
+ * @typeparam T Parent object type.
+ */
+export interface ParentPath<T extends object> {
+    /**
+     * Parent object.
+     */
+    readonly parent: T;
+    /**
+     * Property name (if the parent is an object) or index number (if the parent is an array).
+     */
+    readonly path: PathElement;
+}
+/**
+ * Path from an object to its root.
+ *
+ * @typeparam T Root object type.
+ */
+export interface RootPath<T extends object> {
+    /**
+     * Root object.
+     */
+    readonly root: T;
+    /**
+     * Path from the root to the given target, as a string array.
+     * If the target is a root itself then the array will be empty.
+     */
+    readonly path: Path;
+    /**
+     * Objects in the path, from root (included) until target (included).
+     * If the target is a root then only the target will be included.
+     */
+    readonly pathObjects: ReadonlyArray<unknown>;
+}
+/**
+ * Returns the parent of the target plus the path from the parent to the target, or undefined if it has no parent.
+ *
+ * @typeparam T Parent object type.
+ * @param value Target object.
+ * @returns
+ */
+export declare function getParentPath<T extends object = any>(value: object): ParentPath<T> | undefined;
+/**
+ * Returns the parent object of the target object, or undefined if there's no parent.
+ *
+ * @typeparam T Parent object type.
+ * @param value Target object.
+ * @returns
+ */
+export declare function getParent<T extends object = any>(value: object): T | undefined;
+/**
+ * Returns if a given object is a model interim data object (`$`).
+ *
+ * @param value Object to check.
+ * @returns true if it is, false otherwise.
+ */
+export declare function isModelDataObject(value: object): boolean;
+/**
+ * Returns the root of the target plus the path from the root to get to the target.
+ *
+ * @typeparam T Root object type.
+ * @param value Target object.
+ * @returns
+ */
+export declare function getRootPath<T extends object = any>(value: object): RootPath<T>;
+/**
+ * Returns the root of the target object, or itself if the target is a root.
+ *
+ * @typeparam T Root object type.
+ * @param value Target object.
+ * @returns
+ */
+export declare function getRoot<T extends object = any>(value: object): T;
+/**
+ * Returns if a given object is a root object.
+ *
+ * @param value Target object.
+ * @returns
+ */
+export declare function isRoot(value: object): boolean;
+/**
+ * Tries to resolve a path from an object.
+ *
+ * @typeparam T Returned value type.
+ * @param pathRootObject Object that serves as path root.
+ * @param path Path as an string or number array.
+ * @returns An object with `{ resolved: true, value: T }` or `{ resolved: false }`.
+ */
+export declare function resolvePath<T = any>(pathRootObject: object, path: Path): {
+    resolved: true;
+    value: T;
+} | {
+    resolved: false;
+    value?: undefined;
+};
+/**
+ * Gets the path to get from a parent to a given child.
+ * Returns an empty array if the child is actually the given parent or undefined if the child is not a child of the parent.
+ *
+ * @param fromParent
+ * @param toChild
+ * @returns
+ */
+export declare function getParentToChildPath(fromParent: object, toChild: object): Path | undefined;

package/src/dist/parent/path2.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Returns if the target is a "child" of the tree of the given "parent" object.
+ *
+ * @param child Target object.
+ * @param parent Parent object.
+ * @returns
+ */
+export declare function isChildOfParent(child: object, parent: object): boolean;
+/**
+ * Returns if the target is a "parent" that has in its tree the given "child" object.
+ *
+ * @param parent Target object.
+ * @param child Child object.
+ * @returns
+ */
+export declare function isParentOfChild(parent: object, child: object): boolean;

package/src/dist/parent/pathTypes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Property name (if the parent is an object) or index number (if the parent is an array).
+ */
+export declare type PathElement = string | number;
+/**
+ * Path from a parent to a child.
+ */
+export declare type Path = ReadonlyArray<string | number>;
+/**
+ * Path from a parent to a child (writable).
+ */
+export declare type WritablePath = (string | number)[];

package/src/dist/parent/setParent.d.ts

@@ -0,0 +1 @@
+export {};

package/src/dist/parent/walkTree.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Mode for the `walkTree` method.
+ */
+export declare enum WalkTreeMode {
+    /**
+     * The walk will be done parent (roots) first, then children.
+     */
+    ParentFirst = "parentFirst",
+    /**
+     * The walk will be done children (leafs) first, then parents.
+     */
+    ChildrenFirst = "childrenFirst"
+}
+/**
+ * Walks a tree, running the predicate function for each node.
+ * If the predicate function returns something other than undefined,
+ * then the walk will be stopped and the function will return the returned value.
+ *
+ * @typeparam T Returned object type, defaults to void.
+ * @param root Subtree root object.
+ * @param visit Function that will be run for each node of the tree.
+ * @param mode Mode to walk the tree, as defined in `WalkTreeMode`.
+ * @returns
+ */
+export declare function walkTree<T = void>(root: object, visit: (node: object) => T | undefined, mode: WalkTreeMode): T | undefined;

package/src/dist/patch/Patch.d.ts

@@ -0,0 +1,16 @@
+import type { Path } from "../parent/pathTypes";
+export declare type Patch = PatchAddOperation<any> | PatchRemoveOperation | PatchReplaceOperation<any>;
+export interface PatchBaseOperation {
+    path: Path;
+}
+export interface PatchAddOperation<T> extends PatchBaseOperation {
+    op: "add";
+    value: T;
+}
+export interface PatchRemoveOperation extends PatchBaseOperation {
+    op: "remove";
+}
+export interface PatchReplaceOperation<T> extends PatchBaseOperation {
+    op: "replace";
+    value: T;
+}

package/src/dist/patch/applyPatches.d.ts

@@ -0,0 +1,9 @@
+import type { Patch } from "../patch/Patch";
+/**
+ * Applies the given patches to the given target object.
+ *
+ * @param node Target object.
+ * @param patches List of patches to apply.
+ * @param reverse Whether patches are applied in reverse order.
+ */
+export declare function applyPatches(node: object, patches: ReadonlyArray<Patch> | ReadonlyArray<ReadonlyArray<Patch>>, reverse?: boolean): void;

package/src/dist/patch/emitPatch.d.ts

@@ -0,0 +1,29 @@
+import type { Patch } from "./Patch";
+/**
+ * A function that gets called when a patch is emitted.
+ */
+export declare type OnPatchesListener = (patches: Patch[], inversePatches: Patch[]) => void;
+/**
+ * A function that gets called when a global patch is emitted.
+ */
+export declare type OnGlobalPatchesListener = (target: object, patches: Patch[], inversePatches: Patch[]) => void;
+/**
+ * Disposer function to stop listening to patches.
+ */
+export declare type OnPatchesDisposer = () => void;
+/**
+ * Adds a listener that will be called every time a patch is generated for the tree of the given target object.
+ *
+ * @param subtreeRoot Subtree root object of the patch listener.
+ * @param listener The listener function that will be called everytime a patch is generated for the object or its children.
+ * @returns A disposer to stop listening to patches.
+ */
+export declare function onPatches(subtreeRoot: object, listener: OnPatchesListener): OnPatchesDisposer;
+/**
+ * Adds a listener that will be called every time a patch is generated anywhere.
+ * Usually prefer using `onPatches`.
+ *
+ * @param listener The listener function that will be called everytime a patch is generated anywhere.
+ * @returns A disposer to stop listening to patches.
+ */
+export declare function onGlobalPatches(listener: OnGlobalPatchesListener): OnPatchesDisposer;

package/src/dist/patch/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./applyPatches";
+export * from "./emitPatch";
+export * from "./jsonPatch";
+export * from "./Patch";
+export * from "./patchRecorder";

package/src/dist/patch/jsonPatch.d.ts

@@ -0,0 +1,45 @@
+import type { Path } from "../parent/pathTypes";
+import type { Patch } from "./Patch";
+export declare type JsonPatch = JsonPatchAddOperation<any> | JsonPatchRemoveOperation | JsonPatchReplaceOperation<any>;
+export interface JsonPatchBaseOperation {
+    path: string;
+}
+export interface JsonPatchAddOperation<T> extends JsonPatchBaseOperation {
+    op: "add";
+    value: T;
+}
+export interface JsonPatchRemoveOperation extends JsonPatchBaseOperation {
+    op: "remove";
+}
+export interface JsonPatchReplaceOperation<T> extends JsonPatchBaseOperation {
+    op: "replace";
+    value: T;
+}
+/**
+ * Converts a path into a JSON pointer.
+ *
+ * @param path Path to convert.
+ * @returns Converted JSON pointer.
+ */
+export declare function pathToJsonPointer(path: Path): string;
+/**
+ * Converts a JSON pointer into a path.
+ *
+ * @param jsonPointer JSON pointer to convert.
+ * @returns Converted path.
+ */
+export declare function jsonPointerToPath(jsonPointer: string): Path;
+/**
+ * Convert a patch into a JSON patch.
+ *
+ * @param patch A patch.
+ * @returns A JSON patch.
+ */
+export declare function patchToJsonPatch(patch: Patch): JsonPatch;
+/**
+ * Converts a JSON patch into a patch.
+ *
+ * @param jsonPatch A JSON patch.
+ * @returns A patch.
+ */
+export declare function jsonPatchToPatch(jsonPatch: JsonPatch): Patch;

package/src/dist/patch/patchRecorder.d.ts

@@ -0,0 +1,70 @@
+import { OnPatchesListener } from "./emitPatch";
+import type { Patch } from "./Patch";
+/**
+ * Patch recorder event.
+ */
+export interface PatchRecorderEvent {
+    /**
+     * Target object.
+     */
+    readonly target: object;
+    /**
+     * Recorded patches.
+     */
+    readonly patches: Patch[];
+    /**
+     * Recorded inverse patches.
+     */
+    readonly inversePatches: Patch[];
+}
+/**
+ * Patch recorder interface.
+ */
+export interface PatchRecorder {
+    /**
+     * Gets/sets if the patch recorder is currently recording.
+     */
+    recording: boolean;
+    /**
+     * Observable array of patching events.
+     */
+    readonly events: PatchRecorderEvent[];
+    /**
+     * Dispose of the patch recorder.
+     */
+    dispose(): void;
+}
+/**
+ * Patch recorder options.
+ */
+export interface PatchRecorderOptions {
+    /**
+     * If the patch recorder is initially recording when created.
+     */
+    recording?: boolean;
+    /**
+     * An optional callback filter to select wich patches to record/skip.
+     * It will be executed before the event is added to the events list.
+     *
+     * @param patches Patches about to be recorded.
+     * @param inversePatches Inverse patches about to be recorded.
+     * @returns `true` to record the patch, `false` to skip it.
+     */
+    filter?(patches: Patch[], inversePatches: Patch[]): boolean;
+    /**
+     * An optional callback run once a patch is recorded.
+     * It will be executed after the event is added to the events list.
+     *
+     * @param patches Patches just recorded.
+     * @param inversePatches Inverse patches just recorded.
+     */
+    onPatches?: OnPatchesListener;
+}
+/**
+ * Creates a patch recorder.
+ *
+ * @param subtreeRoot
+ * @param [opts]
+ * @returns The patch recorder.
+ */
+export declare function patchRecorder(subtreeRoot: object, opts?: PatchRecorderOptions): PatchRecorder;

package/src/dist/redux/connectReduxDevTools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Connects a tree node to a redux dev tools instance.
+ *
+ * @param remotedevPackage The remotedev package (usually the result of `require("remoteDev")`) (https://www.npmjs.com/package/remotedev).
+ * @param remotedevConnection The result of a connect method from the remotedev package (usually the result of `remoteDev.connectViaExtension(...)`).
+ * @param target Object to use as root.
+ * @param storeName Name to be shown in the redux dev tools.
+ * @param [options] Optional options object. `logArgsNearName` if it should show the arguments near the action name (default is `true`).
+ */
+export declare function connectReduxDevTools(remotedevPackage: any, remotedevConnection: any, target: object, options?: {
+    logArgsNearName?: boolean;
+}): void;

package/src/dist/redux/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./connectReduxDevTools";
+export * from "./redux";

package/src/dist/redux/redux.d.ts

@@ -0,0 +1,47 @@
+import { ActionCall } from "../action";
+import { OnSnapshotDisposer, OnSnapshotListener } from "../snapshot/onSnapshot";
+import type { SnapshotOutOf } from "../snapshot/SnapshotOf";
+export declare const reduxActionType = "applyAction";
+/**
+ * A redux action for mobx-keystone.
+ */
+export interface ReduxAction {
+    readonly type: typeof reduxActionType;
+    readonly payload: ActionCall;
+}
+/**
+ * Transforms an action call into a redux action.
+ *
+ * @param actionCall Action call.
+ * @returns A redux action.
+ */
+export declare function actionCallToReduxAction(actionCall: ActionCall): ReduxAction;
+/**
+ * A redux store for mobx-keystone.
+ */
+export interface ReduxStore<T> {
+    getState(): SnapshotOutOf<T>;
+    dispatch(action: ReduxAction): ReduxAction;
+    subscribe(listener: OnSnapshotListener<T>): OnSnapshotDisposer;
+}
+/**
+ * A redux runner for mobx-keystone.
+ */
+export interface ReduxRunner<T> {
+    (next: ReduxStore<T>["dispatch"]): (action: ReduxAction) => ReduxAction;
+}
+/**
+ * A redux middleware for mobx-keystone.
+ */
+export interface ReduxMiddleware<T> {
+    (store: ReduxStore<T>): ReduxRunner<T>;
+}
+/**
+ * Generates a redux compatible store out of a mobx-keystone object.
+ *
+ * @typeparam T Object type.
+ * @param target Root object.
+ * @param middlewares Optional list of redux middlewares.
+ * @returns A redux compatible store.
+ */
+export declare function asReduxStore<T extends object>(target: T, ...middlewares: ReduxMiddleware<T>[]): ReduxStore<T>;

package/src/dist/ref/Ref.d.ts

@@ -0,0 +1,53 @@
+import type { ModelClass } from "../modelShared/BaseModelShared";
+declare const Ref_base: import("../model/Model")._Model<unknown, {
+    /**
+     * Reference id.
+     */
+    id: import("..").MaybeOptionalModelProp<string>;
+}, never, never>;
+/**
+ * A reference model base type.
+ * Use `customRef` to create a custom ref constructor.
+ */
+export declare abstract class Ref<T extends object> extends Ref_base {
+    protected abstract resolve(): T | undefined;
+    /**
+     * The object this reference points to, or `undefined` if the reference is currently invalid.
+     */
+    get maybeCurrent(): T | undefined;
+    /**
+     * If the reference is currently valid.
+     */
+    get isValid(): boolean;
+    /**
+     * The object this reference points to, or throws if invalid.
+     */
+    get current(): T;
+    /**
+     * Ensures back references for this ref are up to date.
+     * This only needs to be called if you need to get the most up to date
+     * back references while both still inside an action and while the reference
+     * is not a child of the same root than the target.
+     */
+    abstract forceUpdateBackRefs(): void;
+}
+/**
+ * @ignore
+ */
+export declare const customRefTypeSymbol: unique symbol;
+/** A ref constructor for custom refs */
+export interface RefConstructor<T extends object> {
+    <TE extends T>(valueOrID: TE | string): Ref<TE>;
+    refClass: ModelClass<Ref<T>>;
+    [customRefTypeSymbol]: T;
+}
+/**
+ * Checks if a ref object is of a given ref type.
+ *
+ * @typeparam T Referenced object type.
+ * @param ref Reference object.
+ * @param refType Reference type.
+ * @returns `true` if it is of the given type, false otherwise.
+ */
+export declare function isRefOfType<T extends object>(ref: Ref<object>, refType: RefConstructor<T>): ref is Ref<T>;
+export {};

package/src/dist/ref/core.d.ts

@@ -0,0 +1,46 @@
+import { ObservableSet } from "mobx";
+import { Ref, RefConstructor } from "./Ref";
+/**
+ * Reference resolver type.
+ */
+export declare type RefResolver<T extends object> = (ref: Ref<T>) => T | undefined;
+/**
+ * Reference ID resolver type.
+ */
+export declare type RefIdResolver = (target: object) => string | undefined;
+/**
+ * Type for the callback called when a reference resolved value changes.
+ */
+export declare type RefOnResolvedValueChange<T extends object> = (ref: Ref<T>, newValue: T | undefined, oldValue: T | undefined) => void;
+/**
+ * Uses a model `getRefId()` method whenever possible to get a reference ID.
+ * If the model does not have an implementation of that method it returns `undefined`.
+ * If the model has an implementation, but that implementation returns anything other than
+ * a `string` it will throw.
+ *
+ * @param target Target object to get the ID from.
+ * @returns The string ID or `undefined`.
+ */
+export declare function getModelRefId(target: object): string | undefined;
+/**
+ * Resolves a node given its ID.
+ *
+ * @typeparam T Target object type.
+ * @param root Node where to start the search. The search will be done on it and all its children.
+ * @param id ID to search for.
+ * @param getId Function that will be used to get the ID from an object (`getModelRefId` by default).
+ * @returns The node found or `undefined` if none.
+ */
+export declare function resolveId<T extends object>(root: object, id: string, getId?: RefIdResolver): T | undefined;
+/**
+ * Gets all references that resolve to a given object.
+ *
+ * @typeparam T Referenced object type.
+ * @param target Node the references point to.
+ * @param refType Pass it to filter by only references of a given type, or omit / pass `undefined` to get references of any type.
+ * @param options Options.
+ * @returns An observable set with all reference objects that point to the given object.
+ */
+export declare function getRefsResolvingTo<T extends object>(target: T, refType?: RefConstructor<T>, options?: {
+    updateAllRefsIfNeeded?: boolean;
+}): ObservableSet<Ref<T>>;

package/src/dist/ref/customRef.d.ts

@@ -0,0 +1,38 @@
+import { RefIdResolver, RefOnResolvedValueChange, RefResolver } from "./core";
+import type { RefConstructor } from "./Ref";
+/**
+ * Custom reference options.
+ */
+export interface CustomRefOptions<T extends object> {
+    /**
+     * Must return the resolution for the given reference object.
+     *
+     * @param ref Reference object.
+     * @returns The resolved object or undefined if it could not be resolved.
+     */
+    resolve: RefResolver<T>;
+    /**
+     * Must return the ID associated to the given target object, or `undefined` if it has no ID.
+     * If not provided it will try to get the reference id from the model `getRefId()` method.
+     *
+     * @param target Target object.
+     */
+    getId?: RefIdResolver;
+    /**
+     * What should happen when the resolved value changes.
+     *
+     * @param ref Reference object.
+     * @param newValue New resolved value.
+     * @param oldValue Old resolved value.
+     */
+    onResolvedValueChange?: RefOnResolvedValueChange<T>;
+}
+/**
+ * Creates a custom ref to an object, which in its snapshot form has an id.
+ *
+ * @typeparam T Target object type.
+ * @param modelTypeId Unique model type id.
+ * @param options Custom reference options.
+ * @returns A function that allows you to construct that type of custom reference.
+ */
+export declare const customRef: <T extends object>(modelTypeId: string, options: CustomRefOptions<T>) => RefConstructor<T>;

package/src/dist/ref/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core";
+export * from "./customRef";
+export * from "./Ref";
+export * from "./rootRef";