import { Retry } from "@distilled.cloud/prisma";
import {
type GetProjectBranchesResponse,
type GetProjectsResponse,
deleteBranch,
getBranch,
getProjects,
getProjectBranches,
updateBranch,
createProjectBranch,
} from "@distilled.cloud/prisma/management";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { DEV_TIMESTAMP, attrOrString, devId, devProvider } from "./internal/DevStub.ts";
import type { ObservedBranch } from "./internal/Observed.ts";
import { PrismaPaginationError } from "./internal/Pagination.ts";
import {
concreteIdsChanged,
isInputObject,
isPrismaDevId,
resolveProjectId,
unresolvedProjectIdOf,
} from "./internal/Refs.ts";
import type { Project } from "./Project.ts";
import type { Providers } from "./Providers.ts";
export class BranchConflict extends Data.TaggedError("BranchConflict")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class BranchOperationFailed extends Data.TaggedError("BranchOperationFailed")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class BranchUnexpectedResponse extends Data.TaggedError("BranchUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface BranchProps {
/**
* Project ID or `project.projectId` output that owns this branch.
*/
project: string | Project;
/**
* Git-style branch name. If omitted, Alchemy generates a stable physical
* name.
*/
gitName?: string;
/**
* Promote this branch to be the project's default branch. Setting this to
* `false` does not demote a current default because the Management API only
* supports promotion; promoting another branch atomically demotes it.
* Promotion changes `isDefault`, not the branch's immutable `preview` role.
*
* @default false
*/
isDefault?: boolean;
}
export interface Branch extends Resource<
"Prisma.Branch",
BranchProps,
{
/**
* Prisma branch ID.
*/
branchId: string;
/**
* Git-style branch name.
*/
gitName: string;
/**
* Project ID that owns the branch.
*/
projectId: string;
/**
* Whether this branch is the project's default branch.
*/
isDefault: boolean;
/**
* Branch that was default before this preview branch was promoted. Alchemy
* restores it before deleting this resource so destroy remains reversible.
*/
previousDefaultBranchId?: string;
/**
* Branch role used by Prisma to resolve deploy-time environment variables.
*/
role: "production" | "preview";
/**
* ISO timestamp when the branch was created.
*/
createdAt: string;
/**
* ISO timestamp when the branch was last updated.
*/
updatedAt: string;
},
never,
Providers
> {}
/**
* A Prisma project branch for preview-class databases and compute resources.
*
* Standalone Branch resources always have the `preview` role. Promotion
* changes only the default branch; Alchemy restores the previous default
* before deleting a promoted branch.
*
* ### Creating a Branch
* **Example:** Preview branch
* ```typescript
* const branch = yield* Prisma.Branch("preview", {
* project: project.projectId,
* gitName: "feature/search", // optional — omitted, a stable name is generated
* });
*
* branch.role; // "preview"
* branch.isDefault; // false
* ```
*
* ### Promoting a Branch
* **Example:** Make a preview branch the default
* ```typescript
* const release = yield* Prisma.Branch("release", {
* project,
* gitName: "release/next",
* isDefault: true,
* });
*
* release.role; // still "preview"
* release.isDefault; // true
* ```
*
* @resource
* @product Project
*/
export const Branch = Resource<Branch>("Prisma.Branch");
const createGitName = (id: string, gitName: string | undefined) =>
gitName === undefined ? createPhysicalName({ id }) : Effect.succeed(gitName);
// Distilled emits the cursor-paginated list operations as plain ops, so
// callers walk `pagination` themselves (see `src/Neon/Project.ts`).
const listBranches = (projectId: string, query?: { readonly gitName?: string }) =>
Effect.gen(function* () {
const branches: GetProjectBranchesResponse["data"][number][] = [];
let cursor: string | undefined;
while (true) {
const page = yield* getProjectBranches({
projectId,
...(query?.gitName === undefined ? {} : { gitName: query.gitName }),
...(cursor === undefined ? {} : { cursor }),
});
branches.push(...page.data);
const nextCursor = page.pagination.nextCursor;
if (!page.pagination.hasMore) break;
if (nextCursor === null) {
return yield* new PrismaPaginationError({
message:
"Invalid Prisma Management API pagination response from getProjectBranches: hasMore was true without a non-empty nextCursor",
});
}
cursor = nextCursor;
}
return branches;
});
const listProjects = () =>
Effect.gen(function* () {
const projects: GetProjectsResponse["data"][number][] = [];
let cursor: string | undefined;
while (true) {
const page = yield* getProjects(cursor === undefined ? {} : { cursor });
projects.push(...page.data);
const nextCursor = page.pagination.nextCursor;
if (!page.pagination.hasMore) break;
if (nextCursor === null) {
return yield* new PrismaPaginationError({
message:
"Invalid Prisma Management API pagination response from getProjects: hasMore was true without a non-empty nextCursor",
});
}
cursor = nextCursor;
}
return projects;
});
const findBranch = (projectId: string, gitName: string) =>
listBranches(projectId, { gitName }).pipe(
Effect.flatMap((branches) => {
const matches = branches.filter((b: ObservedBranch) => b.gitName === gitName);
return matches.length > 1
? Effect.fail(
new BranchConflict({
message: `Prisma project '${projectId}' has multiple branches named '${gitName}'; refusing to select one arbitrarily.`,
}),
)
: Effect.succeed(matches[0]);
}),
);
const attrsFrom = (
branch: ObservedBranch,
previousDefaultBranchId?: string,
): Branch["Attributes"] => ({
branchId: branch.id,
gitName: branch.gitName,
projectId: branch.project.id,
isDefault: branch.isDefault,
...(previousDefaultBranchId === undefined ? {} : { previousDefaultBranchId }),
role: branch.role,
createdAt: branch.createdAt,
updatedAt: branch.updatedAt,
});
const ensureBranchIdentity = (
branch: ObservedBranch,
expected: { projectId: string; gitName: string },
) =>
branch.project.id === expected.projectId && branch.gitName === expected.gitName
? Effect.void
: Effect.fail(
new BranchConflict({
message: `Prisma branch '${branch.id}' belongs to project '${branch.project.id}' with git name '${branch.gitName}', but this resource requires project '${expected.projectId}' and git name '${expected.gitName}'. Refusing to promote or delete a mismatched branch.`,
}),
);
const ProviderLive = () =>
Provider.effect(
Branch,
Effect.gen(function* () {
return {
stables: ["branchId"],
list: Effect.fn(function* () {
const projects = yield* listProjects();
const branches = yield* Effect.forEach(
projects,
(project) =>
listBranches(project.id).pipe(Effect.catchTag("NotFound", () => Effect.succeed([]))),
{ concurrency: 8 },
);
// Current defaults and production-role branches are project-owned
// and undeletable through the Branch API. Project deletion removes
// them; omit them here so unsafe nuke only receives deletable rows.
return branches
.flat()
.filter((branch) => !branch.isDefault && branch.role !== "production")
.map((branch) => attrsFrom(branch));
}),
diff: Effect.fn(function* ({ id, olds, news, output }) {
if (!isInputObject(news)) return undefined;
if (isPrismaDevId(output?.branchId)) {
return { action: "update" } as const;
}
const oldProjectId = output?.projectId ?? unresolvedProjectIdOf(olds.project);
const newProjectId = isResolved(news.project)
? unresolvedProjectIdOf(news.project)
: undefined;
const newGitName = isResolved(news.gitName)
? yield* createGitName(id, news.gitName)
: undefined;
if (
concreteIdsChanged(oldProjectId, newProjectId) ||
(newGitName !== undefined &&
newGitName !== (output?.gitName ?? (yield* createGitName(id, olds.gitName))))
) {
return { action: "replace" } as const;
}
if (!isResolved(news.isDefault)) return undefined;
// The Management API can promote a branch, atomically demoting the
// old default, but explicitly rejects demoting the current default.
// `false` therefore means "do not promote", not "demote".
if (news.isDefault === true && output?.isDefault !== true) {
return { action: "update" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const branchId = isPrismaDevId(output?.branchId) ? undefined : output?.branchId;
const findBranchInProject = Effect.gen(function* () {
const projectId = unresolvedProjectIdOf(olds.project);
return projectId
? yield* findBranch(projectId, yield* createGitName(id, olds.gitName))
: undefined;
});
const branch = branchId
? yield* getBranch({ branchId }).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
)
: yield* findBranchInProject;
if (!branch) return undefined;
const attrs = attrsFrom(branch, output?.previousDefaultBranchId);
return branchId === undefined ? Unowned(attrs) : attrs;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const projectId = yield* resolveProjectId(news.project);
const gitName = yield* createGitName(id, news.gitName);
let previousDefaultBranchId = output?.previousDefaultBranchId;
const branchId = isPrismaDevId(output?.branchId) ? undefined : output?.branchId;
let branch = branchId
? yield* getBranch({ branchId }).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
)
: undefined;
if (!branch) {
const liveBranches = yield* listBranches(projectId);
const defaults = liveBranches.filter((candidate) => candidate.isDefault);
if (defaults.length !== 1) {
return yield* new BranchConflict({
message:
defaults.length === 0
? `Prisma project '${projectId}' has no default branch. Refusing to create a standalone Branch because the Management API would make it the undeletable production branch; create or repair the owning Prisma.Project first.`
: `Prisma project '${projectId}' has ${defaults.length} default branches. Refusing to create a Branch until the project invariant is repaired.`,
});
}
previousDefaultBranchId = defaults[0]!.id;
branch = yield* createProjectBranch({
projectId,
gitName,
...(news.isDefault === undefined ? {} : { isDefault: news.isDefault }),
}).pipe(
// A replayed create would make a second branch; the retry
// policy cannot see the request, so opt out explicitly.
Retry.none,
Effect.map((response) => response.data),
Effect.catchTag("Conflict", () =>
Effect.fail(
new BranchConflict({
message: `Prisma branch '${gitName}' appeared after the adoption check. Refusing to take it over; rerun with adoption enabled if it is the intended branch.`,
}),
),
),
);
}
yield* ensureBranchIdentity(branch, {
projectId,
gitName,
});
if (news.isDefault === true && !branch.isDefault) {
const liveBranches = yield* listBranches(projectId);
const defaults = liveBranches.filter((candidate) => candidate.isDefault);
if (defaults.length !== 1 || defaults[0]!.id === branch.id) {
return yield* new BranchConflict({
message: `Prisma project '${projectId}' does not have exactly one different default branch to restore later. Refusing to promote '${branch.gitName}'.`,
});
}
previousDefaultBranchId = defaults[0]!.id;
branch = (yield* updateBranch({
branchId: branch.id,
isDefault: true,
})).data;
yield* ensureBranchIdentity(branch, {
projectId,
gitName,
});
if (!branch.isDefault) {
return yield* new BranchUnexpectedResponse({
message: `Prisma branch '${branch.id}' promotion did not converge to the default branch.`,
});
}
}
return attrsFrom(branch, previousDefaultBranchId);
}),
delete: Effect.fn(function* ({ output }) {
if (isPrismaDevId(output.branchId)) return;
const branch = yield* getBranch({
branchId: output.branchId,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
);
if (!branch) return;
yield* ensureBranchIdentity(branch, {
projectId: output.projectId,
gitName: output.gitName,
});
if (branch.role === "production") {
return yield* new BranchConflict({
message: `Cannot delete Prisma branch '${branch.gitName ?? output.branchId}' directly because its production role is immutable. Delete the owning Prisma.Project.`,
});
}
if (branch.isDefault) {
const previousDefaultBranchId = output.previousDefaultBranchId;
if (previousDefaultBranchId === undefined || previousDefaultBranchId === branch.id) {
return yield* new BranchConflict({
message: `Cannot safely delete default Prisma branch '${branch.gitName}' because state does not identify the branch it displaced. Promote another branch explicitly before deleting this resource.`,
});
}
const previous = yield* getBranch({
branchId: previousDefaultBranchId,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () =>
Effect.fail(
new BranchOperationFailed({
message: `Cannot restore previous default Prisma branch '${previousDefaultBranchId}' because it no longer exists. Promote another branch explicitly before deleting '${branch.gitName}'.`,
}),
),
),
);
if (previous.project.id !== output.projectId || previous.id === branch.id) {
return yield* new BranchConflict({
message: `Previous default Prisma branch '${previous.id}' does not belong to project '${output.projectId}'. Refusing an unsafe promotion.`,
});
}
const restored = previous.isDefault
? previous
: (yield* updateBranch({
branchId: previous.id,
isDefault: true,
})).data;
if (
restored.id !== previous.id ||
restored.project.id !== output.projectId ||
!restored.isDefault
) {
return yield* new BranchUnexpectedResponse({
message: `Prisma did not confirm restoration of previous default branch '${previous.id}'. Refusing to delete '${branch.gitName}'.`,
});
}
const demoted = yield* getBranch({
branchId: branch.id,
}).pipe(
Effect.map((response) => response.data),
Effect.catchTag("NotFound", () => Effect.undefined),
);
if (!demoted) return;
yield* ensureBranchIdentity(demoted, {
projectId: output.projectId,
gitName: output.gitName,
});
if (demoted.isDefault) {
return yield* new BranchUnexpectedResponse({
message: `Prisma branch '${branch.gitName}' remained default after restoring '${previous.gitName}'. Refusing to delete it.`,
});
}
}
// A member deleted moments ago (e.g. an App) can still count as
// live until Prisma's control plane catches up.
yield* deleteBranch({
branchId: output.branchId,
}).pipe(
Effect.retry({
while: (error) => error._tag === "Conflict",
schedule: Schedule.exponential("500 millis"),
times: 6,
}),
Effect.catchTag("NotFound", () => Effect.void),
);
}),
};
}),
);
const ProviderLocal = () =>
devProvider(Branch, ["branchId"], ({ id, news }) => ({
branchId: devId("branch", id),
gitName: news.gitName ?? id,
projectId: attrOrString(news.project, "projectId"),
isDefault: news.isDefault ?? false,
role: news.isDefault ? "production" : "preview",
createdAt: DEV_TIMESTAMP,
updatedAt: DEV_TIMESTAMP,
}));
export const BranchProvider = () =>
ProviderLayer.dual(Branch, {
local: () => ProviderLocal(),
live: () => ProviderLive(),
});