Feature Request: Hook/callback for internal findMany calls

[tsegreto]

Feature Request: Hook/callback for internal findMany calls

Problem

When using prisma-extension-pagination alongside extensions that add custom args to queries (e.g. prisma-extension-redis's cache option), there's no way to differentiate between the multiple internal findMany calls the pagination library makes.

For cursor-based pagination, paginateWithCursor runs 2 concurrent findMany calls via Promise.all:

1. The main results query (take: limit + 1)
2. A boundary check query (take: -1 or take: 1)

Since both calls receive the same spread of ...query, any custom args (like a cache key) are identical for both. This causes issues like cache key collisions where the boundary check overwrites the main results in cache.

Current workaround

We currently have to strip custom args in paginate() and use a Proxy around the model to re-inject them with a unique suffix per internal findMany call. This works but adds complexity that shouldn't be necessary.

Proposed solution

Expose a onFindMany (or wrapFindMany) callback that receives the args for each internal findMany call along with context about which call it is:

const [users, meta] = await prisma.user
  .paginate({
    where: { status: 'active' },
    orderBy: { id: 'asc' },
  })
  .withCursor({
    limit: 10,
    after: cursor,
    onFindMany: (args, context) => {
      // context.type: 'results' | 'boundaryCheck' | 'count'
      // context.index: 0, 1, 2...
      return {
        ...args,
        cache: {
          key: `my:cache:key:${context.type}`,
        },
      };
    },
  });

Alternative: strip unknown args

A simpler (but less flexible) approach would be to strip any non-Prisma args before passing them into internal findMany calls, and instead accept extension-specific config as a separate top-level option:

.paginate({
  where: { status: 'active' },
}, {
  // Separate bag for extension args, not spread into findMany
  extensions: { cache: { key: 'my:key' } }
})

Context

This is specifically painful when combining with prisma-extension-redis, but would affect any Prisma extension that adds custom args to findMany. Related discussion: the pagination library currently spreads the full query object into every internal call without filtering, which leaks consumer-provided custom args into calls they weren't intended for.

[tsegreto]

My current solution for those who are running into the same problem:

type CacheArg = { cache?: boolean | CacheOptions };
type BaseFindManyArgs<T> = Omit<Prisma.Args<T, "findMany">, "cursor" | "take" | "skip">;
type PaginateArgs<T> = BaseFindManyArgs<T> & CacheArg;
type FindManyResult<T, A> = Prisma.Result<T, Omit<A, "cache">, "findMany">;

type PaginatorReturn<T, A> = {
	withCursor: <Cursor extends NonNullable<Prisma.Args<T, "findMany">["cursor"]>>(
		options: CursorPaginationOptions<FindManyResult<T, A>[number], Cursor>,
	) => Promise<[FindManyResult<T, A>, CursorPaginationMeta]>;
	withPages: <TOptions extends PageNumberPaginationOptions>(
		options: TOptions,
	) => Promise<
		[FindManyResult<T, A>, PageNumberPaginationMeta<TOptions extends { includePageCount: true } ? true : false>]
	>;
};

type CacheKeyConfig = { key: string } & Omit<CacheOptions, "key">;

const CACHEABLE_OPS = new Set(["findMany", "count"]);

/**
 * Creates a proxy around the model that intercepts findMany/count calls
 * from the pagination library and injects `cache` with a unique suffix
 * per call. This prevents the key collision that occurs when the
 * pagination library makes multiple internal findMany calls (main results
 * + boundary checks) that would otherwise share the same cache key.
 */
function createCachingProxy<T>(model: T, cacheConfig: CacheKeyConfig): T {
	let callIdx = 0;

	return new Proxy(model as object, {
		get(target, prop, receiver) {
			const value = Reflect.get(target, prop, receiver);
			if (typeof prop === "string" && CACHEABLE_OPS.has(prop)) {
				return (args: Record<string, unknown>) => {
					callIdx++;
					return (value as Function).call(model, {
						...args,
						cache: { ...cacheConfig, key: `${cacheConfig.key}:${callIdx}` },
					});
				};
			}
			return value;
		},
	}) as T;
}

export function paginationExtension(options?: Parameters<typeof createPaginator>[0]) {
	const basePaginate = createPaginator(options);

	return Prisma.defineExtension({
		name: "pagination",
		model: {
			$allModels: {
				paginate<T, A>(this: T, args?: Prisma.Exact<A, PaginateArgs<T>>): PaginatorReturn<T, A> {
					const { cache, ...queryArgs } = (args ?? {}) as Record<string, unknown>;

					const cacheConfig =
						typeof cache === "object" && cache !== null && "key" in cache
							? (cache as CacheKeyConfig)
							: null;

					const model = cacheConfig ? createCachingProxy(this, cacheConfig) : this;

					return (basePaginate as Function).call(model, queryArgs) as PaginatorReturn<T, A>;
				},
			},
		},
	});
}