feat(idProp): add per-model ID generator and inheritance checks (#576)

* feat(idProp): add per-model ID generation with inheritance support

* Update packages/lib/src/modelShared/prop.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: xaviergonz

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Added `idProp.withGenerator(...)` to define per-model ID generation for `idProp` fields, including inheritance-aware behavior in `ExtendedModel`.
+
 ## 1.18.0
 
 - Added `defineModelMixin` and `composeMixins` helpers for type-safe class-model mixin composition without per-factory cast boilerplate.

apps/site/docs/classModels.mdx

@@ -253,6 +253,22 @@ setGlobalConfig({
 })
 ```
 
+You can also define a generator per model ID field using `idProp.withGenerator(...)`:
+
+```ts
+@model("myApp/Todo")
+class Todo extends Model({
+  id: idProp.withGenerator(() => `todo-${uuid()}`),
+  text: prop<string>(),
+}) {}
+```
+
+For `ExtendedModel`, the generator follows inheritance:
+
+- If base has one and extended does not override the id prop, extended uses base generator.
+- If extended overrides a base id prop, `withGenerator(...)` must match the base one exactly (including `undefined`).
+- If base has no id prop and extended defines one, extended uses its own generator.
+
 ## Getting the TypeScript types for model data and model creation data
 
 - `ModelData<Model>` is the type of the model props without transformations (as accessible via `model.$`).

apps/site/docs/mstMigrationGuide.mdx

@@ -105,6 +105,18 @@ getRefId() {
 }
 ```
 
+If your MST model used a generated default identifier, for example:
+
+```ts
+id: types.optional(types.identifier, () => `todo-${nanoid()}`)
+```
+
+the equivalent in `mobx-keystone` is:
+
+```ts
+id: idProp.withGenerator(() => `todo-${nanoid()}`)
+```
+
 ### 7) Identifier mutability differs
 
 MST identifiers are effectively immutable in typical usage.
@@ -406,6 +418,7 @@ Note: `ExtendedModel` extends a single base class. If you need to merge more tha
 | `types.maybe(T)` | `prop<T \| undefined>()` or `tProp(types.maybe(T))` | Optional value; `T` must include `undefined` explicitly. |
 | `types.maybeNull(T)` | `prop<T \| null>()` or `tProp(types.maybeNull(T))` | Nullable value; `T` must include `null` explicitly. |
 | `types.identifier` | `idProp` | Preferred model ID field. |
+| `types.optional(types.identifier, () => id)` | `idProp.withGenerator(() => id)` | Per-model ID generator. |
 | `types.identifierNumber` | Prefer string IDs (`idProp`) or keep numeric field + override `getRefId()` to return `String(id)` | `mobx-keystone` refs require string IDs. |
 | `types.late(() => T)` | Usually not needed with class references | Circular/lazy types are class references; use `types.late(() => T)` only in runtime type-checking declarations if needed. |
 

packages/lib/src/modelShared/prop.ts

@@ -42,6 +42,7 @@ export interface ModelProp<
   _setter: SetterMode
   _setterValueTransform: ((value: unknown) => unknown) | undefined
   _isId: boolean
+  _idGenerator?: (() => string) | undefined
   _transform:
     | {
         transform: (
@@ -56,6 +57,10 @@ export interface ModelProp<
   _fromSnapshotProcessor?: (sn: unknown) => unknown
   _toSnapshotProcessor?: (sn: unknown) => unknown
 
+  /**
+   * 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,
@@ -67,6 +72,10 @@ export interface ModelProp<
     TFromSnapshotOverride,
     TToSnapshotOverride
   >
+  /**
+   * 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<
@@ -118,6 +127,12 @@ export interface ModelProp<
     TToSnapshotOverride
   >
 
+  /**
+   * Sets snapshot processors for this property.
+   *
+   * `fromSnapshot` runs before assigning snapshot data into the model prop.
+   * `toSnapshot` runs when exporting model data back to snapshot form.
+   */
   withSnapshotProcessor<
     FS = TFromSnapshotOverride,
     TS = TToSnapshotOverride,
@@ -160,12 +175,18 @@ export type ModelPropToSnapshot<MP extends AnyModelProp> = IsNeverType<
  * A model prop transform.
  */
 export interface ModelPropTransform<TOriginal, TTransformed> {
+  /**
+   * Converts the stored/original value into the transformed value exposed by the model prop.
+   */
   transform(params: {
     originalValue: TOriginal
     cachedTransformedValue: TTransformed | undefined
     setOriginalValue(value: TOriginal): void
   }): TTransformed
 
+  /**
+   * Converts the transformed model value back into the original stored value.
+   */
   untransform(params: {
     transformedValue: TTransformed
     cacheTransformedValue: () => void
@@ -250,6 +271,35 @@ export type ModelIdProp<T extends string = string> = ModelProp<
   true
 >
 
+type TypedModelIdProp<T extends string = string, THasSetter = never> = Omit<
+  ModelProp<T, T | undefined, T, T | undefined, never, true, THasSetter>,
+  "withSetter"
+> & {
+  /**
+   * Enables generation of a setter method for the ID prop (`setId` for `id`, `setCustomId` for `customId`).
+   */
+  withSetter(): TypedModelIdProp<T, string>
+  /**
+   * Enables generation of a setter method for the ID prop and applies a value transform to setter input.
+   */
+  withSetter(valueTransform: ModelPropSetterValueTransform<T>): TypedModelIdProp<T, string>
+  /**
+   * @deprecated Setter methods are preferred.
+   */
+  withSetter(mode: "assign"): TypedModelIdProp<T, string>
+
+  /**
+   * Sets a custom generator for missing model IDs in this `idProp`.
+   */
+  withGenerator(generator: () => T): TypedModelIdProp<T, THasSetter>
+
+  /**
+   * Same as `idProp`, except that it might have a specific TypeScript string template as type.
+   * E.g. `idProp.typedAs<`custom-${string}`>()`
+   */
+  typedAs<U extends string>(): TypedModelIdProp<U, THasSetter>
+}
+
 /**
  * A property that will be used as model id, accessible through $modelId.
  * Can only be used in models and there can be only one per model.
@@ -258,6 +308,7 @@ export const idProp = {
   _setter: false,
   _setterValueTransform: undefined,
   _isId: true,
+  _idGenerator: undefined,
 
   withSetter(modeOrValueTransform?: SetterMode | ModelPropSetterValueTransform<unknown>) {
     const obj: AnyModelProp = Object.create(this)
@@ -267,16 +318,16 @@ export const idProp = {
     return obj
   },
 
+  withGenerator(generator: () => string) {
+    const obj: AnyModelProp = Object.create(this)
+    obj._idGenerator = generator
+    return obj
+  },
+
   typedAs() {
-    return idProp
+    return this
   },
-} as any as ModelIdProp & {
-  /**
-   * Same as `idProp`, except that it might have an specific TypeScript string template as type.
-   * E.g. `typedIdProp<`custom-${string}`>()`
-   */
-  typedAs<T extends string>(): ModelIdProp<T>
-}
+} as unknown as TypedModelIdProp
 
 /**
  * @ignore

packages/lib/src/modelShared/sharedInternalModel.ts

@@ -109,11 +109,11 @@ const setModelInstanceDataFieldWithPrecheck: SetModelInstanceDataFieldFn = (
   return true
 }
 
-const idGenerator = () => getGlobalConfig().modelIdGenerator()
-const tPropForId = tProp(typesString, idGenerator)
-tPropForId._isId = true
-const propForId = prop(idGenerator)
-propForId._isId = true
+const defaultModelIdGenerator = () => getGlobalConfig().modelIdGenerator()
+const tPropForDefaultId = tProp(typesString, defaultModelIdGenerator)
+tPropForDefaultId._isId = true
+const propForDefaultId = prop(defaultModelIdGenerator)
+propForDefaultId._isId = true
 
 type FromSnapshotProcessorFn = (sn: any) => any
 type ToSnapshotProcessorFn = (sn: any, instance: any) => any
@@ -153,11 +153,12 @@ export function sharedInternalModel<
   }
 
   const composedModelProps: ModelProps = modelProps
+  let baseModelProps: ModelProps | undefined
   if (baseModel) {
-    const oldModelProps = getInternalModelClassPropsInfo(baseModel)
-    for (const oldModelPropKey of Object.keys(oldModelProps)) {
+    baseModelProps = getInternalModelClassPropsInfo(baseModel)
+    for (const oldModelPropKey of Object.keys(baseModelProps)) {
       if (!modelProps[oldModelPropKey]) {
-        composedModelProps[oldModelPropKey] = oldModelProps[oldModelPropKey]
+        composedModelProps[oldModelPropKey] = baseModelProps[oldModelPropKey]
       }
     }
   }
@@ -182,17 +183,41 @@ export function sharedInternalModel<
   if (idKeys.length > 0) {
     idKey = idKeys[0]
     const idProp = composedModelProps[idKey]
-    let baseProp: AnyModelProp = needsTypeChecker ? tPropForId : propForId
-    switch (idProp._setter) {
-      case true:
-        baseProp = baseProp.withSetter()
-        break
-      case "assign":
-        baseProp = baseProp.withSetter("assign")
-        break
-      default:
-        break
+    const idPropGenerator = idProp._idGenerator
+    const baseIdProp = baseModelProps?.[idKey]
+    const baseIdPropGenerator = baseIdProp?._idGenerator
+    const isOverridingBaseIdProp = !!baseIdProp?._isId && Object.hasOwn(modelProps, idKey)
+    if (isOverridingBaseIdProp && baseIdPropGenerator !== idPropGenerator) {
+      throw failure(
+        `expected same idProp.withGenerator function when overriding a base idProp, but got different references`
+      )
+    }
+    const resolvedIdGenerator = idPropGenerator ?? baseIdPropGenerator
+    const effectiveModelIdGenerator = resolvedIdGenerator ?? defaultModelIdGenerator
+    let baseProp: AnyModelProp
+    if (effectiveModelIdGenerator === defaultModelIdGenerator) {
+      baseProp = needsTypeChecker ? tPropForDefaultId : propForDefaultId
+    } else {
+      baseProp = needsTypeChecker
+        ? tProp(typesString, effectiveModelIdGenerator)
+        : prop(effectiveModelIdGenerator)
+      baseProp._isId = true
+    }
+    if (idProp._setterValueTransform) {
+      baseProp = baseProp.withSetter(idProp._setterValueTransform)
+    } else {
+      switch (idProp._setter) {
+        case true:
+          baseProp = baseProp.withSetter()
+          break
+        case "assign":
+          baseProp = baseProp.withSetter("assign")
+          break
+        default:
+          break
+      }
     }
+    baseProp._idGenerator = resolvedIdGenerator
     composedModelProps[idKey] = baseProp
   }