mobx-keystone 1.20.0 → 1.22.0

package/src/model/BaseModel.ts

@@ -1,273 +1,275 @@
-import { observable } from "mobx"
-import {
-  fromSnapshotOverrideTypeSymbol,
-  ModelClass,
-  propsTypeSymbol,
-  toSnapshotOverrideTypeSymbol,
-} from "../modelShared/BaseModelShared"
-import { modelInfoByClass } from "../modelShared/modelInfo"
-import type {
-  ModelProps,
-  ModelPropsToTransformedCreationData,
-  ModelPropsToUntransformedData,
-} from "../modelShared/prop"
-import { getSnapshot } from "../snapshot/getSnapshot"
-import type { SnapshotInOfModel, SnapshotOutOfModel } from "../snapshot/SnapshotOf"
-import { typesModel } from "../types/objectBased/typesModel"
-import type { TypeCheckError } from "../types/TypeCheckError"
-import { typeCheck } from "../types/typeCheck"
-import { assertIsObject, failure } from "../utils"
-import { getModelIdPropertyName } from "./getModelMetadata"
-import type { ModelConstructorOptions } from "./ModelConstructorOptions"
-import { modelIdKey, modelTypeKey } from "./metadata"
-import { internalFromSnapshotModel, internalNewModel } from "./newModel"
-import { assertIsModelClass } from "./utils"
-
-/**
- * @ignore
- */
-export const modelIdPropertyNameSymbol = Symbol("modelIdPropertyName")
-
-/**
- * @ignore
- */
-export type ModelIdPropertyType<TProps extends ModelProps, ModelIdPropertyName extends string> = [
-  ModelIdPropertyName,
-] extends [never]
-  ? never
-  : ModelPropsToUntransformedData<Pick<TProps, ModelIdPropertyName>>[ModelIdPropertyName]
-
-/**
- * Base abstract class for models. Use `Model` instead when extending.
- *
- * Never override the constructor, use `onInit` or `onAttachedToRootStore` instead.
- *
- * @template Data Data type.
- * @template CreationData Creation data type.
- * @template ModelIdPropertyName Model id property name.
- */
-export abstract class BaseModel<
-  TProps extends ModelProps,
-  FromSnapshotOverride extends Record<string, any>,
-  ToSnapshotOverride extends Record<string, any>,
-  ModelIdPropertyName extends string = never,
-> {
-  // just to make typing work properly
-  [propsTypeSymbol]!: TProps;
-  [fromSnapshotOverrideTypeSymbol]!: FromSnapshotOverride;
-  [toSnapshotOverrideTypeSymbol]!: ToSnapshotOverride;
-  [modelIdPropertyNameSymbol]!: ModelIdPropertyName
-
-  /**
-   * Model type name.
-   */
-  readonly [modelTypeKey]!: string
-
-  /**
-   * Model internal id. Can be modified inside a model action.
-   * It will return `undefined` if there's no id prop set.
-   */
-  get [modelIdKey](): ModelIdPropertyType<TProps, ModelIdPropertyName> {
-    const idProp = getModelIdPropertyName(this.constructor as any)
-    return (idProp ? (this.$ as any)[idProp] : undefined) as ModelIdPropertyType<
-      TProps,
-      ModelIdPropertyName
-    >
-  }
-
-  set [modelIdKey](newId: ModelIdPropertyType<TProps, ModelIdPropertyName>) {
-    const idProp = getModelIdPropertyName(this.constructor as any)
-    if (!idProp) {
-      throw failure("$modelId cannot be set when there is no idProp set in the model")
-    }
-    ;(this.$ as any)[idProp] = newId
-  }
-
-  /**
-   * Can be overridden to offer a reference id to be used in reference resolution.
-   * By default it will use the `idProp` if available or return `undefined` otherwise.
-   */
-  getRefId(): string | undefined {
-    return this[modelIdKey]
-  }
-
-  /**
-   * Called after the model has been created.
-   */
-  protected onInit?(): void
-
-  /**
-   * Data part of the model, which is observable and will be serialized in snapshots.
-   * Use it if one of the data properties matches one of the model properties/functions.
-   */
-  readonly $!: ModelPropsToUntransformedData<TProps>
-
-  /**
-   * Optional hook that will run once this model instance is attached to the tree of a model marked as
-   * root store via `registerRootStore`.
-   * Basically this is the place where you know the full root store is complete and where things such as
-   * middlewares, effects (reactions, etc), and other side effects should be registered, since it means
-   * that the model is now part of the active application state.
-   *
-   * It can return a disposer that will be run once this model instance is detached from such root store tree.
-   *
-   * @param rootStore
-   * @returns
-   */
-  protected onAttachedToRootStore?(rootStore: object): (() => void) | void
-
-  /**
-   * Performs a type check over the model instance.
-   * For this to work a data type has to be declared as part of the model properties.
-   *
-   * @returns A `TypeCheckError` or `null` if there is no error.
-   */
-  typeCheck(): TypeCheckError | null {
-    const type = typesModel<this>(this.constructor as any)
-    return typeCheck(type, this as any)
-  }
-
-  /**
-   * Creates an instance of a model.
-   */
-  constructor(data: ModelPropsToTransformedCreationData<TProps>) {
-    const initialData = data as any
-    const { snapshotInitialData, modelClass, generateNewIds }: ModelConstructorOptions =
-      arguments[1]
-
-    Object.setPrototypeOf(this, modelClass!.prototype)
-
-    const self = this as any
-
-    // delete unnecessary props
-    delete self[propsTypeSymbol]
-    delete self[fromSnapshotOverrideTypeSymbol]
-    delete self[toSnapshotOverrideTypeSymbol]
-    delete self[modelIdPropertyNameSymbol]
-
-    if (snapshotInitialData) {
-      // from snapshot
-      internalFromSnapshotModel(this, snapshotInitialData, modelClass!, !!generateNewIds)
-    } else {
-      // plain new
-      assertIsObject(initialData, "initialData")
-
-      internalNewModel(
-        this,
-        observable.object(initialData as any, undefined, { deep: false }),
-        modelClass!
-      )
-    }
-  }
-
-  toString(options?: { withData?: boolean }) {
-    const finalOptions = {
-      withData: true,
-      ...options,
-    }
-
-    const firstPart = `${this.constructor.name}#${this[modelTypeKey]}`
-
-    return finalOptions.withData
-      ? `[${firstPart} ${JSON.stringify(getSnapshot(this))}]`
-      : `[${firstPart}]`
-  }
-}
-
-/**
- * @ignore
- */
-export type BaseModelKeys = keyof AnyModel | "onInit" | "onAttachedToRootStore"
-
-// these props will never be hoisted to this (except for model id)
-/**
- * @internal
- */
-export const baseModelPropNames = new Set<BaseModelKeys>([
-  modelTypeKey,
-  modelIdKey,
-  "onInit",
-  "$",
-  "getRefId",
-  "onAttachedToRootStore",
-  "typeCheck",
-])
-
-/**
- * Any kind of model instance.
- */
-export interface AnyModel extends BaseModel<any, any, any, any> {}
-
-/**
- * @deprecated Should not be needed anymore.
- *
- * Tricks TypeScript into accepting abstract classes as a parameter for `ExtendedModel`.
- * Does nothing in runtime.
- *
- * @template T Abstract model class type.
- * @param type Abstract model class.
- * @returns
- */
-export function abstractModelClass<T>(type: T): T & Object {
-  return type as any
-}
-
-/**
- * The model id property name.
- */
-export type ModelIdPropertyName<M extends AnyModel> = M[typeof modelIdPropertyNameSymbol]
-
-/**
- * Add missing model metadata to a model creation snapshot to generate a proper model snapshot.
- * Usually used alongside `fromSnapshot`.
- *
- * @template M Model type.
- * @param modelClass Model class.
- * @param snapshot Model creation snapshot without metadata.
- * @returns The model snapshot (including metadata).
- */
-export function modelSnapshotInWithMetadata<M extends AnyModel>(
-  modelClass: ModelClass<M>,
-  snapshot: Omit<SnapshotInOfModel<M>, typeof modelTypeKey>
-): SnapshotInOfModel<M> {
-  assertIsModelClass(modelClass, "modelClass")
-  assertIsObject(snapshot, "initialData")
-
-  const modelInfo = modelInfoByClass.get(modelClass)!
-
-  return {
-    ...snapshot,
-    [modelTypeKey]: modelInfo.name,
-  } as any
-}
-
-/**
- * Add missing model metadata to a model output snapshot to generate a proper model snapshot.
- * Usually used alongside `applySnapshot`.
- *
- * @template M Model type.
- * @param modelClass Model class.
- * @param snapshot Model output snapshot without metadata.
- * @returns The model snapshot (including metadata).
- */
-export function modelSnapshotOutWithMetadata<M extends AnyModel>(
-  modelClass: ModelClass<M>,
-  snapshot: Omit<SnapshotOutOfModel<M>, typeof modelTypeKey>
-): SnapshotOutOfModel<M> {
-  assertIsModelClass(modelClass, "modelClass")
-  assertIsObject(snapshot, "initialData")
-
-  const modelInfo = modelInfoByClass.get(modelClass)!
-
-  return {
-    ...snapshot,
-    [modelTypeKey]: modelInfo.name,
-  } as any
-}
-
-/**
- * A model class declaration, made of a base model and the model interface.
- */
-export type ModelClassDeclaration<BaseModelClass, ModelInterface> = BaseModelClass & {
-  new (...args: any[]): ModelInterface
-}
+import { observable } from "mobx"
+import {
+  fromSnapshotOverrideTypeSymbol,
+  type ModelClass,
+  propsTypeSymbol,
+  toSnapshotOverrideTypeSymbol,
+} from "../modelShared/BaseModelShared"
+import { modelInfoByClass } from "../modelShared/modelInfo"
+import type {
+  ModelProps,
+  ModelPropsToTransformedCreationData,
+  ModelPropsToUntransformedData,
+} from "../modelShared/prop"
+import { getSnapshot } from "../snapshot/getSnapshot"
+import type { SnapshotInOfModel, SnapshotOutOfModel } from "../snapshot/SnapshotOf"
+import { typesModel } from "../types/objectBased/typesModel"
+import type { TypeCheckError } from "../types/TypeCheckError"
+import { typeCheck } from "../types/typeCheck"
+import { assertIsObject, failure } from "../utils"
+import { getModelIdPropertyName } from "./getModelMetadata"
+import type { ModelConstructorOptions } from "./ModelConstructorOptions"
+import { modelIdKey, modelTypeKey } from "./metadata"
+import { internalFromSnapshotModel, internalNewModel } from "./newModel"
+import { assertIsModelClass } from "./utils"
+
+/**
+ * @ignore
+ */
+export const modelIdPropertyNameSymbol = Symbol("modelIdPropertyName")
+
+/**
+ * @ignore
+ */
+export type ModelIdPropertyType<TProps extends ModelProps, ModelIdPropertyName extends string> = [
+  ModelIdPropertyName,
+] extends [never]
+  ? never
+  : ModelPropsToUntransformedData<Pick<TProps, ModelIdPropertyName>>[ModelIdPropertyName]
+
+/**
+ * Base abstract class for models. Use `Model` instead when extending.
+ *
+ * Never override the constructor, use `onInit` or `onAttachedToRootStore` instead.
+ *
+ * @template Data Data type.
+ * @template CreationData Creation data type.
+ * @template ModelIdPropertyName Model id property name.
+ */
+export abstract class BaseModel<
+  TProps extends ModelProps,
+  FromSnapshotOverride extends Record<string, any>,
+  ToSnapshotOverride extends Record<string, any>,
+  ModelIdPropertyName extends string = never,
+> {
+  // just to make typing work properly
+  [propsTypeSymbol]!: TProps;
+  [fromSnapshotOverrideTypeSymbol]!: FromSnapshotOverride;
+  [toSnapshotOverrideTypeSymbol]!: ToSnapshotOverride;
+  [modelIdPropertyNameSymbol]!: ModelIdPropertyName
+
+  /**
+   * Model type name.
+   */
+  readonly [modelTypeKey]!: string
+
+  /**
+   * Model internal id. Can be modified inside a model action.
+   * It will return `undefined` if there's no id prop set.
+   */
+  get [modelIdKey](): ModelIdPropertyType<TProps, ModelIdPropertyName> {
+    const idProp = getModelIdPropertyName(this.constructor as any)
+    return (idProp ? (this.$ as any)[idProp] : undefined) as ModelIdPropertyType<
+      TProps,
+      ModelIdPropertyName
+    >
+  }
+
+  set [modelIdKey](newId: ModelIdPropertyType<TProps, ModelIdPropertyName>) {
+    const idProp = getModelIdPropertyName(this.constructor as any)
+    if (!idProp) {
+      throw failure("$modelId cannot be set when there is no idProp set in the model")
+    }
+    ;(this.$ as any)[idProp] = newId
+  }
+
+  /**
+   * Can be overridden to offer a reference id to be used in reference resolution.
+   * By default it will use the `idProp` if available or return `undefined` otherwise.
+   */
+  getRefId(): string | undefined {
+    return this[modelIdKey]
+  }
+
+  /**
+   * Called after the model has been created.
+   */
+  protected onInit?(): void
+
+  /**
+   * Data part of the model, which is observable and will be serialized in snapshots.
+   * Use it if one of the data properties matches one of the model properties/functions.
+   */
+  readonly $!: ModelPropsToUntransformedData<TProps>
+
+  /**
+   * Optional hook that will run once this model instance is attached to the tree of a model marked as
+   * root store via `registerRootStore`.
+   * Basically this is the place where you know the full root store is complete and where things such as
+   * middlewares, effects (reactions, etc), and other side effects should be registered, since it means
+   * that the model is now part of the active application state.
+   *
+   * It can return a disposer that will be run once this model instance is detached from such root store tree.
+   *
+   * @param rootStore
+   * @returns
+   */
+  protected onAttachedToRootStore?(rootStore: object): (() => void) | void
+
+  /**
+   * Performs a type check over the model instance.
+   * For this to work a data type has to be declared as part of the model properties.
+   *
+   * @returns A `TypeCheckError` or `null` if there is no error.
+   */
+  typeCheck(): TypeCheckError | null {
+    const type = typesModel<this>(this.constructor as any)
+    return typeCheck(type, this as any)
+  }
+
+  /**
+   * Creates an instance of a model.
+   */
+  constructor(data: ModelPropsToTransformedCreationData<TProps>) {
+    const initialData = data as any
+    const constructorOptions =
+      // biome-ignore lint/complexity/noArguments: internal factory code passes hidden constructor options through super().
+      arguments[1] as ModelConstructorOptions
+    const { snapshotInitialData, modelClass, generateNewIds } = constructorOptions
+
+    Object.setPrototypeOf(this, modelClass!.prototype)
+
+    const self = this as any
+
+    // delete unnecessary props
+    delete self[propsTypeSymbol]
+    delete self[fromSnapshotOverrideTypeSymbol]
+    delete self[toSnapshotOverrideTypeSymbol]
+    delete self[modelIdPropertyNameSymbol]
+
+    if (snapshotInitialData) {
+      // from snapshot
+      internalFromSnapshotModel(this, snapshotInitialData, modelClass!, !!generateNewIds)
+    } else {
+      // plain new
+      assertIsObject(initialData, "initialData")
+
+      internalNewModel(
+        this,
+        observable.object(initialData as any, undefined, { deep: false }),
+        modelClass!
+      )
+    }
+  }
+
+  toString(options?: { withData?: boolean }) {
+    const finalOptions = {
+      withData: true,
+      ...options,
+    }
+
+    const firstPart = `${this.constructor.name}#${this[modelTypeKey]}`
+
+    return finalOptions.withData
+      ? `[${firstPart} ${JSON.stringify(getSnapshot(this))}]`
+      : `[${firstPart}]`
+  }
+}
+
+/**
+ * @ignore
+ */
+export type BaseModelKeys = keyof AnyModel | "onInit" | "onAttachedToRootStore"
+
+// these props will never be hoisted to this (except for model id)
+/**
+ * @internal
+ */
+export const baseModelPropNames = new Set<BaseModelKeys>([
+  modelTypeKey,
+  modelIdKey,
+  "onInit",
+  "$",
+  "getRefId",
+  "onAttachedToRootStore",
+  "typeCheck",
+])
+
+/**
+ * Any kind of model instance.
+ */
+export interface AnyModel extends BaseModel<any, any, any, any> {}
+
+/**
+ * @deprecated Should not be needed anymore.
+ *
+ * Tricks TypeScript into accepting abstract classes as a parameter for `ExtendedModel`.
+ * Does nothing in runtime.
+ *
+ * @template T Abstract model class type.
+ * @param type Abstract model class.
+ * @returns
+ */
+export function abstractModelClass<T>(type: T): T & Object {
+  return type as any
+}
+
+/**
+ * The model id property name.
+ */
+export type ModelIdPropertyName<M extends AnyModel> = M[typeof modelIdPropertyNameSymbol]
+
+/**
+ * Add missing model metadata to a model creation snapshot to generate a proper model snapshot.
+ * Usually used alongside `fromSnapshot`.
+ *
+ * @template M Model type.
+ * @param modelClass Model class.
+ * @param snapshot Model creation snapshot without metadata.
+ * @returns The model snapshot (including metadata).
+ */
+export function modelSnapshotInWithMetadata<M extends AnyModel>(
+  modelClass: ModelClass<M>,
+  snapshot: Omit<SnapshotInOfModel<M>, typeof modelTypeKey>
+): SnapshotInOfModel<M> {
+  assertIsModelClass(modelClass, "modelClass")
+  assertIsObject(snapshot, "initialData")
+
+  const modelInfo = modelInfoByClass.get(modelClass)!
+
+  return {
+    ...snapshot,
+    [modelTypeKey]: modelInfo.name,
+  } as any
+}
+
+/**
+ * Add missing model metadata to a model output snapshot to generate a proper model snapshot.
+ * Usually used alongside `applySnapshot`.
+ *
+ * @template M Model type.
+ * @param modelClass Model class.
+ * @param snapshot Model output snapshot without metadata.
+ * @returns The model snapshot (including metadata).
+ */
+export function modelSnapshotOutWithMetadata<M extends AnyModel>(
+  modelClass: ModelClass<M>,
+  snapshot: Omit<SnapshotOutOfModel<M>, typeof modelTypeKey>
+): SnapshotOutOfModel<M> {
+  assertIsModelClass(modelClass, "modelClass")
+  assertIsObject(snapshot, "initialData")
+
+  const modelInfo = modelInfoByClass.get(modelClass)!
+
+  return {
+    ...snapshot,
+    [modelTypeKey]: modelInfo.name,
+  } as any
+}
+
+/**
+ * A model class declaration, made of a base model and the model interface.
+ */
+export type ModelClassDeclaration<BaseModelClass, ModelInterface> = BaseModelClass & {
+  new (...args: any[]): ModelInterface
+}

package/src/model/ModelConstructorOptions.ts

@@ -1,15 +1,15 @@
-import type { ModelClass } from "../modelShared/BaseModelShared"
-import type { AnyModel } from "./BaseModel"
-
-/**
- * @internal
- */
-export interface ModelConstructorOptions {
-  snapshotInitialData?: {
-    unprocessedSnapshot: any
-    unprocessedModelType: unknown
-    snapshotToInitialData(processedSnapshot: any): any
-  }
-  modelClass?: ModelClass<AnyModel>
-  generateNewIds?: boolean
-}
+import type { ModelClass } from "../modelShared/BaseModelShared"
+import type { AnyModel } from "./BaseModel"
+
+/**
+ * @internal
+ */
+export interface ModelConstructorOptions {
+  snapshotInitialData?: {
+    unprocessedSnapshot: any
+    unprocessedModelType: unknown
+    snapshotToInitialData(processedSnapshot: any): any
+  }
+  modelClass?: ModelClass<AnyModel>
+  generateNewIds?: boolean
+}