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

import { Stack } from "alchemy/Stack";
import { Stage } from "alchemy/Stage";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";

type NamespaceTypeId = typeof NamespaceTypeId;
const NamespaceTypeId = "Cloudflare.Artifacts.Namespace" as const;

/**
 * Cloudflare validation: 2–63 chars, starting with a letter or digit, followed
 * by letters, digits, `.`, `_`, or `-`. See
 * https://developers.cloudflare.com/artifacts/platform/limits/.
 */
const ARTIFACTS_NAMESPACE_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]{1,62}$/;

export class InvalidNamespaceError extends Data.TaggedError("InvalidNamespaceError")<{
  readonly namespace: string;
}> {
  override get message() {
    return `Invalid artifacts namespace name '${this.namespace}'. Must be 2-63 characters, start with a letter or digit, and contain only letters, digits, ".", "_", and "-".`;
  }
}

export type NamespaceProps = {
  /**
   * Cloudflare namespace name. The first repo created against a name that
   * does not exist yet creates the namespace.
   *
   * Must be 2–63 characters, start with a letter or digit, and contain only
   * letters, digits, `.`, `_`, or `-`. If omitted, the lowercased logical id
   * is used.
   */
  namespace?: string;
};

/**
 * Marker for a Cloudflare Artifacts namespace binding.
 *
 * Artifacts namespaces are implicit (created on first repo write) and require
 * no deploy-time provisioning, so this is a pure binding marker rather than
 * a full Resource. The Worker provider sees this object in `bindings: { ... }`
 * and emits the corresponding `{ type: "artifacts", name, namespace }` binding
 * to the script.
 */
export type Namespace = {
  kind: NamespaceTypeId;
  name: string;
  namespace: string;
};

export const isNamespace = (value: unknown): value is Namespace =>
  typeof value === "object" &&
  value !== null &&
  "kind" in value &&
  (value as Namespace).kind === NamespaceTypeId;

/**
 * A Cloudflare Artifacts namespace — the top-level container for Git-compatible
 * versioned repositories. See the
 * {@link https://blog.cloudflare.com/artifacts-git-for-agents-beta/ | Artifacts launch post}
 * and {@link https://developers.cloudflare.com/artifacts/concepts/namespaces/ | Namespaces docs}.
 *
 * Cloudflare creates a namespace implicitly the first time a repo is created
 * against it (through the REST API or the Worker binding), so the Alchemy
 * "resource" is a thin binding marker with nothing to provision at deploy
 * time. Cloudflare also offers an explicit `POST /artifacts/namespaces` route,
 * needed only to pin a data-location `jurisdiction`; this marker does not
 * call it. Repos themselves are typically created at runtime through
 * the bound `Artifacts` API.
 *
 * Unlike the other Worker-only bindings, an Artifacts namespace does **not**
 * auto-bind when yielded — it always requires an explicit access level via
 * {@link ReadNamespace} / {@link WriteNamespace} / {@link ReadWriteNamespace}.
 *
 * ### Declaring a Namespace
 * **Example:** Default namespace (a unique physical name is generated)
 * ```typescript
 * const Repos = Cloudflare.Artifacts.Namespace("Repos");
 * ```
 *
 * **Example:** Override the namespace name (2–63 chars)
 * ```typescript
 * const Repos = Cloudflare.Artifacts.Namespace("Repos", { namespace: "starter-repos" });
 * ```
 *
 * ### Binding to a Worker
 * **Example:** Wiring it into a Worker
 * ```typescript
 * export const Worker = Cloudflare.Worker("Worker", {
 *   main: "./src/worker.ts",
 *   bindings: { Repos },
 * });
 *
 * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
 * //   { Repos: Artifacts }
 * ```
 *
 * **Example:** Async-style worker
 * ```typescript
 * export default {
 *   async fetch(request: Request, env: WorkerEnv) {
 *     const repo = await env.Repos.create("starter-repo");
 *     return Response.json({ remote: repo.remote, token: repo.token });
 *   },
 * };
 * ```
 *
 * **Example:** Effect-style worker (explicit access level)
 * ```typescript
 * const artifacts = yield* Cloudflare.Artifacts.ReadWriteNamespace(Repos);
 * const repo = yield* artifacts.create("starter-repo", {
 *   setDefaultBranch: "main",
 * });
 * ```
 *
 * **Example:** Effect-style worker reading history (read-only access)
 * ```typescript
 * const artifacts = yield* Cloudflare.Artifacts.ReadNamespace(Repos);
 * const repo = yield* artifacts.get("starter-repo");
 * const commits = yield* repo.log({ ref: "main", limit: 10 });
 * const readme = yield* repo.readFile({ ref: "main", path: "README.md" });
 * ```
 *
 * @binding
 * @product Artifacts
 * @category Developer Platform
 */
export const Namespace: (
  name: string,
  props?: NamespaceProps,
) => Effect.Effect<Namespace, never, Stack | Stage> = Effect.fn(function* (
  name: string,
  props?: NamespaceProps,
) {
  const namespace = props?.namespace ? props.namespace : name.toLocaleLowerCase();
  if (!ARTIFACTS_NAMESPACE_REGEX.test(namespace)) {
    return yield* Effect.die(new InvalidNamespaceError({ namespace }));
  }
  return {
    kind: NamespaceTypeId,
    name,
    namespace,
  } satisfies Namespace;
});