sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ KV/ InstantNamespace.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 type { Providers } from "../Providers.ts";
import {
  createInstantNamespaceLocalId,
  isInstantNamespaceLocalId,
} from "./InstantNamespaceLocal.ts";
import { NamespaceModeMismatch } from "./NamespaceTypes.ts";

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

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

export type InstantNamespace = Resource<
  "Cloudflare.KV.InstantNamespace",
  InstantNamespaceProps,
  {
    /** Namespace storage mode, fixed at creation. */
    mode: "instant";
    /** Human-readable namespace title. */
    title: string;
    /** Cloudflare namespace identifier, stable across title updates. */
    namespaceId: string;
    /** Whether keys written in URLs are URL-decoded before storage. */
    supportsUrlEncoding: boolean | undefined;
    /** Account that owns the namespace. */
    accountId: string;
  },
  never,
  Providers
>;

/**
 * A Cloudflare Workers KV Instant namespace, powered by Quicksilver.
 *
 * Requires private beta access. Uses the same Worker binding as classic KV,
 * with fast global replication and no cold reads. Namespace mode is fixed at
 * creation; switching between Namespace and InstantNamespace replaces it.
 *
 * Metadata is unsupported. Use get instead of getWithMetadata, and do not
 * pass metadata to put. Listing returns all matching keys without pagination.
 * The beta limits namespaces to 1 MB and 10,000 pairs, keys to 300 bytes,
 * and writes to one per namespace per second.
 *
 * Storage and put/delete/list operations cost substantially more than classic
 * KV; reads cost less. See https://blog.cloudflare.com/workers-kv-instant/
 * for pricing and private beta availability.
 *
 * ### Creating an Instant Namespace
 * **Example:** Application configuration
 * ```typescript
 * const config = yield* Cloudflare.KV.InstantNamespace("Config");
 * ```
 *
 * ### Binding to a Worker
 * **Example:** Read configuration using the existing KV binding
 * ```typescript
 * const client = yield* Cloudflare.KV.ReadNamespace(config);
 * const enabled = yield* client.get("feature-enabled");
 * ```
 *
 * Provide ReadNamespaceBinding on the Worker runtime. WriteNamespace and
 * ReadWriteNamespace also accept Instant namespaces, as do their Http and
 * Local capability implementations.
 *
 * During `alchemy dev`, the namespace uses persistent local KV storage without
 * cloud credentials or beta access. Local mode rejects metadata and lists all
 * matching keys in one response. Local keys are limited to 300 UTF-8 bytes.
 * Namespace storage quotas, key-count limits, global replication, billing,
 * and write throttling are not emulated. Use Alchemy.remote()
 * to opt into a live namespace during development (requires beta access).
 *
 * @resource
 * @product KV
 * @category Storage & Databases
 */
export const InstantNamespace = Resource<InstantNamespace>("Cloudflare.KV.InstantNamespace");

const ProviderLive = () =>
  Provider.succeed(InstantNamespace, {
    stables: ["namespaceId", "accountId"],
    diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (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 = news.title ?? output?.title ?? (yield* createTitle(id, undefined));
      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;
            mode?: "instant" | null;
          }
        | 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,
            mode: "instant",
          })
          .pipe(
            Effect.catchTag("NamespaceTitleAlreadyExists", (error) =>
              Effect.gen(function* () {
                const match = yield* findNamespaceByTitle(title);
                if (match) {
                  return match;
                }
                return yield* error;
              }),
            ),
          );
      }

      if (observed.mode !== "instant") {
        return yield* new NamespaceModeMismatch({ namespaceId: observed.id, expected: "instant" });
      }

      // 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 {
        mode: "instant" as const,
        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) => ({
                mode: "instant" as const,
                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.flatMap((namespace) =>
              namespace.mode !== "instant"
                ? Effect.fail(
                    new NamespaceModeMismatch({ namespaceId: namespace.id, expected: "instant" }),
                  )
                : Effect.succeed({
                    mode: "instant" as const,
                    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 {
          mode: "instant" as const,
          title: match.title,
          namespaceId: match.id,
          supportsUrlEncoding: match.supportsUrlEncoding ?? undefined,
          accountId,
        };
      }
      return undefined;
    }),
  });

/** Persistent local workerd namespace; no Cloudflare API calls. */
const ProviderLocal = () =>
  Provider.succeed(InstantNamespace, {
    stables: ["namespaceId", "accountId"],
    diff: Effect.fn(function* ({ output }) {
      const accountId = yield* localAccountId;
      if (output && !isInstantNamespaceLocalId(output.namespaceId)) {
        return { action: "replace" } as const;
      }
      if (output && output.accountId !== accountId) return { action: "replace" } as const;
    }),
    read: Effect.fn(function* ({ output }) {
      return output ?? undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news = {}, output }) {
      const accountId = yield* localAccountId;
      return {
        mode: "instant" as const,
        title: news.title ?? output?.title ?? (yield* createTitle(id, undefined)),
        namespaceId: output?.namespaceId ?? createInstantNamespaceLocalId(),
        supportsUrlEncoding: true,
        accountId: output?.accountId ?? accountId,
      };
    }),
    delete: Effect.fn(function* () {
      // Matches classic local KV: orphaned storage is reclaimed with .alchemy.
    }),
  });

export const InstantNamespaceProvider = () =>
  ProviderLayer.dual(InstantNamespace, {
    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),
  );
});