mobx-keystone 2.0.0 → 2.2.0

package/src/modelShared/prop.ts

@@ -3,7 +3,7 @@ import type { AnyStandardType } from "../types/schemas"
 import { isEqualOrBothNaN, lazy } from "../utils"
 import { runWithErrorDiagnosticsContext, withErrorPathSegment } from "../utils/errorDiagnostics"
 import { getOrCreate } from "../utils/mapUtils"
-import type { Flatten, IsNeverType, IsOptionalValue } from "../utils/types"
+import type { IsNeverType, IsOptionalValue, SimplifyObject } from "../utils/types"
 
 /**
  * @ignore
@@ -71,50 +71,18 @@ export interface ModelProp<
    * Adds a setter to the property. The setter will be named `set${CapitalizedPropName}`
    * and will be available in the model instance.
    */
-  withSetter(): ModelProp<
-    TPropValue,
-    TPropCreationValue,
-    TTransformedValue,
-    TTransformedCreationValue,
-    TIsRequired,
-    TIsId,
-    string,
-    TFromSnapshotOverride,
-    TToSnapshotOverride
-  >
+  withSetter(): ModelPropWithSetter<this>
   /**
    * Adds a setter with a transform to the property. The setter will be named `set${CapitalizedPropName}`
    * and will be available in the model instance.
    */
   withSetter(
     valueTransform: ModelPropSetterValueTransform<TTransformedValue>
-  ): ModelProp<
-    TPropValue,
-    TPropCreationValue,
-    TTransformedValue,
-    TTransformedCreationValue,
-    TIsRequired,
-    TIsId,
-    string,
-    TFromSnapshotOverride,
-    TToSnapshotOverride
-  >
+  ): ModelPropWithSetter<this>
   /**
    * @deprecated Setter methods are preferred.
    */
-  withSetter(
-    mode: "assign"
-  ): ModelProp<
-    TPropValue,
-    TPropCreationValue,
-    TTransformedValue,
-    TTransformedCreationValue,
-    TIsRequired,
-    TIsId,
-    string,
-    TFromSnapshotOverride,
-    TToSnapshotOverride
-  >
+  withSetter(mode: "assign"): ModelPropWithSetter<this>
 
   /**
    * Sets a transform for the property instance value.
@@ -130,17 +98,7 @@ export interface ModelProp<
    */
   withTransform<TTV>(
     transform: ModelPropTransform<NonNullable<TPropValue>, TTV>
-  ): ModelProp<
-    TPropValue,
-    TPropCreationValue,
-    TTV | Extract<TPropValue, null | undefined>,
-    TTV | Extract<TPropCreationValue, null | undefined>,
-    TIsRequired,
-    TIsId,
-    THasSetter,
-    TFromSnapshotOverride,
-    TToSnapshotOverride
-  >
+  ): ModelPropWithTransform<this, TTV>
 
   /**
    * Sets snapshot processors for this property.
@@ -158,18 +116,69 @@ export interface ModelProp<
   >(processor: {
     fromSnapshot?: (sn: FS) => ModelPropFromSnapshot<This>
     toSnapshot?: (sn: ModelPropToSnapshot<This>) => TS
-  }): ModelProp<
-    TPropValue,
-    TPropCreationValue,
-    TTransformedValue,
-    TTransformedCreationValue,
-    TIsRequired,
-    TIsId,
-    THasSetter,
-    FS,
-    TS
-  >
+  }): ModelPropWithSnapshotProcessor<this, FS, TS>
+}
+
+type ModelPropStoredMetadataKey = "$storedValueType" | "$storedCreationValueType"
+
+// keeps the stored value metadata that `tProp` adds (e.g. the encoded type of a codec)
+// when a model prop is derived through one of its modifiers
+type ModelPropStoredMetadata<MP, K extends PropertyKey> = MP extends {
+  $storedValueType: unknown
 }
+  ? Pick<MP, Extract<keyof MP, K>>
+  : {}
+
+// the modifier result types are exported so emitted declaration files can reference them by name
+// instead of expanding them inline in every exported model class
+
+/**
+ * The model property returned by `withSetter`.
+ */
+export type ModelPropWithSetter<MP extends AnyModelProp> = ModelProp<
+  MP["$valueType"],
+  MP["$creationValueType"],
+  MP["$transformedValueType"],
+  MP["$transformedCreationValueType"],
+  MP["$isRequired"],
+  MP["$isId"],
+  string,
+  MP["$fromSnapshotOverride"],
+  MP["$toSnapshotOverride"]
+> &
+  ModelPropStoredMetadata<MP, ModelPropStoredMetadataKey | "$typedFromSnapshotOverride">
+
+/**
+ * The model property returned by `withTransform`.
+ */
+export type ModelPropWithTransform<MP extends AnyModelProp, TTV> = ModelProp<
+  MP["$valueType"],
+  MP["$creationValueType"],
+  TTV | Extract<MP["$valueType"], null | undefined>,
+  TTV | Extract<MP["$creationValueType"], null | undefined>,
+  MP["$isRequired"],
+  MP["$isId"],
+  MP["$hasSetter"],
+  MP["$fromSnapshotOverride"],
+  MP["$toSnapshotOverride"]
+> &
+  ModelPropStoredMetadata<MP, ModelPropStoredMetadataKey | "$typedFromSnapshotOverride">
+
+/**
+ * The model property returned by `withSnapshotProcessor`.
+ */
+export type ModelPropWithSnapshotProcessor<MP extends AnyModelProp, FS, TS> = ModelProp<
+  MP["$valueType"],
+  MP["$creationValueType"],
+  MP["$transformedValueType"],
+  MP["$transformedCreationValueType"],
+  MP["$isRequired"],
+  MP["$isId"],
+  MP["$hasSetter"],
+  FS,
+  TS
+> &
+  ModelPropStoredMetadata<MP, ModelPropStoredMetadataKey>
 
 /**
  * The snapshot in type of a model property.
@@ -189,23 +198,19 @@ export type ModelPropToSnapshot<MP extends AnyModelProp> = IsNeverType<
   MP["$toSnapshotOverride"]
 >
 
-export type ModelPropStoredValue<MP extends AnyModelProp> = MP extends {
-  $storedValueType: infer TStoredValue
-}
-  ? TStoredValue
+export type ModelPropStoredValue<MP extends AnyModelProp> = "$storedValueType" extends keyof MP
+  ? MP["$storedValueType" & keyof MP]
   : MP["$valueType"]
 
-export type ModelPropStoredCreationValue<MP extends AnyModelProp> = MP extends {
-  $storedCreationValueType: infer TStoredCreationValue
-}
-  ? TStoredCreationValue
-  : MP["$creationValueType"]
+export type ModelPropStoredCreationValue<MP extends AnyModelProp> =
+  "$storedCreationValueType" extends keyof MP
+    ? MP["$storedCreationValueType" & keyof MP]
+    : MP["$creationValueType"]
 
-export type ModelPropFromSnapshotOverride<MP extends AnyModelProp> = MP extends {
-  $typedFromSnapshotOverride: infer TFromSnapshotOverride
-}
-  ? TFromSnapshotOverride
-  : MP["$fromSnapshotOverride"]
+export type ModelPropFromSnapshotOverride<MP extends AnyModelProp> =
+  "$typedFromSnapshotOverride" extends keyof MP
+    ? MP["$typedFromSnapshotOverride" & keyof MP]
+    : MP["$fromSnapshotOverride"]
 
 /**
  * A model prop transform.
@@ -245,13 +250,13 @@ export type RequiredModelProps<MP extends ModelProps> = {
   [K in keyof MP]: MP[K]["$isRequired"] & K
 }[keyof MP]
 
-export type ModelPropsToUntransformedData<MP extends ModelProps> = Flatten<{
+export type ModelPropsToUntransformedData<MP extends ModelProps> = {
   [k in keyof MP]: ModelPropStoredValue<MP[k]>
-}>
+} & {}
 
-export type ModelPropsToSnapshotData<MP extends ModelProps> = Flatten<{
+export type ModelPropsToSnapshotData<MP extends ModelProps> = {
   [k in keyof MP]: ModelPropToSnapshot<MP[k]> extends infer R ? R : never
-}>
+} & {}
 
 // we don't use O.Optional anymore since it generates unions too heavy
 // also if we use Pick over the optional props we will loose the ability to infer generics
@@ -264,23 +269,29 @@ export type ModelPropsToUntransformedCreationData<MP extends ModelProps> = {
 
 // we don't use O.Optional anymore since it generates unions too heavy
 // also if we use Pick over the optional props we will loose the ability to infer generics
-export type ModelPropsToSnapshotCreationData<MP extends ModelProps> = Flatten<
+export type ModelPropsToSnapshotCreationData<MP extends ModelProps> = SimplifyObject<
   {
     [k in keyof MP]?: ModelPropFromSnapshot<MP[k]> extends infer R ? R : never
   } & {
-    [k in {
-      [K in keyof MP]: IsNeverType<
-        ModelPropFromSnapshotOverride<MP[K]>,
-        MP[K]["$isRequired"] & K, // no override
-        IsOptionalValue<ModelPropFromSnapshotOverride<MP[K]>, never, K> // with override
-      >
-    }[keyof MP]]: ModelPropFromSnapshot<MP[k]> extends infer R ? R : never
+    [k in SnapshotCreationRequiredKeys<MP>]: ModelPropFromSnapshot<MP[k]> extends infer R
+      ? R
+      : never
   }
 >
 
-export type ModelPropsToTransformedData<MP extends ModelProps> = Flatten<{
+// without a snapshot processor a key is required when the prop is required,
+// with one when the processor input does not accept undefined
+type SnapshotCreationRequiredKeys<MP extends ModelProps> = {
+  [K in keyof MP]: IsNeverType<
+    ModelPropFromSnapshotOverride<MP[K]>,
+    MP[K]["$isRequired"] & K,
+    IsOptionalValue<ModelPropFromSnapshotOverride<MP[K]>, never, K>
+  >
+}[keyof MP]
+
+export type ModelPropsToTransformedData<MP extends ModelProps> = {
   [k in keyof MP]: MP[k]["$transformedValueType"]
-}>
+} & {}
 
 // we don't use O.Optional anymore since it generates unions too heavy
 // also if we use Pick over the optional props we will loose the ability to infer generics
@@ -292,11 +303,11 @@ export type ModelPropsToTransformedCreationData<MP extends ModelProps> = {
   [k in RequiredModelProps<MP>]: MP[k]["$transformedCreationValueType"]
 }
 
-export type ModelPropsToSetter<MP extends ModelProps> = Flatten<{
+export type ModelPropsToSetter<MP extends ModelProps> = {
   [k in keyof MP as MP[k]["$hasSetter"] & `set${Capitalize<k & string>}`]: (
     value: MP[k]["$transformedValueType"]
   ) => void
-}>
+} & {}
 
 export type ModelIdProp<T extends string = string> = ModelProp<
   T,
@@ -307,7 +318,12 @@ export type ModelIdProp<T extends string = string> = ModelProp<
   true
 >
 
-type TypedModelIdProp<T extends string = string, THasSetter = never> = Omit<
+// exported (and publicly re-exported) so emitted declaration files can reference it by name
+// instead of expanding it inline in every exported model class, which is much slower and larger
+/**
+ * The type of `idProp`.
+ */
+export type TypedModelIdProp<T extends string = string, THasSetter = never> = Omit<
   ModelProp<T, T | undefined, T, T | undefined, never, true, THasSetter>,
   "withSetter"
 > & {
@@ -569,21 +585,17 @@ export function prop(...args: [] | [def: any]): AnyModelProp {
 
   const [def] = args
 
-  let p = propCache.get(def)
-
-  if (!p) {
-    p = Object.create(baseProp)
+  return getOrCreate(propCache, def, () => {
+    const p: AnyModelProp = Object.create(baseProp)
 
     if (typeof def === "function") {
-      p!._defaultFn = def
+      p._defaultFn = def
     } else {
-      p!._defaultValue = def
+      p._defaultValue = def
     }
 
-    propCache.set(def, p!)
-  }
-
-  return p!
+    return p
+  })
 }
 
 function parseSetterConfig(
@@ -599,19 +611,11 @@ function parseSetterConfig(
     }
   }
 
-  if (
-    modeOrValueTransform === undefined ||
-    typeof modeOrValueTransform === "boolean" ||
-    modeOrValueTransform === "assign"
-  ) {
-    return {
-      mode: modeOrValueTransform ?? true,
-      valueTransform: undefined,
-    }
-  }
-
   return {
-    mode: true,
+    mode:
+      typeof modeOrValueTransform === "boolean" || modeOrValueTransform === "assign"
+        ? modeOrValueTransform
+        : true,
     valueTransform: undefined,
   }
 }

package/src/modelShared/sharedInternalModel.ts

@@ -241,7 +241,7 @@ export function sharedInternalModel<
     const idPropGenerator = idProp._idGenerator
     const baseIdProp = baseModelProps?.[idKey]
     const baseIdPropGenerator = baseIdProp?._idGenerator
-    const isOverridingBaseIdProp = !!baseIdProp?._isId && Object.hasOwn(modelProps, idKey)
+    const isOverridingBaseIdProp = !!baseIdProp?._isId && hasOwnProp(modelProps, idKey)
     if (isOverridingBaseIdProp && baseIdPropGenerator !== idPropGenerator) {
       throw failure(
         `expected same idProp.withGenerator function when overriding a base idProp, but got different references`
@@ -315,7 +315,7 @@ export function sharedInternalModel<
     // make sure abstract classes do not override prototype props
     if (!propsToDeleteFromBase) {
       propsToDeleteFromBase = Object.keys(modelProps).filter(
-        (p) => !basePropNames.has(p as any) && Object.hasOwn(baseModel, p)
+        (p) => !basePropNames.has(p as any) && hasOwnProp(baseModel, p)
       )
     }
 

package/src/parent/arrayPaths.ts

@@ -0,0 +1,239 @@
+import { createAtom, type IAtom } from "mobx"
+import { treeNodeMetadata } from "../tweaker/treeNodeMetadata"
+import { isPrimitive } from "../utils"
+import { ChunkedSequence, chunkSize, type SequenceChunk } from "../utils/chunks"
+import { reportParentPathChanged } from "./core"
+import type { ParentPath } from "./path"
+
+/** Arrays whose splices would reindex more children than this switch to lazy indexes. */
+const lazyIndexesThreshold = 1024
+
+class PathChunk implements SequenceChunk<LazyArrayParentPath | undefined> {
+  /** Path of each item, or undefined for primitives. */
+  items: (LazyArrayParentPath | undefined)[]
+  offset = 0
+  /**
+   * Changed when the index of any of its items changes, or when items move
+   * out of it, so observers of their paths follow them to their new chunk.
+   */
+  readonly atom: IAtom = createAtom("arrayPathChunk")
+  readonly owner: ArrayPaths
+
+  constructor(owner: ArrayPaths, items: (LazyArrayParentPath | undefined)[]) {
+    this.owner = owner
+    this.items = items
+  }
+}
+
+/**
+ * Parent path of an item of a large array. Its index is the offset of its chunk
+ * plus its position within it, so a splice only renumbers one chunk and moves
+ * the offsets of the chunks after it, instead of reindexing every item after it.
+ * Once removed, it keeps the index it had.
+ *
+ * @internal
+ */
+export class LazyArrayParentPath implements ParentPath<object> {
+  // declared rather than defined fields: there are as many instances as array
+  // items, and defined fields compile to an Object.defineProperty call each
+  declare readonly parent: object
+  /** Undefined once removed from the array. */
+  declare chunk: PathChunk | undefined
+  /** Position within the chunk, or the final index once removed. */
+  declare local: number
+
+  constructor(parent: object, chunk: PathChunk, local: number) {
+    this.parent = parent
+    this.chunk = chunk
+    this.local = local
+  }
+
+  get path(): number {
+    const chunk = this.chunk
+    if (!chunk) {
+      return this.local
+    }
+    chunk.owner.updateOffsets()
+    return chunk.offset + this.local
+  }
+
+  /**
+   * An immutable copy for callers outside the library, which may keep it,
+   * reused while the index stays the same.
+   */
+  toParentPath(): ParentPath<object> {
+    const path = this.path
+    let publicPath = publicPaths.get(this)
+    if (publicPath?.path !== path) {
+      publicPath = { parent: this.parent, path }
+      publicPaths.set(this, publicPath)
+    }
+    return publicPath
+  }
+
+  /** Makes observers of this path also react to index changes. */
+  reportObserved(): void {
+    this.chunk?.atom.reportObserved()
+  }
+}
+
+// kept apart, since few paths are ever handed out
+const publicPaths = new WeakMap<LazyArrayParentPath, ParentPath<object>>()
+
+class ArrayPaths extends ChunkedSequence<LazyArrayParentPath | undefined, PathChunk> {
+  readonly array: readonly unknown[]
+  private offsetsDirty = false
+
+  constructor(array: readonly unknown[]) {
+    super()
+    this.array = array
+    const length = array.length
+    for (let start = 0; start < length; start += chunkSize) {
+      // a slice is much faster than indexed reads through an observable array
+      const items = array.slice(start, start + chunkSize)
+      const chunk = new PathChunk(this, new Array(items.length))
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i]
+        if (!isPrimitive(item)) {
+          const entry = new LazyArrayParentPath(array, chunk, i)
+          chunk.items[i] = entry
+          treeNodeMetadata.get(item as object)!.parentPath = entry
+          // current observers of its path do not observe its chunk yet
+          reportParentPathChanged(item as object)
+        }
+      }
+      this.chunks.push(chunk)
+    }
+    this.offsetsDirty = true
+  }
+
+  updateOffsets(): void {
+    if (!this.offsetsDirty) {
+      return
+    }
+    this.offsetsDirty = false
+    let offset = 0
+    for (const chunk of this.chunks) {
+      chunk.offset = offset
+      offset += chunk.items.length
+    }
+  }
+
+  /**
+   * Paths for values to be inserted at an index, undefined for primitives. They
+   * already resolve to their final index, but are only added by `splice`, so
+   * attaching the values can fail without leaving them behind.
+   */
+  createPaths(index: number, values: readonly unknown[]): (LazyArrayParentPath | undefined)[] {
+    this.updateOffsets()
+    if (this.chunks.length === 0) {
+      this.chunks.push(this.createChunk([]))
+    }
+    const [c, start] = this.locate(index)
+    const chunk = this.chunks[c]
+    const paths: (LazyArrayParentPath | undefined)[] = new Array(values.length)
+    for (let i = 0; i < values.length; i++) {
+      if (!isPrimitive(values[i])) {
+        paths[i] = new LazyArrayParentPath(this.array, chunk, start + i)
+      }
+    }
+    return paths
+  }
+
+  /** Applies a splice, freezing the removed paths and adding ones from `createPaths`. */
+  applySplice(
+    index: number,
+    removedCount: number,
+    addedPaths: (LazyArrayParentPath | undefined)[]
+  ): void {
+    this.updateOffsets()
+    this.splice(index, removedCount, addedPaths, freezeRemovedPath)
+    this.offsetsDirty = true
+  }
+
+  /** Replaces the path of an updated item, freezing the old one. */
+  set(index: number, value: unknown): LazyArrayParentPath | undefined {
+    this.updateOffsets()
+    const [c, local] = this.locate(index)
+    const chunk = this.chunks[c]
+    const old = chunk.items[local]
+    if (old) {
+      freezeRemovedPath(old, chunk, local)
+    }
+    const entry = isPrimitive(value) ? undefined : new LazyArrayParentPath(this.array, chunk, local)
+    chunk.items[local] = entry
+    return entry
+  }
+
+  protected createChunk(items: (LazyArrayParentPath | undefined)[]): PathChunk {
+    return new PathChunk(this, items)
+  }
+
+  protected onSpliced(chunk: PathChunk, from: number): void {
+    // the items after the splice moved within the chunk, and may move to other
+    // chunks when it is resized, where observers will follow them
+    renumber(chunk, from)
+    chunk.atom.reportChanged()
+  }
+
+  protected onItemsMoved(chunk: PathChunk, from: number): void {
+    renumber(chunk, from)
+  }
+
+  protected onShifted(chunk: PathChunk): void {
+    // the index of every item after the splice changed
+    chunk.atom.reportChanged()
+  }
+}
+
+function freezeRemovedPath(
+  entry: LazyArrayParentPath | undefined,
+  chunk: PathChunk,
+  local: number
+): void {
+  if (entry) {
+    entry.local = chunk.offset + local
+    entry.chunk = undefined
+  }
+}
+
+function renumber(chunk: PathChunk, from: number): void {
+  const items = chunk.items
+  for (let i = from; i < items.length; i++) {
+    const entry = items[i]
+    if (entry) {
+      entry.chunk = chunk
+      entry.local = i
+    }
+  }
+}
+
+const arrayPaths = new WeakMap<object, ArrayPaths>()
+
+/**
+ * Lazy indexes of an array, created once a splice would reindex many of its
+ * items.
+ *
+ * @internal
+ */
+export function getArrayPaths(
+  array: readonly unknown[],
+  reindexedCount: number
+): ArrayPaths | undefined {
+  let paths = arrayPaths.get(array)
+  if (!paths && reindexedCount > lazyIndexesThreshold) {
+    paths = new ArrayPaths(array)
+    arrayPaths.set(array, paths)
+  }
+  return paths
+}
+
+/**
+ * Makes an attached value use its lazy path, even if it was attached with an
+ * equal one.
+ *
+ * @internal
+ */
+export function setLazyArrayParentPath(entry: LazyArrayParentPath, node: object): void {
+  treeNodeMetadata.get(node)!.parentPath = entry
+}