sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ KV/ Namespace.ts

import * as kv from "@distilled.cloud/cloudflare/kv";
import { isResolved } from "alchemy/Diff";
import * as ProviderLayer from "alchemy/Local/ProviderLayer";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import { localAccountId } from "../LocalAccount.ts";
import { generateLocalId } from "../LocalRuntime.ts";
import type { Providers } from "../Providers.ts";
import { isInstantNamespaceLocalId } from "./InstantNamespaceLocal.ts";

export const isNamespace = (value: unknown): value is Namespace =>
  isResourceOfType(value, "Cloudflare.KV.Namespace");

export type NamespaceProps = {
  /**
   * A human-readable string name for the namespace.
   * If omitted, a unique name will be generated.
   * @default ${app}-${stage}-${id}
   */
  title?: string;
};

export type Namespace = Resource<
  "Cloudflare.KV.Namespace",
  NamespaceProps,
  {
    title: string;
    namespaceId: string;
    supportsUrlEncoding: boolean | undefined;
    accountId: string;
  },
  never,
  Providers
>;

/**
 * A Cloudflare Workers KV namespace for key-value storage at the edge.
 *
 * KV provides eventually-consistent, low-latency reads with global
 * replication. Create a namespace as a resource, then bind it to a Worker
 * to get/put values at runtime.
 * ### Creating a Namespace
 * **Example:** Basic KV namespace
 * ```typescript
 * const kv = yield* Cloudflare.KV.Namespace("MyKV");
 * ```
 *
 * ### Binding to a Worker
 * **Example:** Using KV inside a Worker
 * ```typescript
 * const kv = yield* Cloudflare.KV.ReadWriteNamespace(MyKV);
 *
 * // Read a value
 * const value = yield* kv.get("my-key");
 *
 * // Write a value
 * yield* kv.put("my-key", "hello world");
 * ```
 *
 * Provide `Cloudflare.KV.ReadWriteNamespaceBinding` (native Worker
 * binding) or `Cloudflare.KV.ReadWriteNamespaceHttp` (scoped HTTP
 * token) in the worker's runtime layer. Use `Cloudflare.KV.ReadNamespace`
 * / `Cloudflare.KV.WriteNamespace` for least-privilege read- or
 * write-only access.
 *
 * @resource
 * @product KV
 * @category Storage & Databases
 */
export const Namespace = Resource<Namespace>("Cloudflare.KV.Namespace", {
  aliases: ["Cloudflare.KVNamespace"],
});

export const ProviderLive = () =>
  Provider.succeed(Namespace, {
    stables: ["namespaceId", "accountId"],
    diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output && "mode" in output && output.mode === "instant") {
        return {
          action: "replace",
          // Titles are unique across modes; an unresolved title may also reuse it.
          deleteFirst: !isResolved(news) || news.title === output.title,
        } as const;
      }
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      const oldTitle = output?.title ?? (yield* createTitle(id, olds.title));
      // Auto-generated titles are engine-owned: the deployed title stays
      // authoritative even if the generator would title this id differently
      // today. Only an explicit user-provided title can force a rename.
      const title = news.title ?? oldTitle;
      if (title !== oldTitle) {
        return { action: "update" } as const;
      }
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const title = yield* createTitle(id, news.title);
      const acct = output?.accountId ?? accountId;

      // Observe — re-fetch the cached namespace; fall back to a title
      // scan so we recover from out-of-band deletes or partial state
      // persistence failures.
      let observed:
        | {
            id: string;
            title: string;
            supportsUrlEncoding?: boolean | null | undefined;
          }
        | undefined;
      if (output?.namespaceId) {
        observed = yield* kv
          .getNamespace({
            accountId: acct,
            namespaceId: output.namespaceId,
          })
          .pipe(Effect.catchTag("NamespaceNotFound", () => Effect.undefined));
      }

      // Ensure — create if missing. Cloudflare returns
      // `NamespaceTitleAlreadyExists` on a concurrent create; tolerate
      // by adopting the namespace with the same title.
      if (!observed) {
        observed = yield* kv
          .createNamespace({
            accountId: acct,
            title,
          })
          .pipe(
            Effect.catchTag("NamespaceTitleAlreadyExists", () =>
              Effect.gen(function* () {
                const match = yield* findNamespaceByTitle(title);
                if (match) {
                  return match;
                }
                return yield* Effect.die(
                  `Namespace with title "${title}" already exists but could not be found`,
                );
              }),
            ),
          );
      }

      // Sync — KV's only mutable property is the title. Rename only
      // when the observed title drifts from desired so we avoid
      // unnecessary API calls on every reconcile.
      let namespaceId = observed.id;
      let resolvedTitle = observed.title;
      let supportsUrlEncoding = observed.supportsUrlEncoding ?? undefined;
      if (observed.title !== title) {
        const renamed = yield* kv.updateNamespace({
          accountId: acct,
          namespaceId: observed.id,
          title,
        });
        namespaceId = renamed.id;
        resolvedTitle = renamed.title;
        supportsUrlEncoding = renamed.supportsUrlEncoding ?? undefined;
      }

      return {
        title: resolvedTitle,
        namespaceId,
        supportsUrlEncoding,
        accountId: acct,
      };
    }),
    delete: Effect.fn(function* ({ output }) {
      yield* kv
        .deleteNamespace({
          accountId: output.accountId,
          namespaceId: output.namespaceId,
        })
        .pipe(Effect.catchTag("NamespaceNotFound", () => Effect.void));
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* kv.listNamespaces.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? [])
              .filter((ns) => ns.mode !== "instant")
              .map((ns) => ({
                title: ns.title,
                namespaceId: ns.id,
                supportsUrlEncoding: ns.supportsUrlEncoding ?? undefined,
                accountId,
              })),
          ),
        ),
      );
    }),
    read: Effect.fn(function* ({ id, olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (output?.namespaceId) {
        return yield* kv
          .getNamespace({
            accountId: output.accountId,
            namespaceId: output.namespaceId,
          })
          .pipe(
            Effect.map((namespace) => ({
              title: namespace.title,
              namespaceId: namespace.id,
              supportsUrlEncoding: namespace.supportsUrlEncoding ?? undefined,
              accountId: output.accountId,
            })),
            Effect.catchTag("NamespaceNotFound", () => Effect.undefined),
          );
      }
      const title = yield* createTitle(id, olds?.title);
      const match = yield* findNamespaceByTitle(title);
      if (match) {
        return {
          title: match.title,
          namespaceId: match.id,
          supportsUrlEncoding: match.supportsUrlEncoding ?? undefined,
          accountId,
        };
      }
      return undefined;
    }),
  });

/**
 * Local (dev) provider — the namespace is purely virtual: a `dev:` id keyed
 * into the local workerd KV simulator. `toRuntimeBinding` lowers a
 * `kv_namespace` binding whose id is `dev:`-prefixed onto the local KV
 * service; data persists under `.alchemy/local/kv`.
 */
export const ProviderLocal = () =>
  Provider.succeed(Namespace, {
    stables: ["accountId"],
    diff: Effect.fn(function* ({ news = {}, output }) {
      const accountId = yield* localAccountId;
      if (!output?.namespaceId) return { action: "update" } as const;
      if (isInstantNamespaceLocalId(output.namespaceId)) return { action: "replace" } as const;
      if (!isResolved(news)) return undefined;
      if (output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      // Fall through to the engine's default prop diff (title renames
      // update in place).
    }),
    read: Effect.fn(function* ({ output }) {
      // Purely virtual — the persisted state row is the source of truth.
      return output ?? undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
      const accountId = yield* localAccountId;
      return {
        title: yield* createTitle(id, news.title),
        namespaceId: output?.namespaceId ?? generateLocalId(),
        supportsUrlEncoding: true,
        accountId: output?.accountId ?? accountId,
      };
    }),
    delete: Effect.fn(function* () {
      // The simulator's on-disk data is keyed by the dev id; dropping the
      // state row is enough — orphaned blobs are reclaimed with `.alchemy`.
    }),
  });

export const NamespaceProvider = () =>
  ProviderLayer.dual(Namespace, {
    local: () => ProviderLocal(),
    live: () => ProviderLive(),
  });

const createTitle = (id: string, title: string | undefined) =>
  Effect.gen(function* () {
    return title ?? (yield* createPhysicalName({ id }));
  });

// Cloudflare's `listNamespaces` accepts no title/prefix filter, so
// adoption-by-name has to scan every page. Use the paginated
// `.items` stream off the un-yielded operation method (yielding
// `kv.listNamespaces` collapses it to a single-page call).
const findNamespaceByTitle = Effect.fn(function* (title: string) {
  const { accountId } = yield* yield* CloudflareEnvironment;
  return yield* kv.listNamespaces.items({ accountId }).pipe(
    Stream.filter((ns) => ns.title === title && ns.mode !== "instant"),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );
});