Merge pull request #37 from klmhyeonwoo/feature/utils-workspace-yeom

feat: copyToClipboard util function

Author: prgmr99

README.md

@@ -66,6 +66,7 @@ const notEmpty = commonUtil.isEmpty("hello"); // false
 const nullCheck = commonUtil.isNull(null); // true
 const notNull = commonUtil.isNull("hello"); // false
 await commonUtil.sleep(1000); // Pauses execution for 1 second
+const copied = await commonUtil.copyToClipboard("Hello, World!"); // true if successful
 
 // Cookie utilities
 cookieUtil.setCookie("theme", "dark");
@@ -110,6 +111,7 @@ const formattedPhone = formatUtil.formatPhoneNumber("01012345678"); // "010-1234
 - `isEmpty(value: unknown): boolean` - Checks if a value is empty (null, undefined, "", 0, [], {}, empty Set/Map, NaN, or invalid Date)
 - `isNull(value: unknown): value is null` - Type guard that checks if a value is null and narrows the type
 - `sleep(ms: number): Promise<void>` - Pauses execution for a specified number of milliseconds
+- `copyToClipboard(text: string): Promise<boolean>` - Copies text to the user's clipboard. Uses modern Clipboard API with fallback to legacy execCommand method. Returns true if successful, false if failed.
 
 ### CookieUtil
 

package/commonUtil/copyToClipboard/index.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test, vi, beforeEach } from "vitest";
+import copyToClipboard from ".";
+
+// * 브라우저 API를 모킹
+// * 실제로는 아무것도 하지 않지만, 호출 여부를 추적할 수 있는 가짜 함수
+const mockClipboard = {
+  writeText: vi.fn(),
+};
+
+vi.stubGlobal("navigator", {
+  clipboard: mockClipboard,
+});
+
+const mockElement = {
+  value: "",
+  style: {},
+  select: vi.fn(),
+  focus: vi.fn(),
+};
+
+vi.stubGlobal("document", {
+  execCommand: vi.fn(),
+  body: {
+    appendChild: vi.fn(),
+    removeChild: vi.fn(),
+  },
+  createElement: vi.fn(() => mockElement),
+});
+
+describe("copyToClipboard", () => {
+  // * 각 테스트 실행 전 모킹 함수 초기화
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("성공 케이스", () => {
+    test("최신 Clipboard API를 사용하여 성공적으로 복사한다", async () => {
+      // * Clipboard API 성공 시나리오
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyToClipboard("hello world");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledTimes(1);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("hello world");
+
+      // * 대체(레거시) 방식은 호출되지 않아야 함
+      expect(document.execCommand).not.toHaveBeenCalled();
+    });
+
+    test("Clipboard API 실패 시, 레거시 execCommand 방식으로 대체하여 성공적으로 복사한다", async () => {
+      // * Clipboard API 실패, execCommand 성공 시나리오
+      mockClipboard.writeText.mockRejectedValue(new Error("API not available"));
+      vi.mocked(document.execCommand).mockReturnValue(true);
+
+      const result = await copyToClipboard("fallback test");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledTimes(1);
+      expect(document.execCommand).toHaveBeenCalledWith("copy");
+    });
+  });
+
+  describe("실패 및 예외 케이스", () => {
+    test("두 가지 방식 모두 실패하면 false를 반환한다", async () => {
+      // * 두 방식 모두 실패 시나리오
+      mockClipboard.writeText.mockRejectedValue(new Error("API not available"));
+      vi.mocked(document.execCommand).mockReturnValue(false);
+
+      const result = await copyToClipboard("fail test");
+
+      expect(result).toBe(false);
+      expect(mockClipboard.writeText).toHaveBeenCalledTimes(1);
+      expect(document.execCommand).toHaveBeenCalledWith("copy");
+    });
+
+    test("빈 문자열도 성공적으로 복사한다", async () => {
+      mockClipboard.writeText.mockResolvedValue(undefined);
+
+      const result = await copyToClipboard("");
+
+      expect(result).toBe(true);
+      expect(mockClipboard.writeText).toHaveBeenCalledWith("");
+    });
+
+    test("매우 긴 텍스트가 주어지면 에러를 던지고 대체(fallback) 로직으로 복사를 시도한다", async () => {
+      const longText = "a".repeat(1000001);
+      vi.mocked(document.execCommand).mockReturnValue(true);
+
+      const result = await copyToClipboard(longText);
+
+      expect(result).toBe(true);
+      // * 크기 제한으로 Clipboard API는 호출되지 않음
+      expect(mockClipboard.writeText).not.toHaveBeenCalled();
+      // * execCommand로 대체 처리
+      expect(document.execCommand).toHaveBeenCalledWith("copy");
+    });
+  });
+});

package/commonUtil/copyToClipboard/index.ts

@@ -0,0 +1,42 @@
+/**
+ * 주어진 텍스트를 사용자의 클립보드에 비동기적으로 복사합니다.
+ *
+ * 최신 Clipboard API (`navigator.clipboard.writeText`)를 우선적으로 시도하며,
+ * 실패하거나 사용할 수 없는 경우 레거시 `document.execCommand('copy')` 방식으로 대체 수행합니다.
+ *
+ * @param {string} text - 클립보드에 복사할 문자열
+ * @returns {Promise<boolean>} 복사 성공 시 `true`, 실패 시 `false`를 반환
+ */
+export default async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    if (text.length > 1000000) {
+      throw new Error("Text too large to copy");
+    }
+
+    await navigator.clipboard.writeText(text);
+
+    return true;
+  } catch (error) {
+    const textArea = document.createElement("textarea");
+    textArea.value = text;
+
+    textArea.style.position = "fixed";
+    textArea.style.top = "-9999px";
+    textArea.style.left = "-9999px";
+
+    document.body.appendChild(textArea);
+    textArea.focus();
+    textArea.select();
+
+    try {
+      const successful = document.execCommand("copy");
+      document.body.removeChild(textArea);
+
+      return successful;
+    } catch (execError) {
+      document.body.removeChild(textArea);
+
+      return false;
+    }
+  }
+}

package/commonUtil/index.ts

@@ -1,2 +1,4 @@
 export { default as isEmpty } from "./isEmpty";
 export { default as isNull } from "./isNull";
+export { default as sleep } from "./sleep";
+export { default as copyToClipboard } from "./copyToClipboard";

package/commonUtil/sleep/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { sleep } from ".";
+import sleep from ".";
 
 describe("sleep", () => {
   // 각 'test'가 실행되기 전에 가짜 타이머를 활성화합니다.

package/commonUtil/sleep/index.ts

@@ -4,7 +4,7 @@
  * @param ms 지연시킬 시간 (밀리초 단위)
  * @returns {Promise<void>} 시간이 지나면 resolve되는 Promise
  */
-export function sleep(ms: number): Promise<void> {
+export default function sleep(ms: number): Promise<void> {
   const delay = Math.max(0, ms | 0);
   return new Promise((resolve) => setTimeout(resolve, delay));
 }