mirror of
https://github.com/outline/outline.git
synced 2026-11-20 21:23:06 +03:00
* fix: Preserve existing values when optional update fields are omitted * chore: Rename setDefined to fill * chore: Use fill in users.update and teamUpdater
611 lines
17 KiB
TypeScript
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;
|