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

import * as firestore from "@distilled.cloud/gcp/firestore_v1";
import { unownedUnlessPrevious } 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 { GcpEnvironment } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import { databaseNameOf, lastSegment, parseDatabaseName, toResourceId } from "./internal.ts";

const DEFAULT_DATABASE = "(default)";
const DEFAULT_COLLECTION = "_alchemy";

export type DocumentFieldValue = {
  /** UTF-8 string. */
  stringValue?: string;
  /** Integer encoded as a decimal string. */
  integerValue?: string;
  /** Boolean. */
  booleanValue?: boolean;
  /** IEEE 754 double. */
  doubleValue?: number;
  /** RFC3339 timestamp. */
  timestampValue?: string;
  /** Null sentinel (`NULL_VALUE`). */
  nullValue?: string;
};

export type DocumentProps = {
  /**
   * Database id or `projects/{project}/databases/{database}`. Defaults
   * to `"(default)"`. Immutable — changing it replaces the document.
   * @default "(default)"
   */
  database?: string;
  /**
   * Collection id relative to `parent`. Immutable — changing it
   * replaces the document.
   * @default "_alchemy"
   */
  collectionId?: string;
  /**
   * Parent document path relative to the database (no leading slash),
   * or empty for a root collection. Immutable — changing it replaces
   * the document.
   */
  parentPath?: string;
  /**
   * Client-assigned document id. If omitted, a unique id is generated
   * from the stack, stage, and logical id. Immutable — changing it
   * replaces the document.
   */
  documentId?: string;
  /**
   * Document fields. Fields absent here are removed from the document.
   */
  fields?: Record<string, DocumentFieldValue>;
};

export type Document = Resource<
  "GCP.Firestore.Document",
  DocumentProps,
  {
    /** Full resource name `projects/{project}/databases/{database}/documents/{path}`. */
    name: string;
    /** Document id (last path segment). */
    documentId: string;
    /** Database resource name. */
    database: string;
    /** Database id. */
    databaseId: string;
    /** Collection id. */
    collectionId: string;
    /** Parent path relative to the database documents root. */
    parentPath: string;
    /** Path relative to the database documents root. */
    documentPath: string;
    /** Project id. */
    project: string;
    /** Document fields. */
    fields: Record<string, DocumentFieldValue>;
    /** RFC3339 creation timestamp. */
    createTime: string | undefined;
    /** RFC3339 last-update timestamp. */
    updateTime: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Cloud Firestore document.
 *
 * Documents have no labels field and Alchemy writes nothing but the given
 * fields: `read` reports a document it finds without prior state as
 * unowned (adopt it with `--adopt`). Changing
 * `database`, `collectionId`, `parentPath`, or `documentId` replaces
 * the document. User fields update in place via `documents.patch`.
 *
 * Runtime get/patch/delete of arbitrary documents still goes through
 * {@link GetDocument} / {@link PatchDocument} / {@link DeleteDocument}.
 *
 * ### Creating a Document
 * **Example:** Generated id in `_alchemy`
 * ```typescript
 * const doc = yield* GCP.Firestore.Document("Flag", {
 *   fields: { env: { stringValue: "test" } },
 * });
 * ```
 *
 * **Example:** Named document
 * ```typescript
 * const doc = yield* GCP.Firestore.Document("Alice", {
 *   database: "(default)",
 *   collectionId: "users",
 *   documentId: "alice",
 *   fields: { name: { stringValue: "Alice" } },
 * });
 * ```
 *
 * @resource
 * @category Firestore
 */
export const Document = Resource<Document>("GCP.Firestore.Document");

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

const databaseIdOf = (value: string | undefined, project: string) => {
  if (value === undefined || value.length === 0) return DEFAULT_DATABASE;
  return parseDatabaseName(databaseNameOf(project, value)).databaseId;
};

const collectionOf = (value: string | undefined) =>
  value && value.length > 0 ? value : DEFAULT_COLLECTION;

const parentPathOf = (value: string | undefined) => (value ?? "").replace(/^\/+|\/+$/g, "");

const documentsParent = (databaseName: string, parentPath: string) =>
  parentPath.length === 0 ? `${databaseName}/documents` : `${databaseName}/documents/${parentPath}`;

const documentName = (
  databaseName: string,
  parentPath: string,
  collectionId: string,
  documentId: string,
) => `${documentsParent(databaseName, parentPath)}/${collectionId}/${documentId}`;

const parseDocumentName = (name: string) => {
  const marker = "/documents/";
  const at = name.indexOf(marker);
  const databaseName = at >= 0 ? name.slice(0, at) : name;
  const relative = at >= 0 ? name.slice(at + marker.length) : lastSegment(name);
  const parts = relative.split("/").filter((part) => part.length > 0);
  const documentId = parts[parts.length - 1] ?? "";
  const collectionId = parts.length >= 2 ? parts[parts.length - 2]! : DEFAULT_COLLECTION;
  const parentParts = parts.slice(0, Math.max(0, parts.length - 2));
  return {
    ...parseDatabaseName(databaseName),
    databaseName,
    documentPath: relative,
    documentId,
    collectionId,
    parentPath: parentParts.join("/"),
  };
};

const fieldOf = (value: firestore.Value | undefined): DocumentFieldValue => ({
  stringValue: value?.stringValue,
  integerValue: value?.integerValue,
  booleanValue: value?.booleanValue,
  doubleValue: value?.doubleValue,
  timestampValue: value?.timestampValue,
  nullValue: value?.nullValue,
});

const userFields = (fields: firestore.ValueMap | undefined): Record<string, DocumentFieldValue> => {
  const next: Record<string, DocumentFieldValue> = {};
  for (const [key, value] of Object.entries(fields ?? {})) {
    next[key] = fieldOf(value);
  }
  return next;
};

const desiredFields = (news: DocumentProps): firestore.ValueMap => ({
  ...news.fields,
});

const jsonOf = (value: unknown) => JSON.stringify(value ?? null);

const toAttrs = (current: firestore.Document, project: string) => {
  const name = current.name ?? "";
  const parsed = parseDocumentName(name);
  return {
    name,
    documentId: parsed.documentId,
    database: parsed.databaseName,
    databaseId: parsed.databaseId,
    collectionId: parsed.collectionId,
    parentPath: parsed.parentPath,
    documentPath: parsed.documentPath,
    project: parsed.project || project,
    fields: userFields(current.fields),
    createTime: current.createTime,
    updateTime: current.updateTime,
  };
};

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

export const DocumentProvider = () =>
  Provider.succeed(Document, {
    stables: [
      "name",
      "documentId",
      "database",
      "databaseId",
      "collectionId",
      "parentPath",
      "documentPath",
      "project",
      "createTime",
    ],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const previousDatabase = olds?.database ?? output?.databaseId;
      const previousCollection = olds?.collectionId ?? output?.collectionId;
      const previousParent = olds?.parentPath ?? output?.parentPath;
      const previousId = olds?.documentId ?? output?.documentId;
      if (
        (previousDatabase !== undefined &&
          news.database !== undefined &&
          news.database !== previousDatabase) ||
        (previousCollection !== undefined &&
          news.collectionId !== undefined &&
          news.collectionId !== previousCollection) ||
        (previousParent !== undefined &&
          news.parentPath !== undefined &&
          parentPathOf(news.parentPath) !== parentPathOf(previousParent)) ||
        (previousId !== undefined &&
          news.documentId !== undefined &&
          news.documentId !== previousId)
      ) {
        return { action: "replace" as const, deleteFirst: true };
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, olds, output, previous }) {
      const env = yield* GcpEnvironment.current;
      const databaseId = databaseIdOf(
        olds?.database ?? output?.database ?? output?.databaseId,
        env.project,
      );
      const databaseName = databaseNameOf(env.project, databaseId);
      const collectionId = collectionOf(olds?.collectionId ?? output?.collectionId);
      const parentPath = parentPathOf(olds?.parentPath ?? output?.parentPath);
      const documentId = yield* toResourceId(id, olds?.documentId, output?.documentId);
      const name = output?.name ?? documentName(databaseName, parentPath, collectionId, documentId);
      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 : unownedUnlessPrevious(attrs, previous, "name");
    }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const databaseId = databaseIdOf(
        news.database ?? output?.database ?? output?.databaseId,
        env.project,
      );
      const databaseName = databaseNameOf(env.project, databaseId);
      const collectionId = collectionOf(news.collectionId);
      const parentPath = parentPathOf(news.parentPath);
      const documentId = yield* toResourceId(id, news.documentId, output?.documentId);
      const parent = documentsParent(databaseName, parentPath);
      const name = documentName(databaseName, parentPath, collectionId, documentId);
      const fields = desiredFields(news);

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

      if (current === undefined) {
        const created = yield* firestore
          .createDocumentProjectsDatabasesDocuments({
            parent,
            collectionId,
            documentId,
            body: { fields },
          })
          .pipe(Effect.catchTag("Conflict", () => getByName(name)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new DocumentNotResolved({ resourceName: name });
      }

      if (jsonOf(current.fields) !== jsonOf(fields)) {
        current = yield* firestore.patchProjectsDatabasesDocuments({
          name: current.name ?? name,
          // Masking observed fields too removes the ones no longer desired.
          "updateMask.fieldPaths": Object.keys({
            ...current.fields,
            ...fields,
          }),
          body: { fields },
        });
      }

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

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