The best way to control Claude Code, Codex and more from any computer or phone

main
ts 213 lines 7.88 KB
Raw
1 import * as entityresolution from "@distilled.cloud/aws/entityresolution";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { deepEqual, isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Effect from "effect/Effect";
9 import * as Schedule from "effect/Schedule";
10 import * as Stream from "effect/Stream";
11 import type { Providers } from "../Providers.ts";
12 import { readEntityResolutionTags, syncEntityResolutionTags } from "./internal.ts";
13
14 export interface SchemaMappingProps {
15 /**
16 * Name of the schema mapping. Must be unique per account/region and match
17 * `[a-zA-Z_0-9-]*`. If omitted, a unique name is generated from the app,
18 * stage, and logical ID. Changing the name replaces the schema mapping.
19 */
20 schemaName?: string;
21 /**
22 * A description of the schema mapping.
23 */
24 description?: string;
25 /**
26 * The columns of the input records table and how Entity Resolution should
27 * interpret them: the attribute `type` (e.g. `UNIQUE_ID`, `EMAIL_ADDRESS`,
28 * `NAME`, `PHONE_NUMBER`), an optional `matchKey` used by rule-based
29 * matching, and optional `groupName`/`subType`/`hashed` metadata.
30 *
31 * Mutable in place — but a schema mapping becomes immutable while it is
32 * referenced by a matching workflow.
33 */
34 mappedInputFields: entityresolution.SchemaInputAttribute[];
35 /**
36 * Tags to apply to the schema mapping. Merged with internal Alchemy tags.
37 */
38 tags?: Record<string, string>;
39 }
40
41 export interface SchemaMapping extends Resource<
42 "AWS.EntityResolution.SchemaMapping",
43 SchemaMappingProps,
44 {
45 /**
46 * The name of the schema mapping.
47 */
48 schemaName: string;
49 /**
50 * The ARN of the schema mapping.
51 */
52 schemaArn: string;
53 },
54 never,
55 Providers
56 > {}
57
58 /**
59 * An AWS Entity Resolution schema mapping — the schema of an input customer
60 * records table. It tells Entity Resolution the attribute type of each column
61 * (name, email, phone, unique id, …) and which columns rule-based matching
62 * compares via `matchKey`.
63 *
64 * ### Creating Schema Mappings
65 * **Example:** Customer records schema
66 * ```typescript
67 * import * as AWS from "@alchemy.run/aws";
68 *
69 * const schema = yield* AWS.EntityResolution.SchemaMapping("Customers", {
70 * mappedInputFields: [
71 * { fieldName: "id", type: "UNIQUE_ID" },
72 * { fieldName: "email", type: "EMAIL_ADDRESS", matchKey: "email" },
73 * { fieldName: "name", type: "NAME", matchKey: "name" },
74 * ],
75 * });
76 * ```
77 *
78 * ### Matching Workflows
79 * **Example:** Use the schema in a matching workflow input source
80 * ```typescript
81 * const workflow = yield* AWS.EntityResolution.MatchingWorkflow("Dedupe", {
82 * inputSourceConfig: [
83 * { inputSourceARN: table.tableArn, schemaName: schema.schemaName },
84 * ],
85 * // ...
86 * });
87 * ```
88 *
89 * @resource
90 */
91 export const SchemaMapping = Resource<SchemaMapping>("AWS.EntityResolution.SchemaMapping");
92
93 export const SchemaMappingProvider = () =>
94 Provider.effect(
95 SchemaMapping,
96 Effect.gen(function* () {
97 const createName = Effect.fn(function* (
98 id: string,
99 props: { schemaName?: string | undefined },
100 ) {
101 return props.schemaName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
102 });
103
104 /** Get a schema mapping by name; typed not-found → undefined. */
105 const getByName = Effect.fn(function* (schemaName: string) {
106 return yield* entityresolution
107 .getSchemaMapping({ schemaName })
108 .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
109 });
110
111 return {
112 stables: ["schemaName", "schemaArn"],
113
114 read: Effect.fn(function* ({ id, olds, output }) {
115 const name = output?.schemaName ?? (yield* createName(id, olds ?? {}));
116 const mapping = yield* getByName(name);
117 if (mapping === undefined) return undefined;
118 const attrs = {
119 schemaName: mapping.schemaName,
120 schemaArn: mapping.schemaArn,
121 };
122 // getSchemaMapping does not return tags — read them via
123 // listTagsForResource for the ownership check.
124 const tags = yield* readEntityResolutionTags(mapping.schemaArn);
125 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
126 }),
127
128 diff: Effect.fn(function* ({ id, news, olds }) {
129 if (!isResolved(news)) return undefined;
130 const oldName = yield* createName(id, olds);
131 const newName = yield* createName(id, news);
132 if (oldName !== newName) {
133 return { action: "replace" } as const;
134 }
135 }),
136
137 reconcile: Effect.fn(function* ({ id, news, output, session }) {
138 const name = output?.schemaName ?? (yield* createName(id, news));
139 const internalTags = yield* createInternalTags(id);
140 const desiredTags = { ...news.tags, ...internalTags };
141
142 // 1. Observe — names are unique, so the name IS the identity.
143 let mapping = yield* getByName(name);
144
145 // 2. Ensure — create when missing; tolerate the concurrent-create
146 // race, then re-observe: the create response is a structural
147 // subset of the Get shape (it omits createdAt/updatedAt/
148 // hasWorkflows).
149 if (mapping === undefined) {
150 yield* entityresolution
151 .createSchemaMapping({
152 schemaName: name,
153 description: news.description,
154 mappedInputFields: news.mappedInputFields,
155 tags: desiredTags,
156 })
157 .pipe(Effect.catchTag("ConflictException", () => Effect.void));
158 mapping = yield* entityresolution.getSchemaMapping({
159 schemaName: name,
160 });
161 }
162
163 // 3. Sync — description and mapped fields update in place (fails
164 // with a typed ConflictException while a workflow references
165 // the schema). Only call the API on an actual delta.
166 if (
167 !deepEqual(mapping.mappedInputFields, news.mappedInputFields) ||
168 (mapping.description || undefined) !== (news.description ?? undefined)
169 ) {
170 // The update response omits createdAt/updatedAt/hasWorkflows;
171 // name and ARN are stable, so keep the observed Get shape.
172 yield* entityresolution.updateSchemaMapping({
173 schemaName: name,
174 description: news.description,
175 mappedInputFields: news.mappedInputFields,
176 });
177 }
178
179 // 3b. Sync tags against OBSERVED cloud tags (adoption-safe).
180 yield* syncEntityResolutionTags(mapping.schemaArn, desiredTags);
181
182 yield* session.note(mapping.schemaArn);
183 return {
184 schemaName: mapping.schemaName,
185 schemaArn: mapping.schemaArn,
186 };
187 }),
188
189 delete: Effect.fn(function* ({ output }) {
190 // deleteSchemaMapping succeeds even when the mapping is already
191 // gone; it conflicts while a matching workflow still references
192 // the schema (the engine deletes dependents first — retry the
193 // eventual-consistency window).
194 yield* entityresolution.deleteSchemaMapping({ schemaName: output.schemaName }).pipe(
195 Effect.retry({
196 while: (e) => e._tag === "ConflictException",
197 schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
198 }),
199 );
200 }),
201
202 list: () =>
203 entityresolution.listSchemaMappings.items({}).pipe(
204 Stream.map((summary) => ({
205 schemaName: summary.schemaName,
206 schemaArn: summary.schemaArn,
207 })),
208 Stream.runCollect,
209 Effect.map((chunk) => Array.from(chunk)),
210 ),
211 };
212 }),
213 );