sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ Firestore/ DatabasesCollectionGroupsIndex.ts

import * as firestore from "@distilled.cloud/gcp/firestore_v1";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
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 * as Stream from "effect/Stream";
import { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import {
  databaseIdOf,
  databaseNameOf,
  jsonEqual,
  lastSegment,
  parseDatabaseName,
  stringFromMap,
} from "./internal.ts";

const DEFAULT_QUERY_SCOPE = "COLLECTION";
const DEFAULT_API_SCOPE = "ANY_API";

export type IndexQueryScope = firestore.GoogleFirestoreAdminV1IndexQueryScopeEnum | (string & {});
export type IndexApiScope = firestore.GoogleFirestoreAdminV1IndexApiScopeEnum | (string & {});
export type IndexDensity = firestore.GoogleFirestoreAdminV1IndexDensityEnum | (string & {});
export type IndexFieldOrder = firestore.GoogleFirestoreAdminV1IndexFieldOrderEnum | (string & {});
export type IndexFieldArrayConfig =
  | firestore.GoogleFirestoreAdminV1IndexFieldArrayConfigEnum
  | (string & {});

export type IndexVectorConfig = {
  /** Vector dimension this configuration applies to. */
  dimension?: number;
  /** Flat (exhaustive) vector index. */
  flat?: Record<string, never>;
};

export type IndexField = {
  /**
   * Field path to index. `__name__` is valid. For composite indexes
   * the API appends `__name__` when it is omitted as the last field.
   */
  fieldPath?: string;
  /** Order for inequality / sort (`ASCENDING`, `DESCENDING`). */
  order?: IndexFieldOrder;
  /** Array-contains indexing (`CONTAINS`). */
  arrayConfig?: IndexFieldArrayConfig;
  /** Vector nearest-neighbor configuration. */
  vectorConfig?: IndexVectorConfig;
};

export type DatabasesCollectionGroupsIndexProps = {
  /**
   * Parent database. Full name `projects/{project}/databases/{database}`
   * or the database id. Immutable — changing it replaces the index.
   */
  database: string;
  /**
   * Collection group id (`users`, `posts`, …). Immutable — changing it
   * replaces the index.
   */
  collectionGroup: string;
  /**
   * Indexed fields. Composite indexes need 2–100 fields. Immutable —
   * changing fields replaces the index.
   */
  fields: IndexField[];
  /**
   * Query scope.
   * @default "COLLECTION"
   */
  queryScope?: IndexQueryScope;
  /**
   * API scope.
   * @default "ANY_API"
   */
  apiScope?: IndexApiScope;
  /**
   * Index density. Immutable — changing it replaces the index.
   */
  density?: IndexDensity;
  /**
   * Unique index. Immutable — changing it replaces the index.
   * @default false
   */
  unique?: boolean;
  /**
   * Multikey index (MongoDB-compatible API). Immutable.
   * @default false
   */
  multikey?: boolean;
  /**
   * Shard count. Immutable — changing it replaces the index.
   */
  shardCount?: number;
};

export type DatabasesCollectionGroupsIndex = Resource<
  "GCP.Firestore.DatabasesCollectionGroupsIndex",
  DatabasesCollectionGroupsIndexProps,
  {
    /** Full resource name `.../collectionGroups/{collection}/indexes/{index}`. */
    name: string;
    /** Server-assigned index id. */
    indexId: string;
    /** Parent collection group resource name. */
    collectionGroup: string;
    /** Collection group id. */
    collectionGroupId: string;
    /** Parent database resource name. */
    database: string;
    /** Parent database id. */
    databaseId: string;
    /** Project id. */
    project: string;
    /** Query scope. */
    queryScope: string | undefined;
    /** API scope. */
    apiScope: string | undefined;
    /** Density. */
    density: string | undefined;
    /** Serving state (`CREATING`, `READY`, `NEEDS_REPAIR`). */
    state: string | undefined;
    /** Indexed fields. */
    fields: IndexField[];
    /** Whether the index is unique. */
    unique: boolean;
    /** Whether the index is multikey. */
    multikey: boolean;
    /** Shard count, if set. */
    shardCount: number | undefined;
  },
  never,
  Providers
>;

/**
 * A composite Firestore index on a collection group.
 *
 * The index id is assigned by the API. Indexes are immutable — changing
 * fields, scope, density, uniqueness, or the parent collection replaces
 * the index. Indexes have no labels field: `read` reports an index it
 * finds without prior state as unowned (adopt it with `--adopt`).
 *
 * ### Creating an Index
 * **Example:** Composite index on a collection
 * ```typescript
 * const database = yield* GCP.Firestore.Database("App", {
 *   location: "us-central1",
 * });
 * const index = yield* GCP.Firestore.DatabasesCollectionGroupsIndex(
 *   "UsersByName",
 *   {
 *     database: database.name,
 *     collectionGroup: "users",
 *     queryScope: "COLLECTION",
 *     fields: [
 *       { fieldPath: "name", order: "ASCENDING" },
 *       { fieldPath: "created", order: "DESCENDING" },
 *     ],
 *   },
 * );
 * ```
 *
 * @resource
 * @category Firestore
 */
export const DatabasesCollectionGroupsIndex = Resource<DatabasesCollectionGroupsIndex>(
  "GCP.Firestore.DatabasesCollectionGroupsIndex",
);

export class IndexNotResolved extends Data.TaggedError("GCP.Firestore.IndexNotResolved")<{
  resourceName: string;
}> {}

export class IndexStillExists extends Data.TaggedError("GCP.Firestore.IndexStillExists")<{
  resourceName: string;
}> {}

const normalizeEnum = (value: string | undefined, fallback: string) => {
  const next = (value ?? fallback).toUpperCase();
  return next.endsWith("_UNSPECIFIED") ? fallback : next;
};

const fieldOf = (field: IndexField | firestore.GoogleFirestoreAdminV1IndexField): IndexField => ({
  fieldPath: field.fieldPath,
  order: field.order,
  arrayConfig: field.arrayConfig,
  vectorConfig:
    field.vectorConfig !== undefined
      ? {
          dimension: field.vectorConfig.dimension,
          flat: field.vectorConfig.flat !== undefined ? {} : undefined,
        }
      : undefined,
});

const canonicalizeFields = (
  fields: readonly (IndexField | firestore.GoogleFirestoreAdminV1IndexField)[],
) => {
  const mapped = fields.map(fieldOf);
  const last = mapped[mapped.length - 1];
  if (last !== undefined && last.fieldPath !== "__name__") {
    mapped.push({
      fieldPath: "__name__",
      order: last.order ?? "ASCENDING",
    });
  }
  return mapped;
};

const fieldsKey = (
  fields: readonly (IndexField | firestore.GoogleFirestoreAdminV1IndexField)[] | undefined,
) =>
  JSON.stringify(
    canonicalizeFields(fields ?? []).map((field) => ({
      fieldPath: field.fieldPath ?? "",
      order: field.order?.toUpperCase(),
      arrayConfig: field.arrayConfig?.toUpperCase(),
      vectorConfig: field.vectorConfig,
    })),
  );

const collectionGroupParent = (project: string, database: string, collectionGroup: string) =>
  `${databaseNameOf(project, database)}/collectionGroups/${lastSegment(collectionGroup)}`;

const toAttrs = (
  index: firestore.GoogleFirestoreAdminV1Index,
  project: string,
): DatabasesCollectionGroupsIndex["Attributes"] => {
  const name = index.name ?? "";
  const parsed = parseDatabaseName(name);
  const database = databaseNameOf(parsed.project || project, parsed.databaseId);
  return {
    name,
    indexId: parsed.indexId || lastSegment(name),
    collectionGroup: `${database}/collectionGroups/${parsed.collectionGroup}`,
    collectionGroupId: parsed.collectionGroup,
    database,
    databaseId: parsed.databaseId,
    project: parsed.project || project,
    queryScope: index.queryScope,
    apiScope: index.apiScope,
    density: index.density,
    state: index.state,
    fields: (index.fields ?? []).map(fieldOf),
    unique: index.unique === true,
    multikey: index.multikey === true,
    shardCount: index.shardCount,
  };
};

const desiredBody = (news: DatabasesCollectionGroupsIndexProps) => ({
  queryScope: news.queryScope ?? DEFAULT_QUERY_SCOPE,
  apiScope: news.apiScope ?? DEFAULT_API_SCOPE,
  density: news.density,
  unique: news.unique === true ? true : undefined,
  multikey: news.multikey === true ? true : undefined,
  shardCount: news.shardCount,
  fields: news.fields.map(fieldOf),
});

const matchesDesired = (
  index: firestore.GoogleFirestoreAdminV1Index,
  news: DatabasesCollectionGroupsIndexProps,
) => {
  const desired = desiredBody(news);
  return (
    normalizeEnum(index.queryScope, DEFAULT_QUERY_SCOPE) ===
      normalizeEnum(desired.queryScope, DEFAULT_QUERY_SCOPE) &&
    normalizeEnum(index.apiScope, DEFAULT_API_SCOPE) ===
      normalizeEnum(desired.apiScope, DEFAULT_API_SCOPE) &&
    (index.unique === true) === (desired.unique === true) &&
    (index.multikey === true) === (desired.multikey === true) &&
    jsonEqual(index.shardCount, desired.shardCount) &&
    (desired.density === undefined ||
      normalizeEnum(index.density, desired.density) ===
        normalizeEnum(desired.density, desired.density)) &&
    fieldsKey(index.fields) === fieldsKey(desired.fields)
  );
};

const getByName = (name: string) =>
  firestore
    .getProjectsDatabasesCollectionGroupsIndexes({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const listOnParent = (parent: string) =>
  firestore.listProjectsDatabasesCollectionGroupsIndexes.pages({ parent }).pipe(
    Stream.flatMap((page) => Stream.fromIterable(page.indexes ?? [])),
    Stream.runCollect,
    Effect.map((chunk) => Array.from(chunk)),
    // The parent database is gone: it has no indexes.
    Effect.catchTag("NotFound", () =>
      Effect.succeed([] as firestore.GoogleFirestoreAdminV1Index[]),
    ),
  );

const nameFromOperation = (operation: firestore.GoogleLongrunningOperation): string | undefined =>
  stringFromMap(operation.response, "name") ??
  stringFromMap(operation.metadata, "index") ??
  stringFromMap(operation.metadata, "name");

const resolveCreatedIndexName = (
  operation: firestore.GoogleLongrunningOperation | undefined,
  parent: string,
  news: DatabasesCollectionGroupsIndexProps,
) =>
  Effect.gen(function* () {
    if (operation !== undefined) {
      const immediate = nameFromOperation(operation);
      if (immediate !== undefined) return immediate;
      if (operation.name !== undefined) {
        const latest = yield* firestore
          .getProjectsDatabasesOperations({ name: operation.name })
          .pipe(Effect.catchTag("NotFound", () => Effect.succeed(operation)));
        const fromOp = nameFromOperation(latest);
        if (fromOp !== undefined) return fromOp;
      }
    }
    const match = (yield* listOnParent(parent)).find((index) => matchesDesired(index, news));
    if (match?.name !== undefined) return match.name;
    return yield* new IndexNotResolved({ resourceName: `${parent}/indexes` });
  }).pipe(
    Effect.retry({
      while: (error) => error._tag === "GCP.Firestore.IndexNotResolved",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const waitUntilExists = (name: string) =>
  getByName(name).pipe(
    Effect.flatMap((index) =>
      index ? Effect.succeed(index) : Effect.fail(new IndexNotResolved({ resourceName: name })),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Firestore.IndexNotResolved",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
  );

const waitUntilGone = (name: string) =>
  getByName(name).pipe(
    Effect.filterOrFail(
      (index) => index === undefined,
      () => new IndexStillExists({ resourceName: name }),
    ),
    Effect.retry({
      while: (error) => error._tag === "GCP.Firestore.IndexStillExists",
      times: 8,
      schedule: Schedule.spaced("2 seconds"),
    }),
    Effect.asVoid,
  );

export const DatabasesCollectionGroupsIndexProvider = () =>
  Provider.succeed(DatabasesCollectionGroupsIndex, {
    stables: [
      "name",
      "indexId",
      "collectionGroup",
      "collectionGroupId",
      "database",
      "databaseId",
      "project",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousDatabase = databaseIdOf(
        olds?.database ?? output?.database ?? output?.databaseId ?? "",
      );
      const nextDatabase = databaseIdOf(news.database);
      const previousGroup = lastSegment(olds?.collectionGroup ?? output?.collectionGroupId ?? "");
      const nextGroup = lastSegment(news.collectionGroup);
      const previousFields = fieldsKey(olds?.fields ?? output?.fields);
      const nextFields = fieldsKey(news.fields);
      const previousScope = normalizeEnum(
        olds?.queryScope ?? output?.queryScope,
        DEFAULT_QUERY_SCOPE,
      );
      const nextScope = normalizeEnum(news.queryScope, DEFAULT_QUERY_SCOPE);
      const previousApi = normalizeEnum(olds?.apiScope ?? output?.apiScope, DEFAULT_API_SCOPE);
      const nextApi = normalizeEnum(news.apiScope, DEFAULT_API_SCOPE);
      const previousUnique = olds?.unique === true || output?.unique === true;
      const nextUnique = news.unique === true;
      const previousMultikey = olds?.multikey === true || output?.multikey === true;
      const nextMultikey = news.multikey === true;
      const previousDensity = (olds?.density ?? output?.density ?? "").toUpperCase();
      const nextDensity = (news.density ?? previousDensity).toUpperCase();
      const previousShards = olds?.shardCount ?? output?.shardCount;
      const nextShards = news.shardCount ?? previousShards;
      if (
        (previousDatabase.length > 0 && previousDatabase !== nextDatabase) ||
        (previousGroup.length > 0 && previousGroup !== nextGroup) ||
        previousFields !== nextFields ||
        previousScope !== nextScope ||
        previousApi !== nextApi ||
        previousUnique !== nextUnique ||
        previousMultikey !== nextMultikey ||
        (news.density !== undefined && previousDensity !== nextDensity) ||
        previousShards !== nextShards
      ) {
        return { action: "replace" as const };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ output }) {
      const env = yield* GcpEnvironment.current;
      const name = output?.name;
      if (name === undefined || name.length === 0) return undefined;
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project);
      // No labels field: without prior state it may not be ours.
      return output !== undefined ? attrs : Unowned(attrs);
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const env = yield* GcpEnvironment.current;
      const parent = collectionGroupParent(env.project, news.database, news.collectionGroup);
      const body = desiredBody(news);

      let current = output?.name !== undefined ? yield* getByName(output.name) : undefined;

      if (current === undefined) {
        const existing = yield* listOnParent(parent);
        current = existing.find((index) => matchesDesired(index, news));
      }

      if (current === undefined) {
        const created = yield* firestore
          .createProjectsDatabasesCollectionGroupsIndexes({
            parent,
            body,
          })
          .pipe(Effect.catchTag("Conflict", () => Effect.undefined));
        const name = yield* resolveCreatedIndexName(created, parent, news);
        current = yield* waitUntilExists(name);
      } else if (current.name !== undefined) {
        current = yield* waitUntilExists(current.name);
      }

      if (current === undefined || current.name === undefined) {
        return yield* new IndexNotResolved({ resourceName: `${parent}/indexes` });
      }

      return toAttrs(current, env.project);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* firestore
        .deleteProjectsDatabasesCollectionGroupsIndexes({
          name: output.name,
        })
        .pipe(Effect.catchTag("NotFound", () => Effect.void));
      yield* waitUntilGone(output.name);
    }),
  });