sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ Location/ Map.ts

import * as location from "@distilled.cloud/aws/location";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, type Tags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as EffectStream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { toTagRecord } from "./internal.ts";

export class MapUnexpectedResponse extends Data.TaggedError("MapUnexpectedResponse")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * Rendering configuration for a map. `style` selects the base map style and is
 * immutable — changing it replaces the map.
 */
export interface MapConfiguration {
  /**
   * The map style. Selecting a style determines the map's data provider
   * (Esri, HERE, or Grab). Immutable — changing the style replaces the map.
   *
   * Common values: `VectorEsriNavigation`, `VectorEsriStreets`,
   * `VectorHereExplore`, `RasterHereExploreSatellite`,
   * `VectorGrabStandardLight`.
   */
  style: string;
  /**
   * Political view (an ISO 3166-1 alpha-3 country code) applied to the map's
   * disputed borders and labels.
   */
  politicalView?: string;
}

export interface MapProps {
  /**
   * Name of the map resource. Immutable — changing it replaces the map.
   * @default ${app}-${stage}-${id}
   */
  mapName?: string;
  /**
   * Rendering configuration for the map (base style + political view).
   */
  configuration: MapConfiguration;
  /**
   * Optional description of the map resource.
   */
  description?: string;
  /**
   * Tags to associate with the map.
   */
  tags?: Record<string, string>;
}

export interface Map extends Resource<
  "AWS.Location.Map",
  MapProps,
  {
    /** Physical name of the map resource. */
    mapName: string;
    /** ARN of the map resource. */
    mapArn: string;
    /** The map style selected at creation. */
    style: string;
    /** Political view currently applied to the map, if any. */
    politicalView: string | undefined;
    /** Data provider backing the map, derived from the style. */
    dataSource: string;
    /** Description of the map resource. */
    description: string | undefined;
    /** Tags currently associated with the map. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An Amazon Location Service map resource. A map exposes vector/raster tiles,
 * glyphs, and sprites for a chosen base style. The map style is immutable;
 * the political view and description can be updated in place.
 *
 * ### Creating Maps
 * **Example:** Basic Map
 * ```typescript
 * import * as Location from "@alchemy.run/aws/Location";
 *
 * const map = yield* Location.Map("AppMap", {
 *   configuration: { style: "VectorEsriNavigation" },
 * });
 * ```
 *
 * **Example:** Map with Political View
 * ```typescript
 * const map = yield* Location.Map("RegionMap", {
 *   configuration: { style: "VectorHereExplore", politicalView: "IND" },
 *   description: "Map with India political view",
 * });
 * ```
 *
 * @resource
 */
export const Map = Resource<Map>("AWS.Location.Map");

const createMapName = (id: string, props: { mapName?: string | undefined }) =>
  Effect.gen(function* () {
    if (props.mapName) return props.mapName;
    return yield* createPhysicalName({ id, maxLength: 100 });
  });

const readMap = Effect.fn(function* (mapName: string) {
  const found = yield* location
    .describeMap({ MapName: mapName })
    .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
  if (!found) return undefined;
  return {
    mapName: found.MapName,
    mapArn: found.MapArn,
    style: found.Configuration.Style,
    politicalView: Redacted.isRedacted(found.Configuration.PoliticalView)
      ? Redacted.value(found.Configuration.PoliticalView)
      : found.Configuration.PoliticalView,
    dataSource: found.DataSource,
    description: found.Description ? found.Description : undefined,
    tags: toTagRecord(found.Tags),
  } satisfies Map["Attributes"];
});

export const MapProvider = () =>
  Provider.effect(
    Map,
    Effect.gen(function* () {
      return {
        stables: ["mapName", "mapArn"],
        list: () =>
          Effect.gen(function* () {
            const names = yield* location.listMaps.pages({}).pipe(
              EffectStream.runCollect,
              Effect.map((chunk) =>
                Array.from(chunk).flatMap((page) =>
                  (page.Entries ?? []).map((entry) => entry.MapName),
                ),
              ),
            );
            const hydrated = yield* Effect.forEach(names, (name) => readMap(name), {
              concurrency: 10,
            });
            return hydrated.filter((attrs): attrs is Map["Attributes"] => attrs !== undefined);
          }),
        read: Effect.fn(function* ({ id, olds, output }) {
          const mapName = output?.mapName ?? (yield* createMapName(id, olds ?? {}));
          const state = yield* readMap(mapName);
          if (!state) return undefined;
          return (yield* hasAlchemyTags(id, state.tags as Tags)) ? state : Unowned(state);
        }),
        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return;
          const oldName = yield* createMapName(id, olds);
          const newName = yield* createMapName(id, news);
          // Name and base style are immutable — either change forces a replace.
          if (oldName !== newName || olds.configuration?.style !== news.configuration?.style) {
            return { action: "replace" } as const;
          }
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const mapName = output?.mapName ?? (yield* createMapName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };

          // Observe — cloud state is authoritative; output is only a name cache.
          let state = yield* readMap(mapName);

          // Ensure — create if missing; tolerate a concurrent create.
          if (state === undefined) {
            yield* location
              .createMap({
                MapName: mapName,
                Configuration: {
                  Style: news.configuration.style,
                  PoliticalView: news.configuration.politicalView,
                },
                Description: news.description,
                Tags: desiredTags,
              })
              .pipe(Effect.catchTag("ConflictException", () => Effect.void));
            state = yield* readMap(mapName);
            if (state === undefined) {
              return yield* new MapUnexpectedResponse({
                message: `failed to read created map ${mapName}`,
              });
            }
          }

          // Sync description + political view.
          if (
            state.description !== (news.description ?? undefined) ||
            state.politicalView !== (news.configuration.politicalView ?? undefined)
          ) {
            yield* location.updateMap({
              MapName: mapName,
              Description: news.description,
              ConfigurationUpdate: {
                PoliticalView: news.configuration.politicalView,
              },
            });
          }

          // Sync tags — diff against observed cloud tags.
          const { removed, upsert } = diffTags(state.tags, desiredTags);
          if (removed.length > 0) {
            yield* location.untagResource({
              ResourceArn: state.mapArn,
              TagKeys: removed,
            });
          }
          if (upsert.length > 0) {
            yield* location.tagResource({
              ResourceArn: state.mapArn,
              Tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }

          yield* session.note(state.mapArn);

          const final = yield* readMap(mapName);
          if (!final) {
            return yield* new MapUnexpectedResponse({
              message: `failed to read reconciled map ${mapName}`,
            });
          }
          return final;
        }),
        delete: Effect.fn(function* ({ output }) {
          yield* location
            .deleteMap({ MapName: output.mapName })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      };
    }),
  );