@zenstackhq/client-helpers 3.1.0

package/src/nested-write-visitor.ts

@@ -0,0 +1,359 @@
+import { enumerate } from '@zenstackhq/common-helpers';
+import type { FieldDef, SchemaDef } from '@zenstackhq/schema';
+import { ORMWriteActions, type MaybePromise, type ORMWriteActionType } from './types';
+
+type NestingPathItem = { field?: FieldDef; model: string; where: any; unique: boolean };
+
+/**
+ * Context for visiting
+ */
+export type NestedWriteVisitorContext = {
+    /**
+     * Parent data, can be used to replace fields
+     */
+    parent: any;
+
+    /**
+     * Current field, undefined if toplevel
+     */
+    field?: FieldDef;
+
+    /**
+     * A top-down path of all nested update conditions and corresponding field till now
+     */
+    nestingPath: NestingPathItem[];
+};
+
+/**
+ * NestedWriteVisitor's callback actions. A call back function should return true or void to indicate
+ * that the visitor should continue traversing its children, or false to stop. It can also return an object
+ * to let the visitor traverse it instead of its original children.
+ */
+export type NestedWriteVisitorCallback = {
+    create?: (model: string, data: any, context: NestedWriteVisitorContext) => MaybePromise<boolean | object | void>;
+
+    createMany?: (
+        model: string,
+        args: { data: any; skipDuplicates?: boolean },
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    connectOrCreate?: (
+        model: string,
+        args: { where: object; create: any },
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    connect?: (
+        model: string,
+        args: object,
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    disconnect?: (
+        model: string,
+        args: object,
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    set?: (model: string, args: object, context: NestedWriteVisitorContext) => MaybePromise<boolean | object | void>;
+
+    update?: (model: string, args: object, context: NestedWriteVisitorContext) => MaybePromise<boolean | object | void>;
+
+    updateMany?: (
+        model: string,
+        args: { where?: object; data: any },
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    upsert?: (
+        model: string,
+        args: { where: object; create: any; update: any },
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    delete?: (
+        model: string,
+        args: object | boolean,
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    deleteMany?: (
+        model: string,
+        args: any | object,
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<boolean | object | void>;
+
+    field?: (
+        field: FieldDef,
+        action: ORMWriteActionType,
+        data: any,
+        context: NestedWriteVisitorContext,
+    ) => MaybePromise<void>;
+};
+
+/**
+ * Recursive visitor for nested write (create/update) payload.
+ */
+export class NestedWriteVisitor {
+    constructor(
+        private readonly schema: SchemaDef,
+        private readonly callback: NestedWriteVisitorCallback,
+    ) {}
+
+    private isWriteAction(value: string): value is ORMWriteActionType {
+        return ORMWriteActions.includes(value as ORMWriteActionType);
+    }
+
+    /**
+     * Start visiting
+     *
+     * @see NestedWriteVisitorCallback
+     */
+    async visit(model: string, action: ORMWriteActionType, args: any): Promise<void> {
+        if (!args) {
+            return;
+        }
+
+        let topData = args;
+
+        switch (action) {
+            // create has its data wrapped in 'data' field
+            case 'create':
+                topData = topData.data;
+                break;
+
+            case 'delete':
+            case 'deleteMany':
+                topData = topData.where;
+                break;
+        }
+
+        await this.doVisit(model, action, topData, undefined, undefined, []);
+    }
+
+    private async doVisit(
+        model: string,
+        action: ORMWriteActionType,
+        data: any,
+        parent: any,
+        field: FieldDef | undefined,
+        nestingPath: NestingPathItem[],
+    ): Promise<void> {
+        if (!data) {
+            return;
+        }
+
+        const toplevel = field == undefined;
+
+        const context = { parent, field, nestingPath: [...nestingPath] };
+        const pushNewContext = (field: FieldDef | undefined, model: string, where: any, unique = false) => {
+            return { ...context, nestingPath: [...context.nestingPath, { field, model, where, unique }] };
+        };
+
+        // visit payload
+        switch (action) {
+            case 'create':
+                for (const item of this.enumerateReverse(data)) {
+                    const newContext = pushNewContext(field, model, {});
+                    let callbackResult: any;
+                    if (this.callback.create) {
+                        callbackResult = await this.callback.create(model, item, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        const subPayload = typeof callbackResult === 'object' ? callbackResult : item;
+                        await this.visitSubPayload(model, action, subPayload, newContext.nestingPath);
+                    }
+                }
+                break;
+
+            case 'createMany':
+            case 'createManyAndReturn':
+                {
+                    const newContext = pushNewContext(field, model, {});
+                    let callbackResult: any;
+                    if (this.callback.createMany) {
+                        callbackResult = await this.callback.createMany(model, data, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        const subPayload = typeof callbackResult === 'object' ? callbackResult : data.data;
+                        await this.visitSubPayload(model, action, subPayload, newContext.nestingPath);
+                    }
+                }
+                break;
+
+            case 'connectOrCreate':
+                for (const item of this.enumerateReverse(data)) {
+                    const newContext = pushNewContext(field, model, item.where);
+                    let callbackResult: any;
+                    if (this.callback.connectOrCreate) {
+                        callbackResult = await this.callback.connectOrCreate(model, item, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        const subPayload = typeof callbackResult === 'object' ? callbackResult : item.create;
+                        await this.visitSubPayload(model, action, subPayload, newContext.nestingPath);
+                    }
+                }
+                break;
+
+            case 'connect':
+                if (this.callback.connect) {
+                    for (const item of this.enumerateReverse(data)) {
+                        const newContext = pushNewContext(field, model, item, true);
+                        await this.callback.connect(model, item, newContext);
+                    }
+                }
+                break;
+
+            case 'disconnect':
+                // disconnect has two forms:
+                //   if relation is to-many, the payload is a unique filter object
+                //   if relation is to-one, the payload can only be boolean `true`
+                if (this.callback.disconnect) {
+                    for (const item of this.enumerateReverse(data)) {
+                        const newContext = pushNewContext(field, model, item, typeof item === 'object');
+                        await this.callback.disconnect(model, item, newContext);
+                    }
+                }
+                break;
+
+            case 'set':
+                if (this.callback.set) {
+                    for (const item of this.enumerateReverse(data)) {
+                        const newContext = pushNewContext(field, model, item, true);
+                        await this.callback.set(model, item, newContext);
+                    }
+                }
+                break;
+
+            case 'update':
+                for (const item of this.enumerateReverse(data)) {
+                    const newContext = pushNewContext(field, model, item.where);
+                    let callbackResult: any;
+                    if (this.callback.update) {
+                        callbackResult = await this.callback.update(model, item, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        const subPayload =
+                            typeof callbackResult === 'object'
+                                ? callbackResult
+                                : typeof item.data === 'object'
+                                  ? item.data
+                                  : item;
+                        await this.visitSubPayload(model, action, subPayload, newContext.nestingPath);
+                    }
+                }
+                break;
+
+            case 'updateMany':
+            case 'updateManyAndReturn':
+                for (const item of this.enumerateReverse(data)) {
+                    const newContext = pushNewContext(field, model, item.where);
+                    let callbackResult: any;
+                    if (this.callback.updateMany) {
+                        callbackResult = await this.callback.updateMany(model, item, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        const subPayload = typeof callbackResult === 'object' ? callbackResult : item;
+                        await this.visitSubPayload(model, action, subPayload, newContext.nestingPath);
+                    }
+                }
+                break;
+
+            case 'upsert': {
+                for (const item of this.enumerateReverse(data)) {
+                    const newContext = pushNewContext(field, model, item.where);
+                    let callbackResult: any;
+                    if (this.callback.upsert) {
+                        callbackResult = await this.callback.upsert(model, item, newContext);
+                    }
+                    if (callbackResult !== false) {
+                        if (typeof callbackResult === 'object') {
+                            await this.visitSubPayload(model, action, callbackResult, newContext.nestingPath);
+                        } else {
+                            await this.visitSubPayload(model, action, item.create, newContext.nestingPath);
+                            await this.visitSubPayload(model, action, item.update, newContext.nestingPath);
+                        }
+                    }
+                }
+                break;
+            }
+
+            case 'delete': {
+                if (this.callback.delete) {
+                    for (const item of this.enumerateReverse(data)) {
+                        const newContext = pushNewContext(field, model, toplevel ? item.where : item);
+                        await this.callback.delete(model, item, newContext);
+                    }
+                }
+                break;
+            }
+
+            case 'deleteMany':
+                if (this.callback.deleteMany) {
+                    for (const item of this.enumerateReverse(data)) {
+                        const newContext = pushNewContext(field, model, toplevel ? item.where : item);
+                        await this.callback.deleteMany(model, item, newContext);
+                    }
+                }
+                break;
+
+            default: {
+                throw new Error(`unhandled action type ${action}`);
+            }
+        }
+    }
+
+    private async visitSubPayload(
+        model: string,
+        action: ORMWriteActionType,
+        payload: any,
+        nestingPath: NestingPathItem[],
+    ) {
+        for (const item of enumerate(payload)) {
+            if (!item || typeof item !== 'object') {
+                continue;
+            }
+            for (const field of Object.keys(item)) {
+                const fieldDef = this.schema.models[model]?.fields[field];
+                if (!fieldDef) {
+                    continue;
+                }
+
+                if (fieldDef.relation) {
+                    if (item[field]) {
+                        // recurse into nested payloads
+                        for (const [subAction, subData] of Object.entries<any>(item[field])) {
+                            if (this.isWriteAction(subAction) && subData) {
+                                await this.doVisit(fieldDef.type, subAction, subData, item[field], fieldDef, [
+                                    ...nestingPath,
+                                ]);
+                            }
+                        }
+                    }
+                } else {
+                    // visit plain field
+                    if (this.callback.field) {
+                        await this.callback.field(fieldDef, action, item[field], {
+                            parent: item,
+                            nestingPath,
+                            field: fieldDef,
+                        });
+                    }
+                }
+            }
+        }
+    }
+
+    // enumerate a (possible) array in reverse order, so that the enumeration
+    // callback can safely delete the current item
+    private *enumerateReverse(data: any) {
+        if (Array.isArray(data)) {
+            for (let i = data.length - 1; i >= 0; i--) {
+                yield data[i];
+            }
+        } else {
+            yield data;
+        }
+    }
+}

package/src/optimistic.ts

@@ -0,0 +1,139 @@
+import type { SchemaDef } from '@zenstackhq/schema';
+import { log, type Logger } from './logging';
+import { applyMutation } from './mutator';
+import type { ORMWriteActionType, QueryInfo } from './types';
+
+/**
+ * Custom optimistic data provider. It takes query information (usually fetched from query cache)
+ * and returns a verdict on how to optimistically update the query data.
+ *
+ * @param args Arguments.
+ * @param args.queryModel The model of the query.
+ * @param args.queryOperation The operation of the query, `findMany`, `count`, etc.
+ * @param args.queryArgs The arguments of the query.
+ * @param args.currentData The current cache data for the query.
+ * @param args.mutationArgs The arguments of the mutation.
+ */
+export type OptimisticDataProvider = (args: {
+    queryModel: string;
+    queryOperation: string;
+    queryArgs: any;
+    currentData: any;
+    mutationArgs: any;
+}) => OptimisticDataProviderResult | Promise<OptimisticDataProviderResult>;
+
+/**
+ * Result of optimistic data provider.
+ */
+export type OptimisticDataProviderResult = {
+    /**
+     * Kind of the result.
+     *   - Update: use the `data` field to update the query cache.
+     *   - Skip: skip the optimistic update for this query.
+     *   - ProceedDefault: proceed with the default optimistic update.
+     */
+    kind: 'Update' | 'Skip' | 'ProceedDefault';
+
+    /**
+     * Data to update the query cache. Only applicable if `kind` is 'Update'.
+     *
+     * If the data is an object with fields updated, it should have a `$optimistic`
+     * field set to `true`. If it's an array and an element object is created or updated,
+     * the element should have a `$optimistic` field set to `true`.
+     */
+    data?: any;
+};
+
+/**
+ * Options for optimistic update.
+ */
+export type OptimisticUpdateOptions = {
+    /**
+     * A custom optimistic data provider.
+     */
+    optimisticDataProvider?: OptimisticDataProvider;
+};
+
+/**
+ * Creates a function that performs optimistic updates for queries potentially
+ * affected by the given mutation operation.
+ *
+ * @param model Model under mutation.
+ * @param operation Mutation operation (e.g, `update`).
+ * @param schema The schema.
+ * @param options Optimistic update options.
+ * @param getAllQueries Callback to get all cached queries.
+ * @param logging Logging option.
+ */
+export function createOptimisticUpdater(
+    model: string,
+    operation: string,
+    schema: SchemaDef,
+    options: OptimisticUpdateOptions,
+    getAllQueries: () => readonly QueryInfo[],
+    logging: Logger | undefined,
+) {
+    return async (...args: unknown[]) => {
+        const [mutationArgs] = args;
+
+        for (const queryInfo of getAllQueries()) {
+            const logInfo = JSON.stringify({
+                model: queryInfo.model,
+                operation: queryInfo.operation,
+                args: queryInfo.args,
+            });
+
+            if (!queryInfo.optimisticUpdate) {
+                if (logging) {
+                    log(logging, `Skipping optimistic update for ${logInfo} due to opt-out`);
+                }
+                continue;
+            }
+
+            if (options.optimisticDataProvider) {
+                const providerResult = await options.optimisticDataProvider({
+                    queryModel: queryInfo.model,
+                    queryOperation: queryInfo.operation,
+                    queryArgs: queryInfo.args,
+                    currentData: queryInfo.data,
+                    mutationArgs,
+                });
+
+                if (providerResult?.kind === 'Skip') {
+                    // skip
+                    if (logging) {
+                        log(logging, `Skipping optimistic updating due to provider result: ${logInfo}`);
+                    }
+                    continue;
+                } else if (providerResult?.kind === 'Update') {
+                    // update cache
+                    if (logging) {
+                        log(logging, `Optimistically updating due to provider result: ${logInfo}`);
+                    }
+                    queryInfo.updateData(providerResult.data, true);
+                    continue;
+                }
+            }
+
+            // proceed with default optimistic update
+            const mutatedData = await applyMutation(
+                queryInfo.model,
+                queryInfo.operation,
+                queryInfo.data,
+                model,
+                operation as ORMWriteActionType,
+                mutationArgs,
+                schema,
+                logging,
+            );
+
+            if (mutatedData !== undefined) {
+                // mutation applicable to this query, update cache
+                if (logging) {
+                    log(logging, `Optimistically updating due to mutation "${model}.${operation}": ${logInfo}`);
+                }
+                queryInfo.updateData(mutatedData, true);
+            }
+        }
+    };
+}

package/src/query-analysis.ts

@@ -0,0 +1,111 @@
+import type { SchemaDef } from '@zenstackhq/schema';
+import { NestedReadVisitor } from './nested-read-visitor';
+import { NestedWriteVisitor } from './nested-write-visitor';
+import type { ORMWriteActionType } from './types';
+
+/**
+ * Gets models read (including nested ones) given a query args.
+ */
+export function getReadModels(model: string, schema: SchemaDef, args: any) {
+    const result = new Set<string>();
+    result.add(model);
+    const visitor = new NestedReadVisitor(schema, {
+        field: (model) => {
+            result.add(model);
+            return true;
+        },
+    });
+    visitor.visit(model, args);
+    return [...result];
+}
+
+/**
+ * Gets mutated models (including nested ones) given a mutation args.
+ */
+export async function getMutatedModels(
+    model: string,
+    operation: ORMWriteActionType,
+    mutationArgs: any,
+    schema: SchemaDef,
+) {
+    const result = new Set<string>();
+    result.add(model);
+
+    if (mutationArgs) {
+        const addModel = (model: string) => void result.add(model);
+
+        // add models that are cascaded deleted recursively
+        const addCascades = (model: string) => {
+            const cascades = new Set<string>();
+            const visited = new Set<string>();
+            collectDeleteCascades(model, schema, cascades, visited);
+            cascades.forEach((m) => addModel(m));
+        };
+
+        const visitor = new NestedWriteVisitor(schema, {
+            create: addModel,
+            createMany: addModel,
+            connectOrCreate: addModel,
+            connect: addModel,
+            disconnect: addModel,
+            set: addModel,
+            update: addModel,
+            updateMany: addModel,
+            upsert: addModel,
+            delete: (model) => {
+                addModel(model);
+                addCascades(model);
+            },
+            deleteMany: (model) => {
+                addModel(model);
+                addCascades(model);
+            },
+        });
+        await visitor.visit(model, operation, mutationArgs);
+    }
+
+    // include delegate base models recursively
+    result.forEach((m) => {
+        getBaseRecursively(m, schema, result);
+    });
+
+    return [...result];
+}
+
+function collectDeleteCascades(model: string, schema: SchemaDef, result: Set<string>, visited: Set<string>) {
+    if (visited.has(model)) {
+        // break circle
+        return;
+    }
+    visited.add(model);
+
+    const modelDef = schema.models[model];
+    if (!modelDef) {
+        return;
+    }
+
+    for (const [modelName, modelDef] of Object.entries(schema.models)) {
+        if (!modelDef) {
+            continue;
+        }
+        for (const fieldDef of Object.values(modelDef.fields)) {
+            if (fieldDef.relation?.onDelete === 'Cascade' && fieldDef.type === model) {
+                if (!result.has(modelName)) {
+                    result.add(modelName);
+                }
+                collectDeleteCascades(modelName, schema, result, visited);
+            }
+        }
+    }
+}
+
+function getBaseRecursively(model: string, schema: SchemaDef, result: Set<string>) {
+    const modelDef = schema.models[model];
+    if (!modelDef) {
+        return;
+    }
+    if (modelDef.baseModel) {
+        result.add(modelDef.baseModel);
+        getBaseRecursively(modelDef.baseModel, schema, result);
+    }
+}

package/src/types.ts

@@ -0,0 +1,82 @@
+/**
+ * A type that represents either a value of type T or a Promise that resolves to type T.
+ */
+export type MaybePromise<T> = T | Promise<T> | PromiseLike<T>;
+
+/**
+ * List of ORM write actions.
+ */
+export const ORMWriteActions = [
+    'create',
+    'createMany',
+    'createManyAndReturn',
+    'connectOrCreate',
+    'update',
+    'updateMany',
+    'updateManyAndReturn',
+    'upsert',
+    'connect',
+    'disconnect',
+    'set',
+    'delete',
+    'deleteMany',
+] as const;
+
+/**
+ * Type representing ORM write action types.
+ */
+export type ORMWriteActionType = (typeof ORMWriteActions)[number];
+
+/**
+ * Type for query and mutation errors.
+ */
+export type QueryError = Error & {
+    /**
+     * Additional error information.
+     */
+    info?: unknown;
+
+    /**
+     * HTTP status code.
+     */
+    status?: number;
+};
+
+/**
+ * Information about a cached query.
+ */
+export type QueryInfo = {
+    /**
+     * Model of the query.
+     */
+    model: string;
+
+    /**
+     * Query operation, e.g., `findUnique`
+     */
+    operation: string;
+
+    /**
+     * Query arguments.
+     */
+    args: unknown;
+
+    /**
+     * Current data cached for this query.
+     */
+    data: unknown;
+
+    /**
+     * Whether optimistic update is enabled for this query.
+     */
+    optimisticUpdate: boolean;
+
+    /**
+     * Function to update the cached data.
+     *
+     * @param data New data to set.
+     * @param cancelOnTheFlyQueries Whether to cancel on-the-fly queries to avoid accidentally
+     * overwriting the optimistic update.
+     */
+    updateData: (data: unknown, cancelOnTheFlyQueries: boolean) => void;
+};