Files
outline/app/models/base/Model.ts
T
Tom MoorandClaude Fable 5.1 b3a1cef018 fix: Revision view does not re-render when late-loaded content arrives (#13683)
* fix: Revision view does not re-render when late content arrives

Pre-define every MobX-decorated field on model instances so reads made
before the data arrives are tracked.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* test: Inherited base-class fields are observable on partial models

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-07 00:51:16 -04:00

359 lines
10 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { isEqual, pick } from "es-toolkit/compat";
import { action, makeObservable, observable, toJS } from "mobx";
import type { JSONObject } from "@shared/types";
import type Store from "~/stores/base/Store";
import type { PartialExcept } from "~/types";
import Logger from "~/utils/Logger";
import { getFieldsForModel, getFieldsForModelClass } from "../decorators/Field";
import { LifecycleManager } from "../decorators/Lifecycle";
import { getRelationsForModelClass } from "../decorators/Relation";
/**
* MobX records decorator annotations on the prototype under a symbol with this
* description.
*/
const storedAnnotationsDescription = "mobx-stored-annotations";
/**
* Returns the keys of every decorated member on a model, including those
* inherited from base classes. The nearest record on the prototype chain
* already includes the parents' annotations, so the search stops there.
*
* With `useDefineForClassFields: false` a field declared without an initializer
* never exists on the instance, so MobX cannot annotate it. This helper, and
* the pre-definition in `initialize`, can be removed if that compiler option
* is enabled.
*
* @param target the model to inspect.
* @returns the keys annotated with a MobX decorator.
*/
function getAnnotatedKeysForModel(target: Model): (string | symbol)[] {
let prototype = Object.getPrototypeOf(target);
while (prototype && prototype !== Object.prototype) {
const symbol = Object.getOwnPropertySymbols(prototype).find(
(candidate) => candidate.description === storedAnnotationsDescription
);
if (symbol) {
const annotations: Record<string | symbol, unknown> = Reflect.get(
prototype,
symbol
);
return Reflect.ownKeys(annotations);
}
prototype = Object.getPrototypeOf(prototype);
}
return [];
}
export default abstract class Model {
static modelName: string;
/**
* Restores data written by toPersisted to the shape the model expects,
* discarding any properties that are not declared fields. Records written by
* a different version of the app may not match the current model.
*
* @param record the persisted representation of a model.
* @returns the data to construct or update a model with.
*/
static fromPersisted<T extends Model>(
record: Record<string, unknown>
): PartialExcept<T, "id"> {
const fields = getFieldsForModelClass(this);
return JSON.parse(JSON.stringify(pick(record, ["id", ...fields])));
}
@observable
id: string;
@observable
isSaving = false;
@observable
isNew = false;
@observable
createdAt: string;
@observable
updatedAt: string;
store: Store<Model>;
constructor(_fields: Record<string, unknown>, store: Store<Model>) {
this.store = store;
}
/**
* Applies the initial data and makes the instance observable.
*
* Call this from the constructor of the most-derived class. MobX can only
* annotate fields that already exist on the instance, and a subclass's fields
* do not exist until its own constructor has run.
*
* @param fields the data to construct the model with.
*/
protected initialize(fields: Record<string, unknown>) {
const declared = [
...getFieldsForModel(this),
...getAnnotatedKeysForModel(this),
];
for (const field of declared) {
if (field in this) {
continue;
}
Object.defineProperty(this, field, {
configurable: true,
enumerable: true,
value: undefined,
writable: true,
});
}
this.updateData(fields);
this.isNew = !this.id;
makeObservable(this);
this.initialized = true;
}
/**
* Ensures all the defined relations and policies for the model are in memory.
*
* @returns A promise that resolves when loading is complete.
*/
async loadRelations(
this: Model,
options: { withoutPolicies?: boolean } = {}
): Promise<unknown> {
// this is to ensure that multiple loads don’t happen in parallel
if (this.loadingRelations) {
return this.loadingRelations;
}
const promises = [];
const relations = getRelationsForModelClass(
this.constructor as typeof Model
);
if (relations) {
for (const properties of relations.values()) {
const store = this.store.rootStore.getStoreForModelName(
properties.relationClassResolver().modelName
);
if ("canFetchById" in store && store.canFetchById) {
const id = this[properties.idKey];
if (id) {
promises.push(store.fetch(id as string));
}
}
}
}
const policy = this.store.rootStore.policies.get(this.id);
if (!policy && !options.withoutPolicies && this.store.canFetchById) {
promises.push(this.store.fetch(this.id, { force: true }));
}
try {
this.loadingRelations = Promise.all(promises);
return await this.loadingRelations;
} finally {
this.loadingRelations = undefined;
}
}
/**
* Persists the model to the server API
*
* @param params Specific fields to save, if not provided the model will be serialized
* @param options Options to pass to the store
* @returns A promise that resolves with the updated model
*/
save = async (
params?: Record<string, unknown>,
options?: Record<string, string | boolean | number | undefined>
): Promise<Model> => {
const isNew = this.isNew;
this.isSaving = true;
try {
// ensure that the id is passed if the document has one
if (!params) {
params = this.toAPI();
}
if (isNew) {
LifecycleManager.executeHooks(this.constructor, "beforeCreate", this);
} else {
LifecycleManager.executeHooks(this.constructor, "beforeUpdate", this);
}
const model = await this.store.save(
{
...params,
id: this.id,
},
{
...options,
isNew,
}
);
// if saving is successful set the new values on the model itself
this.updateData(Object.assign({}, params, model));
if (isNew) {
LifecycleManager.executeHooks(this.constructor, "afterCreate", this);
} else {
LifecycleManager.executeHooks(this.constructor, "afterUpdate", this);
}
return model;
} finally {
this.isSaving = false;
}
};
updateData = action((data: Record<string, unknown>) => {
if (this.initialized) {
LifecycleManager.executeHooks(this.constructor, "beforeChange", this);
}
const previousAttributes = this.toAPI();
let addedKeys = false;
for (const key in data) {
try {
// Some models are serialized with the initialized flag, this should be ignored.
if (key === "initialized") {
continue;
}
// @ts-expect-error TODO
if (isEqual(toJS(this[key]), data[key])) {
continue;
}
// A field declared without a default does not exist until it is first
// assigned, so MobX could not annotate it when the model was created.
addedKeys ||= !(key in this);
// @ts-expect-error TODO
this[key] = data[key];
} catch (error) {
Logger.warn(`Error setting ${key} on model`, { error });
}
}
// Annotate any field that this payload introduced. Re-annotating a field
// that is already observable is a no-op.
if (addedKeys && this.initialized) {
makeObservable(this);
}
this.isNew = false;
this.persistedAttributes = this.toAPI();
if (this.initialized) {
LifecycleManager.executeHooks(
this.constructor,
"afterChange",
this,
previousAttributes
);
}
});
fetch = (options?: JSONObject) => this.store.fetch(this.id, options);
refresh = () =>
this.fetch({
force: true,
});
delete = async () => {
this.isSaving = true;
try {
LifecycleManager.executeHooks(this.constructor, "beforeDelete", this);
const response = await this.store.delete(this);
LifecycleManager.executeHooks(this.constructor, "afterDelete", this);
return response;
} finally {
this.isSaving = false;
}
};
/**
* Returns a plain object representation of fields on the model for
* persistence to the server API
*
* @returns A plain object representation of the model
*/
toAPI = (): Partial<Model> => {
const fields = getFieldsForModel(this);
return pick(this, fields);
};
/**
* Returns a plain object representation of the model, containing its
* identifier and declared fields only, safe to store outside of memory.
* Internal state and observables are not included.
*
* @returns A plain object representation of the model
*/
toPersisted = (): PartialExcept<Model, "id"> =>
JSON.parse(JSON.stringify({ ...this.toAPI(), id: this.id }));
/**
* Returns a plain object representation of all the properties on the model
* overrides the native toJSON method to avoid attempting to serialize store
*
* @returns A plain object representation of the model
*/
toJSON() {
const output: Partial<typeof this> = {};
for (const property in this) {
if (
// oxlint-disable-next-line no-prototype-builtins
this.hasOwnProperty(property) &&
!["persistedAttributes", "store", "isSaving", "isNew"].includes(
property
)
) {
output[property] = this[property];
}
}
return output;
}
/**
* Returns a boolean indicating if the model has changed since it was last
* persisted to the server
*
* @returns boolean true if unsaved
*/
isDirty(): boolean {
const attributes = this.toAPI();
if (Object.keys(attributes).length === 0) {
Logger.warn("Checking dirty on model with no @Field decorators");
}
return (
JSON.stringify(this.persistedAttributes) !== JSON.stringify(attributes)
);
}
protected persistedAttributes: Partial<Model> = {};
/** A promise that resolves when all relations have been loaded. */
private loadingRelations: Promise<unknown[]> | undefined;
/** A boolean representing if the constructor has been called. */
private initialized = false;
}