import * as datazone from "@distilled.cloud/aws/datazone";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { unredact } from "./internal.ts";
export interface ProjectProps {
/**
* The identifier of the {@link Domain} the project lives in. Accepts a
* domain's `domainId` output. Changing it triggers a replacement.
*/
domainId: string;
/**
* Name of the project. If omitted, a deterministic physical name is
* generated from the app, stage, and logical ID. The name is mutable — it
* converges via `UpdateProject` without replacement.
*/
name?: string;
/**
* A description of the project.
*/
description?: string;
/**
* Glossary term identifiers to attach to the project.
*/
glossaryTerms?: string[];
}
export interface Project extends Resource<
"AWS.DataZone.Project",
ProjectProps,
{
/** The unique identifier of the project. */
projectId: string;
/** The identifier of the domain the project lives in. */
domainId: string;
/** The name of the project. */
name: string;
/** The status of the project (`ACTIVE` once settled). */
projectStatus: string | undefined;
/** The identifier of the domain unit the project belongs to. */
domainUnitId: string | undefined;
/** The DataZone user who created the project. */
createdBy: string;
}
> {}
/**
* An Amazon DataZone project — the collaboration space within a domain where
* teams catalog, publish, and subscribe to data assets.
*
* The creating principal is automatically the project owner. DataZone
* projects do not support resource tags, so ownership is tracked purely by
* identity.
*
* ### Creating Projects
* **Example:** Minimal Project
* ```typescript
* import * as DataZone from "@alchemy.run/aws/DataZone";
*
* const domain = yield* DataZone.Domain("governance", {});
*
* const project = yield* DataZone.Project("analytics", {
* domainId: domain.domainId,
* description: "Analytics team project",
* });
* ```
*
* **Example:** Project with an Explicit Name
* ```typescript
* const project = yield* DataZone.Project("analytics", {
* domainId: domain.domainId,
* name: "analytics-team",
* glossaryTerms: [term.id],
* });
* ```
*
* @resource
*/
export const Project = Resource<Project>("AWS.DataZone.Project");
/** Project status values indicating an in-flight transition to wait out. */
const PROJECT_TRANSIENT = new Set(["DELETING", "MOVING", "UPDATING"]);
/**
* A freshly created domain propagates the creator's user profile eventually;
* `createProject` can transiently reject with `AccessDeniedException` right
* after domain creation. Wrapped in an explicitly-typed helper so the
* `Effect.retry` conditional return type does not leak into declaration emit
* (see PATTERNS §7).
*/
const retryWhileUserProfilePropagates = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "AccessDeniedException",
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
});
export const ProjectProvider = () =>
Provider.effect(
Project,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: ProjectProps) {
return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
});
// A deleted project — or a project inside a deleted domain — is
// reported as AccessDeniedException, NOT ResourceNotFoundException:
// DataZone evaluates domain-scoped authorization before existence.
// Both mean "absent".
const getProjectOrUndefined = Effect.fn(function* (domainId: string, projectId: string) {
return yield* datazone
.getProject({ domainIdentifier: domainId, identifier: projectId })
.pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.undefined,
AccessDeniedException: () => Effect.undefined,
}),
);
});
const findByName = Effect.fn(function* (domainId: string, name: string) {
const found = yield* datazone.listProjects({ domainIdentifier: domainId, name }).pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.undefined,
AccessDeniedException: () => Effect.undefined,
}),
);
const summary = (found?.items ?? []).find(
(s) => unredact(s.name) === name && s.projectStatus !== "DELETING",
);
return summary?.id;
});
// Poll the project to a settled (non-transient) status — project
// operations settle within seconds.
const waitForSettled = Effect.fn(function* (domainId: string, projectId: string) {
return yield* getProjectOrUndefined(domainId, projectId).pipe(
Effect.repeat({
schedule: Schedule.fixed("3 seconds"),
until: (project) =>
project === undefined ||
project.projectStatus === undefined ||
!PROJECT_TRANSIENT.has(project.projectStatus),
times: 20,
}),
);
});
// Poll the project until it no longer exists — deletion is async but
// settles within seconds for empty projects.
const waitForGone = Effect.fn(function* (domainId: string, projectId: string) {
yield* getProjectOrUndefined(domainId, projectId).pipe(
Effect.repeat({
schedule: Schedule.fixed("3 seconds"),
until: (project) => project === undefined,
times: 20,
}),
);
});
const toAttributes = (project: datazone.GetProjectOutput | datazone.CreateProjectOutput) => ({
projectId: project.id,
domainId: project.domainId,
name: unredact(project.name),
projectStatus: project.projectStatus,
domainUnitId: project.domainUnitId,
createdBy: project.createdBy,
});
return Project.Provider.of({
stables: ["projectId", "domainId", "createdBy"],
// Projects are keyed by their parent domain — there is no
// account-level enumeration without a domain identifier.
list: () => Effect.succeed([]),
read: Effect.fn(function* ({ id, olds, output }) {
const domainId = output?.domainId ?? olds?.domainId;
if (domainId === undefined) return undefined;
const projectId =
output?.projectId ??
(yield* findByName(domainId, yield* createName(id, olds ?? { domainId })));
if (projectId === undefined) return undefined;
const project = yield* getProjectOrUndefined(domainId, projectId);
if (project === undefined || project.projectStatus === "DELETING") {
return undefined;
}
// Projects have no tags — ownership is tracked purely by identity.
return toAttributes(project);
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
if (olds !== undefined && olds.domainId !== news.domainId) {
return { action: "replace" } as const;
}
// name, description, and glossaryTerms converge via updateProject.
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const domainId = news.domainId;
const name = yield* createName(id, news);
// 1. OBSERVE — cloud state is authoritative; output is only an id
// cache. Fall back to a name lookup after state loss.
let project = output?.projectId
? yield* getProjectOrUndefined(domainId, output.projectId)
: undefined;
if (project === undefined) {
const foundId = yield* findByName(domainId, name);
if (foundId !== undefined) {
project = yield* getProjectOrUndefined(domainId, foundId);
}
}
if (project === undefined) {
// 2. ENSURE — create (retrying the user-profile propagation
// window right after domain creation).
project = yield* retryWhileUserProfilePropagates(
datazone.createProject({
domainIdentifier: domainId,
name,
description: news.description,
glossaryTerms: news.glossaryTerms,
}),
);
project = (yield* waitForSettled(domainId, project.id)) ?? project;
} else {
// 3. SYNC — wait out any in-flight transition, then converge the
// mutable aspects by diffing OBSERVED state against desired.
project = (yield* waitForSettled(domainId, project.id)) ?? project;
const observedTerms = project.glossaryTerms ?? [];
const desiredTerms = news.glossaryTerms ?? [];
const drifted =
unredact(project.name) !== name ||
(project.description === undefined ? undefined : unredact(project.description)) !==
(news.description ?? undefined) ||
observedTerms.length !== desiredTerms.length ||
desiredTerms.some((t) => !observedTerms.includes(t));
if (drifted) {
yield* datazone.updateProject({
domainIdentifier: domainId,
identifier: project.id,
name,
description: news.description,
glossaryTerms: news.glossaryTerms,
});
project = (yield* getProjectOrUndefined(domainId, project.id)) ?? project;
}
}
yield* session.note(project.id);
return toAttributes(project);
}),
delete: Effect.fn(function* ({ output }) {
yield* datazone
.deleteProject({
domainIdentifier: output.domainId,
identifier: output.projectId,
skipDeletionCheck: true,
})
.pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.void,
// deleting a project whose domain is already gone surfaces as
// AccessDenied — auth is checked before existence.
AccessDeniedException: () => Effect.void,
}),
);
yield* waitForGone(output.domainId, output.projectId);
}),
});
}),
);