@sanity/workbench 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/core/projects.test.ts

@@ -0,0 +1,248 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+
+import { brandOrganizationId } from "./organizations";
+import type { OrganizationId } from "./organizations";
+import type { Project, ProjectId, ProjectMember } from "./projects";
+import { brandProjectId, parseProject } from "./projects";
+
+describe("Project type", () => {
+  it("includes members and features by default", () => {
+    expectTypeOf<Project>().toHaveProperty("members");
+    expectTypeOf<Project>().toHaveProperty("features");
+  });
+
+  it("excludes members when IncludeMembers is false", () => {
+    expectTypeOf<Project<false>>().toHaveProperty("features");
+    expectTypeOf<
+      "members" extends keyof Project<false> ? true : false
+    >().toEqualTypeOf<false>();
+  });
+
+  it("excludes features when IncludeFeatures is false", () => {
+    expectTypeOf<Project<true, false>>().toHaveProperty("members");
+    expectTypeOf<
+      "features" extends keyof Project<true, false> ? true : false
+    >().toEqualTypeOf<false>();
+  });
+
+  it("excludes both when both are false", () => {
+    expectTypeOf<
+      "members" extends keyof Project<false, false> ? true : false
+    >().toEqualTypeOf<false>();
+    expectTypeOf<
+      "features" extends keyof Project<false, false> ? true : false
+    >().toEqualTypeOf<false>();
+  });
+
+  it("always includes base properties", () => {
+    expectTypeOf<Project>().toHaveProperty("id");
+    expectTypeOf<Project>().toHaveProperty("displayName");
+    expectTypeOf<Project>().toHaveProperty("organizationId");
+
+    expectTypeOf<Project<false, false>>().toHaveProperty("id");
+    expectTypeOf<Project<false, false>>().toHaveProperty("displayName");
+    expectTypeOf<Project<false, false>>().toHaveProperty("organizationId");
+  });
+
+  it("has branded id and organizationId types", () => {
+    expectTypeOf<Project["id"]>().toEqualTypeOf<ProjectId>();
+    expectTypeOf<Project["organizationId"]>().toEqualTypeOf<OrganizationId>();
+  });
+});
+
+describe("brandProjectId", () => {
+  it("brands a valid project id", () => {
+    const id = brandProjectId("abc123");
+    expect(id).toBe("abc123");
+    expectTypeOf(id).toEqualTypeOf<ProjectId>();
+  });
+
+  it("rejects an empty string", () => {
+    expect(() => brandProjectId("")).toThrow();
+  });
+
+  it("is not assignable from a plain string", () => {
+    expectTypeOf<ProjectId>().branded.toEqualTypeOf<ProjectId>();
+  });
+
+  it("is not assignable from OrganizationId", () => {
+    expectTypeOf<
+      OrganizationId extends ProjectId ? true : false
+    >().toEqualTypeOf<false>();
+  });
+});
+
+describe("parseProject", () => {
+  const VALID_PROJECT = {
+    id: "proj123",
+    displayName: "My Project",
+    studioHost: "my-project",
+    organizationId: brandOrganizationId("org123"),
+    metadata: {
+      integration: "cli",
+      color: "#ff0000",
+      initialTemplate: "blog",
+      cliInitializedAt: "2024-01-01T00:00:00Z",
+    },
+    isBlocked: false,
+    isDisabled: false,
+    isDisabledByUser: false,
+    activityFeedEnabled: true,
+    createdAt: "2024-01-01T00:00:00Z",
+    updatedAt: "2024-01-01T00:00:00Z",
+  };
+
+  const VALID_MEMBER = {
+    id: "member1",
+    createdAt: "2024-01-01T00:00:00Z",
+    updatedAt: "2024-01-01T00:00:00Z",
+    isCurrentUser: true,
+    isRobot: false,
+    roles: [{ name: "admin", title: "Admin", description: "Full access" }],
+  };
+
+  const VALID_PROJECT_FULL = {
+    ...VALID_PROJECT,
+    members: [VALID_MEMBER],
+    features: ["customDomain"],
+  };
+
+  it("parses a valid project with members and features by default", () => {
+    const project = parseProject(VALID_PROJECT_FULL);
+    expect(project.displayName).toBe("My Project");
+    expect(project.members).toHaveLength(1);
+    expect(project.features).toEqual(["customDomain"]);
+    expectTypeOf(project).toEqualTypeOf<Project>();
+    expectTypeOf(project.id).toEqualTypeOf<ProjectId>();
+    expectTypeOf(project.organizationId).toEqualTypeOf<OrganizationId>();
+  });
+
+  it("rejects missing required fields", () => {
+    expect(() => parseProject({ id: "proj123" })).toThrow();
+  });
+
+  it("rejects missing members by default", () => {
+    expect(() => parseProject(VALID_PROJECT)).toThrow();
+  });
+
+  it("strips unknown properties", () => {
+    const project = parseProject({
+      ...VALID_PROJECT_FULL,
+      unknownField: "should be stripped",
+    });
+    expect(project).not.toHaveProperty("unknownField");
+  });
+
+  it("parses without members when excluded", () => {
+    const project = parseProject(
+      { ...VALID_PROJECT, features: ["customDomain"] },
+      { includeMembers: false },
+    );
+    expect(project).not.toHaveProperty("members");
+    expect(project.features).toEqual(["customDomain"]);
+    expectTypeOf(project).toEqualTypeOf<Project<false>>();
+  });
+
+  it("parses without features when excluded", () => {
+    const project = parseProject(
+      { ...VALID_PROJECT, members: [VALID_MEMBER] },
+      { includeFeatures: false },
+    );
+    expect(project).not.toHaveProperty("features");
+    expect(project.members).toHaveLength(1);
+    expectTypeOf(project).toEqualTypeOf<Project<true, false>>();
+    expectTypeOf(project.members).toEqualTypeOf<ProjectMember[]>();
+  });
+
+  it("parses base only when both excluded", () => {
+    const project = parseProject(VALID_PROJECT, {
+      includeMembers: false,
+      includeFeatures: false,
+    });
+    expect(project).not.toHaveProperty("members");
+    expect(project).not.toHaveProperty("features");
+    expectTypeOf(project).toEqualTypeOf<Project<false, false>>();
+  });
+
+  it("parses with both members and features", () => {
+    const project = parseProject(VALID_PROJECT_FULL, {
+      includeMembers: true,
+      includeFeatures: true,
+    });
+    expect(project.members).toHaveLength(1);
+    expect(project.features).toEqual(["customDomain"]);
+    expectTypeOf(project).toEqualTypeOf<Project<true, true>>();
+  });
+
+  describe("metadata fields are optional", () => {
+    const BASE = {
+      ...VALID_PROJECT,
+      members: [VALID_MEMBER],
+      features: ["customDomain"],
+    };
+
+    it("parses with only the integration field", () => {
+      const project = parseProject({
+        ...BASE,
+        metadata: { integration: "cli" },
+      });
+      expect(project.metadata).toEqual({ integration: "cli" });
+    });
+
+    describe("metadata.integration", () => {
+      it('accepts "cli"', () => {
+        const project = parseProject({
+          ...BASE,
+          metadata: { integration: "cli" },
+        });
+        expect(project.metadata.integration).toBe("cli");
+      });
+
+      it('accepts "manage"', () => {
+        const project = parseProject({
+          ...BASE,
+          metadata: { integration: "manage" },
+        });
+        expect(project.metadata.integration).toBe("manage");
+      });
+
+      it("rejects an unknown value", () => {
+        expect(() =>
+          parseProject({
+            ...BASE,
+            metadata: { integration: "unknown" },
+          }),
+        ).toThrow();
+      });
+
+      it("rejects a missing integration field", () => {
+        expect(() =>
+          parseProject({ ...BASE, metadata: { color: "#ff0000" } }),
+        ).toThrow();
+      });
+    });
+
+    it("parses without metadata.color", () => {
+      const { color: _color, ...rest } = BASE.metadata;
+      const project = parseProject({ ...BASE, metadata: rest });
+      expect(project.metadata).not.toHaveProperty("color");
+    });
+
+    it("parses without metadata.externalStudioHost", () => {
+      const project = parseProject({ ...BASE, metadata: BASE.metadata });
+      expect(project.metadata).not.toHaveProperty("externalStudioHost");
+    });
+
+    it("parses without metadata.initialTemplate", () => {
+      const { initialTemplate: _initialTemplate, ...rest } = BASE.metadata;
+      const project = parseProject({ ...BASE, metadata: rest });
+      expect(project.metadata).not.toHaveProperty("initialTemplate");
+    });
+
+    it("parses without metadata.cliInitializedAt", () => {
+      const { cliInitializedAt: _cliInitializedAt, ...rest } = BASE.metadata;
+      const project = parseProject({ ...BASE, metadata: rest });
+      expect(project.metadata).not.toHaveProperty("cliInitializedAt");
+    });
+  });
+});

package/src/core/projects.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+
+import { OrganizationId } from "./organizations";
+
+/**
+ * Project ID schema, branded for type safety.
+ * @public
+ */
+export const ProjectId = z.string().nonempty().brand("ProjectId");
+
+/**
+ * Project ID type, branded for type safety.
+ * @public
+ */
+export type ProjectId = z.output<typeof ProjectId>;
+
+/**
+ * Validates and brands a string as a ProjectId.
+ * @public
+ */
+export function brandProjectId(id: string): ProjectId {
+  return ProjectId.parse(id);
+}
+
+const ProjectMember = z.object({
+  id: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  isCurrentUser: z.boolean(),
+  isRobot: z.boolean(),
+  roles: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string(),
+      description: z.string(),
+    }),
+  ),
+});
+
+/**
+ * @public
+ */
+export type ProjectMember = z.output<typeof ProjectMember>;
+
+/**
+ * Project schema — validates and brands API responses
+ * from the `/projects/:id` endpoint.
+ * @public
+ */
+export const Project = z.object({
+  id: ProjectId,
+  displayName: z.string(),
+  studioHost: z.string().nullable(),
+  organizationId: OrganizationId,
+  metadata: z.object({
+    color: z.string().optional(),
+    externalStudioHost: z.string().optional(),
+    initialTemplate: z.string().optional(),
+    cliInitializedAt: z.string().optional(),
+    integration: z.literal(["manage", "cli"]),
+  }),
+  isBlocked: z.boolean(),
+  isDisabled: z.boolean(),
+  isDisabledByUser: z.boolean(),
+  activityFeedEnabled: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Represents a Sanity project with optional members and
+ * features arrays depending on the generic parameters.
+ * By default, neither members nor features are included.
+ * - `Project` — base fields only (default)
+ * - `Project<true>` — includes `members`
+ * - `Project<true, true>` — includes both
+ * @public
+ */
+export type Project<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+> = z.output<typeof Project> &
+  (IncludeMembers extends true ? { members: ProjectMember[] } : unknown) &
+  (IncludeFeatures extends true ? { features: string[] } : unknown);
+
+/**
+ * Validates and parses a raw API response into a branded
+ * Project. The options control which schema is used —
+ * matching what the API returns based on query params.
+ * @public
+ */
+export function parseProject<
+  IncludeMembers extends boolean = true,
+  IncludeFeatures extends boolean = true,
+>(
+  data: unknown,
+  options?: {
+    includeMembers?: IncludeMembers;
+    includeFeatures?: IncludeFeatures;
+  },
+): Project<IncludeMembers, IncludeFeatures> {
+  const includeMembers = options?.includeMembers ?? true;
+  const includeFeatures = options?.includeFeatures ?? true;
+
+  const extensions = {
+    ...(includeMembers && { members: z.array(ProjectMember) }),
+    ...(includeFeatures && { features: z.array(z.string()) }),
+  };
+
+  const schema =
+    Object.keys(extensions).length > 0 ? Project.extend(extensions) : Project;
+
+  return schema.parse(data) as Project<IncludeMembers, IncludeFeatures>;
+}

package/src/core/shared/urls.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from "vitest";
+
+import { createPath, joinUrlPaths, normalizePath, parsePath } from "./urls";
+
+describe("joinUrlPaths", () => {
+  it("joins two simple segments", () => {
+    expect(joinUrlPaths("foo", "bar")).toBe("foo/bar");
+  });
+
+  it("handles trailing slash on first segment", () => {
+    expect(joinUrlPaths("foo/", "bar")).toBe("foo/bar");
+  });
+
+  it("handles leading slash on second segment", () => {
+    expect(joinUrlPaths("foo", "/bar")).toBe("foo/bar");
+  });
+
+  it("collapses double slashes at the join", () => {
+    expect(joinUrlPaths("foo/", "/bar")).toBe("foo/bar");
+  });
+
+  it("joins multiple segments", () => {
+    expect(joinUrlPaths("a", "b", "c")).toBe("a/b/c");
+  });
+
+  it("skips null and undefined values", () => {
+    expect(joinUrlPaths("a", null, undefined, "b")).toBe("a/b");
+  });
+
+  it("returns empty string for all nullish inputs", () => {
+    expect(joinUrlPaths(null, undefined)).toBe("");
+  });
+
+  it("returns empty string with no arguments", () => {
+    expect(joinUrlPaths()).toBe("");
+  });
+
+  it("returns single segment unchanged", () => {
+    expect(joinUrlPaths("foo")).toBe("foo");
+  });
+
+  it("extracts pathname from URL objects", () => {
+    const url = new URL("https://example.com/api");
+    expect(joinUrlPaths(url, "users")).toBe("/api/users");
+  });
+
+  it("handles URL object with trailing slash", () => {
+    const url = new URL("https://example.com/api/");
+    expect(joinUrlPaths(url, "users")).toBe("/api/users");
+  });
+
+  it("joins two URL objects", () => {
+    const a = new URL("https://example.com/api");
+    const b = new URL("https://example.com/v2");
+    expect(joinUrlPaths(a, b)).toBe("/api/v2");
+  });
+});
+
+describe("normalizePath", () => {
+  it("adds leading slash when missing", () => {
+    expect(normalizePath("foo")).toBe("/foo");
+  });
+
+  it("preserves existing leading slash", () => {
+    expect(normalizePath("/foo")).toBe("/foo");
+  });
+
+  it("removes trailing slash", () => {
+    expect(normalizePath("/foo/")).toBe("/foo");
+  });
+
+  it("preserves root path", () => {
+    expect(normalizePath("/")).toBe("/");
+  });
+
+  it("handles bare segment with trailing slash", () => {
+    expect(normalizePath("foo/")).toBe("/foo");
+  });
+
+  it("handles deeper paths", () => {
+    expect(normalizePath("/a/b/c/")).toBe("/a/b/c");
+  });
+});
+
+describe("parsePath", () => {
+  it("parses pathname only", () => {
+    expect(parsePath("/foo")).toEqual({ pathname: "/foo" });
+  });
+
+  it("parses pathname with search", () => {
+    expect(parsePath("/foo?bar=1")).toEqual({
+      pathname: "/foo",
+      search: "?bar=1",
+    });
+  });
+
+  it("parses pathname with hash", () => {
+    expect(parsePath("/foo#heading")).toEqual({
+      pathname: "/foo",
+      hash: "#heading",
+    });
+  });
+
+  it("parses pathname with search and hash", () => {
+    expect(parsePath("/foo?bar=1#heading")).toEqual({
+      pathname: "/foo",
+      search: "?bar=1",
+      hash: "#heading",
+    });
+  });
+
+  it("parses hash that appears before search in the string", () => {
+    expect(parsePath("/foo#heading?notSearch")).toEqual({
+      pathname: "/foo",
+      hash: "#heading?notSearch",
+    });
+  });
+
+  it("returns empty object for empty string", () => {
+    expect(parsePath("")).toEqual({});
+  });
+
+  it("parses search-only path", () => {
+    expect(parsePath("?q=1")).toEqual({ search: "?q=1" });
+  });
+
+  it("parses hash-only path", () => {
+    expect(parsePath("#top")).toEqual({ hash: "#top" });
+  });
+});
+
+describe("createPath", () => {
+  it("returns pathname only", () => {
+    expect(createPath({ pathname: "/foo" })).toBe("/foo");
+  });
+
+  it("appends search string", () => {
+    expect(createPath({ pathname: "/foo", search: "?bar=1" })).toBe(
+      "/foo?bar=1",
+    );
+  });
+
+  it("appends hash string", () => {
+    expect(createPath({ pathname: "/foo", hash: "#heading" })).toBe(
+      "/foo#heading",
+    );
+  });
+
+  it("appends both search and hash", () => {
+    expect(
+      createPath({
+        pathname: "/foo",
+        search: "?bar=1",
+        hash: "#heading",
+      }),
+    ).toBe("/foo?bar=1#heading");
+  });
+
+  it("adds ? prefix when search is missing it", () => {
+    expect(createPath({ pathname: "/foo", search: "bar=1" })).toBe(
+      "/foo?bar=1",
+    );
+  });
+
+  it("adds # prefix when hash is missing it", () => {
+    expect(createPath({ pathname: "/foo", hash: "heading" })).toBe(
+      "/foo#heading",
+    );
+  });
+
+  it("defaults pathname to /", () => {
+    expect(createPath({})).toBe("/");
+  });
+
+  it("ignores bare ? search", () => {
+    expect(createPath({ pathname: "/foo", search: "?" })).toBe("/foo");
+  });
+
+  it("ignores bare # hash", () => {
+    expect(createPath({ pathname: "/foo", hash: "#" })).toBe("/foo");
+  });
+});

package/src/core/shared/urls.ts

@@ -0,0 +1,128 @@
+/**
+ * Joins multiple path segments into a single path string.
+ * Handles null, undefined, and URL objects gracefully.
+ *
+ * @param paths - An array of path segments to join.
+ * @returns A single joined path string.
+ */
+export const joinUrlPaths = (
+  ...paths: Array<string | URL | null | undefined>
+): string => {
+  let nextPath = null;
+
+  const safeJoinSegments = (
+    segment1: string | null | undefined,
+    segment2: string | null | undefined,
+  ): string => {
+    if (!segment1) {
+      if (!segment2) {
+        return "";
+      }
+
+      return segment2;
+    }
+
+    if (!segment2) {
+      return segment1;
+    }
+
+    if (segment1.endsWith("/") && segment2.startsWith("/")) {
+      return segment1 + segment2.slice(1);
+    }
+
+    if (segment1.endsWith("/") || segment2.startsWith("/")) {
+      return segment1 + segment2;
+    }
+
+    return `${segment1}/${segment2}`;
+  };
+
+  const validPaths = paths.filter(
+    (path) => path !== null && path !== undefined,
+  );
+
+  for (const path of validPaths) {
+    nextPath = safeJoinSegments(
+      nextPath,
+      path instanceof URL ? path.pathname : path,
+    );
+  }
+
+  return nextPath ?? "";
+};
+
+/**
+ * Returns a normalized path by ensuring it starts with a single leading slash
+ * and does not end with a trailing slash (unless it's the root path).
+ */
+export function normalizePath(pathname: string): string {
+  if (!pathname.startsWith("/")) {
+    pathname = `/${pathname}`;
+  }
+
+  if (pathname !== "/" && pathname.endsWith("/")) {
+    pathname = pathname.slice(0, -1);
+  }
+
+  return pathname;
+}
+
+/**
+ * The pathname, search, and hash values of a URL.
+ */
+interface Path {
+  /**
+   * A URL pathname, beginning with a /.
+   */
+  pathname: string;
+  /**
+   * A URL search string, beginning with a ?.
+   */
+  search: string;
+  /**
+   * A URL fragment identifier, beginning with a #.
+   */
+  hash: string;
+}
+
+/**
+ * Parses a string URL path into its separate pathname, search, and hash components.
+ */
+export function parsePath(path: string): Partial<Path> {
+  let parsedPath: Partial<Path> = {};
+
+  if (path) {
+    let hashIndex = path.indexOf("#");
+    if (hashIndex >= 0) {
+      parsedPath.hash = path.substring(hashIndex);
+      path = path.substring(0, hashIndex);
+    }
+
+    let searchIndex = path.indexOf("?");
+    if (searchIndex >= 0) {
+      parsedPath.search = path.substring(searchIndex);
+      path = path.substring(0, searchIndex);
+    }
+
+    if (path) {
+      parsedPath.pathname = path;
+    }
+  }
+
+  return parsedPath;
+}
+
+/**
+ * Creates a string URL path from the given pathname, search, and hash components.
+ */
+export function createPath({
+  pathname = "/",
+  search = "",
+  hash = "",
+}: Partial<Path>) {
+  if (search && search !== "?")
+    pathname += search.charAt(0) === "?" ? search : `?${search}`;
+  if (hash && hash !== "#")
+    pathname += hash.charAt(0) === "#" ? hash : `#${hash}`;
+  return pathname;
+}