sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ State/ Tree.ts

import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import { State, type StateService, type StateStoreError } from "./State.ts";
import { encodeState } from "./StateEncoding.ts";

// The store viewed as a filesystem: `stack/stage/fqn` for a resource record,
// `stack/stage/output` for a stage's outputs. Everything here addresses that
// tree by slash-separated path, so a CLI or an RPC client can walk state
// without knowing the backend's key layout.

/** Reading or listing a path. Omit `path` for the root. */
export interface TreeQuery {
  readonly path?: string;
  /** Recurse into every descendant instead of stopping at immediate children. */
  readonly recursive?: boolean;
}

/** Deleting a path. The path is required — the root is not deletable. */
export interface TreeDelete {
  readonly path: string;
  /** Delete every descendant when the path identifies a directory. */
  readonly recursive?: boolean;
}

/** One decoded record produced by {@link readState}. */
export interface StateEntry {
  readonly path: string;
  readonly kind: "resource" | "output";
  readonly value: unknown;
}

/** The path does not exist, or does not support the requested operation. */
export class InvalidStatePath extends Data.TaggedError("InvalidStatePath")<{
  readonly path: string;
  readonly reason: string;
}> {}

export interface StateDeleted {
  readonly _tag: "StateDeleted";
  readonly path: string;
  readonly deleted: ReadonlyArray<string>;
}

/**
 * Every `(stack, stage)` pair the store holds, or the subset a filter pins.
 *
 * Enumerating them means `listStacks` then a `listStages` per stack, so the
 * fan-out runs concurrently: against a remote store a serial walk is one
 * round trip per stack before the first stage is even known. A pinned
 * `stack`/`stage` is taken at face value and skips the corresponding call —
 * naming a scope is not a claim that it exists, and callers report a missing
 * one from the emptiness of what comes back.
 *
 * Ordered by stack then stage so every traversal built on it is deterministic.
 */
export const allStages = Effect.fn("allStages")(function* (
  filter: { readonly stack?: string; readonly stage?: string } = {},
) {
  return yield* stagesOf(yield* yield* State, filter);
});

const stagesOf = (
  state: StateService,
  filter: { readonly stack?: string; readonly stage?: string },
): Effect.Effect<
  ReadonlyArray<{ readonly stack: string; readonly stage: string }>,
  StateStoreError
> =>
  Effect.gen(function* () {
    const stacks =
      filter.stack !== undefined ? [filter.stack] : [...(yield* state.listStacks())].sort();
    if (filter.stage !== undefined) {
      const stage = filter.stage;
      return stacks.map((stack) => ({ stack, stage }));
    }
    const perStack = yield* Effect.forEach(
      stacks,
      (stack) =>
        Effect.map(state.listStages(stack), (stages) =>
          [...stages].sort().map((stage) => ({ stack, stage })),
        ),
      { concurrency: "unbounded" },
    );
    return perStack.flat();
  });

type StateFile =
  | {
      readonly kind: "resource";
      readonly path: string;
      readonly stack: string;
      readonly stage: string;
      readonly fqn: string;
    }
  | {
      readonly kind: "output";
      readonly path: string;
      readonly stack: string;
      readonly stage: string;
    };

const pathParts = (path: string | undefined): ReadonlyArray<string> =>
  (path ?? "").split("/").filter((part) => part !== "" && part !== ".");

const invalidPath = (path: string, reason = "path does not exist") =>
  Effect.fail(new InvalidStatePath({ path, reason }));

const parsePath = (path: string | undefined) => {
  const parts = pathParts(path);
  return parts.includes("..")
    ? invalidPath(path ?? "/", "parent path segments are not allowed")
    : Effect.succeed(parts);
};

const stageFiles = Effect.fn(function* (state: StateService, stack: string, stage: string) {
  const fqns = yield* state.list({ stack, stage });
  return [
    ...fqns.map((fqn): StateFile => ({
      kind: "resource",
      path: `${stack}/${stage}/${fqn}`,
      stack,
      stage,
      fqn,
    })),
    {
      kind: "output",
      path: `${stack}/${stage}/output`,
      stack,
      stage,
    } as const,
  ];
});

/** Every file under the given scope, listed one stage at a time in parallel. */
const filesUnder = Effect.fn(function* (
  state: StateService,
  filter: { readonly stack?: string } = {},
) {
  const stages = yield* stagesOf(state, filter);
  const perStage = yield* Effect.forEach(
    stages,
    ({ stack, stage }) => stageFiles(state, stack, stage),
    { concurrency: "unbounded" },
  );
  return perStage.flat();
});

const filesAt = Effect.fn(function* (state: StateService, parts: ReadonlyArray<string>) {
  const path = parts.join("/");
  if (parts.length === 0) {
    return { directory: true as const, files: yield* filesUnder(state) };
  }
  if (parts.length === 1) {
    const stack = parts[0]!;
    if (!(yield* state.listStacks()).includes(stack)) {
      return yield* invalidPath(path);
    }
    return {
      directory: true as const,
      files: yield* filesUnder(state, { stack }),
    };
  }
  if (parts.length === 2) {
    const [stack, stage] = parts as [string, string];
    if (!(yield* state.listStages(stack)).includes(stage)) {
      return yield* invalidPath(path);
    }
    return {
      directory: true as const,
      files: yield* stageFiles(state, stack, stage),
    };
  }
  const files = yield* stageFiles(state, parts[0]!, parts[1]!);
  const exact = files.find((file) => file.path === path);
  if (exact !== undefined) return { directory: false as const, files: [exact] };
  const descendants = files.filter((file) => file.path.startsWith(`${path}/`));
  if (descendants.length === 0) return yield* invalidPath(path);
  return { directory: true as const, files: descendants };
});

export const listState = Effect.fn("listState")(function* ({ path, recursive = false }: TreeQuery) {
  const state = yield* yield* State;
  const parts = yield* parsePath(path);
  const normalizedPath = parts.join("/");
  if (parts.length === 0 && !recursive) {
    return (yield* state.listStacks()).map((stack) => `${stack}/`);
  }
  const { directory, files } = yield* filesAt(state, parts);
  if (!directory) return [normalizedPath];
  const prefix = normalizedPath === "" ? "" : `${normalizedPath}/`;
  if (recursive) return files.map((file) => file.path);
  return [
    ...new Set(
      files.map((file) => {
        const rest = file.path.slice(prefix.length);
        const child = rest.split("/")[0]!;
        return rest.includes("/") ? `${prefix}${child}/` : file.path;
      }),
    ),
  ];
});

export const readState = Effect.fn("readState")(function* ({ path, recursive = false }: TreeQuery) {
  const state = yield* yield* State;
  const parts = yield* parsePath(path);
  const target = yield* filesAt(state, parts);
  if (target.directory && !recursive) {
    return yield* invalidPath(
      path ?? "/",
      "path is a directory; set recursive to read its descendants",
    );
  }
  return yield* Effect.forEach(target.files, (file) =>
    (file.kind === "output" ? state.getOutput(file) : state.get(file)).pipe(
      Effect.map((value): StateEntry => ({
        path: file.path,
        kind: file.kind,
        value: encodeState(value) ?? null,
      })),
    ),
  );
});

export const deleteState = Effect.fn("deleteState")(function* ({
  path,
  recursive = false,
}: TreeDelete) {
  const state = yield* yield* State;
  const parts = yield* parsePath(path);
  if (parts.length === 0) {
    return yield* invalidPath(path, "the state root cannot be deleted");
  }
  const target = yield* filesAt(state, parts);
  if (target.directory && !recursive) {
    return yield* invalidPath(path, "path is a directory; set recursive to delete its descendants");
  }
  if (parts.length === 1) {
    yield* state.deleteStack({ stack: parts[0]! });
  } else if (parts.length === 2) {
    yield* state.deleteStack({ stack: parts[0]!, stage: parts[1]! });
  } else {
    const resources = target.files.filter(
      (file): file is Extract<StateFile, { kind: "resource" }> => file.kind === "resource",
    );
    if (resources.length === 0) {
      return yield* invalidPath(path, "output cannot be deleted independently");
    }
    yield* Effect.forEach(resources, (file) => state.delete(file), {
      concurrency: 32,
      discard: true,
    });
  }
  return {
    _tag: "StateDeleted" as const,
    path: parts.join("/"),
    deleted: target.files.map((file) => file.path),
  };
});