sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ EntityResolution/ SchemaMapping.ts

import * as entityresolution from "@distilled.cloud/aws/entityresolution";
import { Unowned } from "alchemy/AdoptPolicy";
import { deepEqual, isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { readEntityResolutionTags, syncEntityResolutionTags } from "./internal.ts";

export interface SchemaMappingProps {
  /**
   * Name of the schema mapping. Must be unique per account/region and match
   * `[a-zA-Z_0-9-]*`. If omitted, a unique name is generated from the app,
   * stage, and logical ID. Changing the name replaces the schema mapping.
   */
  schemaName?: string;
  /**
   * A description of the schema mapping.
   */
  description?: string;
  /**
   * The columns of the input records table and how Entity Resolution should
   * interpret them: the attribute `type` (e.g. `UNIQUE_ID`, `EMAIL_ADDRESS`,
   * `NAME`, `PHONE_NUMBER`), an optional `matchKey` used by rule-based
   * matching, and optional `groupName`/`subType`/`hashed` metadata.
   *
   * Mutable in place — but a schema mapping becomes immutable while it is
   * referenced by a matching workflow.
   */
  mappedInputFields: entityresolution.SchemaInputAttribute[];
  /**
   * Tags to apply to the schema mapping. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface SchemaMapping extends Resource<
  "AWS.EntityResolution.SchemaMapping",
  SchemaMappingProps,
  {
    /**
     * The name of the schema mapping.
     */
    schemaName: string;
    /**
     * The ARN of the schema mapping.
     */
    schemaArn: string;
  },
  never,
  Providers
> {}

/**
 * An AWS Entity Resolution schema mapping — the schema of an input customer
 * records table. It tells Entity Resolution the attribute type of each column
 * (name, email, phone, unique id, …) and which columns rule-based matching
 * compares via `matchKey`.
 *
 * ### Creating Schema Mappings
 * **Example:** Customer records schema
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const schema = yield* AWS.EntityResolution.SchemaMapping("Customers", {
 *   mappedInputFields: [
 *     { fieldName: "id", type: "UNIQUE_ID" },
 *     { fieldName: "email", type: "EMAIL_ADDRESS", matchKey: "email" },
 *     { fieldName: "name", type: "NAME", matchKey: "name" },
 *   ],
 * });
 * ```
 *
 * ### Matching Workflows
 * **Example:** Use the schema in a matching workflow input source
 * ```typescript
 * const workflow = yield* AWS.EntityResolution.MatchingWorkflow("Dedupe", {
 *   inputSourceConfig: [
 *     { inputSourceARN: table.tableArn, schemaName: schema.schemaName },
 *   ],
 *   // ...
 * });
 * ```
 *
 * @resource
 */
export const SchemaMapping = Resource<SchemaMapping>("AWS.EntityResolution.SchemaMapping");

export const SchemaMappingProvider = () =>
  Provider.effect(
    SchemaMapping,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (
        id: string,
        props: { schemaName?: string | undefined },
      ) {
        return props.schemaName ?? (yield* createPhysicalName({ id, maxLength: 255 }));
      });

      /** Get a schema mapping by name; typed not-found → undefined. */
      const getByName = Effect.fn(function* (schemaName: string) {
        return yield* entityresolution
          .getSchemaMapping({ schemaName })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      return {
        stables: ["schemaName", "schemaArn"],

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.schemaName ?? (yield* createName(id, olds ?? {}));
          const mapping = yield* getByName(name);
          if (mapping === undefined) return undefined;
          const attrs = {
            schemaName: mapping.schemaName,
            schemaArn: mapping.schemaArn,
          };
          // getSchemaMapping does not return tags — read them via
          // listTagsForResource for the ownership check.
          const tags = yield* readEntityResolutionTags(mapping.schemaArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.schemaName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. Observe — names are unique, so the name IS the identity.
          let mapping = yield* getByName(name);

          // 2. Ensure — create when missing; tolerate the concurrent-create
          //    race, then re-observe: the create response is a structural
          //    subset of the Get shape (it omits createdAt/updatedAt/
          //    hasWorkflows).
          if (mapping === undefined) {
            yield* entityresolution
              .createSchemaMapping({
                schemaName: name,
                description: news.description,
                mappedInputFields: news.mappedInputFields,
                tags: desiredTags,
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
            mapping = yield* entityresolution.getSchemaMapping({
              schemaName: name,
            });
          }

          // 3. Sync — description and mapped fields update in place (fails
          //    with a typed ConflictException while a workflow references
          //    the schema). Only call the API on an actual delta.
          if (
            !deepEqual(mapping.mappedInputFields, news.mappedInputFields) ||
            (mapping.description || undefined) !== (news.description ?? undefined)
          ) {
            // The update response omits createdAt/updatedAt/hasWorkflows;
            // name and ARN are stable, so keep the observed Get shape.
            yield* entityresolution.updateSchemaMapping({
              schemaName: name,
              description: news.description,
              mappedInputFields: news.mappedInputFields,
            });
          }

          // 3b. Sync tags against OBSERVED cloud tags (adoption-safe).
          yield* syncEntityResolutionTags(mapping.schemaArn, desiredTags);

          yield* session.note(mapping.schemaArn);
          return {
            schemaName: mapping.schemaName,
            schemaArn: mapping.schemaArn,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // deleteSchemaMapping succeeds even when the mapping is already
          // gone; it conflicts while a matching workflow still references
          // the schema (the engine deletes dependents first — retry the
          // eventual-consistency window).
          yield* entityresolution.deleteSchemaMapping({ schemaName: output.schemaName }).pipe(
            Effect.retry({
              while: (e) => e._tag === "ConflictException",
              schedule: Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(10)]),
            }),
          );
        }),

        list: () =>
          entityresolution.listSchemaMappings.items({}).pipe(
            Stream.map((summary) => ({
              schemaName: summary.schemaName,
              schemaArn: summary.schemaArn,
            })),
            Stream.runCollect,
            Effect.map((chunk) => Array.from(chunk)),
          ),
      };
    }),
  );