Files
Tom Moor 9fe0c7ba2b fix: Preserve existing values when optional update fields are omitted (#14344)
* fix: Preserve existing values when optional update fields are omitted

* chore: Rename setDefined to fill

* chore: Use fill in users.update and teamUpdater
2026-10-26 17:29:17 -04:00

611 lines
17 KiB
TypeScript

import isEqual from "fast-deep-equal";
import { isUndefined, omitBy } from "es-toolkit";
import { isArray, isObject, pick } from "es-toolkit/compat";
import type {
Attributes,
CreateOptions,
CreationAttributes,
DestroyOptions,
FindOptions,
FindOrCreateOptions,
ModelStatic,
NonAttribute,
SaveOptions,
} from "sequelize";
import { DataTypes, Op, UniqueConstraintError } from "sequelize";
import {
AfterCreate,
AfterDestroy,
AfterRestore,
AfterUpdate,
AfterUpsert,
BeforeSave,
Model as SequelizeModel,
} from "sequelize-typescript";
import Logger from "@server/logging/Logger";
import type { Replace, APIContext } from "@server/types";
import { getChangesetSkipped } from "../decorators/Changeset";
import { InternalError } from "@server/errors";
import { afterCommit } from "@server/storage/transaction";
export type EventOverrideOptions = {
/** Override the default event name. */
name?: string;
/** Additional data to publish in the event. */
data?: Record<string, unknown>;
/**
* Whether to persist the event to the database. Defaults to true when using any `withCtx` methods.
*/
persist?: boolean;
};
type EventOptions = EventOverrideOptions & {
/**
* Whether to publish event to the job queue. Defaults to true when using any `withCtx` methods.
*/
publish: boolean;
};
export type HookContext = APIContext["context"] & { event?: EventOptions };
class Model<
// oxlint-disable-next-line @typescript-eslint/no-explicit-any -- Sequelize's Attributes<M> resolves to never under object default; load-bearing for static helpers like saveWithCtx<M extends Model>.
TModelAttributes extends object = any,
TCreationAttributes extends object = TModelAttributes,
> extends SequelizeModel<TModelAttributes, TCreationAttributes> {
/**
* Disables Sequelize's public class field detection, which reports a false positive for the
* per-instance accessors that sequelize-strict-attributes installs on attributes omitted from
* a query's selection.
*/
static _overwrittenAttributesChecked = true;
/**
* The namespace to use for events - defaults to the table name if none is provided.
*/
static eventNamespace: string | undefined;
/**
* Validates this instance, and if the validation passes, persists it to the database.
*/
public saveWithCtx<M extends Model>(
ctx: APIContext,
options?: SaveOptions<Attributes<M>>,
eventOpts?: EventOverrideOptions
) {
const hookContext: HookContext = {
...ctx.context,
event: {
...eventOpts,
publish: true,
},
};
return this.save({ ...options, ...hookContext });
}
/**
* This is the same as calling `fill` and then calling `save`.
*/
public updateWithCtx(
ctx: APIContext,
keys: Partial<TModelAttributes>,
eventOpts?: EventOverrideOptions
) {
const hookContext: HookContext = {
...ctx.context,
event: {
...eventOpts,
publish: true,
},
};
this.fill(keys);
return this.save(hookContext);
}
/**
* Sets the given attributes on the instance, skipping any with an undefined
* value. Use `null` to clear an attribute.
*
* @param keys the attributes to set.
* @returns the instance.
*/
public fill(keys: Partial<TModelAttributes>) {
return this.set(omitBy(keys, isUndefined));
}
/**
* Destroy the row corresponding to this instance. Depending on your setting for paranoid, the row will
* either be completely deleted, or have its deletedAt timestamp set to the current time.
*/
public destroyWithCtx(ctx: APIContext, eventOpts?: EventOverrideOptions) {
const hookContext: HookContext = {
...ctx.context,
event: {
...eventOpts,
publish: true,
},
};
return this.destroy(hookContext);
}
/**
* Restore the row corresponding to this instance. Only available for paranoid models.
*/
public restoreWithCtx(ctx: APIContext, eventOpts?: EventOverrideOptions) {
const hookContext: HookContext = {
...ctx.context,
event: {
...eventOpts,
publish: true,
},
};
return this.restore(hookContext);
}
/**
* Find a row that matches the query, or build and save the row if none is found.
* The successful result of the promise will be (instance, created) - Make sure to use `.then(([...]))`
*
* @param ctx The API context.
* @param options The find or create options.
* @param eventOpts Optional event override options.
* @returns a tuple of the instance and a boolean indicating if it was created.
*/
public static async findOrCreateWithCtx<M extends Model>(
this: ModelStatic<M>,
ctx: APIContext,
options: FindOrCreateOptions<Attributes<M>, CreationAttributes<M>>,
eventOpts?: EventOverrideOptions
): Promise<[M, boolean]> {
const hookContext: HookContext = {
...ctx.context,
event: {
...eventOpts,
publish: true,
},
};
const transaction = ctx.context.transaction;
// First, try to find an existing record
const existing = await this.findOne({
where: options.where,
transaction,
});
if (existing) {
return [existing as M, false];
}
// Record not found, try to create it
try {
const created = await this.create(
Object.assign(
{},
options.defaults,
options.where
) as CreationAttributes<M>,
{ ...hookContext, transaction }
);
return [created as M, true];
} catch (err) {
// Handle race condition: another request created the record first
if (err instanceof UniqueConstraintError) {
const found = await this.findOne({
where: options.where,
transaction,
rejectOnEmpty: true,
});
return [found as M, false];
}
throw err;
}
}
/**
* Destroys every row that matches the given options, publishing an event for
* each. Rows are matched when the destroy runs, so rows written after the
* options were prepared are destroyed too.
*
* @param ctx The API context.
* @param options The destroy options.
* @param eventOpts Optional event override options.
* @returns the number of destroyed rows.
*/
public static destroyWithCtx<M extends Model>(
this: ModelStatic<M>,
ctx: APIContext,
options: DestroyOptions<Attributes<M>>,
eventOpts?: EventOverrideOptions
) {
const hookContext = {
...ctx.context,
...options,
individualHooks: true,
event: {
...eventOpts,
publish: true,
},
};
return this.destroy(hookContext);
}
/**
* Builds a new model instance and calls save on it.
*/
public static createWithCtx<M extends Model>(
this: ModelStatic<M>,
ctx: APIContext,
values?: CreationAttributes<M>,
eventOpts?: EventOverrideOptions,
createOpts?: CreateOptions<M>
) {
const hookContext = {
...ctx.context,
...createOpts,
event: {
...eventOpts,
publish: true,
},
};
return this.create(values, hookContext);
}
@BeforeSave
static async beforeSaveEvent<T extends Model>(model: T) {
model.cacheChangeset();
}
@AfterCreate
static async afterCreateEvent<T extends Model>(
model: T,
context: HookContext
) {
await this.insertEvent("create", model, context);
}
@AfterUpsert
static async afterUpsertEvent<T extends Model>(
model: T,
context: HookContext
) {
await this.insertEvent("create", model, context);
}
@AfterUpdate
static async afterUpdateEvent<T extends Model>(
model: T,
context: HookContext
) {
await this.insertEvent("update", model, context);
}
@AfterDestroy
static async afterDestroyEvent<T extends Model>(
model: T,
context: HookContext
) {
await this.insertEvent("delete", model, context);
}
@AfterRestore
static async afterRestoreEvent<T extends Model>(
model: T,
context: HookContext
) {
await this.insertEvent("create", model, context);
}
/**
* Insert an event into the database recording a mutation to this model.
*
* @param name The name of the event.
* @param model The model that was mutated.
* @param context The API context.
*/
protected static async insertEvent<T extends Model>(
name: string,
model: T,
context: HookContext
) {
const namespace = this.eventNamespace ?? this.tableName;
const models = this.sequelize!.models;
if (!context.event?.publish) {
return;
}
if (!context.transaction) {
Logger.warn("No transaction provided to insertEvent", {
modelId: model.id,
});
}
if (!context.ip) {
Logger.warn("No ip provided to insertEvent", {
modelId: model.id,
});
}
if (context.event.name?.includes(".")) {
throw InternalError(
`Event name (${context.event.name}) should not include a period, the namespace is automatically prefixed`
);
}
const collectionId =
"collectionId" in model
? model.collectionId
: model instanceof models.collection
? model.id
: undefined;
const documentId =
"documentId" in model
? model.documentId
: model instanceof models.document
? model.id
: undefined;
let teamId =
"teamId" in model
? model.teamId
: model instanceof models.team
? model.id
: context.auth?.user?.teamId;
// Membership-style models (e.g. UserMembership, GroupMembership) carry no
// teamId of their own, so derive it from the associated document or
// collection when the mutating context has no authenticated team. This
// guarantees events are never persisted without a team.
if (!teamId && (documentId || collectionId)) {
const parent = documentId
? await models.document.unscoped().findByPk(documentId, {
attributes: ["teamId"],
paranoid: false,
transaction: context.transaction,
})
: await models.collection.unscoped().findByPk(collectionId, {
attributes: ["teamId"],
paranoid: false,
transaction: context.transaction,
});
teamId = parent?.getDataValue("teamId") ?? teamId;
}
const attrs = {
name: `${namespace}.${context.event.name ?? name}`,
modelId: "modelId" in model ? model.modelId : model.id,
collectionId,
documentId,
userId:
"userId" in model
? model.userId
: model instanceof models.user
? model.id
: undefined,
teamId,
actorId:
context.auth?.user?.id ??
(model instanceof models.user && name === "create"
? model.id
: undefined),
authType: context.auth?.type,
ip: context.ip,
changes: model.previousChangeset,
data: context.event.data,
};
if (context.event?.persist !== false) {
return models.event.create(attrs, {
transaction: context.transaction,
});
}
return afterCommit(context.transaction, () =>
// @ts-expect-error Event class
models.event.schedule(attrs)
);
}
/**
* Find all models in batches, calling the callback function for each batch.
*
* @param query The query options.
* @param callback The function to call for each batch of results
* @return The total number of results processed.
*/
static async findAllInBatches<T extends Model>(
this: ModelStatic<T>,
query: Omit<Replace<FindOptions<T>, "limit", "batchLimit">, "order"> & {
/** The maximum number of results to return, after which the query will stop. */
totalLimit?: number;
/** The order of results, as plain [column, direction] pairs. */
order?: Array<[string, "ASC" | "DESC"]>;
},
callback: (results: Array<T>, query: FindOptions<T>) => Promise<void>
): Promise<number> {
const { batchLimit = 10, totalLimit = Infinity, offset, ...rest } = query;
// A raw query with an explicit order is trusted to be unique (it may
// select aggregates where the primary key is unavailable), otherwise
// append the primary key column(s) to guarantee a total, stable order.
const order = [...(rest.order ?? [])];
if (!rest.raw || order.length === 0) {
for (const pk of this.primaryKeyAttributes) {
if (!order.some(([column]) => column === pk)) {
order.push([pk, "ASC"]);
}
}
}
// The cursor columns must be selected for their values to be read back,
// so add any missing ones when the caller restricts attributes.
let attributes = rest.attributes;
if (
Array.isArray(attributes) &&
attributes.every((attr): attr is string => typeof attr === "string")
) {
attributes = [
...new Set([...attributes, ...order.map(([column]) => column)]),
];
}
const cursorValue = (row: T, column: string) =>
typeof row.get === "function"
? row.get(column)
: (row as Record<string, unknown>)[column];
const buildCursor = (lastRow: T) => ({
[Op.or]: order.map(([column, direction], index) => {
const clause: Record<string, unknown> = {};
for (const [prevColumn] of order.slice(0, index)) {
clause[prevColumn] = { [Op.eq]: cursorValue(lastRow, prevColumn) };
}
clause[column] = {
[direction === "DESC" ? Op.lt : Op.gt]: cursorValue(lastRow, column),
};
return clause;
}),
});
let cursor: ReturnType<typeof buildCursor> | undefined;
let currentOffset = offset ?? 0;
let total = 0;
let limit: number;
let results: T[];
do {
limit = Math.min(batchLimit, totalLimit - total);
const findOptions: FindOptions<T> = {
...rest,
attributes,
order,
limit,
offset: currentOffset,
where: cursor ? { [Op.and]: [rest.where ?? {}, cursor] } : rest.where,
};
results = await this.findAll<T>(findOptions);
total += results.length;
await callback(results, findOptions);
if (results.length > 0) {
cursor = buildCursor(results[results.length - 1]);
}
// The cursor supersedes offset-based pagination after the first batch.
currentOffset = 0;
} while (results.length >= limit && total < totalLimit);
return total;
}
/**
* Returns a representation of the attributes that have changed since the last save and their previous values.
*
* @returns An object with `attributes` and `previousAttributes` keys.
*/
public get changeset(): NonAttribute<{
attributes: Partial<TModelAttributes>;
previous: Partial<TModelAttributes>;
}> {
const changes = this.changed() as Array<keyof TModelAttributes> | false;
const attributes: Partial<TModelAttributes> = {};
const previousAttributes: Partial<TModelAttributes> = {};
if (!changes) {
return {
attributes,
previous: previousAttributes,
};
}
const virtualFields = (this.constructor as typeof Model).virtualFields;
const blobFields = (this.constructor as typeof Model).blobFields;
const skippedFields = getChangesetSkipped(this);
for (const change of changes) {
const previous = this.previous(change);
const current = this.getDataValue(change);
if (
virtualFields.includes(String(change)) ||
blobFields.includes(String(change)) ||
skippedFields.includes(String(change))
) {
continue;
}
if (
isObject(previous) &&
isObject(current) &&
!isArray(previous) &&
!isArray(current)
) {
const difference = Object.keys(previous)
.concat(Object.keys(current))
.filter(
(key) =>
!isEqual(Reflect.get(previous, key), Reflect.get(current, key))
);
previousAttributes[change] = pick(
previous,
difference
) as TModelAttributes[keyof TModelAttributes];
attributes[change] = pick(
current,
difference
) as TModelAttributes[keyof TModelAttributes];
} else {
previousAttributes[change] = previous;
attributes[change] = current;
}
}
return {
attributes,
previous: previousAttributes,
};
}
/**
* Cache the current changeset for later use.
*/
protected cacheChangeset() {
const previous = this.changeset;
if (
Object.keys(previous.attributes).length > 0 ||
Object.keys(previous.previous).length > 0
) {
this.previousChangeset = previous;
}
}
/**
* Returns the virtual fields for this model.
*/
protected static get virtualFields() {
const attrs = this.rawAttributes;
return Object.keys(attrs).filter(
(attr) => attrs[attr].type instanceof DataTypes.VIRTUAL
);
}
/**
* Returns the blob fields for this model.
*/
protected static get blobFields() {
const attrs = this.rawAttributes;
return Object.keys(attrs).filter(
(attr) => attrs[attr].type instanceof DataTypes.BLOB
);
}
private previousChangeset: NonAttribute<{
attributes: Partial<TModelAttributes>;
previous: Partial<TModelAttributes>;
}> | null;
}
export default Model;