payload 4.0.0-internal.e55ccef → 4.0.0-internal.ea6e8f8

package/dist/branching/resolveBranch.js

@@ -0,0 +1,363 @@
+import { getDataLoader } from '../collections/dataloader.js';
+import { branchesCollectionSlug, MAIN_BRANCH } from './types.js';
+const stateKey = '_branchState';
+const getBranchingConfig = (req)=>req?.payload?.config?.branching;
+/**
+ * Resolves the active branch for a request.
+ *
+ * The branch is an argument, exactly like `locale` and `depth`: it is whatever
+ * the caller passed, and `main` when they passed nothing. Nothing is read from
+ * storage here — no preference lookup, no cookie — so an unbranched request
+ * costs nothing beyond this function.
+ *
+ * Where the admin UI's persisted selection turns into that argument is the
+ * admin UI's business (`initAdminContext`), the same division `locale` already uses.
+ *
+ * Precedence, highest first:
+ *   1. explicit Local API argument (`req.branch`, set by the caller)
+ *   2. `branch` query param
+ *   3. `main`
+ */ export const resolveBranch = (req)=>{
+    const branching = getBranchingConfig(req);
+    if (!branching?.enabled) {
+        return MAIN_BRANCH;
+    }
+    const context = req.context;
+    const existing = context?.[stateKey];
+    if (existing) {
+        return existing.branch;
+    }
+    // The bypass sentinel `createPayloadRequest` sets for `branch: false`. Honoured here and not
+    // only at the database layer, because a request told to ignore branching must not
+    // report a branch to anything that asks — a `branch: false` request built from an HTTP
+    // request still carries `?branch=` in its query, and falling through to it made the
+    // merge engine resolve against the very branch it was merging.
+    if (context?._branchBypass) {
+        req.branch = MAIN_BRANCH;
+        return MAIN_BRANCH;
+    }
+    const branch = resolveBranchFromRequest(req) ?? MAIN_BRANCH;
+    if (context) {
+        context[stateKey] = {
+            branch,
+            deleted: new Map(),
+            manifest: new Map(),
+            manifestLoaded: false,
+            operations: new Map(),
+            rowIDs: new Map()
+        };
+    }
+    req.branch = branch;
+    return branch;
+};
+/**
+ * The branch the caller asked for, whether through the Local API option or the
+ * `branch` query param — the same two ways `locale` is supplied.
+ */ const resolveBranchFromRequest = (req)=>{
+    if (typeof req.branch === 'string' && req.branch) {
+        return req.branch;
+    }
+    if (typeof req.query?.branch === 'string' && req.query.branch) {
+        return req.query.branch;
+    }
+    return undefined;
+};
+/**
+ * Loads every change the active branch has made, in one query, and groups it
+ * by collection in memory.
+ *
+ * One query per request rather than per collection: a request touching a dozen
+ * collections still issues a single manifest read. Bounded by branch size, not
+ * table size.
+ */ export const loadBranchManifest = async (req)=>{
+    const branch = resolveBranch(req);
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (!state || branch === MAIN_BRANCH) {
+        return new Map();
+    }
+    if (state.manifestLoaded) {
+        return state.manifest;
+    }
+    // Marked loaded up front so the manifest read below — which itself goes
+    // through the adapter — cannot recurse back into loading the manifest.
+    state.manifestLoaded = true;
+    const { docs } = await req.payload.db.find({
+        collection: 'payload-branch-changes',
+        limit: 0,
+        pagination: false,
+        req,
+        where: {
+            and: [
+                {
+                    branch: {
+                        equals: branch
+                    }
+                },
+                {
+                    entityType: {
+                        equals: 'collection'
+                    }
+                }
+            ]
+        }
+    });
+    for (const change of docs){
+        const slug = change.collectionSlug;
+        const docID = change.doc?.value ?? change.doc;
+        if (!slug || docID === undefined || docID === null) {
+            continue;
+        }
+        const existing = state.manifest.get(slug);
+        if (existing) {
+            existing.push(docID);
+        } else {
+            state.manifest.set(slug, [
+                docID
+            ]);
+        }
+        if (change.operation === 'delete') {
+            const deleted = state.deleted.get(slug);
+            if (deleted) {
+                deleted.push(docID);
+            } else {
+                state.deleted.set(slug, [
+                    docID
+                ]);
+            }
+        }
+        if (change.operation === 'create' || change.operation === 'delete' || change.operation === 'update') {
+            state.operations.set(`${slug}:${String(docID)}`, change.operation);
+        }
+    }
+    return state.manifest;
+};
+/**
+ * Canonical IDs the active branch has tombstoned, keyed by collection slug.
+ *
+ * Version and collection queries both exclude these documents by canonical
+ * identity from the authoritative change manifest.
+ *
+ * Loaded from the same manifest query, so asking for this costs nothing beyond
+ * the read the request already made.
+ */ export const loadBranchDeletions = async (req)=>{
+    await loadBranchManifest(req);
+    const state = req?.context?.[stateKey];
+    return state?.deleted ?? new Map();
+};
+export const loadBranchOperation = async ({ collectionSlug, docID, req })=>{
+    const branch = resolveBranch(req);
+    const state = req.context?.[stateKey];
+    const operationKey = `${collectionSlug}:${String(docID)}`;
+    const cachedOperation = state?.operations.get(operationKey);
+    if (cachedOperation || branch === MAIN_BRANCH) {
+        return cachedOperation;
+    }
+    const change = await req.payload.db.findOne({
+        branch: false,
+        collection: 'payload-branch-changes',
+        req,
+        where: {
+            and: [
+                {
+                    branch: {
+                        equals: branch
+                    }
+                },
+                {
+                    collectionSlug: {
+                        equals: collectionSlug
+                    }
+                },
+                {
+                    documentID: {
+                        equals: String(docID)
+                    }
+                }
+            ]
+        }
+    });
+    const operation = change?.operation;
+    if (operation === 'create' || operation === 'delete' || operation === 'update') {
+        state?.operations.set(operationKey, operation);
+        return operation;
+    }
+    return undefined;
+};
+/**
+ * A copy of the request that can resolve a branch of its own.
+ *
+ * The resolved branch and its manifest are memoized on `req.context`, so one
+ * request reads one branch — an explicit `branch` argument passed alongside a
+ * request that has already resolved a different one is otherwise accepted and
+ * ignored. Reading the same document on two branches, as a diff does, therefore
+ * needs a request per branch.
+ *
+ * The copy carries the transaction, the user and the locale, so it is the same
+ * request in every respect but the branch. Its dataloader is its own, because
+ * the dataloader's cache key does not include the branch and would otherwise
+ * serve one branch's document to the other.
+ */ export const isolateBranchState = (req)=>{
+    const isolated = {
+        ...req,
+        context: {
+            ...req.context
+        },
+        headers: req.headers
+    };
+    resetBranchState(isolated);
+    isolated.payloadDataLoader = getDataLoader(isolated);
+    return isolated;
+};
+/**
+ * The branch's own row, read once per request.
+ *
+ * Three separate checks want it — whether the branch is closed, whether a merged branch
+ * should reopen, and whether the caller may see it at all — and each used to read it
+ * again. This is the trusted read (`overrideAccess: true`), so it deliberately does *not*
+ * serve the access-checked visibility gate: a row fetched without access control must
+ * never stand in for one fetched with it.
+ */ export const loadBranchRow = async ({ branch, req })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (state && state.branch === branch && state.branchRow !== undefined) {
+        return state.branchRow;
+    }
+    const { docs } = await req.payload.find({
+        collection: branchesCollectionSlug,
+        depth: 0,
+        limit: 1,
+        overrideAccess: true,
+        pagination: false,
+        req,
+        select: {
+            slug: true,
+            status: true
+        },
+        where: {
+            slug: {
+                equals: branch
+            }
+        }
+    });
+    const row = docs[0] ?? null;
+    if (state && state.branch === branch) {
+        state.branchRow = row;
+    }
+    return row;
+};
+/** Replaces the memoized branch row after something changed it. */ export const setBranchRow = ({ branch, req, row })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    if (state && state.branch === branch) {
+        state.branchRow = row;
+    }
+};
+/**
+ * Records a newly forked document in the memoized manifest.
+ *
+ * Cheaper than dropping the manifest and reloading it, which is what a fork used to do:
+ * the manifest needs to know the branch now shadows this document, and that is one ID —
+ * not a reason to re-read every change row on the branch. Reads later in the same request
+ * then exclude main's copy without a second query.
+ */ export const addToBranchManifest = ({ collectionSlug, docID, operation, req })=>{
+    const context = req.context;
+    const state = context?.[stateKey];
+    // Not loaded yet is the common case on a write-only request: the next read loads it
+    // fresh, and it will include this document.
+    if (!state?.manifestLoaded) {
+        return;
+    }
+    const existing = state.manifest.get(collectionSlug);
+    if (existing) {
+        if (!existing.some((id)=>String(id) === String(docID))) {
+            existing.push(docID);
+        }
+    } else {
+        state.manifest.set(collectionSlug, [
+            docID
+        ]);
+    }
+    state.operations.set(`${collectionSlug}:${String(docID)}`, operation);
+};
+/** The shadow row ID this request has already resolved for a canonical ID, if any. */ export const peekBranchRowID = ({ collectionSlug, docID, req })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.rowIDs.get(`${collectionSlug}:${docID}`);
+};
+/** Remembers a canonical ID's shadow row, so the next write does not look it up again. */ export const rememberBranchRowID = ({ collectionSlug, docID, req, rowID })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    state?.rowIDs.set(`${collectionSlug}:${docID}`, rowID);
+};
+/**
+ * The same request with branch resolution switched off.
+ *
+ * For the engines that write to `main` on a branch's behalf — merge and discard. They
+ * address shadow rows by their real primary keys and write production, so every write
+ * they make must bypass branch resolution. Passing `branch: false` per call is one
+ * omission away from a silent no-op: the merge-create promotion goes through
+ * `updateByIDOperation`, which takes no `branch` argument at all and reads the request,
+ * so a merge triggered over HTTP with `?branch=` resolved that write against the branch
+ * it was merging.
+ *
+ * Isolated rather than mutated, because the caller's request keeps its own branch — the
+ * HTTP handler still has a response to render on it.
+ */ export const withoutBranch = (req)=>{
+    const isolated = isolateBranchState(req);
+    // The same sentinel `createPayloadRequest({ branch: false })` sets, rather than a `branch`
+    // of our own: `req.branch` alone is not enough, because resolution falls back to the
+    // query string behind it.
+    isolated.branch = undefined;
+    isolated.context._branchBypass = true;
+    return isolated;
+};
+/**
+ * The branch this request has already resolved, or `undefined` if it has not.
+ *
+ * Deliberately does not resolve: callers use this to find out whether they are about to
+ * *change* the branch, and resolving here would create the state they are checking for.
+ */ export const peekResolvedBranch = (req)=>{
+    const context = req?.context;
+    return context?.[stateKey]?.branch;
+};
+/** Clears memoized branch state, for tests and for cross-branch reads. */ export const resetBranchState = (req)=>{
+    const context = req.context;
+    if (context) {
+        delete context[stateKey];
+    }
+};
+/** Clears memoized branch and document state after a write changes what this request can read. */ export const refreshBranchState = (req)=>{
+    resetBranchState(req);
+    refreshRequestDataLoader(req);
+};
+/** Clears documents cached while populating relationships on this request. */ export const refreshRequestDataLoader = (req)=>{
+    req.payloadDataLoader = getDataLoader(req);
+};
+/**
+ * The manifest already loaded for this request, without loading it.
+ *
+ * For synchronous callers such as join query builders, which run after the
+ * top-level read has resolved the branch and populated the manifest.
+ */ export const peekBranchManifest = (req)=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.manifest ?? new Map();
+};
+/**
+ * The branch deletions already loaded for this request, without loading them.
+ *
+ * Version join builders are synchronous. They run after the top-level branch query has loaded the
+ * manifest, which also records deletions, so they can reuse that state without another query.
+ */ export const peekBranchDeletions = (req)=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.deleted ?? new Map();
+};
+/** The authoritative operation for one collection document in the loaded change manifest. */ export const peekBranchOperation = ({ collectionSlug, docID, req })=>{
+    const context = req?.context;
+    const state = context?.[stateKey];
+    return state?.operations.get(`${collectionSlug}:${String(docID)}`);
+};
+
+//# sourceMappingURL=resolveBranch.js.map

package/dist/branching/resolveBranch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/branching/resolveBranch.ts"],"sourcesContent":["import type { PayloadRequest } from '../types/index.js'\nimport type { BranchOperation, SanitizedBranchingConfig } from './types.js'\n\nimport { getDataLoader } from '../collections/dataloader.js'\nimport { branchesCollectionSlug, MAIN_BRANCH } from './types.js'\n\n/**\n * Per-request branch state, memoized on `req` so a page rendering many\n * collections resolves the branch once and loads the change manifest once.\n */\ntype BranchState = {\n  branch: string\n  /** The branch's own row, read once per request rather than per check. */\n  branchRow?: null | Record<string, unknown>\n  /** Canonical IDs tombstoned on this branch, keyed by collection slug. */\n  deleted: Map<string, (number | string)[]>\n  /** Canonical shadowed document IDs, keyed by collection slug. */\n  manifest: Map<string, (number | string)[]>\n  manifestLoaded: boolean\n  /** Change-record operation keyed by collection and canonical document ID. */\n  operations: Map<string, BranchOperation>\n  /** Canonical ID → shadow row primary key, for the writes that resolved it. */\n  rowIDs: Map<string, number | string>\n}\n\nconst stateKey = '_branchState'\n\nconst getBranchingConfig = (req: PayloadRequest): SanitizedBranchingConfig | undefined =>\n  req?.payload?.config?.branching\n\n/**\n * Resolves the active branch for a request.\n *\n * The branch is an argument, exactly like `locale` and `depth`: it is whatever\n * the caller passed, and `main` when they passed nothing. Nothing is read from\n * storage here — no preference lookup, no cookie — so an unbranched request\n * costs nothing beyond this function.\n *\n * Where the admin UI's persisted selection turns into that argument is the\n * admin UI's business (`initAdminContext`), the same division `locale` already uses.\n *\n * Precedence, highest first:\n *   1. explicit Local API argument (`req.branch`, set by the caller)\n *   2. `branch` query param\n *   3. `main`\n */\nexport const resolveBranch = (req: PayloadRequest): string => {\n  const branching = getBranchingConfig(req)\n\n  if (!branching?.enabled) {\n    return MAIN_BRANCH\n  }\n\n  const context = req.context as Record<string, unknown> | undefined\n  const existing = context?.[stateKey] as BranchState | undefined\n\n  if (existing) {\n    return existing.branch\n  }\n\n  // The bypass sentinel `createPayloadRequest` sets for `branch: false`. Honoured here and not\n  // only at the database layer, because a request told to ignore branching must not\n  // report a branch to anything that asks — a `branch: false` request built from an HTTP\n  // request still carries `?branch=` in its query, and falling through to it made the\n  // merge engine resolve against the very branch it was merging.\n  if (context?._branchBypass) {\n    req.branch = MAIN_BRANCH\n\n    return MAIN_BRANCH\n  }\n\n  const branch = resolveBranchFromRequest(req) ?? MAIN_BRANCH\n\n  if (context) {\n    context[stateKey] = {\n      branch,\n      deleted: new Map(),\n      manifest: new Map(),\n      manifestLoaded: false,\n      operations: new Map(),\n      rowIDs: new Map(),\n    } satisfies BranchState\n  }\n\n  req.branch = branch\n\n  return branch\n}\n\n/**\n * The branch the caller asked for, whether through the Local API option or the\n * `branch` query param — the same two ways `locale` is supplied.\n */\nconst resolveBranchFromRequest = (req: PayloadRequest): string | undefined => {\n  if (typeof req.branch === 'string' && req.branch) {\n    return req.branch\n  }\n\n  if (typeof req.query?.branch === 'string' && req.query.branch) {\n    return req.query.branch\n  }\n\n  return undefined\n}\n\n/**\n * Loads every change the active branch has made, in one query, and groups it\n * by collection in memory.\n *\n * One query per request rather than per collection: a request touching a dozen\n * collections still issues a single manifest read. Bounded by branch size, not\n * table size.\n */\nexport const loadBranchManifest = async (\n  req: PayloadRequest,\n): Promise<Map<string, (number | string)[]>> => {\n  const branch = resolveBranch(req)\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (!state || branch === MAIN_BRANCH) {\n    return new Map()\n  }\n\n  if (state.manifestLoaded) {\n    return state.manifest\n  }\n\n  // Marked loaded up front so the manifest read below — which itself goes\n  // through the adapter — cannot recurse back into loading the manifest.\n  state.manifestLoaded = true\n\n  const { docs } = await req.payload.db.find({\n    collection: 'payload-branch-changes',\n    limit: 0,\n    pagination: false,\n    req,\n    where: {\n      and: [{ branch: { equals: branch } }, { entityType: { equals: 'collection' } }],\n    },\n  })\n\n  for (const change of docs as Record<string, any>[]) {\n    const slug = change.collectionSlug as string\n    const docID = change.doc?.value ?? change.doc\n\n    if (!slug || docID === undefined || docID === null) {\n      continue\n    }\n\n    const existing = state.manifest.get(slug)\n\n    if (existing) {\n      existing.push(docID)\n    } else {\n      state.manifest.set(slug, [docID])\n    }\n\n    if (change.operation === 'delete') {\n      const deleted = state.deleted.get(slug)\n\n      if (deleted) {\n        deleted.push(docID)\n      } else {\n        state.deleted.set(slug, [docID])\n      }\n    }\n\n    if (\n      change.operation === 'create' ||\n      change.operation === 'delete' ||\n      change.operation === 'update'\n    ) {\n      state.operations.set(`${slug}:${String(docID)}`, change.operation)\n    }\n  }\n\n  return state.manifest\n}\n\n/**\n * Canonical IDs the active branch has tombstoned, keyed by collection slug.\n *\n * Version and collection queries both exclude these documents by canonical\n * identity from the authoritative change manifest.\n *\n * Loaded from the same manifest query, so asking for this costs nothing beyond\n * the read the request already made.\n */\nexport const loadBranchDeletions = async (\n  req: PayloadRequest,\n): Promise<Map<string, (number | string)[]>> => {\n  await loadBranchManifest(req)\n\n  const state = (req?.context as Record<string, unknown> | undefined)?.[stateKey] as\n    | BranchState\n    | undefined\n\n  return state?.deleted ?? new Map()\n}\n\nexport const loadBranchOperation = async ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req: PayloadRequest\n}): Promise<BranchOperation | undefined> => {\n  const branch = resolveBranch(req)\n  const state = (req.context as Record<string, unknown> | undefined)?.[stateKey] as\n    | BranchState\n    | undefined\n  const operationKey = `${collectionSlug}:${String(docID)}`\n  const cachedOperation = state?.operations.get(operationKey)\n\n  if (cachedOperation || branch === MAIN_BRANCH) {\n    return cachedOperation\n  }\n\n  const change = await req.payload.db.findOne({\n    branch: false,\n    collection: 'payload-branch-changes',\n    req,\n    where: {\n      and: [\n        { branch: { equals: branch } },\n        { collectionSlug: { equals: collectionSlug } },\n        { documentID: { equals: String(docID) } },\n      ],\n    },\n  })\n  const operation = (change as { operation?: unknown } | null)?.operation\n\n  if (operation === 'create' || operation === 'delete' || operation === 'update') {\n    state?.operations.set(operationKey, operation)\n\n    return operation\n  }\n\n  return undefined\n}\n\n/**\n * A copy of the request that can resolve a branch of its own.\n *\n * The resolved branch and its manifest are memoized on `req.context`, so one\n * request reads one branch — an explicit `branch` argument passed alongside a\n * request that has already resolved a different one is otherwise accepted and\n * ignored. Reading the same document on two branches, as a diff does, therefore\n * needs a request per branch.\n *\n * The copy carries the transaction, the user and the locale, so it is the same\n * request in every respect but the branch. Its dataloader is its own, because\n * the dataloader's cache key does not include the branch and would otherwise\n * serve one branch's document to the other.\n */\nexport const isolateBranchState = (req: PayloadRequest): PayloadRequest => {\n  const isolated = { ...req, context: { ...req.context }, headers: req.headers } as PayloadRequest\n\n  resetBranchState(isolated)\n  isolated.payloadDataLoader = getDataLoader(isolated)\n\n  return isolated\n}\n\n/**\n * The branch's own row, read once per request.\n *\n * Three separate checks want it — whether the branch is closed, whether a merged branch\n * should reopen, and whether the caller may see it at all — and each used to read it\n * again. This is the trusted read (`overrideAccess: true`), so it deliberately does *not*\n * serve the access-checked visibility gate: a row fetched without access control must\n * never stand in for one fetched with it.\n */\nexport const loadBranchRow = async ({\n  branch,\n  req,\n}: {\n  branch: string\n  req: PayloadRequest\n}): Promise<null | Record<string, unknown>> => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (state && state.branch === branch && state.branchRow !== undefined) {\n    return state.branchRow\n  }\n\n  const { docs } = await req.payload.find({\n    collection: branchesCollectionSlug,\n    depth: 0,\n    limit: 1,\n    overrideAccess: true,\n    pagination: false,\n    req,\n    select: { slug: true, status: true },\n    where: { slug: { equals: branch } },\n  })\n\n  const row = (docs[0] as Record<string, unknown> | undefined) ?? null\n\n  if (state && state.branch === branch) {\n    state.branchRow = row\n  }\n\n  return row\n}\n\n/** Replaces the memoized branch row after something changed it. */\nexport const setBranchRow = ({\n  branch,\n  req,\n  row,\n}: {\n  branch: string\n  req: PayloadRequest\n  row: null | Record<string, unknown>\n}): void => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  if (state && state.branch === branch) {\n    state.branchRow = row\n  }\n}\n\n/**\n * Records a newly forked document in the memoized manifest.\n *\n * Cheaper than dropping the manifest and reloading it, which is what a fork used to do:\n * the manifest needs to know the branch now shadows this document, and that is one ID —\n * not a reason to re-read every change row on the branch. Reads later in the same request\n * then exclude main's copy without a second query.\n */\nexport const addToBranchManifest = ({\n  collectionSlug,\n  docID,\n  operation,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  operation: BranchOperation\n  req: PayloadRequest\n}): void => {\n  const context = req.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  // Not loaded yet is the common case on a write-only request: the next read loads it\n  // fresh, and it will include this document.\n  if (!state?.manifestLoaded) {\n    return\n  }\n\n  const existing = state.manifest.get(collectionSlug)\n\n  if (existing) {\n    if (!existing.some((id) => String(id) === String(docID))) {\n      existing.push(docID)\n    }\n  } else {\n    state.manifest.set(collectionSlug, [docID])\n  }\n\n  state.operations.set(`${collectionSlug}:${String(docID)}`, operation)\n}\n\n/** The shadow row ID this request has already resolved for a canonical ID, if any. */\nexport const peekBranchRowID = ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n}): number | string | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.rowIDs.get(`${collectionSlug}:${docID}`)\n}\n\n/** Remembers a canonical ID's shadow row, so the next write does not look it up again. */\nexport const rememberBranchRowID = ({\n  collectionSlug,\n  docID,\n  req,\n  rowID,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n  rowID: number | string\n}): void => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  state?.rowIDs.set(`${collectionSlug}:${docID}`, rowID)\n}\n\n/**\n * The same request with branch resolution switched off.\n *\n * For the engines that write to `main` on a branch's behalf — merge and discard. They\n * address shadow rows by their real primary keys and write production, so every write\n * they make must bypass branch resolution. Passing `branch: false` per call is one\n * omission away from a silent no-op: the merge-create promotion goes through\n * `updateByIDOperation`, which takes no `branch` argument at all and reads the request,\n * so a merge triggered over HTTP with `?branch=` resolved that write against the branch\n * it was merging.\n *\n * Isolated rather than mutated, because the caller's request keeps its own branch — the\n * HTTP handler still has a response to render on it.\n */\nexport const withoutBranch = (req: PayloadRequest): PayloadRequest => {\n  const isolated = isolateBranchState(req)\n\n  // The same sentinel `createPayloadRequest({ branch: false })` sets, rather than a `branch`\n  // of our own: `req.branch` alone is not enough, because resolution falls back to the\n  // query string behind it.\n  isolated.branch = undefined\n  ;(isolated.context as Record<string, unknown>)._branchBypass = true\n\n  return isolated\n}\n\n/**\n * The branch this request has already resolved, or `undefined` if it has not.\n *\n * Deliberately does not resolve: callers use this to find out whether they are about to\n * *change* the branch, and resolving here would create the state they are checking for.\n */\nexport const peekResolvedBranch = (req?: Partial<PayloadRequest>): string | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n\n  return (context?.[stateKey] as BranchState | undefined)?.branch\n}\n\n/** Clears memoized branch state, for tests and for cross-branch reads. */\nexport const resetBranchState = (req: PayloadRequest): void => {\n  const context = req.context as Record<string, unknown> | undefined\n\n  if (context) {\n    delete context[stateKey]\n  }\n}\n\n/** Clears memoized branch and document state after a write changes what this request can read. */\nexport const refreshBranchState = (req: PayloadRequest): void => {\n  resetBranchState(req)\n  refreshRequestDataLoader(req)\n}\n\n/** Clears documents cached while populating relationships on this request. */\nexport const refreshRequestDataLoader = (req: PayloadRequest): void => {\n  req.payloadDataLoader = getDataLoader(req)\n}\n\n/**\n * The manifest already loaded for this request, without loading it.\n *\n * For synchronous callers such as join query builders, which run after the\n * top-level read has resolved the branch and populated the manifest.\n */\nexport const peekBranchManifest = (req: PayloadRequest): Map<string, (number | string)[]> => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.manifest ?? new Map()\n}\n\n/**\n * The branch deletions already loaded for this request, without loading them.\n *\n * Version join builders are synchronous. They run after the top-level branch query has loaded the\n * manifest, which also records deletions, so they can reuse that state without another query.\n */\nexport const peekBranchDeletions = (req: PayloadRequest): Map<string, (number | string)[]> => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.deleted ?? new Map()\n}\n\n/** The authoritative operation for one collection document in the loaded change manifest. */\nexport const peekBranchOperation = ({\n  collectionSlug,\n  docID,\n  req,\n}: {\n  collectionSlug: string\n  docID: number | string\n  req?: Partial<PayloadRequest>\n}): BranchOperation | undefined => {\n  const context = req?.context as Record<string, unknown> | undefined\n  const state = context?.[stateKey] as BranchState | undefined\n\n  return state?.operations.get(`${collectionSlug}:${String(docID)}`)\n}\n"],"names":["getDataLoader","branchesCollectionSlug","MAIN_BRANCH","stateKey","getBranchingConfig","req","payload","config","branching","resolveBranch","enabled","context","existing","branch","_branchBypass","resolveBranchFromRequest","deleted","Map","manifest","manifestLoaded","operations","rowIDs","query","undefined","loadBranchManifest","state","docs","db","find","collection","limit","pagination","where","and","equals","entityType","change","slug","collectionSlug","docID","doc","value","get","push","set","operation","String","loadBranchDeletions","loadBranchOperation","operationKey","cachedOperation","findOne","documentID","isolateBranchState","isolated","headers","resetBranchState","payloadDataLoader","loadBranchRow","branchRow","depth","overrideAccess","select","status","row","setBranchRow","addToBranchManifest","some","id","peekBranchRowID","rememberBranchRowID","rowID","withoutBranch","peekResolvedBranch","refreshBranchState","refreshRequestDataLoader","peekBranchManifest","peekBranchDeletions","peekBranchOperation"],"mappings":"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"}

package/dist/branching/resolveBranchActionAccess.d.ts

@@ -0,0 +1,8 @@
+import type { Access } from '../config/types.js';
+import type { SanitizedBranchingConfig } from './types.js';
+export type BranchAction = 'discardBranch' | 'mergeBranch';
+export declare const resolveBranchActionAccess: ({ action, branching, }: {
+    action: BranchAction;
+    branching: SanitizedBranchingConfig;
+}) => Access;
+//# sourceMappingURL=resolveBranchActionAccess.d.ts.map

package/dist/branching/resolveBranchActionAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveBranchActionAccess.d.ts","sourceRoot":"","sources":["../../src/branching/resolveBranchActionAccess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI1D,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,aAAa,CAAA;AAE1D,eAAO,MAAM,yBAAyB,2BAGnC;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,wBAAwB,CAAA;CACpC,KAAG,MAMH,CAAA"}

package/dist/branching/resolveBranchActionAccess.js

@@ -0,0 +1,9 @@
+import { defaultAccess } from '../auth/defaultAccess.js';
+export const resolveBranchActionAccess = ({ action, branching })=>{
+    if (action === 'mergeBranch') {
+        return branching.access?.mergeBranch ?? branching.access?.readBranch ?? defaultAccess;
+    }
+    return branching.access?.discardBranch ?? branching.access?.deleteBranch ?? defaultAccess;
+};
+
+//# sourceMappingURL=resolveBranchActionAccess.js.map

package/dist/branching/resolveBranchActionAccess.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/branching/resolveBranchActionAccess.ts"],"sourcesContent":["import type { Access } from '../config/types.js'\nimport type { SanitizedBranchingConfig } from './types.js'\n\nimport { defaultAccess } from '../auth/defaultAccess.js'\n\nexport type BranchAction = 'discardBranch' | 'mergeBranch'\n\nexport const resolveBranchActionAccess = ({\n  action,\n  branching,\n}: {\n  action: BranchAction\n  branching: SanitizedBranchingConfig\n}): Access => {\n  if (action === 'mergeBranch') {\n    return branching.access?.mergeBranch ?? branching.access?.readBranch ?? defaultAccess\n  }\n\n  return branching.access?.discardBranch ?? branching.access?.deleteBranch ?? defaultAccess\n}\n"],"names":["defaultAccess","resolveBranchActionAccess","action","branching","access","mergeBranch","readBranch","discardBranch","deleteBranch"],"mappings":"AAGA,SAASA,aAAa,QAAQ,2BAA0B;AAIxD,OAAO,MAAMC,4BAA4B,CAAC,EACxCC,MAAM,EACNC,SAAS,EAIV;IACC,IAAID,WAAW,eAAe;QAC5B,OAAOC,UAAUC,MAAM,EAAEC,eAAeF,UAAUC,MAAM,EAAEE,cAAcN;IAC1E;IAEA,OAAOG,UAAUC,MAAM,EAAEG,iBAAiBJ,UAAUC,MAAM,EAAEI,gBAAgBR;AAC9E,EAAC"}

package/dist/branching/resolveBranchQuery.d.ts

@@ -0,0 +1,48 @@
+import type { PayloadRequest, Where } from '../types/index.js';
+type Args = {
+    /**
+     * Explicit override. `false` bypasses branching entirely — used by the merge
+     * engine, which must reach shadow rows by their real primary key, and by
+     * cross-branch reads such as diff views.
+     */
+    branch?: false | string;
+    collectionSlug?: string;
+    globalSlug?: string;
+    req?: Partial<PayloadRequest>;
+    where: undefined | Where;
+};
+export type BranchReadState = {
+    branch: string;
+    useBranching: boolean;
+};
+export declare const resolveBranchReadState: ({ branch: branchOverride, collectionSlug, globalSlug, req, }: Omit<Args, 'where'>) => BranchReadState;
+/**
+ * The single entry point adapters call to make a read branch-aware.
+ *
+ * Lives in `payload` rather than in each adapter so that Mongo and Drizzle
+ * cannot drift apart on branch semantics — adapters supply only the query
+ * translation they already do.
+ *
+ * Returns `where` untouched when branching is off, when the entity is not
+ * branch-enabled, or when the caller opted out, so a branching-disabled config
+ * takes the same code path it does today.
+ */
+export declare const resolveBranchQuery: ({ branch: branchOverride, collectionSlug, globalSlug, req, where, }: Args) => Promise<undefined | Where>;
+/**
+ * Synchronous branch predicate, for query builders that are not async.
+ *
+ * Reads the change manifest that `resolveBranchQuery` has already loaded and
+ * memoized on the request earlier in the same read. Returns `null` when
+ * branching is inactive for the entity, so callers can skip cleanly.
+ *
+ * Join subqueries need this: they are assembled inside synchronous query
+ * builders, but must carry the same branch predicate as the top-level read or
+ * a branch would see main's related documents.
+ */
+export declare const getBranchPredicateSync: ({ branch: branchOverride, collectionSlug, req, }: {
+    branch?: false | string;
+    collectionSlug: string;
+    req?: Partial<PayloadRequest>;
+}) => null | Where;
+export {};
+//# sourceMappingURL=resolveBranchQuery.d.ts.map

package/dist/branching/resolveBranchQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveBranchQuery.d.ts","sourceRoot":"","sources":["../../src/branching/resolveBranchQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAa9D,KAAK,IAAI,GAAG;IACV;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,GAAG,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IAC7B,KAAK,EAAE,SAAS,GAAG,KAAK,CAAA;CACzB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,OAAO,CAAA;CACtB,CAAA;AAED,eAAO,MAAM,sBAAsB,iEAKhC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,KAAG,eAkCxB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,wEAM5B,IAAI,KAAG,OAAO,CAAC,SAAS,GAAG,KAAK,CA+DlC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,qDAIhC;IACD,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;CAC9B,KAAG,IAAI,GAAG,KA2BV,CAAA"}

package/dist/branching/resolveBranchQuery.js

@@ -0,0 +1,115 @@
+import { appendBranchFilter } from './appendBranchFilter.js';
+import { rewriteBranchIDs } from './branchIDs.js';
+import { loadBranchDeletions, loadBranchManifest, peekBranchDeletions, peekBranchManifest, resolveBranch } from './resolveBranch.js';
+import { MAIN_BRANCH } from './types.js';
+export const resolveBranchReadState = ({ branch: branchOverride, collectionSlug, globalSlug, req })=>{
+    const branching = req?.payload?.config?.branching;
+    const isBranchable = collectionSlug ? Boolean(branching?.branchableCollections.has(collectionSlug)) : globalSlug ? Boolean(branching?.branchableGlobals.has(globalSlug)) : false;
+    const isRequestBypassed = Boolean(req?.context?._branchBypass);
+    const isBypassed = branchOverride === false || isRequestBypassed;
+    if (isRequestBypassed && req?.payload) {
+        resolveBranch(req);
+    }
+    if (!branching?.enabled || !isBranchable || isBypassed) {
+        return {
+            branch: typeof branchOverride === 'string' ? branchOverride : MAIN_BRANCH,
+            useBranching: false
+        };
+    }
+    const branch = typeof branchOverride === 'string' ? branchOverride : req?.payload ? resolveBranch(req) : MAIN_BRANCH;
+    return {
+        branch,
+        useBranching: branch !== MAIN_BRANCH
+    };
+};
+/**
+ * The single entry point adapters call to make a read branch-aware.
+ *
+ * Lives in `payload` rather than in each adapter so that Mongo and Drizzle
+ * cannot drift apart on branch semantics — adapters supply only the query
+ * translation they already do.
+ *
+ * Returns `where` untouched when branching is off, when the entity is not
+ * branch-enabled, or when the caller opted out, so a branching-disabled config
+ * takes the same code path it does today.
+ */ export const resolveBranchQuery = async ({ branch: branchOverride, collectionSlug, globalSlug, req, where })=>{
+    if (branchOverride === false || !req?.payload) {
+        return where;
+    }
+    // Local API `branch: false` bypass, carried on context so it survives the
+    // hop from operation options into the adapter.
+    if (req.context?._branchBypass) {
+        return where;
+    }
+    const branching = req.payload.config?.branching;
+    if (!branching?.enabled) {
+        return where;
+    }
+    const isBranchable = collectionSlug ? branching.branchableCollections.has(collectionSlug) : globalSlug ? branching.branchableGlobals.has(globalSlug) : false;
+    if (!isBranchable) {
+        return where;
+    }
+    const branch = branchOverride ?? resolveBranch(req);
+    if (branch === MAIN_BRANCH) {
+        return appendBranchFilter({
+            branch,
+            deletedIDs: [],
+            enabled: true,
+            shadowedIDs: [],
+            where: where ?? {}
+        });
+    }
+    const [manifest, deletions] = await Promise.all([
+        loadBranchManifest(req),
+        loadBranchDeletions(req)
+    ]);
+    const shadowedIDs = collectionSlug ? manifest.get(collectionSlug) ?? [] : [];
+    const deletedIDs = collectionSlug ? deletions.get(collectionSlug) ?? [] : [];
+    // A shadow row's primary key is not the document's canonical ID, so any `id`
+    // constraint has to be redirected before the branch predicate is applied.
+    const rewritten = rewriteBranchIDs(where ?? {});
+    if (shadowedIDs.length > branching.maxShadowedIDs) {
+        req.payload.logger.warn(`Branch "${branch}" has shadowed ${shadowedIDs.length} documents in "${collectionSlug}", above maxShadowedIDs (${branching.maxShadowedIDs}). Read performance will degrade.`);
+    }
+    return appendBranchFilter({
+        branch,
+        deletedIDs,
+        enabled: true,
+        shadowedIDs,
+        where: rewritten ?? {}
+    });
+};
+/**
+ * Synchronous branch predicate, for query builders that are not async.
+ *
+ * Reads the change manifest that `resolveBranchQuery` has already loaded and
+ * memoized on the request earlier in the same read. Returns `null` when
+ * branching is inactive for the entity, so callers can skip cleanly.
+ *
+ * Join subqueries need this: they are assembled inside synchronous query
+ * builders, but must carry the same branch predicate as the top-level read or
+ * a branch would see main's related documents.
+ */ export const getBranchPredicateSync = ({ branch: branchOverride, collectionSlug, req })=>{
+    if (branchOverride === false || !req?.payload) {
+        return null;
+    }
+    if (req.context?._branchBypass) {
+        return null;
+    }
+    const branching = req.payload.config?.branching;
+    if (!branching?.enabled || !branching.branchableCollections.has(collectionSlug)) {
+        return null;
+    }
+    const branch = branchOverride ?? resolveBranch(req);
+    const shadowedIDs = branch === MAIN_BRANCH ? [] : peekBranchManifest(req).get(collectionSlug) ?? [];
+    const deletedIDs = branch === MAIN_BRANCH ? [] : peekBranchDeletions(req).get(collectionSlug) ?? [];
+    return appendBranchFilter({
+        branch,
+        deletedIDs,
+        enabled: true,
+        shadowedIDs,
+        where: {}
+    });
+};
+
+//# sourceMappingURL=resolveBranchQuery.js.map

package/dist/branching/resolveBranchQuery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/branching/resolveBranchQuery.ts"],"sourcesContent":["import type { PayloadRequest, Where } from '../types/index.js'\n\nimport { appendBranchFilter } from './appendBranchFilter.js'\nimport { rewriteBranchIDs } from './branchIDs.js'\nimport {\n  loadBranchDeletions,\n  loadBranchManifest,\n  peekBranchDeletions,\n  peekBranchManifest,\n  resolveBranch,\n} from './resolveBranch.js'\nimport { MAIN_BRANCH } from './types.js'\n\ntype Args = {\n  /**\n   * Explicit override. `false` bypasses branching entirely — used by the merge\n   * engine, which must reach shadow rows by their real primary key, and by\n   * cross-branch reads such as diff views.\n   */\n  branch?: false | string\n  collectionSlug?: string\n  globalSlug?: string\n  req?: Partial<PayloadRequest>\n  where: undefined | Where\n}\n\nexport type BranchReadState = {\n  branch: string\n  useBranching: boolean\n}\n\nexport const resolveBranchReadState = ({\n  branch: branchOverride,\n  collectionSlug,\n  globalSlug,\n  req,\n}: Omit<Args, 'where'>): BranchReadState => {\n  const branching = req?.payload?.config?.branching\n  const isBranchable = collectionSlug\n    ? Boolean(branching?.branchableCollections.has(collectionSlug))\n    : globalSlug\n      ? Boolean(branching?.branchableGlobals.has(globalSlug))\n      : false\n  const isRequestBypassed = Boolean(\n    (req?.context as Record<string, unknown> | undefined)?._branchBypass,\n  )\n  const isBypassed = branchOverride === false || isRequestBypassed\n\n  if (isRequestBypassed && req?.payload) {\n    resolveBranch(req as PayloadRequest)\n  }\n\n  if (!branching?.enabled || !isBranchable || isBypassed) {\n    return {\n      branch: typeof branchOverride === 'string' ? branchOverride : MAIN_BRANCH,\n      useBranching: false,\n    }\n  }\n\n  const branch =\n    typeof branchOverride === 'string'\n      ? branchOverride\n      : req?.payload\n        ? resolveBranch(req as PayloadRequest)\n        : MAIN_BRANCH\n\n  return {\n    branch,\n    useBranching: branch !== MAIN_BRANCH,\n  }\n}\n\n/**\n * The single entry point adapters call to make a read branch-aware.\n *\n * Lives in `payload` rather than in each adapter so that Mongo and Drizzle\n * cannot drift apart on branch semantics — adapters supply only the query\n * translation they already do.\n *\n * Returns `where` untouched when branching is off, when the entity is not\n * branch-enabled, or when the caller opted out, so a branching-disabled config\n * takes the same code path it does today.\n */\nexport const resolveBranchQuery = async ({\n  branch: branchOverride,\n  collectionSlug,\n  globalSlug,\n  req,\n  where,\n}: Args): Promise<undefined | Where> => {\n  if (branchOverride === false || !req?.payload) {\n    return where\n  }\n\n  // Local API `branch: false` bypass, carried on context so it survives the\n  // hop from operation options into the adapter.\n  if ((req.context as Record<string, unknown> | undefined)?._branchBypass) {\n    return where\n  }\n\n  const branching = req.payload.config?.branching\n\n  if (!branching?.enabled) {\n    return where\n  }\n\n  const isBranchable = collectionSlug\n    ? branching.branchableCollections.has(collectionSlug)\n    : globalSlug\n      ? branching.branchableGlobals.has(globalSlug)\n      : false\n\n  if (!isBranchable) {\n    return where\n  }\n\n  const branch = branchOverride ?? resolveBranch(req as PayloadRequest)\n\n  if (branch === MAIN_BRANCH) {\n    return appendBranchFilter({\n      branch,\n      deletedIDs: [],\n      enabled: true,\n      shadowedIDs: [],\n      where: where ?? {},\n    })\n  }\n\n  const [manifest, deletions] = await Promise.all([\n    loadBranchManifest(req as PayloadRequest),\n    loadBranchDeletions(req as PayloadRequest),\n  ])\n  const shadowedIDs = collectionSlug ? (manifest.get(collectionSlug) ?? []) : []\n  const deletedIDs = collectionSlug ? (deletions.get(collectionSlug) ?? []) : []\n\n  // A shadow row's primary key is not the document's canonical ID, so any `id`\n  // constraint has to be redirected before the branch predicate is applied.\n  const rewritten = rewriteBranchIDs(where ?? {})\n\n  if (shadowedIDs.length > branching.maxShadowedIDs) {\n    req.payload.logger.warn(\n      `Branch \"${branch}\" has shadowed ${shadowedIDs.length} documents in \"${collectionSlug}\", above maxShadowedIDs (${branching.maxShadowedIDs}). Read performance will degrade.`,\n    )\n  }\n\n  return appendBranchFilter({\n    branch,\n    deletedIDs,\n    enabled: true,\n    shadowedIDs,\n    where: rewritten ?? {},\n  })\n}\n\n/**\n * Synchronous branch predicate, for query builders that are not async.\n *\n * Reads the change manifest that `resolveBranchQuery` has already loaded and\n * memoized on the request earlier in the same read. Returns `null` when\n * branching is inactive for the entity, so callers can skip cleanly.\n *\n * Join subqueries need this: they are assembled inside synchronous query\n * builders, but must carry the same branch predicate as the top-level read or\n * a branch would see main's related documents.\n */\nexport const getBranchPredicateSync = ({\n  branch: branchOverride,\n  collectionSlug,\n  req,\n}: {\n  branch?: false | string\n  collectionSlug: string\n  req?: Partial<PayloadRequest>\n}): null | Where => {\n  if (branchOverride === false || !req?.payload) {\n    return null\n  }\n\n  if ((req.context as Record<string, unknown> | undefined)?._branchBypass) {\n    return null\n  }\n\n  const branching = req.payload.config?.branching\n\n  if (!branching?.enabled || !branching.branchableCollections.has(collectionSlug)) {\n    return null\n  }\n\n  const branch = branchOverride ?? resolveBranch(req as PayloadRequest)\n\n  const shadowedIDs =\n    branch === MAIN_BRANCH\n      ? []\n      : (peekBranchManifest(req as PayloadRequest).get(collectionSlug) ?? [])\n  const deletedIDs =\n    branch === MAIN_BRANCH\n      ? []\n      : (peekBranchDeletions(req as PayloadRequest).get(collectionSlug) ?? [])\n\n  return appendBranchFilter({ branch, deletedIDs, enabled: true, shadowedIDs, where: {} })\n}\n"],"names":["appendBranchFilter","rewriteBranchIDs","loadBranchDeletions","loadBranchManifest","peekBranchDeletions","peekBranchManifest","resolveBranch","MAIN_BRANCH","resolveBranchReadState","branch","branchOverride","collectionSlug","globalSlug","req","branching","payload","config","isBranchable","Boolean","branchableCollections","has","branchableGlobals","isRequestBypassed","context","_branchBypass","isBypassed","enabled","useBranching","resolveBranchQuery","where","deletedIDs","shadowedIDs","manifest","deletions","Promise","all","get","rewritten","length","maxShadowedIDs","logger","warn","getBranchPredicateSync"],"mappings":"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"}

package/dist/branching/resolveBranchRowID.d.ts

@@ -0,0 +1,22 @@
+import type { PayloadRequest } from '../types/index.js';
+type Args = {
+    branch?: false | string;
+    collectionSlug: string;
+    id: number | string;
+    req?: Partial<PayloadRequest>;
+};
+/**
+ * Translates a canonical document ID into the primary key of the row that the
+ * active branch should actually write to.
+ *
+ * A canonical ID is the only identity the API exposes: on a branch it addresses
+ * the branch's own copy, on main it addresses the main row. Reads resolve this
+ * through the `where`-tree rewrite; writes cannot, because they address a row
+ * by primary key directly — so they resolve it here instead.
+ *
+ * Returns the ID unchanged on main, when branching is off, or when the branch
+ * has no copy of the document.
+ */
+export declare const resolveBranchRowID: ({ id, branch: branchOverride, collectionSlug, req, }: Args) => Promise<number | string>;
+export {};
+//# sourceMappingURL=resolveBranchRowID.d.ts.map