Files
outline/app/models/base/Model.ts
T
Tom Moor 57c110dbe5 chore: Upgrade MobX (#13554)
* Upgrade Mobx

* fix: Enforce MobX action boundaries

* fix: Wrap static observable updates in actions

* Remove iteration tests
2026-09-02 20:31:37 -04:00

316 lines
8.7 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";
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>) {
for (const field of getFieldsForModel(this)) {
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;
}